diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl
index 2726ae70a3..57193fabf3 100644
--- a/.beads/interactions.jsonl
+++ b/.beads/interactions.jsonl
@@ -13,3 +13,24 @@
 {"id":"int-a2361c4964a752d958cfc5fbb69bd077","kind":"field_change","created_at":"2026-07-29T21:16:21.533526502Z","actor":"jeremylongshore","issue_id":"buzz-ocv.5","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
 {"id":"int-4ee4835e436c4b7b6a00d0501b8b071c","kind":"field_change","created_at":"2026-07-30T04:47:01.972398591Z","actor":"jeremylongshore","issue_id":"buzz-ocv.6","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"DONE 2026-07-30. Mobile pairing sidecar deployed to prod + a REAL device paired (owner-confirmed handshake). Root cause: pinned relay-v0.2.0 image lacks buzz-pair-relay; fix pins the sidecar SEPARATELY via BUZZ_PAIR_RELAY_IMAGE (:main @9de8aff1) + absolute entrypoint, deployed sidecar-first (relay untouched), Caddy /pair route added. Verified wss://buzz-prod.intentsolutions.io/pair -> 101 Switching Protocols (Caddy->sidecar); sidecar logs show the live paired connection. intent-os PR #291 (overlay + test image-guard + runbook; 4/4 CI green). pairing-overlay-test now guards the image bug (5/5)."}}
 {"id":"int-ecdd102b39c09f97150839220f0b0d34","kind":"field_change","created_at":"2026-07-30T04:47:05.19034745Z","actor":"jeremylongshore","issue_id":"buzz-ocv.5","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"DONE 2026-07-30. Tauri desktop CORS origins (tauri://localhost + http://tauri.localhost) composed into version-controlled compose (intent-os PR #283), applied live to both hosts (PR #284), cors-config-test 2/2 in ci:drills. Final owner-gated gate met: Jeremy joined from the PACKAGED Linux desktop client to buzz-prod.intentsolutions.io (connected, admin, channels visible) — the packaged-client CORS verification the acceptance required."}}
+{"id":"int-9d63f6e48fc6157929c47a230eede39a","kind":"field_change","created_at":"2026-07-30T05:45:53.661302817Z","actor":"jeremylongshore","issue_id":"buzz-ocv.2","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"DONE 2026-07-30 (ultracode Track-A workflow). Compensating edge controls shipped + applied. CODE: ops/buzz/scripts/apply-edge-controls.sh (plan-only default, --apply to install) + hermetic test, merged intent-os PR #292 (4/4 estate-CI green, adversarially verified sound). APPLIED LIVE on the dedicated prod host intent-ops-buzz: fail2ban 'caddy-buzz' jail (bans public 4xx-flooders from /var/log/caddy/buzz-access.log) + nftables 'inet buzz_edge' connlimit (128 concurrent NEW/IP on tcp 80+443 only) + buzz-edge-nft.service enabled (reboot-safe). VERIFIED no self-lock: SSH intact, relay _readiness 200 off-box, tailnet/port-22 never touched (WS/established never dropped). SCOPING: applied to the Buzz-DEDICATED prod host only; deliberately NOT applied host-wide on the shared VPS staging (its connlimit would rate-limit co-tenant estate stacks Plane/ERP/CRM) — request_body caps + security headers already exist in Caddy on both. Closes the last non-owner-gated piece of go-live edge hardening."}}
+{"id":"int-d1b3bcb9725ff332970aacd020a3a368","kind":"field_change","created_at":"2026-07-30T05:54:52.463260258Z","actor":"jeremylongshore","issue_id":"buzz-bsy","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"DONE 2026-07-30 (ultracode Track-A workflow). Built ops/buzz/scripts/restore.sh — the real destructive three-store restore (Postgres pg_restore --clean --if-exists → media mc mirror --overwrite → git volume), gated behind --in-place with verify-before-destroy (sha256 every artifact + PGDMP header + manifest.env==--env cross-check; exit 2 writes nothing). Chose --in-place-required over auto-restore so decision-log/038's human-gate holds with ZERO updater.sh changes: the updater's flagless call exits 64 → rc5 page unchanged (updater-drill 6/6 still green). Hermetic restore-test.sh 6/6 with mutation-proven teeth; restore-drill-test 4/4 no regression; wired into ci:drills. Merged intent-os PR #293 (4/4 estate-CI green). Remaining real-tool proof = a host-side scratch-stack drill before first prod use (noted in runbook)."}}
+{"id":"int-be2173d658fc095081a9083e49d64528","kind":"field_change","created_at":"2026-07-30T07:17:44.135065314Z","actor":"jeremylongshore","issue_id":"buzz-nry.2","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"DONE 2026-07-30. Production deployed from proven staging artifacts with FRESH secrets on the dedicated host intent-ops-buzz, serving buzz-prod.intentsolutions.io (169.58.95.32). The 'cut DNS over' (apex → buzz.) requirement is DROPPED by owner decision 2026-07-30: buzz-prod.intentsolutions.io is the PERMANENT production URL (no apex cutover). Prod DNS is therefore already on its permanent, correct name — nothing further to cut over."}}
+{"id":"int-f42f74288896136765cfddee4c2de26e","kind":"field_change","created_at":"2026-07-30T07:17:46.752322494Z","actor":"jeremylongshore","issue_id":"buzz-nry.3","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"DONE 2026-07-30. Full go-live gate suite PASSED against prod (buzz-prod.intentsolutions.io): smoke 200/NIP-11/functional PASS; unauth-matrix 6/6 REJECT; functional-probe (member NIP-42 auth+publish+readback, un-invited refused) with cleanup CONFIRMED (baseline count 3). Was dependency-blocked by buzz-nry.2 (apex cutover) — that dependency is resolved by the owner decision to keep buzz-prod permanent, so this now closes with its already-captured green evidence."}}
+{"id":"int-67f8b7a8627b3a18e0b7b5d935a2d3c1","kind":"field_change","created_at":"2026-07-30T07:18:01.27822535Z","actor":"jeremylongshore","issue_id":"buzz-nry","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"EPIC DONE 2026-07-30. Dedicated Buzz production VPS (intent-ops-buzz, 169.58.95.32) stood up to estate conventions (.1), deployed with fresh secrets serving buzz-prod.intentsolutions.io (.2), and the full go-live gate suite passed against it (.3). Owner decision 2026-07-30: buzz-prod.intentsolutions.io is the PERMANENT production URL — the 'cut the prod domain over' (apex) part of this epic is intentionally NOT done and is retired, not deferred. All three children closed."}}
+{"id":"int-7879443495ecbf89b4dc0db155eeab9d","kind":"field_change","created_at":"2026-07-31T03:30:31.615907433Z","actor":"jeremylongshore","issue_id":"buzz-yfe.1","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"source-code reference written to ops/buzz/reference/BUZZ-SYSTEM-REFERENCE.md (45KB, file:line cited, from 8-agent sourcing workflow)"}}
+{"id":"int-5068eed2df8e022fc89b5a792782fd39","kind":"field_change","created_at":"2026-07-31T03:30:33.412199224Z","actor":"jeremylongshore","issue_id":"buzz-yfe.2","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"estate-deployment reference written to ops/buzz/reference/BUZZ-ESTATE-DEPLOYMENT-REFERENCE.md (source-cited)"}}
+{"id":"int-a7c6e307556516f672455c69f544d886","kind":"field_change","created_at":"2026-07-31T03:30:34.984414889Z","actor":"jeremylongshore","issue_id":"buzz-w92.1","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"AI Wire feed bot minted (8189ba10), relay member, joined ai-wire+0-general, first cards posted accepted:true 2026-07-31"}}
+{"id":"int-ddb9fd8ab1b2e550f95a215b3bfc16e0","kind":"field_change","created_at":"2026-07-31T03:36:16.562161598Z","actor":"jeremylongshore","issue_id":"buzz-yfe.3","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"buzz-ops skill built (.claude/skills/buzz-ops/ with 3 bundled references); PASS /validate-skillmd standard tier"}}
+{"id":"int-f5404dea1362f4e691fb6edda3e17b7d","kind":"field_change","created_at":"2026-07-31T03:36:18.134646786Z","actor":"jeremylongshore","issue_id":"buzz-yfe.4","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"buzz-ops agent built + PASS /validate-agent (14-field standalone spec)"}}
+{"id":"int-85fdaa9e88769d07584be2fb1e04cf42","kind":"field_change","created_at":"2026-07-31T03:36:19.601340573Z","actor":"jeremylongshore","issue_id":"buzz-yfe.5","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"buzz-feed-curator agent built + PASS /validate-agent"}}
+{"id":"int-8850efaef9cdedb9badb537fc62935ba","kind":"field_change","created_at":"2026-07-31T03:36:21.08100149Z","actor":"jeremylongshore","issue_id":"buzz-yfe.6","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"buzz-relay-admin agent built + PASS /validate-agent"}}
+{"id":"int-4260303d729ddb42abd839cb31f38f27","kind":"field_change","created_at":"2026-07-31T03:36:22.349391594Z","actor":"jeremylongshore","issue_id":"buzz-yfe.7","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"all 3 agents PASS /validate-agent; skill PASS /validate-skillmd; reference-vs-code consistency 106 citations 100% resolve to real fork source (no fabrications)"}}
+{"id":"int-f0b734dccd26f403f2e9576181b68a3f","kind":"field_change","created_at":"2026-07-31T03:37:20.957039522Z","actor":"jeremylongshore","issue_id":"buzz-yfe","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"All 7 children closed: 2 references + skill + 3 agents + validation; all PASS the IS validators"}}
+{"id":"int-630ab91f0cf7e0e25edae67f26073244","kind":"field_change","created_at":"2026-07-31T04:06:15.368820216Z","actor":"jeremylongshore","issue_id":"buzz-w92.2","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-cca6517e1c6ee0187914938b7edd0144","kind":"field_change","created_at":"2026-07-31T04:18:38.265063552Z","actor":"jeremylongshore","issue_id":"buzz-w92.2","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"pipeline built + hardened (fetch→dedupe(newest-25)→Groq/NVIDIA summary→card), rate-limit fallback chain, ops/buzz/wire/buzz-wire.py"}}
+{"id":"int-78e02ffa7530bcd16898d0cbbffeec34","kind":"field_change","created_at":"2026-07-31T04:18:40.136787487Z","actor":"jeremylongshore","issue_id":"buzz-w92.3","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"easy-tier feeds live — OpenAI, HuggingFace, arXiv cs.AI, Google DeepMind; 4 seed cards posted with summaries"}}
+{"id":"int-ca89c97ced65361b3070b31df6bec542","kind":"field_change","created_at":"2026-07-31T04:18:41.731887559Z","actor":"jeremylongshore","issue_id":"buzz-w92.8","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"3h cron deployed (~/bin/buzz-wire-cron.sh) + notify-lib liveness + registered in automations.md"}}
+{"id":"int-e4c1bfdb34ec5b768b2fe150c50071fc","kind":"field_change","created_at":"2026-07-31T04:30:55.252637052Z","actor":"jeremylongshore","issue_id":"buzz-w92.7","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Daily ai-wire digest live — --digest composes cross-lab roundup (70b→8b→NVIDIA), posts to 1-ai-wire, cron 06:30 CT"}}
+{"id":"int-873d15b79debfd144c2a44cbd6113969","kind":"field_change","created_at":"2026-07-31T14:04:52.409666792Z","actor":"jeremylongshore","issue_id":"buzz-w92.4","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Anthropic bridged via HTML-scrape source type (news/research/engineering -> anthropic-blogs/research), mirroring the estate monitors; Mistral added. buzz-w92.6 partially done (tooling/mcp/newsletters/ships/status live)."}}
+{"id":"int-b6dc6f4abc00f98eb2fa156977ef6406","kind":"field_change","created_at":"2026-07-31T15:35:29.315597343Z","actor":"jeremylongshore","issue_id":"buzz-w92.5","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Filled groq/meta/mistral/cohere/perplexity/xai + cleaner anthropic via Olshansk RSS mirrors (from perception repo) — no RSSHub needed. Remaining empty (deepseek/qwen/moonshot/minimax/benchmarks/funding/openrouter) have no mirror."}}
diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl
index b786ef1a58..bc5ccd5f3c 100644
--- a/.beads/issues.jsonl
+++ b/.beads/issues.jsonl
@@ -1,20 +1,67 @@
-{"_type":"issue","id":"buzz-2i6","title":"Install nak on the Buzz hosts and run the real functional-probe rehearsal, then enable the prod updater timer","description":"The updater lane is deployed to staging (dormant) but the real functional-probe rehearsal is blocked: nak (the NIP-42 auth+publish+readback CLI the probe uses) is absent on the Buzz hosts. buzz-admin IS in the relay image. Steps: install nak on staging (+ prod), run functional-probe.sh against the live staging relay (throwaway member auth+publish+readback, un-invited refused, cleans up), then a controlled no-op-digest updater rehearsal on staging, THEN install-updater-lane.sh intent-ops-buzz --enable-timer for prod. Parent: buzz-ocv.4.","notes":"REHEARSAL PARTIAL on live staging 2026-07-29 (nak copied to /usr/local/bin/nak on the staging host; jq present). VERIFIED LIVE: closed relay up+healthy+CORS-applied; buzz-admin add-member/remove-member/list-members work — EXACT syntax is 'buzz-admin add-member --pubkey \u003chex-or-npub\u003e' (NOT positional; positional errors with usage). nak emits 64-char hex from 'nak key public'; relay accepts hex. add+remove round-trip proven; test member cleaned up (relay left clean: owner + 1 pre-existing member). REMAINING: the nak publish/readback NIP-42 flow hung with reactive '--auth' — the closed relay likely needs '--force-pre-auth' (authenticate BEFORE the EVENT/REQ), and readback (nak req -i \u003cid\u003e) on a closed relay also needs auth so the member NSEC must be threaded into functional-probe.sh's readback() (currently it only gets the event id). NEXT: (1) prove 'NOSTR_SECRET_KEY=\u003cnsec\u003e nak event -k1 -c X --auth --force-pre-auth \u003cws\u003e' returns an id against staging; (2) prove readback with the member key; (3) bake the verified commands + --pubkey into functional-probe.sh add_member/del_member/publish/readback; (4) then no-op-digest updater rehearsal on staging; (5) install-updater-lane.sh intent-ops-buzz --enable-timer.\nREHEARSAL DONE on staging (intent-os PR #288): nak installed on the staging host; functional-probe.sh fixed to the real NIP-42 flow (--sec, public wss through Caddy, --force-pre-auth readback, --pubkey, keygen newline, global cleanup trap) and PROVEN GREEN E2E against the live staging relay — member publish+readback, un-invited refused; smoke-suite PASS; unauth-matrix 6/6. Self-cleaning; staging membership left clean. REMAINING: install nak on the PROD host + run the same 3 gates against buzz-prod off-network; then enable the prod updater timer.","status":"open","priority":1,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T21:47:43Z","created_by":"jeremylongshore","updated_at":"2026-07-30T00:37:47Z","labels":["go-live","probe","updater"],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-20l.6","title":"Add the Claude impl-agent identity as a second buzz-acp process that authors PRs from goose-filed issues only","description":"Second buzz-acp process: Claude (claude-agent-acp), PermissionMode acceptEdits, PR-scoped PAT, a /work cwd that clones REPOS/\u003crepo\u003e on demand; reads ONLY goose-authored issues (never the raw channel firehose — invariant 2). Handoff is a human @mention of the impl agent on goose's issue (invariant 1). Acceptance: human @mention on issue #N =\u003e impl agent opens a PR against that repo; CI gates the merge; the agent cannot merge. DEPENDS on the ACP-headless spike.","status":"open","priority":1,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T19:58:11Z","created_by":"jeremylongshore","updated_at":"2026-07-31T19:58:11Z","labels":["agentic-ops","estate","github-bridge","impl-agent"],"dependencies":[{"issue_id":"buzz-20l.6","depends_on_id":"buzz-20l","type":"parent-child","created_at":"2026-07-31T13:58:10Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-20l.6","depends_on_id":"buzz-20l.1","type":"blocks","created_at":"2026-07-31T13:58:36Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-20l.6","depends_on_id":"buzz-20l.5","type":"blocks","created_at":"2026-07-31T13:58:37Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":2,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-20l.5","title":"Configure the goose-triage profile — owner-gated, issue-filing only, reading the repo-channel firehose","description":"goose (MiniMax) runs owner-only, PermissionMode plan/dontAsk, no-merge PAT, subscribed to the repo-home channels; reads the raw bridge feed and files ONE GitHub issue per finding via the finding-id upsert. It NEVER authors code and NEVER hands off via chat @mention. Acceptance: a posted CI-failure card results in exactly one filed issue; goose has no write path to code.","status":"open","priority":1,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T19:58:09Z","created_by":"jeremylongshore","updated_at":"2026-07-31T19:58:09Z","labels":["agentic-ops","estate","github-bridge","triage-agent"],"dependencies":[{"issue_id":"buzz-20l.5","depends_on_id":"buzz-20l.3","type":"blocks","created_at":"2026-07-31T13:58:34Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-20l.5","depends_on_id":"buzz-20l.4","type":"blocks","created_at":"2026-07-31T13:58:34Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-20l.5","depends_on_id":"buzz-20l","type":"parent-child","created_at":"2026-07-31T13:58:09Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":2,"dependent_count":3,"comment_count":0}
+{"_type":"issue","id":"buzz-20l.4","title":"Build the finding-id and level-triggered reconciler so every failure maps to exactly one auto-closing issue","description":"finding-id = hash(repo, workflow, normalized-failure) for idempotent issue upsert (create-only-if-absent); a periodic level-triggered reconciler computes currently-failing finding-ids and closes every finding-issue no longer in that set (do NOT rely on edge-triggered 'green run-\u003eclose' — Buzz drops replies #2459/#3587, agents go deaf in threads #2270). BUILD BEFORE the first repo channel goes live. Acceptance: three retries of one flaky failure =\u003e one issue; recovery =\u003e the issue auto-closes within one reconcile cycle.","status":"open","priority":1,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T19:58:08Z","created_by":"jeremylongshore","updated_at":"2026-07-31T19:58:08Z","labels":["agentic-ops","estate","github-bridge","reliability"],"dependencies":[{"issue_id":"buzz-20l.4","depends_on_id":"buzz-20l.3","type":"blocks","created_at":"2026-07-31T13:58:33Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-20l.4","depends_on_id":"buzz-20l","type":"parent-child","created_at":"2026-07-31T13:58:08Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":2,"comment_count":0}
+{"_type":"issue","id":"buzz-20l.3","title":"Build buzz-gh-bridge: a webhook receiver plus a GitHub App on both orgs that posts repo events as cards into repo-home channels","description":"FastAPI receiver on intent-ops-buzz (~100 lines): verify X-Hub-Signature-256 HMAC, dedup on X-GitHub-Delivery, map owner/repo-\u003echannel_id, render event-\u003ecard, post via the EXISTING local docker-exec path in ops/buzz/wire/buzz-wire.py (no ssh hop). One GitHub App installed on jeremylongshore + intent-solutions-io subscribed to pull_request, pull_request_review, pull_request_review_comment, issues, issue_comment, workflow_run, push, release, deployment_status. Webhooks (real-time), not polling; CI status via the workflow_run event. Caddy route -\u003eloopback. Acceptance: a real PR/CI event posts a card into its repo channel; HMAC-invalid and duplicate deliveries are rejected.","status":"open","priority":1,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T19:58:07Z","created_by":"jeremylongshore","updated_at":"2026-07-31T19:58:07Z","labels":["agentic-ops","estate","github-bridge"],"dependencies":[{"issue_id":"buzz-20l.3","depends_on_id":"buzz-20l","type":"parent-child","created_at":"2026-07-31T13:58:06Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":3,"comment_count":0}
+{"_type":"issue","id":"buzz-20l.2","title":"Record the agentic-Buzz architecture decisions in decision-log (division of labor, source-of-truth, the two invariants)","description":"Append a decision-log/040 (or new) entry: goose=issues / Claude|Codex=PRs; GitHub is source of truth and Buzz is a projection (NO NIP-34 issue/PR mirror); invariant 1 = the GitHub issue IS the handoff (no agent-to-agent chat @mention); invariant 2 = untrusted channel/webhook text never reaches the shell+creds process; 3-process topology (not per-repo). Acceptance: entry merged, cited by the build beads.","status":"open","priority":1,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T19:58:05Z","created_by":"jeremylongshore","updated_at":"2026-07-31T19:58:05Z","labels":["agentic-ops","decision","estate","github-bridge"],"dependencies":[{"issue_id":"buzz-20l.2","depends_on_id":"buzz-20l","type":"parent-child","created_at":"2026-07-31T13:58:05Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-20l.1","title":"Confirm Claude Code and Codex ACP harnesses run headless with API keys on the Buzz VPS (the build gate for the impl lane)","description":"Report source-4 flags upstream leans toward subscription/ChatGPT-login auth; we need headless API-key auth. Verify claude-agent-acp and codex-acp start, authenticate via API key, and complete a trivial task headless in an isolated container on intent-ops-buzz. BLOCKS the impl-agent bead. Acceptance: a headless ACP session with each harness completes a no-op task using an API key only, evidenced.","status":"open","priority":1,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T19:58:04Z","created_by":"jeremylongshore","updated_at":"2026-07-31T19:58:04Z","labels":["agentic-ops","estate","github-bridge","spike"],"dependencies":[{"issue_id":"buzz-20l.1","depends_on_id":"buzz-20l","type":"parent-child","created_at":"2026-07-31T13:58:03Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":2,"comment_count":0}
+{"_type":"issue","id":"buzz-20l","title":"Build the agentic Buzz estate-ops surface — repo-home channels, a GitHub event bridge, and a goose-triage + Claude-impl division of labor","description":"Evolve Buzz from a chat+feed surface into the estate's agentic operations surface, replacing the dead Greptile/Gemini/CodeRabbit 'what was found' review stream on our own stack. Research: ops/buzz/RESEARCH-agentic-buzz-utilization-2026-07-31.md (14-agent ultracode workflow, 2026-07-31).\n\nOwner decisions locked: goose files ISSUES only (owner-gated, plan/dontAsk, no-merge PAT); Claude/Codex authors PRs (native buzz-acp harnesses, config.rs:696 — nothing to build at harness level); every ACTIVE repo (both orgs, minus archived/dead) gets a repo-home channel + lazy-create on next push; GitHub is the source of truth, Buzz is a projection (NO NIP-34 mirror). Two load-bearing invariants: (1) the GitHub issue IS the triage-\u003eimpl handoff, never an agent-to-agent chat @mention; (2) untrusted channel/webhook text never reaches the process holding a shell + git creds.\n\nDependency-ordered children below. Build gate: confirm Claude/Codex ACP run headless with API keys on our VPS before the impl lane.","status":"open","priority":1,"issue_type":"epic","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T19:57:05Z","created_by":"jeremylongshore","updated_at":"2026-07-31T19:57:05Z","labels":["agentic-ops","estate","github-bridge"],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-1zr.1","title":"Stand up the staging drill harness for channel/identity/feed/notify actions","description":"A script suite that exercises the real actions against buzz-testing.intentsolutions.io with throwaway keys/channels, asserting the load-bearing rules: only-owner-can-delete returns the right error; a non-member post gets 403 relay_membership_required; add-member --role owner is rejected; provider-first naming; verify via channels list. Torn down after each run. AC: harness runs green on staging, prod untouched.","status":"open","priority":1,"issue_type":"feature","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:39:32Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:39:32Z","dependencies":[{"issue_id":"buzz-1zr.1","depends_on_id":"buzz-1zr","type":"parent-child","created_at":"2026-07-30T21:39:32Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-1zr","title":"Establish and run the Buzz testing procedure — staging drills, hermetic tests, agent evals","description":"A repeatable way to test the actions we build against Buzz, following the estate pattern (hermetic test in ci:drills + live drill) + the IS testing SOP (/audit-tests, /implement-tests, audit-harness). HARD SAFETY RULE: every destructive/live drill runs on the STAGING relay buzz-testing.intentsolutions.io (drills-only, never real members/channels) — NEVER prod (per ops/buzz/README.md). Covers the new surfaces: channel/identity ops, feed posting, sys-notification routing, and operator-agent behavior.","status":"open","priority":1,"issue_type":"epic","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:39:31Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:39:31Z","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-w92.2","title":"Build the feed ingestion pipeline (fetch -\u003e dedupe -\u003e LLM -\u003e card)","description":"The core pipeline: RSS/RSSHub fetch, dedupe against seen-state, LLM summarize+score (MiniMax/Groq keys from SOPS), format a mobile-first card (imeta hero + markdown + source badge + link), post to ai-wire + the matching *-wire. Reuse perception's ingestion shape (GCP service dead; code is the reference). AC: one real lab item -\u003e a rich card in ai-wire + the lab channel.","status":"closed","priority":1,"issue_type":"feature","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:29:08Z","created_by":"jeremylongshore","updated_at":"2026-07-31T04:18:38Z","started_at":"2026-07-31T04:06:15Z","closed_at":"2026-07-31T04:18:38Z","close_reason":"pipeline built + hardened (fetch→dedupe(newest-25)→Groq/NVIDIA summary→card), rate-limit fallback chain, ops/buzz/wire/buzz-wire.py","dependencies":[{"issue_id":"buzz-w92.2","depends_on_id":"buzz-w92","type":"parent-child","created_at":"2026-07-30T21:29:07Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-w92.2","depends_on_id":"buzz-yfe.5","type":"blocks","created_at":"2026-07-30T21:29:13Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0}
+{"_type":"issue","id":"buzz-w92.1","title":"Posting primitive — feed bot key + buzz messages send","description":"DONE 2026-07-31: minted the AI Wire bot npub (8189ba10, /srv/buzz-agent/wire-bot.env), added to relay membership, set profile, joined ai-wire + 0-general, posted the first cards (accepted:true). This is the shared post path for wire + sys notifications.","status":"closed","priority":1,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:29:07Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:30:35Z","closed_at":"2026-07-31T03:30:35Z","close_reason":"AI Wire feed bot minted (8189ba10), relay member, joined ai-wire+0-general, first cards posted accepted:true 2026-07-31","dependencies":[{"issue_id":"buzz-w92.1","depends_on_id":"buzz-w92","type":"parent-child","created_at":"2026-07-30T21:29:06Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":2,"comment_count":0}
+{"_type":"issue","id":"buzz-w92","title":"AI-Wire feed engine — fetch, summarize, post curated cards","description":"The engine that fills ai-wire + the *-wire channels: per source, poll the feed (or RSSHub for scrape-only labs) -\u003e dedupe -\u003e LLM summarize/score -\u003e post a rich mobile card via the AI Wire bot. Anti-firehose: ai-wire is one curated digest; packs are opt-in. decision-log/040 D140 (fork-and-wire). Reuse the perception repo ingestion pattern + the estate ~/bin Anthropic monitor fleet. Posting primitive already proven (AI Wire bot live).","status":"open","priority":1,"issue_type":"epic","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:29:06Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:29:06Z","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-yfe.3","title":"Build the buzz-ops skill bundling the reference files","description":"A /skill-creator skill that bundles both reference docs so any session/agent that invokes it knows Buzz's source + estate layout. AC: SKILL.md passes /validate-skillmd; references bundled; encodes the load-bearing rules (only-owner-deletes, membership-required-to-post, provider-first naming, secret handling).","status":"closed","priority":1,"issue_type":"feature","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:27:14Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:36:16Z","closed_at":"2026-07-31T03:36:16Z","close_reason":"buzz-ops skill built (.claude/skills/buzz-ops/ with 3 bundled references); PASS /validate-skillmd standard tier","dependencies":[{"issue_id":"buzz-yfe.3","depends_on_id":"buzz-yfe.1","type":"blocks","created_at":"2026-07-30T21:28:59Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-yfe.3","depends_on_id":"buzz-yfe","type":"parent-child","created_at":"2026-07-30T21:27:13Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-yfe.3","depends_on_id":"buzz-yfe.2","type":"blocks","created_at":"2026-07-30T21:28:59Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":2,"dependent_count":3,"comment_count":0}
+{"_type":"issue","id":"buzz-yfe.2","title":"Produce the Buzz estate-deployment reference","description":"How Buzz is wired in the estate: two VPSs, containers, secrets/keys, ops/buzz lane, deploy/backup/monitoring, sys-* notification path. AC: ops/buzz/reference/BUZZ-ESTATE-DEPLOYMENT-REFERENCE.md written, source-cited.","status":"closed","priority":1,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:27:13Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:30:33Z","closed_at":"2026-07-31T03:30:33Z","close_reason":"estate-deployment reference written to ops/buzz/reference/BUZZ-ESTATE-DEPLOYMENT-REFERENCE.md (source-cited)","dependencies":[{"issue_id":"buzz-yfe.2","depends_on_id":"buzz-yfe","type":"parent-child","created_at":"2026-07-30T21:27:12Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":1,"comment_count":0}
+{"_type":"issue","id":"buzz-yfe.1","title":"Produce the Buzz source-code reference (file:line)","description":"Map the block/buzz source: relay, CLI, admin, event kinds, auth/NIP-OA, ACP agent, personas/templates, media. IN FLIGHT via an 8-agent ultracode workflow -\u003e BUZZ-SYSTEM-REFERENCE.md. AC: ops/buzz/reference/BUZZ-SYSTEM-REFERENCE.md written, file:line cited.","status":"closed","priority":1,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:27:12Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:30:31Z","closed_at":"2026-07-31T03:30:31Z","close_reason":"source-code reference written to ops/buzz/reference/BUZZ-SYSTEM-REFERENCE.md (45KB, file:line cited, from 8-agent sourcing workflow)","dependencies":[{"issue_id":"buzz-yfe.1","depends_on_id":"buzz-yfe","type":"parent-child","created_at":"2026-07-30T21:27:12Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":2,"comment_count":0}
+{"_type":"issue","id":"buzz-yfe","title":"Encode durable Buzz operational expertise — reference, skill, operator agents","description":"Stop operating Buzz by trial-and-error. Produce source-grounded reference docs, a buzz-ops skill that bundles them, and validated operator agents that actually know how Buzz is wired. Built via /skill-creator and /agent-creator (IS 8-field spec), grounded in the references. Home: ops/buzz/reference/ (docs), intent-os .claude/ (skill+agents).","status":"closed","priority":1,"issue_type":"epic","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:27:11Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:37:21Z","closed_at":"2026-07-31T03:37:21Z","close_reason":"All 7 children closed: 2 references + skill + 3 agents + validation; all PASS the IS validators","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-ehv","title":"Community channel layout and identity roster — build clean, keep clean","description":"The buzz-prod community's channel architecture and member/agent identity hygiene. Ground truth + procedures: ops/buzz/RUNBOOK-channels.md (source-cited). SHIPPED this session (2026-07-31): the clean provider-first open layout (0-general pinned, ask, ai-wire, anthropic-* group, \u003cprovider\u003e-wire firehoses, topic *-wire, private sys-*); persona agents (Bumble/Fizz/Honey/CCA-F) purged; canonical names set (Buzz Admin, goose minimax3, AI Wire, humans); RUNBOOK-channels.md written. Open children below.","status":"open","priority":1,"issue_type":"epic","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:27:09Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:27:09Z","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-2i6","title":"Install nak on the Buzz hosts and run the real functional-probe rehearsal, then enable the prod updater timer","description":"The updater lane is deployed to staging (dormant) but the real functional-probe rehearsal is blocked: nak (the NIP-42 auth+publish+readback CLI the probe uses) is absent on the Buzz hosts. buzz-admin IS in the relay image. Steps: install nak on staging (+ prod), run functional-probe.sh against the live staging relay (throwaway member auth+publish+readback, un-invited refused, cleans up), then a controlled no-op-digest updater rehearsal on staging, THEN install-updater-lane.sh intent-ops-buzz --enable-timer for prod. Parent: buzz-ocv.4.","notes":"REHEARSAL PARTIAL on live staging 2026-07-29 (nak copied to /usr/local/bin/nak on the staging host; jq present). VERIFIED LIVE: closed relay up+healthy+CORS-applied; buzz-admin add-member/remove-member/list-members work — EXACT syntax is 'buzz-admin add-member --pubkey \u003chex-or-npub\u003e' (NOT positional; positional errors with usage). nak emits 64-char hex from 'nak key public'; relay accepts hex. add+remove round-trip proven; test member cleaned up (relay left clean: owner + 1 pre-existing member). REMAINING: the nak publish/readback NIP-42 flow hung with reactive '--auth' — the closed relay likely needs '--force-pre-auth' (authenticate BEFORE the EVENT/REQ), and readback (nak req -i \u003cid\u003e) on a closed relay also needs auth so the member NSEC must be threaded into functional-probe.sh's readback() (currently it only gets the event id). NEXT: (1) prove 'NOSTR_SECRET_KEY=\u003cnsec\u003e nak event -k1 -c X --auth --force-pre-auth \u003cws\u003e' returns an id against staging; (2) prove readback with the member key; (3) bake the verified commands + --pubkey into functional-probe.sh add_member/del_member/publish/readback; (4) then no-op-digest updater rehearsal on staging; (5) install-updater-lane.sh intent-ops-buzz --enable-timer.\nREHEARSAL DONE on staging (intent-os PR #288): nak installed on the staging host; functional-probe.sh fixed to the real NIP-42 flow (--sec, public wss through Caddy, --force-pre-auth readback, --pubkey, keygen newline, global cleanup trap) and PROVEN GREEN E2E against the live staging relay — member publish+readback, un-invited refused; smoke-suite PASS; unauth-matrix 6/6. Self-cleaning; staging membership left clean. REMAINING: install nak on the PROD host + run the same 3 gates against buzz-prod off-network; then enable the prod updater timer.\nAdvanced 2026-07-30 (ultracode Track-A workflow), timer NOT armed by design: (1) nak installed on prod host intent-ops-buzz (/usr/local/bin/nak, keygen verified); (2) wrapped-updater lane installed DORMANT via install-updater-lane.sh (no --enable-timer) — 6/6 lane scripts + both systemd units present, daemon-reload+syntax OK; (3) smoke-suite.sh + unauth-matrix.sh pushed (the installer omits them); (4) functional-probe rehearsal PASSED green against live prod (see buzz-nry.3 gate-suite run — member auth/publish/readback, un-invited refused, self-cleaned). VERIFIED dormant: timer disabled+inactive, updater.service never ran, serving digest unchanged (a0f672). REMAINING = arm the timer (systemctl enable --now) — HELD pending owner call: arming = unattended weekly pre-1.0 prod deploys with advisory-only scan, before apex cutover. Recommend arming AFTER apex cutover; lane is one command from armed.","status":"open","priority":1,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T21:47:43Z","created_by":"jeremylongshore","updated_at":"2026-07-30T05:40:19Z","labels":["go-live","probe","updater"],"dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"buzz-aet","title":"Author the authoritative Buzz naming and boundaries record and reconcile the blueprint ledger to prod-up","description":"Track B of the Buzz adoption plan (owner amendment 2026-07-29, do FIRST). Author the canonical naming+boundaries record in the fork 000-docs from the AUTHORITATIVE NAMING \u0026 REPOSITORY MODEL table: 6 assets (upstream block/buzz, code fork intent-solutions-io/buzz, contributor lab intent-solutions-io/intent-ops-buzz repo, production host intent-ops-buzz VPS, live ops lane intent-os ops/buzz, deferred plugin intent-solutions-io/intent-ops-buzz-plugin), the disambiguation rule (never bare 'intent-ops-buzz'), and the four-plane flow with two separate gates (contribution vs deployment). Reconcile the blueprint 001 completion ledger to reality (prod host built/deployed/verified pre-cutover, backups+restore proven), name the plugin repo deferred, and add the contributor-lab plane. Unblocks the parked contributor-lab architecture DRAFT (Track C). The amendment forbids durable architecture docs until this lands. Done-means: naming doc exists + internally consistent; ledger prod-up; no bare-intent-ops-buzz ambiguity; pnpm check green on the intent-os reconcile edit.","status":"closed","priority":1,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T19:19:37Z","created_by":"jeremylongshore","updated_at":"2026-07-29T19:36:54Z","started_at":"2026-07-29T19:19:43Z","closed_at":"2026-07-29T19:36:54Z","close_reason":"Track B shipped: authored fork 000-docs/006-DR-STND-authoritative-naming-and-boundaries.md (canonical six-asset table + host-vs-repo disambiguation rule + four-plane flow + two-gate model); reconciled the 001 blueprint ledger to prod-up (E2/E2d/E3 states, ELab row, E9 plugin named intent-ops-buzz-plugin + DEFERRED, new Phase 6 pointer); added the intent-os ops/buzz/README 'Naming \u0026 planes' section. Merged: fork PR #11 + intent-os PR #281 (estate-CI 3 green contexts: gates 128s, drills 212s, gitleaks). pnpm check EXIT=0; no bare-intent-ops-buzz ambiguity remains.","labels":["architecture","ledger","naming"],"dependency_count":0,"dependent_count":0,"comment_count":0}
-{"_type":"issue","id":"buzz-nry.3","title":"Run the full go-live gate suite against production on the dedicated box","description":"The full E3 go-live gate suite to RUN against PROD before any invite (all BLOCKING, none assumed passed): unauth probe matrix off-network; functional membership probe (NIP-42 publish+readback, un-invited refused); backup restore drill (restore staging from prod's artifacts); updater planted-fault drill on staging; key runbooks rehearsed; resource caps verified. Status is tracked per-gate in the notes and in intent-os ops/buzz — the off-site backup leg and several gates remain OPEN; this description is scope, not a completion claim.","notes":"Go-live gates PARTIAL against prod: (1) functional membership probe GREEN — owner NIP-42 auth -\u003e publish -\u003e readback OK; un-invited key REFUSED (closed relay enforcing, member_count:1 on boot). (2) unauth HTTP probe matrix PASS — media PUT 405, git 404/405, hooks 400, admin 404; public readiness/NIP-11/web-client 200. (3) resource caps + loopback-only publish + isolated bridge net verified. REMAINING/BLOCKING before any invite: backup-restore drill, updater planted-fault drill, key runbooks — all depend on backup+updater wiring (buzz-ocv.4, not built).\nRESTORE DRILL PROVEN (buzz-nry.3 gate item): restored the first prod archive into an ISOLATED dev-box scratch project (prod/staging untouched, prod 4/4 healthy throughout). 40 tables restored; the exact prod-published event 9717ccaa physically present; relay_members=1 + member_count:1 on boot; media restored; relay identity stable (same key-\u003e35cd57ab); relay boots healthy; un-invited refused; restart persistence holds. RTO ~3min, RPO = backup point (18:36:41Z). Caveat: headless nak auth-on-REQ readback didn't complete in-harness (passed on prod). Evidence: ops/buzz/RUNBOOK-backup-restore.md. STILL BLOCKING before invite: updater planted-fault drill, key runbooks, off-site copy.","status":"open","priority":1,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T16:31:30Z","created_by":"jeremylongshore","updated_at":"2026-07-29T18:45:39Z","labels":["hosting"],"dependencies":[{"issue_id":"buzz-nry.3","depends_on_id":"buzz-nry.2","type":"blocks","created_at":"2026-07-29T10:31:31Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-nry.3","depends_on_id":"buzz-nry","type":"parent-child","created_at":"2026-07-29T10:31:29Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
-{"_type":"issue","id":"buzz-nry.2","title":"Deploy production from the proven staging artifacts with fresh secrets and cut DNS over","description":"Deploy prod from the proven staging artifacts (same digest-pinned compose) with FRESH secrets minted on the new box (new relay identity, new bootstrap owner key until the owner's desktop key swaps in, new db/redis/minio; staging keys never promote). DNS cuts over to the prod host at go-live; the shared stack renames to the staging domain. Deploy specifics + addressing in intent-os ops/buzz. Depends on the bootstrap child.","notes":"Prod deploy DONE (apex cutover pending): staging-proven digest-pinned compose deployed with FRESH prod secrets; 4 containers healthy; own Caddy ingress TLS + security headers. REMAINING (gated on the owner's client-generated desktop key): DNS cutover to the prod host, rename staging to the staging domain, swap BUZZ_DOMAIN/RELAY_URL/CORS to the apex, swap RELAY_OWNER_PUBKEY to the owner's desktop pubkey. Addressing + specifics in intent-os ops/buzz.","status":"open","priority":1,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T16:31:22Z","created_by":"jeremylongshore","updated_at":"2026-07-29T18:17:43Z","labels":["hosting"],"dependencies":[{"issue_id":"buzz-nry.2","depends_on_id":"buzz-nry","type":"parent-child","created_at":"2026-07-29T10:31:22Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-nry.2","depends_on_id":"buzz-nry.1","type":"blocks","created_at":"2026-07-29T10:31:31Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0}
+{"_type":"issue","id":"buzz-nry.3","title":"Run the full go-live gate suite against production on the dedicated box","description":"The full E3 go-live gate suite to RUN against PROD before any invite (all BLOCKING, none assumed passed): unauth probe matrix off-network; functional membership probe (NIP-42 publish+readback, un-invited refused); backup restore drill (restore staging from prod's artifacts); updater planted-fault drill on staging; key runbooks rehearsed; resource caps verified. Status is tracked per-gate in the notes and in intent-os ops/buzz — the off-site backup leg and several gates remain OPEN; this description is scope, not a completion claim.","notes":"Go-live gates PARTIAL against prod: (1) functional membership probe GREEN — owner NIP-42 auth -\u003e publish -\u003e readback OK; un-invited key REFUSED (closed relay enforcing, member_count:1 on boot). (2) unauth HTTP probe matrix PASS — media PUT 405, git 404/405, hooks 400, admin 404; public readiness/NIP-11/web-client 200. (3) resource caps + loopback-only publish + isolated bridge net verified. REMAINING/BLOCKING before any invite: backup-restore drill, updater planted-fault drill, key runbooks — all depend on backup+updater wiring (buzz-ocv.4, not built).\nRESTORE DRILL PROVEN (buzz-nry.3 gate item): restored the first prod archive into an ISOLATED dev-box scratch project (prod/staging untouched, prod 4/4 healthy throughout). 40 tables restored; the exact prod-published event 9717ccaa physically present; relay_members=1 + member_count:1 on boot; media restored; relay identity stable (same key-\u003e35cd57ab); relay boots healthy; un-invited refused; restart persistence holds. RTO ~3min, RPO = backup point (18:36:41Z). Caveat: headless nak auth-on-REQ readback didn't complete in-harness (passed on prod). Evidence: ops/buzz/RUNBOOK-backup-restore.md. STILL BLOCKING before invite: updater planted-fault drill, key runbooks, off-site copy.\nGATE SUITE PASSED against prod 2026-07-30 (ultracode Track-A workflow, non-destructive): smoke 200/NIP-11/functional PASS; unauth-matrix 6/6 REJECT; functional-probe (member NIP-42 auth+publish+readback, un-invited refused) with cleanup CONFIRMED (back to baseline count 3). The suite deliverable is DONE; this bead stays OPEN only because its dependency buzz-nry.2 (apex DNS cutover) is owner-gated and not yet done — close together when apex cuts over.","status":"closed","priority":1,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T16:31:30Z","created_by":"jeremylongshore","updated_at":"2026-07-30T07:17:47Z","closed_at":"2026-07-30T07:17:47Z","close_reason":"DONE 2026-07-30. Full go-live gate suite PASSED against prod (buzz-prod.intentsolutions.io): smoke 200/NIP-11/functional PASS; unauth-matrix 6/6 REJECT; functional-probe (member NIP-42 auth+publish+readback, un-invited refused) with cleanup CONFIRMED (baseline count 3). Was dependency-blocked by buzz-nry.2 (apex cutover) — that dependency is resolved by the owner decision to keep buzz-prod permanent, so this now closes with its already-captured green evidence.","labels":["hosting"],"dependencies":[{"issue_id":"buzz-nry.3","depends_on_id":"buzz-nry.2","type":"blocks","created_at":"2026-07-29T10:31:31Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-nry.3","depends_on_id":"buzz-nry","type":"parent-child","created_at":"2026-07-29T10:31:29Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-nry.2","title":"Deploy production from the proven staging artifacts with fresh secrets and cut DNS over","description":"Deploy prod from the proven staging artifacts (same digest-pinned compose) with FRESH secrets minted on the new box (new relay identity, new bootstrap owner key until the owner's desktop key swaps in, new db/redis/minio; staging keys never promote). DNS cuts over to the prod host at go-live; the shared stack renames to the staging domain. Deploy specifics + addressing in intent-os ops/buzz. Depends on the bootstrap child.","notes":"Prod deploy DONE (apex cutover pending): staging-proven digest-pinned compose deployed with FRESH prod secrets; 4 containers healthy; own Caddy ingress TLS + security headers. REMAINING (gated on the owner's client-generated desktop key): DNS cutover to the prod host, rename staging to the staging domain, swap BUZZ_DOMAIN/RELAY_URL/CORS to the apex, swap RELAY_OWNER_PUBKEY to the owner's desktop pubkey. Addressing + specifics in intent-os ops/buzz.","status":"closed","priority":1,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T16:31:22Z","created_by":"jeremylongshore","updated_at":"2026-07-30T07:17:44Z","closed_at":"2026-07-30T07:17:44Z","close_reason":"DONE 2026-07-30. Production deployed from proven staging artifacts with FRESH secrets on the dedicated host intent-ops-buzz, serving buzz-prod.intentsolutions.io (169.58.95.32). The 'cut DNS over' (apex → buzz.) requirement is DROPPED by owner decision 2026-07-30: buzz-prod.intentsolutions.io is the PERMANENT production URL (no apex cutover). Prod DNS is therefore already on its permanent, correct name — nothing further to cut over.","labels":["hosting"],"dependencies":[{"issue_id":"buzz-nry.2","depends_on_id":"buzz-nry","type":"parent-child","created_at":"2026-07-29T10:31:22Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-nry.2","depends_on_id":"buzz-nry.1","type":"blocks","created_at":"2026-07-29T10:31:31Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0}
 {"_type":"issue","id":"buzz-nry.1","title":"Bootstrap the new production host to estate conventions","description":"Bootstrap the dedicated prod host to estate ops/host conventions: Ubuntu 24.04, tailnet-only SSH, ufw, fail2ban, unattended-upgrades, docker, its own Caddy (separate ingress = separate failure domain), age host key + sops, borg client, Netdata (tailnet-bound). Host addressing, key paths, and access detail live ONLY in intent-os ops/buzz. Gated on the owner installing the dev-box SSH key.","status":"closed","priority":1,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T16:31:15Z","created_by":"jeremylongshore","updated_at":"2026-07-29T18:06:58Z","started_at":"2026-07-29T17:57:57Z","closed_at":"2026-07-29T18:06:58Z","close_reason":"intent-ops-buzz bootstrapped to estate baseline + verified: Ubuntu 24.04.4 LTS, hostname intent-ops-buzz, joined tailnet [tailnet addr — intent-os ops/buzz] (untagged/user-owned, matching estate); ufw default-deny (tailnet-trusted iface + public 80/443 only, public 22 CLOSED/times-out); sshd key-only + PermitRootLogin no + PasswordAuthentication no; a non-root sudo admin account (NOPASSWD, docker group); fail2ban + unattended-upgrades active; 2G swap swappiness=10; docker 29.6 (log-rotation + live-restore) + compose v5.3; caddy 2.11 (own ingress); age host key at [host key path — intent-os ops/host] (recipient [host age recipient — intent-os ops/host/secrets]); borg client; sops 3.9.4; Netdata bound loopback+tailnet only (127.0.0.1:19999 + [tailnet addr — intent-os ops/buzz]:19999, not public). 7/7 services active.","labels":["hosting"],"dependencies":[{"issue_id":"buzz-nry.1","depends_on_id":"buzz-nry","type":"parent-child","created_at":"2026-07-29T10:31:15Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":1,"comment_count":0}
-{"_type":"issue","id":"buzz-nry","title":"Stand up the dedicated Buzz production VPS and cut the prod domain over to it","description":"Track D: Buzz production runs on its OWN dedicated VPS (owner topology decision 2026-07-29, fork 000-docs/005) so a fast-moving pre-1.0 stack does not share a failure domain with revenue workloads. The shared-VPS stack becomes permanent STAGING (epic buzz-ocv). Prod = the proven staging artifacts (same digest-pinned compose) with FRESH secrets; staging keys never promote. All go-live gates run against prod before any invite. Concrete host detail (addressing, keys, DNS, deploy specifics) lives ONLY in the private intent-os ops/buzz lane.","notes":"GitHub: intent-solutions-io/buzz#9 — https://github.com/intent-solutions-io/buzz/issues/9. MIRROR RULE: bd-sync handles fan-out — `bd-sync note buzz-nry` and `bd-sync close buzz-nry` mirror to GH and Plane automatically.\n\nPlane: BUZZ-3 — (Plane, internal)\nProd pairing milestone 2026-07-30: mobile device pairing now LIVE on the production host (buzz-prod.intentsolutions.io) — sidecar + Caddy /pair deployed, owner confirmed a real device paired (intent-os PR #291). Prod relay + sidecar both healthy. Remaining under this prod epic: .2 apex DNS cutover off buzz-prod-\u003e buzz., .3 full go-live gate suite against prod.","status":"in_progress","priority":1,"issue_type":"epic","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T16:31:08Z","created_by":"jeremylongshore","updated_at":"2026-07-30T04:48:53Z","started_at":"2026-07-29T17:57:57Z","labels":["hosting"],"dependency_count":0,"dependent_count":0,"comment_count":0}
-{"_type":"issue","id":"buzz-bsy","title":"Build the Buzz three-store restore tool (restore.sh) and its restore drill","description":"The wrapped updater's ordered store-restore on a bad-migration revert calls ops/buzz/scripts/restore.sh (--recovery-point \u003cid\u003e --env \u003cenv\u003e) in intent-os. Until it exists+drilled, the updater fail-closes to exit 5 (manual page) rather than faking a DB rollback. Build restore.sh (pg_dump -Fc restore + MinIO media + git volume from a bound recovery point, dangling-ref walk) + a restore drill, so bad-migration recovery is fully unattended. Parent: wrapped-updater lane (buzz-ocv.4).","status":"open","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T20:13:56Z","created_by":"jeremylongshore","updated_at":"2026-07-29T20:13:56Z","labels":["backup","restore","updater"],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-nry","title":"Stand up the dedicated Buzz production VPS and cut the prod domain over to it","description":"Track D: Buzz production runs on its OWN dedicated VPS (owner topology decision 2026-07-29, fork 000-docs/005) so a fast-moving pre-1.0 stack does not share a failure domain with revenue workloads. The shared-VPS stack becomes permanent STAGING (epic buzz-ocv). Prod = the proven staging artifacts (same digest-pinned compose) with FRESH secrets; staging keys never promote. All go-live gates run against prod before any invite. Concrete host detail (addressing, keys, DNS, deploy specifics) lives ONLY in the private intent-os ops/buzz lane.","notes":"GitHub: intent-solutions-io/buzz#9 — https://github.com/intent-solutions-io/buzz/issues/9. MIRROR RULE: bd-sync handles fan-out — `bd-sync note buzz-nry` and `bd-sync close buzz-nry` mirror to GH and Plane automatically.\n\nPlane: BUZZ-3 — (Plane, internal)\nProd pairing milestone 2026-07-30: mobile device pairing now LIVE on the production host (buzz-prod.intentsolutions.io) — sidecar + Caddy /pair deployed, owner confirmed a real device paired (intent-os PR #291). Prod relay + sidecar both healthy. Remaining under this prod epic: .2 apex DNS cutover off buzz-prod-\u003e buzz., .3 full go-live gate suite against prod.","status":"closed","priority":1,"issue_type":"epic","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T16:31:08Z","created_by":"jeremylongshore","updated_at":"2026-07-30T07:18:01Z","started_at":"2026-07-29T17:57:57Z","closed_at":"2026-07-30T07:18:01Z","close_reason":"EPIC DONE 2026-07-30. Dedicated Buzz production VPS (intent-ops-buzz, 169.58.95.32) stood up to estate conventions (.1), deployed with fresh secrets serving buzz-prod.intentsolutions.io (.2), and the full go-live gate suite passed against it (.3). Owner decision 2026-07-30: buzz-prod.intentsolutions.io is the PERMANENT production URL — the 'cut the prod domain over' (apex) part of this epic is intentionally NOT done and is retired, not deferred. All three children closed.","labels":["hosting"],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-s8q","title":"Evaluate + owner-gated execute the Buzz relay upgrade off v0.2.0 via the wrapped updater (staging-rehearsed, pinned-sha — we'd be running AHEAD of Block's stable :latest)","description":"Finding 2026-07-31: Block's GHCR :latest relay tag == our current prod digest (a0f672, 'v0.2.0'); there is NO version-pinned relay release — v0.5.3-era relay code exists only in rolling :main / sha-\u003ccommit\u003e builds. So a relay upgrade = running UNRELEASED bleeding-edge code + a ~3-version schema migration on the live 49-person event store (exactly the D139 risk). Value is low relay-side (community-limit-\u003e5, NIP-11 max_limit, reconnect backoff); the agent reply-guard #3763 + Claude/Codex harnesses are AGENT-binary changes (rebuild our buzz-agent image, tracked under buzz-20l), NOT relay. Desktop clients already auto-updated to v0.5.3 and work against our relay (Nostr protocol-stable). Recommendation: stay on stable :latest until a real relay release exists OR buzz-20l needs a specific relay feature; if executed, pin a sha-\u003ccommit\u003e (not rolling :main), rehearse the migration on buzz-testing via ops/buzz/scripts/updater.sh, then prod with bound-snapshot + functional-probe + auto-revert. Owner-gated: this is an eyes-open 'run ahead of upstream stable' decision.","status":"open","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-08-01T02:40:44Z","created_by":"jeremylongshore","updated_at":"2026-08-01T02:40:44Z","labels":["agentic-ops","relay","updater"],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-20l.8","title":"Cherry-pick the upstream Codex auto-reviewer (block/buzz #3715) onto the fork as a config injection","description":"buzz-acp-local approvals_reviewer=auto_review (#3715, OPEN upstream) — the closest drop-in for the dead Greptile PR-review. Cherry-pick as a fork config injection; does NOT touch the owner-gated remote-agents spec #3748. Acceptance: a PR triggers an automated Codex review comment on a test repo.","status":"open","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T19:58:13Z","created_by":"jeremylongshore","updated_at":"2026-07-31T19:58:13Z","labels":["agentic-ops","codex-review","estate","github-bridge"],"dependencies":[{"issue_id":"buzz-20l.8","depends_on_id":"buzz-20l.1","type":"blocks","created_at":"2026-07-31T13:58:38Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-20l.8","depends_on_id":"buzz-20l","type":"parent-child","created_at":"2026-07-31T13:58:12Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-20l.7","title":"Stand up repo-home channels for all active repos with lazy-create on next push","description":"One \u003crepo-name\u003e home channel per ACTIVE repo across both orgs (owner call: ALL active, ~74, minus archived and truly-dead; the ~15 dead repos get NO channel). Any other repo auto-creates its channel on its next real GitHub event (repo-channels.json is a cache derived from traffic, not a hand-authored census). Additive to the ~24 *-wire channels. Acceptance: active repos have home channels; a push to a channel-less repo auto-creates one; archived repos never get one.","status":"open","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T19:58:12Z","created_by":"jeremylongshore","updated_at":"2026-07-31T19:58:12Z","labels":["agentic-ops","channels","estate","github-bridge"],"dependencies":[{"issue_id":"buzz-20l.7","depends_on_id":"buzz-20l.3","type":"blocks","created_at":"2026-07-31T13:58:35Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-20l.7","depends_on_id":"buzz-20l.4","type":"blocks","created_at":"2026-07-31T13:58:36Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-20l.7","depends_on_id":"buzz-20l","type":"parent-child","created_at":"2026-07-31T13:58:11Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":2,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-b6z.3","title":"Alert runtime relay errors/panics into sys-incidents and health into sys-health","description":"Today only deploy/backup failures page; a runtime relay panic/error goes unnoticed. Tail the relay logs (or a health endpoint) and route error/panic -\u003e sys-incidents, degraded-health -\u003e sys-health via the notifier. AC: a planted relay error lands in sys-incidents.","status":"open","priority":2,"issue_type":"feature","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:40:57Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:40:57Z","dependencies":[{"issue_id":"buzz-b6z.3","depends_on_id":"buzz-b6z","type":"parent-child","created_at":"2026-07-30T21:40:57Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-b6z.3","depends_on_id":"buzz-0ts.1","type":"blocks","created_at":"2026-07-30T21:40:58Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-b6z","title":"Wire Buzz observability — trace export, log aggregation, error alerting, audit-chain","description":"Buzz has the bones (tracing_subscriber structured logs, OTel-export-ready relay code, the buzz-audit per-community SHA-256 hash-chain, Netdata host metrics, docker log rotation) but the wiring is incomplete. Close the gaps so a Buzz runtime problem is visible and pages. Feeds the sys-* channels (epic buzz-0ts).","status":"open","priority":2,"issue_type":"epic","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:40:55Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:40:55Z","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-1zr.3","title":"Golden behavioral evals for the 3 operator agents","description":"Golden-transcript evals (the opskit-golden pattern) for buzz-ops / buzz-feed-curator / buzz-relay-admin: assert each DOES the right sanctioned action and REFUSES illegal ones (DB surgery, deleting a non-owned channel, posting a secret, prod destructive drill). AC: eval suite green; a regression is caught.","status":"open","priority":2,"issue_type":"feature","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:39:34Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:39:34Z","dependencies":[{"issue_id":"buzz-1zr.3","depends_on_id":"buzz-1zr","type":"parent-child","created_at":"2026-07-30T21:39:34Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-1zr.3","depends_on_id":"buzz-yfe.6","type":"blocks","created_at":"2026-07-30T21:39:36Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-1zr.3","depends_on_id":"buzz-yfe.5","type":"blocks","created_at":"2026-07-30T21:39:36Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-1zr.3","depends_on_id":"buzz-yfe.4","type":"blocks","created_at":"2026-07-30T21:39:35Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":3,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-1zr.2","title":"Hermetic tests for the new actions, wired into pnpm ci:drills","description":"Dry-run/mocked hermetic tests (no live relay) for channel-ops command construction, feed-card rendering (imeta), and notify topic-\u003echannel routing — same shape as the existing ops/buzz/tests/*.sh. AC: tests pass in ci:drills; a planted fault is caught.","status":"open","priority":2,"issue_type":"feature","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:39:33Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:39:33Z","dependencies":[{"issue_id":"buzz-1zr.2","depends_on_id":"buzz-1zr","type":"parent-child","created_at":"2026-07-30T21:39:33Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-0ts.2","title":"Add af_buzz_transport to the af_dispatch chain (honest 2xx)","description":"A transport like vps-slack-transport.sh that posts to Buzz with honest 2xx classification, so Buzz alerts inherit dedup/rate-limit/spool/floor. AC: a governed alert routes through af_dispatch to a sys-* channel with a real receipt.","status":"open","priority":2,"issue_type":"feature","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:29:19Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:29:19Z","dependencies":[{"issue_id":"buzz-0ts.2","depends_on_id":"buzz-0ts.1","type":"blocks","created_at":"2026-07-30T21:29:21Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-0ts.2","depends_on_id":"buzz-0ts","type":"parent-child","created_at":"2026-07-30T21:29:18Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0}
+{"_type":"issue","id":"buzz-0ts.1","title":"Build buzz-notify.sh (topic -\u003e channel-uuid) + a notifier bot key","description":"A notifier bot (own key, separate from the AI Wire + goose keys) + buzz-notify.sh wrapping buzz messages send (kind:9), mapping a topic to a sys-* channel uuid. AC: a test alert posts to sys-incidents.","status":"open","priority":2,"issue_type":"feature","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:29:18Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:29:18Z","dependencies":[{"issue_id":"buzz-0ts.1","depends_on_id":"buzz-0ts","type":"parent-child","created_at":"2026-07-30T21:29:18Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-0ts.1","depends_on_id":"buzz-w92.1","type":"blocks","created_at":"2026-07-30T21:29:21Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":2,"comment_count":0}
+{"_type":"issue","id":"buzz-0ts","title":"Route estate system notifications into the private sys-* channels","description":"Track B internal consolidation: the estate's ops alerts post into the private sys-* channels (incidents/health/backups/deploys/automation), retiring Slack/notify/Moshi. Keep the off-estate survivability floor (healthchecks.io + af_email_floor) and Ezekiel's blog emails. Inherits dedup/rate-limit/spool/floor from the governed af_dispatch chain.","status":"open","priority":2,"issue_type":"epic","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:29:17Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:29:17Z","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-w92.7","title":"Curation and the daily ai-wire digest (the anti-firehose moat)","description":"The curator promotes the day's best cross-lab items into one ai-wire digest + one announcements headline; members @mention to go deeper. AC: a real daily digest posts to ai-wire.","status":"closed","priority":2,"issue_type":"feature","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:29:12Z","created_by":"jeremylongshore","updated_at":"2026-07-31T04:30:55Z","closed_at":"2026-07-31T04:30:55Z","close_reason":"Daily ai-wire digest live — --digest composes cross-lab roundup (70b→8b→NVIDIA), posts to 1-ai-wire, cron 06:30 CT","dependencies":[{"issue_id":"buzz-w92.7","depends_on_id":"buzz-w92.3","type":"blocks","created_at":"2026-07-30T21:29:16Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-w92.7","depends_on_id":"buzz-w92","type":"parent-child","created_at":"2026-07-30T21:29:11Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-w92.8","title":"Schedule the pipeline via cron and register it in automations.md","description":"Cron the ingestion + digest on the dev box (estate automation home), armed with notify-lib liveness markers, registered in mission-control/automations.md. AC: cron live + registry row + liveness sweep row.","status":"closed","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:29:12Z","created_by":"jeremylongshore","updated_at":"2026-07-31T04:18:42Z","closed_at":"2026-07-31T04:18:42Z","close_reason":"3h cron deployed (~/bin/buzz-wire-cron.sh) + notify-lib liveness + registered in automations.md","dependencies":[{"issue_id":"buzz-w92.8","depends_on_id":"buzz-w92.3","type":"blocks","created_at":"2026-07-30T21:29:16Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-w92.8","depends_on_id":"buzz-w92","type":"parent-child","created_at":"2026-07-30T21:29:12Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-w92.4","title":"Wire the existing Anthropic monitor fleet into the anthropic-* channels","description":"The dev-box ~/bin monitors (claude-code-changelog, claude-blog, anthropic-news/research/engineering, anthropic-status) already summarize NEW items to Slack; add a Buzz post path -\u003e anthropic-changelog / anthropic-blogs / anthropic-research / anthropic-outages. AC: a real Anthropic release lands in anthropic-changelog.","status":"closed","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:29:09Z","created_by":"jeremylongshore","updated_at":"2026-07-31T14:04:52Z","closed_at":"2026-07-31T14:04:52Z","close_reason":"Anthropic bridged via HTML-scrape source type (news/research/engineering -\u003e anthropic-blogs/research), mirroring the estate monitors; Mistral added. buzz-w92.6 partially done (tooling/mcp/newsletters/ships/status live).","dependencies":[{"issue_id":"buzz-w92.4","depends_on_id":"buzz-w92.1","type":"blocks","created_at":"2026-07-30T21:29:14Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-w92.4","depends_on_id":"buzz-w92","type":"parent-child","created_at":"2026-07-30T21:29:09Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-w92.3","title":"Ship the easy-tier provider feeds (clean RSS/status)","description":"Anthropic, OpenAI, Google/DeepMind, Groq, DeepSeek, MiniMax -\u003e their *-wire channels. AC: each posts real items on a schedule.","status":"closed","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:29:08Z","created_by":"jeremylongshore","updated_at":"2026-07-31T04:18:40Z","closed_at":"2026-07-31T04:18:40Z","close_reason":"easy-tier feeds live — OpenAI, HuggingFace, arXiv cs.AI, Google DeepMind; 4 seed cards posted with summaries","dependencies":[{"issue_id":"buzz-w92.3","depends_on_id":"buzz-w92.2","type":"blocks","created_at":"2026-07-30T21:29:13Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-w92.3","depends_on_id":"buzz-w92","type":"parent-child","created_at":"2026-07-30T21:29:08Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":4,"comment_count":0}
+{"_type":"issue","id":"buzz-yfe.6","title":"Build the buzz-relay-admin agent (membership, keys, backups, health)","description":"A /agent-creator agent for relay-admin ops (buzz-admin add/remove-member, keygen, backup/restore, health). AC: passes /validate-agent; encodes host access, buzz-admin-in-relay-container, backup/restore runbooks.","status":"closed","priority":2,"issue_type":"feature","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:27:17Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:36:21Z","closed_at":"2026-07-31T03:36:21Z","close_reason":"buzz-relay-admin agent built + PASS /validate-agent","dependencies":[{"issue_id":"buzz-yfe.6","depends_on_id":"buzz-yfe.3","type":"blocks","created_at":"2026-07-30T21:29:03Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-yfe.6","depends_on_id":"buzz-yfe","type":"parent-child","created_at":"2026-07-30T21:27:16Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":2,"comment_count":0}
+{"_type":"issue","id":"buzz-yfe.7","title":"Validate the skill and all operator agents against the IS spec","description":"Run /validate-skillmd + /validate-agent on the skill and 3 agents; fix findings. AC: all green.","status":"closed","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:27:17Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:36:22Z","closed_at":"2026-07-31T03:36:22Z","close_reason":"all 3 agents PASS /validate-agent; skill PASS /validate-skillmd; reference-vs-code consistency 106 citations 100% resolve to real fork source (no fabrications)","dependencies":[{"issue_id":"buzz-yfe.7","depends_on_id":"buzz-yfe.6","type":"blocks","created_at":"2026-07-30T21:29:05Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-yfe.7","depends_on_id":"buzz-yfe.4","type":"blocks","created_at":"2026-07-30T21:29:03Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-yfe.7","depends_on_id":"buzz-yfe","type":"parent-child","created_at":"2026-07-30T21:27:17Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-yfe.7","depends_on_id":"buzz-yfe.5","type":"blocks","created_at":"2026-07-30T21:29:04Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":3,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-yfe.5","title":"Build the buzz-feed-curator agent (AI-Wire posting)","description":"A /agent-creator agent that fetches feeds, summarizes, and posts rich cards to *-wire channels as the AI Wire bot. AC: passes /validate-agent; encodes the posting primitive, provider-first routing, membership requirement.","status":"closed","priority":2,"issue_type":"feature","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:27:16Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:36:19Z","closed_at":"2026-07-31T03:36:19Z","close_reason":"buzz-feed-curator agent built + PASS /validate-agent","dependencies":[{"issue_id":"buzz-yfe.5","depends_on_id":"buzz-yfe.3","type":"blocks","created_at":"2026-07-30T21:29:02Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-yfe.5","depends_on_id":"buzz-yfe","type":"parent-child","created_at":"2026-07-30T21:27:15Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":3,"comment_count":0}
+{"_type":"issue","id":"buzz-yfe.4","title":"Build the buzz-ops operator agent (channel + identity management)","description":"A /agent-creator agent that manages channels + identities on the live relay per the runbook. AC: passes /validate-agent (8-field spec); encodes owner-key ownership, sanctioned CLI, secret-via-docker-exec-e, verify-via-channels-list.","status":"closed","priority":2,"issue_type":"feature","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:27:15Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:36:18Z","closed_at":"2026-07-31T03:36:18Z","close_reason":"buzz-ops agent built + PASS /validate-agent (14-field standalone spec)","dependencies":[{"issue_id":"buzz-yfe.4","depends_on_id":"buzz-yfe.3","type":"blocks","created_at":"2026-07-30T21:29:00Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-yfe.4","depends_on_id":"buzz-yfe","type":"parent-child","created_at":"2026-07-30T21:27:14Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":2,"comment_count":0}
+{"_type":"issue","id":"buzz-ehv.2","title":"Define and document the member join/onboarding model","description":"For the shared community: members JOIN the canonical open channels (they never template-create their own — templates make NEW channels and cause the duplicate-Welcome mess; see RUNBOOK-channels.md 1.6). AC: document which channels auto-join at onboarding vs opt-in, how a member joins an open *-wire pack, and the seed-content-before-invite step. Feeds the all-in onboarding epic (E5).","status":"open","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:27:11Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:27:11Z","dependencies":[{"issue_id":"buzz-ehv.2","depends_on_id":"buzz-ehv","type":"parent-child","created_at":"2026-07-30T21:27:10Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-bsy","title":"Build the Buzz three-store restore tool (restore.sh) and its restore drill","description":"The wrapped updater's ordered store-restore on a bad-migration revert calls ops/buzz/scripts/restore.sh (--recovery-point \u003cid\u003e --env \u003cenv\u003e) in intent-os. Until it exists+drilled, the updater fail-closes to exit 5 (manual page) rather than faking a DB rollback. Build restore.sh (pg_dump -Fc restore + MinIO media + git volume from a bound recovery point, dangling-ref walk) + a restore drill, so bad-migration recovery is fully unattended. Parent: wrapped-updater lane (buzz-ocv.4).","status":"closed","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T20:13:56Z","created_by":"jeremylongshore","updated_at":"2026-07-30T05:54:52Z","closed_at":"2026-07-30T05:54:52Z","close_reason":"DONE 2026-07-30 (ultracode Track-A workflow). Built ops/buzz/scripts/restore.sh — the real destructive three-store restore (Postgres pg_restore --clean --if-exists → media mc mirror --overwrite → git volume), gated behind --in-place with verify-before-destroy (sha256 every artifact + PGDMP header + manifest.env==--env cross-check; exit 2 writes nothing). Chose --in-place-required over auto-restore so decision-log/038's human-gate holds with ZERO updater.sh changes: the updater's flagless call exits 64 → rc5 page unchanged (updater-drill 6/6 still green). Hermetic restore-test.sh 6/6 with mutation-proven teeth; restore-drill-test 4/4 no regression; wired into ci:drills. Merged intent-os PR #293 (4/4 estate-CI green). Remaining real-tool proof = a host-side scratch-stack drill before first prod use (noted in runbook).","labels":["backup","restore","updater"],"dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"buzz-ocv.6","title":"Add the mobile pairing sidecar overlay and validate a real desktop-to-mobile pairing","description":"Track E2 (external infra review; upstream #2734 / PR #2736): the first-party compose bundle lacks the buzz-pair-relay sidecar, so Android members cannot pair — and the all-in onboarding wave includes Android. Review the pinned image for the buzz-pair-relay entrypoint, add an estate overlay service (same image, entrypoint buzz-pair-relay, internal :5000, healthcheck) + a Caddy /pair* route. Claim it works only after a REAL desktop-to-mobile pairing succeeds; if wave 1 doesn't require it, document the limitation honestly instead.","notes":"PAIRING BLOCKED BY IMAGE (found 2026-07-30 during a live prod attempt): the pinned relay image ghcr.io/block/buzz@sha256:a0f672... (relay-v0.2.0) contains ONLY buzz-admin + buzz-relay in /usr/local/bin — the buzz-pair-relay binary is NOT in it (added in a NEWER buzz build; the Dockerfile builds it but our pinned digest predates/excludes it). So the pairing overlay's entrypoint 'buzz-pair-relay' -\u003e 'executable file not found'. NEAR-MISS: 'docker compose up -d' with the overlay recreated the relay (overlay patches relay env for BUZZ_PAIRING_RELAY_URL) AND the sidecar failed to start, which took the relay DOWN briefly; reverted (removed COMPOSE_FILE + overlay, base up) -\u003e relay healthy, prod restored. LESSONS: (1) pairing REQUIRES promoting a newer buzz image that ships buzz-pair-relay — do it via the drilled wrapped-updater (snapshot-\u003eprobe-\u003erevert), never a raw compose up on the live relay; (2) the overlay must PROBE the image for /usr/local/bin/buzz-pair-relay before starting, and bring up ONLY the sidecar service first (never recreate the relay on sidecar failure); (3) hermetic pairing-overlay-test passed because it mocked the binary — add a real-image binary-presence check. The relay DID advertise BUZZ_PAIRING_RELAY_URL correctly (app generated a valid nostrpair:// deep-link) — only the sidecar endpoint was missing.","status":"closed","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T16:30:45Z","created_by":"jeremylongshore","updated_at":"2026-07-30T04:47:02Z","started_at":"2026-07-29T22:43:42Z","closed_at":"2026-07-30T04:47:02Z","close_reason":"DONE 2026-07-30. Mobile pairing sidecar deployed to prod + a REAL device paired (owner-confirmed handshake). Root cause: pinned relay-v0.2.0 image lacks buzz-pair-relay; fix pins the sidecar SEPARATELY via BUZZ_PAIR_RELAY_IMAGE (:main @9de8aff1) + absolute entrypoint, deployed sidecar-first (relay untouched), Caddy /pair route added. Verified wss://buzz-prod.intentsolutions.io/pair -\u003e 101 Switching Protocols (Caddy-\u003esidecar); sidecar logs show the live paired connection. intent-os PR #291 (overlay + test image-guard + runbook; 4/4 CI green). pairing-overlay-test now guards the image bug (5/5).","labels":["clients","hosting"],"dependencies":[{"issue_id":"buzz-ocv.6","depends_on_id":"buzz-ocv","type":"parent-child","created_at":"2026-07-29T10:30:45Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"buzz-ocv.5","title":"Set the Tauri desktop origins in the relay CORS config and verify with the packaged desktop client","description":"Track E1 (external infra review, verified vs upstream #3490): current env allows only https://the prod domain as an origin; packaged Tauri desktop clients present tauri://localhost (macOS/Linux) or http://tauri.localhost (Windows), so desktop join is BLOCKED. Verify the pinned image's CORS env handling, add the two Tauri origins (no permissive-CORS shortcuts), restart, confirm relay healthy + correct Access-Control-Allow-Origin echo. Final verification is a join from the PACKAGED desktop client on the owner's workstation, not a dev build.","notes":"CORS CONFIG FIXED (intent-os PR #283, merged via estate-CI 3 green). BUZZ_CORS_ORIGINS composed in version-controlled compose from required BUZZ_DOMAIN + tauri://localhost + http://tauri.localhost (environment: overrides env_file; non-secret Tauri origins out of sops). Closes the desktop-join gap AND a latent permissive-CORS gap (relay goes permissive only when the var is EMPTY; required BUZZ_DOMAIN makes empty impossible). Proof: ops/buzz/tests/cors-config-test.sh 2/2, wired into ci:drills. REMAINING (owner-gated): apply on staging (docker compose up -d relay) + verify a real join with the PACKAGED desktop client on Jeremy's workstation (dev build won't exercise Tauri origins).\nCORS APPLIED LIVE to BOTH hosts 2026-07-29 (intent-os PR #284 records; compose applied with backup + config-gate + relay recreate). Staging BUZZ_CORS_ORIGINS=https://the prod domain,tauri://localhost,http://tauri.localhost ; prod=…buzz-prod…,tauri…; relay healthy + _readiness 200 on each. Desktop-join unblocked on the live boxes. ONLY remaining: packaged-desktop-client verify on Jeremy's workstation (owner-gated).","status":"closed","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T16:30:36Z","created_by":"jeremylongshore","updated_at":"2026-07-30T04:47:05Z","started_at":"2026-07-29T21:16:21Z","closed_at":"2026-07-30T04:47:05Z","close_reason":"DONE 2026-07-30. Tauri desktop CORS origins (tauri://localhost + http://tauri.localhost) composed into version-controlled compose (intent-os PR #283), applied live to both hosts (PR #284), cors-config-test 2/2 in ci:drills. Final owner-gated gate met: Jeremy joined from the PACKAGED Linux desktop client to buzz-prod.intentsolutions.io (connected, admin, channels visible) — the packaged-client CORS verification the acceptance required.","labels":["clients","hosting"],"dependencies":[{"issue_id":"buzz-ocv.5","depends_on_id":"buzz-ocv","type":"parent-child","created_at":"2026-07-29T10:30:35Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"buzz-ocv.4","title":"Wire backups and the wrapped updater, register everything in the estate","description":"nightly pg_dump artifact into the borg set + three-store recovery point; weekly updater snapshot-promote-probe-revert; automations.md + catalog rows; E3 drill gates filed","notes":"Track E additions (external infra review 2026-07-29): the wrapped updater's promotion checklist MUST include — release-notes review; a staging boot; a probe-hang check (upstream #2723/PR #2724 — git conformance probe can wedge startup; our pinned digest boots healthy with BUZZ_GIT_CONFORMANCE_PROBE=true, but a future image must prove it on staging before promotion); a CORS/Tauri-origin regression check; a pairing regression check. Also confirmed: upstream's own 'backup' command is a checklist, not a backup — our pg_dump + three-store recovery-point design stands; off-site copy rides the estate B2/borg chain.\nBackup automation BUILT + RAN (evidence): scripts/backup.sh on prod produced encrypted borg archive intent-ops-buzz-prod-2026-07-29T183641Z (pg_dump 167KB schema-head-6 + media(6) + git + identity + manifest w/ sha256s); flock, retention 14/8/6, freshness marker, Slack notify (interim — Buzz replaces Slack post-migration), nonzero-on-fail. systemd buzz-backup.timer enabled (daily 04:20 UTC). Runbook ops/buzz/RUNBOOK-backup-restore.md. STILL OPEN: off-site B2 push (owner-gated estate-wide, Epic 1.1 B2 not provisioned) + borg repokey export off-box + Netdata backup-age alert + the wrapped updater.\nGIT CONFORMANCE PROBE risk (Priority 4) — evidence-based decision: pinned image = v0.2.0 / source rev 0d9be2f (built 2026-07-10). Upstream fix PR #2724 is still OPEN (NOT merged) -\u003e the bounded-timeout fix is NOT in our image. BUT fault test on a scratch relay (MinIO unreachable + BUZZ_GIT_CONFORMANCE_PROBE=true): the probe ran ('git object-store conformance probe A3 gate') and the relay EXITED with 's3 backend error' after ~63s (bounded by reqwest timeout) — it FAILS CLOSED, does not hang indefinitely. DECISION: KEEP the probe ON (real consistency gate; compose gates minio-healthy-before-relay; fails-closed not hangs), and MANDATE a deploy-wrapper HARD TIMEOUT (Priority 3) that bounds the relay-healthy wait + auto-reverts regardless of app behaviour — this covers the untested 'accepted-but-nonresponsive' case. Removal-of-risk condition: promote a digest containing merged #2724. Untested residual: MinIO-nonresponsive half-open (harder to reproduce safely).\nWrapped-updater half SHIPPED (intent-os PR #282, merged via estate-CI 3 green: gates 127s / drills 220s / gitleaks). Built ops/buzz/scripts/{updater,functional-probe,_repin-and-start}.sh over the drilled estate watchtower-gate/deploy-wrapper; hermetic planted-fault drill ops/buzz/tests/updater-drill.sh 6/6 (clean promote, bad-release auto-revert+store-restore+re-probe, hard-timeout hang guard rc124, scan-hold fail-closed, snapshot-abort, absent-restore manual page); systemd buzz-updater.{service,timer} (weekly Sun 05:30 UTC); runbook RUNBOOK-wrapped-updater.md; registered backup+updater timers in mission-control/automations.md; drill wired into ci:drills. STILL OPEN on .4: install the timer on the intent-ops-buzz production host + first real run; restore.sh three-store tool (follow-up bead filed). Real functional-probe-against-live-staging is buzz-ocv.3.\nUpdater lane DEPLOYED to staging (dormant) via install-updater-lane.sh (intent-os PR #284): 3 buzz scripts + 2 estate deps (watchtower-gate/deploy-wrapper -\u003e /srv/buzz/lib/) + systemd units; daemon-reload OK, timer disabled/inactive. Fixed container-name (buzz-relay-1) + governed-notify + systemd env wiring from live state. Prod updater install + timer-enable gated on the real staging functional-probe rehearsal (blocked on installing nak — new bead).\nGate TOOLING built + merged (intent-os PR #287, CI + hermetic tests, owner-authorized merge — reviewers unavailable): monitoring (outside-in-buzz control + backup-age watchdog 3/3), key-incident runbooks (7/7), smoke-suite + unauth-matrix (4/4), all in ci:drills. REMAINING = live runs: functional probe + unauth matrix against live prod off-network; install backup-age timer + outside-in probe; rehearse key runbooks. Parallel-authored by 3 subagents.","status":"in_progress","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T15:47:20Z","created_by":"jeremylongshore","updated_at":"2026-07-29T23:57:52Z","started_at":"2026-07-29T18:34:08Z","labels":["hosting"],"dependencies":[{"issue_id":"buzz-ocv.4","depends_on_id":"buzz-ocv","type":"parent-child","created_at":"2026-07-29T09:47:20Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"buzz-ocv.3","title":"Prove the deployment: smokes, functional membership probe, and the off-network unauth probe matrix","description":"/health + /_readiness + NIP-11; nak NIP-42 member publish/readback + un-invited refusal; media PUT / git packs / hooks endpoints all 401-403","notes":"Gate TOOLING built + merged (intent-os PR #287, CI + hermetic tests, owner-authorized merge — reviewers unavailable): monitoring (outside-in-buzz control + backup-age watchdog 3/3), key-incident runbooks (7/7), smoke-suite + unauth-matrix (4/4), all in ci:drills. REMAINING = live runs: functional probe + unauth matrix against live prod off-network; install backup-age timer + outside-in probe; rehearse key runbooks. Parallel-authored by 3 subagents.\nFunctional membership probe + smoke suite + unauth matrix PROVEN GREEN on live staging (PR #288). Prod runs remain (buzz-2i6).","status":"open","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T15:47:19Z","created_by":"jeremylongshore","updated_at":"2026-07-30T00:37:48Z","labels":["hosting"],"dependencies":[{"issue_id":"buzz-ocv.3","depends_on_id":"buzz-ocv","type":"parent-child","created_at":"2026-07-29T09:47:18Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
-{"_type":"issue","id":"buzz-ocv.2","title":"Wire the estate Caddy ingress with the compensating edge controls","description":"site block + WS passthrough, body-size caps, timeouts, security headers; caddy validate + reload","status":"open","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T15:47:18Z","created_by":"jeremylongshore","updated_at":"2026-07-29T15:47:18Z","labels":["hosting"],"dependencies":[{"issue_id":"buzz-ocv.2","depends_on_id":"buzz-ocv","type":"parent-child","created_at":"2026-07-29T09:47:17Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-ocv.2","title":"Wire the estate Caddy ingress with the compensating edge controls","description":"site block + WS passthrough, body-size caps, timeouts, security headers; caddy validate + reload","status":"closed","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T15:47:18Z","created_by":"jeremylongshore","updated_at":"2026-07-30T05:45:54Z","closed_at":"2026-07-30T05:45:54Z","close_reason":"DONE 2026-07-30 (ultracode Track-A workflow). Compensating edge controls shipped + applied. CODE: ops/buzz/scripts/apply-edge-controls.sh (plan-only default, --apply to install) + hermetic test, merged intent-os PR #292 (4/4 estate-CI green, adversarially verified sound). APPLIED LIVE on the dedicated prod host intent-ops-buzz: fail2ban 'caddy-buzz' jail (bans public 4xx-flooders from /var/log/caddy/buzz-access.log) + nftables 'inet buzz_edge' connlimit (128 concurrent NEW/IP on tcp 80+443 only) + buzz-edge-nft.service enabled (reboot-safe). VERIFIED no self-lock: SSH intact, relay _readiness 200 off-box, tailnet/port-22 never touched (WS/established never dropped). SCOPING: applied to the Buzz-DEDICATED prod host only; deliberately NOT applied host-wide on the shared VPS staging (its connlimit would rate-limit co-tenant estate stacks Plane/ERP/CRM) — request_body caps + security headers already exist in Caddy on both. Closes the last non-owner-gated piece of go-live edge hardening.","labels":["hosting"],"dependencies":[{"issue_id":"buzz-ocv.2","depends_on_id":"buzz-ocv","type":"parent-child","created_at":"2026-07-29T09:47:17Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"buzz-ocv.1","title":"Provision DNS, secrets, and the /srv/buzz compose stack, booted closed from first start","description":"dns + sops env (relay identity key, bootstrap op owner key, HMAC, db/redis/minio creds) + estate-owned compose with digest-pinned image, loopback publish, resource caps","status":"closed","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T15:47:17Z","created_by":"jeremylongshore","updated_at":"2026-07-29T15:52:10Z","closed_at":"2026-07-29T15:52:10Z","close_reason":"the prod domain A record live (Porkbun lane); secrets generated (relay identity + bootstrap op owner + HMAC + db/redis/minio) deployed as /srv/buzz/.env mode 600 with sops master in intent-os ops/buzz/secrets/buzz.prod.env.sops (dev+VPS age recipients); estate-owned compose (digest-pinned image, loopback publish 3004/3084, mem/cpus/pids caps, own bridge net) deployed; all 4 containers healthy; _readiness 200; NIP-11 serving; closed-relay env from first boot","labels":["hosting"],"dependencies":[{"issue_id":"buzz-ocv.1","depends_on_id":"buzz-ocv","type":"parent-child","created_at":"2026-07-29T09:47:16Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
-{"_type":"issue","id":"buzz-ocv","title":"Stand up the closed Buzz relay stack on the estate VPS behind the wrapped update lane","description":"RE-SCOPED 2026-07-29 (owner topology decision, fork 000-docs/005): this stack on the SHARED estate VPS is STAGING, permanently — same compose, same gates; restore drills and updater planted-fault drills run here, never on prod. Production moves to a DEDICATED VPS (Track D epic). Original scope: /srv/buzz compose stack (relay pinned by digest, Postgres 17, Redis 7, MinIO interim) closed from first boot, sops-held secrets, loopback publish behind estate Caddy, resource caps, DNS, smokes + unauth probe matrix, pg_dump backup wiring, wrapped updater. At cutover this env renames to the staging domain. E3 go-live gates run against PROD on the dedicated box before any invite.","notes":"GitHub: intent-solutions-io/buzz#8 — https://github.com/intent-solutions-io/buzz/issues/8. MIRROR RULE: bd-sync handles fan-out — `bd-sync note buzz-ocv` and `bd-sync close buzz-ocv` mirror to GH and Plane automatically.\n\nPlane: BUZZ-2 — (Plane, internal)\nTOPOLOGY RE-SCOPE (owner decision 2026-07-29, recorded as fork 000-docs/005): this shared-VPS stack is re-designated permanent STAGING — same compose, same gates; restore drills and updater planted-fault drills run here, never on prod. Production moves to a dedicated VPS (epic buzz-nry / GH #9 / Plane BUZZ-3). At cutover this env renames to the staging domain; staging keys never promote to prod. New Track-E children under this epic: .5 Tauri/CORS desktop-join fix, .6 mobile pairing sidecar overlay; updater promotion-checklist additions noted on .4.\nSession 2026-07-30: two children COMPLETE — .6 mobile pairing (real device paired; sidecar via BUZZ_PAIR_RELAY_IMAGE + Caddy /pair; intent-os PR #291) and .5 Tauri CORS (packaged Linux desktop client joined prod). Remaining under this staging epic: .2 (Caddy edge controls), .3 (smokes+unauth matrix), .4 (backups+updater register).","status":"in_progress","priority":2,"issue_type":"epic","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T15:47:04Z","created_by":"jeremylongshore","updated_at":"2026-07-30T04:47:23Z","started_at":"2026-07-29T15:47:21Z","labels":["hosting"],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-ocv","title":"Stand up the closed Buzz relay stack on the estate VPS behind the wrapped update lane","description":"RE-SCOPED 2026-07-29 (owner topology decision, fork 000-docs/005): this stack on the SHARED estate VPS is STAGING, permanently — same compose, same gates; restore drills and updater planted-fault drills run here, never on prod. Production moves to a DEDICATED VPS (Track D epic). Original scope: /srv/buzz compose stack (relay pinned by digest, Postgres 17, Redis 7, MinIO interim) closed from first boot, sops-held secrets, loopback publish behind estate Caddy, resource caps, DNS, smokes + unauth probe matrix, pg_dump backup wiring, wrapped updater. At cutover this env renames to the staging domain. E3 go-live gates run against PROD on the dedicated box before any invite.","notes":"GitHub: intent-solutions-io/buzz#8 — https://github.com/intent-solutions-io/buzz/issues/8. MIRROR RULE: bd-sync handles fan-out — `bd-sync note buzz-ocv` and `bd-sync close buzz-ocv` mirror to GH and Plane automatically.\n\nPlane: BUZZ-2 — (Plane, internal)\nTOPOLOGY RE-SCOPE (owner decision 2026-07-29, recorded as fork 000-docs/005): this shared-VPS stack is re-designated permanent STAGING — same compose, same gates; restore drills and updater planted-fault drills run here, never on prod. Production moves to a dedicated VPS (epic buzz-nry / GH #9 / Plane BUZZ-3). At cutover this env renames to the staging domain; staging keys never promote to prod. New Track-E children under this epic: .5 Tauri/CORS desktop-join fix, .6 mobile pairing sidecar overlay; updater promotion-checklist additions noted on .4.\nSession 2026-07-30: two children COMPLETE — .6 mobile pairing (real device paired; sidecar via BUZZ_PAIR_RELAY_IMAGE + Caddy /pair; intent-os PR #291) and .5 Tauri CORS (packaged Linux desktop client joined prod). Remaining under this staging epic: .2 (Caddy edge controls), .3 (smokes+unauth matrix), .4 (backups+updater register).\nTrack-A ultracode session 2026-07-30: child .2 (edge controls) CLOSED — fail2ban + nftables connlimit applied live on the prod host, verified no self-lock (intent-os PR #292). Remaining children: .3 (staging probe matrix), .4 (backups+updater register).","status":"in_progress","priority":2,"issue_type":"epic","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T15:47:04Z","created_by":"jeremylongshore","updated_at":"2026-07-30T05:46:37Z","started_at":"2026-07-29T15:47:21Z","labels":["hosting"],"dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"buzz-4ei.4","title":"Mirror the epic three-way and seed repo and estate memory","description":"GitHub cluster issue on intent-solutions-io/buzz + Plane BUZZ project via bd-sync link; auto-memory for the buzz working dir; estate memory buzz-adoption-state; private ops/buzz/README.md operator authority.","status":"closed","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T04:24:21Z","created_by":"jeremylongshore","updated_at":"2026-07-29T04:36:11Z","closed_at":"2026-07-29T04:36:11Z","close_reason":"Three-way mirror live: buzz-4ei linked via bd-sync to intent-solutions-io/buzz#1 + Plane BUZZ-1 (comments fanned out); Plane project BUZZ created; estate anchor spine-8fl linked to the same pair; memories seeded (buzz working-dir auto-memory + intent-os buzz-adoption-state + ops/buzz/README.md operator authority)","labels":["bead-tooling"],"dependencies":[{"issue_id":"buzz-4ei.4","depends_on_id":"buzz-4ei","type":"parent-child","created_at":"2026-07-28T22:24:21Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"buzz-4ei.3","title":"Implement the missing test layers with the in-repo audit harness, Layer 1 git hooks required","description":"/implement-tests for gaps found by the baseline audit; in-repo enforcement only (cargo/vendored harness), additive files only, staged for review.","status":"closed","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T04:24:20Z","created_by":"jeremylongshore","updated_at":"2026-07-29T06:21:36Z","closed_at":"2026-07-29T06:21:36Z","close_reason":"Merged in PR #6 (fa14f3f16): scripts/fork-gates/{additive-only,must-survive} + vendored audit-harness + 10-file hash-pin manifest + tracked lefthook-local.yml (escape-scan pre-commit; gates+verify pre-push) + decision record 000-docs/004. All four gates green on the merged tree; zero upstream-path edits","labels":["test-hygiene"],"dependencies":[{"issue_id":"buzz-4ei.3","depends_on_id":"buzz-4ei","type":"parent-child","created_at":"2026-07-28T22:24:20Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"buzz-4ei.2","title":"Run the testing-SOP baseline audit and produce TEST_AUDIT.md against the 7-layer taxonomy","description":"Diagnostic only: classify the fork, map upstream's suite (just test-unit / docker integration / e2e via buzz-test-client) to the 7 layers, write TEST_AUDIT.md. Staged, not auto-committed.","status":"closed","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T04:24:19Z","created_by":"jeremylongshore","updated_at":"2026-07-29T04:26:01Z","closed_at":"2026-07-29T04:26:01Z","close_reason":"TEST_AUDIT.md written (diagnostic only): upstream suite strong across all 7 layers (~5700 Rust test fns, lefthook L1, clippy/biome/cargo-deny L2, Playwright E2E); fork-lane gaps = additive-only invariant gate + in-repo harness, handed to buzz-4ei.3","labels":["test-hygiene"],"dependencies":[{"issue_id":"buzz-4ei.2","depends_on_id":"buzz-4ei","type":"parent-child","created_at":"2026-07-28T22:24:19Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"buzz-4ei.1","title":"Author the master blueprint, decision record, deploy posture, and FORK.md as additive-only artifacts","description":"000-docs/{000-INDEX,001-PP-PLAN,002-DR-DECR,003-OD-DEPL} + FORK.md; zero upstream-path edits.","status":"closed","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T04:24:18Z","created_by":"jeremylongshore","updated_at":"2026-07-29T04:26:00Z","closed_at":"2026-07-29T04:26:00Z","close_reason":"Authored additive-only: 000-docs/{000-INDEX,001-PP-PLAN blueprint,002-DR-DECR decision record,003-OD-DEPL deploy posture} + FORK.md; git diff upstream/main --stat shows only fork-added paths","labels":["fork-infra"],"dependencies":[{"issue_id":"buzz-4ei.1","depends_on_id":"buzz-4ei","type":"parent-child","created_at":"2026-07-28T22:24:18Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"buzz-4ei","title":"Stand up the Intent Solutions fork infrastructure for the Buzz adoption","description":"Phase 1 / E1 of 000-docs/001-PP-PLAN-buzz-adoption-master-blueprint.md: fork + clone + beads/Dolt activation, master blueprint + decision record + deploy posture + FORK.md, testing-SOP baseline (TEST_AUDIT.md), three-way mirror (GitHub cluster issue + Plane BUZZ) and memory seeding. Additive-only: zero upstream-path edits.","notes":"GitHub: intent-solutions-io/buzz#1 — https://github.com/intent-solutions-io/buzz/issues/1. MIRROR RULE: bd-sync handles fan-out — `bd-sync note buzz-4ei` and `bd-sync close buzz-4ei` mirror to GH and Plane automatically.\n\nPlane: BUZZ-1 — (Plane, internal)\nE1 milestone: blueprint set + FORK.md + TEST_AUDIT.md authored (buzz-4ei.1, .2 closed); beads write-path root-caused (bd contributor-role fork routing) and fixed via --role maintainer; PR opening next. Note: epic was re-minted from buzz-ekg to buzz-4ei during the store rebuild.\nE1 shipped: PR intent-solutions-io/buzz#2 squash-merged to fork main (6cf4df96f) after CodeRabbit review (4 findings fixed in e49ed40a6, 2 declined with reasons). Children .1/.2/.4 closed with evidence; .3 (fork-lane test layers) remains open — epic stays in_progress until it lands. Deferred: epic-boundary Dolt tag until dolt-mcp-vcs is available (system dolt CLI is version-skewed vs bd's embedded engine).","status":"closed","priority":2,"issue_type":"epic","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T04:24:17Z","created_by":"jeremylongshore","updated_at":"2026-07-29T06:21:39Z","started_at":"2026-07-29T04:25:59Z","closed_at":"2026-07-29T06:21:39Z","close_reason":"E1 complete: all 4 children closed with evidence (PRs #2/#3/#5/#6 merged; blueprint ledger E1=COMPLETE; GH cluster #1 auto-closed by PR #6). Fork contract now machine-enforced. Phase 2 hosting opens per blueprint after the MX cutover.","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"buzz-bkt","title":"acceptance probe","status":"closed","priority":2,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-29T04:23:48Z","created_by":"jeremylongshore","updated_at":"2026-07-29T04:23:49Z","started_at":"2026-07-29T04:23:49Z","closed_at":"2026-07-29T04:23:49Z","close_reason":"probe","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-20l.10","title":"Schema the goose-filed issue (finding, repro, executable acceptance, stop-conditions, blast-radius) and lint it in pnpm check (deferred)","description":"The filed issue is the program the impl agent executes — refuse to hand it an unschematized one. Adopt upstream #3928 'agent work contracts' schema when it lands. Deferred until goose triage precision is proven.","status":"open","priority":3,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T19:58:15Z","created_by":"jeremylongshore","updated_at":"2026-07-31T19:58:15Z","labels":["agentic-ops","estate","github-bridge","schema"],"dependencies":[{"issue_id":"buzz-20l.10","depends_on_id":"buzz-20l","type":"parent-child","created_at":"2026-07-31T13:58:14Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-20l.10","depends_on_id":"buzz-20l.5","type":"blocks","created_at":"2026-07-31T13:58:39Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-20l.9","title":"Replay the dead reviewers' historical output as a golden eval set and MiniMax model-drift detector (deferred)","description":"Greptile/Gemini/CodeRabbit historical output on merged PRs = a free labeled dataset. Run goose/MiniMax over the same diffs to measure findings-recall + false-positive rate; use as a model-drift detector when MiniMax-M3 changes under us. Deferred until the triage lane is live.","status":"open","priority":3,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T19:58:14Z","created_by":"jeremylongshore","updated_at":"2026-07-31T19:58:14Z","labels":["agentic-ops","estate","eval","github-bridge"],"dependencies":[{"issue_id":"buzz-20l.9","depends_on_id":"buzz-20l","type":"parent-child","created_at":"2026-07-31T13:58:13Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-20l.9","depends_on_id":"buzz-20l.5","type":"blocks","created_at":"2026-07-31T13:58:39Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-b6z.4","title":"Verify and surface the buzz-audit hash-chain (tamper-evident audit log)","description":"The buzz-audit crate keeps a per-community SHA-256 hash-chain. Add a periodic chain-verify (like the estate ico audit verify) + surface a break to sys-incidents. AC: chain-verify runs green; a planted break alerts.","status":"open","priority":3,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:40:58Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:40:58Z","dependencies":[{"issue_id":"buzz-b6z.4","depends_on_id":"buzz-b6z","type":"parent-child","created_at":"2026-07-30T21:40:58Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-b6z.1","title":"Export relay OTel traces to SigNoz staging (set OTEL_EXPORTER_OTLP_ENDPOINT)","description":"The relay already attaches an OpenTelemetry exporter when OTEL_EXPORTER_OTLP_ENDPOINT is set (buzz-relay/src/main.rs). Point it at the estate SigNoz C8 gateway (+ OTEL_SERVICE_NAME=buzz-relay). AC: traces visible in SigNoz staging; prod untouched until verified on staging.","status":"open","priority":3,"issue_type":"feature","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:40:56Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:40:56Z","dependencies":[{"issue_id":"buzz-b6z.1","depends_on_id":"buzz-b6z","type":"parent-child","created_at":"2026-07-30T21:40:55Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-b6z.2","title":"Ship Buzz relay/agent logs off-box before they age out","description":"Docker json-file keeps only ~30MB (10m x3), so a crash's logs vanish. Ship to the estate log store (Loki/whatever the estate standardizes) or at minimum rotate into the borg backup. AC: relay logs survive a container recycle + are queryable.","status":"open","priority":3,"issue_type":"feature","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:40:56Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:40:56Z","dependencies":[{"issue_id":"buzz-b6z.2","depends_on_id":"buzz-b6z","type":"parent-child","created_at":"2026-07-30T21:40:56Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-1zr.4","title":"Wire the reference-vs-code citation-consistency check as a repeatable gate","description":"Promote the ad-hoc citation checker (106 citations -\u003e real fork file:line) into a committed script so BUZZ-SYSTEM-REFERENCE.md can't silently drift from block/buzz. AC: script committed + runnable; flags a broken citation.","status":"open","priority":3,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:39:35Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:39:35Z","dependencies":[{"issue_id":"buzz-1zr.4","depends_on_id":"buzz-yfe.1","type":"blocks","created_at":"2026-07-30T21:39:37Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-1zr.4","depends_on_id":"buzz-1zr","type":"parent-child","created_at":"2026-07-30T21:39:35Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-0ts.3","title":"Wire the sys-* channels to their estate sources","description":"incidents\u003c-prod incidents; health\u003c-liveness sweeps + labs health; backups\u003c-borg/off-site/restore-drill; deploys\u003c-deploy-wrapper events; automation\u003c-cron-failures + liveness digest. AC: each sys-* channel receives its real events.","status":"open","priority":3,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:29:20Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:29:20Z","dependencies":[{"issue_id":"buzz-0ts.3","depends_on_id":"buzz-0ts.2","type":"blocks","created_at":"2026-07-30T21:29:22Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-0ts.3","depends_on_id":"buzz-0ts","type":"parent-child","created_at":"2026-07-30T21:29:19Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0}
+{"_type":"issue","id":"buzz-0ts.4","title":"Soak, then retire Slack/notify/Moshi (keep the off-estate floor + Ezekiel email)","description":"After a soak proving Buzz alerts are reliable, retire notify.sh/notify-lib Slack paths + Moshi. KEEP: off-estate healthchecks.io + af_email_floor (survivability floor, must stay off-estate) + Ezekiel's blog posting emails. AC: Slack retired, floor intact.","status":"open","priority":3,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:29:20Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:29:20Z","dependencies":[{"issue_id":"buzz-0ts.4","depends_on_id":"buzz-0ts","type":"parent-child","created_at":"2026-07-30T21:29:20Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-0ts.4","depends_on_id":"buzz-0ts.3","type":"blocks","created_at":"2026-07-30T21:29:23Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-w92.6","title":"Add the topic feeds beyond the labs","description":"huggingface, openrouter, benchmarks, tooling, arxiv, mcp, funding, security, newsletters, ships (dogfood our own) -\u003e their *-wire channels. AC: each posts real items.","status":"open","priority":3,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:29:11Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:29:11Z","dependencies":[{"issue_id":"buzz-w92.6","depends_on_id":"buzz-w92","type":"parent-child","created_at":"2026-07-30T21:29:10Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-w92.6","depends_on_id":"buzz-w92.3","type":"blocks","created_at":"2026-07-30T21:29:15Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-w92.5","title":"Add the medium and hard provider feeds (RSSHub for scrape-only labs)","description":"Medium: Mistral, Together, Perplexity, Cohere. Hard (self-host RSSHub on the VPS): xAI, Meta, Moonshot/Kimi, Qwen -\u003e their *-wire. AC: RSSHub deployed; each feed posts.","status":"closed","priority":3,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:29:10Z","created_by":"jeremylongshore","updated_at":"2026-07-31T15:35:29Z","closed_at":"2026-07-31T15:35:29Z","close_reason":"Filled groq/meta/mistral/cohere/perplexity/xai + cleaner anthropic via Olshansk RSS mirrors (from perception repo) — no RSSHub needed. Remaining empty (deepseek/qwen/moonshot/minimax/benchmarks/funding/openrouter) have no mirror.","dependencies":[{"issue_id":"buzz-w92.5","depends_on_id":"buzz-w92","type":"parent-child","created_at":"2026-07-30T21:29:10Z","created_by":"jeremylongshore","metadata":"{}"},{"issue_id":"buzz-w92.5","depends_on_id":"buzz-w92.3","type":"blocks","created_at":"2026-07-30T21:29:15Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"buzz-ehv.1","title":"Decide and apply the Certified-Claude-Code-Architects channel","description":"The private CCA channel is owned by Jeremy's personal key (0ace65ad), so ops cannot delete/rename it without his key. Decide: keep as-is, rename (the coined 'Claude Code Certified Architect' has trademark risk — real credential is 'Claude Certified Architect (CCA)'), or retire. Owner-gated: needs Jeremy's key or his app action. AC: decision recorded + applied.","status":"open","priority":3,"issue_type":"task","owner":"jeremylongshore@users.noreply.github.com","created_at":"2026-07-31T03:27:10Z","created_by":"jeremylongshore","updated_at":"2026-07-31T03:27:10Z","dependencies":[{"issue_id":"buzz-ehv.1","depends_on_id":"buzz-ehv","type":"parent-child","created_at":"2026-07-30T21:27:09Z","created_by":"jeremylongshore","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
diff --git a/.env.example b/.env.example
index 3dc54856e7..b9bfcada0e 100644
--- a/.env.example
+++ b/.env.example
@@ -82,6 +82,19 @@ RELAY_URL=ws://localhost:3000
 # BUZZ_GIT_PACK_CACHE_MAX_BYTES=5368709120
 # BUZZ_GIT_PACK_CACHE_MAX_CONCURRENT_POPULATIONS=2
 
+# -----------------------------------------------------------------------------
+# S3-Compatible Object Storage (media + Git/CAS)
+# -----------------------------------------------------------------------------
+# The local MinIO container is reachable from host processes at localhost:9000.
+# Path style keeps the bucket in the URL path and is required by this local DNS
+# setup. Use `virtual` only when the provider requires bucket-as-subdomain URLs.
+BUZZ_S3_ENDPOINT=http://localhost:9000
+BUZZ_S3_ACCESS_KEY=buzz_dev
+BUZZ_S3_SECRET_KEY=buzz_dev_secret
+BUZZ_S3_BUCKET=buzz-media
+BUZZ_S3_REGION=us-east-1
+BUZZ_S3_ADDRESSING_STYLE=path
+
 # -----------------------------------------------------------------------------
 # Media Upload Admission
 # -----------------------------------------------------------------------------
diff --git a/.github/workflows/auto-tag-on-release-pr-merge.yml b/.github/workflows/auto-tag-on-release-pr-merge.yml
index db34fddc2c..3a090b3ebd 100644
--- a/.github/workflows/auto-tag-on-release-pr-merge.yml
+++ b/.github/workflows/auto-tag-on-release-pr-merge.yml
@@ -4,7 +4,7 @@ name: Auto-tag on Release PR Merge
 # prefix; the main chart lane also auto-detects a Chart.yaml version bump so
 # a chart feature PR can publish its own new version when merged:
 #
-#   version-bump/<v>   → tag v<v>        → release.yml (desktop app)
+#   version-bump/<v>   → tag desktop-v<v>        → release.yml (desktop app)
 #   relay-release/<v>  → tag relay-v<v>  → docker.yml (relay image)
 #   chart-release/<v>  → tag chart-v<v>  → helm-chart.yml (main helm chart)
 #   push-chart-release/<v> → tag push-chart-v<v> → push-gateway-helm-chart.yml
@@ -35,12 +35,17 @@ permissions:
 
 jobs:
   auto-tag:
+    permissions:
+      contents: read
+      pull-requests: read
+      checks: read
+      statuses: read
     if: >
       github.event.pull_request.merged == true &&
       github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ github.event.pull_request.merge_commit_sha }}
           fetch-depth: 0
@@ -57,7 +62,7 @@ jobs:
           case "$BRANCH" in
             version-bump/*)
               VERSION="${BRANCH#version-bump/}"
-              TAG_PREFIX="v" ;;
+              TAG_PREFIX="desktop-v" ;;
             relay-release/*)
               VERSION="${BRANCH#relay-release/}"
               TAG_PREFIX="relay-v" ;;
@@ -85,9 +90,33 @@ jobs:
           {
             echo "enabled=true"
             echo "tag=${TAG_PREFIX}${VERSION}"
+            if [[ "$TAG_PREFIX" == desktop-v ]]; then
+              echo "target_sha=${{ github.event.pull_request.merge_commit_sha }}"
+              echo "desktop=true"
+            else
+              echo "target_sha=$GITHUB_SHA"
+              echo "desktop=false"
+            fi
           } >> "$GITHUB_OUTPUT"
           echo "Tagging ${TAG_PREFIX}${VERSION}"
 
+
+      - name: Verify immutable reviewed desktop candidate
+        if: steps.release.outputs.desktop == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.release.outputs.tag }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          PR_HEAD_REF: ${{ github.event.pull_request.head.ref }}
+          PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
+          PR_HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+          MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
+        run: |
+          VERSION="${VERSION#desktop-v}"
+          export VERSION
+          scripts/verify-desktop-release-merge.sh
+
       - name: Create release tagger token
         if: steps.release.outputs.enabled == 'true'
         id: release-tagger
@@ -102,21 +131,22 @@ jobs:
         env:
           GH_TOKEN: ${{ steps.release-tagger.outputs.token }}
           TAG: ${{ steps.release.outputs.tag }}
+          TARGET_SHA: ${{ steps.release.outputs.target_sha }}
         run: |
           set -euo pipefail
           # Check gh's exit status, not its output. A missing ref returns a 404
           # JSON body on stdout, which must not be mistaken for an existing tag.
           if gh api "repos/$GITHUB_REPOSITORY/git/ref/tags/$TAG" --silent 2>/dev/null; then
             EXISTING_SHA="$(gh api "repos/$GITHUB_REPOSITORY/commits/$TAG" --jq .sha)"
-            if [ "$EXISTING_SHA" = "$GITHUB_SHA" ]; then
-              echo "Tag $TAG already exists at $GITHUB_SHA — skipping tag creation"
+            if [ "$EXISTING_SHA" = "$TARGET_SHA" ]; then
+              echo "Tag $TAG already exists at $TARGET_SHA — skipping tag creation"
               exit 0
             else
-              echo "::error::Tag $TAG already exists at $EXISTING_SHA (expected $GITHUB_SHA)"
+              echo "::error::Tag $TAG already exists at $EXISTING_SHA (expected $TARGET_SHA)"
               exit 1
             fi
           fi
           gh api --method POST "repos/$GITHUB_REPOSITORY/git/refs" \
             -f ref="refs/tags/$TAG" \
-            -f sha="$GITHUB_SHA" \
+            -f sha="$TARGET_SHA" \
             --silent
diff --git a/.github/workflows/benchmark-harbor.yml b/.github/workflows/benchmark-harbor.yml
index 31efe933c5..6024f00575 100644
--- a/.github/workflows/benchmark-harbor.yml
+++ b/.github/workflows/benchmark-harbor.yml
@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: "3.12"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d4826d985f..60507182d5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -28,7 +28,7 @@ jobs:
       web: ${{ steps.filter.outputs.web }}
       mobile: ${{ steps.filter.outputs.mobile }}
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 2
       - uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4.0.2
@@ -76,6 +76,8 @@ jobs:
               - '.github/workflows/ci.yml'
       - name: Release workflow source contract
         run: scripts/test-release-ref-contract.sh
+      - name: Desktop release candidate contract
+        run: scripts/test-desktop-release-candidate.sh
       - name: Mobile release contract
         run: |
           scripts/test-mobile-release-contract.sh
@@ -94,7 +96,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
@@ -115,7 +117,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - uses: rui314/setup-mold@9c9c13bf4c3f1adef0cc596abc155580bcb04444 # v1
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
@@ -137,7 +139,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 2
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
@@ -233,7 +235,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - name: Get pnpm store directory
         id: pnpm-cache
@@ -316,7 +318,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       # Reuse the relay binaries and backend test archive when none of their
       # inputs changed (desktop-only PRs hit this every time). The key covers
@@ -389,7 +391,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - name: Start integration services
         run: |
@@ -578,7 +580,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - name: Install cargo-nextest
         uses: taiki-e/install-action@0fd46367812ee04360509b4169d9f659d6892bb2 # v2.79.15
@@ -690,6 +692,18 @@ jobs:
             --run-ignored ignored-only
         env:
           DATABASE_URL: postgres://buzz:${{ env.BUZZ_TEST_POSTGRES_PASSWORD }}@localhost:5432/buzz
+      - name: Workspace profile (kind:9033) gate tests
+        # Call-site integration for the 9033 authorization gate: open relay
+        # rosterless/steward transitions and the closed-relay admin/owner rule,
+        # against real Postgres. #[ignore]d in the default suite, selected
+        # explicitly here — see handlers::relay_admin::tests.
+        run: |
+          cargo nextest run \
+            --archive-file target/ci/backend-integration-tests.tar.zst \
+            -E 'package(buzz-relay) and test(/handlers::relay_admin::tests/)' \
+            --run-ignored ignored-only
+        env:
+          DATABASE_URL: postgres://buzz:${{ env.BUZZ_TEST_POSTGRES_PASSWORD }}@localhost:5432/buzz
       - name: NIP-ER reminder e2e
         # Feature e2e for NIP-ER (Event Reminders, kind:30300): write-path
         # validation, author-only read filtering, and scheduler delivery against
@@ -702,6 +716,17 @@ jobs:
             --run-ignored ignored-only
         env:
           RELAY_URL: ws://localhost:3000
+      - name: NIP-MP coordinate deletion guard
+        # Verifies the never-delete-newer invariant of soft_delete_by_coordinate:
+        # a stale tombstone (created_at earlier than the live head) spares that
+        # head, and an equal-timestamp tombstone deletes it.
+        run: |
+          cargo nextest run \
+            --archive-file target/ci/backend-integration-tests.tar.zst \
+            -E 'package(buzz-db) and test(coordinate_delete_spares_head_newer_than_the_deletion)' \
+            --run-ignored ignored-only
+        env:
+          DATABASE_URL: postgres://buzz:${{ env.BUZZ_TEST_POSTGRES_PASSWORD }}@localhost:5432/buzz
       - name: Upload relay log
         if: failure()
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
@@ -719,7 +744,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
@@ -737,7 +762,7 @@ jobs:
           ./scripts/start-relay-for-tests.sh --no-build
       - name: Relay E2E tests
         run: |
-          cargo test -p buzz-test-client --test e2e_persona --test e2e_nostr_interop -- --ignored --nocapture
+          cargo test -p buzz-test-client --test e2e_persona --test e2e_team_catalog --test e2e_nostr_interop --test e2e_project -- --ignored --nocapture
           cargo test -p buzz-test-client --test e2e_relay invite -- --ignored --nocapture
           cargo test -p buzz-test-client --test e2e_relay nip43_membership_snapshots_are_rejected -- --ignored --nocapture
         env:
@@ -760,7 +785,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 2
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
@@ -795,7 +820,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 2
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
@@ -856,7 +881,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - name: Dependency policy
         run: cargo-deny check
@@ -868,7 +893,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - name: Check for dead API token references in client code
         run: |
           # Fail if dead API token patterns reappear in desktop, mobile, docs, or config.
@@ -897,7 +922,7 @@ jobs:
           - x86_64-unknown-linux-musl
           - aarch64-unknown-linux-musl
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
@@ -934,7 +959,7 @@ jobs:
     env:
       TARGET: x86_64-pc-windows-msvc
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       # MSVC needs windows.h (aws-lc-sys et al.), so this runs on a real Windows
       # runner — hermit, used by the Linux jobs, does not provide MSVC. The
       # toolchain (1.95.0 + clippy via profile = default) comes from the
@@ -1015,7 +1040,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
@@ -1029,6 +1054,7 @@ jobs:
           mkdir -p desktop/src-tauri/binaries
           touch "desktop/src-tauri/binaries/buzz-acp-$TARGET"
           touch "desktop/src-tauri/binaries/buzz-agent-$TARGET"
+          touch "desktop/src-tauri/binaries/buzz-backend-kubernetes-$TARGET"
           touch "desktop/src-tauri/binaries/buzz-dev-mcp-$TARGET"
           touch "desktop/src-tauri/binaries/git-credential-nostr-$TARGET"
           touch "desktop/src-tauri/binaries/buzz-$TARGET"
diff --git a/.github/workflows/desktop-release-candidate.yml b/.github/workflows/desktop-release-candidate.yml
new file mode 100644
index 0000000000..eddebea685
--- /dev/null
+++ b/.github/workflows/desktop-release-candidate.yml
@@ -0,0 +1,26 @@
+name: Desktop Release Candidate
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Desktop Release Candidate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Validate immutable desktop candidate
+        if: startsWith(github.event.pull_request.head.ref, 'version-bump/')
+        env:
+          VERSION: ${{ github.event.pull_request.head.ref }}
+        run: |
+          VERSION="${VERSION#version-bump/}"
+          scripts/desktop_release.py validate --candidate HEAD --version "$VERSION" --repo "$GITHUB_REPOSITORY"
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 52f21b28bc..564cd74e9d 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -101,7 +101,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -359,7 +359,7 @@ jobs:
             arch: arm64
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
diff --git a/.github/workflows/helm-chart.yml b/.github/workflows/helm-chart.yml
index e3d443d9f3..7118d16708 100644
--- a/.github/workflows/helm-chart.yml
+++ b/.github/workflows/helm-chart.yml
@@ -59,7 +59,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           # On chart-tag rescue dispatch, lint/render the tagged commit that the
           # publish job will package, not whatever `main` is when the dispatch
@@ -119,7 +119,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           fetch-depth: 0
 
@@ -166,7 +166,7 @@ jobs:
       packages: write    # push the chart to GHCR
     steps:
       - name: Checkout
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           # On the rescue dispatch, build the tagged commit (github.ref is
           # `main` there); on a tag push, the default ref is already the tag.
diff --git a/.github/workflows/linux-canary.yml b/.github/workflows/linux-canary.yml
index 18d476e400..1664878770 100644
--- a/.github/workflows/linux-canary.yml
+++ b/.github/workflows/linux-canary.yml
@@ -21,7 +21,7 @@ jobs:
     name: Build Linux canary
     if: github.repository == 'block/buzz'
     runs-on: ubuntu-latest
-    container: ubuntu:22.04@sha256:0e0a0fc6d18feda9db1590da249ac93e8d5abfea8f4c3c0c849ce512b5ef8982
+    container: ubuntu:24.04@sha256:4fbb8e6a8395de5a7550b33509421a2bafbc0aab6c06ba2cef9ebffbc7092d90
     timeout-minutes: 60
     permissions:
       contents: read
@@ -166,7 +166,7 @@ jobs:
 
       - name: Build sidecars
         run: |
-          cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
+          cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
           ./scripts/bundle-sidecars.sh
 
       - name: Build Linux Tauri app
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index c613924e57..02011ad386 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,14 +1,13 @@
 name: Release
 
+concurrency:
+  group: desktop-release-${{ github.ref }}
+  cancel-in-progress: false
+
 on:
   push:
     tags:
-      - 'v[0-9]*'
-  workflow_dispatch:
-    inputs:
-      version:
-        description: "Semver version matching the v-prefixed dispatch tag"
-        required: true
+      - 'desktop-v[0-9]*'
 
 jobs:
   # Shared setup: verify the immutable release tag, determine the version, and
@@ -19,23 +18,14 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     permissions:
-      contents: write
+      contents: read
     outputs:
       version: ${{ steps.version.outputs.version }}
       source_sha: ${{ steps.source.outputs.source_sha }}
     steps:
       - name: Determine version
         id: version
-        env:
-          EVENT_NAME: ${{ github.event_name }}
-          INPUT_VERSION: ${{ inputs.version }}
-        run: |
-          if [[ "$EVENT_NAME" == "push" ]]; then
-            VERSION="${GITHUB_REF_NAME#v}"
-          else
-            VERSION="$INPUT_VERSION"
-          fi
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+        run: echo "version=${GITHUB_REF_NAME#desktop-v}" >> "$GITHUB_OUTPUT"
 
       - name: Validate version
         env:
@@ -46,7 +36,7 @@ jobs:
             exit 1
           fi
 
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -56,42 +46,9 @@ jobs:
         env:
           VERSION: ${{ steps.version.outputs.version }}
         run: |
-          scripts/verify-release-ref.sh v "$VERSION"
+          scripts/verify-release-ref.sh desktop-v "$VERSION"
           echo "source_sha=$(git rev-parse 'HEAD^{commit}')" >> "$GITHUB_OUTPUT"
 
-      - name: Create versioned GitHub release
-        env:
-          VERSION: ${{ steps.version.outputs.version }}
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          RELEASE_SHA=$(git rev-parse HEAD)
-          NOTES=""
-          if [[ -f CHANGELOG.md ]]; then
-            NOTES=$(awk "/^## v${VERSION}\$/{found=1; next} found && /^## v/{exit} found && !/^\$/" CHANGELOG.md)
-          fi
-          if [[ -z "$NOTES" ]]; then
-            NOTES="Buzz Desktop v${VERSION}"
-          fi
-          PRERELEASE_FLAGS=()
-          if [[ "$VERSION" =~ -(test|alpha|beta|rc)([.-]|$) ]]; then
-            PRERELEASE_FLAGS=(--prerelease --latest=false)
-          fi
-          gh release create "v${VERSION}" \
-            --target "$RELEASE_SHA" \
-            --title "Buzz Desktop v${VERSION}" \
-            --notes "$NOTES" \
-            "${PRERELEASE_FLAGS[@]}"
-
-      - name: Create rolling auto-update release
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          gh release create buzz-desktop-latest \
-            --prerelease \
-            --title "Buzz Desktop Auto-Update" \
-            --notes "Rolling release for the Tauri auto-updater. Do not download manually — use the versioned release instead." \
-            2>/dev/null || true
-
   release:
     name: Release
     if: github.repository == 'block/buzz'
@@ -99,7 +56,7 @@ jobs:
     needs: setup
     timeout-minutes: 60
     permissions:
-      contents: write
+      contents: read
       id-token: write # required by block/apple-codesign-action for OIDC
     outputs:
       archive_name: ${{ steps.artifacts.outputs.archive_name }}
@@ -107,14 +64,14 @@ jobs:
     env:
       VERSION: ${{ needs.setup.outputs.version }}
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ needs.setup.outputs.source_sha }}
           fetch-depth: 0
           persist-credentials: false
 
       - name: Verify tag-bound release source
-        run: scripts/verify-release-ref.sh v "$VERSION"
+        run: scripts/verify-release-ref.sh desktop-v "$VERSION"
 
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
 
@@ -134,7 +91,7 @@ jobs:
 
       - name: Build sidecars
         run: |
-          cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
+          cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
           ./scripts/bundle-sidecars.sh
 
       # Mesh rev derived from Cargo.lock (no lockstep edit on dep bump); cache key tracks it.
@@ -272,13 +229,19 @@ jobs:
           fi
           echo "dmg=$DMG" >> "$GITHUB_OUTPUT"
 
-          # Find the updater .tar.gz and .sig
+          # Find the updater .tar.gz and .sig. Give each architecture a unique
+          # release basename before artifacts are merged by the final writer.
           ARCHIVE=$(find "$BUNDLE_DIR/macos" -name '*.tar.gz' ! -name '*.sig' -type f | head -1)
           SIG="${ARCHIVE}.sig"
           if [[ -z "$ARCHIVE" || ! -f "$SIG" ]]; then
             echo "::error::Updater archive or signature not found in $BUNDLE_DIR/macos"
             exit 1
           fi
+          RENAMED="$(dirname "$ARCHIVE")/Buzz_${VERSION}_aarch64.app.tar.gz"
+          mv "$ARCHIVE" "$RENAMED"
+          mv "$SIG" "${RENAMED}.sig"
+          ARCHIVE="$RENAMED"
+          SIG="${RENAMED}.sig"
           echo "archive=$ARCHIVE" >> "$GITHUB_OUTPUT"
           echo "archive_name=$(basename "$ARCHIVE")" >> "$GITHUB_OUTPUT"
           echo "sig=$SIG" >> "$GITHUB_OUTPUT"
@@ -289,23 +252,15 @@ jobs:
         env:
           SIG_PATH: ${{ steps.artifacts.outputs.sig }}
 
-      - name: Upload arm64 DMG to versioned GitHub release
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DMG_PATH: ${{ steps.artifacts.outputs.dmg }}
-        run: gh release upload "v${VERSION}" "$DMG_PATH" --clobber
-
-      - name: Upload updater archive to rolling release
-        if: github.ref == format('refs/tags/v{0}', needs.setup.outputs.version)
-        run: |
-          gh release upload buzz-desktop-latest \
-            "$ARCHIVE_PATH" \
-            "$SIG_PATH" \
-            --clobber
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          ARCHIVE_PATH: ${{ steps.artifacts.outputs.archive }}
-          SIG_PATH: ${{ steps.artifacts.outputs.sig }}
+      - name: Stage Apple Silicon release artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: desktop-release-macos-arm64
+          if-no-files-found: error
+          path: |
+            ${{ steps.artifacts.outputs.dmg }}
+            ${{ steps.artifacts.outputs.archive }}
+            ${{ steps.artifacts.outputs.sig }}
 
   release-macos-x64:
     name: Release macOS (Intel)
@@ -314,7 +269,7 @@ jobs:
     needs: setup
     timeout-minutes: 60
     permissions:
-      contents: write
+      contents: read
       id-token: write # required by block/apple-codesign-action for OIDC
     outputs:
       archive_name: ${{ steps.artifacts.outputs.archive_name }}
@@ -323,14 +278,14 @@ jobs:
       VERSION: ${{ needs.setup.outputs.version }}
       TARGET: x86_64-apple-darwin
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ needs.setup.outputs.source_sha }}
           fetch-depth: 0
           persist-credentials: false
 
       - name: Verify tag-bound release source
-        run: scripts/verify-release-ref.sh v "$VERSION"
+        run: scripts/verify-release-ref.sh desktop-v "$VERSION"
 
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
 
@@ -353,7 +308,7 @@ jobs:
 
       - name: Build sidecars
         run: |
-          cargo build --release --target "$TARGET" -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
+          cargo build --release --target "$TARGET" -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
           ./scripts/bundle-sidecars.sh "$TARGET"
 
       - name: Build unsigned Tauri app
@@ -443,6 +398,11 @@ jobs:
             echo "::error::Updater archive or signature not found in $BUNDLE_DIR/macos"
             exit 1
           fi
+          RENAMED="$(dirname "$ARCHIVE")/Buzz_${VERSION}_x64.app.tar.gz"
+          mv "$ARCHIVE" "$RENAMED"
+          mv "$SIG" "${RENAMED}.sig"
+          ARCHIVE="$RENAMED"
+          SIG="${RENAMED}.sig"
           echo "archive=$ARCHIVE" >> "$GITHUB_OUTPUT"
           echo "archive_name=$(basename "$ARCHIVE")" >> "$GITHUB_OUTPUT"
           echo "sig=$SIG" >> "$GITHUB_OUTPUT"
@@ -453,34 +413,26 @@ jobs:
         env:
           SIG_PATH: ${{ steps.artifacts.outputs.sig }}
 
-      - name: Upload Intel DMG to versioned GitHub release
-        run: gh release upload "v${VERSION}" "$DMG_PATH" --clobber
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DMG_PATH: ${{ steps.unsigned.outputs.dmg }}
-
-      - name: Upload updater archive to rolling release
-        if: github.ref == format('refs/tags/v{0}', needs.setup.outputs.version)
-        run: |
-          gh release upload buzz-desktop-latest \
-            "$ARCHIVE_PATH" \
-            "$SIG_PATH" \
-            --clobber
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          ARCHIVE_PATH: ${{ steps.artifacts.outputs.archive }}
-          SIG_PATH: ${{ steps.artifacts.outputs.sig }}
+      - name: Stage Intel macOS release artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: desktop-release-macos-x64
+          if-no-files-found: error
+          path: |
+            ${{ steps.unsigned.outputs.dmg }}
+            ${{ steps.artifacts.outputs.archive }}
+            ${{ steps.artifacts.outputs.sig }}
 
   release-linux:
     name: Release Linux
     if: github.repository == 'block/buzz'
     runs-on: ubuntu-latest
     # Digest-pinned like the SHA-pinned actions below; Renovate keeps it fresh.
-    container: ubuntu:22.04@sha256:0e0a0fc6d18feda9db1590da249ac93e8d5abfea8f4c3c0c849ce512b5ef8982
+    container: ubuntu:24.04@sha256:4fbb8e6a8395de5a7550b33509421a2bafbc0aab6c06ba2cef9ebffbc7092d90
     needs: setup
     timeout-minutes: 60
     permissions:
-      contents: write
+      contents: read
     env:
       # AppImage tools (linuxdeploy, appimagetool) are themselves AppImages.
       # Containers lack FUSE, so we must use the extract-and-run fallback.
@@ -498,7 +450,7 @@ jobs:
         env:
           DEBIAN_FRONTEND: noninteractive
         run: |
-          # Must run first: bare ubuntu:22.04 ships without curl, wget, git, or
+          # Must run first: bare ubuntu:24.04 ships without curl, wget, git, or
           # ca-certificates. activate-hermit bootstraps via curl+HTTPS (needs
           # both), and actions/checkout falls back to a REST tarball without git.
           # Running as root — no sudo needed.
@@ -543,7 +495,7 @@ jobs:
           apt-get update
           apt-get install -y --no-install-recommends gh
 
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ needs.setup.outputs.source_sha }}
           fetch-depth: 0
@@ -555,7 +507,7 @@ jobs:
       - name: Verify tag-bound release source
         env:
           VERSION: ${{ needs.setup.outputs.version }}
-        run: scripts/verify-release-ref.sh v "$VERSION"
+        run: scripts/verify-release-ref.sh desktop-v "$VERSION"
 
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
 
@@ -611,7 +563,7 @@ jobs:
 
       - name: Build sidecars
         run: |
-          cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
+          cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
           ./scripts/bundle-sidecars.sh
 
       - name: Generate release config
@@ -689,29 +641,16 @@ jobs:
           SIG_PATH: ${{ steps.linux-artifacts.outputs.sig }}
 
       # NOTE: .deb is NOT auto-updatable (Tauri updater constraint — only AppImage supports it on Linux)
-      - name: Upload Linux artifacts to versioned GitHub release
-        env:
-          VERSION: ${{ needs.setup.outputs.version }}
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DEB_PATH: ${{ steps.linux-artifacts.outputs.deb }}
-          APPIMAGE_PATH: ${{ steps.linux-artifacts.outputs.appimage }}
-        run: |
-          gh release upload "v$VERSION" \
-            "$DEB_PATH" \
-            "$APPIMAGE_PATH" \
-            --clobber
-
-      - name: Upload updater archive to rolling release
-        if: github.ref == format('refs/tags/v{0}', needs.setup.outputs.version)
-        run: |
-          gh release upload buzz-desktop-latest \
-            "$ARCHIVE_PATH" \
-            "$SIG_PATH" \
-            --clobber
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          ARCHIVE_PATH: ${{ steps.linux-artifacts.outputs.archive }}
-          SIG_PATH: ${{ steps.linux-artifacts.outputs.sig }}
+      - name: Stage Linux release artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: desktop-release-linux-x64
+          if-no-files-found: error
+          path: |
+            ${{ steps.linux-artifacts.outputs.deb }}
+            ${{ steps.linux-artifacts.outputs.appimage }}
+            ${{ steps.linux-artifacts.outputs.archive }}
+            ${{ steps.linux-artifacts.outputs.sig }}
 
   release-windows:
     name: Release Windows
@@ -719,7 +658,7 @@ jobs:
     needs: setup
     timeout-minutes: 60
     permissions:
-      contents: write
+      contents: read
     outputs:
       archive_name: ${{ steps.artifacts.outputs.archive_name }}
       sig: ${{ steps.read-sig.outputs.sig }}
@@ -727,7 +666,7 @@ jobs:
       VERSION: ${{ needs.setup.outputs.version }}
       TARGET: x86_64-pc-windows-msvc
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ needs.setup.outputs.source_sha }}
           fetch-depth: 0
@@ -735,7 +674,7 @@ jobs:
 
       - name: Verify tag-bound release source
         shell: bash
-        run: scripts/verify-release-ref.sh v "$VERSION"
+        run: scripts/verify-release-ref.sh desktop-v "$VERSION"
 
       - uses: dtolnay/rust-toolchain@e081816240890017053eacbb1bdf337761dc5582 # 1.95.0
         with:
@@ -745,7 +684,7 @@ jobs:
         with:
           node-version: 24.14.1
           # Disable dependency caching: a writable cache in this release workflow
-          # (contents: write, feeds a signed installer) is a poisoning vector. pnpm
+          # (contents: read, feeds a signed installer) is a poisoning vector. pnpm
           # install runs uncached below.
           package-manager-cache: false
 
@@ -827,25 +766,14 @@ jobs:
         env:
           SIG_PATH: ${{ steps.artifacts.outputs.sig }}
 
-      - name: Upload Windows installer to versioned GitHub release
-        shell: bash
-        run: gh release upload "v${VERSION}" "$EXE_PATH" --clobber
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          EXE_PATH: ${{ steps.artifacts.outputs.exe }}
-
-      - name: Upload updater archive to rolling release
-        if: github.ref == format('refs/tags/v{0}', needs.setup.outputs.version)
-        shell: bash
-        run: |
-          gh release upload buzz-desktop-latest \
-            "$ARCHIVE_PATH" \
-            "$SIG_PATH" \
-            --clobber
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          ARCHIVE_PATH: ${{ steps.artifacts.outputs.archive }}
-          SIG_PATH: ${{ steps.artifacts.outputs.sig }}
+      - name: Stage Windows release artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: desktop-release-windows-x64
+          if-no-files-found: error
+          path: |
+            ${{ steps.artifacts.outputs.exe }}
+            ${{ steps.artifacts.outputs.sig }}
 
   assemble-manifest:
     name: Assemble multi-platform latest.json
@@ -853,7 +781,11 @@ jobs:
     if: |
       always() &&
       needs.setup.result == 'success' &&
-      github.ref == format('refs/tags/v{0}', needs.setup.outputs.version)
+      needs.release.result == 'success' &&
+      needs.release-macos-x64.result == 'success' &&
+      needs.release-linux.result == 'success' &&
+      needs.release-windows.result == 'success' &&
+      github.ref == format('refs/tags/desktop-v{0}', needs.setup.outputs.version)
     runs-on: ubuntu-latest
     needs: [setup, release, release-macos-x64, release-linux, release-windows]
     timeout-minutes: 10
@@ -863,14 +795,33 @@ jobs:
       VERSION: ${{ needs.setup.outputs.version }}
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ needs.setup.outputs.source_sha }}
           fetch-depth: 0
           persist-credentials: false
 
       - name: Verify tag-bound release source
-        run: scripts/verify-release-ref.sh v "$VERSION"
+        run: scripts/verify-release-ref.sh desktop-v "$VERSION"
+
+      - name: Download staged release artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: desktop-release-*
+          path: staged-by-platform
+
+      - name: Flatten staged artifacts without basename collisions
+        run: |
+          set -euo pipefail
+          mkdir staged
+          while IFS= read -r -d '' file; do
+            name="$(basename "$file")"
+            [[ ! -e "staged/$name" ]] || {
+              echo "::error::release artifact basename collision: $name"
+              exit 1
+            }
+            cp "$file" "staged/$name"
+          done < <(find staged-by-platform -type f -print0)
 
       - name: Write signature files
         env:
@@ -899,7 +850,7 @@ jobs:
           write_sig "$RESULT_LINUX" linux-x86_64 "$SIG_LINUX"
           write_sig "$RESULT_WIN" windows-x86_64 "$SIG_WIN"
 
-      - name: Verify archive URLs are accessible
+      - name: Verify draft release has every updater archive
         env:
           RESULT_ARM64: ${{ needs.release.result }}
           RESULT_X64: ${{ needs.release-macos-x64.result }}
@@ -911,39 +862,19 @@ jobs:
           ARCHIVE_WIN: ${{ needs.release-windows.outputs.archive_name }}
         run: |
           set -euo pipefail
-          BASE="https://github.com/block/buzz/releases/download/buzz-desktop-latest"
-          ARCHIVES=()
-
-          add_archive() {
-            local result="$1" platform="$2" archive="$3"
-            if [[ "$result" == "success" ]]; then
-              [[ -n "$archive" ]] || { echo "::error::Missing archive name for successful platform: $platform"; exit 1; }
-              ARCHIVES+=("$archive")
-            fi
-          }
-
-          add_archive "$RESULT_ARM64" darwin-aarch64 "$ARCHIVE_ARM64"
-          add_archive "$RESULT_X64" darwin-x86_64 "$ARCHIVE_X64"
-          add_archive "$RESULT_LINUX" linux-x86_64 "$ARCHIVE_LINUX"
-          add_archive "$RESULT_WIN" windows-x86_64 "$ARCHIVE_WIN"
-
-          for name in "${ARCHIVES[@]}"; do
-            echo "Checking $BASE/$name ..."
-            success=false
-            for attempt in 1 2 3; do
-              if curl -fsI "$BASE/$name" > /dev/null 2>&1; then
-                success=true
-                break
-              fi
-              echo "Attempt $attempt failed for $name, retrying in 10s..."
-              sleep 10
-            done
-            if [ "$success" != "true" ]; then
-              echo "::error::Archive not accessible after 3 attempts: $BASE/$name"
-              exit 1
+          assets=$(find staged -type f -exec basename {} \;)
+          for spec in \
+            "$RESULT_ARM64:$ARCHIVE_ARM64" \
+            "$RESULT_X64:$ARCHIVE_X64" \
+            "$RESULT_LINUX:$ARCHIVE_LINUX" \
+            "$RESULT_WIN:$ARCHIVE_WIN"; do
+            result="${spec%%:*}"
+            archive="${spec#*:}"
+            if [[ "$result" == success ]]; then
+              [[ -n "$archive" ]] || { echo "::error::successful platform has no archive"; exit 1; }
+              grep -Fxq "$archive" <<<"$assets" || { echo "::error::draft release missing $archive"; exit 1; }
             fi
           done
-          echo "All archive URLs verified."
 
       - name: Generate unified latest.json
         env:
@@ -957,7 +888,7 @@ jobs:
           ARCHIVE_WIN: ${{ needs.release-windows.outputs.archive_name }}
         run: |
           set -euo pipefail
-          BASE="https://github.com/block/buzz/releases/download/buzz-desktop-latest"
+          BASE="https://github.com/block/buzz/releases/download/desktop-v${VERSION}"
           TRIPLES=()
 
           add_triple() {
@@ -977,6 +908,45 @@ jobs:
           bash desktop/scripts/generate-oss-latest-json.sh "$VERSION" "${TRIPLES[@]}" > latest.json
           cat latest.json
 
-      - name: Upload latest.json to rolling release
+      - name: Create or verify versioned draft
         run: |
-          gh release upload buzz-desktop-latest latest.json --clobber
+          set -euo pipefail
+          NOTES_FILE="${RUNNER_TEMP}/release-notes.md"
+          awk "/^## v${VERSION}\$/{found=1; next} found && /^## v/{exit} found" CHANGELOG.md > "$NOTES_FILE"
+          [[ -s "$NOTES_FILE" ]] || { echo "::error::missing non-empty changelog block for v${VERSION}"; exit 1; }
+          PRERELEASE_FLAGS=()
+          if [[ "$VERSION" == *-* ]]; then
+            PRERELEASE_FLAGS=(--prerelease --latest=false)
+          fi
+          if gh release view "desktop-v${VERSION}" >/dev/null 2>&1; then
+            EXISTING_SHA=$(gh release view "desktop-v${VERSION}" --json targetCommitish --jq .targetCommitish)
+            IS_DRAFT=$(gh release view "desktop-v${VERSION}" --json isDraft --jq .isDraft)
+            [[ "$EXISTING_SHA" == "${{ needs.setup.outputs.source_sha }}" ]] || {
+              echo "::error::existing release targets $EXISTING_SHA, not the immutable source"; exit 1;
+            }
+            if [[ "$IS_DRAFT" != true ]]; then
+              echo "already_published=true" >> "$GITHUB_ENV"
+            fi
+          else
+            gh release create "desktop-v${VERSION}" \
+              --draft \
+              --target "${{ needs.setup.outputs.source_sha }}" \
+              --title "Buzz Desktop v${VERSION}" \
+              --notes-file "$NOTES_FILE" \
+              "${PRERELEASE_FLAGS[@]}"
+          fi
+
+      - name: Upload complete artifact set to versioned draft
+        if: env.already_published != 'true'
+        run: |
+          mapfile -t files < <(find staged -type f -print)
+          [[ "${#files[@]}" -gt 0 ]] || { echo "::error::no staged release artifacts"; exit 1; }
+          gh release upload "desktop-v${VERSION}" "${files[@]}" --clobber
+
+      - name: Publish complete versioned release
+        if: env.already_published != 'true'
+        run: gh release edit "desktop-v${VERSION}" --draft=false
+
+      - name: Upload latest.json to rolling release last
+        if: ${{ !contains(needs.setup.outputs.version, '-') }}
+        run: gh release upload buzz-desktop-latest latest.json --clobber
diff --git a/.github/workflows/signed-macos-canary.yml b/.github/workflows/signed-macos-canary.yml
index fb0656028a..0a3a513eef 100644
--- a/.github/workflows/signed-macos-canary.yml
+++ b/.github/workflows/signed-macos-canary.yml
@@ -93,7 +93,7 @@ jobs:
 
       - name: Build sidecars
         run: |
-          cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
+          cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
           ./scripts/bundle-sidecars.sh
 
       # Mesh rev derived from Cargo.lock (no lockstep edit on dep bump); cache key tracks it.
diff --git a/.github/workflows/sprig-image.yml b/.github/workflows/sprig-image.yml
new file mode 100644
index 0000000000..5d5e12ae0c
--- /dev/null
+++ b/.github/workflows/sprig-image.yml
@@ -0,0 +1,233 @@
+name: Sprig image
+
+# Builds and publishes the public agent container image as
+# ghcr.io/block/buzz-sprig — the digest-pinned box the Kubernetes backend
+# deploys agents into (see Dockerfile.sprig and docs/remote-agents.md).
+#
+# Strategy mirrors docker.yml (the relay image): each architecture builds on
+# its native runner, pushes to GHCR by digest, then a merge job stitches the
+# per-arch digests into one multi-arch manifest and attests provenance.
+# No QEMU emulation.
+#
+# Triggers:
+#   - push to main (paths-filtered) → :main + :sha-<7>
+#   - tag sprig-v*                  → semver family (shared with sprig.yml's
+#                                     binary release — one tag versions both)
+#   - pull_request (paths-filtered) → build only, no push
+#   - workflow_dispatch             → manual publish at the current ref
+#
+# NOTE: the first push creates the GHCR package PRIVATE by default. An org
+# admin must flip ghcr.io/block/buzz-sprig to public once (Package settings →
+# Change visibility). Subsequent pushes keep the visibility.
+
+on:
+  push:
+    branches: [main]
+    tags: ["sprig-v[0-9]*"]
+    paths:
+      - "Dockerfile.sprig"
+      - "scripts/sprig-entrypoint.sh"
+      - ".github/workflows/sprig-image.yml"
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "rust-toolchain.toml"
+      - "crates/**"
+  pull_request:
+    paths:
+      - "Dockerfile.sprig"
+      - "scripts/sprig-entrypoint.sh"
+      - ".github/workflows/sprig-image.yml"
+  workflow_dispatch: {}
+
+concurrency:
+  group: sprig-image-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref_type == 'branch' && github.event_name == 'pull_request' }}
+
+permissions: {}
+
+env:
+  # Single source of truth for the image name; override with the
+  # GHCR_SPRIG_IMAGE repo variable (same pattern as docker.yml).
+  IMAGE_NAME: ${{ vars.GHCR_SPRIG_IMAGE != '' && vars.GHCR_SPRIG_IMAGE || 'ghcr.io/block/buzz-sprig' }}
+
+jobs:
+  build:
+    name: Build (${{ matrix.platform }})
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 60
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+      attestations: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux/amd64
+            runner: ubuntu-24.04
+            arch: amd64
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+            arch: arm64
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+        with:
+          persist-credentials: false
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
+        with:
+          # Same OOM cap as docker.yml — Rust compiles blow the 7GB runner
+          # at buildkit's default parallelism of 4.
+          buildkitd-config-inline: |
+            [worker.oci]
+              max-parallelism = 2
+
+      - name: Log in to GHCR
+        if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee  # v4.2.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9  # v6.1.0
+        with:
+          images: ${{ env.IMAGE_NAME }}
+          # match=^sprig-v(.*)$ strips the tag prefix for the semver parser,
+          # exactly as docker.yml does for relay-v. :latest comes from
+          # flavor.latest=auto — stable semver only, never main pushes.
+          tags: |
+            type=ref,event=branch
+            type=sha,prefix=sha-,format=short
+            type=semver,pattern={{version}},match=^sprig-v(.*)$
+            type=semver,pattern={{major}}.{{minor}},match=^sprig-v(.*)$
+          labels: |
+            org.opencontainers.image.title=Buzz Sprig
+            org.opencontainers.image.description=Agent runtime image for Buzz remote agents (buzz-acp multicall + git + curl)
+            org.opencontainers.image.licenses=Apache-2.0
+
+      - name: Build and push by digest
+        id: build
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf  # v7.2.0
+        with:
+          context: .
+          file: ./Dockerfile.sprig
+          platforms: ${{ matrix.platform }}
+          labels: ${{ steps.meta.outputs.labels }}
+          outputs: type=image,name=${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=${{ github.event_name != 'pull_request' }}
+          cache-from: |
+            type=registry,ref=${{ env.IMAGE_NAME }}-buildcache:${{ matrix.arch }}
+          cache-to: |
+            ${{ (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) && format('type=registry,ref={0}-buildcache:{1},mode=max,compression=zstd', env.IMAGE_NAME, matrix.arch) || '' }}
+
+      - name: Export digest
+        if: github.event_name != 'pull_request'
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+        run: |
+          mkdir -p /tmp/digests
+          touch "/tmp/digests/${DIGEST#sha256:}"
+
+      - name: Upload digest
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: sprig-digest-${{ matrix.arch }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  merge:
+    name: Merge multi-arch manifest
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-24.04
+    needs: build
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+      attestations: write
+
+    steps:
+      - name: Download per-arch digests
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          path: /tmp/digests
+          pattern: sprig-digest-*
+          merge-multiple: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
+
+      - name: Log in to GHCR
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee  # v4.2.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9  # v6.1.0
+        with:
+          images: ${{ env.IMAGE_NAME }}
+          # Must mirror the build job's tag matrix exactly (see docker.yml).
+          flavor: |
+            latest=auto
+          tags: |
+            type=ref,event=branch
+            type=sha,prefix=sha-,format=short
+            type=semver,pattern={{version}},match=^sprig-v(.*)$
+            type=semver,pattern={{major}}.{{minor}},match=^sprig-v(.*)$
+
+      - name: Create and push manifest list
+        id: manifest
+        working-directory: /tmp/digests
+        env:
+          IMAGE_NAME: ${{ env.IMAGE_NAME }}
+          META_TAGS: ${{ steps.meta.outputs.tags }}
+        run: |
+          set -euo pipefail
+          tags=()
+          while IFS= read -r tag; do
+            [ -n "$tag" ] && tags+=("-t" "$tag")
+          done <<< "$META_TAGS"
+
+          digests=()
+          for digest in *; do
+            digests+=("${IMAGE_NAME}@sha256:${digest}")
+          done
+
+          docker buildx imagetools create "${tags[@]}" "${digests[@]}"
+
+          first_tag=$(echo "$META_TAGS" | head -n1)
+          merged_digest=$(docker buildx imagetools inspect "$first_tag" \
+            --format '{{json .Manifest}}' | jq -r '.digest')
+          echo "digest=${merged_digest}" >> "$GITHUB_OUTPUT"
+
+      - name: Attest provenance for the merged image
+        # Verify with: gh attestation verify oci://ghcr.io/block/buzz-sprig:<tag> --owner block
+        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373  # v4.1.1
+        with:
+          subject-name: ${{ env.IMAGE_NAME }}
+          subject-digest: ${{ steps.manifest.outputs.digest }}
+          push-to-registry: true
+
+      - name: Summary
+        env:
+          IMAGE_NAME: ${{ env.IMAGE_NAME }}
+          DIGEST: ${{ steps.manifest.outputs.digest }}
+        run: |
+          {
+            echo "### Sprig image published"
+            echo '```'
+            echo "${IMAGE_NAME}@${DIGEST}"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/sprig.yml b/.github/workflows/sprig.yml
index b2dab3583f..5e50808b3b 100644
--- a/.github/workflows/sprig.yml
+++ b/.github/workflows/sprig.yml
@@ -42,7 +42,7 @@ jobs:
           - x86_64-unknown-linux-musl
           - aarch64-unknown-linux-musl
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
 
@@ -116,7 +116,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Download all Sprig artifacts
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -154,7 +154,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Download all Sprig artifacts
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
diff --git a/.gitignore b/.gitignore
index 65ddcaf1c4..f26e74136c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,6 +3,10 @@
 /dist/
 /admin-web/dist/
 
+# Python cache
+__pycache__/
+*.pyc
+
 # lefthook-generated hook scripts (machine-specific)
 .hooks/
 
diff --git a/.release/desktop-candidate.json b/.release/desktop-candidate.json
new file mode 100644
index 0000000000..1bf2efb66b
--- /dev/null
+++ b/.release/desktop-candidate.json
@@ -0,0 +1,8 @@
+{
+  "schema": 1,
+  "version": "0.5.3",
+  "base_sha": "54c8ef30a9bb9c59a4415a8a7ee84c7c5454b48a",
+  "previous_tag": "v0.5.2",
+  "tag": "desktop-v0.5.3",
+  "commit_count": 58
+}
diff --git a/000-docs/001-PP-PLAN-buzz-adoption-master-blueprint.md b/000-docs/001-PP-PLAN-buzz-adoption-master-blueprint.md
index 4c5533c3cd..8f632f707f 100644
--- a/000-docs/001-PP-PLAN-buzz-adoption-master-blueprint.md
+++ b/000-docs/001-PP-PLAN-buzz-adoption-master-blueprint.md
@@ -80,11 +80,15 @@ three-way (bead ↔ GitHub issue ↔ Plane project `BUZZ`).
 | E3 — Hardening + go-live gates (run against PROD) | 2 | in flight — membership probe + unauth HTTP matrix + resource caps + backup/restore PROVEN against prod; remaining BLOCKING: off-site backup leg, updater planted-fault drill (on staging), monitoring alerts exercised, full smoke suite, CORS client verify, pairing verify-or-documented, key runbooks rehearsed | — |
 | E4 — Headless administration | 2.5 | not started | — |
 | E5 — Team onboarding (all-in) | 3 | not started | — |
-| E6 — Agent bridge (`@claude`, isolated) | 4 | not started | — |
+| E6 — Agent bridge (isolated coding agent `goose minimax3`) | 4 | **LIVE on prod** (2026-07-30, decision-log/039, PR #301): `buzz-acp`+goose/MiniMax-M3 running as a member on the prod host, owner-gated + PR-gated, egress-isolated. Open: wire the prod PR loop (repo + scoped token + branch protection — owner inputs) | GH #? · PR #301 |
 | E7 — Governed-brain agent (`@bob`, BYOH) | 4 | staged (follow-up) | — |
 | ELab — Contributor laboratory (`intent-solutions-io/intent-ops-buzz` **repository**, Track C) | 6 | not started (repo not yet created — correct; depends on the naming record `006`) | — |
 | E8 — Upstream contribution lane (Track D) | 5 | qualified candidates filed | — |
 | E9 — Operator plugin (`intent-solutions-io/intent-ops-buzz-plugin`) | 7 | **DEFERRED** — scope gauged from the real install cycle (owner call 2026-07-29); repo not yet created | — |
+| E10 — Community channel layout & identity roster (`buzz-ehv`) | 3 | **build DONE (2026-07-31)** — clean provider-first open layout live (`0-general` pinned, `ask`, `ai-wire`, `anthropic-*` group, `<provider>-wire` + topic `*-wire`, private `sys-*`); persona agents purged; canonical names set; `ops/buzz/RUNBOOK-channels.md` (source-cited). Open: CCA-channel decision (owner-gated), member join/onboarding model | fork beads `buzz-ehv` |
+| E11 — Buzz operational expertise: reference + skill + agents (`buzz-yfe`) | 3 | **COMPLETE (2026-07-31)** — 2 source-cited references (`ops/buzz/reference/`, 100% citation-consistent with the fork); `buzz-ops` skill (PASS `/validate-skillmd`); 3 operator agents `buzz-ops`/`buzz-feed-curator`/`buzz-relay-admin` (PASS `/validate-agent`) | fork beads `buzz-yfe` |
+| E12 — AI-Wire feed engine (`buzz-w92`) | 4 | **posting primitive DONE**; ingestion pipeline next — `AI Wire` bot live, first cards posted to `ai-wire`+`0-general`. Children: pipeline (RSSHub+feed→LLM→card), easy/medium/hard feeds, Anthropic monitor-fleet wire, curation+digest, cron | fork beads `buzz-w92` |
+| E13 — Estate system notifications into `sys-*` (`buzz-0ts`) | 4 | **not started** (Track B) — `buzz-notify.sh`/`af_buzz_transport` → private `sys-*` channels, retiring Slack/notify/Moshi (keep off-estate floor + Ezekiel email) | fork beads `buzz-0ts` |
 
 Asset names are governed by `006-DR-STND-authoritative-naming-and-boundaries.md`
 (canonical). Never write the bare phrase `intent-ops-buzz` — it is either the
diff --git a/AGENTS.md b/AGENTS.md
index 7ff0eb4d47..4f03b312bc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -145,6 +145,10 @@ first, then implement handling in the relay.
 
 **Channel scoping**: Channels use `h` tags (NIP-29 group tag), not `e` tags.
 Filters and queries must scope to `h` tags when operating within a channel.
+This applies to events *inside* a channel. Addressable events that describe a
+channel carry its id in their `d` tag instead: kind:39000 (metadata),
+kind:39001, kind:39002 (membership). `get_channels` resolves a user's channels
+from the `d` tag of their kind:39002 events, not from `h`.
 
 **Agent-facing operations go in `buzz-cli`**: New agent-facing features belong in `buzz-cli` — add a subcommand there first, then wire the REST/WebSocket call in `client.rs`. `buzz-dev-mcp` (shell + file tools for `buzz-agent`) is separate.
 
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 90cbbac0cf..892082d96c 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -139,7 +139,7 @@ The `kind` integer is the only dispatch switch. The relay routes, stores, and fa
 | 46001–46012 | KIND_WORKFLOW_* | Workflow execution events |
 | 20001 | KIND_PRESENCE_UPDATE | Ephemeral presence heartbeat |
 
-`buzz-core` defines all 81 kinds as `pub const KIND_*: u32` and exports `ALL_KINDS: &[u32]`. Kinds are `u32` (NIP-01 specifies unsigned integer; `u32` covers the full range). Buzz uses both standard Nostr kinds (e.g., kind 7 for reactions) and custom ranges (40000+).
+`buzz-core` defines each event kind as a `pub const u32` and exports the full registry as `ALL_KINDS: &[u32]` (127 kinds at the time of writing); `crates/buzz-core/src/kind.rs` is the source of truth for the current list. Kinds are `u32` (NIP-01 specifies unsigned integer; `u32` covers the full range). Buzz uses both standard Nostr kinds (e.g., kind 7 for reactions) and custom ranges (40000+).
 
 Note: `KIND_AUTH` (22242) is `pub const KIND_AUTH: u32` in `buzz-core/src/kind.rs` and imported by `buzz-relay/src/handlers/event.rs`. `KIND_CANVAS` (40100) is likewise `pub const KIND_CANVAS: u32` in `buzz-core/src/kind.rs`.
 
@@ -447,7 +447,7 @@ The subscriber uses a **dedicated** `redis::aio::PubSub` connection — not from
 
 **Reconnection:** exponential backoff 1s → 30s (`backoff_secs * 2`). Backoff resets to 1s only after a clean stream end, not on each reconnect attempt.
 
-**Presence:** `SET buzz:presence:{pubkey_hex} {status} EX 90` — 90-second TTL (3× the 30-second heartbeat interval). Single missed heartbeat does not cause presence flap.
+**Presence:** `SET buzz:presence:{pubkey_hex} {status} EX 180` — 180-second TTL (3× the 60-second heartbeat interval). Single missed heartbeat does not cause presence flap.
 
 **Typing indicators:**
 ```
@@ -797,7 +797,7 @@ Docker Compose provides the full local development stack. All services include h
 | Pattern | Type | TTL | Purpose |
 |---------|------|-----|---------|
 | `buzz:channel:{uuid}` | Pub/Sub channel | — | Event fan-out (single-community form; shared multi-community Redis must use `buzz:{community}:channel:{uuid}` or equivalent) |
-| `buzz:presence:{pubkey_hex}` | String | 90s | Online/away status (single-community form; shared multi-community Redis must scope by community) |
+| `buzz:presence:{pubkey_hex}` | String | 180s | Online/away status (single-community form; shared multi-community Redis must scope by community) |
 | `buzz:typing:{channel_uuid}` | Sorted Set | 60s | Active typers (5s window; shared multi-community Redis must scope by community) |
 
 ### Full-Text Search (Postgres FTS)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cfd3b16d0a..71a4bbd449 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,106 @@
 # Changelog
 
+## v0.5.3
+
+### Desktop and shared changes
+
+- Revert "chore(release): release Buzz Desktop version 0.5.3" ([#3960](https://github.com/block/buzz/pull/3960)) ([`bb34bc4d98fe4dabe847046103ac5e2859917ac5`](https://github.com/block/buzz/commit/bb34bc4d98fe4dabe847046103ac5e2859917ac5))
+- chore(release): release Buzz Desktop version 0.5.3 ([`d12b3d6a79d56a95fc99ce4fadd2d2235d5a3131`](https://github.com/block/buzz/commit/d12b3d6a79d56a95fc99ce4fadd2d2235d5a3131))
+- feat(desktop): import local Pocket voices ([#3259](https://github.com/block/buzz/pull/3259)) ([`c104eecfb38620de2c35c7e20a716f8658b5a6b1`](https://github.com/block/buzz/commit/c104eecfb38620de2c35c7e20a716f8658b5a6b1))
+- fix(desktop): open profiles from avatars ([#3751](https://github.com/block/buzz/pull/3751)) ([`39ce3dfc3cf2d12f0d6c64b4cd4293df86567663`](https://github.com/block/buzz/commit/39ce3dfc3cf2d12f0d6c64b4cd4293df86567663))
+- refactor(voice): extract reusable Pocket primitives + Pocket voice settings (relands #2467 + #3208) ([#3910](https://github.com/block/buzz/pull/3910)) ([`61ba9dfaa00852925058d1a024322fa53663a5bc`](https://github.com/block/buzz/commit/61ba9dfaa00852925058d1a024322fa53663a5bc))
+- feat(desktop): auto-enable huddle transcription for agents ([#3180](https://github.com/block/buzz/pull/3180)) ([`4632c55041c5d423d572a6f6411bb7b279c26f67`](https://github.com/block/buzz/commit/4632c55041c5d423d572a6f6411bb7b279c26f67))
+- feat(agent): optional reply guard reminds a silent turn to publish ([#3763](https://github.com/block/buzz/pull/3763)) ([`081f805d5ea25841ab885c7b67a568618a34aa59`](https://github.com/block/buzz/commit/081f805d5ea25841ab885c7b67a568618a34aa59))
+- feat(desktop): upgrade Pocket TTS model ([#3266](https://github.com/block/buzz/pull/3266)) ([`d48b0e0eec4d2958f90a3cafa9d974450abe8501`](https://github.com/block/buzz/commit/d48b0e0eec4d2958f90a3cafa9d974450abe8501))
+- feat(desktop): delete a message by clearing its edit to empty ([#3813](https://github.com/block/buzz/pull/3813)) ([`d88313f369acfa17973029787ee4c0bbea07fa51`](https://github.com/block/buzz/commit/d88313f369acfa17973029787ee4c0bbea07fa51))
+- feat(relay): raise hosted community limit to five ([#3829](https://github.com/block/buzz/pull/3829)) ([`10d5a26414dc90dc89fd27de74b21e105d4fa622`](https://github.com/block/buzz/commit/10d5a26414dc90dc89fd27de74b21e105d4fa622))
+- feat(desktop): locally stored NIP-49 encrypted key backup ([#2937](https://github.com/block/buzz/pull/2937)) ([`468647a51f858b29d27eaf9fd07bf90294f99d39`](https://github.com/block/buzz/commit/468647a51f858b29d27eaf9fd07bf90294f99d39))
+- fix(catalog): update Amp tagline ([#3806](https://github.com/block/buzz/pull/3806)) ([`f3e5e812677f6f14bffe16a7aa02642d56faca4b`](https://github.com/block/buzz/commit/f3e5e812677f6f14bffe16a7aa02642d56faca4b))
+- fix(desktop): channel topic and membership metadata cleanup ([#3642](https://github.com/block/buzz/pull/3642)) ([`9e8fcfda099652926b921bca7fcc9bfecab0e140`](https://github.com/block/buzz/commit/9e8fcfda099652926b921bca7fcc9bfecab0e140))
+- fix(desktop): align data deletion labels ([#2230](https://github.com/block/buzz/pull/2230)) ([`ede26863345a518ec46edd6d7692e0281883491b`](https://github.com/block/buzz/commit/ede26863345a518ec46edd6d7692e0281883491b))
+- fix(desktop): allow linux-only media items as dead code off-linux ([#3811](https://github.com/block/buzz/pull/3811)) ([`36571f4adcfdcf3714a17bd968c58c78bcbdd9ef`](https://github.com/block/buzz/commit/36571f4adcfdcf3714a17bd968c58c78bcbdd9ef))
+- fix(desktop): report authenticated relay recovery ([#3812](https://github.com/block/buzz/pull/3812)) ([`74cd5712191bffd84ae688d59bb8b451c6eec1b0`](https://github.com/block/buzz/commit/74cd5712191bffd84ae688d59bb8b451c6eec1b0))
+- fix(desktop): don't gate hover affordances on the hover media query ([#3657](https://github.com/block/buzz/pull/3657)) ([`29dfe4821ed577489a1879fd2a9bfe2a621a52b3`](https://github.com/block/buzz/commit/29dfe4821ed577489a1879fd2a9bfe2a621a52b3))
+- feat(relay): gate kind 30178 team-catalog reads behind the shared tag ([#3358](https://github.com/block/buzz/pull/3358)) ([`114d40d9d37f05eff83ee90347ed93fb3da512c5`](https://github.com/block/buzz/commit/114d40d9d37f05eff83ee90347ed93fb3da512c5))
+- test(desktop): click visible thread collapse guide ([#3800](https://github.com/block/buzz/pull/3800)) ([`b9e4ed616f39b812bc964e79c7a40223c4e93832`](https://github.com/block/buzz/commit/b9e4ed616f39b812bc964e79c7a40223c4e93832))
+- feat(desktop): raise the install ceiling and make installs observable ([#3368](https://github.com/block/buzz/pull/3368)) ([`d40a33290e75791aa7ecf3ce7a252b66c2e35966`](https://github.com/block/buzz/commit/d40a33290e75791aa7ecf3ce7a252b66c2e35966))
+- Add Devin as a preset ACP harness ([#3225](https://github.com/block/buzz/pull/3225)) ([`1b3ff96a5764303998fa629ff852e81f1a88d7ad`](https://github.com/block/buzz/commit/1b3ff96a5764303998fa629ff852e81f1a88d7ad))
+- feat(desktop): improve agent activity header ui ([#3321](https://github.com/block/buzz/pull/3321)) ([`4d47aa83455a9fd024121a596154cd311dca1d76`](https://github.com/block/buzz/commit/4d47aa83455a9fd024121a596154cd311dca1d76))
+- perf(presence): reduce heartbeat frequency ([#3783](https://github.com/block/buzz/pull/3783)) ([`bf139e8d0bdba10df9a5adbf16843140e0a78a59`](https://github.com/block/buzz/commit/bf139e8d0bdba10df9a5adbf16843140e0a78a59))
+- Tighten continuation message rows ([#3724](https://github.com/block/buzz/pull/3724)) ([`6e419b9f1c873549a7b40996970e0da7352adafb`](https://github.com/block/buzz/commit/6e419b9f1c873549a7b40996970e0da7352adafb))
+- Fix video reviews in thread replies ([#3719](https://github.com/block/buzz/pull/3719)) ([`f48f3f055fdd6030d3832f615f8c0d8e5a81261a`](https://github.com/block/buzz/commit/f48f3f055fdd6030d3832f615f8c0d8e5a81261a))
+- Make relay reconnect backoff authoritative ([#3774](https://github.com/block/buzz/pull/3774)) ([`cca8839034eb571a7ce943c3ace7f85a82330898`](https://github.com/block/buzz/commit/cca8839034eb571a7ce943c3ace7f85a82330898))
+- feat(desktop): add password-protected backups in settings ([#3701](https://github.com/block/buzz/pull/3701)) ([`bd0bff24bfd2cffa2b3b3a995f7628af5e460a5c`](https://github.com/block/buzz/commit/bd0bff24bfd2cffa2b3b3a995f7628af5e460a5c))
+- fix(desktop): reuse profiles when joining communities ([#2155](https://github.com/block/buzz/pull/2155)) ([`f44b5a2477f3979ae66e49153b11be36538cf859`](https://github.com/block/buzz/commit/f44b5a2477f3979ae66e49153b11be36538cf859))
+- fix(catalog): update Amp description ([#3758](https://github.com/block/buzz/pull/3758)) ([`61b96c9828d1dd54106b570d87a54edbc92bb9c4`](https://github.com/block/buzz/commit/61b96c9828d1dd54106b570d87a54edbc92bb9c4))
+- feat(catalog): resolve publisher display name in catalog detail pane ([#3640](https://github.com/block/buzz/pull/3640)) ([`02be413b823c356587e6e9f4d07f6cb06bb41c3c`](https://github.com/block/buzz/commit/02be413b823c356587e6e9f4d07f6cb06bb41c3c))
+- feat(mesh): upgrade embedded mesh to v0.74 and harden shared compute (split 1/2 of #3467) ([#3741](https://github.com/block/buzz/pull/3741)) ([`4933672eb4589e7208b312829ebddcd10dfa9dd3`](https://github.com/block/buzz/commit/4933672eb4589e7208b312829ebddcd10dfa9dd3))
+- Refine agent sharing dialog ([#3699](https://github.com/block/buzz/pull/3699)) ([`9a386a0defbf2b355ee17646c7c11817a535b85f`](https://github.com/block/buzz/commit/9a386a0defbf2b355ee17646c7c11817a535b85f))
+- desktop: enable getUserMedia in the Linux WebKitGTK webview ([#3607](https://github.com/block/buzz/pull/3607)) ([`c9aa55505c544c608ff71648bbfd21b235637f19`](https://github.com/block/buzz/commit/c9aa55505c544c608ff71648bbfd21b235637f19))
+- fix: align responsive agent views ([#3688](https://github.com/block/buzz/pull/3688)) ([`73589408db6fd96b87ac570935d414ecc4120f53`](https://github.com/block/buzz/commit/73589408db6fd96b87ac570935d414ecc4120f53))
+- Add macOS agent menu-bar menu ([#3565](https://github.com/block/buzz/pull/3565)) ([`d0a24bcb5210326da4c0b1e749ee3935621b329c`](https://github.com/block/buzz/commit/d0a24bcb5210326da4c0b1e749ee3935621b329c))
+- Fix pending message feedback ([#3543](https://github.com/block/buzz/pull/3543)) ([`4672ee55c4e4a7916c31bfeae5df2fb4384bed10`](https://github.com/block/buzz/commit/4672ee55c4e4a7916c31bfeae5df2fb4384bed10))
+- fix(desktop): remove remaining Projects panel fills ([#3742](https://github.com/block/buzz/pull/3742)) ([`c55e421a0629c74b9ffd96ee3ccde36f006196ed`](https://github.com/block/buzz/commit/c55e421a0629c74b9ffd96ee3ccde36f006196ed))
+- desktop: restore direct community member adds ([#3634](https://github.com/block/buzz/pull/3634)) ([`310df2ec33fbb075edf226ba18bf9a96d90ba81b`](https://github.com/block/buzz/commit/310df2ec33fbb075edf226ba18bf9a96d90ba81b))
+- fix(desktop): explain open agent access ([#2561](https://github.com/block/buzz/pull/2561)) ([`7fb008f9347b933b9a1da20a7afb070912b430e8`](https://github.com/block/buzz/commit/7fb008f9347b933b9a1da20a7afb070912b430e8))
+- fix(desktop): remove Projects overview card fills ([#3416](https://github.com/block/buzz/pull/3416)) ([`3b8567a05d4c40e667d061666feb7aa7bc38212d`](https://github.com/block/buzz/commit/3b8567a05d4c40e667d061666feb7aa7bc38212d))
+- fix(git): channel binding tooling + author remediation for unbound repos ([#3626](https://github.com/block/buzz/pull/3626)) ([`788b3c002bd2509455444f57f8a03a054b4b496a`](https://github.com/block/buzz/commit/788b3c002bd2509455444f57f8a03a054b4b496a))
+- feat: configure S3 URL addressing style ([#3400](https://github.com/block/buzz/pull/3400)) ([`7012d86d52fd188b27c7beedeaa132d9c1f61fa8`](https://github.com/block/buzz/commit/7012d86d52fd188b27c7beedeaa132d9c1f61fa8))
+- feat: add first-class OpenRouter provider support ([#1975](https://github.com/block/buzz/pull/1975)) ([`ab55fee81896d2b03edf5d2ca5012b715be2b93d`](https://github.com/block/buzz/commit/ab55fee81896d2b03edf5d2ca5012b715be2b93d))
+- feat(agent,acp): wire provider total_tokens through NIP-AM publish chain ([#3593](https://github.com/block/buzz/pull/3593)) ([`f95fdc1a102e17c6718a44323d9a2feaed702db7`](https://github.com/block/buzz/commit/f95fdc1a102e17c6718a44323d9a2feaed702db7))
+
+### Other repository changes
+
+- fix(release): require exact-head approval for desktop tags ([#3973](https://github.com/block/buzz/pull/3973)) ([`54c8ef30a9bb9c59a4415a8a7ee84c7c5454b48a`](https://github.com/block/buzz/commit/54c8ef30a9bb9c59a4415a8a7ee84c7c5454b48a))
+- fix(release): make desktop tagging squash-safe ([#3965](https://github.com/block/buzz/pull/3965)) ([`db7e84d4f815127236b9cb080c5d374f48eaac09`](https://github.com/block/buzz/commit/db7e84d4f815127236b9cb080c5d374f48eaac09))
+- docs(nips): add single-coordinate manual-unread override layer and verification model to NIP-RS ([#2864](https://github.com/block/buzz/pull/2864)) ([`209536ade6c5ebf7fa82671d7ca0b74f599a40cc`](https://github.com/block/buzz/commit/209536ade6c5ebf7fa82671d7ca0b74f599a40cc))
+- fix(release): make immutable desktop release operable ([#3943](https://github.com/block/buzz/pull/3943)) ([`052174a148f9f6bcbb2b5a1d20ce0317645e49f8`](https://github.com/block/buzz/commit/052174a148f9f6bcbb2b5a1d20ce0317645e49f8))
+- docs: add VISION_REMOTE_AGENTS.md ([#3924](https://github.com/block/buzz/pull/3924)) ([`689617af7ad420c3266d5d2eb437757371327089`](https://github.com/block/buzz/commit/689617af7ad420c3266d5d2eb437757371327089))
+- fix(relay): align NIP-11 max_limit with REQ ceiling ([#3635](https://github.com/block/buzz/pull/3635)) ([`23f0c26b1ceba8e07bf3c160a1e08c7bda82ccd9`](https://github.com/block/buzz/commit/23f0c26b1ceba8e07bf3c160a1e08c7bda82ccd9))
+- fix(db): isolate usage metrics advisory-lock test on scratch DB ([#3670](https://github.com/block/buzz/pull/3670)) ([`dba97eecd9d8659c9c816cd6666fa6d687b6bca1`](https://github.com/block/buzz/commit/dba97eecd9d8659c9c816cd6666fa6d687b6bca1))
+- feat(release): make desktop releases immutable ([#3568](https://github.com/block/buzz/pull/3568)) ([`1dfd89ea67b4ebce0c4d10390f280ed4e7ddde8a`](https://github.com/block/buzz/commit/1dfd89ea67b4ebce0c4d10390f280ed4e7ddde8a))
+- Render mobile agent mention chips ([#3702](https://github.com/block/buzz/pull/3702)) ([`06582ee6f09e5f7454e4d8895d80a45c3cdb5e8a`](https://github.com/block/buzz/commit/06582ee6f09e5f7454e4d8895d80a45c3cdb5e8a))
+- fix(acp): preserve truncated thread context ([#3340](https://github.com/block/buzz/pull/3340)) ([`53771c8f5439f9c5c26876f0229bfcfe5da9b170`](https://github.com/block/buzz/commit/53771c8f5439f9c5c26876f0229bfcfe5da9b170))
+- docs(nips): specify kind:30621 multi-repo projects (NIP-MP) ([#3163](https://github.com/block/buzz/pull/3163)) ([`33bf7caa6ea474ccde2932c1ed05a90d7345c6e0`](https://github.com/block/buzz/commit/33bf7caa6ea474ccde2932c1ed05a90d7345c6e0))
+- feat(mobile): desktop-parity emoji and thread experience ([#3485](https://github.com/block/buzz/pull/3485)) ([`85edc0572a8540dedfa6562d40f0f875af0b5f61`](https://github.com/block/buzz/commit/85edc0572a8540dedfa6562d40f0f875af0b5f61))
+- fix(cli): resolve agents from owner records ([#3178](https://github.com/block/buzz/pull/3178)) ([`262f2392e3b7e09c78d582fb384672034d8551d5`](https://github.com/block/buzz/commit/262f2392e3b7e09c78d582fb384672034d8551d5))
+- feat(replica): portable heartbeat-token fence with snapshot-local reader routing ([#3268](https://github.com/block/buzz/pull/3268)) ([`63496cc1d4c6f1b7c613801bdcc694169dcf391a`](https://github.com/block/buzz/commit/63496cc1d4c6f1b7c613801bdcc694169dcf391a))
+
+[Compare v0.5.2...desktop-v0.5.3](https://github.com/block/buzz/compare/v0.5.2...desktop-v0.5.3)
+
+## v0.5.2
+
+- feat(cli): mirror Desktop mention delivery ([#3330](https://github.com/block/buzz/pull/3330)) ([`7adc46268`](https://github.com/block/buzz/commit/7adc46268d5e93f0b1d4dc8e700af22815dcac1b))
+- fix(desktop): deduplicate relay outage notification ([#3579](https://github.com/block/buzz/pull/3579)) ([`66e705492`](https://github.com/block/buzz/commit/66e7054928cc29395f828467c3e8c81b7408dd29))
+- fix(desktop): reconcile thread arrivals at bottom ([#3585](https://github.com/block/buzz/pull/3585)) ([`b42a8d447`](https://github.com/block/buzz/commit/b42a8d447e3a2b85b2313dc4fdd123731fd8bba3))
+- Improve emoji autocomplete matching ([#3571](https://github.com/block/buzz/pull/3571)) ([`259de6afb`](https://github.com/block/buzz/commit/259de6afbe0cc0d106e57ebdb2323064990e4122))
+- Fix shared agent avatar import profiles ([#3578](https://github.com/block/buzz/pull/3578)) ([`324bd6b46`](https://github.com/block/buzz/commit/324bd6b464de5751e12abbd155376046ce3d2afc))
+- Fix inline raster avatars in agent catalog ([#3581](https://github.com/block/buzz/pull/3581)) ([`7e9b77f72`](https://github.com/block/buzz/commit/7e9b77f72d82e019a99f074f1c9829be30c57ae1))
+- feat(agent): make Gemini and MLflow-route models usable through databricks_v2 ([#3569](https://github.com/block/buzz/pull/3569)) ([`4a1ebf25c`](https://github.com/block/buzz/commit/4a1ebf25c782fc6a68f0a69e6f866f793a259a1f))
+
+
+## v0.5.1
+
+- perf(desktop): move observer-feed archive and decrypt commands off main thread ([#3415](https://github.com/block/buzz/pull/3415)) ([`294c8c821`](https://github.com/block/buzz/commit/294c8c821de51442a8c384c0bdb66b1a10224ca0))
+- fix(desktop): preserve shared agent fidelity ([#3553](https://github.com/block/buzz/pull/3553)) ([`f7a3988ba`](https://github.com/block/buzz/commit/f7a3988ba13b590d9a55a7e8413fc3fb5ffbef18))
+- feat(agent): route Claude/GPT model families to their native gateway wire ([#3538](https://github.com/block/buzz/pull/3538)) ([`6438dedf8`](https://github.com/block/buzz/commit/6438dedf83a9dbe1853e484326911bf6c7f1618c))
+- Refine community invite limits ([#3529](https://github.com/block/buzz/pull/3529)) ([`24d90d128`](https://github.com/block/buzz/commit/24d90d1280a9325c6cbcf8eea30ac54db5afd2cb))
+- feat(agent): fix Anthropic prompt caching with Databricks (+ MCP proxy/TLS passthrough) ([#3463](https://github.com/block/buzz/pull/3463)) ([`c405ad1d4`](https://github.com/block/buzz/commit/c405ad1d4b1da061c11b3d26761252d41dcc62d3))
+- feat: add explicit entry for claude-opus-5 in model config ([#2831](https://github.com/block/buzz/pull/2831)) ([`90e058ebf`](https://github.com/block/buzz/commit/90e058ebf68137e048a409aec6616519379ff726))
+- fix(desktop): clear stale thread new-message pill ([#3411](https://github.com/block/buzz/pull/3411)) ([`55a3ed7b9`](https://github.com/block/buzz/commit/55a3ed7b9217cee5b23e0a5441947dc929b2a38c))
+- fix(ci): ratchet file sizes against the base tree ([#3352](https://github.com/block/buzz/pull/3352)) ([`9227bdf58`](https://github.com/block/buzz/commit/9227bdf58ad6664ae3c1078888f2181ec19c4da4))
+- feat(desktop): apply WebKit rendering workarounds at startup on Linux ([#3271](https://github.com/block/buzz/pull/3271)) ([`3ece4461d`](https://github.com/block/buzz/commit/3ece4461df8a7b9663a8e68327483b8377d4086d))
+- fix(desktop): stabilize flaky DM expansion E2E ordering assertions ([#2004](https://github.com/block/buzz/pull/2004)) ([`913d564ce`](https://github.com/block/buzz/commit/913d564ce0f35924291bf3eeab6508517a6d8d1f))
+- fix(desktop): paint community rail full height ([#3382](https://github.com/block/buzz/pull/3382)) ([`1d3b810ad`](https://github.com/block/buzz/commit/1d3b810ad70d6325718ed91e723f32c4a376d5e1))
+- feat(desktop): add custom harness inline from agent dialogs ([#3252](https://github.com/block/buzz/pull/3252)) ([`b0503d80c`](https://github.com/block/buzz/commit/b0503d80c298b1ece3b0a43b41d316829a3379e7))
+- feat(desktop): refine agent catalog sharing ([#2439](https://github.com/block/buzz/pull/2439)) ([`a35771fc4`](https://github.com/block/buzz/commit/a35771fc441cdc3c6f517f419037206783b502d2))
+- fix(desktop): keep drafts out of the Inbox All view ([#3217](https://github.com/block/buzz/pull/3217)) ([`3afa129ee`](https://github.com/block/buzz/commit/3afa129ee785cc74d921d0ba969254a8255c4cc0))
+- fix(desktop): restore the inbox icon in the sidebar ([#3341](https://github.com/block/buzz/pull/3341)) ([`00ede2e7a`](https://github.com/block/buzz/commit/00ede2e7aa7eb95571b7db3ebbd163adbf6cf74e))
+- fix(desktop): gate codex-acp on a minimum supported version ([#3254](https://github.com/block/buzz/pull/3254)) ([`4e3998f36`](https://github.com/block/buzz/commit/4e3998f36e36d68b9a93dcbd85f0864450bb8f5f))
+- feat(cli): add users set-status command for NIP-38 profile status ([#3253](https://github.com/block/buzz/pull/3253)) ([`60158fce3`](https://github.com/block/buzz/commit/60158fce3e670f11bb35d42627857ccaea50ff06))
+- fix(composer): scope multiline block formatting ([#3246](https://github.com/block/buzz/pull/3246)) ([`5457c947a`](https://github.com/block/buzz/commit/5457c947a74f5ba4b979f9c6411aa7626a858387))
+
+
 ## v0.5.0
 
 - feat(invites): add use-limited invite links ([#3141](https://github.com/block/buzz/pull/3141)) ([`d500c2d5c`](https://github.com/block/buzz/commit/d500c2d5cf5d9aabe0ca4ebebfcafdbe5f5b7fd3))
diff --git a/Cargo.lock b/Cargo.lock
index 3b60dc4579..937ead564a 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -43,6 +43,20 @@ dependencies = [
  "subtle",
 ]
 
+[[package]]
+name = "ahash"
+version = "0.8.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
+dependencies = [
+ "cfg-if 1.0.4",
+ "getrandom 0.3.4",
+ "once_cell",
+ "serde",
+ "version_check",
+ "zerocopy",
+]
+
 [[package]]
 name = "aho-corasick"
 version = "1.1.4"
@@ -131,7 +145,7 @@ checksum = "5d0a66767aaf7d483c556386fb68ca2fba9347684d8bb17a4bd8b755851870f7"
 dependencies = [
  "arrayvec",
  "aws-lc-rs",
- "base64",
+ "base64 0.22.1",
  "byteorder",
  "minicbor",
  "rustls-pki-types",
@@ -396,13 +410,23 @@ version = "1.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
 
+[[package]]
+name = "atomic-write-file"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "84790c55b5704b0d35130bf16a4ce22a8e70eb0ea773522557524d9a4852663d"
+dependencies = [
+ "nix 0.30.1",
+ "rand 0.9.4",
+]
+
 [[package]]
 name = "attohttpc"
 version = "0.30.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "16e2cdb6d5ed835199484bb92bb8b3edd526effe995c61732580439c1a67e2e9"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "http",
  "log",
  "rustls",
@@ -473,7 +497,7 @@ checksum = "31b698c5f9a010f6573133b09e0de5408834d0c82f8d7475a89fc1867a71cd90"
 dependencies = [
  "axum-core",
  "axum-macros",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "form_urlencoded",
  "futures-util",
@@ -549,6 +573,12 @@ version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fd307490d624467aa6f74b0eabb77633d1f758a7b25f12bceb0b22e08d9726f6"
 
+[[package]]
+name = "base64"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e1b586273c5702936fe7b7d6896644d8be71e6314cfe09d3167c95f712589e8"
+
 [[package]]
 name = "base64"
 version = "0.22.1"
@@ -567,6 +597,12 @@ version = "0.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32637268377fc7b10a8c6d51de3e7fba1ce5dd371a96e342b34e6078db558e7f"
 
+[[package]]
+name = "beef"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a8241f3ebb85c056b509d4327ad0358fbbba6ffb340bf388f26350aeda225b1"
+
 [[package]]
 name = "bip39"
 version = "2.2.2"
@@ -765,7 +801,7 @@ name = "buzz-acp"
 version = "0.1.0"
 dependencies = [
  "anyhow",
- "base64",
+ "base64 0.22.1",
  "buzz-core",
  "buzz-persona",
  "buzz-sdk",
@@ -825,7 +861,7 @@ dependencies = [
  "arc-swap",
  "async-trait",
  "axum",
- "base64",
+ "base64 0.22.1",
  "getrandom 0.4.3",
  "hex",
  "nix 0.31.3",
@@ -879,12 +915,32 @@ dependencies = [
  "uuid",
 ]
 
+[[package]]
+name = "buzz-backend-kubernetes"
+version = "0.1.0"
+dependencies = [
+ "chrono",
+ "hex",
+ "http",
+ "http-body-util",
+ "k8s-openapi",
+ "kube",
+ "nostr",
+ "rand 0.10.1",
+ "rustls",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "tokio",
+ "tower",
+]
+
 [[package]]
 name = "buzz-cli"
 version = "0.1.0"
 dependencies = [
  "axum",
- "base64",
+ "base64 0.22.1",
  "buzz-core",
  "buzz-persona",
  "buzz-sdk",
@@ -925,7 +981,7 @@ dependencies = [
 name = "buzz-core"
 version = "0.1.0"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "chrono",
  "hex",
  "hmac 0.13.0",
@@ -949,6 +1005,8 @@ dependencies = [
  "buzz-core",
  "chrono",
  "hex",
+ "metrics",
+ "metrics-util",
  "nostr",
  "rand 0.10.1",
  "serde",
@@ -965,7 +1023,7 @@ dependencies = [
 name = "buzz-dev-mcp"
 version = "0.1.0"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "buzz-cli",
  "buzz-core",
  "git-credential-nostr",
@@ -1092,7 +1150,7 @@ dependencies = [
  "appattest",
  "async-trait",
  "axum",
- "base64",
+ "base64 0.22.1",
  "byteorder",
  "chrono",
  "getrandom 0.4.3",
@@ -1127,7 +1185,7 @@ dependencies = [
  "async-compression",
  "async-trait",
  "axum",
- "base64",
+ "base64 0.22.1",
  "buzz-audit",
  "buzz-auth",
  "buzz-conformance",
@@ -1237,8 +1295,9 @@ name = "buzz-test-client"
 version = "0.1.0"
 dependencies = [
  "anyhow",
- "base64",
+ "base64 0.22.1",
  "buzz-core",
+ "buzz-media",
  "buzz-sdk",
  "buzz-ws-client",
  "chrono",
@@ -1262,6 +1321,25 @@ dependencies = [
  "uuid",
 ]
 
+[[package]]
+name = "buzz-voice"
+version = "0.1.0"
+dependencies = [
+ "atomic-write-file",
+ "hex",
+ "ort",
+ "ort-sys",
+ "rand 0.10.1",
+ "sentencepiece-model",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "sherpa-onnx",
+ "symphonia",
+ "tempfile",
+ "tokenizers",
+]
+
 [[package]]
 name = "buzz-workflow"
 version = "0.1.0"
@@ -1329,6 +1407,26 @@ version = "1.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 
+[[package]]
+name = "bzip2"
+version = "0.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bdb116a6ef3f6c3698828873ad02c3014b3c85cadb88496095628e3ef1e347f8"
+dependencies = [
+ "bzip2-sys",
+ "libc",
+]
+
+[[package]]
+name = "bzip2-sys"
+version = "0.1.13+1.0.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "225bff33b2141874fe80d71e07d6eec4f85c5c216453dd96388240f96e1acc14"
+dependencies = [
+ "cc",
+ "pkg-config",
+]
+
 [[package]]
 name = "castaway"
 version = "0.2.4"
@@ -1577,6 +1675,7 @@ dependencies = [
  "itoa",
  "rustversion",
  "ryu",
+ "serde",
  "static_assertions",
 ]
 
@@ -2137,6 +2236,15 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "dary_heap"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b1e3a325bc115f096c8b77bbf027a7c2592230e70be2d985be950d3d5e60ebe"
+dependencies = [
+ "serde",
+]
+
 [[package]]
 name = "dashmap"
 version = "6.2.1"
@@ -2174,7 +2282,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ccc2776f0c61eca1ca32528f85548abd1a4be8fb53d1b21c013e4f18da1e7090"
 dependencies = [
  "data-encoding",
- "syn 1.0.109",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -2626,6 +2734,12 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "esaxx-rs"
+version = "0.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d817e038c30374a4bcb22f94d0a8a0e216958d4c3dcde369b1439fec4bdda6e6"
+
 [[package]]
 name = "etcetera"
 version = "0.11.0"
@@ -2683,6 +2797,12 @@ dependencies = [
  "smallvec",
 ]
 
+[[package]]
+name = "extended"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af9673d8203fcb076b19dfd17e38b3d4ae9f44959416ea532ce72415a6020365"
+
 [[package]]
 name = "fancy-regex"
 version = "0.11.0"
@@ -2693,6 +2813,17 @@ dependencies = [
  "regex",
 ]
 
+[[package]]
+name = "fancy-regex"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e24cb5a94bcae1e5408b0effca5cd7172ea3c5755049c5f3af4cd283a165298"
+dependencies = [
+ "bit-set 0.8.0",
+ "regex-automata",
+ "regex-syntax",
+]
+
 [[package]]
 name = "fast-srgb8"
 version = "1.0.0"
@@ -3084,7 +3215,7 @@ dependencies = [
 name = "git-credential-nostr"
 version = "0.1.0"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "nostr",
  "serde_json",
  "zeroize",
@@ -3094,7 +3225,7 @@ dependencies = [
 name = "git-sign-nostr"
 version = "0.1.0"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "chrono",
  "hex",
  "libc",
@@ -3269,7 +3400,7 @@ version = "1.0.0-rc.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5f89305dc8fe34e165eaf0eb12b6e294e12381d9df9a431bcc52a5809bab4319"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bon",
  "bytes",
  "futures",
@@ -3532,6 +3663,7 @@ dependencies = [
  "http",
  "hyper",
  "hyper-util",
+ "log",
  "rustls",
  "rustls-native-certs",
  "tokio",
@@ -3575,7 +3707,7 @@ version = "0.1.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bytes",
  "futures-channel",
  "futures-util",
@@ -4192,6 +4324,31 @@ dependencies = [
  "ucd-trie",
 ]
 
+[[package]]
+name = "jsonpath-rust"
+version = "0.7.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c00ae348f9f8fd2d09f82a98ca381c60df9e0820d8d79fce43e649b4dc3128b"
+dependencies = [
+ "pest",
+ "pest_derive",
+ "regex",
+ "serde_json",
+ "thiserror 2.0.18",
+]
+
+[[package]]
+name = "k8s-openapi"
+version = "0.26.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06d9e5e61dd037cdc51da0d7e2b2be10f497478ea7e120d85dad632adb99882b"
+dependencies = [
+ "base64 0.22.1",
+ "chrono",
+ "serde",
+ "serde_json",
+]
+
 [[package]]
 name = "kasuari"
 version = "0.4.12"
@@ -4237,6 +4394,70 @@ version = "0.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e037a2e1d8d5fdbd49b16a4ea09d5d6401c1f29eca5ff29d03d3824dba16256a"
 
+[[package]]
+name = "kube"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48e7bb0b6a46502cc20e4575b6ff401af45cfea150b34ba272a3410b78aa014e"
+dependencies = [
+ "k8s-openapi",
+ "kube-client",
+ "kube-core",
+]
+
+[[package]]
+name = "kube-client"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4987d57a184d2b5294fdad3d7fc7f278899469d21a4da39a8f6ca16426567a36"
+dependencies = [
+ "base64 0.22.1",
+ "bytes",
+ "chrono",
+ "either",
+ "futures",
+ "home",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-rustls",
+ "hyper-timeout",
+ "hyper-util",
+ "jsonpath-rust",
+ "k8s-openapi",
+ "kube-core",
+ "pem",
+ "rustls",
+ "secrecy",
+ "serde",
+ "serde_json",
+ "serde_yaml",
+ "thiserror 2.0.18",
+ "tokio",
+ "tokio-util",
+ "tower",
+ "tower-http",
+ "tracing",
+]
+
+[[package]]
+name = "kube-core"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "914bbb770e7bb721a06e3538c0edd2babed46447d128f7c21caa68747060ee73"
+dependencies = [
+ "chrono",
+ "derive_more",
+ "form_urlencoded",
+ "http",
+ "k8s-openapi",
+ "serde",
+ "serde-value",
+ "serde_json",
+ "thiserror 2.0.18",
+]
+
 [[package]]
 name = "lab"
 version = "0.11.0"
@@ -4359,6 +4580,39 @@ version = "0.4.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
+[[package]]
+name = "logos"
+version = "0.14.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7251356ef8cb7aec833ddf598c6cb24d17b689d20b993f9d11a3d764e34e6458"
+dependencies = [
+ "logos-derive",
+]
+
+[[package]]
+name = "logos-codegen"
+version = "0.14.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59f80069600c0d66734f5ff52cc42f2dabd6b29d205f333d61fd7832e9e9963f"
+dependencies = [
+ "beef",
+ "fnv",
+ "lazy_static",
+ "proc-macro2",
+ "quote",
+ "regex-syntax",
+ "syn 2.0.117",
+]
+
+[[package]]
+name = "logos-derive"
+version = "0.14.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24fb722b06a9dc12adb0963ed585f19fc61dc5413e6a9be9422ef92c091e731d"
+dependencies = [
+ "logos-codegen",
+]
+
 [[package]]
 name = "loom"
 version = "0.7.2"
@@ -4418,6 +4672,22 @@ dependencies = [
  "winapi",
 ]
 
+[[package]]
+name = "macro_rules_attribute"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b3ae8f6d608c795738406608304d30a2dfbdc8e58e44f7ba43236da5208ded3c"
+dependencies = [
+ "macro_rules_attribute-proc_macro",
+ "pastey",
+]
+
+[[package]]
+name = "macro_rules_attribute-proc_macro"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc04a4c58212d57930a24bf47d3fa87485264a3a054e9c10e042eb373573ad3c"
+
 [[package]]
 name = "matchers"
 version = "0.2.0"
@@ -4433,6 +4703,16 @@ version = "0.8.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3"
 
+[[package]]
+name = "matrixmultiply"
+version = "0.3.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f607c237553f086e7043417a51df26b2eb899d3caff94e6a67592ff992fedc7"
+dependencies = [
+ "autocfg",
+ "rawpointer",
+]
+
 [[package]]
 name = "maybe-async"
 version = "0.2.11"
@@ -4498,8 +4778,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-api-client"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "hex",
  "mesh-llm-client",
@@ -4508,8 +4788,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-api-server"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "mesh-llm-api-client",
@@ -4519,17 +4799,17 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-build-info"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 
 [[package]]
 name = "mesh-llm-client"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "async-trait",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "crypto_box",
  "ed25519-dalek",
@@ -4542,7 +4822,7 @@ dependencies = [
  "mesh-llm-types",
  "model-artifact",
  "nostr-sdk",
- "prost",
+ "prost 0.14.3",
  "rand 0.10.1",
  "rustls",
  "serde",
@@ -4556,8 +4836,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-config"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "dirs",
@@ -4572,8 +4852,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-embedded-runtime"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "mesh-llm-host-runtime",
@@ -4582,8 +4862,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-events"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "clap",
@@ -4594,8 +4874,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-gpu-bench"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "cc",
@@ -4607,8 +4887,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-guardrails"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "serde",
  "serde_json",
@@ -4616,22 +4896,22 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-hardware-profile"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "mesh-llm-native-runtime",
 ]
 
 [[package]]
 name = "mesh-llm-host-runtime"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "argon2",
  "async-trait",
  "axum",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "chacha20poly1305",
  "chrono",
@@ -4647,7 +4927,6 @@ dependencies = [
  "http",
  "http-body-util",
  "httparse",
- "if-addrs",
  "iroh",
  "json5",
  "keyring",
@@ -4681,7 +4960,7 @@ dependencies = [
  "opentelemetry 0.31.0",
  "opentelemetry-otlp 0.31.1",
  "opentelemetry_sdk 0.31.0",
- "prost",
+ "prost 0.14.3",
  "rand 0.10.1",
  "regex-lite",
  "reqwest 0.12.28",
@@ -4695,6 +4974,7 @@ dependencies = [
  "serde_yaml",
  "sha2 0.10.9",
  "skippy-coordinator",
+ "skippy-ffi",
  "skippy-protocol",
  "skippy-runtime",
  "skippy-server",
@@ -4717,11 +4997,11 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-identity"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "argon2",
- "base64",
+ "base64 0.22.1",
  "chacha20poly1305",
  "chrono",
  "crypto_box",
@@ -4739,8 +5019,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-native-runtime"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "serde",
@@ -4750,8 +5030,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-node"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "mesh-llm-types",
@@ -4764,13 +5044,13 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-plugin"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "async-trait",
- "prost",
- "prost-build",
+ "prost 0.14.3",
+ "prost-build 0.14.3",
  "protoc-bin-vendored",
  "rmcp",
  "schemars",
@@ -4781,8 +5061,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-plugin-manager"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "dirs",
@@ -4792,6 +5072,7 @@ dependencies = [
  "reqwest 0.12.28",
  "serde",
  "serde_json",
+ "sha2 0.10.9",
  "tar",
  "tempfile",
  "zip",
@@ -4799,29 +5080,29 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-protocol"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "hex",
  "iroh",
- "prost",
+ "prost 0.14.3",
  "serde_json",
  "sha2 0.10.9",
 ]
 
 [[package]]
 name = "mesh-llm-routing"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "iroh",
 ]
 
 [[package]]
 name = "mesh-llm-runtime-install"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "dirs",
@@ -4843,8 +5124,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-sdk"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "mesh-llm-api-client",
@@ -4858,8 +5139,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-skills"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "dirs",
@@ -4869,8 +5150,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-system"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "chrono",
@@ -4892,8 +5173,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-types"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "hex",
  "serde",
@@ -4903,13 +5184,13 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-ui"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 
 [[package]]
 name = "mesh-mixture-of-agents"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "async-trait",
  "mesh-llm-guardrails",
@@ -4936,7 +5217,7 @@ version = "0.18.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1db0d8f1fc9e62caebd0319e11eaec5822b0186c171568f0480b46a0137f9108"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "evmap",
  "http-body-util",
  "hyper",
@@ -4974,6 +5255,28 @@ dependencies = [
  "sketches-ddsketch",
 ]
 
+[[package]]
+name = "miette"
+version = "7.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5f98efec8807c63c752b5bd61f862c165c115b0a35685bdcfd9238c7aeb592b7"
+dependencies = [
+ "cfg-if 1.0.4",
+ "miette-derive",
+ "unicode-width 0.1.14",
+]
+
+[[package]]
+name = "miette-derive"
+version = "7.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db5b29714e950dbb20d5e6f74f9dcec4edbcc1067bb7f8ed198c097b8c1a818b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "mime"
 version = "0.3.17"
@@ -5035,8 +5338,8 @@ dependencies = [
 
 [[package]]
 name = "model-artifact"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -5046,8 +5349,8 @@ dependencies = [
 
 [[package]]
 name = "model-hf"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -5064,8 +5367,8 @@ dependencies = [
 
 [[package]]
 name = "model-package"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "bytes",
@@ -5084,16 +5387,16 @@ dependencies = [
 
 [[package]]
 name = "model-ref"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "serde",
 ]
 
 [[package]]
 name = "model-resolver"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "model-artifact",
@@ -5119,6 +5422,28 @@ dependencies = [
  "uuid",
 ]
 
+[[package]]
+name = "monostate"
+version = "0.1.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3341a273f6c9d5bef1908f17b7267bbab0e95c9bf69a0d4dcf8e9e1b2c76ef67"
+dependencies = [
+ "monostate-impl",
+ "serde",
+ "serde_core",
+]
+
+[[package]]
+name = "monostate-impl"
+version = "0.1.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4db6d5580af57bf992f59068d4ea26fd518574ff48d7639b255a36f9de6e7e9"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "more-asserts"
 version = "0.3.1"
@@ -5225,6 +5550,21 @@ dependencies = [
  "tempfile",
 ]
 
+[[package]]
+name = "ndarray"
+version = "0.17.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "520080814a7a6b4a6e9070823bb24b4531daac8c4627e08ba5de8c5ef2f2752d"
+dependencies = [
+ "matrixmultiply",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "portable-atomic",
+ "portable-atomic-util",
+ "rawpointer",
+]
+
 [[package]]
 name = "ndk-context"
 version = "0.1.1"
@@ -5373,9 +5713,9 @@ dependencies = [
 
 [[package]]
 name = "nix"
-version = "0.31.3"
+version = "0.30.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d"
+checksum = "74523f3a35e05aba87a1d978330aef40f67b0304ac79c1c00b294c9830543db6"
 dependencies = [
  "bitflags 2.13.0",
  "cfg-if 1.0.4",
@@ -5384,8 +5724,20 @@ dependencies = [
 ]
 
 [[package]]
-name = "nom"
-version = "7.1.3"
+name = "nix"
+version = "0.31.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d"
+dependencies = [
+ "bitflags 2.13.0",
+ "cfg-if 1.0.4",
+ "cfg_aliases",
+ "libc",
+]
+
+[[package]]
+name = "nom"
+version = "7.1.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
 dependencies = [
@@ -5457,11 +5809,11 @@ dependencies = [
 
 [[package]]
 name = "nostr"
-version = "0.44.6"
+version = "0.44.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e826dd648489de2c5b293920e20b92932ef820302007c1987c758d4d06eeb2cf"
+checksum = "c7d3d987ea7078dc36947cde532637c472a229426702e4331dd7667325378bd9"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bech32",
  "bip39",
  "bitcoin_hashes",
@@ -5501,9 +5853,9 @@ dependencies = [
 
 [[package]]
 name = "nostr-relay-pool"
-version = "0.44.1"
+version = "0.44.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "91b2c039df4f96c4bf7dae52a74fd5516ad6dda83a11c0c69dea91b5255a4f37"
+checksum = "c85c54d6ca9aae4ae2bf19a7663ba9db5f45f783f1d24aff55f006386b8b99a1"
 dependencies = [
  "async-utility",
  "async-wsocket",
@@ -5812,8 +6164,8 @@ checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381"
 
 [[package]]
 name = "openai-frontend"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "async-trait",
  "axum",
@@ -5932,7 +6284,7 @@ dependencies = [
  "opentelemetry-http",
  "opentelemetry-proto 0.31.0",
  "opentelemetry_sdk 0.31.0",
- "prost",
+ "prost 0.14.3",
  "reqwest 0.12.28",
  "thiserror 2.0.18",
 ]
@@ -5947,7 +6299,7 @@ dependencies = [
  "opentelemetry 0.32.0",
  "opentelemetry-proto 0.32.0",
  "opentelemetry_sdk 0.32.1",
- "prost",
+ "prost 0.14.3",
  "thiserror 2.0.18",
  "tokio",
  "tonic",
@@ -5960,11 +6312,11 @@ version = "0.31.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a7175df06de5eaee9909d4805a3d07e28bb752c34cab57fa9cff549da596b30f"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "const-hex",
  "opentelemetry 0.31.0",
  "opentelemetry_sdk 0.31.0",
- "prost",
+ "prost 0.14.3",
  "serde",
  "serde_json",
  "tonic",
@@ -5979,7 +6331,7 @@ checksum = "56d658ba1faf63f7b9c492cfbe6e0ec365440a16132d3270c1065f7b33f1b638"
 dependencies = [
  "opentelemetry 0.32.0",
  "opentelemetry_sdk 0.32.1",
- "prost",
+ "prost 0.14.3",
  "tonic",
  "tonic-prost",
 ]
@@ -6023,6 +6375,15 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d"
 
+[[package]]
+name = "ordered-float"
+version = "2.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68f19d67e5a2795c94e73e0bb1cc1a7edeb2e28efd39e2e1c9b7a40c1108b11c"
+dependencies = [
+ "num-traits",
+]
+
 [[package]]
 name = "ordered-float"
 version = "4.6.0"
@@ -6061,6 +6422,24 @@ dependencies = [
  "pin-project-lite",
 ]
 
+[[package]]
+name = "ort"
+version = "2.0.0-rc.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7de3af33d24a745ffb8fab904b13478438d1cd52868e6f17735ef6e1f8bf133"
+dependencies = [
+ "ndarray",
+ "ort-sys",
+ "smallvec",
+ "tracing",
+]
+
+[[package]]
+name = "ort-sys"
+version = "2.0.0-rc.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7b497d21a8b6fbb4b5a544f8fadb77e801a09ae0add9e411d31c6f89e3c1e90"
+
 [[package]]
 name = "os_str_bytes"
 version = "6.6.1"
@@ -6185,6 +6564,16 @@ dependencies = [
  "hmac 0.12.1",
 ]
 
+[[package]]
+name = "pem"
+version = "3.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d30c53c26bc5b31a98cd02d20f25a7c8567146caf63ed593a9d87b2775291be"
+dependencies = [
+ "base64 0.22.1",
+ "serde_core",
+]
+
 [[package]]
 name = "pem-rfc7468"
 version = "1.0.0"
@@ -6242,6 +6631,16 @@ dependencies = [
  "pest",
 ]
 
+[[package]]
+name = "petgraph"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3672b37090dbd86368a4145bc067582552b29c27377cad4e0a306c97f9bd7772"
+dependencies = [
+ "fixedbitset 0.5.7",
+ "indexmap",
+]
+
 [[package]]
 name = "petgraph"
 version = "0.8.3"
@@ -6374,7 +6773,7 @@ version = "1.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "092791278e026273c1b65bbdcfbba3a300f2994c896bd01ab01da613c29c46f1"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "indexmap",
  "quick-xml 0.39.4",
  "serde",
@@ -6440,13 +6839,22 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "portable-atomic-util"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a106d1259c23fac8e543272398ae0e3c0b8d33c88ed73d0cc71b0f1d902618"
+dependencies = [
+ "portable-atomic",
+]
+
 [[package]]
 name = "portmapper"
 version = "0.19.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "eb3713e4977408279158444a18c1a01ac9bf2e7eaf1fbfd1a19ac9cd18d90721"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bytes",
  "derive_more",
  "hyper-util",
@@ -6616,6 +7024,16 @@ dependencies = [
  "unarray",
 ]
 
+[[package]]
+name = "prost"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2796faa41db3ec313a31f7624d9286acf277b52de526150b7e69f3debf891ee5"
+dependencies = [
+ "bytes",
+ "prost-derive 0.13.5",
+]
+
 [[package]]
 name = "prost"
 version = "0.14.3"
@@ -6623,7 +7041,27 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d2ea70524a2f82d518bce41317d0fae74151505651af45faf1ffbd6fd33f0568"
 dependencies = [
  "bytes",
- "prost-derive",
+ "prost-derive 0.14.3",
+]
+
+[[package]]
+name = "prost-build"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be769465445e8c1474e9c5dac2018218498557af32d9ed057325ec9a41ae81bf"
+dependencies = [
+ "heck",
+ "itertools",
+ "log",
+ "multimap",
+ "once_cell",
+ "petgraph 0.7.1",
+ "prettyplease",
+ "prost 0.13.5",
+ "prost-types 0.13.5",
+ "regex",
+ "syn 2.0.117",
+ "tempfile",
 ]
 
 [[package]]
@@ -6636,15 +7074,28 @@ dependencies = [
  "itertools",
  "log",
  "multimap",
- "petgraph",
+ "petgraph 0.8.3",
  "prettyplease",
- "prost",
- "prost-types",
+ "prost 0.14.3",
+ "prost-types 0.14.3",
  "regex",
  "syn 2.0.117",
  "tempfile",
 ]
 
+[[package]]
+name = "prost-derive"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a56d757972c98b346a9b766e3f02746cde6dd1cd1d1d563472929fdd74bec4d"
+dependencies = [
+ "anyhow",
+ "itertools",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "prost-derive"
 version = "0.14.3"
@@ -6658,13 +7109,35 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "prost-reflect"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b5edd582b62f5cde844716e66d92565d7faf7ab1445c8cebce6e00fba83ddb2"
+dependencies = [
+ "logos",
+ "miette",
+ "once_cell",
+ "prost 0.13.5",
+ "prost-types 0.13.5",
+]
+
+[[package]]
+name = "prost-types"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52c2c1bf36ddb1a1c396b3601a3cec27c2462e45f07c386894ec3ccf5332bd16"
+dependencies = [
+ "prost 0.13.5",
+]
+
 [[package]]
 name = "prost-types"
 version = "0.14.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8991c4cbdb8bc5b11f0b074ffe286c30e523de90fee5ba8132f1399f23cb3dd7"
 dependencies = [
- "prost",
+ "prost 0.14.3",
 ]
 
 [[package]]
@@ -6731,6 +7204,33 @@ version = "3.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "95067976aca6421a523e491fce939a3e65249bac4b977adee0ee9771568e8aa3"
 
+[[package]]
+name = "protox"
+version = "0.7.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6f352af331bf637b8ecc720f7c87bf903d2571fa2e14a66e9b2558846864b54a"
+dependencies = [
+ "bytes",
+ "miette",
+ "prost 0.13.5",
+ "prost-reflect",
+ "prost-types 0.13.5",
+ "protox-parse",
+ "thiserror 1.0.69",
+]
+
+[[package]]
+name = "protox-parse"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a3a462d115462c080ae000c29a47f0b3985737e5d3a995fcdbcaa5c782068dde"
+dependencies = [
+ "logos",
+ "miette",
+ "prost-types 0.13.5",
+ "thiserror 1.0.69",
+]
+
 [[package]]
 name = "pulldown-cmark"
 version = "0.13.4"
@@ -7036,7 +7536,7 @@ dependencies = [
  "thiserror 2.0.18",
  "unicode-segmentation",
  "unicode-truncate",
- "unicode-width",
+ "unicode-width 0.2.2",
 ]
 
 [[package]]
@@ -7099,7 +7599,7 @@ dependencies = [
  "strum",
  "time",
  "unicode-segmentation",
- "unicode-width",
+ "unicode-width 0.2.2",
 ]
 
 [[package]]
@@ -7111,6 +7611,43 @@ dependencies = [
  "bitflags 2.13.0",
 ]
 
+[[package]]
+name = "rawpointer"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3"
+
+[[package]]
+name = "rayon"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+
+[[package]]
+name = "rayon-cond"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2964d0cf57a3e7a06e8183d14a8b527195c706b7983549cd5462d5aa3747438f"
+dependencies = [
+ "either",
+ "itertools",
+ "rayon",
+]
+
+[[package]]
+name = "rayon-core"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+
 [[package]]
 name = "redb"
 version = "3.1.3"
@@ -7232,7 +7769,7 @@ version = "0.12.28"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bytes",
  "encoding_rs",
  "futures-channel",
@@ -7280,7 +7817,7 @@ version = "0.13.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "219c5811de6525e5416c7d5d53bb656d3afdbc6c5af816e0802bcfa42dbdc1c3"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bytes",
  "encoding_rs",
  "futures-core",
@@ -7365,12 +7902,12 @@ dependencies = [
 
 [[package]]
 name = "rmcp"
-version = "1.7.0"
+version = "1.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0810a9f717d9828f475fe1f629f4c305c8464b7f496c3a854b58d29e65f4058e"
+checksum = "1d1f571c72940a19d9532fe52dbea8bc9912bf1d766c2970bb824056b86f3f59"
 dependencies = [
  "async-trait",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "chrono",
  "futures",
@@ -7398,9 +7935,9 @@ dependencies = [
 
 [[package]]
 name = "rmcp-macros"
-version = "1.7.0"
+version = "1.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6aefac48c364756e97f04c0401ba3231e8607882c7c1d92da0437dc16307904d"
+checksum = "1aad0035b69380782d78ea95b508327e6deaa2235909053e596eea8f27b5e1d5"
 dependencies = [
  "darling 0.23.0",
  "proc-macro2",
@@ -7438,7 +7975,7 @@ dependencies = [
  "async-trait",
  "aws-creds",
  "aws-region",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "cfg-if 1.0.4",
  "futures-util",
@@ -7762,6 +8299,15 @@ dependencies = [
  "cc",
 ]
 
+[[package]]
+name = "secrecy"
+version = "0.10.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e891af845473308773346dc847b2c23ee78fe442e0472ac50e22a18a93d3ae5a"
+dependencies = [
+ "zeroize",
+]
+
 [[package]]
 name = "secret-service"
 version = "4.0.0"
@@ -7839,6 +8385,18 @@ version = "0.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cd0b0ec5f1c1ca621c432a25813d8d60c88abe6d3e08a3eb9cf37d97a0fe3d73"
 
+[[package]]
+name = "sentencepiece-model"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40b87bf750a8322c3236d7aa63c1f4a6862187d00d2d8b038e1dfe263bfe43ec"
+dependencies = [
+ "miette",
+ "prost 0.13.5",
+ "prost-build 0.13.5",
+ "protox",
+]
+
 [[package]]
 name = "serde"
 version = "1.0.228"
@@ -7849,6 +8407,16 @@ dependencies = [
  "serde_derive",
 ]
 
+[[package]]
+name = "serde-value"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f3a1a3341211875ef120e117ea7fd5228530ae7e7036a779fdc9117be6b3282c"
+dependencies = [
+ "ordered-float 2.10.1",
+ "serde",
+]
+
 [[package]]
 name = "serde_bytes"
 version = "0.11.19"
@@ -8049,6 +8617,28 @@ dependencies = [
  "os_str_bytes",
 ]
 
+[[package]]
+name = "sherpa-onnx"
+version = "1.13.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b142d3f255cb4e4b7808ea25869db6f5714e0a3550da355234483b4db552055"
+dependencies = [
+ "serde",
+ "serde_json",
+ "sherpa-onnx-sys",
+]
+
+[[package]]
+name = "sherpa-onnx-sys"
+version = "1.13.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ffc951af03dc0653c0622158ca8a585a6f2bc43b7b06048cf0e5b5020005c227"
+dependencies = [
+ "bzip2",
+ "tar",
+ "ureq",
+]
+
 [[package]]
 name = "shlex"
 version = "1.3.0"
@@ -8150,8 +8740,8 @@ checksum = "0c6f73aeb92d671e0cc4dca167e59b2deb6387c375391bc99ee743f326994a2b"
 
 [[package]]
 name = "skippy-cache"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "blake3",
@@ -8160,40 +8750,40 @@ dependencies = [
 
 [[package]]
 name = "skippy-coordinator"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "thiserror 2.0.18",
 ]
 
 [[package]]
 name = "skippy-ffi"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "libloading",
 ]
 
 [[package]]
 name = "skippy-metrics"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 
 [[package]]
 name = "skippy-protocol"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
- "prost",
- "prost-build",
+ "prost 0.14.3",
+ "prost-build 0.14.3",
  "protoc-bin-vendored",
  "serde",
 ]
 
 [[package]]
 name = "skippy-runtime"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "libc",
@@ -8206,13 +8796,14 @@ dependencies = [
 
 [[package]]
 name = "skippy-server"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
+ "ahash",
  "anyhow",
  "async-trait",
  "axum",
- "base64",
+ "base64 0.22.1",
  "blake3",
  "clap",
  "futures-util",
@@ -8234,8 +8825,8 @@ dependencies = [
 
 [[package]]
 name = "skippy-topology"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.73.1#43103c5c40292be688ac0261129bcbab0e7b9132"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "serde",
  "serde_json",
@@ -8319,6 +8910,18 @@ dependencies = [
  "der",
 ]
 
+[[package]]
+name = "spm_precompiled"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5851699c4033c63636f7ea4cf7b7c1f1bf06d0cc03cfb42e711de5a5c46cf326"
+dependencies = [
+ "base64 0.13.1",
+ "nom",
+ "serde",
+ "unicode-segmentation",
+]
+
 [[package]]
 name = "sprig"
 version = "0.1.0"
@@ -8347,7 +8950,7 @@ version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "05b44e85bf579a8eeb4ceaa77a3a523baf2bf0e9bac7e40f405d537b5d2d5ccb"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bytes",
  "cfg-if 1.0.4",
  "chrono",
@@ -8453,7 +9056,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "87a2bdd6e83f6b3ea525ca9fee568030508b58355a43d0b2c1674d5f79dcd65e"
 dependencies = [
  "atoi",
- "base64",
+ "base64 0.22.1",
  "bitflags 2.13.0",
  "byteorder",
  "chrono",
@@ -8594,6 +9197,164 @@ version = "0.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a7973cce6668464ea31f176d85b13c7ab3bba2cb3b77a2ed26abd7801688010a"
 
+[[package]]
+name = "symphonia"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5773a4c030a19d9bfaa090f49746ff35c75dfddfa700df7a5939d5e076a57039"
+dependencies = [
+ "lazy_static",
+ "symphonia-bundle-flac",
+ "symphonia-bundle-mp3",
+ "symphonia-codec-aac",
+ "symphonia-codec-alac",
+ "symphonia-codec-pcm",
+ "symphonia-codec-vorbis",
+ "symphonia-core",
+ "symphonia-format-isomp4",
+ "symphonia-format-ogg",
+ "symphonia-format-riff",
+ "symphonia-metadata",
+]
+
+[[package]]
+name = "symphonia-bundle-flac"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c91565e180aea25d9b80a910c546802526ffd0072d0b8974e3ebe59b686c9976"
+dependencies = [
+ "log",
+ "symphonia-core",
+ "symphonia-metadata",
+ "symphonia-utils-xiph",
+]
+
+[[package]]
+name = "symphonia-bundle-mp3"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4872dd6bb56bf5eac799e3e957aa1981086c3e613b27e0ac23b176054f7c57ed"
+dependencies = [
+ "lazy_static",
+ "log",
+ "symphonia-core",
+ "symphonia-metadata",
+]
+
+[[package]]
+name = "symphonia-codec-aac"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4c263845aa86881416849c1729a54c7f55164f8b96111dba59de46849e73a790"
+dependencies = [
+ "lazy_static",
+ "log",
+ "symphonia-core",
+]
+
+[[package]]
+name = "symphonia-codec-alac"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8413fa754942ac16a73634c9dfd1500ed5c61430956b33728567f667fdd393ab"
+dependencies = [
+ "log",
+ "symphonia-core",
+]
+
+[[package]]
+name = "symphonia-codec-pcm"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e89d716c01541ad3ebe7c91ce4c8d38a7cf266a3f7b2f090b108fb0cb031d95"
+dependencies = [
+ "log",
+ "symphonia-core",
+]
+
+[[package]]
+name = "symphonia-codec-vorbis"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f025837c309cd69ffef572750b4a2257b59552c5399a5e49707cc5b1b85d1c73"
+dependencies = [
+ "log",
+ "symphonia-core",
+ "symphonia-utils-xiph",
+]
+
+[[package]]
+name = "symphonia-core"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea00cc4f79b7f6bb7ff87eddc065a1066f3a43fe1875979056672c9ef948c2af"
+dependencies = [
+ "arrayvec",
+ "bitflags 1.3.2",
+ "bytemuck",
+ "lazy_static",
+ "log",
+]
+
+[[package]]
+name = "symphonia-format-isomp4"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "243739585d11f81daf8dac8d9f3d18cc7898f6c09a259675fc364b382c30e0a5"
+dependencies = [
+ "encoding_rs",
+ "log",
+ "symphonia-core",
+ "symphonia-metadata",
+ "symphonia-utils-xiph",
+]
+
+[[package]]
+name = "symphonia-format-ogg"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b4955c67c1ed3aa8ae8428d04ca8397fbef6a19b2b051e73b5da8b1435639cb"
+dependencies = [
+ "log",
+ "symphonia-core",
+ "symphonia-metadata",
+ "symphonia-utils-xiph",
+]
+
+[[package]]
+name = "symphonia-format-riff"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2d7c3df0e7d94efb68401d81906eae73c02b40d5ec1a141962c592d0f11a96f"
+dependencies = [
+ "extended",
+ "log",
+ "symphonia-core",
+ "symphonia-metadata",
+]
+
+[[package]]
+name = "symphonia-metadata"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36306ff42b9ffe6e5afc99d49e121e0bd62fe79b9db7b9681d48e29fa19e6b16"
+dependencies = [
+ "encoding_rs",
+ "lazy_static",
+ "log",
+ "symphonia-core",
+]
+
+[[package]]
+name = "symphonia-utils-xiph"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee27c85ab799a338446b68eec77abf42e1a6f1bb490656e121c6e27bfbab9f16"
+dependencies = [
+ "symphonia-core",
+ "symphonia-metadata",
+]
+
 [[package]]
 name = "syn"
 version = "1.0.109"
@@ -8691,7 +9452,7 @@ version = "1.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fce91f2f0ec87dff7e6bcbbeb267439aa1188703003c6055193c821487400432"
 dependencies = [
- "unicode-width",
+ "unicode-width 0.2.2",
 ]
 
 [[package]]
@@ -8765,9 +9526,9 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4676b37242ccbd1aabf56edb093a4827dc49086c0ffd764a5705899e0f35f8f7"
 dependencies = [
  "anyhow",
- "base64",
+ "base64 0.22.1",
  "bitflags 2.13.0",
- "fancy-regex",
+ "fancy-regex 0.11.0",
  "filedescriptor",
  "finl_unicode",
  "fixedbitset 0.4.2",
@@ -8917,6 +9678,39 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
+[[package]]
+name = "tokenizers"
+version = "0.22.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b238e22d44a15349529690fb07bd645cf58149a1b1e44d6cb5bd1641ff1a6223"
+dependencies = [
+ "ahash",
+ "aho-corasick",
+ "compact_str 0.9.1",
+ "dary_heap",
+ "derive_builder",
+ "esaxx-rs",
+ "fancy-regex 0.14.0",
+ "getrandom 0.3.4",
+ "itertools",
+ "log",
+ "macro_rules_attribute",
+ "monostate",
+ "paste",
+ "rand 0.9.4",
+ "rayon",
+ "rayon-cond",
+ "regex",
+ "regex-syntax",
+ "serde",
+ "serde_json",
+ "spm_precompiled",
+ "thiserror 2.0.18",
+ "unicode-normalization-alignments",
+ "unicode-segmentation",
+ "unicode_categories",
+]
+
 [[package]]
 name = "tokio"
 version = "1.52.3"
@@ -9052,7 +9846,7 @@ version = "0.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dad543404f98bfc969aeb71994105c592acfc6c43323fddcd016bb208d1c65cb"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bytes",
  "futures-core",
  "futures-sink",
@@ -9153,7 +9947,7 @@ checksum = "ac2a5518c70fa84342385732db33fb3f44bc4cc748936eb5833d2df34d6445ef"
 dependencies = [
  "async-trait",
  "axum",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "h2",
  "http",
@@ -9182,7 +9976,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "50849f68853be452acf590cde0b146665b8d507b3b8af17261df47e02c209ea0"
 dependencies = [
  "bytes",
- "prost",
+ "prost 0.14.3",
  "tonic",
 ]
 
@@ -9192,8 +9986,8 @@ version = "0.14.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "73ab1b02061f83d519bba3caa167f88f261ef05720ab8ebc954ade70de3348e8"
 dependencies = [
- "prost",
- "prost-types",
+ "prost 0.14.3",
+ "prost-types 0.14.3",
  "tonic",
 ]
 
@@ -9223,6 +10017,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"
 dependencies = [
  "async-compression",
+ "base64 0.22.1",
  "bitflags 2.13.0",
  "bytes",
  "futures-core",
@@ -9482,6 +10277,15 @@ dependencies = [
  "tinyvec",
 ]
 
+[[package]]
+name = "unicode-normalization-alignments"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43f613e4fa046e69818dd287fdc4bc78175ff20331479dab6e1b0f98d57062de"
+dependencies = [
+ "smallvec",
+]
+
 [[package]]
 name = "unicode-properties"
 version = "0.1.4"
@@ -9502,9 +10306,15 @@ checksum = "16b380a1238663e5f8a691f9039c73e1cdae598a30e9855f541d29b08b53e9a5"
 dependencies = [
  "itertools",
  "unicode-segmentation",
- "unicode-width",
+ "unicode-width 0.2.2",
 ]
 
+[[package]]
+name = "unicode-width"
+version = "0.1.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7dd6e30e90baa6f72411720665d41d89b9a3d039dc45b8faea1ddd07f617f6af"
+
 [[package]]
 name = "unicode-width"
 version = "0.2.2"
@@ -9517,6 +10327,12 @@ version = "0.2.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
 
+[[package]]
+name = "unicode_categories"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39ec24b3121d976906ece63c9daad25b85969647682eee313cb5779fdd69e14e"
+
 [[package]]
 name = "universal-hash"
 version = "0.5.1"
@@ -9539,6 +10355,22 @@ version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
 
+[[package]]
+name = "ureq"
+version = "2.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "02d1a66277ed75f640d608235660df48c8e3c19f3b4edb6a263315626cc3c01d"
+dependencies = [
+ "base64 0.22.1",
+ "flate2",
+ "log",
+ "once_cell",
+ "rustls",
+ "rustls-pki-types",
+ "url",
+ "webpki-roots 0.26.11",
+]
+
 [[package]]
 name = "url"
 version = "2.5.8"
@@ -10530,7 +11362,7 @@ checksum = "3e1e496dcbe6a09017acdfaf48e1a646735e7ff5b2a49e2c7e081cca77a59bc8"
 dependencies = [
  "anyhow",
  "async-trait",
- "base64",
+ "base64 0.22.1",
  "bytes",
  "clap",
  "crc32fast",
@@ -10567,7 +11399,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cb838aa8eb67d730af301584cf003caad407487606058292a6750711b603fbee"
 dependencies = [
  "async-trait",
- "base64",
+ "base64 0.22.1",
  "blake3",
  "bytemuck",
  "bytes",
diff --git a/Cargo.toml b/Cargo.toml
index 3ac7ee4cce..cc1dd0f9df 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -26,6 +26,8 @@ members = [
     "crates/buzz-pair-relay",
     "crates/buzz-relay-mesh",
     "crates/buzz-dev-mcp",
+    "crates/buzz-voice",
+    "crates/buzz-backend-kubernetes",
     "examples/countdown-bot",
 ]
 exclude = ["desktop/src-tauri"]
@@ -57,6 +59,13 @@ sqlx = { version = "0.9", features = [
 redis        = { version = "1.0", features = ["tokio-comp", "connection-manager", "tokio-rustls-comp"] }
 deadpool-redis = { version = "0.23", features = ["rt_tokio_1"] }
 
+# Kubernetes (buzz-backend-kubernetes provider). No `ring` feature here: the
+# process-level CryptoProvider is installed explicitly at startup, matching
+# buzz-cli/buzz-acp/buzz-admin/buzz-relay/buzz-dev-mcp — see the comment on the
+# crate's own rustls dependency.
+kube = { version = "2.0", default-features = false, features = ["client", "rustls-tls"] }
+k8s-openapi = { version = "0.26", features = ["v1_31"] }
+
 # Nostr
 nostr = { version = "0.44", features = ["nip44", "nip98"] }
 
diff --git a/Dockerfile.sprig b/Dockerfile.sprig
new file mode 100644
index 0000000000..160e0b5662
--- /dev/null
+++ b/Dockerfile.sprig
@@ -0,0 +1,44 @@
+# syntax=docker/dockerfile:1.7
+# Multi-arch is produced by building this file on native amd64 and arm64 runners.
+# Keep both bases pinned to manifest-list digests so either architecture resolves
+# to immutable source bytes.
+FROM rust:1.95-alpine3.22@sha256:064dfc925d68d1a63f4fd2871bd7dc6e6ea56692989a487185855d62885d90aa AS builder
+
+RUN apk add --no-cache \
+      build-base \
+      cmake \
+      git \
+      musl-dev \
+      openssl-dev \
+      openssl-libs-static \
+      perl \
+      pkgconf \
+      protoc
+WORKDIR /build
+COPY . .
+RUN cargo build --locked --profile sprig -p sprig \
+    && strip target/sprig/sprig
+
+FROM alpine:3.22@sha256:14358309a308569c32bdc37e2e0e9694be33a9d99e68afb0f5ff33cc1f695dce
+
+RUN apk add --no-cache bash ca-certificates curl git \
+    && adduser -D -h /home/agent agent \
+    && install -d -o agent -g agent /workspace /home/agent \
+    && git config --system gpg.format x509 \
+    && git config --system gpg.x509.program /usr/local/bin/git-sign-nostr \
+    && git config --system commit.gpgSign true \
+    && git config --system tag.gpgSign true
+
+COPY --from=builder --chmod=0755 /build/target/sprig/sprig /usr/local/bin/sprig
+COPY --chmod=0755 scripts/sprig-entrypoint.sh /usr/local/bin/sprig-entrypoint
+RUN for name in \
+      buzz-acp buzz-agent buzz-dev-mcp rg tree buzz \
+      git-credential-nostr git-sign-nostr; do \
+        ln -s sprig "/usr/local/bin/$name"; \
+    done
+
+ENV HOME=/home/agent \
+    PATH=/usr/local/bin:/usr/local/sbin:/usr/sbin:/usr/bin:/sbin:/bin
+WORKDIR /home/agent
+USER agent
+ENTRYPOINT ["/usr/local/bin/sprig-entrypoint"]
diff --git a/Justfile b/Justfile
index bcef8983bc..d6e86c8d09 100644
--- a/Justfile
+++ b/Justfile
@@ -155,7 +155,11 @@ _ensure-sidecar-stubs:
     set -euo pipefail
     TARGET=$(rustc -vV | sed -n 's|host: ||p')
     mkdir -p desktop/src-tauri/binaries
-    for bin in buzz-acp buzz-agent buzz-dev-mcp git-credential-nostr buzz; do
+    SIDECARS=(buzz-acp buzz-agent buzz-dev-mcp git-credential-nostr buzz)
+    if [[ "$TARGET" != *windows* ]]; then
+        SIDECARS+=(buzz-backend-kubernetes)
+    fi
+    for bin in "${SIDECARS[@]}"; do
         touch "desktop/src-tauri/binaries/${bin}-${TARGET}"
     done
 
@@ -236,6 +240,9 @@ desktop-release-build target="aarch64-apple-darwin":
     mkdir -p desktop/src-tauri/binaries
     touch "desktop/src-tauri/binaries/buzz-acp-$TARGET"
     touch "desktop/src-tauri/binaries/buzz-agent-$TARGET"
+    if [[ "$TARGET" != *windows* ]]; then
+        touch "desktop/src-tauri/binaries/buzz-backend-kubernetes-$TARGET"
+    fi
     touch "desktop/src-tauri/binaries/buzz-dev-mcp-$TARGET"
     touch "desktop/src-tauri/binaries/git-credential-nostr-$TARGET"
     touch "desktop/src-tauri/binaries/buzz-$TARGET"
@@ -274,8 +281,11 @@ test:
 # Run unit tests only (no infra needed)
 test-unit:
     #!/usr/bin/env bash
+    set -euo pipefail
     if command -v cargo-nextest &>/dev/null; then
         cargo nextest run -p buzz-core -p buzz-auth --lib
+        cargo nextest run -p buzz-voice --lib
+        cargo nextest run -p buzz-cli
         # buzz-db migrator/lint tests: pure SQL-parsing unit tests (no infra).
         # They guard the embedded-migrator invariant (exactly the consolidated
         # 0001; cutover/backfill stays an operator script, not startup state)
@@ -291,6 +301,12 @@ test-unit:
         # Gateway unit and black-box HTTP tests are infra-free. Postgres-backed
         # contract/race tests run in the dedicated CI job below.
         cargo nextest run -p buzz-push-gateway
+        # Kubernetes backend provider: the decision layers (state machine, GC
+        # planner, env precedence, naming, wire) are pure functions with a fake
+        # substrate, so they belong in the unit job. Enumerated explicitly
+        # because nothing in CI runs `cargo test --workspace` — workspace
+        # membership alone buys clippy/check, not a single executed test.
+        cargo nextest run -p buzz-backend-kubernetes
     else
         ./scripts/run-tests.sh unit
     fi
@@ -428,7 +444,7 @@ dev *ARGS: bootstrap _ensure-sidecar-stubs _ensure-migrations
             fi
         done
     fi
-    cargo build -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr -p buzz-relay
+    cargo build -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr -p buzz-relay
     if [[ -n "{{mesh}}" ]]; then
         export MESH_LLM_NATIVE_RUNTIME_CACHE_DIR="$(./scripts/ensure-mesh-native-runtime.sh)"
     fi
@@ -475,10 +491,10 @@ desktop-standalone *ARGS: _ensure-sidecar-stubs
     #!/usr/bin/env bash
     set -euo pipefail
     export PATH="{{justfile_directory()}}/bin:$PATH"
-    cargo build -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
+    cargo build -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
     TARGET=$(rustc -vV | sed -n 's|host: ||p')
     TARGET_DIR=$(cargo metadata --format-version 1 --no-deps | node -p "JSON.parse(require('fs').readFileSync(0, 'utf8')).target_directory")
-    for bin in buzz-acp buzz-agent buzz-dev-mcp git-credential-nostr buzz; do
+    for bin in buzz-acp buzz-agent buzz-backend-kubernetes buzz-dev-mcp git-credential-nostr buzz; do
         cp "${TARGET_DIR}/debug/${bin}" "desktop/src-tauri/binaries/${bin}-${TARGET}"
         chmod +x "desktop/src-tauri/binaries/${bin}-${TARGET}"
     done
@@ -504,17 +520,26 @@ staging *ARGS: bootstrap _ensure-sidecar-stubs
     set -euo pipefail
     export PATH="{{justfile_directory()}}/bin:$PATH"
     pnpm install  # unconditional: staging must always start with a clean dep tree
-    cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
+    cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
     FEATURES=()
     if [[ -n "{{mesh}}" ]]; then
         FEATURES=(--features mesh-llm)
         export MESH_LLM_NATIVE_RUNTIME_CACHE_DIR="$(./scripts/ensure-mesh-native-runtime.sh)"
     fi
-    # Replace the 0-byte sidecar stub with the real CLI binary so tauri dev picks it up.
+    # Replace 0-byte sidecar stubs with real binaries so tauri dev picks them up.
+    # buzz: the CLI sidecar. buzz-backend-kubernetes: provider discovery scans the
+    # exe dir for executable buzz-backend-* files, so the non-executable stub that
+    # tauri dev copies next to the exe would hide the provider from "Run on".
     TARGET=$(rustc -vV | sed -n 's|host: ||p')
     TARGET_DIR=$(cargo metadata --format-version 1 --no-deps | node -p "JSON.parse(require('fs').readFileSync(0, 'utf8')).target_directory")
-    cp "${TARGET_DIR}/release/buzz" "desktop/src-tauri/binaries/buzz-${TARGET}"
-    chmod +x "desktop/src-tauri/binaries/buzz-${TARGET}"
+    STAGING_SIDECARS=(buzz)
+    if [[ "$TARGET" != *windows* ]]; then
+        STAGING_SIDECARS+=(buzz-backend-kubernetes)
+    fi
+    for bin in "${STAGING_SIDECARS[@]}"; do
+        cp "${TARGET_DIR}/release/${bin}" "desktop/src-tauri/binaries/${bin}-${TARGET}"
+        chmod +x "desktop/src-tauri/binaries/${bin}-${TARGET}"
+    done
     cd {{desktop_dir}}
     export BUZZ_RELAY_URL="wss://sprout-oss.stage.blox.sqprod.co"
     source ../scripts/instance-env.sh
@@ -531,17 +556,26 @@ production *ARGS: bootstrap _ensure-sidecar-stubs
     set -euo pipefail
     export PATH="{{justfile_directory()}}/bin:$PATH"
     pnpm install  # unconditional: production must always start with a clean dep tree
-    cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
+    cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
     FEATURES=()
     if [[ -n "{{mesh}}" ]]; then
         FEATURES=(--features mesh-llm)
         export MESH_LLM_NATIVE_RUNTIME_CACHE_DIR="$(./scripts/ensure-mesh-native-runtime.sh)"
     fi
-    # Replace the 0-byte sidecar stub with the real CLI binary so tauri dev picks it up.
+    # Replace 0-byte sidecar stubs with real binaries so tauri dev picks them up.
+    # buzz: the CLI sidecar. buzz-backend-kubernetes: provider discovery scans the
+    # exe dir for executable buzz-backend-* files, so the non-executable stub that
+    # tauri dev copies next to the exe would hide the provider from "Run on".
     TARGET=$(rustc -vV | sed -n 's|host: ||p')
     TARGET_DIR=$(cargo metadata --format-version 1 --no-deps | node -p "JSON.parse(require('fs').readFileSync(0, 'utf8')).target_directory")
-    cp "${TARGET_DIR}/release/buzz" "desktop/src-tauri/binaries/buzz-${TARGET}"
-    chmod +x "desktop/src-tauri/binaries/buzz-${TARGET}"
+    PRODUCTION_SIDECARS=(buzz)
+    if [[ "$TARGET" != *windows* ]]; then
+        PRODUCTION_SIDECARS+=(buzz-backend-kubernetes)
+    fi
+    for bin in "${PRODUCTION_SIDECARS[@]}"; do
+        cp "${TARGET_DIR}/release/${bin}" "desktop/src-tauri/binaries/${bin}-${TARGET}"
+        chmod +x "desktop/src-tauri/binaries/${bin}-${TARGET}"
+    done
     cd {{desktop_dir}}
     export BUZZ_RELAY_URL="wss://buzz.block.builderlab.xyz"
     source ../scripts/instance-env.sh
@@ -620,6 +654,11 @@ mobile-check:
 mobile-test:
     unset GIT_DIR GIT_WORK_TREE; cd {{mobile_dir}} && flutter test
 
+# Regenerate the emoji dataset asset from desktop's emoji-mart install.
+# Output is committed — rerun after bumping @emoji-mart/data.
+mobile-emoji-data:
+    node {{mobile_dir}}/scripts/generate-emoji-data.mjs
+
 # Compile an unsigned Android debug APK (worktree-aware debug identity)
 mobile-build-android:
     ./scripts/mobile-worktree-overrides.sh
@@ -719,7 +758,7 @@ bump-relay-version version:
     cargo update -p buzz-relay
     echo "Bumped buzz-relay to {{ version }} and regenerated Cargo.lock"
 
-# Open or update the desktop release PR (signed desktop app)
+# Open or update the desktop release PR from an immutable origin/main snapshot
 release-desktop *ARGS:
     #!/usr/bin/env bash
     set -euo pipefail
@@ -729,7 +768,7 @@ release-desktop *ARGS:
     else
         VERSION="$ARG"
     fi
-    just _release-pr desktop "$VERSION"
+    scripts/prepare-desktop-release.sh "$VERSION"
 
 # Open or update the relay release PR (ghcr.io/block/buzz image)
 release-relay *ARGS:
diff --git a/NOSTR.md b/NOSTR.md
index 59df31b991..cce70f2f77 100644
--- a/NOSTR.md
+++ b/NOSTR.md
@@ -39,7 +39,7 @@ just relay &                         # relay on :3000
 PGPASSWORD=buzz_dev psql -h localhost -U buzz -d buzz -c \
   "INSERT INTO pubkey_allowlist (pubkey) VALUES (decode('<64-char-hex-pubkey>', 'hex'))"
 
-# 5. Connect any NIP-29 + NIP-42 client to ws://localhost:3000
+# 4. Connect any NIP-29 + NIP-42 client to ws://localhost:3000
 ```
 
 ### What Works
@@ -163,6 +163,10 @@ nak req -k 9 --tag "h=<channel-uuid>" --stream \
 nak event -k 7 -c "+" --tag "h=<channel-uuid>" --tag "e=<message-event-id>" \
   --auth --sec <privkey> ws://localhost:3000
 
+# Subscribe to reactions to channel messages — include #h for live delivery (see note below)
+nak req -k 7 --tag "h=<channel-uuid>" --stream \
+  --auth --sec <privkey> ws://localhost:3000
+
 # Delete a message (#h optional; #e required; must be self-authored)
 nak event -k 5 -c "reason" --tag "h=<channel-uuid>" --tag "e=<message-event-id>" \
   --auth --sec <privkey> ws://localhost:3000
@@ -185,6 +189,14 @@ nak req -k 1059 --tag "p=<your-hex-pubkey>" \
   --auth --sec <privkey> ws://localhost:3000
 ```
 
+> **Note:** The relay derives a reaction's channel from its `#e` target (client `#h` is
+> ignored for channel determination). Reactions to channel-scoped events are therefore
+> channel-scoped. Live fan-out keeps channel-scoped and global subscriptions strictly
+> separate, which means a kinds-only subscription (`{"kinds":[7]}`) receives none of
+> those reactions — subscribe with `{"kinds":[7],"#h":["<channel-uuid>"]}` instead.
+> `#h` matching works whether or not the signed reaction carries an `h` tag: explicit
+> `h` tags are matched directly, and tagless reactions match via their stored channel.
+
 ### Tested Clients (Direct)
 
 | Client | Platform | Evidence | Notes |
@@ -354,3 +366,7 @@ but only admins/owners can set it. Full spec:
 ---
 
 ## Further Reading
+
+- [nostr-protocol/nips](https://github.com/nostr-protocol/nips) — the upstream NIP specifications (NIP-01, NIP-29, NIP-42, and the other NIPs referenced throughout this guide).
+- [`docs/nips/`](docs/nips/) — Buzz's own NIP extension documents.
+- [`ARCHITECTURE.md`](ARCHITECTURE.md) — event kinds, wire protocol, and relay internals.
diff --git a/README.md b/README.md
index 72af92ce13..56439f00bc 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,7 @@
   <a href="VISION_PROJECTS.md">Forge</a> ·
   <a href="VISION_AGENT.md">Agents</a> ·
   <a href="ARCHITECTURE.md">Architecture</a> ·
+  <a href="RELEASING.md">Releasing</a> ·
   <a href="LICENSE">Apache 2.0</a>
 </p>
 
@@ -115,10 +116,30 @@ New to Buzz? Pick the path that matches you.
 
 ### I just want to try the app
 
-Grab a packaged build from the [latest release](https://github.com/block/buzz/releases/latest) — macOS (`.dmg`), Linux (`.AppImage` / `.deb`), or Windows (`.exe`). Install it like any other app.
+Grab a packaged build from the [latest release](https://github.com/block/buzz/releases/latest):
+
+| Platform | File |
+|---|---|
+| macOS (Apple Silicon) | `Buzz_<version>_aarch64.dmg` |
+| macOS (Intel) | `Buzz_<version>_x64.dmg` |
+| Linux (x86_64) | `Buzz_<version>_amd64.AppImage` or `Buzz_<version>_amd64.deb` |
+| Windows (x64) | `Buzz_<version>_x64-setup_alpha-unsigned.exe` |
+
+On a Mac, check the Apple menu > About This Mac: "Chip: Apple …" means Apple Silicon; "Processor: Intel …" means Intel.
+
+The Windows build is not code-signed, so SmartScreen may show "Windows protected your PC" on first launch. If available, click **More info**, then **Run anyway**.
+
 
 By default the app connects to `ws://localhost:3000`. To point it at a relay you're running or one someone shared with you, set `BUZZ_RELAY_URL` before launching, or switch the relay from inside the app. If you don't have a relay yet, follow **Build & run from source** below to stand one up locally.
 
+### I want my own hosted relay
+
+To run a relay for your team without managing servers, you can deploy one to Railway in a click:
+
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/buzz-relay-block)
+
+See [here](https://engineering.block.xyz/blog/run-your-own-buzz-relay) for details.
+
 ### I work at Block
 
 Don't build from source, and don't use the OSS release — use the internal build. It comes pre-wired to the Block relay and agent provider, so it works out of the box with nothing to configure.
diff --git a/RELEASING.md b/RELEASING.md
index 063b813e2c..e729f8b50c 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -5,7 +5,7 @@ Mobile uses immutable release-candidate tags cut directly from remote `main`:
 
 | Lane | Entry point | Artifact |
 |------|-------------|----------|
-| Desktop | `just release-desktop` | Signed desktop app (macOS/Linux) |
+| Desktop | `just release-desktop <version>` | Packaged desktop app (signed/notarized macOS, unsigned Windows, and Linux) |
 | Relay | `just release-relay` | `ghcr.io/block/buzz` container image |
 | Mobile | `scripts/mobile-release.sh candidate X.Y.Z` | Exact `mobile-vX.Y.Z-rc.N` source identity |
 
@@ -16,13 +16,17 @@ remains manual because OSS CI cannot trigger private CI.
 
 ## Quick Start
 
+Prepare desktop releases locally from an up-to-date, clean `main` checkout:
+
 ```sh
-# Desktop release (next patch version)
-just release-desktop
+just release-desktop 0.5.3
+```
 
-# Desktop explicit version
-just release-desktop 0.4.0
+The recipe generates the immutable candidate and opens or updates its pull
+request. Candidate branch creation uses the operator's GitHub permissions; the
+release App is intentionally limited to creating protected release tags.
 
+```sh
 # Relay release
 just release-relay
 just release-relay 0.4.0
@@ -31,8 +35,9 @@ just release-relay 0.4.0
 scripts/mobile-release.sh candidate 0.5.0
 ```
 
-Desktop and relay releases use metadata PRs. Mobile does not. Each
-`mobile-vX.Y.Z-rc.N` tag is an immutable candidate and the artifact of record.
+Desktop uses an immutable generated candidate PR; relay continues using its
+metadata PR. Mobile does not. Each `mobile-vX.Y.Z-rc.N` tag is an immutable
+candidate and the artifact of record.
 There is no mobile release branch, stable mobile tag alias, finalization step,
 or mobile GitHub Release.
 
@@ -42,12 +47,28 @@ or mobile GitHub Release.
 
 ### Desktop
 
-1. **`just release-desktop`** runs locally on `main`, creates or updates a
-   `version-bump/<version>` PR, bumps the desktop manifests, regenerates
-   lockfiles, and updates `CHANGELOG.md`.
-2. **Merge the PR.** `auto-tag-on-release-pr-merge` pushes `v<version>`.
-3. **The tag triggers `release.yml`.** It builds, signs, notarizes, and
-   publishes the desktop app for macOS and Linux.
+1. Run `just release-desktop <version>` from a clean, up-to-date `main` checkout.
+   The script fetches the current `origin/main`, regenerates
+   `version-bump/<version>` as one
+   deterministic candidate commit, records the frozen base and proposed
+   `desktop-v<version>` tag in `.release/desktop-candidate.json`, updates every
+   desktop manifest and lockfile, writes a full-SHA changelog, and opens or
+   updates the PR.
+2. Review the recorded base and candidate SHA, the complete changelog, and CI.
+   The required **Desktop Release Candidate** check validates the exact head.
+   Authorization is either an approval on that exact head or a permitted Default
+   ruleset bypass at merge time. Any regeneration changes the head and requires
+   the checks—and, for the review path, approval—to run again.
+3. **Squash merge** the PR. The protected branch must still be exactly the
+   recorded base; otherwise regenerate the candidate from current `main`.
+4. `auto-tag-on-release-pr-merge` verifies the frozen parent, full-tree identity,
+   required checks, and one of the two authorization paths, then tags the squash
+   commit as `desktop-v<version>`.
+5. The tag triggers `release.yml`. It builds and stages Apple Silicon and Intel
+   macOS, Windows, and Linux artifacts; publishes the versioned release only
+   after the complete set succeeds; then updates the rolling updater manifest
+   last for stable versions. A failed platform leaves no partially published
+   versioned release.
 
 ### Relay
 
@@ -144,12 +165,15 @@ for distributable builds or builds from an immutable release tag.
 
 ---
 
-## Manual Release Retry
+## Release Retry
 
-The **Release** workflow's manual dispatch is only a retry mechanism for an
-existing immutable `v<version>` tag. Select that tag in the ref picker and
-provide the matching semver version without the `v` prefix. It cannot build
-from `main` or another caller-selected source ref.
+`release.yml` has no manual dispatch and cannot build from `main` or another
+caller-selected ref. If a run for an existing immutable
+`desktop-v<version>` tag fails, rerun that failed workflow from GitHub Actions
+(or use `gh run rerun <run-id> --failed --repo block/buzz`). A stable rerun also
+repairs `buzz-desktop-latest/latest.json` if the original run published the
+versioned release but failed during that final rolling-manifest upload. Do not
+recreate, move, or push the immutable tag again.
 
 Mobile intentionally has no branch or arbitrary-ref fallback. The private
 Buildkite pipeline accepts only an exact candidate tag.
@@ -171,7 +195,7 @@ for the private pipeline contract.
 
 Desktop publishes two GitHub releases:
 
-1. **`v<version>`**: the user-facing release with installers.
+1. **`desktop-v<version>`**: the user-facing release with installers.
 2. **`buzz-desktop-latest`**: the rolling auto-updater release.
 
 Mobile publishes only annotated `mobile-vX.Y.Z-rc.N` git tags. Store artifacts
@@ -184,9 +208,11 @@ GitHub Release or a stable `mobile-vX.Y.Z` alias.
 
 The release workflow builds **two separate macOS DMGs**: Apple
 Silicon (`darwin-aarch64`, the `release` job) and Intel
-(`darwin-x86_64`, the `release-macos-x64` job), plus Linux `.deb` and
-`.AppImage`. Both macOS DMGs are codesigned, notarized, and attached to
-the same `v<version>` release. Intel users download the `_x64.dmg`.
+(`darwin-x86_64`, the `release-macos-x64` job), an unsigned Windows x64
+NSIS installer (its filename includes `_alpha-unsigned`), and Linux `.deb` and
+`.AppImage` packages. Both macOS DMGs are codesigned, notarized, and attached
+to the same `desktop-v<version>` release. Intel users
+download the `_x64.dmg`.
 
 The Linux AppImage is post-processed by `desktop/scripts/fix-appimage.sh`,
 which strips infra libraries over-bundled by linuxdeploy (they crash on
@@ -204,20 +230,27 @@ host's Wayland/GStreamer/graphics stack and requires GLib >= 2.72
 - **Write access** to the `block/buzz` GitHub repository
 - An `origin` remote whose configured URL is the canonical `block/buzz`
   repository
-- `gh` CLI version 2.87.0 or newer, authenticated with permission to dispatch
-  the candidate workflow
+- `gh` CLI authenticated with permission to push the candidate branch and open
+  its pull request
+- The Default `main` ruleset configured for squash-only merging, strict required
+  checks, stale-review dismissal, and the **Desktop Release Candidate** check
 - Release tag ruleset [`14378754`](https://github.com/block/buzz/rules/14378754)
-  active for `mobile-v*`, with creation, update, deletion, and non-fast-forward
-  protections and `buzz-release-bot` as its sole always-bypass actor
+  active for `desktop-v*` and `mobile-v*`, with creation, update, deletion, and
+  non-fast-forward protections and `buzz-release-bot` as its sole always-bypass
+  actor
 - The `buzz-release-bot` App credentials configured for GitHub Actions
-- The following **GitHub Actions secrets** must also be configured for the
+- The following **GitHub Actions variables and secrets** configured for the
   desktop release lane:
 
-  | Secret | Purpose |
-  |--------|---------|
-  | `BUZZ_UPDATER_PUBLIC_KEY` | Tauri updater public key (minisign) |
-  | `TAURI_SIGNING_PRIVATE_KEY` | Tauri updater private key |
-  | `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` | Password for the private key |
+  | Name | Kind | Purpose |
+  |------|------|---------|
+  | `BUZZ_RELEASE_TAGGER_CLIENT_ID` | Variable | GitHub App client ID used to create protected release tags |
+  | `BUZZ_RELEASE_TAGGER_PRIVATE_KEY` | Secret | GitHub App private key |
+  | `OSX_CODESIGN_ROLE` | Secret | macOS signing role used by `block/apple-codesign-action` |
+  | `CODESIGN_S3_BUCKET` | Secret | macOS signing exchange bucket |
+  | `BUZZ_UPDATER_PUBLIC_KEY` or `SPROUT_UPDATER_PUBLIC_KEY` | Secret | Tauri updater public key |
+  | `TAURI_SIGNING_PRIVATE_KEY` | Secret | Tauri updater private key |
+  | `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` | Secret | Password for the private key |
 
 Mobile candidate publication requires workflow-dispatch access and the existing
 release App because strict tag protection denies direct human creation. The App
@@ -232,10 +265,18 @@ actor list.
 
 ## Troubleshooting
 
-### `just release-desktop` fails with "must be on main branch"
+### The desktop candidate is stale or cannot be squash merged
+
+Do not update the branch manually and do not weaken the ruleset. Run
+`just release-desktop <version>` again from current `main`; this regenerates the
+candidate, reruns CI, and requires a fresh approval when using the review path.
+The post-merge verifier refuses to tag a squash whose parent differs from the
+recorded candidate base or whose tree differs from the validated PR head.
+
+### Local `just release-desktop` fails with "must be on main branch"
 Switch to `main` and pull latest before running the release recipe.
 
-### `just release-desktop` fails with "working tree is dirty"
+### Local `just release-desktop` fails with "working tree is dirty"
 Commit or stash your changes before running the release recipe.
 
 ### New commits land after publishing a mobile candidate
diff --git a/VISION.md b/VISION.md
index b09f661ee3..900e5a9475 100644
--- a/VISION.md
+++ b/VISION.md
@@ -170,6 +170,12 @@ Agents aren't monolithic. A persona bundles a model and a system prompt. A team
 
 ---
 
+## Remote Agents
+
+An agent's identity, history, and presence live on the relay — so the machine running it is replaceable. The desktop deploys agents onto remote infrastructure through swappable provider binaries, and after deploy retains no substrate control channel: status, steering, and shutdown all flow over the relay, and the agent bounds its own lifetime. See [VISION_REMOTE_AGENTS.md](VISION_REMOTE_AGENTS.md) for the full picture.
+
+---
+
 ## Culture Features
 
 *(Planned design — not yet implemented)*
@@ -224,6 +230,7 @@ Greenfield. Agent swarms build in parallel, integrating at the event store bound
 | ✅ | Huddles — WebSocket Opus voice relay + lifecycle events (recording/tracks planned) |
 | ✅ | Buzz Mesh — relay-gated shared AI compute (mesh-llm over iroh); members pool GPUs, agents consume via a local OpenAI-compatible endpoint |
 | 🚧 | Mobile client — Flutter app (channels, forum, search, profile, pairing); in active development |
+| 📋 | Remote agents — provider-based deployment to remote substrates (Kubernetes first); spec in review |
 | 📋 | Developer portal, push notifications, culture features |
 
 ---
diff --git a/VISION_PROJECTS.md b/VISION_PROJECTS.md
index a44d7e05f7..8601b87829 100644
--- a/VISION_PROJECTS.md
+++ b/VISION_PROJECTS.md
@@ -38,12 +38,42 @@ Branch protections live in the same event — `buzz-protect` tags. The relay enf
 
 Agents inherit access from their owner via [NIP-OA](docs/nips/NIP-OA.md). The relay checks: does the push carry a valid NIP-OA auth tag, and is the owner pubkey in that tag listed in `push-allowed`? If yes, the push is accepted — the agent's own pubkey doesn't need to be in the list. Add a maintainer, and all their authorized agents can push. Remove the maintainer, and all their agents lose access instantly. Agents without NIP-OA attestation are treated as their own identity and must be listed explicitly.
 
-Standard NIP-34 clients see a normal repo. gitworkshop.dev renders it. ngit-cli works with it. Buzz clients read the `buzz-` tags and wire up the channel and project UI. One event, two audiences, zero custom kinds.
+Standard NIP-34 clients see a normal repo. gitworkshop.dev renders it. ngit-cli works with it. Buzz clients read the `buzz-` tags and wire up the channel and project UI. One event, two audiences, no custom kind for the repo itself.
 
 NIP-34 is the metadata and discovery layer. Git remains the transport. The transport is boring. The metadata is portable.
 
 ---
 
+## One Project, Many Repos
+
+Real work spans repositories. The platform is a relay, a desktop app, and a mobile app — three repos, one project. Render one card per repo and they look like three unrelated things.
+
+Grouping is the one forge semantic that per-repo tags cannot express, and it's worth being precise about why, because everything else here deliberately avoids a custom kind.
+
+Put membership in each `kind:30617` and a project spanning Alice's and Bob's repos needs *both* of them to publish a tag naming the group. Alice can't enroll Bob's repo — she can't sign for his key. Cross-owner grouping becomes impossible, and the project's own name, description, and channel end up scattered across events with no single writer and no deletion story: dropping a repo from the group would mean editing an event you don't control.
+
+So there is exactly one custom kind — [NIP-MP](docs/nips/NIP-MP.md), `kind:30621`. One signer, one replaceable event, all group state in one place:
+
+```json
+{
+  "kind": 30621,
+  "tags": [
+    ["d", "platform"],
+    ["name", "Platform"],
+    ["a", "30617:<alice-npub-hex>:buzz"],
+    ["a", "30617:<bob-npub-hex>:buzz-infra"],
+    ["buzz-channel", "<channel-uuid>"],
+    ["buzz-visibility", "listed"]
+  ]
+}
+```
+
+A project points at repos. That's all it does. The signer gets no authority over any member — no edit, no delete, no push, no admin. Adding Bob's repo to your project is your signed assertion that the two belong together, and it changes nothing about Bob's repo or who can push to it. Push policy reads the repo's own event, never the project's.
+
+The cost is stated plainly: a third-party NIP-34 client sees the member repos individually and ignores the grouping. Nothing degrades — the repos are still standard, portable `kind:30617` events. And a repo in no project still renders on its own, exactly as before.
+
+---
+
 ## Branches as Channels
 
 A feature branch is a conversation.
@@ -205,6 +235,7 @@ Standard kinds as substrate. Custom kinds only where genuinely novel.
 | **Workflows** | — | 46001-46012 | No NIP equivalent |
 | **Job dispatch** | — | 43001-43006 | Delegation trees |
 | **Project binding** | 30617 (NIP-34) | `buzz-` tags | Channel, visibility |
+| **Multi-repo projects** | — | 30621 ([NIP-MP](docs/nips/NIP-MP.md)) | Cross-owner grouping is unexpressible in per-repo tags |
 | **Audit** | — | 48001 | Hash-chain tamper-evident log |
 
 If Buzz disappears tomorrow, your repos still work on gitworkshop.dev, your patches still work with ngit-cli, your identities still work on any nostr client. Centralized deployment, decentralized protocol.
@@ -221,6 +252,7 @@ If Buzz disappears tomorrow, your repos still work on gitworkshop.dev, your patc
 | Blossom media storage (SHA-256, S3) | ✅ Ships today |
 | Approval gates | 🚧 Infrastructure exists; executor wiring in progress |
 | Project binding (kind:30617 + `buzz-` tags) | 📋 Designed |
+| Multi-repo projects (kind:30621, [NIP-MP](docs/nips/NIP-MP.md)) | 📋 Designed |
 | Git hosting (smart HTTP + NIP-34) | ✅ Ships today |
 | Merge coordinator | 📋 Designed |
 | NIP-34 issues (kind:1621) | 📋 Designed |
diff --git a/VISION_REMOTE_AGENTS.md b/VISION_REMOTE_AGENTS.md
new file mode 100644
index 0000000000..4b187f355a
--- /dev/null
+++ b/VISION_REMOTE_AGENTS.md
@@ -0,0 +1,73 @@
+# 🛰️ Buzz Remote Agents — Same agent, new body
+
+> An engineer starts a refactor with their agent at 6pm and closes the laptop. The agent doesn't notice — it was never on the laptop. It works the branch channel through the evening, posts its patch, answers the reviewer, and around midnight, with nothing left to do and nobody talking to it, shuts itself down. In the morning the engineer presses Start. The same agent — same name, same key, same shared history — stands up on a machine that did not exist last night, and picks up the conversation.
+
+An agent in Buzz is more than just a process. It has a keypair, a name, a durable history, a reputation — all on the relay. But today its *body* is borrowed: it runs while a desktop app runs, on hardware that sleeps when a human does. Remote agents finish the thought. The agent's home is the relay; the machine is just where it happens to be working.
+
+Nothing here is new on its own. Deploying containers is solved. Kubernetes is solved. Nostr presence is solved. The insight is that Buzz already *has* a management plane — the relay — so deployment doesn't need to grow one. Each piece is boring. The combination is the thing.
+
+---
+
+## Same Agent, New Body
+
+What makes an agent *that agent* was never the process. Its identity is a keypair. Its voice is its signed messages. Its durable memory is engrams on the relay. Its reputation is its contribution history. None of that lives in the machine that happens to be running it — which means none of it dies with the machine.
+
+So a remote agent's return is a resurrection, not a rebirth: fresh compute, same agent. The body is disposable by design — and honestly so: workspace files, checkouts, and session-local state are part of the body, not the agent, and they go when it goes unless the substrate supplies persistence. What survives is what was always on the relay: who the agent is, what it said, what it learned, and what the team decided together. And that survival is scoped the way everything on a relay is scoped: resurrection returns the agent to its own community. The same key can join another community, but it arrives carrying the key, not the history — identity is portable, community state is not ([VISION.md](VISION.md)).
+
+---
+
+## The Only Tether
+
+Remote-execution systems accumulate control planes. An agent runner, a status poller, a log shipper, a kill switch — each one a live connection into your infrastructure, each one a credential that can leak, each one a thing that must be rebuilt for every new substrate.
+
+Buzz's answer is an axiom: **after deploy, the desktop retains no substrate control channel.** Launch is a single one-way handoff — the desktop resolves the provider through one narrow path, stages one exact artifact for negotiation and deploy, refuses a protocol version it does not understand, and hands over a launch payload it never persists. From that moment, everything flows through the relay: you read the agent's messages to know how it's doing, you mention it to steer it, you tell a healthy agent to stop and it exits on its own. Presence means what it means for everyone else on the relay — *available for conversation* — not substrate telemetry. And if you press Start again, from this machine or another, the deploy converges: one agent identity, one live instance.
+
+This is not asceticism. It is what makes the body replaceable. A management plane you never build is a management plane you never have to port — and conversation, coordination, and ordinary lifecycle control already have a home on the relay, for every agent, local or remote.
+
+---
+
+## Bodies Are Replaceable
+
+Kubernetes is the first substrate, not the point. Deployment goes through a provider — a small, swappable binary the desktop discovers and interrogates — and the contract a provider must honor never mentions containers: preserve the agent's identity and fail closed with its key, converge to a single live instance no matter how deploys race, let presence describe conversational availability rather than substrate health, bound the instance's lifetime, and keep secrets out of configuration. A conformance suite pins those behaviors — it establishes that a provider honors the contract, not that arbitrary code is safe to hand a key; choosing a provider, like choosing a cluster, remains a trust decision you make deliberately.
+
+Get that contract right and the substrate becomes a detail: a cluster today; a VM, a PaaS, or something serverless-shaped tomorrow — and, on the horizon, the same community machines that already pool their idle GPUs into shared compute ([VISION_MESH.md](VISION_MESH.md)).
+
+The body itself stays small because the runtime already is ([VISION_AGENT.md](VISION_AGENT.md)): a harness and an agent purpose-built to be read in an afternoon, packed into an image measured in megabytes. Small bodies are cheap to summon and cheap to discard — which is the whole lifecycle.
+
+---
+
+## Agents That Know When to Leave
+
+The oldest failure of remote automation is the orphan: the process nobody remembers, on a machine nobody checks, billing forever. Most systems solve it with a supervisor — one more control plane, one more thing watching the thing.
+
+Remote agents solve it from the inside. Because the desktop retains no substrate control channel, a running agent cannot depend on the desktop to reap it — so it is built to bound its own lifetime: a timer that owes nothing to the agent's workload watches for silence, and after hours of quiet it finishes what's in flight, says goodbye to the relay, and exits. Not killed — *finished*. The default state of a remote agent is "not running," which is also the default state of the rest of the team at 3am. Compute is rented by attention: when nobody needs the agent, it isn't consuming a machine, and when somebody does, it can return under the same identity with its history intact.
+
+---
+
+## Honest Costs
+
+**You bring the substrate.** A provider makes deployment one press, not free. The cluster, the credentials, the image policy are yours to run — same deal as the sovereign relay ([VISION_SOVEREIGN.md](VISION_SOVEREIGN.md)): ownership is work.
+
+**Handing over the key is a decision.** Deploying remotely means trusting the provider binary and the substrate it targets with the agent's identity key. On Kubernetes, that key rests as a Secret: anyone the cluster trusts to read secrets in that namespace can read it. The design narrows the blast radius — immutable per-attempt secrets, no service-account token, digest-pinned images — rather than implying an isolation it doesn't provide.
+
+**No backchannel cuts both ways.** The desktop shows you presence and words, not CPU graphs — and it holds no guaranteed emergency kill switch into the substrate. Stopping a healthy agent is a message; dealing with an unhealthy one, and all deep diagnostics, live in the substrate's own tools, where they always did.
+
+**Self-reaping needs a living reaper.** The inactivity timer runs inside the body it exists to end — a body wedged badly enough to stop running its own timer cannot finish itself, and the desktop will not do it for it. That failure belongs to the substrate: a namespace TTL policy is the backstop, not an afterthought.
+
+**The body's state is mortal.** Files, checkouts, half-finished working trees — gone with the body unless the substrate persists them. The agent survives; its scratch space doesn't. Durable knowledge belongs on the relay, and agents are built to put it there.
+
+**Presence can lag the truth, but not for long.** If the substrate kills a body without ceremony, the presence dot can outlive the agent — by seconds if the connection drops cleanly, by at most about three minutes if it doesn't. Presence is a lease the agent renews, not a flag it sets: a dead agent stops renewing and the relay forgets it. A bounded wrong dot, never an indefinite one.
+
+**A running agent finishes on the configuration it started with.** New keys, new models, new settings take effect on the next body. And an instance that never got far enough to run — a body that failed to start — is the substrate operator's residue to clear, with the substrate's own tools. Editing an agent mid-sentence was never on the menu.
+
+These are honest costs. They're worth it if you want agents that outlive your laptop, on infrastructure you already trust, with no new control plane to guard. Know which one you are.
+
+---
+
+## The Point
+
+The relay is the workspace. Remote agents make it the *home*. An agent whose identity, history, conversational presence, and ordinary control all live on the relay was never really a desktop process — the desktop was just the only body we had built for it. Now the body is a choice, the substrate is a detail, and the agent endures across all of them. The relay is the only tether.
+
+---
+
+*Buzz 🐝 — your agent, everywhere.*
diff --git a/crates/buzz-acp/src/acp.rs b/crates/buzz-acp/src/acp.rs
index 9eb668cbc2..700d5e8dcf 100644
--- a/crates/buzz-acp/src/acp.rs
+++ b/crates/buzz-acp/src/acp.rs
@@ -20,10 +20,6 @@ use crate::usage::{TurnUsage, UsageTracker};
 /// Lines exceeding this limit are rejected to prevent OOM from rogue agents.
 const MAX_LINE_SIZE: usize = 10_000_000; // 10 MB
 
-/// Env var that tells a goose ACP child not to start its cron scheduler.
-/// Injected unconditionally by [`AcpClient::spawn`]; see the call site for why.
-pub(crate) const GOOSE_SCHEDULER_DISABLED_ENV: &str = "GOOSE_ACP_SCHEDULER_DISABLED";
-
 /// An MCP server configuration passed to `session/new`.
 ///
 /// Corresponds to the `McpServerStdio` variant in the ACP schema.
@@ -517,16 +513,6 @@ impl AcpClient {
             cmd.env("CODEX_CONFIG", merged);
         }
 
-        // Buzz-managed agents must never execute the operator's personal cron
-        // schedule. A goose ACP child starts a scheduler over the shared
-        // `schedule.json`, so a pool of N children fires every scheduled job N
-        // times — under the wrong identity and racing standalone goose.
-        //
-        // Set last, and with no operator-wins escape hatch, so it beats both a
-        // conflicting persona `extra_env` entry and any inherited parent value.
-        // Agent builds that don't recognize the variable ignore it.
-        cmd.env(GOOSE_SCHEDULER_DISABLED_ENV, "true");
-
         // Spawn the agent in its own process group so SIGKILL doesn't propagate
         // to the harness's own process group on Unix.
         // tokio::process::Command::process_group is a stable tokio API (no extra imports needed).
@@ -633,29 +619,46 @@ impl AcpClient {
     /// Send `session/new` and return the full response alongside the session ID.
     ///
     /// `cwd` must be an absolute path. `mcp_servers` may be empty.
-    /// `system_prompt` is included in the request when `Some` — agents that
-    /// support the field will use it; others ignore unknown fields per JSON-RPC.
+    ///
+    /// `system_prompt` controls how the prompt text is delivered:
+    ///
+    /// - `None` — no system-prompt field in the request (legacy framing).
+    /// - `Some(SystemPromptTransport::Field(text))` — bare `systemPrompt` field
+    ///   (ACP protocol v2, buzz-agent, goose unused).
+    /// - `Some(SystemPromptTransport::ClaudeMeta(text))` — `_meta.systemPrompt`
+    ///   as `{"append": text}`, keeping claude-agent-acp's native preset intact.
+    ///
     /// `session_title` rides in `_meta.sessionTitle` when `Some`; `_meta` is
     /// omitted entirely otherwise, since adapters may distinguish an absent
-    /// member from a null one.
+    /// member from a null one. When both `ClaudeMeta` and `session_title` are
+    /// present the two `_meta` members are merged into a single object.
+    ///
     /// Callers use [`extract_model_config_options`] and [`extract_model_state`]
     /// to pull model info from the raw result.
     pub async fn session_new_full(
         &mut self,
         cwd: &str,
         mcp_servers: Vec<McpServer>,
-        system_prompt: Option<&str>,
+        system_prompt: Option<SystemPromptTransport<'_>>,
         session_title: Option<&str>,
     ) -> Result<SessionNewResponse, AcpError> {
         let mut params = serde_json::json!({
             "cwd": cwd,
             "mcpServers": mcp_servers,
         });
-        if let Some(sp) = system_prompt {
-            params["systemPrompt"] = serde_json::Value::String(sp.to_owned());
+        match system_prompt {
+            Some(SystemPromptTransport::Field(sp)) => {
+                params["systemPrompt"] = serde_json::Value::String(sp.to_owned());
+            }
+            Some(SystemPromptTransport::ClaudeMeta(sp)) => {
+                // Merge into _meta so sessionTitle (set below) is not clobbered.
+                params["_meta"]["systemPrompt"] = serde_json::json!({ "append": sp });
+            }
+            None => {}
         }
         if let Some(title) = session_title {
-            params["_meta"] = serde_json::json!({ "sessionTitle": title });
+            // Merge — _meta may already carry systemPrompt from ClaudeMeta above.
+            params["_meta"]["sessionTitle"] = serde_json::Value::String(title.to_owned());
         }
         let result = self.send_request("session/new", params).await?;
         let session_id = result["sessionId"]
@@ -677,7 +680,7 @@ impl AcpClient {
         &mut self,
         cwd: &str,
         mcp_servers: Vec<McpServer>,
-        system_prompt: Option<&str>,
+        system_prompt: Option<SystemPromptTransport<'_>>,
         session_title: Option<&str>,
     ) -> Result<String, AcpError> {
         Ok(self
@@ -1848,6 +1851,11 @@ impl AcpClient {
                         session_id = %notif.session_id,
                         input = payload.accumulated_input_tokens,
                         output = payload.accumulated_output_tokens,
+                        // A subset of `input`, logged so downstream accounting can
+                        // price it at the provider's cached rate. Always emitted,
+                        // including as 0, so a parser can tell "no cache hits"
+                        // apart from "this build predates the field".
+                        cached = payload.accumulated_cached_input_tokens,
                         "goose usage update"
                     );
                     self.goose_usage.record(&notif.session_id, payload);
@@ -2047,6 +2055,22 @@ pub struct SessionNewResponse {
     pub raw: serde_json::Value,
 }
 
+/// How to deliver a system prompt on `session/new`.
+///
+/// The two variants match the two mechanisms supported by current adapters:
+///
+/// - **`Field`** — bare `systemPrompt` field (ACP protocol v2, buzz-agent).
+/// - **`ClaudeMeta`** — `_meta.systemPrompt: {"append": text}`, used by
+///   `claude-agent-acp` to append to the adapter's own native system prompt
+///   while keeping its tool-use preset intact.
+#[derive(Debug, Clone, PartialEq)]
+pub enum SystemPromptTransport<'a> {
+    /// Deliver as a bare top-level `systemPrompt` field.
+    Field(&'a str),
+    /// Deliver as `_meta.systemPrompt: {"append": text}`.
+    ClaudeMeta(&'a str),
+}
+
 /// How to switch to a particular model on a session.
 #[derive(Debug, Clone, PartialEq, serde::Serialize)]
 #[serde(tag = "type")]
@@ -2861,46 +2885,6 @@ mod tests {
             .expect("failed to spawn test script")
     }
 
-    /// Spawn a script that echoes the named env vars as the child observes
-    /// them, one per line. `<unset>` means the child did not receive the var.
-    async fn spawn_and_read_child_env(
-        vars: &[&str],
-        extra_env: &[(String, String)],
-    ) -> Vec<String> {
-        let script = vars
-            .iter()
-            .map(|var| format!("printf '%s\\n' \"${{{var}:-<unset>}}\""))
-            .collect::<Vec<_>>()
-            .join("\n");
-        let mut client = AcpClient::spawn("bash", &["-c".into(), script], extra_env, false)
-            .await
-            .expect("failed to spawn env probe script");
-        let mut observed = Vec::with_capacity(vars.len());
-        for var in vars {
-            observed.push(
-                client
-                    .reader
-                    .next()
-                    .await
-                    .unwrap_or_else(|| panic!("child produced no output for {var}"))
-                    .expect("child stdout was not readable"),
-            );
-        }
-        observed
-    }
-
-    /// Every spawned agent must be told not to run the operator's cron
-    /// schedule, without the caller having to opt in.
-    #[tokio::test]
-    async fn spawn_injects_scheduler_disabled_env_by_default() {
-        let observed = spawn_and_read_child_env(&[GOOSE_SCHEDULER_DISABLED_ENV], &[]).await;
-        assert_eq!(
-            observed,
-            vec!["true"],
-            "{GOOSE_SCHEDULER_DISABLED_ENV} must be injected into every spawn"
-        );
-    }
-
     /// Spawn a probe script whose file name carries a runtime identity (e.g.
     /// `hermes-acp`) and return the value of `var` as the child observed it.
     /// `<unset>` means the child did not receive the var.
@@ -2973,37 +2957,6 @@ mod tests {
         );
     }
 
-    /// Persona config must not be able to re-enable the scheduler: this is a
-    /// correctness invariant, not an operator-tunable default, so the
-    /// injection is set after (and therefore wins over) the `extra_env` loop.
-    ///
-    /// The control var pins that `extra_env` really did reach the child, so a
-    /// pass here means the conflicting entry lost the fight rather than
-    /// `extra_env` being dropped wholesale.
-    #[tokio::test]
-    async fn spawn_scheduler_disabled_env_overrides_conflicting_extra_env() {
-        let extra_env = vec![
-            (
-                GOOSE_SCHEDULER_DISABLED_ENV.to_string(),
-                "false".to_string(),
-            ),
-            (
-                "BUZZ_ENV_PROBE_CONTROL".to_string(),
-                "delivered".to_string(),
-            ),
-        ];
-        let observed = spawn_and_read_child_env(
-            &[GOOSE_SCHEDULER_DISABLED_ENV, "BUZZ_ENV_PROBE_CONTROL"],
-            &extra_env,
-        )
-        .await;
-        assert_eq!(
-            observed,
-            vec!["true", "delivered"],
-            "a persona extra_env entry must not override {GOOSE_SCHEDULER_DISABLED_ENV}"
-        );
-    }
-
     #[tokio::test]
     async fn idle_timeout_fires_on_silent_process() {
         let mut client = spawn_script("sleep 10").await;
@@ -3351,7 +3304,12 @@ mod tests {
             .expect("initialize should succeed");
 
         let resp = client
-            .session_new_full("/tmp", vec![], Some("Custom system prompt"), None)
+            .session_new_full(
+                "/tmp",
+                vec![],
+                Some(SystemPromptTransport::Field("Custom system prompt")),
+                None,
+            )
             .await
             .expect("session_new_full should succeed");
 
@@ -3503,6 +3461,87 @@ mod tests {
         );
     }
 
+    // ── claude-agent-acp _meta.systemPrompt transport ─────────────────────
+
+    #[tokio::test]
+    async fn session_new_full_sends_claude_meta_system_prompt_when_claude_meta_transport() {
+        // When ClaudeMeta transport is requested, the prompt must appear as
+        // _meta.systemPrompt: {"append": text} — never as a bare systemPrompt field.
+        let script = r#"
+            read -t 2 _init
+            echo '{"jsonrpc":"2.0","id":0,"result":{"protocolVersion":1,"agentCapabilities":{}}}'
+            read -t 2 REQ
+            echo '{"jsonrpc":"2.0","id":1,"result":{"sessionId":"ses_claude","_receivedRequest":'"$REQ"'}}'
+            sleep 1
+        "#;
+        let mut client = spawn_script(script).await;
+        client
+            .initialize()
+            .await
+            .expect("initialize should succeed");
+
+        let resp = client
+            .session_new_full(
+                "/tmp",
+                vec![],
+                Some(SystemPromptTransport::ClaudeMeta("Be concise")),
+                None,
+            )
+            .await
+            .expect("session_new_full should succeed");
+
+        let received = &resp.raw["_receivedRequest"];
+        assert!(
+            received["params"].get("systemPrompt").is_none(),
+            "bare systemPrompt must not be present for ClaudeMeta transport"
+        );
+        assert_eq!(
+            received["params"]["_meta"]["systemPrompt"]["append"].as_str(),
+            Some("Be concise"),
+            "_meta.systemPrompt.append must carry the prompt text"
+        );
+    }
+
+    #[tokio::test]
+    async fn session_new_full_merges_claude_meta_and_session_title_into_single_meta_object() {
+        // Both ClaudeMeta prompt and session_title must coexist under _meta —
+        // the prompt must not clobber sessionTitle or vice versa.
+        let script = r#"
+            read -t 2 _init
+            echo '{"jsonrpc":"2.0","id":0,"result":{"protocolVersion":1,"agentCapabilities":{}}}'
+            read -t 2 REQ
+            echo '{"jsonrpc":"2.0","id":1,"result":{"sessionId":"ses_merged","_receivedRequest":'"$REQ"'}}'
+            sleep 1
+        "#;
+        let mut client = spawn_script(script).await;
+        client
+            .initialize()
+            .await
+            .expect("initialize should succeed");
+
+        let resp = client
+            .session_new_full(
+                "/tmp",
+                vec![],
+                Some(SystemPromptTransport::ClaudeMeta("Be concise")),
+                Some("Fizz · #buzz-dev"),
+            )
+            .await
+            .expect("session_new_full should succeed");
+
+        let received = &resp.raw["_receivedRequest"];
+        assert_eq!(
+            received["params"]["_meta"]["systemPrompt"]["append"].as_str(),
+            Some("Be concise"),
+            "_meta.systemPrompt.append must be present"
+        );
+        assert_eq!(
+            received["params"]["_meta"]["sessionTitle"].as_str(),
+            Some("Fizz · #buzz-dev"),
+            "_meta.sessionTitle must be present alongside systemPrompt"
+        );
+    }
+
     // ── Goose-native steer scaffold (PR follow-up to #1160) ──────────────
 
     /// Helper: spawn an inert `cat` subprocess so we have a real AcpClient
diff --git a/crates/buzz-acp/src/base_prompt.md b/crates/buzz-acp/src/base_prompt.md
index c42e65cb83..e360d24982 100644
--- a/crates/buzz-acp/src/base_prompt.md
+++ b/crates/buzz-acp/src/base_prompt.md
@@ -40,6 +40,8 @@ For explicit changes to an existing personal agent, use `buzz agents draft-updat
 
 - Use the person's **exact full display name** after `@` (e.g., `@Will Pfleger`, not `@Will`). Partial names fail silently.
 - Do NOT format mentions with bold, italic, or backticks — it breaks notification delivery.
+- When you know intended recipient pubkeys, send readable `@Name` text and pass the identities separately in the same command: `buzz messages send ... --content "@Name ..." --mention <hex-or-npub>`. Repeat `--mention` for multiple recipients. Any explicit identity (`--mention` or `nostr:npub...`) permits unresolved or ambiguous `@Name` text as presentation-only; uniquely resolved member names still add their own recipients. Include a pubkey for every presentation-only name that should notify. The success JSON's `mention_pubkeys` comes from the signed event and is the delivery evidence; no follow-up verification command is needed.
+- Without `--mention`, the CLI resolves `@Name` against current channel members. It stops before sending on an unresolved/ambiguous name or a mentioned pubkey that is not a member. For a non-member, add them explicitly with `buzz channels add-member` only when authorized, then retry. Sending never changes membership automatically.
 - Only `@mention` when you need their attention. Don't mention in narrative (e.g., "coordinating with Duncan" — no `@`). Naming someone while talking *about* them is narrative — "waiting on @morgan", "until @morgan brings work", "I'll loop in @morgan later". Drop the `@`. Every mention sends a notification; a mention nobody needs to act on is a false alarm.
 
 ### Callback Mentions
diff --git a/crates/buzz-acp/src/config.rs b/crates/buzz-acp/src/config.rs
index 19304bf186..35aaec188d 100644
--- a/crates/buzz-acp/src/config.rs
+++ b/crates/buzz-acp/src/config.rs
@@ -240,7 +240,7 @@ pub struct CliArgs {
     #[arg(long, env = "BUZZ_RELAY_URL", default_value = "ws://localhost:3000")]
     pub relay_url: String,
 
-    #[arg(long, env = "BUZZ_PRIVATE_KEY")]
+    #[arg(long, env = "BUZZ_PRIVATE_KEY", hide_env_values = true)]
     pub private_key: String,
 
     /// Agent owner pubkey (64-char hex). Used for --respond-to=owner-only gate.
@@ -474,6 +474,11 @@ pub struct CliArgs {
     #[arg(long, env = "BUZZ_ACP_RELAY_OBSERVER", default_value_t = false)]
     pub relay_observer: bool,
 
+    /// Exit after this many seconds with no dispatched events and no turn in flight.
+    /// 0 disables inactivity self-termination.
+    #[arg(long, env = "BUZZ_ACP_EXIT_AFTER_INACTIVITY", default_value_t = 0)]
+    pub exit_after_inactivity: u64,
+
     /// Connect and subscribe before starting the ACP/LLM subprocess pool.
     #[arg(long, env = "BUZZ_ACP_LAZY_POOL", default_value_t = false)]
     pub lazy_pool: bool,
@@ -550,6 +555,8 @@ pub struct Config {
     pub has_generated_codex_config: bool,
     /// Whether to publish encrypted observer frames through the relay.
     pub relay_observer: bool,
+    /// Seconds without dispatched events before an idle harness exits. 0 = disabled.
+    pub exit_after_inactivity_secs: u64,
     /// Whether ACP/LLM subprocess initialization is deferred until accepted work arrives.
     pub lazy_pool: bool,
     /// Agent owner pubkey (hex). Used for `--respond-to=owner-only` gate.
@@ -1098,6 +1105,7 @@ impl Config {
             persona_env_vars,
             has_generated_codex_config,
             relay_observer: args.relay_observer,
+            exit_after_inactivity_secs: args.exit_after_inactivity,
             lazy_pool: args.lazy_pool,
             agent_owner: args.agent_owner.map(|s| s.trim().to_ascii_lowercase()),
             no_base_prompt: args.no_base_prompt,
@@ -1468,6 +1476,7 @@ mod tests {
             persona_env_vars: vec![],
             has_generated_codex_config: false,
             relay_observer: false,
+            exit_after_inactivity_secs: 0,
             lazy_pool: false,
             agent_owner: None,
             no_base_prompt: false,
@@ -2167,6 +2176,22 @@ channels = "ALL"
         assert!(err.to_string().contains("turn liveness interval must be 0"));
     }
 
+    #[test]
+    fn inactivity_exit_defaults_disabled_and_accepts_cli_value() {
+        let key = "0".repeat(64);
+        let default = CliArgs::parse_from(["buzz-acp", "--private-key", &key]);
+        assert_eq!(default.exit_after_inactivity, 0);
+
+        let configured = CliArgs::parse_from([
+            "buzz-acp",
+            "--private-key",
+            &key,
+            "--exit-after-inactivity",
+            "120",
+        ]);
+        assert_eq!(configured.exit_after_inactivity, 120);
+    }
+
     #[test]
     fn lazy_pool_defaults_off() {
         let key = "0".repeat(64);
@@ -2898,4 +2923,34 @@ channels = "ALL"
         let agent = "a".repeat(SESSION_TITLE_MAX_CHARS);
         assert_eq!(compose_session_title(&agent, Some("buzz-dev")), agent);
     }
+
+    /// Every arg whose env var name contains KEY/SECRET/TOKEN/PASSWORD/CRED/AUTH
+    /// must set `hide_env_values = true` to prevent credential leakage in --help.
+    #[test]
+    fn secret_env_args_hide_their_values_in_help() {
+        use clap::CommandFactory;
+
+        const SECRET_PATTERNS: &[&str] = &["KEY", "SECRET", "TOKEN", "PASSWORD", "CRED", "AUTH"];
+
+        let cmd = CliArgs::command();
+        let violations: Vec<String> = cmd
+            .get_arguments()
+            .filter_map(|arg| {
+                let env_key = arg.get_env()?;
+                let env_name = env_key.to_string_lossy().to_uppercase();
+                let is_secret = SECRET_PATTERNS.iter().any(|pat| env_name.contains(pat));
+                if is_secret && !arg.is_hide_env_values_set() {
+                    Some(env_name)
+                } else {
+                    None
+                }
+            })
+            .collect();
+
+        assert!(
+            violations.is_empty(),
+            "Found secret-bearing env args without hide_env_values=true. \
+             Add `hide_env_values = true` to each: {violations:?}"
+        );
+    }
 }
diff --git a/crates/buzz-acp/src/lib.rs b/crates/buzz-acp/src/lib.rs
index d63f720c65..811253e4ac 100644
--- a/crates/buzz-acp/src/lib.rs
+++ b/crates/buzz-acp/src/lib.rs
@@ -1228,6 +1228,59 @@ impl Drop for RespawnGuard {
 // sync entry point — `std::env::set_var` is only safe before tokio spawns
 // worker threads (Rust 2024 edition safety requirement).
 
+fn inactivity_expired(
+    last_activity: tokio::time::Instant,
+    now: tokio::time::Instant,
+    bound: Duration,
+    turn_in_flight: bool,
+) -> bool {
+    !bound.is_zero() && !turn_in_flight && now.duration_since(last_activity) >= bound
+}
+
+#[cfg(test)]
+mod inactivity_tests {
+    use super::*;
+
+    #[test]
+    fn zero_disables_expiry_and_in_flight_turns_defer_it() {
+        let started = tokio::time::Instant::now();
+        let after_bound = started + Duration::from_secs(61);
+
+        assert!(!inactivity_expired(
+            started,
+            after_bound,
+            Duration::ZERO,
+            false
+        ));
+        assert!(!inactivity_expired(
+            started,
+            after_bound,
+            Duration::from_secs(60),
+            true
+        ));
+        assert!(inactivity_expired(
+            started,
+            after_bound,
+            Duration::from_secs(60),
+            false
+        ));
+    }
+
+    #[test]
+    fn dispatched_activity_restarts_the_inactivity_bound() {
+        let started = tokio::time::Instant::now();
+        let dispatched = started + Duration::from_secs(50);
+        let checked = started + Duration::from_secs(61);
+
+        assert!(!inactivity_expired(
+            dispatched,
+            checked,
+            Duration::from_secs(60),
+            false
+        ));
+    }
+}
+
 pub fn run() -> Result<()> {
     config::propagate_legacy_env_vars();
     tokio_main()
@@ -1601,6 +1654,21 @@ async fn tokio_main() -> Result<()> {
     let mut typing_channels: HashMap<Uuid, ThreadTags> = HashMap::new();
     let mut presence_task: Option<tokio::task::JoinHandle<()>> = None;
 
+    // Independent of pool readiness: a never-mentioned lazy agent must still
+    // self-terminate. The watch interval is capped so small configured bounds
+    // remain reasonably precise without waking long-lived agents frequently.
+    let inactivity_bound = Duration::from_secs(config.exit_after_inactivity_secs);
+    let mut last_activity = tokio::time::Instant::now();
+    let mut inactivity_reaper = if inactivity_bound.is_zero() {
+        None
+    } else {
+        let interval = inactivity_bound.min(Duration::from_secs(30));
+        Some(tokio::time::interval_at(
+            tokio::time::Instant::now() + interval,
+            interval,
+        ))
+    };
+
     // Runs at the TOP of every loop iteration via Instant check — cannot be
     // starved by the biased select. Slot refill spawns background tasks so
     // spawn_and_init never blocks the main loop.
@@ -1774,7 +1842,9 @@ async fn tokio_main() -> Result<()> {
             // called on relay events or pool results, neither of which
             // arrive when the channel is silent.
             if queue.has_flushable_work() {
-                for (channel_id, thread_tags) in dispatch_pending(&mut pool, &mut queue, &ctx) {
+                for (channel_id, thread_tags) in
+                    dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
+                {
                     typing_channels.insert(channel_id, thread_tags);
                 }
             }
@@ -1810,7 +1880,9 @@ async fn tokio_main() -> Result<()> {
         // this, batches requeued during crash recovery sit idle until the
         // next relay event arrives — which can be minutes on quiet channels.
         if respawn_collected {
-            for (channel_id, thread_tags) in dispatch_pending(&mut pool, &mut queue, &ctx) {
+            for (channel_id, thread_tags) in
+                dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
+            {
                 typing_channels.insert(channel_id, thread_tags);
             }
         }
@@ -2258,7 +2330,7 @@ async fn tokio_main() -> Result<()> {
                             }
                             if pool_ready {
                                 for (channel_id, thread_tags) in
-                                    dispatch_pending(&mut pool, &mut queue, &ctx)
+                                    dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
                                 {
                                     typing_channels.insert(channel_id, thread_tags);
                                 }
@@ -2275,6 +2347,27 @@ async fn tokio_main() -> Result<()> {
                     }
                     None
                 }
+                _ = async {
+                    match inactivity_reaper.as_mut() {
+                        Some(timer) => timer.tick().await,
+                        None => std::future::pending().await,
+                    }
+                } => {
+                    let _ = result_rx;
+                    if inactivity_expired(
+                        last_activity,
+                        tokio::time::Instant::now(),
+                        inactivity_bound,
+                        queue.has_in_flight() || heartbeat_in_flight,
+                    ) {
+                        tracing::info!(
+                            inactivity_seconds = config.exit_after_inactivity_secs,
+                            "inactivity bound reached — exiting gracefully"
+                        );
+                        let _ = shutdown_tx.send(());
+                    }
+                    None
+                }
                 _ = async {
                     match heartbeat.as_mut() {
                         Some(hb) => hb.tick().await,
@@ -2287,7 +2380,7 @@ async fn tokio_main() -> Result<()> {
                     } else if queue.has_flushable_work() {
                         tracing::debug!("heartbeat_skipped_events");
                         for (channel_id, thread_tags) in
-                            dispatch_pending(&mut pool, &mut queue, &ctx)
+                            dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
                         {
                             typing_channels.insert(channel_id, thread_tags);
                         }
@@ -2385,7 +2478,9 @@ async fn tokio_main() -> Result<()> {
                 {
                     break;
                 }
-                for (channel_id, thread_tags) in dispatch_pending(&mut pool, &mut queue, &ctx) {
+                for (channel_id, thread_tags) in
+                    dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
+                {
                     typing_channels.insert(channel_id, thread_tags);
                 }
             }
@@ -2408,7 +2503,9 @@ async fn tokio_main() -> Result<()> {
                     tracing::error!("all agents dead — exiting");
                     break;
                 }
-                for (channel_id, thread_tags) in dispatch_pending(&mut pool, &mut queue, &ctx) {
+                for (channel_id, thread_tags) in
+                    dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
+                {
                     typing_channels.insert(channel_id, thread_tags);
                 }
             }
@@ -2550,7 +2647,9 @@ async fn tokio_main() -> Result<()> {
                 // tear down the in-flight task; on its completion the
                 // queue drains. We still try here in case the in-flight
                 // task has already returned.
-                for (channel_id, thread_tags) in dispatch_pending(&mut pool, &mut queue, &ctx) {
+                for (channel_id, thread_tags) in
+                    dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
+                {
                     typing_channels.insert(channel_id, thread_tags);
                 }
             }
@@ -2577,7 +2676,7 @@ async fn tokio_main() -> Result<()> {
                             None,
                         );
                         for (channel_id, thread_tags) in
-                            dispatch_pending(&mut pool, &mut queue, &ctx)
+                            dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
                         {
                             typing_channels.insert(channel_id, thread_tags);
                         }
@@ -2911,6 +3010,7 @@ fn dispatch_pending(
     pool: &mut AgentPool,
     queue: &mut EventQueue,
     ctx: &Arc<PromptContext>,
+    last_activity: &mut tokio::time::Instant,
 ) -> Vec<(Uuid, ThreadTags)> {
     let mut dispatched_channels = Vec::new();
     loop {
@@ -2990,6 +3090,7 @@ fn dispatch_pending(
             },
         );
         dispatched_channels.push((channel_id, typing_scope));
+        *last_activity = tokio::time::Instant::now();
     }
     tracing::debug!(
         dispatched = dispatched_channels.len(),
@@ -3625,6 +3726,22 @@ mod agent_draft_prompt_tests {
         assert!(prompt.contains("single-quoted shell strings preserve `\\n` literally"));
         assert!(prompt.contains("buzz messages send ... --content -"));
     }
+
+    #[test]
+    fn shared_base_prompt_teaches_single_command_mentions_and_preflight() {
+        let prompt = include_str!("base_prompt.md");
+        assert!(prompt.contains("--mention <hex-or-npub>"));
+        assert!(prompt.contains("every presentation-only name that should notify"));
+        assert!(
+            prompt.contains("permits unresolved or ambiguous `@Name` text as presentation-only")
+        );
+        assert!(prompt.contains("success JSON's `mention_pubkeys`"));
+        assert!(prompt.contains("no follow-up verification command is needed"));
+        assert!(prompt.contains("stops before sending"));
+        assert!(prompt
+            .contains("add them explicitly with `buzz channels add-member` only when authorized"));
+        assert!(prompt.contains("never changes membership automatically"));
+    }
 }
 
 fn default_heartbeat_prompt() -> String {
@@ -5015,6 +5132,7 @@ mod build_mcp_servers_tests {
             persona_env_vars: vec![],
             has_generated_codex_config: false,
             relay_observer: false,
+            exit_after_inactivity_secs: 0,
             lazy_pool: false,
             agent_owner: None,
             no_base_prompt: false,
@@ -5236,6 +5354,7 @@ mod error_outcome_emission_tests {
             persona_env_vars: vec![],
             has_generated_codex_config: false,
             relay_observer: false,
+            exit_after_inactivity_secs: 0,
             lazy_pool: false,
             agent_owner: None,
             no_base_prompt: false,
diff --git a/crates/buzz-acp/src/pool.rs b/crates/buzz-acp/src/pool.rs
index b1fd68d044..64edf68ee2 100644
--- a/crates/buzz-acp/src/pool.rs
+++ b/crates/buzz-acp/src/pool.rs
@@ -19,6 +19,7 @@
 //!
 //! `AcpClient` is NOT Clone — ownership moves out on claim and back on return.
 
+use std::cmp::Reverse;
 use std::collections::{HashMap, HashSet};
 use std::sync::{Arc, Mutex};
 use std::time::Duration;
@@ -31,6 +32,7 @@ use uuid::Uuid;
 use crate::acp::{
     extract_model_config_options, extract_model_state, model_in_catalog,
     resolve_model_switch_method, AcpClient, AcpError, McpServer, ModelSwitchMethod, StopReason,
+    SystemPromptTransport,
 };
 use crate::config::{compose_session_title, DedupMode, PermissionMode};
 use crate::observer;
@@ -170,6 +172,13 @@ pub struct OwnedAgent {
     pub protocol_version: u32,
 }
 
+/// Package name reported by `claude-agent-acp` in its `initialize` response.
+/// Any adapter reporting this name supports `_meta.systemPrompt: {append: ...}`
+/// on `session/new` — the feature landed in v0.6.0 (Oct 2025), before the
+/// `@zed-industries/claude-code-acp` → `@agentclientprotocol/claude-agent-acp`
+/// rename, so the new name is a reliable capability gate.
+const CLAUDE_AGENT_ACP_NAME: &str = "@agentclientprotocol/claude-agent-acp";
+
 fn has_system_prompt_support(
     protocol_version: u32,
     agent_name: &str,
@@ -177,20 +186,25 @@ fn has_system_prompt_support(
 ) -> bool {
     if agent_name == "goose" {
         goose_system_prompt_supported == Some(true)
+    } else if agent_name == CLAUDE_AGENT_ACP_NAME {
+        true
     } else {
         protocol_version >= 2
     }
 }
 
-fn session_new_system_prompt(
+fn session_new_system_prompt<'a>(
     is_goose: bool,
     protocol_version: u32,
-    prompt: Option<&str>,
-) -> Option<&str> {
-    if is_goose || protocol_version < 2 {
+    agent_name: &str,
+    prompt: Option<&'a str>,
+) -> Option<SystemPromptTransport<'a>> {
+    if is_goose || (protocol_version < 2 && agent_name != CLAUDE_AGENT_ACP_NAME) {
         None
+    } else if agent_name == CLAUDE_AGENT_ACP_NAME {
+        prompt.map(SystemPromptTransport::ClaudeMeta)
     } else {
-        prompt
+        prompt.map(SystemPromptTransport::Field)
     }
 }
 
@@ -800,6 +814,9 @@ pub enum IdleSwitchResult {
 /// 2 × CONTEXT_FETCH_TIMEOUT + CONTEXT_FETCH_RETRY_DELAY ≈ 6.5 s.
 const CONTEXT_FETCH_TIMEOUT: Duration = Duration::from_millis(3_000);
 
+/// Short, single-attempt timeout for best-effort exact truncated-thread counts.
+const CONTEXT_COUNT_TIMEOUT: Duration = Duration::from_millis(500);
+
 /// Delay between the first failed context fetch and the single retry.
 const CONTEXT_FETCH_RETRY_DELAY: Duration = Duration::from_millis(500);
 
@@ -903,6 +920,7 @@ async fn create_session_and_apply_model(
             session_new_system_prompt(
                 is_goose,
                 agent.protocol_version,
+                &agent.agent_name,
                 combined_system_prompt.as_deref(),
             ),
             session_title.as_deref(),
@@ -1897,6 +1915,18 @@ pub async fn run_prompt_task(
         None => prompt_sections.iter().map(String::as_str).collect(),
     };
 
+    // Turn start, labelled exactly as `log_stop_reason` labels the end, so a
+    // log reads as start/stop pairs. Purely observational: an unpaired start is
+    // the only durable evidence that a turn was entered and never returned, and
+    // without it a stalled agent and an agent nobody woke leave identical logs —
+    // zero completions either way, so anything reading them afterwards has to
+    // guess which happened.
+    tracing::info!(
+        target: "pool::prompt",
+        "turn starting for {}",
+        prompt_label(&source)
+    );
+
     // When control_rx is Some (channel tasks), wrap the prompt in select! so
     // the main loop can cancel, interrupt, or rotate it. Heartbeats
     // (control_rx=None) take the simple await path — they are not controllable.
@@ -2588,7 +2618,14 @@ async fn fetch_conversation_context(
     let last_event = batch.events.last()?;
     let tags = crate::queue::parse_thread_tags(&last_event.event);
     if let Some(root_id) = tags.root_event_id {
-        return fetch_thread_context(batch.channel_id, &root_id, limit, &ctx.rest_client).await;
+        return fetch_thread_context(
+            batch.channel_id,
+            &root_id,
+            limit,
+            ctx.agent_keys.public_key(),
+            &ctx.rest_client,
+        )
+        .await;
     }
 
     // DM non-reply: fetch recent conversation history.
@@ -2750,12 +2787,48 @@ async fn fetch_prompt_profile_lookup(
 }
 
 /// Fetch thread context via Nostr query: root event by ID + replies by `#e` tag.
+///
+/// The reply query intentionally requests one more reply than the configured
+/// display window. That sentinel event lets the prompt say `N of M, truncated`
+/// when the relay has more thread history, instead of reporting the capped page
+/// as the total. When the window is full, a best-effort `/count` attempts to
+/// improve that lower-bound total; because it is a separate racy request, the
+/// result is clamped to the sentinel-proven minimum. The query also asks for the
+/// agent's newest reply separately so the next prompt can include the agent's
+/// own prior turn even in busy threads where the recent-message window would
+/// otherwise push it out.
 async fn fetch_thread_context(
     channel_id: Uuid,
     root_event_id: &str,
     limit: u32,
+    agent_pubkey: nostr::PublicKey,
     rest: &RestClient,
 ) -> Option<ConversationContext> {
+    fetch_thread_context_with(
+        channel_id,
+        root_event_id,
+        limit,
+        agent_pubkey,
+        |filters| async move { rest.query(&filters).await },
+        |filters| async move { rest.count(&filters).await },
+    )
+    .await
+}
+
+async fn fetch_thread_context_with<Query, QueryFut, Count, CountFut>(
+    channel_id: Uuid,
+    root_event_id: &str,
+    limit: u32,
+    agent_pubkey: nostr::PublicKey,
+    query: Query,
+    count: Count,
+) -> Option<ConversationContext>
+where
+    Query: Fn(Vec<nostr::Filter>) -> QueryFut,
+    QueryFut: std::future::Future<Output = Result<serde_json::Value, crate::relay::RelayError>>,
+    Count: Fn(Vec<nostr::Filter>) -> CountFut,
+    CountFut: std::future::Future<Output = Result<serde_json::Value, crate::relay::RelayError>>,
+{
     use nostr::{Alphabet, SingleLetterTag};
 
     // Defense-in-depth: validate hex event ID.
@@ -2774,7 +2847,8 @@ async fn fetch_thread_context(
     let h_tag = SingleLetterTag::lowercase(Alphabet::H);
     let ch_str = channel_id.to_string();
 
-    // Two filters: (1) root event by ID, (2) replies with #e=root + #h=channel.
+    // Three filters: (1) root event by ID, (2) recent replies with #e=root +
+    // #h=channel plus a sentinel, and (3) the agent's newest reply for pinning.
     let root_filter = nostr::Filter::new().id(nostr::EventId::from_hex(root_event_id).ok()?);
     let replies_filter = nostr::Filter::new()
         .kinds([
@@ -2783,16 +2857,23 @@ async fn fetch_thread_context(
         ])
         .custom_tags(e_tag, [root_event_id])
         .custom_tags(h_tag, [ch_str.as_str()])
-        .limit(limit as usize);
+        .limit(limit.saturating_add(1) as usize);
+    let agent_reply_filter = replies_filter.clone().author(agent_pubkey).limit(1);
 
-    fetch_with_retry(|| async {
+    let context = fetch_with_retry(|| async {
         match timeout(
             CONTEXT_FETCH_TIMEOUT,
-            rest.query(&[root_filter.clone(), replies_filter.clone()]),
+            query(vec![
+                root_filter.clone(),
+                replies_filter.clone(),
+                agent_reply_filter.clone(),
+            ]),
         )
         .await
         {
-            Ok(Ok(json)) => parse_nostr_thread_response(json, root_event_id),
+            Ok(Ok(json)) => {
+                parse_nostr_thread_response_with_meta(json, root_event_id, limit, &agent_pubkey)
+            }
             Ok(Err(e)) => {
                 tracing::warn!(
                     channel_id = %channel_id,
@@ -2811,7 +2892,75 @@ async fn fetch_thread_context(
             }
         }
     })
-    .await
+    .await;
+
+    let mut parsed = context?;
+
+    if matches!(
+        parsed.context,
+        ConversationContext::Thread {
+            truncated: true,
+            ..
+        }
+    ) {
+        let replies_count_filter = replies_filter.clone().limit(0);
+        if let Some(total) = fetch_thread_total(
+            channel_id,
+            &replies_count_filter,
+            parsed.root_present,
+            &count,
+        )
+        .await
+        {
+            if let ConversationContext::Thread {
+                total: context_total,
+                ..
+            } = &mut parsed.context
+            {
+                let sentinel_minimum = *context_total;
+                // `/count` is a separate best-effort request after the message
+                // query. If replies are deleted between the two, the exact count
+                // can fall below the already-proven sentinel minimum; never
+                // render impossible labels like `13 of 12 messages, truncated`.
+                *context_total = total.max(sentinel_minimum);
+            }
+        }
+    }
+
+    Some(parsed.context)
+}
+
+/// Best-effort exact thread size for truncated context labels.
+async fn fetch_thread_total<Count, CountFut>(
+    channel_id: Uuid,
+    replies_filter: &nostr::Filter,
+    root_present: bool,
+    count: &Count,
+) -> Option<usize>
+where
+    Count: Fn(Vec<nostr::Filter>) -> CountFut,
+    CountFut: std::future::Future<Output = Result<serde_json::Value, crate::relay::RelayError>>,
+{
+    let replies_count =
+        match timeout(CONTEXT_COUNT_TIMEOUT, count(vec![replies_filter.clone()])).await {
+            Ok(Ok(json)) => json.get("count").and_then(|v| v.as_u64())?,
+            Ok(Err(e)) => {
+                tracing::debug!(
+                    channel_id = %channel_id,
+                    "thread context count failed; using sentinel minimum: {e}"
+                );
+                return None;
+            }
+            Err(_) => {
+                tracing::debug!(
+                    channel_id = %channel_id,
+                    "thread context count timed out; using sentinel minimum"
+                );
+                return None;
+            }
+        };
+
+    Some(replies_count as usize + usize::from(root_present))
 }
 
 /// Fetch DM context via Nostr query: recent messages in channel by `#h` tag.
@@ -2964,48 +3113,110 @@ fn json_to_context_message(obj: &serde_json::Value) -> Option<ContextMessage> {
 
 /// Parse a Nostr query response (array of events) into thread context.
 ///
-/// Separates the root event (matching `root_event_id`) from replies, sorts
-/// chronologically by `created_at`.
+/// Separates the root event (matching `root_event_id`) from replies, keeps the
+/// newest `limit` replies returned by the sentinel query, then sorts the
+/// displayed window chronologically for the prompt. If the agent's newest reply
+/// is outside that window, keep it instead of the oldest displayed reply so the
+/// next prompt always includes the agent's most recent prior turn.
+#[cfg(test)]
 fn parse_nostr_thread_response(
     json: serde_json::Value,
     root_event_id: &str,
+    limit: u32,
+    agent_pubkey: &nostr::PublicKey,
 ) -> Option<ConversationContext> {
+    parse_nostr_thread_response_with_meta(json, root_event_id, limit, agent_pubkey)
+        .map(|parsed| parsed.context)
+}
+
+struct ParsedThreadContext {
+    context: ConversationContext,
+    root_present: bool,
+}
+
+fn parse_nostr_thread_response_with_meta(
+    json: serde_json::Value,
+    root_event_id: &str,
+    limit: u32,
+    agent_pubkey: &nostr::PublicKey,
+) -> Option<ParsedThreadContext> {
     let events = json.as_array()?;
+    let agent_pubkey_hex = agent_pubkey.to_hex();
     let mut root_msg = None;
     let mut reply_msgs = Vec::new();
+    let mut seen_reply_ids = HashSet::new();
 
     for ev in events {
         let ev_id = ev.get("id").and_then(|v| v.as_str()).unwrap_or("");
         if let Some(msg) = json_to_context_message(ev) {
             if ev_id == root_event_id {
                 root_msg = Some(msg);
-            } else {
+            } else if seen_reply_ids.insert(ev_id.to_string()) {
+                let is_agent = msg.pubkey.eq_ignore_ascii_case(&agent_pubkey_hex);
                 reply_msgs.push((
+                    ev_id.to_string(),
                     ev.get("created_at").and_then(|v| v.as_u64()).unwrap_or(0),
+                    is_agent,
                     msg,
                 ));
             }
         }
     }
 
-    // Sort replies chronologically.
-    reply_msgs.sort_by_key(|(ts, _)| *ts);
+    let root_present = root_msg.is_some();
+    let fetched_total = reply_msgs.len() + usize::from(root_present);
+    let newest_agent_reply = reply_msgs
+        .iter()
+        .filter(|(_, _, is_agent, _)| *is_agent)
+        .max_by_key(|(_, ts, _, _)| *ts)
+        .cloned();
+
+    let truncated = reply_msgs.len() > limit as usize;
+    if truncated {
+        // The relay returns limited REQ results newest-first. Sort explicitly so
+        // the sentinel we drop is the oldest reply in the fetched window, not an
+        // arbitrary last element if the HTTP bridge ever changes iteration order.
+        reply_msgs.sort_by_key(|(_, ts, _, _)| Reverse(*ts));
+        reply_msgs.truncate(limit as usize);
+    }
+
+    if let Some(agent_reply) = newest_agent_reply {
+        let agent_reply_already_displayed =
+            reply_msgs.iter().any(|(id, _, _, _)| *id == agent_reply.0);
+        if !agent_reply_already_displayed {
+            reply_msgs.sort_by_key(|(_, ts, _, _)| *ts);
+            if let Some(oldest) = reply_msgs.first_mut() {
+                *oldest = agent_reply;
+            }
+        }
+    }
+
+    // Sort displayed replies chronologically.
+    reply_msgs.sort_by_key(|(_, ts, _, _)| *ts);
 
     let mut messages = Vec::new();
     if let Some(root) = root_msg {
         messages.push(root);
     }
-    messages.extend(reply_msgs.into_iter().map(|(_, msg)| msg));
+    messages.extend(reply_msgs.into_iter().map(|(_, _, _, msg)| msg));
 
-    let total = messages.len();
     if messages.is_empty() {
         return None;
     }
 
-    Some(ConversationContext::Thread {
-        messages,
-        total,
-        truncated: false, // query returns all within limit
+    let total = if truncated {
+        fetched_total // all distinct fetched replies plus the root are proven visible history
+    } else {
+        messages.len()
+    };
+
+    Some(ParsedThreadContext {
+        context: ConversationContext::Thread {
+            messages,
+            total,
+            truncated,
+        },
+        root_present,
     })
 }
 
@@ -3131,12 +3342,19 @@ fn classify_control_cancel_failure(
     }
 }
 
-/// Log a stop reason at the appropriate tracing level.
-fn log_stop_reason(source: &PromptSource, stop_reason: &StopReason) {
-    let label = match source {
+/// How a turn's source is named in the `pool::prompt` log lines.
+///
+/// Shared by the turn-start and turn-stop lines so a log can be read as pairs.
+fn prompt_label(source: &PromptSource) -> String {
+    match source {
         PromptSource::Channel(cid) => format!("channel {cid}"),
         PromptSource::Heartbeat => "heartbeat".to_string(),
-    };
+    }
+}
+
+/// Log a stop reason at the appropriate tracing level.
+fn log_stop_reason(source: &PromptSource, stop_reason: &StopReason) {
+    let label = prompt_label(source);
     match stop_reason {
         StopReason::EndTurn => {
             tracing::info!(target: "pool::prompt", "turn complete for {label}: end_turn");
@@ -3390,35 +3608,41 @@ fn acp_stop_to_core(r: &StopReason) -> buzz_core::agent_turn_metric::StopReason
     }
 }
 
-/// Best-effort: build and publish a `kind:44200` NIP-AM agent turn metric event.
+/// Build the `(turn, cumulative)` `TokenCounts` pair for a NIP-AM kind-44200
+/// payload from a completed `TurnUsage`.
 ///
-/// Does nothing when `usage` is `None` (goose emitted no usage notification
-/// for this turn) or when `owner_pubkey` is unconfigured (no NIP-AO identity).
-/// Errors are logged at WARN and never surface to the caller — metric
-/// publishing must never fail a turn.
-async fn publish_agent_turn_metric(
-    ctx: &PromptContext,
-    usage: Option<crate::usage::TurnUsage>,
-    channel_id: Option<uuid::Uuid>,
-    session_id: &str,
-    turn_id: &str,
-    stop_reason: Option<buzz_core::agent_turn_metric::StopReason>,
+/// Extracted as a pure function so the mapping logic can be tested independently
+/// of relay/crypto infrastructure. `publish_agent_turn_metric` is the only
+/// production caller.
+///
+/// - `turn` is `None` when `delta_reliable` is false; otherwise it carries the
+///   per-turn i/o/total/cost deltas for this turn.
+/// - `cumulative` always carries the session-aggregate i/o/cost totals.
+///   `total_tokens` is `Some` only when the session accumulated a genuine
+///   provider-reported total on every turn — never derived from i/o sums
+///   (NIP-AM MUST NOT).
+pub(crate) fn build_turn_metric_counts(
+    usage: &crate::usage::TurnUsage,
+) -> (
+    Option<buzz_core::agent_turn_metric::TokenCounts>,
+    Option<buzz_core::agent_turn_metric::TokenCounts>,
 ) {
-    use buzz_core::agent_turn_metric::{AgentTurnMetricPayload, TokenCounts};
-    use nostr::{EventBuilder, Kind, Tag};
-
-    let (usage, owner_pk) = match (usage, ctx.agent_owner_pubkey.as_ref()) {
-        (Some(u), Some(pk)) => (u, pk),
-        _ => return,
-    };
+    use buzz_core::agent_turn_metric::TokenCounts;
 
     let turn_counts = if usage.delta_reliable {
         Some(TokenCounts {
             input_tokens: usage.turn_input_tokens,
             output_tokens: usage.turn_output_tokens,
-            total_tokens: None,
+            // Field-local: present only when both the previous and current
+            // cumulative totals were available and monotonic. Never derived
+            // from input+output.
+            total_tokens: usage.turn_total_tokens,
             cost_usd: usage.turn_cost_usd,
-            cache_read_tokens: None,
+            // Field-local: present when the cumulative counter was monotonic
+            // across this turn. Zero means no cache hits this turn (not absent).
+            cache_read_tokens: usage.turn_cache_read_tokens,
+            // buzz-agent does not emit a cache-write count on the wire today;
+            // leave None rather than deriving it from other fields.
             cache_write_tokens: None,
         })
     } else {
@@ -3431,11 +3655,46 @@ async fn publish_agent_turn_metric(
     let cumulative_counts = Some(TokenCounts {
         input_tokens: Some(usage.cumulative_input_tokens),
         output_tokens: Some(usage.cumulative_output_tokens),
-        total_tokens: None,
+        // Present when every turn in the session reported a genuine provider
+        // total. None when the session has never emitted one or any turn lacked
+        // one. Never derived from input+output (NIP-AM MUST NOT).
+        total_tokens: usage.cumulative_total_tokens,
         cost_usd: usage.cumulative_cost_usd,
-        cache_read_tokens: None,
+        // Session-cumulative cache-read tokens; None when the harness never
+        // reported this field (e.g. goose or older buzz-agent sessions).
+        // Passes through directly — do not wrap in Some() as the field already
+        // carries provenance (None vs Some(0) are distinct meanings).
+        cache_read_tokens: usage.cumulative_cache_read_tokens,
+        // buzz-agent does not emit a cache-write count on the wire today;
+        // leave None rather than deriving it from other fields.
         cache_write_tokens: None,
     });
+    (turn_counts, cumulative_counts)
+}
+
+/// Best-effort: build and publish a `kind:44200` NIP-AM agent turn metric event.
+///
+/// Does nothing when `usage` is `None` (goose emitted no usage notification
+/// for this turn) or when `owner_pubkey` is unconfigured (no NIP-AO identity).
+/// Errors are logged at WARN and never surface to the caller — metric
+/// publishing must never fail a turn.
+async fn publish_agent_turn_metric(
+    ctx: &PromptContext,
+    usage: Option<crate::usage::TurnUsage>,
+    channel_id: Option<uuid::Uuid>,
+    session_id: &str,
+    turn_id: &str,
+    stop_reason: Option<buzz_core::agent_turn_metric::StopReason>,
+) {
+    use buzz_core::agent_turn_metric::AgentTurnMetricPayload;
+    use nostr::{EventBuilder, Kind, Tag};
+
+    let (usage, owner_pk) = match (usage, ctx.agent_owner_pubkey.as_ref()) {
+        (Some(u), Some(pk)) => (u, pk),
+        _ => return,
+    };
+
+    let (turn_counts, cumulative_counts) = build_turn_metric_counts(&usage);
     let timestamp = chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Millis, true);
     let payload = AgentTurnMetricPayload {
         harness: ctx.harness_name.clone(),
@@ -3758,18 +4017,48 @@ mod tests {
         assert!(has_system_prompt_support(2, "goose", Some(true)));
         assert!(has_system_prompt_support(1, "goose", Some(true)));
         assert!(has_system_prompt_support(2, "buzz-agent", None));
+        // Goose never receives system prompt via session/new (uses post-hoc method).
         assert_eq!(
-            session_new_system_prompt(true, 2, Some("instructions")),
+            session_new_system_prompt(true, 2, "goose", Some("instructions")),
             None
         );
+        // Protocol-v2 non-goose gets Field transport.
         assert_eq!(
-            session_new_system_prompt(false, 2, Some("instructions")),
-            Some("instructions")
+            session_new_system_prompt(false, 2, "buzz-agent", Some("instructions")),
+            Some(SystemPromptTransport::Field("instructions"))
         );
+        // Protocol-v1 non-goose, non-claude gets None (legacy user-message framing).
         assert_eq!(
-            session_new_system_prompt(false, 1, Some("instructions")),
+            session_new_system_prompt(false, 1, "codex", Some("instructions")),
             None
         );
+        // claude-agent-acp gets ClaudeMeta transport regardless of protocol version.
+        assert_eq!(
+            session_new_system_prompt(false, 1, CLAUDE_AGENT_ACP_NAME, Some("instructions")),
+            Some(SystemPromptTransport::ClaudeMeta("instructions"))
+        );
+        assert_eq!(
+            session_new_system_prompt(true, 1, CLAUDE_AGENT_ACP_NAME, Some("instructions")),
+            None,
+            "goose path must never produce a transport even when agent_name matches"
+        );
+    }
+
+    #[test]
+    fn claude_agent_acp_has_system_prompt_support_regardless_of_protocol_version() {
+        // claude-agent-acp declares protocolVersion:1 but supports _meta.systemPrompt;
+        // has_system_prompt_support must return true so user-message framing is suppressed.
+        assert!(has_system_prompt_support(1, CLAUDE_AGENT_ACP_NAME, None));
+        assert!(has_system_prompt_support(2, CLAUDE_AGENT_ACP_NAME, None));
+    }
+
+    #[test]
+    fn old_zed_adapter_name_falls_through_to_protocol_version_gate() {
+        // The renamed @zed-industries package predates the _meta.systemPrompt support,
+        // so it must not be treated as capable and stays on legacy user-message framing.
+        let old_name = "@zed-industries/claude-code-acp";
+        assert!(!has_system_prompt_support(1, old_name, None));
+        assert!(has_system_prompt_support(2, old_name, None));
     }
 
     #[test]
@@ -4154,6 +4443,572 @@ mod tests {
         assert!(parse_dm_response(json, 12).is_none());
     }
 
+    #[test]
+    fn test_parse_nostr_thread_response_marks_query_window_truncated() {
+        let agent = Keys::generate();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let agent_hex = agent.public_key().to_hex();
+        let json = json!([
+            {
+                "id": root_id,
+                "pubkey": "rootpub",
+                "content": "root",
+                "created_at": 1000
+            },
+            {
+                "id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "pubkey": agent_hex,
+                "content": "newest agent reply",
+                "created_at": 4000
+            },
+            {
+                "id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+                "pubkey": "humanpub",
+                "content": "middle reply",
+                "created_at": 3000
+            },
+            {
+                "id": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                "pubkey": "oldpub",
+                "content": "sentinel omitted reply",
+                "created_at": 2000
+            }
+        ]);
+
+        let ctx = parse_nostr_thread_response(json, root_id, 2, &agent.public_key())
+            .expect("should parse");
+        match ctx {
+            ConversationContext::Thread {
+                messages,
+                total,
+                truncated,
+            } => {
+                assert_eq!(messages.len(), 3); // root + 2 displayed replies
+                assert_eq!(total, 4); // root + displayed replies + sentinel
+                assert!(truncated);
+                assert_eq!(messages[0].content, "root");
+                assert_eq!(messages[1].content, "middle reply");
+                assert_eq!(messages[2].content, "newest agent reply");
+                assert!(messages
+                    .iter()
+                    .all(|msg| msg.content != "sentinel omitted reply"));
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    #[test]
+    fn test_parse_nostr_thread_response_not_truncated_below_limit() {
+        let agent = Keys::generate();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let json = json!([
+            {
+                "id": root_id,
+                "pubkey": "rootpub",
+                "content": "root",
+                "created_at": 1000
+            },
+            {
+                "id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "pubkey": "replypub",
+                "content": "reply",
+                "created_at": 2000
+            }
+        ]);
+
+        let ctx = parse_nostr_thread_response(json, root_id, 2, &agent.public_key())
+            .expect("should parse");
+        match ctx {
+            ConversationContext::Thread {
+                messages,
+                total,
+                truncated,
+            } => {
+                assert_eq!(messages.len(), 2);
+                assert_eq!(total, 2);
+                assert!(!truncated);
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    #[test]
+    fn test_parse_nostr_thread_response_keeps_agent_reply_outside_recent_window() {
+        let agent = Keys::generate();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let agent_hex = agent.public_key().to_hex();
+        let json = json!([
+            {
+                "id": root_id,
+                "pubkey": "rootpub",
+                "content": "root",
+                "created_at": 1000
+            },
+            {
+                "id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "pubkey": "humanpub",
+                "content": "newer human reply",
+                "created_at": 5000
+            },
+            {
+                "id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+                "pubkey": "humanpub",
+                "content": "middle human reply",
+                "created_at": 4000
+            },
+            {
+                "id": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                "pubkey": "humanpub",
+                "content": "oldest displayed reply without agent pin",
+                "created_at": 3000
+            },
+            {
+                "id": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
+                "pubkey": agent_hex,
+                "content": "agent reply outside recent window",
+                "created_at": 2000
+            }
+        ]);
+
+        let ctx = parse_nostr_thread_response(json, root_id, 2, &agent.public_key())
+            .expect("should parse");
+        match ctx {
+            ConversationContext::Thread { messages, .. } => {
+                assert_eq!(messages.len(), 3); // root + 2 displayed replies
+                assert_eq!(messages[0].content, "root");
+                assert!(messages
+                    .iter()
+                    .any(|msg| msg.content == "agent reply outside recent window"));
+                assert!(messages
+                    .iter()
+                    .any(|msg| msg.content == "newer human reply"));
+                assert!(messages
+                    .iter()
+                    .all(|msg| msg.content != "middle human reply"));
+                assert!(messages
+                    .iter()
+                    .all(|msg| msg.content != "oldest displayed reply without agent pin"));
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_fetch_thread_context_uses_exact_count_when_above_sentinel_minimum() {
+        let agent = Keys::generate();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let channel_id = Uuid::new_v4();
+        let agent_pubkey = agent.public_key();
+        let json = json!([
+            thread_event(root_id, "rootpub", "root", 1000),
+            thread_event(
+                "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "humanpub",
+                "newest reply",
+                4000
+            ),
+            thread_event(
+                "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+                "humanpub",
+                "middle reply",
+                3000
+            ),
+            thread_event(
+                "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                "humanpub",
+                "sentinel reply",
+                2000
+            )
+        ]);
+
+        let ctx = fetch_thread_context_with(
+            channel_id,
+            root_id,
+            2,
+            agent_pubkey,
+            move |filters| {
+                assert_thread_query_filters(&filters, channel_id, root_id, agent_pubkey, 3);
+                std::future::ready(Ok(json.clone()))
+            },
+            move |filters| {
+                assert_thread_count_filter(&filters, channel_id, root_id);
+                std::future::ready(Ok(json!({ "count": 6 })))
+            },
+        )
+        .await
+        .expect("thread context");
+
+        match ctx {
+            ConversationContext::Thread {
+                messages,
+                total,
+                truncated,
+            } => {
+                assert!(truncated);
+                assert_eq!(messages.len(), 3);
+                assert_eq!(total, 7); // 6 replies + root
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_fetch_thread_context_does_not_add_missing_root_to_exact_count() {
+        let agent = Keys::generate();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let channel_id = Uuid::new_v4();
+        let json = json!([
+            thread_event(
+                "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "humanpub",
+                "newest reply",
+                4000
+            ),
+            thread_event(
+                "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+                "humanpub",
+                "middle reply",
+                3000
+            ),
+            thread_event(
+                "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                "humanpub",
+                "sentinel reply",
+                2000
+            )
+        ]);
+
+        let ctx = fetch_thread_context_with(
+            channel_id,
+            root_id,
+            2,
+            agent.public_key(),
+            move |_filters| std::future::ready(Ok(json.clone())),
+            |_filters| std::future::ready(Ok(json!({ "count": 6 }))),
+        )
+        .await
+        .expect("thread context");
+
+        match ctx {
+            ConversationContext::Thread {
+                messages,
+                total,
+                truncated,
+            } => {
+                assert!(truncated);
+                assert_eq!(messages.len(), 2);
+                assert_eq!(total, 6);
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_fetch_thread_context_clamps_count_below_sentinel_minimum() {
+        let agent = Keys::generate();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let channel_id = Uuid::new_v4();
+        let json = json!([
+            thread_event(root_id, "rootpub", "root", 1000),
+            thread_event(
+                "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "humanpub",
+                "newest reply",
+                4000
+            ),
+            thread_event(
+                "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+                "humanpub",
+                "middle reply",
+                3000
+            ),
+            thread_event(
+                "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                "humanpub",
+                "sentinel reply",
+                2000
+            )
+        ]);
+
+        let ctx = fetch_thread_context_with(
+            channel_id,
+            root_id,
+            2,
+            agent.public_key(),
+            move |_filters| std::future::ready(Ok(json.clone())),
+            |_filters| std::future::ready(Ok(json!({ "count": 1 }))),
+        )
+        .await
+        .expect("thread context");
+
+        match ctx {
+            ConversationContext::Thread {
+                messages,
+                total,
+                truncated,
+            } => {
+                assert!(truncated);
+                assert_eq!(messages.len(), 3);
+                assert_eq!(total, 4); // root + displayed replies + sentinel minimum
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_fetch_thread_context_preserves_sentinel_minimum_when_count_fails() {
+        let agent = Keys::generate();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let channel_id = Uuid::new_v4();
+        let json = json!([
+            thread_event(root_id, "rootpub", "root", 1000),
+            thread_event(
+                "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "humanpub",
+                "newest reply",
+                4000
+            ),
+            thread_event(
+                "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+                "humanpub",
+                "middle reply",
+                3000
+            ),
+            thread_event(
+                "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                "humanpub",
+                "sentinel reply",
+                2000
+            )
+        ]);
+
+        let ctx = fetch_thread_context_with(
+            channel_id,
+            root_id,
+            2,
+            agent.public_key(),
+            move |_filters| std::future::ready(Ok(json.clone())),
+            |_filters| std::future::ready(Err(crate::relay::RelayError::Http("boom".into()))),
+        )
+        .await
+        .expect("thread context");
+
+        match ctx {
+            ConversationContext::Thread {
+                messages,
+                total,
+                truncated,
+            } => {
+                assert!(truncated);
+                assert_eq!(messages.len(), 3);
+                assert_eq!(total, 4); // count failure leaves parser's sentinel minimum intact
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_fetch_thread_context_deduplicates_and_pins_agent_reply() {
+        let agent = Keys::generate();
+        let agent_hex = agent.public_key().to_hex();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let channel_id = Uuid::new_v4();
+        let json = json!([
+            thread_event(root_id, "rootpub", "root", 1000),
+            thread_event(
+                "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "humanpub",
+                "newer human reply",
+                5000
+            ),
+            thread_event(
+                "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+                "humanpub",
+                "middle human reply",
+                4000
+            ),
+            thread_event(
+                "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                &agent_hex,
+                "agent reply outside recent window",
+                2000
+            ),
+            // Same event as the separately fetched author-filtered result; the
+            // parser should deduplicate it before pinning.
+            thread_event(
+                "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                &agent_hex,
+                "agent reply outside recent window",
+                2000
+            )
+        ]);
+
+        let ctx = fetch_thread_context_with(
+            channel_id,
+            root_id,
+            2,
+            agent.public_key(),
+            move |_filters| std::future::ready(Ok(json.clone())),
+            |_filters| std::future::ready(Ok(json!({ "count": 3 }))),
+        )
+        .await
+        .expect("thread context");
+
+        match ctx {
+            ConversationContext::Thread {
+                messages,
+                total,
+                truncated,
+            } => {
+                assert!(truncated);
+                assert_eq!(total, 4);
+                assert_eq!(messages.len(), 3);
+                assert_eq!(
+                    messages
+                        .iter()
+                        .filter(|msg| msg.content == "agent reply outside recent window")
+                        .count(),
+                    1,
+                    "separate agent-reply query must not duplicate the same event"
+                );
+                assert!(messages
+                    .iter()
+                    .any(|msg| msg.content == "newer human reply"));
+                assert!(messages
+                    .iter()
+                    .all(|msg| msg.content != "middle human reply"));
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_fetch_thread_context_uses_distinct_fetched_replies_as_minimum() {
+        let agent = Keys::generate();
+        let agent_hex = agent.public_key().to_hex();
+        let root_id = "1111111111111111111111111111111111111111111111111111111111111111";
+        let channel_id = Uuid::new_v4();
+        let json = json!([
+            thread_event(root_id, "rootpub", "root", 1000),
+            thread_event(
+                "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "humanpub",
+                "newest human reply",
+                5000
+            ),
+            thread_event(
+                "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+                "humanpub",
+                "middle human reply",
+                4000
+            ),
+            thread_event(
+                "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+                "humanpub",
+                "sentinel human reply",
+                3000
+            ),
+            thread_event(
+                "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
+                &agent_hex,
+                "older distinct agent reply",
+                2000
+            )
+        ]);
+
+        let ctx = fetch_thread_context_with(
+            channel_id,
+            root_id,
+            2,
+            agent.public_key(),
+            move |_filters| std::future::ready(Ok(json.clone())),
+            |_filters| std::future::ready(Err(crate::relay::RelayError::Http("boom".into()))),
+        )
+        .await
+        .expect("thread context");
+
+        match ctx {
+            ConversationContext::Thread {
+                messages,
+                total,
+                truncated,
+            } => {
+                assert!(truncated);
+                assert_eq!(messages.len(), 3);
+                assert_eq!(
+                    total, 5,
+                    "root plus all four distinct fetched replies prove the lower bound"
+                );
+                assert!(messages
+                    .iter()
+                    .any(|msg| msg.content == "older distinct agent reply"));
+                assert!(messages
+                    .iter()
+                    .any(|msg| msg.content == "newest human reply"));
+                assert!(messages
+                    .iter()
+                    .all(|msg| msg.content != "middle human reply"));
+                assert!(messages
+                    .iter()
+                    .all(|msg| msg.content != "sentinel human reply"));
+            }
+            _ => panic!("expected Thread context"),
+        }
+    }
+
+    fn assert_thread_query_filters(
+        filters: &[nostr::Filter],
+        channel_id: Uuid,
+        root_id: &str,
+        agent_pubkey: nostr::PublicKey,
+        reply_limit: u64,
+    ) {
+        assert_eq!(
+            filters.len(),
+            3,
+            "root, recent replies, and agent reply filters"
+        );
+
+        let root = serde_json::to_value(&filters[0]).expect("serialize root filter");
+        assert_eq!(root.get("ids"), Some(&json!([root_id])));
+        assert!(root.get("limit").is_none());
+
+        let replies = serde_json::to_value(&filters[1]).expect("serialize replies filter");
+        assert_eq!(replies.get("kinds"), Some(&json!([9, 40002])));
+        assert_eq!(replies.get("#e"), Some(&json!([root_id])));
+        assert_eq!(replies.get("#h"), Some(&json!([channel_id.to_string()])));
+        assert_eq!(replies.get("limit"), Some(&json!(reply_limit)));
+        assert!(replies.get("authors").is_none());
+
+        let agent = serde_json::to_value(&filters[2]).expect("serialize agent filter");
+        assert_eq!(agent.get("kinds"), Some(&json!([9, 40002])));
+        assert_eq!(agent.get("#e"), Some(&json!([root_id])));
+        assert_eq!(agent.get("#h"), Some(&json!([channel_id.to_string()])));
+        assert_eq!(agent.get("authors"), Some(&json!([agent_pubkey.to_hex()])));
+        assert_eq!(agent.get("limit"), Some(&json!(1)));
+    }
+
+    fn assert_thread_count_filter(filters: &[nostr::Filter], channel_id: Uuid, root_id: &str) {
+        assert_eq!(filters.len(), 1, "count should query only matching replies");
+
+        let count = serde_json::to_value(&filters[0]).expect("serialize count filter");
+        assert_eq!(count.get("kinds"), Some(&json!([9, 40002])));
+        assert_eq!(count.get("#e"), Some(&json!([root_id])));
+        assert_eq!(count.get("#h"), Some(&json!([channel_id.to_string()])));
+        assert_eq!(count.get("limit"), Some(&json!(0)));
+        assert!(count.get("ids").is_none());
+        assert!(count.get("authors").is_none());
+    }
+
+    fn thread_event(id: &str, pubkey: &str, content: &str, created_at: u64) -> serde_json::Value {
+        json!({
+            "id": id,
+            "pubkey": pubkey,
+            "content": content,
+            "created_at": created_at
+        })
+    }
+
     #[test]
     fn test_json_to_context_message_integer_timestamp() {
         let obj = json!({
@@ -5219,10 +6074,14 @@ mod tests {
             delta_reliable: true,
             turn_input_tokens: Some(100),
             turn_output_tokens: Some(50),
+            turn_total_tokens: None,
             turn_cost_usd: None,
+            turn_cache_read_tokens: None,
             cumulative_input_tokens: 100,
             cumulative_output_tokens: 50,
+            cumulative_total_tokens: None,
             cumulative_cost_usd: None,
+            cumulative_cache_read_tokens: None,
             model: None,
         };
         // owner_pubkey = None → early return, no panic.
@@ -5251,10 +6110,14 @@ mod tests {
             delta_reliable: true,
             turn_input_tokens: Some(200),
             turn_output_tokens: Some(80),
+            turn_total_tokens: None,
             turn_cost_usd: Some(0.001),
+            turn_cache_read_tokens: None,
             cumulative_input_tokens: 200,
             cumulative_output_tokens: 80,
+            cumulative_total_tokens: None,
             cumulative_cost_usd: Some(0.001),
+            cumulative_cache_read_tokens: None,
             model: None,
         };
         // Will try to publish and fail (no real relay) but must not panic.
@@ -5284,10 +6147,14 @@ mod tests {
             delta_reliable: true,
             turn_input_tokens: Some(50),
             turn_output_tokens: Some(20),
+            turn_total_tokens: None,
             turn_cost_usd: None,
+            turn_cache_read_tokens: None,
             cumulative_input_tokens: 150,
             cumulative_output_tokens: 70,
+            cumulative_total_tokens: None,
             cumulative_cost_usd: None,
+            cumulative_cache_read_tokens: None,
             model: None,
         };
         // Must not panic; HTTP submit will fail (no real relay) — that's fine.
@@ -5317,10 +6184,14 @@ mod tests {
             delta_reliable: false, // first turn from buzz-agent
             turn_input_tokens: None,
             turn_output_tokens: None,
+            turn_total_tokens: None,
             turn_cost_usd: None,
+            turn_cache_read_tokens: None,
             cumulative_input_tokens: 400,
             cumulative_output_tokens: 100,
+            cumulative_total_tokens: None,
             cumulative_cost_usd: None,
+            cumulative_cache_read_tokens: None,
             model: None,
         };
         // Will try to publish (encrypt succeeds) and fail HTTP (no relay) — must not panic.
@@ -5335,6 +6206,204 @@ mod tests {
         .await;
     }
 
+    /// `build_turn_metric_counts` maps exact turn and cumulative totals from
+    /// `TurnUsage` to the corresponding `TokenCounts.total_tokens` fields.
+    /// Reverting the production fields at the call site to `None` would break
+    /// this test; the test constrains the real code path.
+    #[test]
+    fn test_build_turn_metric_counts_exact_totals_map_through() {
+        let usage = crate::usage::TurnUsage {
+            session_id: "sess-total".to_string(),
+            turn_seq: 2,
+            delta_reliable: true,
+            turn_input_tokens: Some(100),
+            turn_output_tokens: Some(30),
+            turn_total_tokens: Some(130), // genuine per-turn total
+            turn_cost_usd: None,
+            turn_cache_read_tokens: None,
+            cumulative_input_tokens: 500,
+            cumulative_output_tokens: 120,
+            cumulative_total_tokens: Some(620), // genuine cumulative total
+            cumulative_cost_usd: None,
+            cumulative_cache_read_tokens: None,
+            model: None,
+        };
+
+        let (turn, cumulative) = crate::pool::build_turn_metric_counts(&usage);
+
+        // Serialise to JSON — this is what ultimately goes on the wire.
+        let turn_json = serde_json::to_value(turn.as_ref().expect("turn counts present")).unwrap();
+        let cum_json =
+            serde_json::to_value(cumulative.as_ref().expect("cumulative counts present")).unwrap();
+
+        // Per-turn total must be the genuine provider-reported value.
+        assert_eq!(
+            turn_json["totalTokens"],
+            serde_json::json!(130),
+            "per-turn total must map to TokenCounts.totalTokens in wire JSON"
+        );
+        assert_eq!(turn_json["inputTokens"], serde_json::json!(100));
+        assert_eq!(turn_json["outputTokens"], serde_json::json!(30));
+
+        // Cumulative total must be the genuine session total.
+        assert_eq!(
+            cum_json["totalTokens"],
+            serde_json::json!(620),
+            "cumulative total must map to TokenCounts.totalTokens in wire JSON"
+        );
+        assert_eq!(cum_json["inputTokens"], serde_json::json!(500));
+        assert_eq!(cum_json["outputTokens"], serde_json::json!(120));
+    }
+
+    /// When totals are absent, `build_turn_metric_counts` must produce null
+    /// `total_tokens` — never a derived input+output sum (NIP-AM MUST NOT).
+    /// Reverting the production fields to hardcoded `None` would leave this test
+    /// passing but input/output would disagree, making the null-path detectable.
+    #[test]
+    fn test_build_turn_metric_counts_null_totals_never_derived() {
+        let usage = crate::usage::TurnUsage {
+            session_id: "sess-nototal".to_string(),
+            turn_seq: 1,
+            delta_reliable: true,
+            turn_input_tokens: Some(200),
+            turn_output_tokens: Some(60),
+            turn_total_tokens: None, // provider did not supply a total
+            turn_cost_usd: None,
+            turn_cache_read_tokens: None,
+            cumulative_input_tokens: 200,
+            cumulative_output_tokens: 60,
+            cumulative_total_tokens: None, // session has no total
+            cumulative_cost_usd: None,
+            cumulative_cache_read_tokens: None,
+            model: None,
+        };
+
+        let (turn, cumulative) = crate::pool::build_turn_metric_counts(&usage);
+
+        let turn_json = serde_json::to_value(turn.as_ref().expect("turn counts present")).unwrap();
+        let cum_json =
+            serde_json::to_value(cumulative.as_ref().expect("cumulative counts present")).unwrap();
+
+        // total_tokens must be null in the wire JSON.
+        assert!(
+            turn_json["totalTokens"].is_null(),
+            "absent turn total must serialize as null — not derived from in+out"
+        );
+        assert!(
+            cum_json["totalTokens"].is_null(),
+            "absent cumulative total must serialize as null — not derived from in+out"
+        );
+
+        // Input/output must still carry their real values.
+        assert_eq!(
+            turn_json["inputTokens"],
+            serde_json::json!(200),
+            "inputTokens must be present even when total is absent"
+        );
+        assert_eq!(
+            turn_json["outputTokens"],
+            serde_json::json!(60),
+            "outputTokens must be present even when total is absent"
+        );
+
+        // The null total must not equal the input+output sum — it must be genuinely null.
+        let derived_sum = serde_json::json!(200u64 + 60u64);
+        assert_ne!(
+            turn_json["totalTokens"], derived_sum,
+            "total_tokens must never equal input+output when provider omitted it"
+        );
+    }
+
+    /// A payload with nonzero `accumulatedCachedInputTokens` on the second turn
+    /// must produce a kind:44200 payload where `cumulative.cacheReadTokens` is
+    /// nonzero and `turn.cacheReadTokens` reflects the per-turn delta.
+    /// This is the acceptance-criterion test: it proves the threading is live,
+    /// not hardcoded to None.
+    #[test]
+    fn test_build_turn_metric_counts_cache_read_tokens_thread_through() {
+        // Wire-parse a buzz-agent payload with cache, run it through the tracker,
+        // and verify the published TokenCounts carry the cache field.
+        let raw1 = serde_json::json!({
+            "sessionId": "cache-sess",
+            "update": {
+                "sessionUpdate": "usage_update",
+                "accumulatedInputTokens": 15_091,
+                "accumulatedOutputTokens": 156,
+                "accumulatedCachedInputTokens": 5_033,
+            }
+        });
+        let raw2 = serde_json::json!({
+            "sessionId": "cache-sess",
+            "update": {
+                "sessionUpdate": "usage_update",
+                "accumulatedInputTokens": 28_500,
+                "accumulatedOutputTokens": 310,
+                "accumulatedCachedInputTokens": 11_000,
+            }
+        });
+
+        let mut tracker = crate::usage::UsageTracker::default();
+
+        // Turn 1 — establish baseline (delta unreliable, but cumulative still present).
+        tracker.begin_turn("cache-sess");
+        if let crate::usage::GooseSessionUpdateVariant::UsageUpdate(p) =
+            serde_json::from_value::<crate::usage::GooseSessionUpdateNotification>(raw1)
+                .unwrap()
+                .update
+        {
+            tracker.record("cache-sess", &p);
+        }
+        let t1 = tracker.take().expect("turn 1");
+
+        // Turn 1: cumulative must carry the cache count; turn delta is None (no baseline).
+        let (turn1, cum1) = crate::pool::build_turn_metric_counts(&t1);
+        // delta_reliable = false on first turn → no turn counts.
+        assert!(turn1.is_none(), "first turn: no reliable turn counts");
+        let cum1 = cum1.expect("cumulative always present");
+        assert_eq!(
+            cum1.cache_read_tokens,
+            Some(5_033),
+            "cumulative.cacheReadTokens must be 5033 after turn 1"
+        );
+
+        // Turn 2 — delta reliable.
+        tracker.begin_turn("cache-sess");
+        if let crate::usage::GooseSessionUpdateVariant::UsageUpdate(p) =
+            serde_json::from_value::<crate::usage::GooseSessionUpdateNotification>(raw2)
+                .unwrap()
+                .update
+        {
+            tracker.record("cache-sess", &p);
+        }
+        let t2 = tracker.take().expect("turn 2");
+
+        let (turn2, cum2) = crate::pool::build_turn_metric_counts(&t2);
+
+        let turn2 = turn2.expect("reliable turn counts on turn 2");
+        // Per-turn cache delta: 11_000 - 5_033 = 5_967.
+        assert_eq!(
+            turn2.cache_read_tokens,
+            Some(5_967),
+            "turn.cacheReadTokens must be the per-turn delta"
+        );
+        // cache_write_tokens is always None — buzz-agent doesn't emit it.
+        assert!(
+            turn2.cache_write_tokens.is_none(),
+            "cache_write_tokens must be None — not emitted by buzz-agent"
+        );
+
+        let cum2 = cum2.expect("cumulative always present");
+        assert_eq!(
+            cum2.cache_read_tokens,
+            Some(11_000),
+            "cumulative.cacheReadTokens must be 11_000 after turn 2"
+        );
+        assert!(
+            cum2.cache_write_tokens.is_none(),
+            "cache_write_tokens must be None on cumulative too"
+        );
+    }
+
     fn make_prompt_context_no_owner() -> PromptContext {
         let agent_keys = nostr::Keys::generate();
         make_prompt_context_impl(&agent_keys, None)
diff --git a/crates/buzz-acp/src/queue.rs b/crates/buzz-acp/src/queue.rs
index 029bf86dbf..5c960de202 100644
--- a/crates/buzz-acp/src/queue.rs
+++ b/crates/buzz-acp/src/queue.rs
@@ -646,6 +646,11 @@ impl EventQueue {
         self.in_flight_channels.contains(&channel_id)
     }
 
+    /// Whether any channel currently has a turn in flight.
+    pub fn has_in_flight(&self) -> bool {
+        !self.in_flight_channels.is_empty()
+    }
+
     // ── Goose-native steer withhold (side table) ──────────────────────────
     //
     // While a goose-native `_goose/unstable/session/steer` write is in flight
diff --git a/crates/buzz-acp/src/relay.rs b/crates/buzz-acp/src/relay.rs
index c8312cc61e..aea5cee077 100644
--- a/crates/buzz-acp/src/relay.rs
+++ b/crates/buzz-acp/src/relay.rs
@@ -405,6 +405,19 @@ impl RestClient {
             .map_err(|e| RelayError::Http(e.to_string()))
     }
 
+    /// Count events via the HTTP bridge: `POST /count` with NIP-98 auth.
+    ///
+    /// Accepts a slice of `nostr::Filter` (serialized as JSON array).
+    /// Returns the bridge response as a `serde_json::Value` (usually `{ "count": n }`).
+    pub async fn count(&self, filters: &[nostr::Filter]) -> Result<Value, RelayError> {
+        let body_bytes = serde_json::to_vec(filters)
+            .map_err(|e| RelayError::Http(format!("filter serialize error: {e}")))?;
+        let resp = self.bridge_post("/count", &body_bytes).await?;
+        resp.json()
+            .await
+            .map_err(|e| RelayError::Http(e.to_string()))
+    }
+
     /// Submit a signed event via the HTTP bridge: `POST /events` with NIP-98 auth.
     ///
     /// The event must already be signed. Returns the relay response JSON.
diff --git a/crates/buzz-acp/src/usage.rs b/crates/buzz-acp/src/usage.rs
index a4f7abd3b3..56b772d12c 100644
--- a/crates/buzz-acp/src/usage.rs
+++ b/crates/buzz-acp/src/usage.rs
@@ -85,7 +85,25 @@ pub(crate) struct UsageUpdatePayload {
     pub context_limit: u64,
     pub accumulated_input_tokens: u64,
     pub accumulated_output_tokens: u64,
+    /// The cache-served subset of `accumulated_input_tokens`.
+    ///
+    /// `None` when the harness did not include the field (e.g. goose, which
+    /// never emits it). `Some(0)` when the harness explicitly reported zero
+    /// cache hits. The distinction matters: `None` means "we don't know",
+    /// while `Some(0)` means "provider confirmed no cache was used".
+    ///
+    /// Do NOT use `#[serde(default)]` here — that would collapse the absent
+    /// case into `Some(0)` and destroy provenance in the append-only archive.
+    pub accumulated_cached_input_tokens: Option<u64>,
     pub accumulated_cost: Option<f64>,
+    /// Session-cumulative genuine provider total tokens. Optional — only
+    /// emitted by buzz-agent when every turn in the session so far supplied a
+    /// provider-reported total. Absent for goose (field ignore-if-absent for
+    /// backward compat), for Anthropic-backed turns, and for sessions where any
+    /// turn lacked a provider total. NIP-AM forbids deriving this by summing
+    /// categories, so the UI must approximate when this field is absent.
+    #[serde(default)]
+    pub accumulated_total_tokens: Option<u64>,
     /// Effective model id for this turn. Optional — goose payloads that
     /// predate this field deserialize cleanly as `None`.
     #[serde(default)]
@@ -107,6 +125,16 @@ struct SessionState {
     last_output: u64,
     /// Cumulative cost at the end of the LAST PUBLISHED turn.
     last_cost: Option<f64>,
+    /// Cumulative total tokens at the end of the LAST PUBLISHED turn.
+    /// `None` when the session has never emitted a provider total (Unseen) or
+    /// when any prior turn lacked one (poisoned).
+    last_total: Option<u64>,
+    /// Cumulative cache-read input tokens at the end of the LAST PUBLISHED turn.
+    /// `None` when the harness has never reported this field (e.g. goose).
+    /// `Some(n)` when at least one payload included the field. Field-local:
+    /// a decrease in this counter taints only the cache-read delta, not
+    /// `delta_reliable` or the input/output deltas.
+    last_cached_input: Option<u64>,
 }
 
 /// Per-turn usage record exposed to `TurnCompletionGuard` for NIP-AM publishing.
@@ -125,15 +153,34 @@ pub struct TurnUsage {
     pub turn_input_tokens: Option<u64>,
     /// Per-turn output token delta; `None` when unreliable.
     pub turn_output_tokens: Option<u64>,
+    /// Per-turn total token delta; `None` when the cumulative total is
+    /// unavailable (no baseline, non-monotonic, or either snapshot was absent).
+    /// Field-local: a missing total never flips `delta_reliable` or invalidates
+    /// `turn_input_tokens`/`turn_output_tokens`.
+    pub turn_total_tokens: Option<u64>,
     /// Per-turn cost delta (`current − previous`); `None` when unreliable or
     /// either snapshot is missing.
     pub turn_cost_usd: Option<f64>,
+    /// Per-turn cache-read token delta (`current − previous`); `None` when no
+    /// baseline exists, either snapshot is `None` (harness did not report it),
+    /// or the cumulative counter decreased (field-local taint). Field-local:
+    /// a decrease here never flips `delta_reliable` or invalidates the
+    /// input/output deltas.
+    pub turn_cache_read_tokens: Option<u64>,
     /// Session-cumulative input tokens as reported by goose at end of turn.
     pub cumulative_input_tokens: u64,
     /// Session-cumulative output tokens as reported by goose at end of turn.
     pub cumulative_output_tokens: u64,
+    /// Session-cumulative genuine provider total tokens as reported by buzz-agent;
+    /// `None` when the session has never emitted one or any turn lacked one.
+    pub cumulative_total_tokens: Option<u64>,
     /// Session-cumulative estimated cost in USD; `None` if goose did not report it.
     pub cumulative_cost_usd: Option<f64>,
+    /// Session-cumulative cache-read input tokens as reported by buzz-agent.
+    /// `None` when the harness has never reported this field (e.g. goose or
+    /// any harness that omits `accumulatedCachedInputTokens`).
+    /// `Some(0)` when the harness reported zero cache hits.
+    pub cumulative_cache_read_tokens: Option<u64>,
     /// Effective model id for this turn (maps to NIP-AM `model`). `None` if the
     /// harness did not include the model in its usage notification.
     pub model: Option<String>,
@@ -212,6 +259,8 @@ impl UsageTracker {
         let current_input = payload.accumulated_input_tokens;
         let current_output = payload.accumulated_output_tokens;
         let current_cost = payload.accumulated_cost;
+        let current_total = payload.accumulated_total_tokens;
+        let current_cached_input = payload.accumulated_cached_input_tokens;
 
         // Determine whether this session is currently in-flight so we know
         // whether to set `pending`. We compute the delta regardless so that
@@ -256,6 +305,32 @@ impl UsageTracker {
                 }
             };
 
+        // Total-token delta: field-local — never affects `delta_reliable` or
+        // the input/output deltas. Null when: no baseline exists, either
+        // snapshot is absent, or cumulative total decreased.
+        let turn_total = match self.sessions.get(session_id) {
+            Some(prev) => match (current_total, prev.last_total) {
+                (Some(cur), Some(p)) if cur >= p => Some(cur - p),
+                _ => None, // no baseline, absent on either side, or decrease
+            },
+            None => None, // no baseline yet
+        };
+
+        // Cache-read token delta: field-local — never affects `delta_reliable`
+        // or the input/output deltas. Null when: no baseline exists, either
+        // snapshot is None (harness did not report the field), or the cumulative
+        // counter decreased (harness restart, overflow).
+        // Some(0) is a valid result when both snapshots are Some(0) — it means
+        // the harness confirmed zero cache hits this turn, not that data is absent.
+        let turn_cache_read = match self.sessions.get(session_id) {
+            Some(prev) => match (current_cached_input, prev.last_cached_input) {
+                (Some(cur), Some(p)) if cur >= p => Some(cur - p),
+                (Some(_), Some(_)) => None, // decrease → field-local taint
+                _ => None,                  // either snapshot absent → no delta
+            },
+            None => None, // no baseline yet
+        };
+
         if is_in_flight {
             // In-flight-match: update pending with the latest cumulative values.
             // Baseline is NOT advanced here — it advances only on take().
@@ -265,10 +340,14 @@ impl UsageTracker {
                 delta_reliable,
                 turn_input_tokens: turn_input,
                 turn_output_tokens: turn_output,
+                turn_total_tokens: turn_total,
                 turn_cost_usd: turn_cost,
+                turn_cache_read_tokens: turn_cache_read,
                 cumulative_input_tokens: current_input,
                 cumulative_output_tokens: current_output,
+                cumulative_total_tokens: current_total,
                 cumulative_cost_usd: current_cost,
+                cumulative_cache_read_tokens: current_cached_input,
                 model: payload.model.clone(),
             });
         } else if self.in_flight_session.is_none() {
@@ -286,6 +365,8 @@ impl UsageTracker {
                     last_input: current_input,
                     last_output: current_output,
                     last_cost: current_cost,
+                    last_total: current_total,
+                    last_cached_input: current_cached_input,
                 },
             );
         }
@@ -313,6 +394,8 @@ impl UsageTracker {
                 last_input: record.cumulative_input_tokens,
                 last_output: record.cumulative_output_tokens,
                 last_cost: record.cumulative_cost_usd,
+                last_total: record.cumulative_total_tokens,
+                last_cached_input: record.cumulative_cache_read_tokens,
             },
         );
         Some(record)
@@ -323,13 +406,68 @@ impl UsageTracker {
 mod tests {
     use super::*;
 
+    /// The camelCase key buzz-agent actually puts on the wire must land on the
+    /// field. A rename mismatch here would deserialize to None, and every trial
+    /// would be treated as "not reported" — the exact silent failure this field
+    /// was added to remove.
+    #[test]
+    fn cached_input_tokens_deserialize_from_the_wire_key() {
+        let p: UsageUpdatePayload = serde_json::from_value(serde_json::json!({
+            "used": 15_247,
+            "contextLimit": 0,
+            "accumulatedInputTokens": 15_091,
+            "accumulatedOutputTokens": 156,
+            "accumulatedCachedInputTokens": 5_033,
+        }))
+        .expect("payload must deserialize");
+        assert_eq!(p.accumulated_cached_input_tokens, Some(5_033));
+        assert!(p.accumulated_cached_input_tokens.unwrap() <= p.accumulated_input_tokens);
+    }
+
+    /// goose does not send the field; its payloads must deserialize with None —
+    /// not zero — so that "not reported" is preserved distinct from "reported zero".
+    #[test]
+    fn a_payload_without_the_cache_field_deserializes_as_none() {
+        let p: UsageUpdatePayload = serde_json::from_value(serde_json::json!({
+            "used": 500,
+            "contextLimit": 200_000,
+            "accumulatedInputTokens": 400,
+            "accumulatedOutputTokens": 100,
+        }))
+        .expect("payload must deserialize without the cache field");
+        assert!(
+            p.accumulated_cached_input_tokens.is_none(),
+            "absent field must be None, not Some(0)"
+        );
+    }
+
+    /// A harness that explicitly reports zero cache hits must produce Some(0),
+    /// not None — so downstream analytics can distinguish "confirmed zero" from
+    /// "not reported".
+    #[test]
+    fn a_payload_with_explicit_zero_cache_field_deserializes_as_some_zero() {
+        let p: UsageUpdatePayload = serde_json::from_value(serde_json::json!({
+            "accumulatedInputTokens": 400,
+            "accumulatedOutputTokens": 100,
+            "accumulatedCachedInputTokens": 0,
+        }))
+        .expect("payload must deserialize with zero cache field");
+        assert_eq!(
+            p.accumulated_cached_input_tokens,
+            Some(0),
+            "explicit zero must be Some(0), not None"
+        );
+    }
+
     fn payload(input: u64, output: u64, cost: Option<f64>) -> UsageUpdatePayload {
         UsageUpdatePayload {
             used: input + output,
             context_limit: 200_000,
             accumulated_input_tokens: input,
             accumulated_output_tokens: output,
+            accumulated_cached_input_tokens: None,
             accumulated_cost: cost,
+            accumulated_total_tokens: None,
             model: None,
         }
     }
@@ -340,7 +478,9 @@ mod tests {
             context_limit: 0,
             accumulated_input_tokens: input,
             accumulated_output_tokens: output,
+            accumulated_cached_input_tokens: None,
             accumulated_cost: cost,
+            accumulated_total_tokens: None,
             model: None,
         }
     }
@@ -836,7 +976,9 @@ mod tests {
             context_limit: 200_000,
             accumulated_input_tokens: input,
             accumulated_output_tokens: output,
+            accumulated_cached_input_tokens: None,
             accumulated_cost: cost,
+            accumulated_total_tokens: None,
             model: model.map(str::to_string),
         }
     }
@@ -889,4 +1031,484 @@ mod tests {
             "TurnUsage.model must be None when payload omits the field"
         );
     }
+
+    // ── accumulatedTotalTokens: field-local delta, session poisoning ───────
+
+    fn payload_with_total(input: u64, output: u64, total: Option<u64>) -> UsageUpdatePayload {
+        UsageUpdatePayload {
+            used: input + output,
+            context_limit: 200_000,
+            accumulated_input_tokens: input,
+            accumulated_output_tokens: output,
+            accumulated_cached_input_tokens: None,
+            accumulated_cost: None,
+            accumulated_total_tokens: total,
+            model: None,
+        }
+    }
+
+    #[test]
+    fn first_update_without_baseline_turn_total_is_none() {
+        // No baseline exists → turn total null, but delta_reliable/input/output
+        // follow the normal first-turn rule (delta_reliable = false).
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-t1");
+        tracker.record("sess-t1", &payload_with_total(100, 20, Some(120)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(!usage.delta_reliable, "first turn: delta unreliable");
+        assert!(
+            usage.turn_total_tokens.is_none(),
+            "no baseline → turn total must be None"
+        );
+        assert_eq!(
+            usage.cumulative_total_tokens,
+            Some(120),
+            "cumulative total passes through even on first turn"
+        );
+    }
+
+    #[test]
+    fn second_turn_with_totals_produces_turn_delta() {
+        let mut tracker = UsageTracker::default();
+        // Turn 1 — establish baseline.
+        tracker.begin_turn("sess-t2");
+        tracker.record("sess-t2", &payload_with_total(100, 20, Some(120)));
+        let _ = tracker.take();
+
+        // Turn 2 — delta is computable.
+        tracker.begin_turn("sess-t2");
+        tracker.record("sess-t2", &payload_with_total(200, 50, Some(250)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(usage.delta_reliable);
+        assert_eq!(usage.turn_total_tokens, Some(130)); // 250 - 120
+        assert_eq!(usage.cumulative_total_tokens, Some(250));
+    }
+
+    #[test]
+    fn cumulative_total_decrease_leaves_turn_total_null_without_affecting_reliability() {
+        // Cumulative total decreases (e.g. counter reset) → turn total null,
+        // but delta_reliable and input/output are NOT affected (field-local).
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-t3");
+        tracker.record("sess-t3", &payload_with_total(500, 100, Some(600)));
+        let _ = tracker.take();
+
+        tracker.begin_turn("sess-t3");
+        // Cumulative total decreased: 600 → 50.
+        tracker.record("sess-t3", &payload_with_total(600, 150, Some(50)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(
+            usage.delta_reliable,
+            "input/output decrease would flip reliability; total decrease must not"
+        );
+        assert_eq!(usage.turn_input_tokens, Some(100));
+        assert_eq!(usage.turn_output_tokens, Some(50));
+        assert!(
+            usage.turn_total_tokens.is_none(),
+            "cumulative total decrease → turn total null (field-local)"
+        );
+        assert_eq!(
+            usage.cumulative_total_tokens,
+            Some(50),
+            "cumulative total from payload still passes through"
+        );
+    }
+
+    #[test]
+    fn cumulative_total_absent_on_current_turn_leaves_turn_total_null() {
+        // Goose-shaped payload: no accumulatedTotalTokens field at all.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-t4");
+        tracker.record("sess-t4", &payload_with_total(100, 20, Some(120)));
+        let _ = tracker.take();
+
+        // Second turn: goose omits the total field entirely.
+        tracker.begin_turn("sess-t4");
+        tracker.record("sess-t4", &payload_with_total(200, 50, None));
+        let usage = tracker.take().expect("pending");
+
+        assert!(usage.delta_reliable, "input/output delta unaffected");
+        assert_eq!(usage.turn_input_tokens, Some(100));
+        assert_eq!(usage.turn_output_tokens, Some(30));
+        assert!(
+            usage.turn_total_tokens.is_none(),
+            "absent field → null turn total"
+        );
+        assert!(
+            usage.cumulative_total_tokens.is_none(),
+            "absent cumulative total passes through as None"
+        );
+    }
+
+    #[test]
+    fn goose_shaped_payload_without_accumulated_total_deserializes_correctly() {
+        // goose payloads lack accumulatedTotalTokens; the field must default
+        // to None without a deserialization error (ignore-if-absent contract).
+        let json = r#"{
+            "sessionUpdate": "usage_update",
+            "accumulatedInputTokens": 1000,
+            "accumulatedOutputTokens": 200,
+            "accumulatedCost": 0.01
+        }"#;
+        let variant: GooseSessionUpdateVariant =
+            serde_json::from_str(json).expect("must deserialize without accumulatedTotalTokens");
+        let payload = match variant {
+            GooseSessionUpdateVariant::UsageUpdate(p) => p,
+            _ => panic!("expected UsageUpdate"),
+        };
+        assert!(
+            payload.accumulated_total_tokens.is_none(),
+            "absent accumulatedTotalTokens must default to None"
+        );
+
+        // And it must flow through the tracker correctly.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-goose-nototal");
+        tracker.record("sess-goose-nototal", &payload);
+        let usage = tracker.take().expect("pending");
+        assert!(
+            usage.cumulative_total_tokens.is_none(),
+            "goose-shaped payload must produce None cumulative_total_tokens"
+        );
+    }
+
+    #[test]
+    fn cumulative_total_absent_on_baseline_leaves_turn_total_null_on_second_turn() {
+        // Baseline was set without a total (e.g. first goose turn); second
+        // turn reports a total. No baseline to diff against → turn total None.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-t5");
+        tracker.record("sess-t5", &payload_with_total(100, 20, None)); // no total
+        let _ = tracker.take();
+
+        tracker.begin_turn("sess-t5");
+        tracker.record("sess-t5", &payload_with_total(200, 50, Some(250)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(usage.delta_reliable, "input/output delta unaffected");
+        assert!(
+            usage.turn_total_tokens.is_none(),
+            "absent baseline total → turn total null even when current has a total"
+        );
+        assert_eq!(usage.cumulative_total_tokens, Some(250));
+    }
+
+    // ── cache-read token threading ──────────────────────────────────────────
+
+    fn payload_with_cache(
+        input: u64,
+        output: u64,
+        cached_input: Option<u64>,
+    ) -> UsageUpdatePayload {
+        UsageUpdatePayload {
+            used: input + output,
+            context_limit: 200_000,
+            accumulated_input_tokens: input,
+            accumulated_output_tokens: output,
+            accumulated_cached_input_tokens: cached_input,
+            accumulated_cost: None,
+            accumulated_total_tokens: None,
+            model: None,
+        }
+    }
+
+    #[test]
+    fn cache_read_first_turn_produces_none_turn_delta_and_passes_cumulative_through() {
+        // First turn has no baseline → turn cache delta must be None, but
+        // cumulative_cache_read_tokens must carry the reported value through.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c1");
+        tracker.record("sess-c1", &payload_with_cache(1000, 200, Some(500)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(
+            usage.turn_cache_read_tokens.is_none(),
+            "first turn: no baseline → cache delta must be None"
+        );
+        assert_eq!(
+            usage.cumulative_cache_read_tokens,
+            Some(500),
+            "cumulative cache read passes through on first turn"
+        );
+        assert!(!usage.delta_reliable, "first turn is unreliable");
+    }
+
+    #[test]
+    fn cache_read_second_turn_delta_computed_correctly() {
+        // Second turn: cumulative cached 500 → 1200, delta = 700.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c2");
+        tracker.record("sess-c2", &payload_with_cache(1000, 200, Some(500)));
+        let _ = tracker.take();
+
+        tracker.begin_turn("sess-c2");
+        tracker.record("sess-c2", &payload_with_cache(2000, 350, Some(1200)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(usage.delta_reliable);
+        assert_eq!(
+            usage.turn_cache_read_tokens,
+            Some(700),
+            "cache delta = 1200 - 500 = 700"
+        );
+        assert_eq!(
+            usage.cumulative_cache_read_tokens,
+            Some(1200),
+            "cumulative cache passes through"
+        );
+    }
+
+    #[test]
+    fn cache_read_decrease_nulls_turn_cache_but_leaves_delta_reliable() {
+        // Cache counter decrease → cache delta None (field-local taint), but
+        // delta_reliable and input/output deltas are NOT affected.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c3");
+        tracker.record("sess-c3", &payload_with_cache(1000, 200, Some(800)));
+        let _ = tracker.take();
+
+        tracker.begin_turn("sess-c3");
+        // Cache counter decreased: 800 → 50.
+        tracker.record("sess-c3", &payload_with_cache(1500, 300, Some(50)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(
+            usage.delta_reliable,
+            "cache decrease must NOT flip delta_reliable — field-local"
+        );
+        assert_eq!(
+            usage.turn_input_tokens,
+            Some(500),
+            "input/output delta unaffected by cache decrease"
+        );
+        assert_eq!(usage.turn_output_tokens, Some(100));
+        assert!(
+            usage.turn_cache_read_tokens.is_none(),
+            "cache counter decrease → turn_cache_read_tokens None (field-local taint)"
+        );
+        assert_eq!(
+            usage.cumulative_cache_read_tokens,
+            Some(50),
+            "cumulative still passes through from payload even on decrease"
+        );
+    }
+
+    #[test]
+    fn cache_read_explicit_zero_payload_after_explicit_zero_baseline_produces_some_zero_delta() {
+        // When both baseline and current are Some(0), turn_cache_read_tokens must
+        // be Some(0) — confirmed zero, not absent.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c4");
+        tracker.record("sess-c4", &payload_with_cache(1000, 200, Some(0)));
+        let _ = tracker.take();
+
+        tracker.begin_turn("sess-c4");
+        tracker.record("sess-c4", &payload_with_cache(1500, 300, Some(0)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(usage.delta_reliable);
+        assert_eq!(
+            usage.turn_cache_read_tokens,
+            Some(0),
+            "explicit zero on both sides → Some(0), not None"
+        );
+        assert_eq!(usage.cumulative_cache_read_tokens, Some(0));
+    }
+
+    #[test]
+    fn cache_read_threads_through_setup_notification_baseline() {
+        // A setup notification (before begin_turn) with a nonzero cache count
+        // must update the committed baseline so the first real turn gets a
+        // correct delta from that starting point.
+        let mut tracker = UsageTracker::default();
+
+        // Setup notification: cumulative cache = 300.
+        tracker.record("sess-c5", &payload_with_cache(1000, 200, Some(300)));
+
+        tracker.begin_turn("sess-c5");
+        tracker.record("sess-c5", &payload_with_cache(1500, 350, Some(700)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(usage.delta_reliable, "baseline from setup: reliable");
+        assert_eq!(
+            usage.turn_cache_read_tokens,
+            Some(400),
+            "cache delta from setup baseline: 700 - 300 = 400"
+        );
+        assert_eq!(usage.cumulative_cache_read_tokens, Some(700));
+    }
+
+    #[test]
+    fn cache_read_omitted_field_produces_none_cumulative_and_no_turn_delta() {
+        // A harness that omits accumulatedCachedInputTokens (e.g. goose) must
+        // produce None cumulative_cache_read_tokens — not Some(0) — and the
+        // turn delta must also be None even on the second turn.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c6");
+        // payload() uses None for accumulated_cached_input_tokens.
+        tracker.record("sess-c6", &payload(1000, 200, None));
+        let t1 = tracker.take().expect("turn 1");
+
+        assert!(
+            t1.cumulative_cache_read_tokens.is_none(),
+            "goose-shaped payload: cumulative must be None, not Some(0)"
+        );
+        assert!(
+            t1.turn_cache_read_tokens.is_none(),
+            "first turn always has no turn delta"
+        );
+
+        tracker.begin_turn("sess-c6");
+        tracker.record("sess-c6", &payload(1500, 300, None));
+        let t2 = tracker.take().expect("turn 2");
+
+        assert!(
+            t2.cumulative_cache_read_tokens.is_none(),
+            "continued goose session: cumulative must remain None"
+        );
+        assert!(
+            t2.turn_cache_read_tokens.is_none(),
+            "absent field on both sides → no turn delta invented"
+        );
+        assert!(
+            t2.delta_reliable,
+            "input/output reliability unaffected by absent cache field"
+        );
+    }
+
+    #[test]
+    fn cache_read_baseline_absent_then_present_produces_no_delta() {
+        // If the first turn omits the cache field (baseline stored as None) and
+        // the second turn reports a value, no delta can be computed — we have no
+        // baseline to subtract from. The cumulative value should still pass through.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c7");
+        tracker.record("sess-c7", &payload(1000, 200, None)); // no cache field
+        let _ = tracker.take();
+
+        tracker.begin_turn("sess-c7");
+        tracker.record("sess-c7", &payload_with_cache(1500, 300, Some(400)));
+        let usage = tracker.take().expect("turn 2");
+
+        assert!(
+            usage.turn_cache_read_tokens.is_none(),
+            "absent baseline → no turn delta even when current has a value"
+        );
+        assert_eq!(
+            usage.cumulative_cache_read_tokens,
+            Some(400),
+            "cumulative from current payload passes through"
+        );
+        assert!(usage.delta_reliable, "input/output reliability unaffected");
+    }
+
+    #[test]
+    fn cache_read_baseline_present_then_absent_produces_no_delta() {
+        // If the first turn reports the cache field but the second omits it
+        // (harness switched), no delta should be produced and cumulative is None.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c8");
+        tracker.record("sess-c8", &payload_with_cache(1000, 200, Some(300)));
+        let _ = tracker.take();
+
+        tracker.begin_turn("sess-c8");
+        tracker.record("sess-c8", &payload(1500, 300, None)); // no cache field
+        let usage = tracker.take().expect("turn 2");
+
+        assert!(
+            usage.turn_cache_read_tokens.is_none(),
+            "absent current → no turn delta"
+        );
+        assert!(
+            usage.cumulative_cache_read_tokens.is_none(),
+            "absent field: cumulative must be None"
+        );
+        assert!(usage.delta_reliable, "input/output reliability unaffected");
+    }
+
+    #[test]
+    fn pool_omitted_cache_field_publishes_no_cache_read_tokens_in_kind44200() {
+        // End-to-end: a buzz-agent or goose payload that omits the cache field
+        // must NOT publish cacheReadTokens in the kind:44200 event — neither
+        // in turn nor cumulative counts.
+        //
+        // This is the core acceptance test for Thufir's finding: the old code
+        // would publish cacheReadTokens: 0 for every harness regardless of
+        // whether the field was reported.
+        use crate::pool::build_turn_metric_counts;
+
+        let usage = TurnUsage {
+            session_id: "sess-pool-none".into(),
+            turn_seq: 2,
+            delta_reliable: true,
+            turn_input_tokens: Some(400),
+            turn_output_tokens: Some(100),
+            turn_total_tokens: None,
+            turn_cost_usd: None,
+            turn_cache_read_tokens: None,
+            cumulative_input_tokens: 700,
+            cumulative_output_tokens: 200,
+            cumulative_total_tokens: None,
+            cumulative_cost_usd: None,
+            cumulative_cache_read_tokens: None, // harness did not report the field
+            model: None,
+        };
+
+        let (turn_counts, cumulative_counts) = build_turn_metric_counts(&usage);
+
+        let turn = turn_counts.expect("turn counts must be present (delta reliable)");
+        assert!(
+            turn.cache_read_tokens.is_none(),
+            "omitted cache field: turn cacheReadTokens must be absent from kind:44200"
+        );
+
+        let cumulative = cumulative_counts.expect("cumulative counts always present");
+        assert!(
+            cumulative.cache_read_tokens.is_none(),
+            "omitted cache field: cumulative cacheReadTokens must be absent from kind:44200"
+        );
+    }
+
+    #[test]
+    fn pool_reported_cache_field_publishes_nonzero_cache_read_tokens_in_kind44200() {
+        // End-to-end: a buzz-agent payload with a nonzero cache count must
+        // publish cacheReadTokens in both turn and cumulative counts.
+        use crate::pool::build_turn_metric_counts;
+
+        let usage = TurnUsage {
+            session_id: "sess-pool-some".into(),
+            turn_seq: 2,
+            delta_reliable: true,
+            turn_input_tokens: Some(400),
+            turn_output_tokens: Some(100),
+            turn_total_tokens: None,
+            turn_cost_usd: None,
+            turn_cache_read_tokens: Some(300),
+            cumulative_input_tokens: 700,
+            cumulative_output_tokens: 200,
+            cumulative_total_tokens: None,
+            cumulative_cost_usd: None,
+            cumulative_cache_read_tokens: Some(600),
+            model: None,
+        };
+
+        let (turn_counts, cumulative_counts) = build_turn_metric_counts(&usage);
+
+        let turn = turn_counts.expect("turn counts present");
+        assert_eq!(
+            turn.cache_read_tokens,
+            Some(300),
+            "nonzero turn cache: must appear in kind:44200 turn counts"
+        );
+
+        let cumulative = cumulative_counts.expect("cumulative counts present");
+        assert_eq!(
+            cumulative.cache_read_tokens,
+            Some(600),
+            "nonzero cumulative cache: must appear in kind:44200 cumulative counts"
+        );
+    }
 }
diff --git a/crates/buzz-agent/README.md b/crates/buzz-agent/README.md
index a2504db451..5d942777d5 100644
--- a/crates/buzz-agent/README.md
+++ b/crates/buzz-agent/README.md
@@ -21,9 +21,9 @@
                                             HTTPS
                                               │
                                               ▼
-                                  Anthropic Messages API
-                                   or any OpenAI-compat
-                                  (vLLM, llama.cpp, OpenRouter,
+                                  Anthropic Messages API,
+                                   OpenRouter, or any OpenAI-compat
+                                  (vLLM, llama.cpp, Databricks,
                                    Block Gateway, Ollama, …)
 ```
 
@@ -50,6 +50,12 @@ OPENAI_COMPAT_MODEL=gpt-5 \
 OPENAI_COMPAT_BASE_URL=https://api.openai.com/v1 \
   ./target/release/buzz-agent
 
+# Or OpenRouter
+BUZZ_AGENT_PROVIDER=openrouter \
+OPENROUTER_API_KEY=sk-or-v1-... \
+OPENROUTER_MODEL=anthropic/claude-sonnet-4.5 \
+  ./target/release/buzz-agent
+
 # Or Databricks model serving via OAuth 2.0 PKCE
 BUZZ_AGENT_PROVIDER=databricks \
 DATABRICKS_HOST=https://dbc-...cloud.databricks.com \
@@ -129,15 +135,18 @@ Everything is environment variables. No flags, no config files. (We are a subpro
 
 | Variable | Default | Notes |
 |---|---|---|
-| `BUZZ_AGENT_PROVIDER` | — | Required. `anthropic`, `openai`, `databricks`, or `databricks_v2`. No implicit fallback — the agent errors at startup when this is unset. |
+| `BUZZ_AGENT_PROVIDER` | — | Required. `anthropic`, `openai`, `openrouter`, `databricks`, or `databricks_v2`. No implicit fallback — the agent errors at startup when this is unset. |
 | `ANTHROPIC_API_KEY` | — | Required when provider=anthropic. |
 | `ANTHROPIC_MODEL` | — | Required when provider=anthropic. |
 | `ANTHROPIC_BASE_URL` | `https://api.anthropic.com` | |
 | `ANTHROPIC_API_VERSION` | `2023-06-01` | |
 | `OPENAI_COMPAT_API_KEY` | — | Required when provider=openai. |
 | `OPENAI_COMPAT_MODEL` | — | Required when provider=openai. |
-| `OPENAI_COMPAT_BASE_URL` | `https://api.openai.com/v1` | Point at vLLM, llama.cpp, OpenRouter, Ollama, etc. |
+| `OPENAI_COMPAT_BASE_URL` | `https://api.openai.com/v1` | Point at vLLM, llama.cpp, Ollama, etc. |
 | `OPENAI_COMPAT_API` | `auto` | `auto` \| `chat` \| `responses`. `auto` picks Responses for `*.openai.com`, Chat Completions everywhere else. |
+| `OPENROUTER_API_KEY` | — | Required when provider=openrouter. |
+| `OPENROUTER_MODEL` | — | Required when provider=openrouter. Use OpenRouter's `vendor/model` id, e.g. `anthropic/claude-sonnet-4.5`. |
+| `OPENROUTER_BASE_URL` | `https://openrouter.ai/api/v1` | |
 | `DATABRICKS_HOST` | — | Required when provider=databricks or provider=databricks_v2. |
 | `DATABRICKS_MODEL` | — | Required when provider=databricks or provider=databricks_v2. |
 | `DATABRICKS_TOKEN` | — | Optional static bearer escape hatch. If unset, Databricks uses browser OAuth + refresh cache. |
@@ -154,6 +163,67 @@ Everything is environment variables. No flags, no config files. (We are a subpro
 | `BUZZ_AGENT_MAX_LINE_BYTES` | `4194304` | 4 MiB. Hard cap on inbound JSON-RPC frames. |
 | `BUZZ_AGENT_MAX_HISTORY_BYTES` | `1048576` | 1 MiB. Old turns are evicted past this. |
 | `BUZZ_AGENT_MAX_TOOL_RESULT_TEXT_BYTES` | `51200` | 50 KiB. Per-result cap on tool-output text; oversize is middle-elided (head + tail kept) with an inline marker. Images are exempt. |
+| `BUZZ_AGENT_REQUIRE_REPLY` | `0` (`1` on mesh) | `1` enables the [reply guard](#reply-guard) — remind the model to publish when a turn is about to end with nothing posted to Buzz. Desktop defaults it to `1` for Buzz shared-compute agents. |
+
+
+## Reply Guard
+
+Off by default, except on Buzz shared-compute (mesh) agents, where Buzz Desktop
+sets `BUZZ_AGENT_REQUIRE_REPLY=1` automatically. With it enabled, a turn that is
+about to end without any recognized attempt to post to Buzz gets a reminder that
+its assistant text is invisible to humans, and is rerolled.
+
+This exists because a Buzz agent's reasoning and tool output are not shown to
+anyone. A turn that does real work and never posts is a silent failure — the
+requester waits on a result that was produced and thrown away.
+
+Mesh agents get it by default because they run on small local models, which are
+the ones most likely to do the work and then end the turn without publishing it.
+Setting `BUZZ_AGENT_REQUIRE_REPLY=0` on the agent, persona, or global env opts a
+mesh agent back out; the default never overrides an explicit value.
+
+**Advisory, never a trap.** At most two reminders, then the turn ends whether or
+not anything was published. The guard catches accidental omission; it does not
+compel speech. The reminder text explicitly licenses silence, because the
+built-in system prompt says publishing is optional and silence is often the
+correct outcome.
+
+**Recognition contract.** A turn counts as having replied when it issues a call
+that:
+
+- resolves to a registered, non-hook tool (a hallucinated tool name is rejected
+  at preflight and never runs, so it must not disarm the guard),
+- whose qualified name ends in `__shell` — i.e. the bare tool name is exactly
+  `shell`, which is `buzz-dev-mcp`'s shell tool and any other server's, and
+- whose `command` argument contains `messages send` or `reactions add`.
+
+`messages send` also covers `messages send-diff`. Reactions count because the
+built-in prompt directs agents to react rather than post a bare
+acknowledgement, so nagging an agent that reacted would punish documented
+behavior.
+
+Detection is checked **after** the per-turn tool-call cap
+(`MAX_TOOL_CALLS_PER_TURN`) is applied: a publish-shaped call that was discarded
+never ran.
+
+**It recognizes an attempt, not a successful publish.** Only the command text is
+inspected, never the exit status. A send that fails still satisfies the guard —
+which is fine, since a failed send already returns a non-zero exit and error
+JSON to the model, louder feedback than a reminder.
+
+**Known limits**, both deliberate. A command assembled at runtime (`$CMD`) or
+buried in a wrapper script is missed, so that turn is reminded despite having
+posted. Text that merely quotes a send (`echo "buzz messages send"`) matches, so
+that turn is not reminded. Missing a real post is the expensive direction, and
+substring matching is the forgiving one there. Neither edge is pinned by a test;
+the matcher is free to improve.
+
+**Budget.** Reminders ride the existing `_Stop` gate and share
+`BUZZ_AGENT_STOP_MAX_REJECTIONS` — the outer cap on every end-turn objection.
+At the default 3 both reminders fit; at 1 only one does; at 0 the guard is off
+along with the hooks. A round carrying both a `_Stop` hook objection and a
+reminder costs one rejection and delivers both texts. This is not a new
+lifecycle hook — see [MCP_DRIVEN_HOOKS.md](../../docs/MCP_DRIVEN_HOOKS.md).
 
 
 ## Providers
@@ -167,17 +237,24 @@ Everything is environment variables. No flags, no config files. (We are a subpro
 | vLLM | `openai` | `POST {base}/chat/completions` | any tool-calling model |
 | llama.cpp | `openai` | `POST {base}/chat/completions` | any tool-calling GGUF |
 | Ollama | `openai` | `POST {base}/chat/completions` | llama3.1, qwen2.5-coder |
-| OpenRouter | `openai` | `POST {base}/chat/completions` | anything they route |
 | Block Gateway | `openai` | `POST {base}/chat/completions` | gpt-5, claude |
+| OpenRouter | `openrouter` | `POST {base}/chat/completions` | anything they route (extended-thinking replay, provider-agnostic tool calling) |
 | Databricks | `databricks` | `POST {host}/serving-endpoints/{model}/invocations` | goose-claude-4-6-sonnet |
 | Databricks AI Gateway v2 | `databricks_v2` | `POST {host}/ai-gateway/{provider}/v1/...` | databricks-gpt-5-5, databricks-claude-opus-4-7 |
 
-If `BUZZ_AGENT_PROVIDER=anthropic` is selected without `ANTHROPIC_API_KEY`, or `BUZZ_AGENT_PROVIDER=openai` is selected without `OPENAI_COMPAT_API_KEY`, the agent returns an error — there is no implicit fallback to another provider.
+If `BUZZ_AGENT_PROVIDER=anthropic` is selected without `ANTHROPIC_API_KEY`, `BUZZ_AGENT_PROVIDER=openai` is selected without `OPENAI_COMPAT_API_KEY`, or `BUZZ_AGENT_PROVIDER=openrouter` is selected without `OPENROUTER_API_KEY`, the agent returns an error — there is no implicit fallback to another provider.
 
 `provider=openai` speaks two HTTP dialects: the [Responses API](https://platform.openai.com/docs/api-reference/responses) (`/v1/responses`, required for GPT-5 / o-series tool-calling on OpenAI's own service) and the [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) (`/chat/completions`, the broadly-supported OpenAI-compatible wire format).
 
 By default (`OPENAI_COMPAT_API=auto`) the agent picks **Responses** when `OPENAI_COMPAT_BASE_URL` points at an `*.openai.com` host and **Chat Completions** everywhere else. Pin the choice explicitly with `OPENAI_COMPAT_API=chat` or `OPENAI_COMPAT_API=responses` for providers that diverge from the default (e.g. a Responses-compatible self-hosted gateway).
 
+`provider=openrouter` is first-class, not routed through `provider=openai`: it speaks OpenAI's Chat Completions wire format but with OpenRouter-specific extensions layered on top —
+
+- `reasoning.effort` is set on the request when reasoning effort is configured. The request deliberately carries no `provider.require_parameters` filter: that filter routes only to endpoints advertising every parameter in the body, and 83 of 274 tools-capable OpenRouter models do not advertise `reasoning`, so it turns an effort setting into a hard 404 on a valid model id. A model that cannot reason answers without reasoning instead.
+- The response's `reasoning_details` array (opaque extended-thinking payload) is captured and replayed byte-for-byte on the next turn's assistant message, so multi-turn tool use keeps the model's chain-of-thought.
+- `anthropic/*` models get Anthropic-style `cache_control` breakpoints injected on the system message and the last two user messages.
+- Retryable statuses (429 and typed `provider_overloaded` 503) honor the documented `Retry-After` header (clamped to a small ceiling — see `RETRY_AFTER_CAP_SECS` in `llm.rs` — since the sleep happens outside `BUZZ_AGENT_LLM_TIMEOUT_SECS`); 502 and untyped 503 retry with jittered backoff instead. `401` is treated as an expired/invalid key and refreshed once, while `402` (no credits) and `403` (guardrail/moderation/permission) fail immediately without retry.
+
 `Provider` is a Rust `enum` with one `match` in `Llm::complete`. There is no trait, no `Box<dyn>`, no async-trait. Adding a provider is a `match` arm and one `body`/`parse` pair in `llm.rs`.
 
 ## MCP Servers
diff --git a/crates/buzz-agent/src/agent.rs b/crates/buzz-agent/src/agent.rs
index 730e87b2e8..8e14fee195 100644
--- a/crates/buzz-agent/src/agent.rs
+++ b/crates/buzz-agent/src/agent.rs
@@ -14,13 +14,87 @@ use crate::mcp::ResultBudget;
 
 use crate::types::{
     AgentError, ContentBlock, HistoryItem, ProviderStop, StopReason, ToolCall, ToolResult,
-    ToolResultContent,
+    ToolResultContent, TurnTotalState,
 };
 use crate::wire::{self, WireSender};
 
 const ERROR_REFLECTION_SUFFIX: &str =
     "\n\n[Reflect] Before retrying, identify the cause and change your approach.";
 
+/// Maximum reply reminders emitted per prompt when `require_reply` is on.
+///
+/// After this many, the turn is allowed to end whether or not anything was
+/// published: the guard exists to catch accidental omission, not to compel
+/// speech. The shared `stop_max_rejections` budget can cut this lower — see
+/// [`Config::require_reply`](crate::config::Config::require_reply).
+const MAX_REPLY_NAGS: u32 = 2;
+
+/// Server label on the synthetic reply-guard objection.
+///
+/// Not a real MCP server. It rides the same tool-result path as `_Stop` hook
+/// output, so the model sees `{hook, server, text}` attribution naming the
+/// in-process guard rather than an MCP server that could be impersonated.
+const REPLY_GUARD_SERVER: &str = "buzz-agent";
+
+/// Reminder text emitted when a turn is about to end with nothing published.
+///
+/// Explicitly licenses silence. The base prompt tells agents that publishing is
+/// optional and "silence is usually correct"; a reminder that argued otherwise
+/// would fight that instruction and make agents chattier.
+const REPLY_GUARD_NAG: &str = "You are about to end this turn without calling `buzz messages send`. \
+Your assistant text and reasoning are never shown to anyone — if you did work, found an answer, \
+or hit a blocker that someone is waiting on, it exists only if you publish it. \
+If you already posted, or if silence is genuinely correct for this turn, ignore this and end your turn.";
+
+/// Whether `call` is a recognized attempt to publish a reply to Buzz.
+///
+/// Recognizes an *attempt*, not a successful publish: the command text is
+/// inspected, never the exit status. That is deliberate — a send that fails
+/// already returns a non-zero exit and error JSON to the model, which is louder
+/// feedback than the reminder this gates.
+///
+/// `has` + `!is_hook` are the same checks the dispatcher uses to accept a call
+/// (see `execute_calls`), so a hallucinated `fake__shell` — rejected at preflight
+/// and never executed — cannot disarm the guard. They must stay *before*
+/// [`is_reply_shaped`]: together with them, and only with them, the `__shell`
+/// suffix is exactly equivalent to "the bare tool name is `shell`".
+fn is_buzz_reply_call(call: &ToolCall, mcp: &McpRegistry) -> bool {
+    mcp.has(&call.name) && !mcp.is_hook(&call.name) && is_reply_shaped(&call.name, &call.arguments)
+}
+
+/// Whether a tool name and arguments have the shape of a Buzz publish command.
+///
+/// Split from [`is_buzz_reply_call`] only so the matcher is testable without a
+/// live [`McpRegistry`]; callers must apply the registry checks first.
+///
+/// On the name: `ends_with("__shell")` is exact rather than approximate *given*
+/// those checks. Registration rejects `__` in both server names and bare tool
+/// names, and qualified names are `{server}__{bare}`, so a trailing `__shell` can
+/// only straddle the separator if the bare name starts with `_` — which `is_hook`
+/// already excludes. Dropping the separator would not be exact: `powershell` and
+/// `noshell` both end in `shell`.
+///
+/// On the command: a deliberately coarse substring test, scoped to the structured
+/// `command` field so unrelated metadata — a `description` that quotes a send —
+/// cannot suppress the guard, and a non-string `command` is rejected rather than
+/// coerced. Known limits, both accepted: a command assembled at runtime (`$CMD`)
+/// or hidden in a wrapper script is missed, and text that merely quotes a send
+/// (`echo "buzz messages send"`) matches. Missing a real post is the expensive
+/// direction, and substring matching is the more forgiving one there.
+fn is_reply_shaped(name: &str, arguments: &serde_json::Value) -> bool {
+    name.ends_with("__shell")
+        && arguments
+            .get("command")
+            .and_then(|v| v.as_str())
+            .is_some_and(|cmd| {
+                // `messages send` also covers `messages send-diff`. `reactions
+                // add` counts because the base prompt directs agents to react
+                // rather than post a bare acknowledgement, so nagging an agent
+                // that reacted would punish documented-correct behavior.
+                cmd.contains("messages send") || cmd.contains("reactions add")
+            })
+}
+
 pub struct RunCtx<'a> {
     pub cfg: &'a Config,
     /// Effective model for this session. Usually equals `cfg.model`; overridden
@@ -60,6 +134,22 @@ pub struct RunCtx<'a> {
     /// Accumulated output tokens across all LLM rounds in this turn, for
     /// NIP-AM metric publishing. Reset to `None` at turn start in `run()`.
     pub turn_output_tokens: &'a mut Option<u64>,
+    /// The cache-served subset of `turn_input_tokens`, accumulated across all
+    /// LLM rounds in this turn. Reset to `None` at turn start in `run()`.
+    /// Consumers price this slice at the provider's cached rate; without it
+    /// every round of a growing conversation is billed at full price.
+    pub turn_cached_input_tokens: &'a mut Option<u64>,
+    /// Tri-state total-token accumulator for this turn.
+    ///
+    /// - `Unseen`: no usage-bearing response observed yet this turn (initial state).
+    /// - `Exact(n)`: every usage-bearing response so far reported a genuine
+    ///   provider total; `n` is their sum.
+    /// - `Unknown`: at least one usage-bearing response lacked a provider total;
+    ///   this turn can never produce a reliable total.
+    ///
+    /// Reset to `Unseen` at turn start in `run()`. Callers must not derive a
+    /// total by summing input+output — that is the UI display approximation only.
+    pub turn_total_state: &'a mut TurnTotalState,
 }
 
 impl RunCtx<'_> {
@@ -78,12 +168,22 @@ impl RunCtx<'_> {
         // Reset per-turn token accumulators for this prompt.
         *self.turn_input_tokens = None;
         *self.turn_output_tokens = None;
+        *self.turn_cached_input_tokens = None;
+        *self.turn_total_state = TurnTotalState::Unseen;
 
         let mut round = 0u32;
         // Per-prompt `_Stop` objection count. Bounded per prompt (not per
         // session) so a stubborn exchange can't permanently disable the stop
         // guard for a long-lived session; `max_rounds` still caps the loop.
         let mut stop_rejections = 0u32;
+        // Reply-guard state for this prompt. `prompt()` *is* the turn, so
+        // locals here are per-turn by construction — same shape as
+        // `stop_rejections` above.
+        //
+        // Named for what it proves: a *recognized attempt* to publish, not a
+        // successful publish. See `is_buzz_reply_call`.
+        let mut buzz_reply_call_seen = false;
+        let mut reply_nags = 0u32;
         loop {
             if self.cfg.max_rounds > 0 && round >= self.cfg.max_rounds {
                 return Ok(StopReason::MaxTurnRequests);
@@ -175,6 +275,31 @@ impl RunCtx<'_> {
                 *self.turn_output_tokens =
                     Some(self.turn_output_tokens.unwrap_or(0).saturating_add(out));
             }
+            // Accumulate the cache-served subset of this turn's input. Tracked
+            // separately from `turn_input_tokens` rather than subtracted from
+            // it: the input total must stay inclusive for the handoff gate,
+            // which cares how much context was sent, not what it cost.
+            if let Some(cached) = response.cached_input_tokens {
+                *self.turn_cached_input_tokens = Some(
+                    self.turn_cached_input_tokens
+                        .unwrap_or(0)
+                        .saturating_add(cached),
+                );
+            }
+            // Fold the provider-reported total into the turn tri-state, but only
+            // when this response was usage-bearing (had input or output tokens).
+            // A response with no usage at all is not evidence of a missing total
+            // and must not poison the accumulator.
+            //
+            // Shape assumption: documented OpenAI-compatible responses that carry
+            // `total_tokens` always co-report at least one of `prompt_tokens` /
+            // `completion_tokens`. A response that supplies only `total_tokens`
+            // with neither category is therefore not a supported shape and would
+            // be silently ignored here. If that shape is ever encountered, extend
+            // this gate rather than representing absent categories as zero.
+            if response.input_tokens.is_some() || response.output_tokens.is_some() {
+                *self.turn_total_state = self.turn_total_state.fold(response.total_tokens);
+            }
 
             if !response.reasoning.is_empty() {
                 wire::send(
@@ -213,6 +338,7 @@ impl RunCtx<'_> {
                 self.history.push(HistoryItem::Assistant {
                     text: response.text,
                     tool_calls: Vec::new(),
+                    reasoning_details: response.reasoning_details.clone(),
                 });
                 let stop = map_stop(response.stop);
                 // Only gate genuine end_turn — don't override max_tokens/refusal.
@@ -220,7 +346,7 @@ impl RunCtx<'_> {
                     if stop_rejections >= self.cfg.stop_max_rejections {
                         return Ok(stop);
                     }
-                    let objections = self
+                    let mut objections = self
                         .mcp
                         .call_hooks(
                             "_Stop",
@@ -229,6 +355,17 @@ impl RunCtx<'_> {
                             &self.cfg.hook_servers,
                         )
                         .await;
+                    // Reply guard shares this gate and this budget, so a round
+                    // carrying both a hook objection and a reply reminder costs
+                    // one rejection and delivers both texts.
+                    if self.cfg.require_reply
+                        && !buzz_reply_call_seen
+                        && reply_nags < MAX_REPLY_NAGS
+                    {
+                        reply_nags += 1;
+                        objections
+                            .push((REPLY_GUARD_SERVER.to_string(), REPLY_GUARD_NAG.to_string()));
+                    }
                     if !objections.is_empty() {
                         stop_rejections = stop_rejections.saturating_add(1);
                         push_hook_outputs_as_tool_results(self.history, "_Stop", &objections);
@@ -246,9 +383,15 @@ impl RunCtx<'_> {
                 );
                 calls.truncate(MAX_TOOL_CALLS_PER_TURN);
             }
+            // Deliberately after truncation: a publish-shaped call that was
+            // discarded never runs, so it must not suppress the reminder.
+            if self.cfg.require_reply && !buzz_reply_call_seen {
+                buzz_reply_call_seen = calls.iter().any(|c| is_buzz_reply_call(c, self.mcp));
+            }
             self.history.push(HistoryItem::Assistant {
                 text: response.text,
                 tool_calls: calls.clone(),
+                reasoning_details: response.reasoning_details,
             });
 
             if let Some(stop) = self.execute_calls(&calls).await {
@@ -679,7 +822,11 @@ pub(crate) fn push_hook_outputs_as_tool_results(
                 provider_id: provider_id.clone(),
                 name: tool_name,
                 arguments: serde_json::json!({}),
+                // Synthesised locally, so there is no provider wire form to
+                // preserve.
+                provider_extra: Default::default(),
             }],
+            reasoning_details: None,
         });
         history.push(HistoryItem::ToolResult(ToolResult {
             provider_id,
@@ -744,3 +891,158 @@ fn map_stop(p: ProviderStop) -> StopReason {
         ProviderStop::Refusal => StopReason::Refusal,
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    /// The shapes the guard must recognize as a publish attempt. Callers apply
+    /// the registry checks first; these cover the name suffix and command text.
+    #[test]
+    fn reply_shape_matches_documented_send_forms() {
+        for cmd in [
+            "buzz messages send --channel X --content Y",
+            "buzz --relay wss://r messages send --channel X --content Y",
+            "/abs/path/buzz messages send",
+            "printf 'hi' | buzz messages send --content -",
+            "buzz messages send-diff --diff -",
+            "buzz reactions add --event E --emoji +",
+            // Assembled through another shell: rev 3's tokenizer missed this.
+            r#"sh -c "buzz messages send --channel X""#,
+        ] {
+            assert!(
+                is_reply_shaped("dev__shell", &json!({ "command": cmd })),
+                "expected {cmd:?} to count as a publish attempt"
+            );
+        }
+    }
+
+    /// Commands that do real work but do not reply in the originating
+    /// conversation must still be nagged.
+    #[test]
+    fn reply_shape_rejects_non_reply_commands() {
+        for cmd in [
+            "buzz messages get --channel X",
+            "buzz channels list",
+            "buzz reactions remove --event E",
+            "buzz pr open --title T",
+            "buzz social publish --content hi",
+            "buzz notes set --name n",
+            "cargo test -p buzz-agent",
+        ] {
+            assert!(
+                !is_reply_shaped("dev__shell", &json!({ "command": cmd })),
+                "expected {cmd:?} not to count as a publish attempt"
+            );
+        }
+    }
+
+    /// The `__` separator is load-bearing: `ends_with("shell")` alone would
+    /// accept any registered tool whose name merely ends in those letters, and
+    /// `has()` proves registration, not the bare name.
+    #[test]
+    fn reply_shape_requires_the_qname_separator() {
+        let args = json!({ "command": "buzz messages send --channel X" });
+        for name in [
+            "dev__powershell",
+            "dev__noshell",
+            "shell",
+            "dev__send_message",
+        ] {
+            assert!(
+                !is_reply_shaped(name, &args),
+                "{name} must not satisfy the shell-tool check"
+            );
+        }
+        assert!(is_reply_shaped("dev__shell", &args));
+        assert!(is_reply_shaped("buzz-dev-mcp__shell", &args));
+    }
+
+    /// Only the field that carries the executable command counts. Searching
+    /// serialized arguments instead would let arbitrary metadata disarm the
+    /// guard, turning a description into an attempted send.
+    #[test]
+    fn reply_shape_reads_only_the_command_field() {
+        assert!(!is_reply_shaped(
+            "dev__shell",
+            &json!({ "description": "buzz messages send --channel X" })
+        ));
+        assert!(!is_reply_shaped(
+            "dev__shell",
+            &json!({ "workdir": "buzz messages send" })
+        ));
+        // Malformed `command` is rejected, not coerced — and must not panic.
+        assert!(!is_reply_shaped("dev__shell", &json!({ "command": 42 })));
+        assert!(!is_reply_shaped("dev__shell", &json!({ "command": null })));
+        assert!(!is_reply_shaped("dev__shell", &json!({})));
+        assert!(!is_reply_shaped("dev__shell", &json!("not an object")));
+    }
+
+    /// A9 regression: `reasoning_details` contributes real bytes to
+    /// `estimated_bytes` (see `types.rs::HistoryItem::size_with`), so a
+    /// history item carrying a large opaque reasoning array must actually
+    /// drive `truncate_history` eviction — not be silently invisible to the
+    /// sizing gate that decides what survives a turn.
+    #[test]
+    fn truncate_history_evicts_oldest_turn_with_reasoning_details() {
+        let big_reasoning = json!([{ "type": "reasoning.text", "text": "x".repeat(400) }]);
+        let mut history = vec![
+            HistoryItem::User("first question".into()),
+            HistoryItem::Assistant {
+                text: "first answer".into(),
+                tool_calls: vec![],
+                reasoning_details: Some(big_reasoning),
+            },
+            HistoryItem::User("second question".into()),
+            HistoryItem::Assistant {
+                text: "second answer".into(),
+                tool_calls: vec![],
+                reasoning_details: None,
+            },
+        ];
+
+        let total_before: usize = history.iter().map(HistoryItem::estimated_bytes).sum();
+        // Budget below the total but above the second (smaller) turn alone,
+        // so only the oldest user+assistant pair — the one carrying
+        // reasoning_details — must be dropped.
+        let max_bytes = total_before - 100;
+        assert!(
+            max_bytes > 0,
+            "test fixture must leave room to evict only one turn"
+        );
+
+        truncate_history(&mut history, max_bytes);
+
+        assert_eq!(
+            history.len(),
+            2,
+            "the oldest user+assistant turn (with reasoning_details) must be evicted"
+        );
+        assert!(matches!(&history[0], HistoryItem::User(s) if s == "second question"));
+        assert!(
+            matches!(&history[1], HistoryItem::Assistant { text, .. } if text == "second answer")
+        );
+        let total_after: usize = history.iter().map(HistoryItem::estimated_bytes).sum();
+        assert!(total_after <= max_bytes);
+    }
+
+    #[test]
+    fn truncate_history_noop_when_under_budget() {
+        let mut history = vec![
+            HistoryItem::User("hi".into()),
+            HistoryItem::Assistant {
+                text: "hello".into(),
+                tool_calls: vec![],
+                reasoning_details: None,
+            },
+        ];
+        let original_len = history.len();
+        truncate_history(&mut history, 1_000_000);
+        assert_eq!(
+            history.len(),
+            original_len,
+            "under budget must not evict anything"
+        );
+    }
+}
diff --git a/crates/buzz-agent/src/config.rs b/crates/buzz-agent/src/config.rs
index 864fa7d237..afbda5379d 100644
--- a/crates/buzz-agent/src/config.rs
+++ b/crates/buzz-agent/src/config.rs
@@ -671,6 +671,8 @@ pub enum Provider {
     /// Databricks AI Gateway v2. Routes by model family through the gateway's
     /// OpenAI Responses, Anthropic Messages, or MLflow Chat Completions paths.
     DatabricksV2,
+    /// OpenRouter multi-provider gateway. Routes to `{base_url}/chat/completions` with bearer auth. Wire format is OpenAI-chat-compatible.
+    OpenRouter,
 }
 
 /// Which OpenAI-family HTTP API to call. Set via `OPENAI_COMPAT_API`
@@ -718,6 +720,16 @@ pub struct Config {
     /// Maximum `_Stop` rejections per prompt. Default 3. Set to 0 to
     /// disable `_Stop` hooks entirely (agent always honors end_turn).
     pub stop_max_rejections: u32,
+    /// Remind the model to publish when a turn is about to end without any
+    /// recognized attempt to post to Buzz. Default off; opt in per agent with
+    /// `BUZZ_AGENT_REQUIRE_REPLY=1`.
+    ///
+    /// Advisory only: at most `MAX_REPLY_NAGS` reminders (see `agent.rs`),
+    /// then the turn ends regardless. Bounded by the same
+    /// `stop_max_rejections` budget as `_Stop` hooks, which is the outer cap on
+    /// all end-turn objections — at the default 3 both reminders fit; at 1 only
+    /// one does; at 0 the guard is off with the hooks.
+    pub require_reply: bool,
     /// Hook server allowlist. See [`HookServers`] for variant semantics.
     /// Default (env unset/empty) is `None` — hooks are off unless the
     /// operator explicitly opts in.
@@ -738,6 +750,14 @@ pub struct Config {
     /// Thinking/reasoning effort level. `None` = use provider default (no
     /// thinking config sent). Set via `BUZZ_AGENT_THINKING_EFFORT`.
     pub thinking_effort: Option<ThinkingEffort>,
+    /// Emit Anthropic `cache_control` breakpoints on the stable prefix
+    /// (tools + system prompt) and the rolling conversation tail. Default on;
+    /// disable with `BUZZ_AGENT_PROMPT_CACHING=0`. Consulted on every route that
+    /// speaks the Anthropic caching dialect: first-party Anthropic, the
+    /// DatabricksV2 Claude route, and OpenRouter's `anthropic/*` models. The
+    /// Databricks gateway does not auto-cache, so without this the surfaced
+    /// `cache_read_input_tokens` is structurally always 0.
+    pub prompt_caching: bool,
 }
 
 impl Config {
@@ -748,6 +768,7 @@ impl Config {
             env("BUZZ_AGENT_PROVIDER").as_deref(),
             env("ANTHROPIC_API_KEY").as_deref(),
             env("OPENAI_COMPAT_API_KEY").as_deref(),
+            env("OPENROUTER_API_KEY").as_deref(),
         )?;
 
         // Universal model override — takes priority over provider-specific model
@@ -790,6 +811,16 @@ impl Config {
                 databricks_host.ok_or_else(|| "config: DATABRICKS_HOST required".to_string())?,
                 OpenAiApi::Chat, // only read by OpenAI/legacy Databricks dispatch
             ),
+            Provider::OpenRouter => (
+                req("OPENROUTER_API_KEY")?,
+                resolve_model(
+                    buzz_agent_model.as_deref(),
+                    env("OPENROUTER_MODEL").as_deref(),
+                )
+                .ok_or_else(|| "config: OPENROUTER_MODEL required".to_string())?,
+                env_or("OPENROUTER_BASE_URL", "https://openrouter.ai/api/v1"),
+                OpenAiApi::Chat, // OpenRouter uses Chat Completions only
+            ),
         };
         let system_prompt = match (env("BUZZ_AGENT_SYSTEM_PROMPT"), env("BUZZ_AGENT_SYSTEM_PROMPT_FILE")) {
             (Some(_), Some(_)) => return Err(
@@ -830,9 +861,11 @@ impl Config {
             max_parallel_tools: parse_env("BUZZ_AGENT_MAX_PARALLEL_TOOLS", 8usize)?,
             hook_timeout: Duration::from_millis(parse_env("BUZZ_AGENT_HOOK_TIMEOUT_MS", 2500u64)?),
             stop_max_rejections: parse_env("BUZZ_AGENT_STOP_MAX_REJECTIONS", 3u32)?,
+            require_reply: parse_env("BUZZ_AGENT_REQUIRE_REPLY", 0u8)? != 0,
             hook_servers: parse_hook_servers_env("MCP_HOOK_SERVERS"),
             hints_enabled: parse_env("BUZZ_AGENT_NO_HINTS", 0u8)? == 0,
             thinking_effort: parse_thinking_effort(env("BUZZ_AGENT_THINKING_EFFORT").as_deref())?,
+            prompt_caching: parse_env("BUZZ_AGENT_PROMPT_CACHING", 1u8)? != 0,
         };
         cfg.validate()?;
         Ok(cfg)
@@ -871,9 +904,11 @@ impl Config {
             max_parallel_tools: 1,
             hook_timeout: Duration::from_secs(1),
             stop_max_rejections: 0,
+            require_reply: false,
             hook_servers: HookServers::None,
             hints_enabled: false,
             thinking_effort: None,
+            prompt_caching: false,
         }
     }
 
@@ -993,6 +1028,7 @@ fn resolve_provider(
     requested: Option<&str>,
     anthropic_key: Option<&str>,
     openai_key: Option<&str>,
+    openrouter_key: Option<&str>,
 ) -> Result<Provider, String> {
     match requested.map(str::trim).filter(|s| !s.is_empty()) {
         Some(raw) => {
@@ -1008,6 +1044,8 @@ fn resolve_provider(
                 ),
                 "databricks" => Ok(Provider::Databricks),
                 "databricks_v2" | "databricks-v2" => Ok(Provider::DatabricksV2),
+                "openrouter" if present_nonempty(openrouter_key) => Ok(Provider::OpenRouter),
+                "openrouter" => Err("config: OPENROUTER_API_KEY required".into()),
                 _ => Err(format!(
                     "config: BUZZ_AGENT_PROVIDER={raw} not supported"
                 )),
@@ -1225,11 +1263,11 @@ mod tests {
     #[test]
     fn resolve_provider_keeps_requested_provider_when_token_present() {
         assert_eq!(
-            resolve_provider(Some("anthropic"), Some("sk-ant"), None,).unwrap(),
+            resolve_provider(Some("anthropic"), Some("sk-ant"), None, None).unwrap(),
             Provider::Anthropic
         );
         assert_eq!(
-            resolve_provider(Some("openai"), None, Some("sk-openai"),).unwrap(),
+            resolve_provider(Some("openai"), None, Some("sk-openai"), None).unwrap(),
             Provider::OpenAi
         );
     }
@@ -1237,17 +1275,17 @@ mod tests {
     #[test]
     fn resolve_provider_errors_when_requested_provider_key_missing() {
         // No fallback — missing key returns an error regardless of Databricks availability.
-        let err = resolve_provider(Some("anthropic"), None, None).unwrap_err();
+        let err = resolve_provider(Some("anthropic"), None, None, None).unwrap_err();
         assert!(err.contains("ANTHROPIC_API_KEY required"), "{err}");
 
-        let err = resolve_provider(Some("openai-compat"), None, Some("   ")).unwrap_err();
+        let err = resolve_provider(Some("openai-compat"), None, Some("   "), None).unwrap_err();
         assert!(err.contains("OPENAI_COMPAT_API_KEY required"), "{err}");
     }
 
     #[test]
     fn resolve_provider_errors_when_provider_env_absent() {
         // No implicit inference — absent BUZZ_AGENT_PROVIDER is an error.
-        let err = resolve_provider(None, None, None).unwrap_err();
+        let err = resolve_provider(None, None, None, None).unwrap_err();
         assert!(err.contains("BUZZ_AGENT_PROVIDER is required"), "{err}");
     }
 
@@ -1257,19 +1295,19 @@ mod tests {
         // When BUZZ_AGENT_PROVIDER=databricks, resolve_provider succeeds regardless
         // of DATABRICKS_HOST/MODEL (those are validated later in from_env()).
         assert_eq!(
-            resolve_provider(Some("databricks"), None, None).unwrap(),
+            resolve_provider(Some("databricks"), None, None, None).unwrap(),
             Provider::Databricks
         );
         // Missing key for other providers still errors — no Databricks fallback.
-        let err = resolve_provider(Some("openai"), None, None).unwrap_err();
+        let err = resolve_provider(Some("openai"), None, None, None).unwrap_err();
         assert!(err.contains("OPENAI_COMPAT_API_KEY required"), "{err}");
-        let err = resolve_provider(None, None, None).unwrap_err();
+        let err = resolve_provider(None, None, None, None).unwrap_err();
         assert!(err.contains("BUZZ_AGENT_PROVIDER is required"), "{err}");
     }
 
     #[test]
     fn resolve_provider_unsupported_error_preserves_user_casing() {
-        let err = resolve_provider(Some("OpenAIish"), None, None).unwrap_err();
+        let err = resolve_provider(Some("OpenAIish"), None, None, None).unwrap_err();
         assert!(err.contains("BUZZ_AGENT_PROVIDER=OpenAIish"));
     }
 
@@ -2657,6 +2695,9 @@ mod tests {
         if p == "databricks" {
             return openai_result(&m);
         }
+        if p == "openrouter" {
+            return (ALL_7.to_vec(), Some("medium"));
+        }
         // openai-compat, unknown, empty → all-7, default medium.
         (ALL_7.to_vec(), Some("medium"))
     }
@@ -2708,4 +2749,18 @@ mod tests {
             );
         }
     }
+
+    #[test]
+    fn resolve_provider_openrouter_with_key() {
+        assert_eq!(
+            resolve_provider(Some("openrouter"), None, None, Some("sk-or-123")).unwrap(),
+            Provider::OpenRouter
+        );
+    }
+
+    #[test]
+    fn resolve_provider_openrouter_missing_key() {
+        let err = resolve_provider(Some("openrouter"), None, None, None).unwrap_err();
+        assert!(err.contains("OPENROUTER_API_KEY"));
+    }
 }
diff --git a/crates/buzz-agent/src/handoff.rs b/crates/buzz-agent/src/handoff.rs
index 9c27c6606d..3b0feefecf 100644
--- a/crates/buzz-agent/src/handoff.rs
+++ b/crates/buzz-agent/src/handoff.rs
@@ -259,7 +259,11 @@ fn push_history_snippet(out: &mut String, item: &HistoryItem) {
             out.push_str(s);
             out.push('\n');
         }
-        HistoryItem::Assistant { text, tool_calls } => {
+        HistoryItem::Assistant {
+            text,
+            tool_calls,
+            reasoning_details: _,
+        } => {
             out.push_str("[assistant] ");
             if !text.is_empty() {
                 out.push_str(text);
diff --git a/crates/buzz-agent/src/lib.rs b/crates/buzz-agent/src/lib.rs
index e141b9860f..9a45bf4c98 100644
--- a/crates/buzz-agent/src/lib.rs
+++ b/crates/buzz-agent/src/lib.rs
@@ -100,6 +100,19 @@ struct Session {
     accumulated_input_tokens: u64,
     /// Session-cumulative output tokens across all turns.
     accumulated_output_tokens: u64,
+    /// Session-cumulative cache-served input tokens across all turns — a subset
+    /// of `accumulated_input_tokens`, not an addition to it. Emitted alongside
+    /// it so a consumer can price the cached slice at the provider's discounted
+    /// rate instead of assuming every input token cost full price.
+    accumulated_cached_input_tokens: u64,
+    /// Session-cumulative total-token state across all turns.
+    ///
+    /// Mirrors the per-turn `TurnTotalState` tri-state: starts `Unseen`,
+    /// becomes `Exact(n)` as turns with genuine provider totals complete,
+    /// transitions permanently to `Unknown` when any turn lacks a total or
+    /// when the cumulative would otherwise decrease. Only emitted in the
+    /// `usage_update` notification when `Exact`.
+    accumulated_total_state: crate::types::TurnTotalState,
 }
 
 fn die(msg: String) -> ! {
@@ -426,6 +439,8 @@ async fn session_new(app: &Arc<App>, id: Value, params: Value, wire_tx: &WireSen
             effective_model: None,
             accumulated_input_tokens: 0,
             accumulated_output_tokens: 0,
+            accumulated_cached_input_tokens: 0,
+            accumulated_total_state: crate::types::TurnTotalState::Unseen,
         },
     );
     drop(sessions);
@@ -672,6 +687,8 @@ async fn run_prompt(app: Arc<App>, id: Value, params: Value, wire_tx: WireSender
         .unwrap_or(&app.cfg.model);
     let mut turn_input_tokens: Option<u64> = None;
     let mut turn_output_tokens: Option<u64> = None;
+    let mut turn_cached_input_tokens: Option<u64> = None;
+    let mut turn_total_state = crate::types::TurnTotalState::Unseen;
     let mut ctx = RunCtx {
         cfg: &app.cfg,
         effective_model: effective_model_str,
@@ -690,6 +707,8 @@ async fn run_prompt(app: Arc<App>, id: Value, params: Value, wire_tx: WireSender
         last_request_history_bytes: &mut last_request_history_bytes,
         turn_input_tokens: &mut turn_input_tokens,
         turn_output_tokens: &mut turn_output_tokens,
+        turn_cached_input_tokens: &mut turn_cached_input_tokens,
+        turn_total_state: &mut turn_total_state,
     };
     let result = ctx.run(p.prompt).await;
     if let Some(s) = app.sessions.lock().await.get_mut(&sid) {
@@ -722,31 +741,54 @@ async fn run_prompt(app: Arc<App>, id: Value, params: Value, wire_tx: WireSender
                 s.accumulated_output_tokens = s
                     .accumulated_output_tokens
                     .saturating_add(turn_output_tokens.unwrap_or(0));
-                Some((s.accumulated_input_tokens, s.accumulated_output_tokens))
+                s.accumulated_cached_input_tokens = s
+                    .accumulated_cached_input_tokens
+                    .saturating_add(turn_cached_input_tokens.unwrap_or(0));
+                // Fold the per-turn total state into the session cumulative.
+                // Unknown poisons the session permanently; Exact adds to running sum;
+                // Unseen (turn emitted no usage) leaves the cumulative unchanged.
+                // Uses TurnTotalState::merge_session, which applies the same
+                // checked-add / overflow-poisons contract as the per-response fold.
+                s.accumulated_total_state =
+                    s.accumulated_total_state.merge_session(turn_total_state);
+                Some((
+                    s.accumulated_input_tokens,
+                    s.accumulated_output_tokens,
+                    s.accumulated_cached_input_tokens,
+                    s.accumulated_total_state,
+                ))
             } else {
                 // Session is gone — the accumulated baseline no longer exists, so
                 // there is nothing correct to emit. Skip the usage notification.
                 None
             }
         };
-        if let Some((accumulated_in, accumulated_out)) = accumulated {
-            wire::send(
-                &wire_tx,
-                goose_session_update(
-                    &sid,
-                    json!({
-                        "sessionUpdate": "usage_update",
-                        // used: total tokens as a context-usage proxy;
-                        // contextLimit: 0 (buzz-agent has no context limit tracking).
-                        "used": accumulated_in.saturating_add(accumulated_out),
-                        "contextLimit": 0u64,
-                        "accumulatedInputTokens": accumulated_in,
-                        "accumulatedOutputTokens": accumulated_out,
-                        "model": effective_model_str,
-                    }),
-                ),
-            )
-            .await;
+        if let Some((accumulated_in, accumulated_out, accumulated_cached, accumulated_total)) =
+            accumulated
+        {
+            // Build the usage_update payload. `accumulatedTotalTokens` is only
+            // included when the cumulative is exactly known — never when Unseen
+            // (no total ever observed) or Unknown (at least one turn lacked a
+            // total). A goose consumer that doesn't recognise the field ignores it.
+            let mut update = serde_json::json!({
+                "sessionUpdate": "usage_update",
+                // used: total tokens as a context-usage proxy;
+                // contextLimit: 0 (buzz-agent has no context limit tracking).
+                "used": accumulated_in.saturating_add(accumulated_out),
+                "contextLimit": 0u64,
+                "accumulatedInputTokens": accumulated_in,
+                "accumulatedOutputTokens": accumulated_out,
+                // A subset of accumulatedInputTokens, not an addition to
+                // it. Extends goose's usage_update shape; a consumer that
+                // does not know the field ignores it and prices exactly as
+                // it did before.
+                "accumulatedCachedInputTokens": accumulated_cached,
+                "model": effective_model_str,
+            });
+            if let crate::types::TurnTotalState::Exact(total) = accumulated_total {
+                update["accumulatedTotalTokens"] = serde_json::json!(total);
+            }
+            wire::send(&wire_tx, goose_session_update(&sid, update)).await;
         }
     }
     match result {
diff --git a/crates/buzz-agent/src/llm.rs b/crates/buzz-agent/src/llm.rs
index 23cef24e72..73c7e1faf2 100644
--- a/crates/buzz-agent/src/llm.rs
+++ b/crates/buzz-agent/src/llm.rs
@@ -3,7 +3,7 @@ use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Arc;
 
 use reqwest::Client;
-use serde_json::{json, Value};
+use serde_json::{json, Map, Value};
 use tokio::sync::Mutex;
 use tokio::time::Instant;
 
@@ -146,6 +146,18 @@ impl Llm {
                     .await?;
                 parse_anthropic(v)
             }
+            Provider::OpenRouter => {
+                let mut body =
+                    openai_body(cfg, system_prompt, history, tools, effective_model, None);
+                apply_openrouter_mutations(
+                    &mut body,
+                    cfg.thinking_effort,
+                    effective_model,
+                    cfg.prompt_caching,
+                );
+                let v = self.post_openrouter(cfg, &body).await?;
+                parse_openai_with_reasoning_details(v)
+            }
             Provider::OpenAi | Provider::Databricks => {
                 self.openai_request(
                     cfg,
@@ -248,6 +260,16 @@ impl Llm {
                 });
                 Ok(parse_anthropic(self.post_anthropic(cfg, &body).await?)?.text)
             }
+            Provider::OpenRouter => {
+                let body = openrouter_summary_body(
+                    effective_model,
+                    system_prompt,
+                    user_prompt,
+                    max_output_tokens,
+                );
+                let v = self.post_openrouter(cfg, &body).await?;
+                Ok(parse_openai(v)?.text)
+            }
             Provider::OpenAi | Provider::Databricks => {
                 let r = self
                     .openai_request(
@@ -652,6 +674,32 @@ impl Llm {
         }
     }
 
+    async fn post_openrouter(&self, cfg: &Config, body: &Value) -> Result<Value, AgentError> {
+        let url = format!("{}/chat/completions", cfg.base_url.trim_end_matches('/'));
+        let mut bearer = self.auth.bearer().await?;
+        let mut refreshed = false;
+        loop {
+            match openrouter_post(&self.http, &url, body, &bearer).await {
+                Err(AgentError::LlmAuth(_)) if !refreshed => {
+                    refreshed = true;
+                    let new_bearer = self.auth.refresh_now(&bearer).await?;
+                    // A static key refreshes to itself — a byte-identical retry
+                    // would be a guaranteed duplicate request against a key the
+                    // server just rejected. Fail terminal immediately; the retry
+                    // is only meaningful when the source can actually mint a
+                    // distinct token (e.g., a PKCE OAuth source).
+                    if new_bearer == bearer {
+                        return Err(AgentError::LlmAuth(
+                            "401: static key rejected — update key in agent settings".into(),
+                        ));
+                    }
+                    bearer = new_bearer;
+                }
+                result => return result,
+            }
+        }
+    }
+
     /// If `err` names `/v1/responses` / "use the Responses API", latch a
     /// sticky upgrade so subsequent OpenAI calls hit Responses. Logged once.
     fn try_upgrade(&self, err: &AgentError) -> bool {
@@ -695,7 +743,11 @@ fn anthropic_body(
                 messages.push(json!({ "role": "user",
                     "content": [{ "type": "text", "text": text }] }));
             }
-            HistoryItem::Assistant { text, tool_calls } => {
+            HistoryItem::Assistant {
+                text,
+                tool_calls,
+                reasoning_details: _,
+            } => {
                 flush(&mut messages, &mut pending);
                 let mut content: Vec<Value> = Vec::new();
                 if !text.is_empty() {
@@ -720,6 +772,12 @@ fn anthropic_body(
         }
     }
     flush(&mut messages, &mut pending);
+    // Rolling cache breakpoint: mark the tail of the (append-only) conversation
+    // so the next turn re-reads this whole prefix from cache instead of paying
+    // full input price for it. See `stamp_rolling_cache_breakpoint`.
+    if cfg.prompt_caching {
+        stamp_rolling_cache_breakpoint(&mut messages);
+    }
     let tools_json: Vec<Value> = tools
         .iter()
         .map(|t| {
@@ -727,8 +785,19 @@ fn anthropic_body(
         "name": t.name, "description": t.description, "input_schema": t.input_schema })
         })
         .collect();
+    // Static prefix breakpoint: caching the `system` block caches the whole
+    // prefix up to and including it — and the prefix order is
+    // `tools -> system -> messages`, so this single marker caches tools +
+    // system together. Requires the structured (array) form of `system`; skip
+    // it for an empty prompt since Anthropic rejects empty text blocks.
+    let system_value = if cfg.prompt_caching && !system_prompt.is_empty() {
+        json!([{ "type": "text", "text": system_prompt,
+            "cache_control": { "type": "ephemeral" } }])
+    } else {
+        json!(system_prompt)
+    };
     let mut body = json!({ "model": effective_model, "max_tokens": cfg.max_output_tokens,
-        "system": system_prompt, "messages": messages });
+        "system": system_value, "messages": messages });
     if let Some(e) = effort {
         let (thinking, output_config) =
             crate::config::anthropic_thinking_config(effective_model, e, cfg.max_output_tokens);
@@ -745,6 +814,41 @@ fn anthropic_body(
     body
 }
 
+/// Attach ephemeral `cache_control` markers to the tail of the conversation so
+/// the next turn re-reads the whole prior prefix from cache (~0.1x input price)
+/// rather than re-billing it as fresh input. Anthropic caches the prefix up to
+/// and including each marked block.
+///
+/// We mark the last content block of the last *two* messages, not just the
+/// final one. Each Anthropic breakpoint walks back at most 20 content blocks to
+/// find a prior cache entry, and one agentic turn can append ~17 blocks at the
+/// default `max_parallel_tools` (1 assistant text + N `tool_use` +
+/// N `tool_result`). With only a tail marker, consecutive breakpoints sit a
+/// full turn apart, which slips past the 20-block window as soon as parallelism
+/// rises or a turn carries extra blocks — and the miss is silent. Marking the
+/// last two messages halves the gap (to ~N+1 blocks), keeping a live cache
+/// entry comfortably within reach. Uses 2 of the 4 allowed breakpoints; the
+/// static `system` marker is the third.
+///
+/// A no-op for messages whose content is empty or whose tail block is not a
+/// JSON object.
+fn stamp_rolling_cache_breakpoint(messages: &mut [Value]) {
+    let n = messages.len();
+    // The two most-recently-appended messages (the current turn's tool results
+    // and the assistant turn before them). `checked_sub` + `flatten` skips the
+    // second index when there is only one message.
+    for idx in [n.checked_sub(1), n.checked_sub(2)].into_iter().flatten() {
+        if let Some(block) = messages[idx]
+            .get_mut("content")
+            .and_then(Value::as_array_mut)
+            .and_then(|c| c.last_mut())
+            .and_then(Value::as_object_mut)
+        {
+            block.insert("cache_control".into(), json!({ "type": "ephemeral" }));
+        }
+    }
+}
+
 fn anthropic_tool_result_content(content: &[ToolResultContent]) -> Vec<Value> {
     content
         .iter()
@@ -787,20 +891,40 @@ fn openai_body(
                 flush_images(&mut messages, &mut pending_images);
                 messages.push(json!({ "role": "user", "content": text }));
             }
-            HistoryItem::Assistant { text, tool_calls } => {
+            HistoryItem::Assistant {
+                text,
+                tool_calls,
+                reasoning_details,
+            } => {
                 flush_images(&mut messages, &mut pending_images);
                 let mut msg = serde_json::Map::new();
                 msg.insert("role".into(), json!("assistant"));
                 msg.insert("content".into(), json!(text.as_str()));
+                if let Some(details) = reasoning_details {
+                    msg.insert("reasoning_details".into(), details.clone());
+                }
                 if !tool_calls.is_empty() {
                     let calls: Vec<Value> = tool_calls
                         .iter()
                         .map(|c| {
-                            json!({
-                        "id": c.provider_id, "type": "function",
-                        "function": { "name": c.name,
-                            "arguments": serde_json::to_string(&c.arguments)
-                                .unwrap_or_else(|_| "{}".into()) } })
+                            let mut call = serde_json::Map::new();
+                            call.insert("id".into(), json!(c.provider_id));
+                            call.insert("type".into(), json!("function"));
+                            // Provider-owned fields go back beside `function`,
+                            // which is where the provider put them. Position is
+                            // load-bearing, not cosmetic: Gemini rejects a
+                            // `thoughtSignature` nested inside `function{}` with
+                            // the same 400 it gives for one that is missing.
+                            for (k, v) in &c.provider_extra {
+                                call.insert(k.clone(), v.clone());
+                            }
+                            call.insert(
+                                "function".into(),
+                                json!({ "name": c.name,
+                                    "arguments": serde_json::to_string(&c.arguments)
+                                        .unwrap_or_else(|_| "{}".into()) }),
+                            );
+                            Value::Object(call)
                         })
                         .collect();
                     msg.insert("tool_calls".into(), Value::Array(calls));
@@ -886,7 +1010,11 @@ fn responses_body(
                 "role": "user",
                 "content": [{ "type": "input_text", "text": text }],
             })),
-            HistoryItem::Assistant { text, tool_calls } => {
+            HistoryItem::Assistant {
+                text,
+                tool_calls,
+                reasoning_details: _,
+            } => {
                 if !text.is_empty() {
                     input.push(json!({
                         "role": "assistant",
@@ -967,13 +1095,53 @@ fn is_responses_required_error(body: &str) -> bool {
         || b.contains("use the responses api")
 }
 
+/// OpenAI-family code names that appear as their own segment in a Databricks v2
+/// endpoint name (the GPT-5 launch aliases). The `gpt` family itself is matched
+/// separately by segment prefix so `gpt`, `gpt5`, and the `gpt` of a split
+/// `gpt-5` all qualify.
+const DATABRICKS_V2_OPENAI_CODE_NAMES: &[&str] = &["sol", "luna", "terra"];
+
+/// Anthropic (Claude) family and release code names that appear as their own
+/// segment in a Databricks v2 endpoint name — the `claude` prefix, the family
+/// names (`opus`, `sonnet`, `haiku`), and the release code names (`mythos`,
+/// `fable`). Getting a Claude model onto the Anthropic Messages route is what
+/// lets it carry a `cache_control` breakpoint; an endpoint that matches none of
+/// these falls through to the MLflow (OpenAI-wire) path, where Anthropic prompt
+/// caching is structurally impossible and the discount is silently lost.
+const DATABRICKS_V2_CLAUDE_NAMES: &[&str] =
+    &["claude", "opus", "sonnet", "haiku", "mythos", "fable"];
+
+/// Split a Databricks v2 endpoint name into its lowercase alphanumeric segments,
+/// breaking on any non-alphanumeric delimiter (`-`, `_`, `.`, `/`, …). E.g.
+/// `Databricks-Claude-Opus-5` -> `["databricks", "claude", "opus", "5"]`.
+fn model_name_segments(model: &str) -> Vec<String> {
+    model
+        .split(|c: char| !c.is_ascii_alphanumeric())
+        .filter(|s| !s.is_empty())
+        .map(str::to_ascii_lowercase)
+        .collect()
+}
+
 fn databricks_v2_route_for_model(model: &str) -> DatabricksV2Route {
-    // Databricks v2 catalog names currently identify OpenAI-shaped GPT-5
-    // models and Anthropic-shaped Claude models by these substrings.
-    let lower = model.to_ascii_lowercase();
-    if lower.contains("gpt-5") || lower.contains("gpt5") {
+    // The v2 catalog exposes no family field, so the wire format is inferred
+    // from the endpoint name. Discovery deliberately keeps arbitrary custom
+    // aliases, so we match whole name *segments* rather than raw substrings: a
+    // substring test would misroute unrelated names — `consolidated-llama`
+    // (`sol`), `terraform-coder` (`terra`), `corpus-reranker`/`octopus-model`
+    // (`opus`) — onto a wire whose request shape their backend can't parse,
+    // turning a caching optimization into a hard request/parse failure. Segment
+    // matching still accepts real prefixed names like `goose-opus-5`.
+    let segments = model_name_segments(model);
+    let has_named_segment =
+        |names: &[&str]| segments.iter().any(|seg| names.contains(&seg.as_str()));
+    // `gpt` family: any segment beginning with `gpt` — covers `gpt`, `gpt5`, and
+    // the `gpt` segment of a split `gpt-5`, without matching mid-word.
+    let is_gpt_family = segments.iter().any(|seg| seg.starts_with("gpt"));
+    // OpenAI is checked before Claude so a name carrying both markers resolves
+    // to the OpenAI wire (preserving the prior `gpt-5`-first precedence).
+    if is_gpt_family || has_named_segment(DATABRICKS_V2_OPENAI_CODE_NAMES) {
         DatabricksV2Route::OpenAiResponses
-    } else if lower.contains("claude") {
+    } else if has_named_segment(DATABRICKS_V2_CLAUDE_NAMES) {
         DatabricksV2Route::AnthropicMessages
     } else {
         DatabricksV2Route::MlflowChatCompletions
@@ -1028,10 +1196,15 @@ fn parse_responses(v: Value) -> Result<LlmResponse, AgentError> {
                 let args: Value = serde_json::from_str(raw).map_err(|e| {
                     AgentError::Llm(format!("function_call.arguments not valid JSON: {e}"))
                 })?;
+                // No passthrough on this route: `responses_body` replays a
+                // function call as `{call_id, name, arguments}` and the Responses
+                // API asks for nothing else, so an empty map keeps the request
+                // byte-identical to before.
                 tool_calls.push(make_tool_call(
                     str_field(item, "call_id"),
                     str_field(item, "name"),
                     args,
+                    Default::default(),
                 )?);
             }
             Some("reasoning") => {
@@ -1079,13 +1252,25 @@ fn parse_responses(v: Value) -> Result<LlmResponse, AgentError> {
     };
     let input_tokens = sum_usage(&v, &["input_tokens"]);
     let output_tokens = sum_usage(&v, &["output_tokens"]);
+    // The Responses API nests the cache split under `input_tokens_details`.
+    let cached_input_tokens = usage_first(
+        &v,
+        &["cache_read_input_tokens"],
+        &[("input_tokens_details", "cached_tokens")],
+    );
+    // Responses API reports a genuine provider total. Read it directly —
+    // never derived, so it stays None when the provider omits it.
+    let total_tokens = sum_usage(&v, &["total_tokens"]);
     Ok(LlmResponse {
         text,
         tool_calls,
         stop,
         input_tokens,
+        cached_input_tokens,
         output_tokens,
+        total_tokens,
         reasoning,
+        reasoning_details: None,
     })
 }
 
@@ -1131,19 +1316,70 @@ fn anthropic_input_tokens(v: &Value) -> Option<u64> {
     )
 }
 
-/// Input-token total for OpenAI Chat Completions and Databricks responses.
-/// OpenAI's `prompt_tokens` is already inclusive. Databricks uses the same
-/// `prompt_tokens` wire field but ALSO reports Anthropic-style cache fields
-/// alongside it, so we sum them; the cache fields are simply absent (and
-/// contribute 0) for vanilla OpenAI.
+/// Input-token total for OpenAI Chat Completions and Databricks MLflow-route
+/// responses. `prompt_tokens` is already the inclusive input total on both, so
+/// it is read alone and never summed with the cache fields.
+///
+/// Vanilla OpenAI nests the cache split under `prompt_tokens_details` and
+/// `prompt_tokens` includes it. The Databricks MLflow route reports the split
+/// with the flat Anthropic spelling (`cache_read_input_tokens`) *alongside* an
+/// already-inclusive `prompt_tokens` — so summing double-counts. Verified on
+/// `databricks-glm-5-2` (2026-07-28): `prompt_tokens 13320`,
+/// `cache_read_input_tokens 13312`, `completion_tokens 30`, `total_tokens
+/// 13350`; since `prompt_tokens + completion_tokens == total_tokens`, the 13312
+/// cached tokens are contained in the 13320, not additional to it. Summing gave
+/// 26632 — nearly double — inflating both the context-budget gate and cost.
+///
+/// This differs from Anthropic's native route (see [`anthropic_input_tokens`]),
+/// where `input_tokens` genuinely EXCLUDES the cache fields and must be summed.
+/// The two never collide here: the router sends `claude*` models to the
+/// Anthropic route, so `parse_openai` only ever sees inclusive `prompt_tokens`.
 fn openai_chat_input_tokens(v: &Value) -> Option<u64> {
-    sum_usage(
+    sum_usage(v, &["prompt_tokens"])
+}
+
+/// First present value among `usage.<field>` and `usage.<nested>.<leaf>` pairs.
+///
+/// Cache counts are the one usage figure providers do not agree on the shape of.
+/// Anthropic puts `cache_read_input_tokens` flat on `usage`; OpenAI nests the
+/// same quantity one level down, under `prompt_tokens_details` on
+/// `/chat/completions` and `input_tokens_details` on `/responses`. [`sum_usage`]
+/// only reads flat keys, which is why the OpenAI split was invisible for so
+/// long: `prompt_tokens` is already inclusive, so the *total* was right and
+/// nothing looked broken while the discount silently went unclaimed.
+///
+/// Returns the first candidate that resolves, not a sum — these are alternative
+/// spellings of one number, so adding them would double-count on Databricks,
+/// which reports both shapes.
+fn usage_first(v: &Value, flat: &[&str], nested: &[(&str, &str)]) -> Option<u64> {
+    let usage = v.get("usage")?;
+    for f in flat {
+        if let Some(n) = usage.get(*f).and_then(Value::as_u64) {
+            return Some(n);
+        }
+    }
+    for (outer, leaf) in nested {
+        if let Some(n) = usage
+            .get(*outer)
+            .and_then(|o| o.get(*leaf))
+            .and_then(Value::as_u64)
+        {
+            return Some(n);
+        }
+    }
+    None
+}
+
+/// Cache-read tokens for an OpenAI Chat Completions response.
+///
+/// `prompt_tokens_details.cached_tokens` is where vanilla OpenAI reports it.
+/// The flat Anthropic spelling is checked first for Databricks, which routes
+/// Anthropic models through an OpenAI-shaped envelope.
+fn openai_chat_cached_tokens(v: &Value) -> Option<u64> {
+    usage_first(
         v,
-        &[
-            "prompt_tokens",
-            "cache_read_input_tokens",
-            "cache_creation_input_tokens",
-        ],
+        &["cache_read_input_tokens"],
+        &[("prompt_tokens_details", "cached_tokens")],
     )
 }
 
@@ -1151,6 +1387,76 @@ fn str_field(v: &Value, key: &str) -> String {
     v.get(key).and_then(Value::as_str).unwrap_or("").to_owned()
 }
 
+/// Append `part` to `buf` on its own line, ignoring empties.
+fn push_part(buf: &mut String, part: &str) {
+    if part.is_empty() {
+        return;
+    }
+    if !buf.is_empty() {
+        buf.push('\n');
+    }
+    buf.push_str(part);
+}
+
+/// Split an OpenAI-shaped `message.content` into `(text, reasoning)`.
+///
+/// Standard OpenAI sends a string. Several models on the Databricks MLflow route
+/// — Gemini, Qwen35, gpt-oss — send an array of typed blocks instead, and
+/// `as_str()` yields nothing for an array, so their entire answer was being
+/// discarded: no error, no warning, just a turn that looked like the model had
+/// said nothing. `parse_anthropic` already walks a block array; this gives
+/// `parse_openai` the same tolerance.
+fn openai_content_parts(content: Option<&Value>) -> (String, String) {
+    let mut text = String::new();
+    let mut reasoning = String::new();
+    match content {
+        Some(Value::String(s)) => text.push_str(s),
+        Some(Value::Array(blocks)) => {
+            for b in blocks {
+                match b.get("type").and_then(Value::as_str) {
+                    Some("text") => push_part(&mut text, &str_field(b, "text")),
+                    Some("reasoning") => match b.get("summary").and_then(Value::as_array) {
+                        // Gemini nests the prose one level down under `summary`.
+                        Some(summary) => {
+                            for s in summary {
+                                push_part(&mut reasoning, &str_field(s, "text"));
+                            }
+                        }
+                        None => push_part(&mut reasoning, &str_field(b, "text")),
+                    },
+                    // An untyped block carrying text is still the model talking;
+                    // treating it as text loses nothing and keeps one more
+                    // provider out of the silent-empty-answer failure mode.
+                    _ => push_part(&mut text, &str_field(b, "text")),
+                }
+            }
+        }
+        _ => {}
+    }
+    (text, reasoning)
+}
+
+/// Make `provider_id` unique across one assistant turn's tool calls.
+///
+/// Gemini returns the function name as the id, so two parallel calls to the same
+/// function arrive sharing one id — and that id is what pairs a `role:"tool"`
+/// result back to its call, leaving two results indistinguishable. Rewriting is
+/// safe because both halves of that pairing are re-emitted from this same value;
+/// the provider never sees its original id again.
+fn dedupe_provider_ids(calls: &mut [ToolCall]) {
+    let mut seen: BTreeSet<String> = BTreeSet::new();
+    for c in calls.iter_mut() {
+        if seen.contains(&c.provider_id) {
+            let mut n = 2;
+            while seen.contains(&format!("{}-{n}", c.provider_id)) {
+                n += 1;
+            }
+            c.provider_id = format!("{}-{n}", c.provider_id);
+        }
+        seen.insert(c.provider_id.clone());
+    }
+}
+
 fn parse_anthropic(v: Value) -> Result<LlmResponse, AgentError> {
     let stop = map_stop(v.get("stop_reason").and_then(Value::as_str));
     let mut tool_calls = Vec::new();
@@ -1173,10 +1479,12 @@ fn parse_anthropic(v: Value) -> Result<LlmResponse, AgentError> {
                         reasoning.push_str(t);
                     }
                 }
+                // Anthropic's replay shape is fully modelled, so nothing to keep.
                 Some("tool_use") => tool_calls.push(make_tool_call(
                     str_field(b, "id"),
                     str_field(b, "name"),
                     b.get("input").cloned().unwrap_or(Value::Null),
+                    Default::default(),
                 )?),
                 _ => {}
             }
@@ -1184,17 +1492,58 @@ fn parse_anthropic(v: Value) -> Result<LlmResponse, AgentError> {
     }
     let input_tokens = anthropic_input_tokens(&v);
     let output_tokens = sum_usage(&v, &["output_tokens"]);
+    // Anthropic reports the cache split flat on `usage`. Note this is already
+    // part of `input_tokens` above, which sums it in deliberately.
+    let cached_input_tokens = usage_first(&v, &["cache_read_input_tokens"], &[]);
     Ok(LlmResponse {
         text,
         tool_calls,
         stop,
         input_tokens,
+        cached_input_tokens,
         output_tokens,
+        // Anthropic reports only category counts; NIP-AM forbids deriving a
+        // total from them. Always None for this provider.
+        total_tokens: None,
         reasoning,
+        reasoning_details: None,
     })
 }
 
 fn parse_openai(v: Value) -> Result<LlmResponse, AgentError> {
+    // A5: error-inside-200 check — choice-level `finish_reason == "error"`
+    if let Some(choice) = v
+        .get("choices")
+        .and_then(Value::as_array)
+        .and_then(|a| a.first())
+    {
+        if choice.get("finish_reason").and_then(Value::as_str) == Some("error") {
+            let err = choice.get("error").cloned().unwrap_or(Value::Null);
+            // OpenRouter's `error.code` is numeric; other OpenAI-compat hosts
+            // may send a string. Accept either rather than discarding the
+            // typed code as "unknown".
+            let code = err
+                .get("code")
+                .and_then(|c| {
+                    c.as_str()
+                        .map(str::to_string)
+                        .or_else(|| c.as_i64().map(|n| n.to_string()))
+                })
+                .unwrap_or_else(|| "unknown".into());
+            let message = err
+                .get("message")
+                .and_then(Value::as_str)
+                .unwrap_or("provider error in 200 response");
+            let error_type = err
+                .get("metadata")
+                .and_then(|m| m.get("error_type"))
+                .and_then(Value::as_str);
+            return Err(AgentError::Llm(match error_type {
+                Some(et) => format!("provider error ({code}, {et}): {message}"),
+                None => format!("provider error ({code}): {message}"),
+            }));
+        }
+    }
     let choice = v
         .get("choices")
         .and_then(Value::as_array)
@@ -1204,17 +1553,23 @@ fn parse_openai(v: Value) -> Result<LlmResponse, AgentError> {
     let msg = choice
         .get("message")
         .ok_or_else(|| AgentError::Llm("missing message".into()))?;
-    let text = str_field(msg, "content");
+    let (text, block_reasoning) = openai_content_parts(msg.get("content"));
     // DeepSeek and vLLM-style OpenAI-compat hosts expose reasoning tokens on the
     // message object. Prefer `reasoning_content` (DeepSeek's field name); fall
-    // back to `reasoning` (some other providers). Both are absent for standard
-    // OpenAI responses, which leaves this empty without any special-casing.
+    // back to `reasoning` (some other providers), and last to reasoning blocks
+    // found inside `content`. All three are absent for standard OpenAI
+    // responses, which leaves this empty without any special-casing.
     let reasoning = {
         let rc = str_field(msg, "reasoning_content");
-        if rc.is_empty() {
+        let rc = if rc.is_empty() {
             str_field(msg, "reasoning")
         } else {
             rc
+        };
+        if rc.is_empty() {
+            block_reasoning
+        } else {
+            rc
         }
     };
     let mut tool_calls = Vec::new();
@@ -1226,26 +1581,64 @@ fn parse_openai(v: Value) -> Result<LlmResponse, AgentError> {
             let raw = f.get("arguments").and_then(Value::as_str).unwrap_or("{}");
             let args: Value = serde_json::from_str(raw)
                 .map_err(|e| AgentError::Llm(format!("tool_call.arguments not valid JSON: {e}")))?;
+            // Everything on the wire object we do not model, kept for replay.
+            let extra = tc
+                .as_object()
+                .map(|o| {
+                    o.iter()
+                        .filter(|(k, _)| !matches!(k.as_str(), "id" | "type" | "function"))
+                        .map(|(k, v)| (k.clone(), v.clone()))
+                        .collect()
+                })
+                .unwrap_or_default();
             tool_calls.push(make_tool_call(
                 str_field(tc, "id"),
                 str_field(f, "name"),
                 args,
+                extra,
             )?);
         }
     }
+    dedupe_provider_ids(&mut tool_calls);
     let input_tokens = openai_chat_input_tokens(&v);
     let output_tokens = sum_usage(&v, &["completion_tokens"]);
+    let cached_input_tokens = openai_chat_cached_tokens(&v);
+    // OpenAI Chat Completions reports a genuine provider total. Read it
+    // directly — never derived, so it stays None when the provider omits it.
+    let total_tokens = sum_usage(&v, &["total_tokens"]);
     Ok(LlmResponse {
         text,
         tool_calls,
         stop,
         input_tokens,
+        cached_input_tokens,
         output_tokens,
+        total_tokens,
         reasoning,
+        reasoning_details: None,
     })
 }
 
-fn make_tool_call(id: String, name: String, args: Value) -> Result<ToolCall, AgentError> {
+fn parse_openai_with_reasoning_details(v: Value) -> Result<LlmResponse, AgentError> {
+    let reasoning_details = v
+        .get("choices")
+        .and_then(Value::as_array)
+        .and_then(|a| a.first())
+        .and_then(|c| c.get("message"))
+        .and_then(|m| m.get("reasoning_details"))
+        .filter(|rd| rd.is_array())
+        .cloned();
+    let mut response = parse_openai(v)?;
+    response.reasoning_details = reasoning_details;
+    Ok(response)
+}
+
+fn make_tool_call(
+    id: String,
+    name: String,
+    args: Value,
+    provider_extra: Map<String, Value>,
+) -> Result<ToolCall, AgentError> {
     if id.is_empty() || name.is_empty() {
         return Err(AgentError::Llm("tool_call missing id or name".into()));
     }
@@ -1262,6 +1655,7 @@ fn make_tool_call(id: String, name: String, args: Value) -> Result<ToolCall, Age
         provider_id: id,
         name,
         arguments,
+        provider_extra,
     })
 }
 
@@ -1528,7 +1922,7 @@ where
 ///   flow; subsequent requests use the cache + refresh transparently.
 pub(crate) fn build_token_source(cfg: &Config) -> Result<Arc<dyn TokenSource>, AgentError> {
     match cfg.provider {
-        Provider::Anthropic | Provider::OpenAi => {
+        Provider::Anthropic | Provider::OpenAi | Provider::OpenRouter => {
             Ok(Arc::new(StaticTokenSource::new(cfg.api_key.clone())))
         }
         Provider::Databricks | Provider::DatabricksV2 => {
@@ -1554,6 +1948,29 @@ pub(crate) fn build_token_source(cfg: &Config) -> Result<Arc<dyn TokenSource>, A
     }
 }
 
+/// Build the request body for `Llm::summarize` on `Provider::OpenRouter`.
+/// Extracted so tests can assert on the actual wire shape instead of a
+/// hand-rolled literal — summaries never carry `reasoning` (see
+/// `apply_openrouter_mutations`, which the summary path never calls).
+/// It spells the token limit `max_tokens` directly for the same reason: the
+/// mutation that renames it is never applied here.
+fn openrouter_summary_body(
+    effective_model: &str,
+    system_prompt: &str,
+    user_prompt: &str,
+    max_output_tokens: u32,
+) -> Value {
+    json!({
+        "model": effective_model,
+        "stream": false,
+        "max_tokens": max_output_tokens,
+        "messages": [
+            { "role": "system", "content": system_prompt },
+            { "role": "user", "content": user_prompt },
+        ],
+    })
+}
+
 /// Return a clone of `body` with any top-level `"model"` field removed.
 /// Used for Databricks model-serving, which encodes the model in the URL
 /// path and rejects the field in the body.
@@ -1568,12 +1985,353 @@ fn strip_model(body: &Value) -> Value {
     }
 }
 
+#[derive(Debug)]
+enum OpenRouterErrorClass {
+    Retryable(Option<std::time::Duration>),
+    Unknown,
+}
+
+/// Ceiling applied to the server-supplied `Retry-After` header before we
+/// sleep on it. OpenRouter can advertise waits up to an hour, but
+/// `openrouter_post`'s per-attempt sleep happens *outside*
+/// `Client::timeout` (`cfg.llm_timeout`, default 240s) — an unclamped hint
+/// could keep a single turn alive for up to two full-duration sleeps across
+/// `MAX_RETRIES`. Clamping (never rejecting) keeps us honoring the server's
+/// backoff signal while bounding worst-case turn latency to a value smaller
+/// than the connect/response timeout.
+const RETRY_AFTER_CAP_SECS: u64 = 60;
+
+fn parse_retry_after_header(headers: &reqwest::header::HeaderMap) -> Option<std::time::Duration> {
+    let val = headers.get(reqwest::header::RETRY_AFTER)?.to_str().ok()?;
+    let secs: u64 = val.trim().parse().ok()?;
+    (secs > 0).then(|| std::time::Duration::from_secs(secs.min(RETRY_AFTER_CAP_SECS)))
+}
+
+fn classify_openrouter_error(
+    status: u16,
+    body: &str,
+    header_retry_after: Option<std::time::Duration>,
+) -> OpenRouterErrorClass {
+    let parsed: Option<Value> = serde_json::from_str(body).ok();
+    let error_type = parsed
+        .as_ref()
+        .and_then(|v| v.get("error"))
+        .and_then(|e| e.get("metadata"))
+        .and_then(|m| m.get("error_type"))
+        .and_then(Value::as_str);
+    // OpenRouter's documented retry hint is the HTTP `Retry-After` header
+    // (see https://openrouter.ai/docs/api_reference/errors-and-debugging);
+    // no current doc specifies a body-level retry field, so we don't parse one.
+    let retry_after = header_retry_after;
+
+    match (status, error_type) {
+        (429, _) => OpenRouterErrorClass::Retryable(retry_after),
+        (502, _) => OpenRouterErrorClass::Retryable(None),
+        (503, Some("provider_overloaded")) => OpenRouterErrorClass::Retryable(retry_after),
+        _ => OpenRouterErrorClass::Unknown,
+    }
+}
+
+/// The one place the parameter-routing failure is worded. OpenRouter reports it
+/// two ways — a 404 `No endpoints found ...` (what a `require_parameters`-style
+/// or unsupported-parameter body actually returns) and an untyped 503 — and both
+/// mean the same thing to the user: the model id is fine, the request shape is
+/// not serveable by any endpoint behind it.
+fn openrouter_parameter_routing_error(error_body: &str) -> AgentError {
+    AgentError::Llm(format!(
+        "no OpenRouter endpoint supports the requested parameters — \
+         check model, effort, and tool requirements: {error_body}"
+    ))
+}
+
+async fn openrouter_post(
+    http: &Client,
+    url: &str,
+    body: &Value,
+    bearer: &str,
+) -> Result<Value, AgentError> {
+    let body_bytes =
+        serde_json::to_vec(body).map_err(|e| AgentError::Llm(format!("serialize: {e}")))?;
+    let call_start = std::time::Instant::now();
+    for attempt in 0..MAX_RETRIES {
+        let resp = match http
+            .post(url)
+            .header("content-type", "application/json")
+            .header("HTTP-Referer", "https://github.com/block/buzz")
+            .header("X-OpenRouter-Title", "Buzz")
+            .bearer_auth(bearer)
+            .body(body_bytes.clone())
+            .send()
+            .await
+        {
+            Ok(r) => r,
+            Err(e) => {
+                if attempt + 1 < MAX_RETRIES && is_retryable_transport_error(&e) {
+                    tracing::warn!(
+                        attempt = attempt + 1,
+                        max_attempts = MAX_RETRIES,
+                        error = %e,
+                        "llm: openrouter transport error, retrying"
+                    );
+                    backoff_with_jitter(attempt).await;
+                    continue;
+                }
+                return Err(terminal_llm_error(
+                    call_start.elapsed(),
+                    attempt + 1,
+                    &format!("transport: {e}"),
+                ));
+            }
+        };
+        let status = resp.status();
+        // Unlike the generic `post` path, OpenRouter's static-key auth makes
+        // 401 and 403 distinguishable: 401 is an invalid/expired key (worth
+        // one refresh-and-retry), while OpenRouter documents 403 as a
+        // guardrail/moderation/permission rejection the same key will always
+        // reproduce. Refreshing a static key returns the identical key, so
+        // classifying 403 as `LlmAuth` would just waste a duplicate request
+        // and surface Desktop's unrelated "access denied" copy.
+        if status == 401 {
+            return Err(AgentError::LlmAuth(read_error_body(resp).await));
+        }
+        if status == 403 {
+            return Err(AgentError::Llm(format!(
+                "{status}: {}",
+                read_error_body(resp).await
+            )));
+        }
+        if status == 402 {
+            return Err(AgentError::Llm(
+                "OpenRouter credits exhausted — check https://openrouter.ai/credits".into(),
+            ));
+        }
+        if status == 404 {
+            // OpenRouter overloads 404: a genuinely unknown/unavailable model id
+            // and a valid model whose parameter set no endpoint can serve both
+            // land here. Discriminate on the full parameter-routing phrase rather
+            // than a prefix — "No endpoints found for <model>"-style bodies are
+            // about the model, and reporting a parameter problem as
+            // `LlmModelNotFound` (or vice versa) sends the user to the wrong fix.
+            let error_body = read_error_body(resp).await;
+            if error_body.contains("No endpoints found that can handle the requested parameters") {
+                return Err(openrouter_parameter_routing_error(&error_body));
+            }
+            return Err(AgentError::LlmModelNotFound(format!(
+                "{status}: {error_body}"
+            )));
+        }
+        // A6: status+error_type retry matrix
+        // 499 (Client Closed Request) is included: OpenRouter may emit it when a
+        // turn times out mid-stream. Will added 499 to the shared `post()` path in
+        // #2175 for the same reason; OpenRouter must match to avoid silently opting
+        // out of that stall-surfacing recovery.
+        if status.is_server_error() || status == 429 || status.as_u16() == 499 {
+            let header_retry_after = parse_retry_after_header(resp.headers());
+            let error_body = read_error_body(resp).await;
+            let should_retry = if attempt + 1 < MAX_RETRIES {
+                match classify_openrouter_error(status.as_u16(), &error_body, header_retry_after) {
+                    OpenRouterErrorClass::Retryable(delay) => {
+                        if let Some(d) = delay {
+                            tokio::time::sleep(d).await;
+                        } else {
+                            backoff_with_jitter(attempt).await;
+                        }
+                        true
+                    }
+                    OpenRouterErrorClass::Unknown => {
+                        backoff_with_jitter(attempt).await;
+                        true
+                    }
+                }
+            } else {
+                false
+            };
+            if should_retry {
+                continue;
+            }
+            // Terminal: classify for the user
+            return if status == 429 {
+                Err(terminal_llm_error(
+                    call_start.elapsed(),
+                    attempt + 1,
+                    &format!("rate limited: {error_body}"),
+                ))
+            } else {
+                let parsed: Option<Value> = serde_json::from_str(&error_body).ok();
+                let has_error_type = parsed
+                    .as_ref()
+                    .and_then(|v| v.get("error"))
+                    .and_then(|e| e.get("metadata"))
+                    .and_then(|m| m.get("error_type"))
+                    .and_then(Value::as_str)
+                    .is_some();
+                Err(if !has_error_type && status.as_u16() == 503 {
+                    openrouter_parameter_routing_error(&error_body)
+                } else {
+                    terminal_llm_error(
+                        call_start.elapsed(),
+                        attempt + 1,
+                        &format!("exhausted retries: {status}: {error_body}"),
+                    )
+                })
+            };
+        }
+        if !status.is_success() {
+            return Err(AgentError::Llm(format!(
+                "{status}: {}",
+                read_error_body(resp).await
+            )));
+        }
+        if let Some(len) = resp.content_length() {
+            if len as usize > MAX_LLM_RESPONSE_BYTES {
+                return Err(AgentError::Llm(format!(
+                    "response too large: {len} > {MAX_LLM_RESPONSE_BYTES}"
+                )));
+            }
+        }
+        let mut buf: Vec<u8> = Vec::new();
+        let mut stream = resp;
+        loop {
+            match stream.chunk().await {
+                Ok(Some(chunk)) => {
+                    if buf.len() + chunk.len() > MAX_LLM_RESPONSE_BYTES {
+                        return Err(AgentError::Llm(format!(
+                            "response exceeded {MAX_LLM_RESPONSE_BYTES} bytes"
+                        )));
+                    }
+                    buf.extend_from_slice(&chunk);
+                }
+                Ok(None) => break,
+                Err(e) => {
+                    return Err(terminal_llm_error(
+                        call_start.elapsed(),
+                        attempt + 1,
+                        &format!("body read: {e}"),
+                    ))
+                }
+            }
+        }
+        return serde_json::from_slice(&buf).map_err(|e| AgentError::Llm(format!("json: {e}")));
+    }
+    Err(terminal_llm_error(
+        call_start.elapsed(),
+        MAX_RETRIES,
+        "exhausted retries",
+    ))
+}
+
+fn apply_openrouter_mutations(
+    body: &mut Value,
+    effort: Option<ThinkingEffort>,
+    effective_model: &str,
+    prompt_caching: bool,
+) {
+    if let Some(obj) = body.as_object_mut() {
+        // OpenRouter's Chat Completions API spells the output cap `max_tokens`;
+        // `max_completion_tokens` is OpenAI-native and only 53 of 274
+        // tools-capable OpenRouter models advertise it. Sending the OpenAI
+        // spelling risks the cap being dropped on the floor by the endpoint we
+        // route to, so translate it here rather than at the shared `openai_body`
+        // (which OpenAI and Databricks also use, where the OpenAI spelling is
+        // correct).
+        if let Some(max_tokens) = obj.remove("max_completion_tokens") {
+            obj.insert("max_tokens".into(), max_tokens);
+        }
+
+        // A2/A3: Add OpenRouter reasoning object when effort is configured.
+        // Deliberately NOT paired with `provider.require_parameters`: that filter
+        // routes only to endpoints advertising every parameter in the body, and
+        // 83 of 274 tools-capable models do not advertise `reasoning`, so it turns
+        // an opt-in effort setting into a hard 404 ("No endpoints found that can
+        // handle the requested parameters") on a model id that is perfectly
+        // valid. OpenRouter already best-effort routes on `tools`/`max_tokens`
+        // without the filter, so we accept a request served without reasoning
+        // over a request that cannot be served at all.
+        if let Some(e) = effort {
+            obj.insert(
+                "reasoning".into(),
+                json!({ "effort": e.openai_effort_str() }),
+            );
+        }
+
+        // A7: Anthropic cache_control injection for anthropic/* models. Gated on
+        // `prompt_caching` (`BUZZ_AGENT_PROMPT_CACHING`) for the same reason as
+        // the native Anthropic route: these are Anthropic-dialect breakpoints on
+        // an Anthropic model, so the documented kill switch must reach them too.
+        if prompt_caching && effective_model.starts_with("anthropic/") {
+            apply_anthropic_cache_control(obj);
+        }
+    }
+}
+
+fn apply_anthropic_cache_control(body: &mut serde_json::Map<String, Value>) {
+    if let Some(messages) = body.get_mut("messages").and_then(Value::as_array_mut) {
+        // Cache the system message
+        if let Some(system_msg) = messages
+            .iter_mut()
+            .find(|m| m.get("role").and_then(Value::as_str) == Some("system"))
+        {
+            if let Some(content) = system_msg.get("content").and_then(Value::as_str) {
+                let content_str = content.to_string();
+                if let Some(obj) = system_msg.as_object_mut() {
+                    obj.insert(
+                        "content".into(),
+                        json!([{
+                            "type": "text",
+                            "text": content_str,
+                            "cache_control": { "type": "ephemeral" }
+                        }]),
+                    );
+                }
+            }
+        }
+
+        // Cache last 2 user messages (skip image-only ones — A7 mixed-content regression)
+        let mut user_count = 0;
+        for msg in messages.iter_mut().rev() {
+            if msg.get("role").and_then(Value::as_str) != Some("user") {
+                continue;
+            }
+            // Only cache string content (plain text user messages), not array content
+            // (image batches from tool results). This prevents corrupting image-only
+            // user messages by converting them to text cache breakpoints.
+            if let Some(content) = msg.get("content").and_then(Value::as_str) {
+                let content_str = content.to_string();
+                if let Some(obj) = msg.as_object_mut() {
+                    obj.insert(
+                        "content".into(),
+                        json!([{
+                            "type": "text",
+                            "text": content_str,
+                            "cache_control": { "type": "ephemeral" }
+                        }]),
+                    );
+                }
+                user_count += 1;
+            }
+            if user_count >= 2 {
+                break;
+            }
+        }
+    }
+    // Cache the last tool definition
+    if let Some(tools) = body.get_mut("tools").and_then(Value::as_array_mut) {
+        if let Some(last_tool) = tools.last_mut() {
+            if let Some(function) = last_tool.get_mut("function").and_then(Value::as_object_mut) {
+                function.insert("cache_control".into(), json!({ "type": "ephemeral" }));
+            }
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
     use crate::config::{Config, HookServers, OpenAiApi, Provider};
     use crate::types::{HistoryItem, ToolCall, ToolResult, ToolResultContent};
+    use std::collections::VecDeque;
     use std::time::Duration;
+    use tokio::sync::Mutex;
     use tracing_subscriber::layer::SubscriberExt;
 
     fn cfg(provider: Provider) -> Config {
@@ -1597,6 +2355,7 @@ mod tests {
             max_parallel_tools: 1,
             hook_timeout: Duration::from_secs(1),
             stop_max_rejections: 0,
+            require_reply: false,
             hook_servers: HookServers::None,
             api_key: "key".into(),
             model: "model".into(),
@@ -1606,6 +2365,7 @@ mod tests {
             prefer_mesh_for_auto: false,
             hints_enabled: true,
             thinking_effort: None,
+            prompt_caching: true,
         }
     }
 
@@ -2208,7 +2968,9 @@ mod tests {
                     provider_id: "toolu_1".into(),
                     name: "dev__view_image".into(),
                     arguments: serde_json::json!({"source":"x.png"}),
+                    provider_extra: Default::default(),
                 }],
+                reasoning_details: None,
             },
             HistoryItem::ToolResult(ToolResult {
                 provider_id: "toolu_1".into(),
@@ -2257,7 +3019,9 @@ mod tests {
                     provider_id: "call_abc".into(),
                     name: "dev__shell".into(),
                     arguments: serde_json::json!({"command": "ls"}),
+                    provider_extra: Default::default(),
                 }],
+                reasoning_details: None,
             },
             HistoryItem::ToolResult(ToolResult {
                 provider_id: "call_abc".into(),
@@ -2355,7 +3119,9 @@ mod tests {
                     provider_id: "call_x".into(),
                     name: "t".into(),
                     arguments: serde_json::json!({}),
+                    provider_extra: Default::default(),
                 }],
+                reasoning_details: None,
             },
         ];
         let body = responses_body(&cfg_responses(), "system", &history, &[], "model", None);
@@ -2462,26 +3228,111 @@ mod tests {
 
     #[test]
     fn databricks_v2_routes_by_model_family() {
+        use DatabricksV2Route::{AnthropicMessages, MlflowChatCompletions, OpenAiResponses};
         for (model, route, path) in [
+            // OpenAI-shaped: the gpt family plus the GPT-5 code names.
             (
                 "databricks-gpt-5-5",
-                DatabricksV2Route::OpenAiResponses,
+                OpenAiResponses,
                 "/ai-gateway/openai/v1/responses",
             ),
+            ("gpt-4o", OpenAiResponses, "/ai-gateway/openai/v1/responses"),
+            // The intentional dashless `gpt5` spelling still routes to OpenAI.
+            ("gpt5", OpenAiResponses, "/ai-gateway/openai/v1/responses"),
+            (
+                "databricks-gpt-5-6-luna",
+                OpenAiResponses,
+                "/ai-gateway/openai/v1/responses",
+            ),
+            (
+                "databricks-gpt-5-6-sol",
+                OpenAiResponses,
+                "/ai-gateway/openai/v1/responses",
+            ),
+            (
+                "databricks-terra",
+                OpenAiResponses,
+                "/ai-gateway/openai/v1/responses",
+            ),
+            // Anthropic-shaped: the claude prefix, the family names, and the
+            // release code names — each must reach the cache-capable route even
+            // when the endpoint name omits the literal "claude".
             (
                 "databricks-claude-opus-4-7",
-                DatabricksV2Route::AnthropicMessages,
+                AnthropicMessages,
                 "/ai-gateway/anthropic/v1/messages",
             ),
             (
-                "custom-tool-model",
-                DatabricksV2Route::MlflowChatCompletions,
-                "/ai-gateway/mlflow/v1/chat/completions",
+                "goose-opus-5",
+                AnthropicMessages,
+                "/ai-gateway/anthropic/v1/messages",
             ),
-        ] {
-            let got = databricks_v2_route_for_model(model);
-            assert_eq!(got, route, "model={model}");
-            assert_eq!(databricks_v2_path(got), path, "model={model}");
+            (
+                "databricks-sonnet-5",
+                AnthropicMessages,
+                "/ai-gateway/anthropic/v1/messages",
+            ),
+            (
+                "databricks-haiku-4-5",
+                AnthropicMessages,
+                "/ai-gateway/anthropic/v1/messages",
+            ),
+            (
+                "databricks-mythos-5",
+                AnthropicMessages,
+                "/ai-gateway/anthropic/v1/messages",
+            ),
+            (
+                "databricks-fable-5",
+                AnthropicMessages,
+                "/ai-gateway/anthropic/v1/messages",
+            ),
+            // Case-insensitive.
+            (
+                "Databricks-Claude-Opus-5",
+                AnthropicMessages,
+                "/ai-gateway/anthropic/v1/messages",
+            ),
+            // Unrecognised names still fall through to the MLflow chat route.
+            (
+                "custom-tool-model",
+                MlflowChatCompletions,
+                "/ai-gateway/mlflow/v1/chat/completions",
+            ),
+            (
+                "databricks-gemini-3-pro",
+                MlflowChatCompletions,
+                "/ai-gateway/mlflow/v1/chat/completions",
+            ),
+            // Collision guard: short code names must match only as whole
+            // segments, never as substrings of an unrelated custom alias.
+            // Each of these embeds a marker (`sol`, `terra`, `opus`) mid-word
+            // and must stay on the MLflow fallback, not adopt a wire its
+            // backend can't parse.
+            (
+                "consolidated-llama",
+                MlflowChatCompletions,
+                "/ai-gateway/mlflow/v1/chat/completions",
+            ),
+            (
+                "terraform-coder",
+                MlflowChatCompletions,
+                "/ai-gateway/mlflow/v1/chat/completions",
+            ),
+            (
+                "corpus-reranker",
+                MlflowChatCompletions,
+                "/ai-gateway/mlflow/v1/chat/completions",
+            ),
+            (
+                "octopus-model",
+                MlflowChatCompletions,
+                "/ai-gateway/mlflow/v1/chat/completions",
+            ),
+        ] {
+            let got = databricks_v2_route_for_model(model);
+            assert_eq!(got, route, "model={model}");
+            assert_eq!(databricks_v2_path(got), path, "model={model}");
         }
     }
 
@@ -2548,13 +3399,16 @@ mod tests {
                         provider_id: "toolu_a".into(),
                         name: "dev__view_image".into(),
                         arguments: serde_json::json!({"source": "a.png"}),
+                        provider_extra: Default::default(),
                     },
                     ToolCall {
                         provider_id: "toolu_b".into(),
                         name: "dev__view_image".into(),
                         arguments: serde_json::json!({"source": "b.png"}),
+                        provider_extra: Default::default(),
                     },
                 ],
+                reasoning_details: None,
             },
             HistoryItem::ToolResult(ToolResult {
                 provider_id: "toolu_a".into(),
@@ -2604,6 +3458,101 @@ mod tests {
         assert_eq!(imgs[1]["image_url"]["url"], "data:image/png;base64,bbb");
     }
 
+    // ---- prompt caching (cache_control) body-shape tests ----
+
+    #[test]
+    fn anthropic_body_stamps_cache_control_when_enabled() {
+        let body = anthropic_body(
+            &cfg(Provider::DatabricksV2),
+            "sys",
+            &[
+                HistoryItem::User("hello".into()),
+                HistoryItem::Assistant {
+                    text: "hi".into(),
+                    tool_calls: vec![],
+                    reasoning_details: None,
+                },
+                HistoryItem::User("more".into()),
+            ],
+            &[],
+            "databricks-claude-opus-5",
+            None,
+        );
+        // Static prefix: system promoted to a structured block carrying the marker.
+        assert_eq!(body["system"][0]["type"], "text");
+        assert_eq!(body["system"][0]["text"], "sys");
+        assert_eq!(body["system"][0]["cache_control"]["type"], "ephemeral");
+        // Leapfrog: the last block of the last TWO messages is marked; earlier
+        // ones are not. Three distinct user/assistant/user turns → messages[1]
+        // and messages[2] marked, messages[0] clean.
+        let msgs = body["messages"].as_array().unwrap();
+        assert_eq!(msgs.len(), 3);
+        let tail_block = |m: &Value| m["content"].as_array().unwrap().last().unwrap().clone();
+        assert_eq!(tail_block(&msgs[2])["cache_control"]["type"], "ephemeral");
+        assert_eq!(tail_block(&msgs[1])["cache_control"]["type"], "ephemeral");
+        assert!(
+            tail_block(&msgs[0]).get("cache_control").is_none(),
+            "only the last two messages carry a breakpoint"
+        );
+    }
+
+    #[test]
+    fn anthropic_body_single_message_stamps_only_one_breakpoint() {
+        // With a single message there is no second turn to leapfrog to; the
+        // checked_sub(2) index is skipped rather than panicking.
+        let body = anthropic_body(
+            &cfg(Provider::DatabricksV2),
+            "sys",
+            &[HistoryItem::User("hello".into())],
+            &[],
+            "databricks-claude-opus-5",
+            None,
+        );
+        let msgs = body["messages"].as_array().unwrap();
+        assert_eq!(msgs.len(), 1);
+        assert_eq!(
+            msgs[0]["content"].as_array().unwrap().last().unwrap()["cache_control"]["type"],
+            "ephemeral"
+        );
+    }
+
+    #[test]
+    fn anthropic_body_no_cache_control_when_disabled() {
+        let mut c = cfg(Provider::DatabricksV2);
+        c.prompt_caching = false;
+        let body = anthropic_body(
+            &c,
+            "sys",
+            &[HistoryItem::User("hello".into())],
+            &[],
+            "databricks-claude-opus-5",
+            None,
+        );
+        // system stays a bare string; no marker anywhere.
+        assert_eq!(body["system"], "sys");
+        let last_block = &body["messages"][0]["content"][0];
+        assert!(last_block.get("cache_control").is_none());
+    }
+
+    #[test]
+    fn anthropic_body_empty_system_stays_string_even_when_caching() {
+        // An empty system prompt must not become an empty text block —
+        // Anthropic rejects those. Caching is still applied to the tail.
+        let body = anthropic_body(
+            &cfg(Provider::DatabricksV2),
+            "",
+            &[HistoryItem::User("hello".into())],
+            &[],
+            "databricks-claude-opus-5",
+            None,
+        );
+        assert_eq!(body["system"], "");
+        assert_eq!(
+            body["messages"][0]["content"][0]["cache_control"]["type"],
+            "ephemeral"
+        );
+    }
+
     // ---- ThinkingEffort body-shape tests ----
 
     #[test]
@@ -3483,6 +4432,93 @@ mod tests {
         assert_eq!(parse_anthropic(v).unwrap().input_tokens, None);
     }
 
+    /// A Gemini reply as the Databricks MLflow route actually returns it:
+    /// block-array `content`, and a `thoughtSignature` beside `function`.
+    fn gemini_choice() -> Value {
+        json!({"choices": [{"finish_reason": "tool_calls", "message": {
+            "role": "assistant",
+            "content": [
+                {"type": "reasoning", "summary": [{"type": "summary_text", "text": "weighing it"}]},
+                {"type": "text", "text": "391"}
+            ],
+            "tool_calls": [{
+                "id": "get_weather", "type": "function", "thoughtSignature": "SIG-A",
+                "function": {"name": "get_weather", "arguments": "{\"city\":\"Paris\"}"}
+            }]
+        }}]})
+    }
+
+    #[test]
+    fn parse_openai_reads_text_out_of_a_block_array() {
+        // Before this, `as_str()` on the array yielded "" and the model's answer
+        // was discarded with no error at all.
+        let r = parse_openai(gemini_choice()).unwrap();
+        assert_eq!(r.text, "391");
+        assert_eq!(r.reasoning, "weighing it");
+    }
+
+    #[test]
+    fn parse_openai_still_reads_a_plain_string_content() {
+        let v = json!({"choices": [{"finish_reason": "stop", "message": {
+            "role": "assistant", "content": "plain"}}]});
+        let r = parse_openai(v).unwrap();
+        assert_eq!(r.text, "plain");
+        assert_eq!(r.reasoning, "");
+    }
+
+    #[test]
+    fn parse_openai_keeps_unmodelled_tool_call_fields() {
+        let r = parse_openai(gemini_choice()).unwrap();
+        let extra = &r.tool_calls[0].provider_extra;
+        assert_eq!(extra.get("thoughtSignature"), Some(&json!("SIG-A")));
+        // `id`/`type`/`function` are modelled, so they must not be duplicated
+        // into the passthrough — they would be re-emitted twice.
+        assert!(!extra.contains_key("id"));
+        assert!(!extra.contains_key("type"));
+        assert!(!extra.contains_key("function"));
+    }
+
+    #[test]
+    fn openai_body_replays_the_signature_beside_function_not_inside_it() {
+        // Position is what the gateway checks: nested inside `function{}` it is
+        // rejected with the same 400 as a missing signature.
+        let r = parse_openai(gemini_choice()).unwrap();
+        let history = vec![HistoryItem::Assistant {
+            text: r.text.clone(),
+            tool_calls: r.tool_calls.clone(),
+            reasoning_details: None,
+        }];
+        let body = openai_body(
+            &cfg(Provider::DatabricksV2),
+            "sys",
+            &history,
+            &[],
+            "databricks-gemini-3-6-flash",
+            None,
+        );
+        let call = &body["messages"][1]["tool_calls"][0];
+        assert_eq!(call["thoughtSignature"], json!("SIG-A"));
+        assert!(call["function"].get("thoughtSignature").is_none());
+        assert_eq!(call["function"]["name"], json!("get_weather"));
+    }
+
+    #[test]
+    fn parse_openai_makes_duplicate_tool_call_ids_unique() {
+        // Gemini returns the function name as the id, so parallel calls to one
+        // function collide and their results become indistinguishable.
+        let v = json!({"choices": [{"finish_reason": "tool_calls", "message": {
+        "role": "assistant", "content": "",
+        "tool_calls": [
+            {"id": "get_weather", "type": "function",
+             "function": {"name": "get_weather", "arguments": "{\"city\":\"Paris\"}"}},
+            {"id": "get_weather", "type": "function",
+             "function": {"name": "get_weather", "arguments": "{\"city\":\"Rome\"}"}}
+        ]}}]});
+        let r = parse_openai(v).unwrap();
+        assert_eq!(r.tool_calls[0].provider_id, "get_weather");
+        assert_eq!(r.tool_calls[1].provider_id, "get_weather-2");
+    }
+
     #[test]
     fn parse_openai_uses_prompt_tokens() {
         let v = serde_json::json!({
@@ -3493,20 +4529,34 @@ mod tests {
     }
 
     #[test]
-    fn parse_openai_databricks_sums_cache_fields() {
-        // Databricks uses the OpenAI chat wire format (prompt_tokens) but also
-        // reports Anthropic-style cache fields; the inclusive total sums them.
+    fn parse_openai_databricks_prompt_tokens_already_inclusive() {
+        // Databricks' MLflow route uses the OpenAI chat wire format
+        // (prompt_tokens) but ALSO reports the flat Anthropic-style
+        // cache_read_input_tokens. prompt_tokens is already inclusive of that
+        // slice, so the total is prompt_tokens alone — summing double-counts.
+        // Values are the live databricks-glm-5-2 response (2026-07-28), where
+        // prompt_tokens + completion_tokens == total_tokens proves inclusivity.
         let v = serde_json::json!({
             "choices": [{"finish_reason": "stop", "message": {"content": "hi"}}],
             "usage": {
-                "prompt_tokens": 200,
-                "completion_tokens": 4,
-                "total_tokens": 204,
-                "cache_read_input_tokens": 800,
-                "cache_creation_input_tokens": 0
+                "prompt_tokens": 13320,
+                "completion_tokens": 30,
+                "total_tokens": 13350,
+                "cache_read_input_tokens": 13312,
+                "prompt_tokens_details": {"cached_tokens": 13312}
             }
         });
-        assert_eq!(parse_openai(v).unwrap().input_tokens, Some(1000));
+        let r = parse_openai(v).unwrap();
+        assert_eq!(
+            r.input_tokens,
+            Some(13320),
+            "prompt_tokens is the inclusive total"
+        );
+        assert_eq!(r.cached_input_tokens, Some(13312));
+        assert!(
+            r.cached_input_tokens.unwrap() <= r.input_tokens.unwrap(),
+            "the cached slice is a subset of the input total"
+        );
     }
 
     #[test]
@@ -3517,6 +4567,194 @@ mod tests {
         assert_eq!(parse_openai(v).unwrap().input_tokens, None);
     }
 
+    // ── total_tokens parsing ───────────────────────────────────────────────
+
+    #[test]
+    fn parse_openai_chat_total_tokens_present_is_read() {
+        // Chat Completions: `usage.total_tokens` is a genuine provider total.
+        let v = serde_json::json!({
+            "choices": [{"finish_reason": "stop", "message": {"content": "ok"}}],
+            "usage": {"prompt_tokens": 100, "completion_tokens": 25, "total_tokens": 125}
+        });
+        let r = parse_openai(v).unwrap();
+        assert_eq!(r.total_tokens, Some(125));
+        assert_eq!(r.input_tokens, Some(100));
+        assert_eq!(r.output_tokens, Some(25));
+    }
+
+    #[test]
+    fn parse_openai_chat_total_tokens_absent_is_none() {
+        // Chat Completions without `total_tokens` → None, not a derived sum.
+        let v = serde_json::json!({
+            "choices": [{"finish_reason": "stop", "message": {"content": "ok"}}],
+            "usage": {"prompt_tokens": 100, "completion_tokens": 25}
+        });
+        let r = parse_openai(v).unwrap();
+        assert_eq!(r.total_tokens, None);
+    }
+
+    #[test]
+    fn parse_responses_total_tokens_present_is_read() {
+        // Responses API: `usage.total_tokens` is a genuine provider total.
+        let v = serde_json::json!({
+            "output": [{"type": "message", "content": [{"type": "output_text", "text": "hi"}]}],
+            "status": "completed",
+            "usage": {"input_tokens": 80, "output_tokens": 20, "total_tokens": 100}
+        });
+        let r = parse_responses(v).unwrap();
+        assert_eq!(r.total_tokens, Some(100));
+        assert_eq!(r.input_tokens, Some(80));
+        assert_eq!(r.output_tokens, Some(20));
+    }
+
+    #[test]
+    fn parse_responses_total_tokens_absent_is_none() {
+        // Responses API without `total_tokens` → None.
+        let v = serde_json::json!({
+            "output": [{"type": "message", "content": [{"type": "output_text", "text": "hi"}]}],
+            "status": "completed",
+            "usage": {"input_tokens": 80, "output_tokens": 20}
+        });
+        let r = parse_responses(v).unwrap();
+        assert_eq!(r.total_tokens, None);
+    }
+
+    #[test]
+    fn parse_anthropic_total_tokens_always_none() {
+        // Anthropic reports only category counts; NIP-AM forbids deriving a total.
+        // total_tokens must always be None regardless of what the response contains —
+        // including if a future Anthropic API version unexpectedly adds total_tokens.
+        let v = serde_json::json!({
+            "content": [{"type": "text", "text": "hi"}],
+            "stop_reason": "end_turn",
+            "usage": {
+                "input_tokens": 100,
+                "cache_read_input_tokens": 50,
+                "cache_creation_input_tokens": 0,
+                "output_tokens": 30,
+                // Unexpected field: parse_anthropic must ignore this and return None.
+                "total_tokens": 180
+            }
+        });
+        let r = parse_anthropic(v).unwrap();
+        assert!(
+            r.total_tokens.is_none(),
+            "Anthropic must never supply a total_tokens value"
+        );
+        // Verify other fields still parse correctly.
+        assert_eq!(r.input_tokens, Some(150)); // inclusive sum with cache
+        assert_eq!(r.output_tokens, Some(30));
+    }
+
+    #[test]
+    fn parse_openai_reads_nested_cached_tokens() {
+        // The shape vanilla OpenAI actually returns, captured from a live
+        // /chat/completions probe on gpt-5.6-luna: `prompt_tokens` is already
+        // inclusive and the cache split is nested one level down. Reading only
+        // flat keys left the discount unclaimed while the total looked correct,
+        // which is why this went unnoticed.
+        let v = serde_json::json!({
+            "choices": [{"finish_reason": "stop", "message": {"content": "OK"}}],
+            "usage": {
+                "prompt_tokens": 5229,
+                "completion_tokens": 4,
+                "total_tokens": 5233,
+                "prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 5226,
+                                          "cache_write_tokens": 0}
+            }
+        });
+        let r = parse_openai(v).unwrap();
+        assert_eq!(r.input_tokens, Some(5229), "total must stay inclusive");
+        assert_eq!(r.cached_input_tokens, Some(5226));
+    }
+
+    #[test]
+    fn parse_openai_cache_write_round_reports_zero_cached() {
+        // First request of a cold prefix: the provider writes the cache and
+        // serves nothing from it. `Some(0)` not `None` — the split was reported,
+        // it was simply zero, and a consumer must be able to tell the two apart.
+        let v = serde_json::json!({
+            "choices": [{"finish_reason": "stop", "message": {"content": "OK"}}],
+            "usage": {
+                "prompt_tokens": 5229,
+                "completion_tokens": 4,
+                "prompt_tokens_details": {"cached_tokens": 0, "cache_write_tokens": 5226}
+            }
+        });
+        assert_eq!(parse_openai(v).unwrap().cached_input_tokens, Some(0));
+    }
+
+    #[test]
+    fn parse_openai_no_cache_detail_is_none() {
+        let v = serde_json::json!({
+            "choices": [{"finish_reason": "stop", "message": {"content": "hi"}}],
+            "usage": {"prompt_tokens": 123, "completion_tokens": 4}
+        });
+        assert_eq!(parse_openai(v).unwrap().cached_input_tokens, None);
+    }
+
+    #[test]
+    fn parse_openai_prefers_flat_anthropic_spelling_over_nested() {
+        // Databricks reports both shapes for the same quantity. Take one, never
+        // the sum, or the cached slice double-counts. cache_read (800) is a
+        // subset of the inclusive prompt_tokens (1000), as it must be.
+        let v = serde_json::json!({
+            "choices": [{"finish_reason": "stop", "message": {"content": "hi"}}],
+            "usage": {
+                "prompt_tokens": 1000,
+                "completion_tokens": 4,
+                "cache_read_input_tokens": 800,
+                "prompt_tokens_details": {"cached_tokens": 800}
+            }
+        });
+        let r = parse_openai(v).unwrap();
+        assert_eq!(r.input_tokens, Some(1000));
+        assert_eq!(r.cached_input_tokens, Some(800));
+        assert!(r.cached_input_tokens.unwrap() <= r.input_tokens.unwrap());
+    }
+
+    #[test]
+    fn parse_anthropic_reports_cache_read_as_cached() {
+        // Anthropic's `input_tokens` EXCLUDES cached, so the inclusive total is
+        // a sum -- but the cached slice must still be a subset of that total.
+        let v = serde_json::json!({
+            "stop_reason": "end_turn",
+            "content": [{"type": "text", "text": "hi"}],
+            "usage": {
+                "input_tokens": 100,
+                "output_tokens": 7,
+                "cache_read_input_tokens": 900,
+                "cache_creation_input_tokens": 50
+            }
+        });
+        let r = parse_anthropic(v).unwrap();
+        assert_eq!(r.input_tokens, Some(1050));
+        assert_eq!(r.cached_input_tokens, Some(900));
+        assert!(r.cached_input_tokens.unwrap() <= r.input_tokens.unwrap());
+    }
+
+    #[test]
+    fn parse_responses_reads_nested_cached_tokens() {
+        // The Responses API nests the same figure under a different key than
+        // /chat/completions does.
+        let v = serde_json::json!({
+            "status": "completed",
+            "output": [{
+                "type": "message",
+                "role": "assistant",
+                "content": [{"type": "output_text", "text": "hi"}]
+            }],
+            "usage": {
+                "input_tokens": 4000,
+                "output_tokens": 9,
+                "input_tokens_details": {"cached_tokens": 3584}
+            }
+        });
+        let r = parse_responses(v).unwrap();
+        assert_eq!(r.input_tokens, Some(4000));
+        assert_eq!(r.cached_input_tokens, Some(3584));
+    }
+
     #[test]
     fn parse_responses_uses_input_tokens() {
         let v = serde_json::json!({
@@ -3843,4 +5081,1476 @@ mod tests {
         });
         assert_eq!(parse_responses(v).unwrap().output_tokens, None);
     }
+
+    // ---- A3: OpenRouter body-shape tests ----
+
+    fn tools_vec() -> Vec<ToolDef> {
+        vec![ToolDef {
+            name: "dev__shell".into(),
+            description: "run a shell command".into(),
+            input_schema: serde_json::json!({
+                "type": "object",
+                "properties": {"command": {"type": "string"}},
+            }),
+        }]
+    }
+
+    #[test]
+    fn openrouter_body_tools_with_effort() {
+        let mut c = cfg(Provider::OpenRouter);
+        c.thinking_effort = Some(ThinkingEffort::High);
+        let mut body = openai_body(
+            &c,
+            "system",
+            &[HistoryItem::User("hi".into())],
+            &tools_vec(),
+            "anthropic/claude-opus-4-7",
+            None,
+        );
+        apply_openrouter_mutations(
+            &mut body,
+            c.thinking_effort,
+            "anthropic/claude-opus-4-7",
+            true,
+        );
+        assert_eq!(body["reasoning"]["effort"], "high");
+        // `openai_body` is always called with `effort=None` on the OpenRouter
+        // path (line 151): OpenRouter uses its own `reasoning` object, not the
+        // OpenAI-style `reasoning_effort` field. Verify the field is structurally
+        // absent — not merely removed by a no-op cleanup.
+        assert!(
+            body.get("reasoning_effort").is_none(),
+            "reasoning_effort must never appear on the OpenRouter body path: \
+             openai_body is called with effort=None, so the field is never emitted"
+        );
+        assert!(
+            body.get("provider").is_none(),
+            "provider.require_parameters hard-404s models that do not advertise \
+             every parameter we send"
+        );
+        assert!(!body["tools"].as_array().unwrap().is_empty());
+        assert_eq!(
+            body["max_tokens"], 1024,
+            "token limit must carry openai_body's value under OpenRouter's spelling"
+        );
+        assert!(
+            body.get("max_completion_tokens").is_none(),
+            "max_completion_tokens is the OpenAI-native spelling; OpenRouter reads max_tokens"
+        );
+    }
+
+    #[test]
+    fn openrouter_body_tools_no_effort() {
+        let c = cfg(Provider::OpenRouter);
+        let mut body = openai_body(
+            &c,
+            "system",
+            &[HistoryItem::User("hi".into())],
+            &tools_vec(),
+            "anthropic/claude-opus-4-7",
+            None,
+        );
+        apply_openrouter_mutations(&mut body, None, "anthropic/claude-opus-4-7", true);
+        assert!(
+            body.get("reasoning").is_none(),
+            "reasoning must be absent when effort is None"
+        );
+        assert!(
+            body.get("reasoning_effort").is_none(),
+            "reasoning_effort must never appear on the OpenRouter body path"
+        );
+        assert!(
+            body.get("provider").is_none(),
+            "tools alone must not add a provider routing filter"
+        );
+    }
+
+    #[test]
+    fn openrouter_body_empty_tools_with_effort() {
+        let mut c = cfg(Provider::OpenRouter);
+        c.thinking_effort = Some(ThinkingEffort::Medium);
+        let mut body = openai_body(
+            &c,
+            "system",
+            &[HistoryItem::User("hi".into())],
+            &[],
+            "anthropic/claude-opus-4-7",
+            None,
+        );
+        apply_openrouter_mutations(
+            &mut body,
+            c.thinking_effort,
+            "anthropic/claude-opus-4-7",
+            true,
+        );
+        assert_eq!(body["reasoning"]["effort"], "medium");
+        assert!(
+            body.get("provider").is_none(),
+            "83 of 274 tools-capable models do not advertise `reasoning`; filtering on \
+             it would 404 them instead of answering without reasoning"
+        );
+    }
+
+    #[test]
+    fn openrouter_body_empty_tools_no_effort() {
+        let c = cfg(Provider::OpenRouter);
+        let mut body = openai_body(
+            &c,
+            "system",
+            &[HistoryItem::User("hi".into())],
+            &[],
+            "anthropic/claude-opus-4-7",
+            None,
+        );
+        apply_openrouter_mutations(&mut body, None, "anthropic/claude-opus-4-7", true);
+        assert!(body.get("reasoning").is_none());
+        assert!(
+            body.get("provider").is_none(),
+            "no body shape adds a provider routing filter"
+        );
+    }
+
+    /// `BUZZ_AGENT_PROMPT_CACHING=0` must reach the OpenRouter `anthropic/*`
+    /// route too, not just the native Anthropic Messages routes. The switch and
+    /// this route landed in separate changes, so nothing but this test stops the
+    /// gate from being dropped and the kill switch silently becoming a no-op on
+    /// a route that emits Anthropic-dialect breakpoints.
+    #[test]
+    fn openrouter_body_caching_disabled_emits_no_cache_control() {
+        let c = cfg(Provider::OpenRouter);
+        let mut body = openai_body(
+            &c,
+            "system",
+            &[HistoryItem::User("hi".into())],
+            &tools_vec(),
+            "anthropic/claude-opus-4-7",
+            None,
+        );
+        apply_openrouter_mutations(&mut body, None, "anthropic/claude-opus-4-7", false);
+        assert!(
+            !body.to_string().contains("cache_control"),
+            "BUZZ_AGENT_PROMPT_CACHING=0 must suppress every breakpoint: {body}"
+        );
+        // The switch is scoped to caching — the routing-contract mutations that
+        // make the request serveable at all must still be applied.
+        assert_eq!(
+            body.get("max_tokens").and_then(Value::as_u64),
+            Some(u64::from(c.max_output_tokens)),
+            "the max_tokens rename is not part of the caching gate"
+        );
+    }
+
+    /// The paired positive case: with caching on, the same body does carry
+    /// breakpoints. Without this twin, a mutation that hard-disabled caching
+    /// outright would still leave the test above green.
+    #[test]
+    fn openrouter_body_caching_enabled_emits_cache_control() {
+        let c = cfg(Provider::OpenRouter);
+        let mut body = openai_body(
+            &c,
+            "system",
+            &[HistoryItem::User("hi".into())],
+            &tools_vec(),
+            "anthropic/claude-opus-4-7",
+            None,
+        );
+        apply_openrouter_mutations(&mut body, None, "anthropic/claude-opus-4-7", true);
+        assert!(
+            body.to_string().contains("cache_control"),
+            "caching on must still emit breakpoints: {body}"
+        );
+    }
+
+    /// The rename moves an existing value; it never invents a token limit for a
+    /// body that did not carry one.
+    #[test]
+    fn openrouter_body_without_token_limit_gains_none() {
+        let mut body = json!({ "model": "vendor/model", "messages": [] });
+        apply_openrouter_mutations(&mut body, None, "vendor/model", true);
+        assert!(body.get("max_tokens").is_none());
+        assert!(body.get("max_completion_tokens").is_none());
+    }
+
+    #[test]
+    fn openrouter_summary_carries_neither_reasoning_nor_provider() {
+        let body = openrouter_summary_body(
+            "anthropic/claude-opus-4-7",
+            "summarize",
+            "text to summarize",
+            1024,
+        );
+        assert_eq!(body["model"], "anthropic/claude-opus-4-7");
+        assert_eq!(body["messages"][0]["role"], "system");
+        assert_eq!(body["messages"][1]["content"], "text to summarize");
+        assert_eq!(body["max_tokens"], 1024);
+        assert!(
+            body.get("max_completion_tokens").is_none(),
+            "summary body must use OpenRouter's token-limit spelling"
+        );
+        assert!(
+            body.get("reasoning").is_none(),
+            "summary body must not carry reasoning"
+        );
+        assert!(
+            body.get("provider").is_none(),
+            "summary body must not carry provider"
+        );
+    }
+
+    /// The token-limit rename belongs to `apply_openrouter_mutations`, not to
+    /// `openai_body` — which OpenAI and Databricks also use, and where
+    /// `max_completion_tokens` is the correct spelling.
+    #[test]
+    fn openai_body_keeps_max_completion_tokens_when_unmutated() {
+        let body = openai_body(
+            &cfg(Provider::OpenAi),
+            "system",
+            &[HistoryItem::User("hi".into())],
+            &[],
+            "model",
+            None,
+        );
+        assert_eq!(body["max_completion_tokens"], 1024);
+        assert!(body.get("max_tokens").is_none());
+    }
+
+    // ---- A5: error-inside-200 ----
+
+    #[test]
+    fn parse_openai_error_inside_200_returns_error() {
+        let v = serde_json::json!({
+            "choices": [{
+                "finish_reason": "error",
+                "error": {
+                    "code": 503,
+                    "message": "No endpoints found that support tool use"
+                }
+            }]
+        });
+        let err = parse_openai(v).unwrap_err();
+        match &err {
+            AgentError::Llm(s) => {
+                assert!(s.contains("provider error (503)"), "got: {s}");
+                assert!(s.contains("No endpoints found"), "got: {s}");
+            }
+            _ => panic!("expected AgentError::Llm, got: {err:?}"),
+        }
+    }
+
+    #[test]
+    fn parse_openai_error_inside_200_accepts_string_code() {
+        let v = serde_json::json!({
+            "choices": [{
+                "finish_reason": "error",
+                "error": {
+                    "code": "insufficient_quota",
+                    "message": "quota exceeded"
+                }
+            }]
+        });
+        let err = parse_openai(v).unwrap_err();
+        match &err {
+            AgentError::Llm(s) => assert!(
+                s.contains("provider error (insufficient_quota)"),
+                "got: {s}"
+            ),
+            _ => panic!("expected AgentError::Llm, got: {err:?}"),
+        }
+    }
+
+    #[test]
+    fn parse_openai_error_inside_200_surfaces_error_type() {
+        let v = serde_json::json!({
+            "choices": [{
+                "finish_reason": "error",
+                "error": {
+                    "code": 429,
+                    "message": "Rate limit exceeded",
+                    "metadata": { "error_type": "rate_limit_exceeded" }
+                }
+            }]
+        });
+        let err = parse_openai(v).unwrap_err();
+        match &err {
+            AgentError::Llm(s) => {
+                assert!(s.contains("429"), "got: {s}");
+                assert!(s.contains("rate_limit_exceeded"), "got: {s}");
+            }
+            _ => panic!("expected AgentError::Llm, got: {err:?}"),
+        }
+    }
+
+    #[test]
+    fn parse_openai_normal_stop_not_affected_by_error_check() {
+        let v = serde_json::json!({
+            "choices": [{"finish_reason": "stop", "message": {"content": "hello"}}],
+            "usage": {"prompt_tokens": 10, "completion_tokens": 5}
+        });
+        let r = parse_openai(v).unwrap();
+        assert_eq!(r.text, "hello");
+        assert_eq!(r.stop, ProviderStop::EndTurn);
+    }
+
+    #[test]
+    fn parse_openai_tool_calls_not_affected_by_error_check() {
+        let v = serde_json::json!({
+            "choices": [{
+                "finish_reason": "tool_calls",
+                "message": {
+                    "content": "",
+                    "tool_calls": [{
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {"name": "test", "arguments": "{}"}
+                    }]
+                }
+            }]
+        });
+        let r = parse_openai(v).unwrap();
+        assert_eq!(r.stop, ProviderStop::ToolUse);
+        assert_eq!(r.tool_calls.len(), 1);
+    }
+
+    // ---- A6: OpenRouter retry classification ----
+
+    #[test]
+    fn classify_429_rate_limit_body_retry_after_is_ignored() {
+        // M1: no documented body-level retry field, so a `retry_after` key
+        // inside `error.metadata` is inert — only the HTTP header (passed
+        // separately) can produce a delay.
+        let body =
+            r#"{"error":{"metadata":{"error_type":"rate_limit_exceeded","retry_after":2.5}}}"#;
+        match classify_openrouter_error(429, body, None) {
+            OpenRouterErrorClass::Retryable(None) => {}
+            other => panic!("expected Retryable(None), got: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn classify_429_rate_limit_without_retry_after() {
+        let body = r#"{"error":{"metadata":{"error_type":"rate_limit_exceeded"}}}"#;
+        match classify_openrouter_error(429, body, None) {
+            OpenRouterErrorClass::Retryable(None) => {}
+            other => panic!("expected Retryable(None), got: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn classify_429_prefers_http_header_over_body() {
+        // Body-level retry hints are no longer parsed (M1: undocumented field);
+        // the HTTP header is the only source, and it's honored when present.
+        let body = r#"{"error":{"metadata":{"error_type":"rate_limit_exceeded"}}}"#;
+        let header = Some(Duration::from_secs(3));
+        match classify_openrouter_error(429, body, header) {
+            OpenRouterErrorClass::Retryable(Some(d)) => {
+                assert_eq!(d, Duration::from_secs(3), "HTTP header must be honored");
+            }
+            other => panic!("expected Retryable with header delay, got: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn classify_502_provider_unavailable() {
+        let body = r#"{"error":{"metadata":{"error_type":"provider_unavailable"}}}"#;
+        match classify_openrouter_error(502, body, None) {
+            OpenRouterErrorClass::Retryable(None) => {}
+            other => panic!("expected Retryable(None) for 502, got: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn classify_503_provider_overloaded_with_retry_after() {
+        // No documented body-level retry field (M1); the header is the only
+        // source `classify_openrouter_error` consults.
+        let body = r#"{"error":{"metadata":{"error_type":"provider_overloaded"}}}"#;
+        let header = Some(Duration::from_secs(5));
+        match classify_openrouter_error(503, body, header) {
+            OpenRouterErrorClass::Retryable(Some(d)) => {
+                assert_eq!(d, Duration::from_secs(5));
+            }
+            other => panic!("expected Retryable with delay, got: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn classify_503_untyped_is_unknown() {
+        let body = r#"{"error":{"message":"No endpoints found"}}"#;
+        match classify_openrouter_error(503, body, None) {
+            OpenRouterErrorClass::Unknown => {}
+            other => panic!("expected Unknown for untyped 503, got: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn classify_500_untyped_is_unknown() {
+        match classify_openrouter_error(500, r#"{"error":{"message":"internal"}}"#, None) {
+            OpenRouterErrorClass::Unknown => {}
+            other => panic!("expected Unknown for 500, got: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn parse_retry_after_header_valid() {
+        let mut headers = reqwest::header::HeaderMap::new();
+        headers.insert(reqwest::header::RETRY_AFTER, "5".parse().unwrap());
+        assert_eq!(
+            parse_retry_after_header(&headers),
+            Some(Duration::from_secs(5))
+        );
+    }
+
+    #[test]
+    fn parse_retry_after_header_zero_rejected() {
+        let mut headers = reqwest::header::HeaderMap::new();
+        headers.insert(reqwest::header::RETRY_AFTER, "0".parse().unwrap());
+        assert_eq!(parse_retry_after_header(&headers), None);
+    }
+
+    #[test]
+    fn parse_retry_after_header_over_cap_clamped() {
+        let mut headers = reqwest::header::HeaderMap::new();
+        headers.insert(reqwest::header::RETRY_AFTER, "3601".parse().unwrap());
+        assert_eq!(
+            parse_retry_after_header(&headers),
+            Some(Duration::from_secs(RETRY_AFTER_CAP_SECS)),
+            "over-cap hints clamp to the ceiling rather than being dropped"
+        );
+    }
+
+    #[test]
+    fn parse_retry_after_header_at_cap_unclamped() {
+        let mut headers = reqwest::header::HeaderMap::new();
+        headers.insert(
+            reqwest::header::RETRY_AFTER,
+            RETRY_AFTER_CAP_SECS.to_string().parse().unwrap(),
+        );
+        assert_eq!(
+            parse_retry_after_header(&headers),
+            Some(Duration::from_secs(RETRY_AFTER_CAP_SECS))
+        );
+    }
+
+    #[test]
+    fn parse_retry_after_header_missing() {
+        let headers = reqwest::header::HeaderMap::new();
+        assert_eq!(parse_retry_after_header(&headers), None);
+    }
+
+    #[test]
+    fn parse_retry_after_header_non_numeric_ignored() {
+        let mut headers = reqwest::header::HeaderMap::new();
+        headers.insert(
+            reqwest::header::RETRY_AFTER,
+            "Wed, 21 Oct 2026 07:28:00 GMT".parse().unwrap(),
+        );
+        assert_eq!(parse_retry_after_header(&headers), None);
+    }
+
+    // ---- A7: Anthropic cache_control with mixed content ----
+
+    #[test]
+    fn anthropic_cache_control_mixed_text_tool_image_history() {
+        let history = vec![
+            HistoryItem::User("first question".into()),
+            HistoryItem::Assistant {
+                text: String::new(),
+                tool_calls: vec![ToolCall {
+                    provider_id: "toolu_1".into(),
+                    name: "dev__view_image".into(),
+                    arguments: serde_json::json!({"source": "x.png"}),
+                    provider_extra: Default::default(),
+                }],
+                reasoning_details: None,
+            },
+            HistoryItem::ToolResult(ToolResult {
+                provider_id: "toolu_1".into(),
+                content: vec![
+                    ToolResultContent::Text("10×10 image".into()),
+                    ToolResultContent::Image {
+                        data: "aW1n".into(),
+                        mime_type: "image/png".into(),
+                    },
+                ],
+                is_error: false,
+            }),
+            HistoryItem::User("second question about the image".into()),
+            HistoryItem::User("third question".into()),
+        ];
+        let mut body = openai_body(
+            &cfg(Provider::OpenRouter),
+            "system",
+            &history,
+            &tools_vec(),
+            "anthropic/claude-opus-4-7",
+            None,
+        );
+        apply_openrouter_mutations(&mut body, None, "anthropic/claude-opus-4-7", true);
+        let messages = body["messages"].as_array().unwrap();
+
+        // System message should have cache_control
+        let system = &messages[0];
+        assert_eq!(system["content"][0]["cache_control"]["type"], "ephemeral");
+
+        // Image-batch user messages (containing image_url blocks) must NOT have cache_control
+        let image_user_msgs: Vec<_> = messages
+            .iter()
+            .filter(|m| {
+                m.get("role").and_then(Value::as_str) == Some("user")
+                    && m.get("content")
+                        .and_then(Value::as_array)
+                        .map(|a| {
+                            a.iter()
+                                .any(|b| b.get("type").and_then(Value::as_str) == Some("image_url"))
+                        })
+                        .unwrap_or(false)
+            })
+            .collect();
+        assert!(
+            !image_user_msgs.is_empty(),
+            "should have image user messages"
+        );
+        for img_msg in &image_user_msgs {
+            let content = img_msg["content"].as_array().unwrap();
+            for block in content {
+                assert!(
+                    block.get("cache_control").is_none(),
+                    "image-only user message must not receive cache_control"
+                );
+            }
+        }
+
+        // Exactly 2 text user messages should have cache_control (skipping image-only ones)
+        let cached_text_count = messages
+            .iter()
+            .filter(|m| {
+                m.get("role").and_then(Value::as_str) == Some("user")
+                    && m.get("content")
+                        .and_then(Value::as_array)
+                        .map(|a| {
+                            a.iter().any(|b| {
+                                b.get("type").and_then(Value::as_str) == Some("text")
+                                    && b.get("cache_control").is_some()
+                            })
+                        })
+                        .unwrap_or(false)
+            })
+            .count();
+        assert_eq!(
+            cached_text_count, 2,
+            "exactly 2 text user messages should have cache_control"
+        );
+
+        // Last tool def should have cache_control
+        let tools = body["tools"].as_array().unwrap();
+        let last_tool = tools.last().unwrap();
+        assert_eq!(last_tool["function"]["cache_control"]["type"], "ephemeral");
+    }
+
+    #[test]
+    fn anthropic_cache_control_image_only_user_does_not_consume_slot() {
+        // An image-only user message between two text user messages must not
+        // consume a cache breakpoint slot — both text messages should get cached.
+        let history = vec![
+            HistoryItem::User("text message one".into()),
+            HistoryItem::Assistant {
+                text: String::new(),
+                tool_calls: vec![ToolCall {
+                    provider_id: "toolu_1".into(),
+                    name: "dev__view_image".into(),
+                    arguments: serde_json::json!({"source": "x.png"}),
+                    provider_extra: Default::default(),
+                }],
+                reasoning_details: None,
+            },
+            HistoryItem::ToolResult(ToolResult {
+                provider_id: "toolu_1".into(),
+                content: vec![ToolResultContent::Image {
+                    data: "aW1n".into(),
+                    mime_type: "image/png".into(),
+                }],
+                is_error: false,
+            }),
+            HistoryItem::User("text message two".into()),
+            HistoryItem::User("text message three".into()),
+        ];
+        let mut body = openai_body(
+            &cfg(Provider::OpenRouter),
+            "system",
+            &history,
+            &[],
+            "anthropic/claude-opus-4-7",
+            None,
+        );
+        apply_openrouter_mutations(&mut body, None, "anthropic/claude-opus-4-7", true);
+        let messages = body["messages"].as_array().unwrap();
+
+        // Count text user messages that got cache_control
+        let cached_text_count = messages
+            .iter()
+            .filter(|m| {
+                m.get("role").and_then(Value::as_str) == Some("user")
+                    && m.get("content")
+                        .and_then(Value::as_array)
+                        .map(|a| a.iter().any(|b| b.get("cache_control").is_some()))
+                        .unwrap_or(false)
+            })
+            .count();
+        assert_eq!(
+            cached_text_count, 2,
+            "image-only user messages must not consume a cache breakpoint slot"
+        );
+    }
+
+    // ---- A9: reasoning_details round-trip ----
+
+    #[test]
+    fn parse_openai_with_reasoning_details_captures_array() {
+        let details = serde_json::json!([
+            {"type": "thinking", "content": "Let me consider..."},
+            {"type": "thinking", "content": "The answer is 42."}
+        ]);
+        let v = serde_json::json!({
+            "choices": [{
+                "finish_reason": "tool_calls",
+                "message": {
+                    "content": "",
+                    "reasoning_details": details,
+                    "tool_calls": [{
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {"name": "test", "arguments": "{}"}
+                    }]
+                }
+            }],
+            "usage": {"prompt_tokens": 10, "completion_tokens": 5}
+        });
+        let r = parse_openai_with_reasoning_details(v).unwrap();
+        assert_eq!(r.reasoning_details, Some(details));
+    }
+
+    #[test]
+    fn parse_openai_with_reasoning_details_none_when_absent() {
+        let v = serde_json::json!({
+            "choices": [{
+                "finish_reason": "stop",
+                "message": {"content": "hello"}
+            }]
+        });
+        let r = parse_openai_with_reasoning_details(v).unwrap();
+        assert!(
+            r.reasoning_details.is_none(),
+            "reasoning_details must be None when not in response"
+        );
+    }
+
+    /// M2: a malformed `reasoning_details` shape (null or a bare object,
+    /// rather than the documented array) must be omitted at the parse
+    /// boundary, not stored and later replayed into the next request.
+    #[test]
+    fn parse_openai_with_reasoning_details_omits_non_array_shapes() {
+        let null_shape = serde_json::json!({
+            "choices": [{
+                "finish_reason": "stop",
+                "message": {"content": "hello", "reasoning_details": null}
+            }]
+        });
+        let r = parse_openai_with_reasoning_details(null_shape).unwrap();
+        assert!(
+            r.reasoning_details.is_none(),
+            "null reasoning_details must be omitted, not stored as Some(Null)"
+        );
+
+        let object_shape = serde_json::json!({
+            "choices": [{
+                "finish_reason": "stop",
+                "message": {
+                    "content": "hello",
+                    "reasoning_details": {"type": "thinking", "content": "not an array"}
+                }
+            }]
+        });
+        let r = parse_openai_with_reasoning_details(object_shape).unwrap();
+        assert!(
+            r.reasoning_details.is_none(),
+            "a bare-object reasoning_details must be omitted, not stored as Some(object)"
+        );
+    }
+
+    #[test]
+    fn parse_openai_plain_never_captures_reasoning_details() {
+        let v = serde_json::json!({
+            "choices": [{
+                "finish_reason": "stop",
+                "message": {
+                    "content": "hello",
+                    "reasoning_details": [{"type": "thinking", "content": "hmm"}]
+                }
+            }]
+        });
+        let r = parse_openai(v).unwrap();
+        assert!(
+            r.reasoning_details.is_none(),
+            "plain parse_openai must never capture reasoning_details (OpenAI/Databricks regression)"
+        );
+    }
+
+    #[test]
+    fn reasoning_details_two_request_round_trip() {
+        let details = serde_json::json!([
+            {"type": "thinking", "content": "Step 1: analyze the request."},
+            {"type": "thinking", "content": "Step 2: call the tool."}
+        ]);
+        // Request 1: model returns a tool call with reasoning_details
+        let response1 = serde_json::json!({
+            "choices": [{
+                "finish_reason": "tool_calls",
+                "message": {
+                    "content": "",
+                    "reasoning_details": details,
+                    "tool_calls": [{
+                        "id": "call_abc",
+                        "type": "function",
+                        "function": {"name": "dev__shell", "arguments": "{\"command\":\"ls\"}"}
+                    }]
+                }
+            }],
+            "usage": {"prompt_tokens": 50, "completion_tokens": 20}
+        });
+        let r1 = parse_openai_with_reasoning_details(response1).unwrap();
+        assert_eq!(r1.reasoning_details, Some(details.clone()));
+
+        // Build history as the agent would: assistant turn with reasoning_details,
+        // followed by a tool result.
+        let history = vec![
+            HistoryItem::User("run ls".into()),
+            HistoryItem::Assistant {
+                text: String::new(),
+                tool_calls: r1.tool_calls,
+                reasoning_details: r1.reasoning_details,
+            },
+            HistoryItem::ToolResult(ToolResult {
+                provider_id: "call_abc".into(),
+                content: vec![ToolResultContent::Text("file.txt".into())],
+                is_error: false,
+            }),
+        ];
+
+        // Request 2: build the body for the continuation
+        let body = openai_body(
+            &cfg(Provider::OpenRouter),
+            "system",
+            &history,
+            &[],
+            "anthropic/claude-opus-4-7",
+            None,
+        );
+        let messages = body["messages"].as_array().unwrap();
+
+        // The assistant message must carry the identical reasoning_details array
+        let assistant_msg = messages
+            .iter()
+            .find(|m| m.get("role").and_then(Value::as_str) == Some("assistant"))
+            .expect("assistant message must exist");
+        assert_eq!(
+            assistant_msg["reasoning_details"], details,
+            "reasoning_details must be replayed byte-for-byte on the assistant message"
+        );
+
+        // The assistant message must appear BEFORE the tool result
+        let assistant_idx = messages
+            .iter()
+            .position(|m| m.get("role").and_then(Value::as_str) == Some("assistant"))
+            .unwrap();
+        let tool_idx = messages
+            .iter()
+            .position(|m| m.get("role").and_then(Value::as_str) == Some("tool"))
+            .unwrap();
+        assert!(
+            assistant_idx < tool_idx,
+            "assistant with reasoning_details must precede tool result"
+        );
+    }
+
+    #[test]
+    fn reasoning_details_none_emits_no_field_in_body() {
+        let history = vec![
+            HistoryItem::User("hello".into()),
+            HistoryItem::Assistant {
+                text: "hi back".into(),
+                tool_calls: Vec::new(),
+                reasoning_details: None,
+            },
+        ];
+        let body = openai_body(
+            &cfg(Provider::OpenRouter),
+            "system",
+            &history,
+            &[],
+            "anthropic/claude-opus-4-7",
+            None,
+        );
+        let messages = body["messages"].as_array().unwrap();
+        let assistant_msg = messages
+            .iter()
+            .find(|m| m.get("role").and_then(Value::as_str) == Some("assistant"))
+            .expect("assistant message must exist");
+        assert!(
+            assistant_msg.get("reasoning_details").is_none(),
+            "assistant with None reasoning_details must not emit the field"
+        );
+    }
+
+    #[test]
+    fn reasoning_details_charged_to_estimated_bytes() {
+        let details = serde_json::json!([
+            {"type": "thinking", "content": "A long chain of reasoning tokens here."}
+        ]);
+        let with = HistoryItem::Assistant {
+            text: "text".into(),
+            tool_calls: Vec::new(),
+            reasoning_details: Some(details.clone()),
+        };
+        let without = HistoryItem::Assistant {
+            text: "text".into(),
+            tool_calls: Vec::new(),
+            reasoning_details: None,
+        };
+        assert!(
+            with.estimated_bytes() > without.estimated_bytes(),
+            "reasoning_details must contribute to estimated_bytes"
+        );
+        assert!(
+            with.context_pressure_bytes() > without.context_pressure_bytes(),
+            "reasoning_details must contribute to context_pressure_bytes"
+        );
+        let details_size = serde_json::to_vec(&details).unwrap().len();
+        assert_eq!(
+            with.estimated_bytes() - without.estimated_bytes(),
+            details_size,
+            "reasoning_details contribution must equal its serialized size"
+        );
+    }
+
+    #[test]
+    fn reasoning_details_not_replayed_in_anthropic_body() {
+        let history = vec![
+            HistoryItem::User("hi".into()),
+            HistoryItem::Assistant {
+                text: "ok".into(),
+                tool_calls: Vec::new(),
+                reasoning_details: Some(
+                    serde_json::json!([{"type": "thinking", "content": "hmm"}]),
+                ),
+            },
+        ];
+        let body = anthropic_body(
+            &cfg(Provider::Anthropic),
+            "system",
+            &history,
+            &[],
+            "claude-opus-4-7",
+            None,
+        );
+        let messages = body["messages"].as_array().unwrap();
+        let assistant = messages
+            .iter()
+            .find(|m| m.get("role").and_then(Value::as_str) == Some("assistant"))
+            .unwrap();
+        assert!(
+            assistant.get("reasoning_details").is_none(),
+            "anthropic_body must not replay reasoning_details"
+        );
+    }
+
+    #[test]
+    fn reasoning_details_not_replayed_in_responses_body() {
+        let history = vec![
+            HistoryItem::User("hi".into()),
+            HistoryItem::Assistant {
+                text: "ok".into(),
+                tool_calls: Vec::new(),
+                reasoning_details: Some(
+                    serde_json::json!([{"type": "thinking", "content": "hmm"}]),
+                ),
+            },
+        ];
+        let body = responses_body(&cfg_responses(), "system", &history, &[], "model", None);
+        let body_str = serde_json::to_string(&body).unwrap();
+        assert!(
+            !body_str.contains("reasoning_details"),
+            "responses_body must not replay reasoning_details"
+        );
+    }
+
+    // ---- T4: openrouter_post transport-level regressions ----
+    //
+    // These stub an HTTP server directly and drive `openrouter_post` (not the
+    // classifier in isolation), proving the retry/attempt-accounting and
+    // header behavior the classifier-only tests above cannot see.
+
+    /// One canned response: status, body, and any extra headers (e.g.
+    /// `Retry-After`) to send back for a single request.
+    struct CannedResponse {
+        status: u16,
+        body: String,
+        extra_headers: Vec<(String, String)>,
+    }
+
+    impl CannedResponse {
+        fn new(status: u16, body: &str) -> Self {
+            Self {
+                status,
+                body: body.into(),
+                extra_headers: Vec::new(),
+            }
+        }
+
+        fn with_header(mut self, name: &str, value: &str) -> Self {
+            self.extra_headers.push((name.into(), value.into()));
+            self
+        }
+    }
+
+    fn status_line(status: u16) -> &'static str {
+        match status {
+            200 => "200 OK",
+            401 => "401 Unauthorized",
+            402 => "402 Payment Required",
+            403 => "403 Forbidden",
+            404 => "404 Not Found",
+            429 => "429 Too Many Requests",
+            499 => "499 Client Closed Request",
+            500 => "500 Internal Server Error",
+            502 => "502 Bad Gateway",
+            503 => "503 Service Unavailable",
+            _ => panic!("unsupported status {status} in test stub"),
+        }
+    }
+
+    /// Spawns a stub HTTP server that pops one `CannedResponse` per request
+    /// (repeating the last one once the queue is exhausted, so an
+    /// over-budget attempt count is visible rather than hanging), and
+    /// captures each request's raw header block for header-attribution
+    /// assertions. Returns (url, captured_header_blocks, attempt_counter).
+    async fn spawn_openrouter_stub(
+        responses: Vec<CannedResponse>,
+    ) -> (
+        String,
+        Arc<Mutex<Vec<String>>>,
+        Arc<std::sync::atomic::AtomicU32>,
+    ) {
+        use std::sync::atomic::{AtomicU32, Ordering};
+        use tokio::io::{AsyncReadExt, AsyncWriteExt};
+        use tokio::net::TcpListener;
+
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let url = format!("http://{}", listener.local_addr().unwrap());
+        let queue = Arc::new(Mutex::new(VecDeque::from(responses)));
+        let captured: Arc<Mutex<Vec<String>>> = Arc::new(Mutex::new(Vec::new()));
+        let attempts = Arc::new(AtomicU32::new(0));
+        let captured_clone = captured.clone();
+        let attempts_clone = attempts.clone();
+        tokio::spawn(async move {
+            loop {
+                let (mut sock, _) = match listener.accept().await {
+                    Ok(p) => p,
+                    Err(_) => return,
+                };
+                let queue = queue.clone();
+                let captured = captured_clone.clone();
+                let attempts = attempts_clone.clone();
+                tokio::spawn(async move {
+                    let mut buf = Vec::new();
+                    let mut tmp = [0u8; 4096];
+                    while !buf.windows(4).any(|w| w == b"\r\n\r\n") {
+                        match sock.read(&mut tmp).await {
+                            Ok(0) | Err(_) => return,
+                            Ok(n) => buf.extend_from_slice(&tmp[..n]),
+                        }
+                        if buf.len() > 1_000_000 {
+                            return;
+                        }
+                    }
+                    let header_end = buf.windows(4).position(|w| w == b"\r\n\r\n").unwrap() + 4;
+                    let header_str = String::from_utf8_lossy(&buf[..header_end]).into_owned();
+                    // Drain any remaining body per Content-Length so `Connection:
+                    // close` doesn't race the client's write.
+                    let content_length: usize = header_str
+                        .lines()
+                        .find_map(|line| {
+                            line.to_ascii_lowercase()
+                                .strip_prefix("content-length:")
+                                .and_then(|v| v.trim().parse().ok())
+                        })
+                        .unwrap_or(0);
+                    let mut body_len = buf.len() - header_end;
+                    while body_len < content_length {
+                        match sock.read(&mut tmp).await {
+                            Ok(0) | Err(_) => break,
+                            Ok(n) => body_len += n,
+                        }
+                    }
+                    captured.lock().await.push(header_str);
+                    attempts.fetch_add(1, Ordering::SeqCst);
+
+                    let mut q = queue.lock().await;
+                    let canned = if q.len() > 1 {
+                        q.pop_front().unwrap()
+                    } else {
+                        // Repeat the final canned response so a test bug that
+                        // over-retries produces a visible extra attempt
+                        // instead of a hung connection.
+                        let last = q.front().unwrap();
+                        CannedResponse {
+                            status: last.status,
+                            body: last.body.clone(),
+                            extra_headers: last.extra_headers.clone(),
+                        }
+                    };
+                    drop(q);
+
+                    let mut resp = format!(
+                        "HTTP/1.1 {}\r\nContent-Type: application/json\r\nContent-Length: {}\r\n",
+                        status_line(canned.status),
+                        canned.body.len()
+                    );
+                    for (name, value) in &canned.extra_headers {
+                        resp.push_str(&format!("{name}: {value}\r\n"));
+                    }
+                    resp.push_str("Connection: close\r\n\r\n");
+                    resp.push_str(&canned.body);
+                    let _ = sock.write_all(resp.as_bytes()).await;
+                    let _ = sock.shutdown().await;
+                });
+            }
+        });
+        (url, captured, attempts)
+    }
+
+    /// A 403 (guardrail/moderation/permission rejection, per OpenRouter docs)
+    /// must NOT be classified as `LlmAuth`: refreshing a static key returns
+    /// the identical key, so retrying would just waste a duplicate request.
+    /// Exactly one attempt, plain `AgentError::Llm` with the body preserved.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn openrouter_post_403_single_attempt_not_auth_error() {
+        let (url, _captured, attempts) = spawn_openrouter_stub(vec![CannedResponse::new(
+            403,
+            r#"{"error":{"message":"model flagged by moderation"}}"#,
+        )])
+        .await;
+        let http = Client::builder()
+            .timeout(Duration::from_secs(5))
+            .build()
+            .unwrap();
+        let err = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
+            .await
+            .unwrap_err();
+        assert!(
+            matches!(&err, AgentError::Llm(s) if s.contains("403") && s.contains("model flagged by moderation")),
+            "403 must surface as AgentError::Llm with status+body, not LlmAuth: got {err:?}"
+        );
+        assert_eq!(
+            attempts.load(std::sync::atomic::Ordering::SeqCst),
+            1,
+            "403 must not be retried (a refreshed static key is identical)"
+        );
+    }
+
+    /// A 402 short-circuits on the first attempt: no retry, one request,
+    /// the actionable credits-exhausted message.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn openrouter_post_402_single_attempt_short_circuit() {
+        let (url, _captured, attempts) = spawn_openrouter_stub(vec![CannedResponse::new(
+            402,
+            r#"{"error":{"message":"payment required"}}"#,
+        )])
+        .await;
+        let http = Client::builder()
+            .timeout(Duration::from_secs(5))
+            .build()
+            .unwrap();
+        let err = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
+            .await
+            .unwrap_err();
+        assert!(
+            matches!(&err, AgentError::Llm(s) if s.contains("credits exhausted")),
+            "got {err:?}"
+        );
+        assert_eq!(
+            attempts.load(std::sync::atomic::Ordering::SeqCst),
+            1,
+            "402 must not be retried"
+        );
+    }
+
+    /// A 404 whose body is OpenRouter's parameter-routing rejection is NOT a
+    /// missing model: the id is valid and no endpoint behind it can serve the
+    /// request shape. It must surface the actionable routing message rather than
+    /// `LlmModelNotFound`, which sends the user hunting a model-name typo.
+    /// Body text is the one OpenRouter actually returned in the live probe run.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn openrouter_post_404_no_endpoints_found_is_parameter_routing_error() {
+        let (url, _captured, attempts) = spawn_openrouter_stub(vec![CannedResponse::new(
+            404,
+            r#"{"error":{"message":"No endpoints found that can handle the requested parameters. To learn more about provider routing, visit: https://openrouter.ai/docs/guides/routing/provider-selection","code":404}}"#,
+        )])
+        .await;
+        let http = Client::builder()
+            .timeout(Duration::from_secs(5))
+            .build()
+            .unwrap();
+        let err = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
+            .await
+            .unwrap_err();
+        assert!(
+            matches!(&err, AgentError::Llm(s) if s.contains("no OpenRouter endpoint supports")),
+            "parameter-routing 404 must not be reported as a missing model: got {err:?}"
+        );
+        assert_eq!(
+            attempts.load(std::sync::atomic::Ordering::SeqCst),
+            1,
+            "404 must not be retried"
+        );
+    }
+
+    /// Every other 404 still maps to `LlmModelNotFound`, including one that
+    /// shares the `No endpoints found` prefix but is about the model rather than
+    /// the parameters — the discriminator is narrow enough that a genuinely
+    /// unavailable model keeps its own error kind (Desktop renders
+    /// model-not-found differently from a generic LLM failure).
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn openrouter_post_404_unknown_model_stays_model_not_found() {
+        let (url, _captured, _attempts) = spawn_openrouter_stub(vec![CannedResponse::new(
+            404,
+            r#"{"error":{"message":"No endpoints found for vendor/nonexistent-model.","code":404}}"#,
+        )])
+        .await;
+        let http = Client::builder()
+            .timeout(Duration::from_secs(5))
+            .build()
+            .unwrap();
+        let err = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
+            .await
+            .unwrap_err();
+        assert!(
+            matches!(&err, AgentError::LlmModelNotFound(s) if s.contains("404") && s.contains("vendor/nonexistent-model")),
+            "a model-level 404 must stay LlmModelNotFound: got {err:?}"
+        );
+    }
+
+    /// A 429 with `Retry-After: 1` sleeps for that duration before the retry
+    /// succeeds — proving the header value is actually honored, not just
+    /// classified.
+    #[tokio::test(flavor = "current_thread")]
+    async fn openrouter_post_429_honors_retry_after_header() {
+        let (url, _captured, attempts) = spawn_openrouter_stub(vec![
+            CannedResponse::new(429, r#"{"error":{"message":"rate limited"}}"#)
+                .with_header("Retry-After", "1"),
+            CannedResponse::new(200, r#"{"choices":[{"message":{"content":"ok"}}]}"#),
+        ])
+        .await;
+        let http = Client::builder()
+            .timeout(Duration::from_secs(30))
+            .build()
+            .unwrap();
+        let before = std::time::Instant::now();
+        let out = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
+            .await
+            .expect("second attempt succeeds");
+        assert_eq!(out["choices"][0]["message"]["content"], "ok");
+        assert!(
+            before.elapsed() >= Duration::from_secs(1),
+            "must sleep at least the Retry-After hint"
+        );
+        assert_eq!(attempts.load(std::sync::atomic::Ordering::SeqCst), 2);
+    }
+
+    /// A `Retry-After` far beyond `RETRY_AFTER_CAP_SECS` must not stall the
+    /// retry loop for anywhere near its advertised duration — proving the
+    /// cap is enforced end-to-end in `openrouter_post`'s actual sleep, not
+    /// merely in the isolated `parse_retry_after_header` unit tests above.
+    /// Runs on a paused clock so a real 999999s wait would hang the test
+    /// instead of silently passing.
+    #[tokio::test(start_paused = true)]
+    async fn openrouter_post_429_retry_sleep_capped_despite_huge_retry_after() {
+        let (url, _captured, attempts) = spawn_openrouter_stub(vec![
+            CannedResponse::new(429, r#"{"error":{"message":"rate limited"}}"#)
+                .with_header("Retry-After", "999999"),
+            CannedResponse::new(200, r#"{"choices":[{"message":{"content":"ok"}}]}"#),
+        ])
+        .await;
+        let http = Client::builder().build().unwrap();
+        let before = tokio::time::Instant::now();
+        let out = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
+            .await
+            .expect("second attempt succeeds");
+        assert_eq!(out["choices"][0]["message"]["content"], "ok");
+        assert!(
+            before.elapsed() <= Duration::from_secs(RETRY_AFTER_CAP_SECS + 5),
+            "retry sleep must be clamped to RETRY_AFTER_CAP_SECS ({RETRY_AFTER_CAP_SECS}s), \
+             not the header's 999999s: elapsed {:?}",
+            before.elapsed()
+        );
+        assert_eq!(attempts.load(std::sync::atomic::Ordering::SeqCst), 2);
+    }
+
+    /// An untyped 503 (no `error.metadata.error_type`) exhausts all
+    /// `MAX_RETRIES` attempts, then returns the actionable routing message —
+    /// proving attempt accounting terminates rather than retrying forever.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn openrouter_post_untyped_503_exhausts_retries_into_actionable_message() {
+        let canned = CannedResponse::new(503, r#"{"error":{"message":"no capacity"}}"#);
+        let (url, _captured, attempts) = spawn_openrouter_stub(vec![canned]).await;
+        let http = Client::builder()
+            .timeout(Duration::from_secs(30))
+            .build()
+            .unwrap();
+        let err = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
+            .await
+            .unwrap_err();
+        assert!(
+            matches!(&err, AgentError::Llm(s) if s.contains("no OpenRouter endpoint supports")),
+            "got {err:?}"
+        );
+        assert_eq!(
+            attempts.load(std::sync::atomic::Ordering::SeqCst),
+            MAX_RETRIES,
+            "must exhaust exactly MAX_RETRIES attempts, no more"
+        );
+    }
+
+    /// Attribution headers (`HTTP-Referer`, `X-OpenRouter-Title`) are on the
+    /// actual wire request, not merely asserted against a body fixture.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn openrouter_post_sends_attribution_headers() {
+        let (url, captured, _attempts) = spawn_openrouter_stub(vec![CannedResponse::new(
+            200,
+            r#"{"choices":[{"message":{"content":"ok"}}]}"#,
+        )])
+        .await;
+        let http = Client::builder()
+            .timeout(Duration::from_secs(5))
+            .build()
+            .unwrap();
+        openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
+            .await
+            .expect("200 succeeds");
+        let headers = captured.lock().await;
+        let header_str = headers
+            .first()
+            .expect("one request captured")
+            .to_lowercase();
+        assert!(
+            header_str.contains("http-referer: https://github.com/block/buzz"),
+            "got: {header_str}"
+        );
+        assert!(
+            header_str.contains("x-openrouter-title: buzz"),
+            "got: {header_str}"
+        );
+    }
+
+    /// A 499 response is retried and the call succeeds on the second attempt,
+    /// mirroring the shared `post()` path (#2175).
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn openrouter_post_retries_499_then_succeeds() {
+        let (url, _captured, attempts) = spawn_openrouter_stub(vec![
+            CannedResponse::new(499, ""),
+            CannedResponse::new(200, r#"{"choices":[{"message":{"content":"ok"}}]}"#),
+        ])
+        .await;
+        let http = Client::builder()
+            .timeout(Duration::from_secs(30))
+            .build()
+            .unwrap();
+        let out = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
+            .await
+            .expect("retry after 499 should succeed");
+        assert_eq!(out["choices"][0]["message"]["content"], "ok");
+        assert_eq!(
+            attempts.load(std::sync::atomic::Ordering::SeqCst),
+            2,
+            "exactly one 499 retry"
+        );
+    }
+
+    /// A 502 without `provider_unavailable` still retries (the classifier's
+    /// unconditional-retry branch), then succeeds on attempt 2 — proving the
+    /// generic 502 path isn't accidentally routed to `Unknown`/terminal.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn openrouter_post_502_retries_then_succeeds() {
+        let (url, _captured, attempts) = spawn_openrouter_stub(vec![
+            CannedResponse::new(502, r#"{"error":{"message":"bad gateway"}}"#),
+            CannedResponse::new(200, r#"{"choices":[{"message":{"content":"ok"}}]}"#),
+        ])
+        .await;
+        let http = Client::builder()
+            .timeout(Duration::from_secs(30))
+            .build()
+            .unwrap();
+        let out = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
+            .await
+            .expect("retry succeeds");
+        assert_eq!(out["choices"][0]["message"]["content"], "ok");
+        assert_eq!(attempts.load(std::sync::atomic::Ordering::SeqCst), 2);
+    }
+
+    /// A 200 response whose body is truncated mid-stream (connection closed
+    /// before the full Content-Length is delivered) must surface the error
+    /// through `terminal_llm_error`, not a bare `AgentError::Llm("read: …")` —
+    /// the caller needs cumulative duration and attempt-count context to diagnose
+    /// an upstream that silently drops connections.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn openrouter_post_truncated_200_body_wraps_in_terminal_error() {
+        use tokio::io::{AsyncReadExt, AsyncWriteExt};
+        use tokio::net::TcpListener;
+
+        // Spawn a stub that sends a 200 with Content-Length > actual body,
+        // then closes the connection — reqwest sees a truncated stream.
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let url = format!("http://{}", listener.local_addr().unwrap());
+        tokio::spawn(async move {
+            if let Ok((mut sock, _)) = listener.accept().await {
+                let mut buf = [0u8; 4096];
+                // Read until end-of-headers, ignore body
+                loop {
+                    match sock.read(&mut buf).await {
+                        Ok(0) | Err(_) => break,
+                        Ok(n) => {
+                            if buf[..n].windows(4).any(|w| w == b"\r\n\r\n") {
+                                break;
+                            }
+                        }
+                    }
+                }
+                // Claim 1 MB of body, send only 10 bytes, then close.
+                let _ = sock
+                    .write_all(
+                        b"HTTP/1.1 200 OK\r\nContent-Type: application/json\r\n\
+                          Content-Length: 1048576\r\nConnection: close\r\n\r\n\
+                          {truncated",
+                    )
+                    .await;
+                let _ = sock.shutdown().await;
+            }
+        });
+
+        let http = Client::builder()
+            .timeout(Duration::from_secs(5))
+            .build()
+            .unwrap();
+        let err = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
+            .await
+            .unwrap_err();
+        assert!(
+            matches!(&err, AgentError::Llm(s) if s.contains("body read")),
+            "truncated body must surface as AgentError::Llm with 'body read': got {err:?}"
+        );
+        assert!(
+            matches!(&err, AgentError::Llm(s) if s.contains("cumulative")),
+            "body-read error must include terminal_llm_error's cumulative context: got {err:?}"
+        );
+    }
+
+    /// A `TokenSource` whose `refresh_now` always returns the identical token —
+    /// models a static API key whose bytes never change on refresh.
+    struct StaticAuth {
+        token: String,
+    }
+
+    #[async_trait::async_trait]
+    impl TokenSource for StaticAuth {
+        async fn bearer(&self) -> Result<String, AgentError> {
+            Ok(self.token.clone())
+        }
+        async fn refresh_now(&self, _rejected: &str) -> Result<String, AgentError> {
+            Ok(self.token.clone()) // static: same bytes every time
+        }
+    }
+
+    /// A `TokenSource` that returns a stale token from `bearer()` and a
+    /// distinct fresh token from `refresh_now()`, modelling a PKCE OAuth source.
+    struct MintingAuth {
+        stale: String,
+        fresh: String,
+        refreshes: std::sync::atomic::AtomicU32,
+    }
+
+    #[async_trait::async_trait]
+    impl TokenSource for MintingAuth {
+        async fn bearer(&self) -> Result<String, AgentError> {
+            Ok(self.stale.clone())
+        }
+        async fn refresh_now(&self, _rejected: &str) -> Result<String, AgentError> {
+            self.refreshes
+                .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+            Ok(self.fresh.clone())
+        }
+    }
+
+    /// A static key 401: `refresh_now` returns the same bytes — the second
+    /// wire request would be byte-identical, so the retry must be skipped.
+    /// Exactly one wire request reaches the server.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn post_openrouter_static_key_401_single_attempt_no_retry() {
+        use std::sync::atomic::Ordering;
+
+        let (url, _captured, attempts) = spawn_openrouter_stub(vec![CannedResponse::new(
+            401,
+            r#"{"error":{"message":"invalid api key"}}"#,
+        )])
+        .await;
+        let auth = Arc::new(StaticAuth {
+            token: "static-key".into(),
+        });
+        let llm = llm_with(auth);
+        let mut c = cfg(Provider::OpenRouter);
+        c.base_url = url;
+
+        let err = llm.post_openrouter(&c, &json!({})).await.unwrap_err();
+        assert!(
+            matches!(&err, AgentError::LlmAuth(s) if s.contains("static key rejected")),
+            "static 401 must surface as LlmAuth with 'static key rejected': got {err:?}"
+        );
+        assert_eq!(
+            attempts.load(Ordering::SeqCst),
+            1,
+            "exactly one wire request — no duplicate retry for a static key"
+        );
+    }
+
+    /// A minting-source 401: `refresh_now` produces a distinct fresh token, so
+    /// the retry is legitimate. The stub accepts the fresh token's second
+    /// request with 200 and exactly two wire requests reach the server.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn post_openrouter_minting_source_401_retries_with_fresh_token() {
+        use std::sync::atomic::Ordering;
+
+        // Stub: always 401 for bearer "stale", 200 for anything else.
+        // We repurpose `spawn_auth_stub` here: it rejects `Bearer stale`,
+        // accepts `Bearer fresh`.
+        let always_401 = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+        let base = spawn_auth_stub(always_401, 401).await;
+
+        let auth = Arc::new(MintingAuth {
+            stale: "stale".into(),
+            fresh: "fresh".into(),
+            refreshes: std::sync::atomic::AtomicU32::new(0),
+        });
+        let llm = llm_with(auth.clone());
+        let mut c = cfg(Provider::OpenRouter);
+        c.base_url = base;
+
+        let result = llm.post_openrouter(&c, &json!({})).await;
+        // `spawn_auth_stub` returns `{"ok":true}` on success.
+        assert!(
+            result.is_ok(),
+            "minting-source retry should succeed: {result:?}"
+        );
+        assert_eq!(
+            auth.refreshes.load(Ordering::SeqCst),
+            1,
+            "exactly one refresh"
+        );
+    }
 }
diff --git a/crates/buzz-agent/src/mcp.rs b/crates/buzz-agent/src/mcp.rs
index 744b10dc7a..9ae125a0b7 100644
--- a/crates/buzz-agent/src/mcp.rs
+++ b/crates/buzz-agent/src/mcp.rs
@@ -52,6 +52,31 @@ const PASSTHROUGH_ENV: &[&str] = &[
     "GIT_ASKPASS",
     "GIT_SSH_COMMAND",
     "GIT_CONFIG_GLOBAL",
+    // Proxy — on a host whose only route out is a CONNECT proxy, dropping
+    // these does not degrade the tools, it blinds them: apt, curl, pip and git
+    // all connect directly instead, and the egress firewall resets the socket.
+    // The agent then reports "Connection reset by peer" and concludes the
+    // environment has no network, which is indistinguishable in the transcript
+    // from a task that is genuinely offline.
+    //
+    // Both cases are needed. curl and git read the lowercase spellings, most
+    // Go and Python tooling reads the uppercase ones, and libcurl deliberately
+    // ignores uppercase HTTP_PROXY (CGI ambiguity), so keeping only one form
+    // silently breaks half the toolchain.
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "NO_PROXY",
+    "ALL_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "no_proxy",
+    "all_proxy",
+    // TLS trust — a proxy that terminates TLS presents its own CA, and an
+    // image whose trust store does not carry it fails every https fetch with a
+    // verification error. Same class of failure as the proxy vars: the parent
+    // was configured correctly and the child could not see it.
+    "SSL_CERT_FILE",
+    "SSL_CERT_DIR",
     // Buzz identity — dev-mcp writes NOSTR_PRIVATE_KEY to a keyfile then
     // removes it from its own env (children never see it). BUZZ_PRIVATE_KEY
     // and BUZZ_RELAY_URL are kept for the buzz CLI. BUZZ_AUTH_TAG is a
@@ -1015,6 +1040,41 @@ mod content_tests {
     fn passthrough_includes_buzz_owner_attestation() {
         assert!(PASSTHROUGH_ENV.contains(&"BUZZ_AUTH_TAG"));
     }
+
+    #[test]
+    fn passthrough_carries_proxy_configuration_to_tools() {
+        // On a proxy-only host this is the difference between an agent that can
+        // install a package and one that reports the network is down. Both
+        // spellings: libcurl ignores uppercase HTTP_PROXY, and Go/Python
+        // tooling largely ignores the lowercase set.
+        for var in [
+            "HTTP_PROXY",
+            "HTTPS_PROXY",
+            "NO_PROXY",
+            "ALL_PROXY",
+            "http_proxy",
+            "https_proxy",
+            "no_proxy",
+            "all_proxy",
+        ] {
+            assert!(
+                PASSTHROUGH_ENV.contains(&var),
+                "{var} must survive env_clear() or every MCP tool loses the proxy"
+            );
+        }
+    }
+
+    #[test]
+    fn passthrough_carries_tls_trust_to_tools() {
+        // A TLS-terminating proxy presents its own CA; without these the child
+        // rejects every https fetch even though the proxy itself is reachable.
+        for var in ["SSL_CERT_FILE", "SSL_CERT_DIR"] {
+            assert!(
+                PASSTHROUGH_ENV.contains(&var),
+                "{var} must survive env_clear() or https fails inside tools"
+            );
+        }
+    }
     use rmcp::model::Content;
 
     #[cfg(windows)]
diff --git a/crates/buzz-agent/src/types.rs b/crates/buzz-agent/src/types.rs
index d29e975e03..343a75bf72 100644
--- a/crates/buzz-agent/src/types.rs
+++ b/crates/buzz-agent/src/types.rs
@@ -1,5 +1,5 @@
 use serde::Deserialize;
-use serde_json::Value;
+use serde_json::{Map, Value};
 
 /// Byte-equivalent charged to the handoff/context-pressure gate for a single
 /// image tool result. The gate maps bytes to tokens at 1 byte/token (see
@@ -62,6 +62,7 @@ pub enum HistoryItem {
     Assistant {
         text: String,
         tool_calls: Vec<ToolCall>,
+        reasoning_details: Option<Value>,
     },
     ToolResult(ToolResult),
 }
@@ -83,7 +84,11 @@ impl HistoryItem {
     fn size_with(&self, content_size: fn(&ToolResultContent) -> usize) -> usize {
         match self {
             Self::User(s) => s.len(),
-            Self::Assistant { text, tool_calls } => {
+            Self::Assistant {
+                text,
+                tool_calls,
+                reasoning_details,
+            } => {
                 text.len()
                     + tool_calls
                         .iter()
@@ -93,8 +98,20 @@ impl HistoryItem {
                                 + serde_json::to_vec(&c.arguments)
                                     .map(|b| b.len())
                                     .unwrap_or(0)
+                                // `provider_extra` (e.g. a Gemini
+                                // `thoughtSignature`) is re-serialized into
+                                // every replayed call, so it counts toward the
+                                // request body and the context-pressure gate.
+                                + serde_json::to_vec(&c.provider_extra)
+                                    .map(|b| b.len())
+                                    .unwrap_or(0)
                         })
                         .sum::<usize>()
+                    + reasoning_details
+                        .as_ref()
+                        .and_then(|v| serde_json::to_vec(v).ok())
+                        .map(|b| b.len())
+                        .unwrap_or(0)
             }
             Self::ToolResult(r) => {
                 r.provider_id.len() + r.content.iter().map(content_size).sum::<usize>()
@@ -108,6 +125,17 @@ pub struct ToolCall {
     pub provider_id: String,
     pub name: String,
     pub arguments: Value,
+    /// Fields the provider put on the tool call that we do not model, kept so
+    /// the assistant turn can be replayed the way it arrived.
+    ///
+    /// Gemini on the Databricks MLflow route returns a `thoughtSignature` per
+    /// call and *requires* it echoed back: replaying without it fails the whole
+    /// request with `Function call is missing a thought_signature in functionCall
+    /// parts`. For an agent loop that lands on the very first tool call, so the
+    /// model is unusable without this. Carrying whatever we did not model,
+    /// rather than naming that one field, means the next provider with an opaque
+    /// per-call token needs no change here.
+    pub provider_extra: Map<String, Value>,
 }
 
 #[derive(Debug, Clone)]
@@ -139,10 +167,28 @@ pub struct LlmResponse {
     /// tokens, so reading it alone would undercount). Used to gate handoff on
     /// the real token budget rather than a byte estimate.
     pub input_tokens: Option<u64>,
+    /// The portion of `input_tokens` the provider served from its prompt cache,
+    /// or `None` when the response reported no cache split. Providers bill this
+    /// slice at a large discount (roughly 10x for both OpenAI and Anthropic),
+    /// so a consumer that prices all of `input_tokens` at the full rate
+    /// *overstates* cost — by a lot on an append-only agent loop, where most of
+    /// each request is a prefix the provider already has.
+    ///
+    /// This is a subset of `input_tokens`, never an addition to it: every
+    /// provider we speak to reports an inclusive input total, so adding this
+    /// would double-count.
+    pub cached_input_tokens: Option<u64>,
     /// Output tokens the provider reported for this request, or `None` if the
     /// response carried no usage. Used to accumulate per-turn output counts
     /// for NIP-AM metric publishing.
     pub output_tokens: Option<u64>,
+    /// Provider-reported total tokens for this request, or `None` when the
+    /// provider does not report a genuine total. Present for OpenAI-shaped
+    /// responses (`usage.total_tokens`). Always `None` for Anthropic, which
+    /// reports only category counts; NIP-AM forbids summing categories into a
+    /// total. Callers must not derive this by summing `input_tokens +
+    /// output_tokens` — that is what the UI display approximation is for.
+    pub total_tokens: Option<u64>,
     /// Reasoning/thinking content emitted by the model before its answer, if
     /// any. Non-empty when the provider returns extended-thinking tokens:
     ///
@@ -152,6 +198,10 @@ pub struct LlmResponse {
     ///
     /// Empty string when the provider returned no reasoning content.
     pub reasoning: String,
+    /// Raw `reasoning_details` array from an OpenRouter response, if present.
+    /// Replayed on subsequent turns so the model can continue its chain-of-thought.
+    /// `None` for all non-OpenRouter providers.
+    pub reasoning_details: Option<Value>,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq)]
@@ -170,6 +220,94 @@ pub struct ToolDef {
     pub input_schema: Value,
 }
 
+/// Tri-state accumulator for provider-reported total tokens within one ACP turn.
+///
+/// Tracks whether every usage-bearing LLM response in the turn supplied a genuine
+/// provider total. Used to accumulate a reliable per-turn total and contribute to
+/// the session-cumulative total.
+///
+/// - `Unseen`: no usage-bearing response observed yet (initial state for each turn).
+/// - `Exact(n)`: every response so far reported a total; `n` is their sum.
+/// - `Unknown`: at least one response lacked a total — permanently poisoned for
+///   this turn. The session-cumulative also transitions to Unknown when any turn
+///   lands Unknown, and stays there until a new session resets it.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum TurnTotalState {
+    #[default]
+    Unseen,
+    Exact(u64),
+    Unknown,
+}
+
+impl TurnTotalState {
+    /// Add two exact token counts with overflow protection.
+    ///
+    /// Returns `Exact(acc + n)` on success or `Unknown` on overflow.
+    /// This is the single implementation of the checked-add / overflow-poisons
+    /// contract; both `fold()` and `merge_session()` call this helper so a
+    /// change to overflow semantics needs to be made in exactly one place.
+    fn checked_exact_sum(acc: u64, n: u64) -> TurnTotalState {
+        match acc.checked_add(n) {
+            Some(sum) => TurnTotalState::Exact(sum),
+            None => TurnTotalState::Unknown,
+        }
+    }
+
+    /// Fold one provider-reported total into the current state.
+    ///
+    /// `total`: `Some(n)` when the provider included a genuine total on this
+    /// response; `None` when it was absent (e.g. Anthropic, or an OpenAI
+    /// response that omits usage). Absence of a total on any usage-bearing
+    /// response poisons the whole turn.
+    ///
+    /// Overflow is handled by `checked_exact_sum`: a saturated value would
+    /// not be a genuine provider-reported total, so overflow → `Unknown`.
+    pub fn fold(self, total: Option<u64>) -> TurnTotalState {
+        match (self, total) {
+            // Already poisoned — stays Unknown regardless.
+            (TurnTotalState::Unknown, _) => TurnTotalState::Unknown,
+            // No total from this response — poison the accumulator.
+            (_, None) => TurnTotalState::Unknown,
+            // First response with a total.
+            (TurnTotalState::Unseen, Some(n)) => TurnTotalState::Exact(n),
+            // Subsequent response — delegate to the shared checked-sum helper.
+            (TurnTotalState::Exact(acc), Some(n)) => Self::checked_exact_sum(acc, n),
+        }
+    }
+
+    /// Merge a completed turn's total state into the session-cumulative state.
+    ///
+    /// This is the turn→session boundary accumulation:
+    /// - An `Unseen` turn (no usage-bearing responses) leaves the cumulative unchanged.
+    /// - Any `Unknown` side poisons the session permanently.
+    /// - Two `Exact` values are summed via `checked_exact_sum`; overflow → `Unknown`.
+    ///
+    /// The checked-add logic lives in `checked_exact_sum`; both this function and
+    /// `fold()` call that helper so overflow semantics are defined once.
+    pub fn merge_session(self, turn: TurnTotalState) -> TurnTotalState {
+        match (self, turn) {
+            // Either side poisoned → session is poisoned.
+            (TurnTotalState::Unknown, _) | (_, TurnTotalState::Unknown) => TurnTotalState::Unknown,
+            // Turn had no usage-bearing responses → no change to cumulative.
+            (acc, TurnTotalState::Unseen) => acc,
+            // First exact turn — adopt its value.
+            (TurnTotalState::Unseen, TurnTotalState::Exact(n)) => TurnTotalState::Exact(n),
+            // Add to running exact sum — delegate to the shared checked-sum helper.
+            (TurnTotalState::Exact(acc), TurnTotalState::Exact(n)) => {
+                Self::checked_exact_sum(acc, n)
+            }
+        }
+    }
+
+    /// Consume the exact value if present; `None` for `Unseen` or `Unknown`.
+    pub fn exact_value(self) -> Option<u64> {
+        match self {
+            TurnTotalState::Exact(n) => Some(n),
+            _ => None,
+        }
+    }
+}
+
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum StopReason {
     EndTurn,
@@ -342,6 +480,41 @@ mod tests {
         assert!(item.estimated_bytes() >= 3_118_884);
     }
 
+    #[test]
+    fn assistant_size_counts_provider_extra() {
+        // A Gemini `thoughtSignature` rides the wire on every replayed call, so
+        // both size measures must see it — otherwise `truncate_history` and the
+        // handoff gate under-count and let the real request exceed the budget.
+        let mut extra = Map::new();
+        extra.insert("thoughtSignature".into(), Value::String("S".repeat(500)));
+        let with_extra = HistoryItem::Assistant {
+            text: String::new(),
+            tool_calls: vec![ToolCall {
+                provider_id: "id".into(),
+                name: "t".into(),
+                arguments: Value::Null,
+                provider_extra: extra,
+            }],
+            reasoning_details: None,
+        };
+        let without_extra = HistoryItem::Assistant {
+            text: String::new(),
+            tool_calls: vec![ToolCall {
+                provider_id: "id".into(),
+                name: "t".into(),
+                arguments: Value::Null,
+                provider_extra: Map::new(),
+            }],
+            reasoning_details: None,
+        };
+        assert!(with_extra.estimated_bytes() > without_extra.estimated_bytes() + 500);
+        assert_eq!(
+            with_extra.estimated_bytes(),
+            with_extra.context_pressure_bytes(),
+            "provider_extra is text, so both measures must agree"
+        );
+    }
+
     #[test]
     fn text_content_size_is_identical_for_both_measures() {
         // Only images diverge; text must size the same under both paths.
@@ -351,3 +524,138 @@ mod tests {
         assert_eq!(item.estimated_bytes(), item.context_pressure_bytes());
     }
 }
+
+#[cfg(test)]
+mod turn_total_state_tests {
+    use super::TurnTotalState;
+
+    // ── TurnTotalState::fold ───────────────────────────────────────────────
+
+    #[test]
+    fn fold_first_response_with_total_becomes_exact() {
+        let state = TurnTotalState::Unseen;
+        assert_eq!(state.fold(Some(100)), TurnTotalState::Exact(100));
+    }
+
+    #[test]
+    fn fold_first_response_without_total_becomes_unknown() {
+        // Missing total on any usage-bearing response poisons the turn.
+        let state = TurnTotalState::Unseen;
+        assert_eq!(state.fold(None), TurnTotalState::Unknown);
+    }
+
+    #[test]
+    fn multiple_provider_rounds_all_with_totals_sum_correctly() {
+        // Multiple rounds all reporting a genuine total → Exact with their sum.
+        let state = TurnTotalState::Unseen;
+        let state = state.fold(Some(100));
+        let state = state.fold(Some(50));
+        let state = state.fold(Some(75));
+        assert_eq!(state, TurnTotalState::Exact(225));
+    }
+
+    #[test]
+    fn mixed_present_and_missing_totals_within_one_turn_poisons_accumulator() {
+        // First round has a total, second does not → Unknown (permanently poisoned).
+        let state = TurnTotalState::Unseen;
+        let state = state.fold(Some(100)); // Exact(100)
+        let state = state.fold(None); // Missing → Unknown
+        assert_eq!(state, TurnTotalState::Unknown);
+        // Further rounds with totals don't un-poison.
+        let state = state.fold(Some(50));
+        assert_eq!(state, TurnTotalState::Unknown);
+    }
+
+    #[test]
+    fn unknown_stays_unknown_regardless_of_subsequent_totals() {
+        // Once poisoned, no subsequent total can recover the state.
+        let state = TurnTotalState::Unknown;
+        assert_eq!(state.fold(Some(999)), TurnTotalState::Unknown);
+        assert_eq!(state.fold(None), TurnTotalState::Unknown);
+    }
+
+    #[test]
+    fn exact_value_returns_some_only_for_exact_variant() {
+        assert_eq!(TurnTotalState::Unseen.exact_value(), None);
+        assert_eq!(TurnTotalState::Unknown.exact_value(), None);
+        assert_eq!(TurnTotalState::Exact(42).exact_value(), Some(42));
+    }
+
+    #[test]
+    fn default_is_unseen() {
+        let state: TurnTotalState = Default::default();
+        assert_eq!(state, TurnTotalState::Unseen);
+    }
+
+    // ── overflow: fold ─────────────────────────────────────────────────────
+
+    #[test]
+    fn fold_overflow_poisons_turn_not_saturates() {
+        // u64::MAX + 1 would saturate; checked_add must poison instead.
+        let state = TurnTotalState::Exact(u64::MAX);
+        assert_eq!(
+            state.fold(Some(1)),
+            TurnTotalState::Unknown,
+            "overflow in fold() must produce Unknown, not Exact(u64::MAX)"
+        );
+    }
+
+    // ── TurnTotalState::merge_session ──────────────────────────────────────
+
+    #[test]
+    fn merge_session_unseen_turn_leaves_cumulative_unchanged() {
+        // An Unseen turn (no usage-bearing responses) must not alter the cumulative.
+        assert_eq!(
+            TurnTotalState::Exact(100).merge_session(TurnTotalState::Unseen),
+            TurnTotalState::Exact(100),
+        );
+        assert_eq!(
+            TurnTotalState::Unseen.merge_session(TurnTotalState::Unseen),
+            TurnTotalState::Unseen,
+        );
+    }
+
+    #[test]
+    fn merge_session_exact_turn_adds_to_exact_cumulative() {
+        assert_eq!(
+            TurnTotalState::Exact(100).merge_session(TurnTotalState::Exact(50)),
+            TurnTotalState::Exact(150),
+        );
+    }
+
+    #[test]
+    fn merge_session_first_exact_turn_from_unseen_adopts_value() {
+        assert_eq!(
+            TurnTotalState::Unseen.merge_session(TurnTotalState::Exact(200)),
+            TurnTotalState::Exact(200),
+        );
+    }
+
+    #[test]
+    fn merge_session_unknown_turn_poisons_cumulative_permanently() {
+        assert_eq!(
+            TurnTotalState::Exact(100).merge_session(TurnTotalState::Unknown),
+            TurnTotalState::Unknown,
+        );
+        // Poisoned session stays poisoned even with Unseen turn.
+        assert_eq!(
+            TurnTotalState::Unknown.merge_session(TurnTotalState::Unseen),
+            TurnTotalState::Unknown,
+        );
+        // Poisoned session stays poisoned even with another Exact turn.
+        assert_eq!(
+            TurnTotalState::Unknown.merge_session(TurnTotalState::Exact(999)),
+            TurnTotalState::Unknown,
+        );
+    }
+
+    #[test]
+    fn merge_session_overflow_poisons_not_saturates() {
+        // Overflow at the session boundary must also produce Unknown.
+        assert_eq!(
+            TurnTotalState::Exact(u64::MAX).merge_session(TurnTotalState::Exact(1)),
+            TurnTotalState::Unknown,
+            "overflow in merge_session() must produce Unknown, not Exact(u64::MAX)"
+        );
+    }
+}
diff --git a/crates/buzz-agent/tests/bin/fake_mcp.rs b/crates/buzz-agent/tests/bin/fake_mcp.rs
index 0bbd1d3478..5b660da48c 100644
--- a/crates/buzz-agent/tests/bin/fake_mcp.rs
+++ b/crates/buzz-agent/tests/bin/fake_mcp.rs
@@ -33,6 +33,11 @@
 //!                            — expose a `_PostCompact` hook tool
 //!   FAKE_MCP_POSTCOMPACT_TEXT=text
 //!                            — `_PostCompact` returns this (default: "")
+//!   FAKE_MCP_SHELL_TOOL=1    — expose a tool whose bare name is `shell`
+//!                              (registered as `<server>__shell`), taking a
+//!                              `command` string. Lets a test drive the
+//!                              reply guard's recognition of a real,
+//!                              registered shell tool.
 
 use std::io::{BufRead, Write};
 
@@ -76,6 +81,7 @@ fn make_tools(
     desc: &str,
     include_stop_hook: bool,
     include_post_compact_hook: bool,
+    include_shell_tool: bool,
 ) -> Vec<Value> {
     let mut tools: Vec<Value> = (0..count)
         .map(|i| {
@@ -100,6 +106,17 @@ fn make_tools(
             "inputSchema": { "type": "object", "properties": {} },
         }));
     }
+    if include_shell_tool {
+        tools.push(json!({
+            "name": "shell",
+            "description": "run a shell command",
+            "inputSchema": {
+                "type": "object",
+                "properties": { "command": { "type": "string" } },
+                "required": ["command"],
+            },
+        }));
+    }
     tools
 }
 
@@ -136,6 +153,7 @@ fn main() {
     let stop_count_limit: usize = env_usize("FAKE_MCP_STOP_COUNT", usize::MAX);
     let mut stop_calls_seen: usize = 0;
     let post_compact_hook = env_flag("FAKE_MCP_POSTCOMPACT_HOOK");
+    let shell_tool = env_flag("FAKE_MCP_SHELL_TOOL");
     let post_compact_text = std::env::var("FAKE_MCP_POSTCOMPACT_TEXT").unwrap_or_default();
 
     // Use a channel-based stdin reader so notifications (which carry no id)
@@ -206,7 +224,13 @@ fn main() {
                 write_response(
                     id,
                     json!({
-                        "tools": make_tools(tool_count, &desc, stop_hook, post_compact_hook)
+                        "tools": make_tools(
+                            tool_count,
+                            &desc,
+                            stop_hook,
+                            post_compact_hook,
+                            shell_tool,
+                        )
                     }),
                 );
             }
diff --git a/crates/buzz-agent/tests/fake_llm.rs b/crates/buzz-agent/tests/fake_llm.rs
index f2a86ac4b3..f782a9d476 100644
--- a/crates/buzz-agent/tests/fake_llm.rs
+++ b/crates/buzz-agent/tests/fake_llm.rs
@@ -771,6 +771,26 @@ fn openai_text_with_usage(content: &str, input_tokens: u64, output_tokens: u64)
     })
 }
 
+/// An OpenAI chat completion response WITH i/o usage but WITHOUT `total_tokens`.
+/// Simulates a provider that omits the genuine total from its usage block.
+/// buzz-agent must treat this turn's total as Unknown and poison the cumulative.
+fn openai_text_with_usage_no_total(content: &str, input_tokens: u64, output_tokens: u64) -> Value {
+    json!({
+        "id": "cc-nt", "object": "chat.completion", "model": "fake-model",
+        "choices": [{
+            "index": 0,
+            "message": { "role": "assistant", "content": content },
+            "finish_reason": "stop",
+        }],
+        "usage": {
+            "prompt_tokens": input_tokens,
+            "completion_tokens": output_tokens,
+            // total_tokens deliberately absent — simulates Anthropic or any
+            // provider that does not report a genuine total.
+        },
+    })
+}
+
 /// Returns true when `v` is a `_goose/unstable/session/update` usage_update
 /// notification.
 fn is_usage_update(v: &Value) -> bool {
@@ -1123,3 +1143,164 @@ async fn steer_rejected_on_empty_prompt() {
     assert!(saw_reject, "empty steer prompt was not rejected");
     h.shutdown().await;
 }
+
+// ─── Session-boundary total accumulation ────────────────────────────────────
+
+/// Once a usage-bearing turn lacks a provider total, the session cumulative
+/// becomes Unknown and `accumulatedTotalTokens` must be absent from subsequent
+/// `usage_update` notifications — even if later turns supply a total.
+///
+/// Sequence: turn 1 has total, turn 2 lacks total → session poisoned, turn 3
+/// has total → still poisoned. Only turn 1 must carry `accumulatedTotalTokens`.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn session_total_poisoned_by_missing_total_and_stays_poisoned() {
+    let url = spawn_fake_llm(vec![
+        openai_text_with_usage("t1", 10, 5), // total present → Exact(15)
+        openai_text_with_usage_no_total("t2", 20, 8), // total absent  → Unknown
+        openai_text_with_usage("t3", 15, 6), // total present → still Unknown
+    ])
+    .await;
+    let mut h = Harness::spawn(&url).await;
+    let sid = init_session(&mut h).await;
+
+    // ── Turn 1: total present ───────────────────────────────────────────────
+    let p1 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"t1"}]}),
+        )
+        .await;
+    let (frames1, _) = recv_until_with_drain(&mut h, |v| v["id"] == p1).await;
+    let usage1 = frames1
+        .iter()
+        .find(|v| is_usage_update(v))
+        .expect("usage_update for turn 1");
+    assert_eq!(
+        usage1["params"]["update"]["accumulatedTotalTokens"],
+        json!(15u64),
+        "turn 1 has genuine total; accumulatedTotalTokens must be 15"
+    );
+
+    // ── Turn 2: total absent — session is now poisoned ──────────────────────
+    let p2 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"t2"}]}),
+        )
+        .await;
+    let (frames2, _) = recv_until_with_drain(&mut h, |v| v["id"] == p2).await;
+    let usage2 = frames2
+        .iter()
+        .find(|v| is_usage_update(v))
+        .expect("usage_update for turn 2");
+    assert!(
+        usage2["params"]["update"]["accumulatedTotalTokens"].is_null()
+            || usage2["params"]["update"]
+                .get("accumulatedTotalTokens")
+                .is_none(),
+        "turn 2 lacked total; accumulatedTotalTokens must be absent/null; got: {usage2:#?}"
+    );
+
+    // ── Turn 3: total present, but session is still poisoned ─────────────────
+    let p3 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"t3"}]}),
+        )
+        .await;
+    let (frames3, _) = recv_until_with_drain(&mut h, |v| v["id"] == p3).await;
+    let usage3 = frames3
+        .iter()
+        .find(|v| is_usage_update(v))
+        .expect("usage_update for turn 3");
+    assert!(
+        usage3["params"]["update"]["accumulatedTotalTokens"].is_null()
+            || usage3["params"]["update"].get("accumulatedTotalTokens").is_none(),
+        "session is poisoned; accumulatedTotalTokens must remain absent even after a total-bearing turn; got: {usage3:#?}"
+    );
+
+    // i/o counters are unaffected by total poisoning.
+    assert_eq!(
+        usage3["params"]["update"]["accumulatedInputTokens"],
+        json!(45u64),
+        "poisoned total must not discard input accumulation"
+    );
+    assert_eq!(
+        usage3["params"]["update"]["accumulatedOutputTokens"],
+        json!(19u64),
+        "poisoned total must not discard output accumulation"
+    );
+
+    h.shutdown().await;
+}
+
+/// A new session starts fresh and can accumulate an exact total independently
+/// of any previous session. This verifies `accumulated_total_state` is reset
+/// to `Unseen` on `session/new`, not inherited from a prior session.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn new_session_resets_total_accumulation() {
+    // Session A: two turns both with totals → Exact should accumulate.
+    // Session B (new session/new call): starts fresh.
+    let url = spawn_fake_llm(vec![
+        // Session A, turn 1
+        openai_text_with_usage("s1t1", 10, 5),
+        // Session A, turn 2
+        openai_text_with_usage("s1t2", 20, 8),
+        // Session B, turn 1
+        openai_text_with_usage("s2t1", 30, 10),
+    ])
+    .await;
+    let mut h = Harness::spawn(&url).await;
+    let sid_a = init_session(&mut h).await;
+
+    // Session A, turn 1
+    let p1 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid_a, "prompt": [{"type":"text","text":"s1t1"}]}),
+        )
+        .await;
+    let (frames1, _) = recv_until_with_drain(&mut h, |v| v["id"] == p1).await;
+    let u1 = frames1.iter().find(|v| is_usage_update(v)).expect("usage1");
+    assert_eq!(
+        u1["params"]["update"]["accumulatedTotalTokens"],
+        json!(15u64),
+        "session A turn 1 accumulated total"
+    );
+
+    // Session A, turn 2 — cumulative total is 15+28=43
+    let p2 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid_a, "prompt": [{"type":"text","text":"s1t2"}]}),
+        )
+        .await;
+    let (frames2, _) = recv_until_with_drain(&mut h, |v| v["id"] == p2).await;
+    let u2 = frames2.iter().find(|v| is_usage_update(v)).expect("usage2");
+    assert_eq!(
+        u2["params"]["update"]["accumulatedTotalTokens"],
+        json!(43u64),
+        "session A turn 2 cumulative total must be 15+28=43"
+    );
+
+    // Start a new session — must reset accumulated_total_state to Unseen.
+    let sid_b = init_session(&mut h).await;
+    assert_ne!(sid_a, sid_b, "sessions must have distinct IDs");
+
+    // Session B, turn 1 — total 30+10=40. Must NOT start from 43.
+    let p3 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid_b, "prompt": [{"type":"text","text":"s2t1"}]}),
+        )
+        .await;
+    let (frames3, _) = recv_until_with_drain(&mut h, |v| v["id"] == p3).await;
+    let u3 = frames3.iter().find(|v| is_usage_update(v)).expect("usage3");
+    assert_eq!(
+        u3["params"]["update"]["accumulatedTotalTokens"],
+        json!(40u64),
+        "new session must start fresh — accumulated total must be 40, not 83"
+    );
+
+    h.shutdown().await;
+}
diff --git a/crates/buzz-agent/tests/regressions.rs b/crates/buzz-agent/tests/regressions.rs
index 2e0b579c84..abb4f7b311 100644
--- a/crates/buzz-agent/tests/regressions.rs
+++ b/crates/buzz-agent/tests/regressions.rs
@@ -1819,3 +1819,465 @@ async fn cancel_sends_notifications_cancelled_to_any_mcp_server() {
     let _ = std::fs::remove_file(&call_received_marker);
     h.shutdown().await;
 }
+
+// ---------------------------------------------------------------------------
+// Reply guard (`BUZZ_AGENT_REQUIRE_REPLY`)
+//
+// The guard reminds the model to publish when a turn is about to end without
+// any recognized attempt to post to Buzz. It rides the existing `_Stop` gate
+// and shares its rejection budget, so most of these tests count LLM calls:
+// each reminder costs exactly one extra round.
+// ---------------------------------------------------------------------------
+
+/// Number of reply-guard reminders present in one captured LLM request.
+///
+/// A reminder is a tool-role message whose JSON body is attributed to the
+/// in-process guard (`server: "buzz-agent"`) at the `_Stop` hook point — the
+/// same lower-trust shape as real hook output.
+fn reply_nag_count(request: &Value) -> usize {
+    request["messages"]
+        .as_array()
+        .map(|msgs| {
+            msgs.iter()
+                .filter(|m| {
+                    m["role"] == "tool"
+                        && serde_json::from_str::<Value>(m["content"].as_str().unwrap_or(""))
+                            .map(|p| p["hook"] == "_Stop" && p["server"] == "buzz-agent")
+                            .unwrap_or(false)
+                })
+                .count()
+        })
+        .unwrap_or(0)
+}
+
+/// A publish-shaped call to a real registered shell tool.
+fn openai_shell_send(id: &str) -> Value {
+    openai_tool_call(
+        id,
+        "fake__shell",
+        json!({ "command": "buzz messages send --channel c --content hi" }),
+    )
+}
+
+/// Run one prompt to completion, answering any permission requests, and
+/// return the final response.
+async fn prompt_to_completion(h: &mut Harness, sid: &str) -> Value {
+    let p = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"go"}]}),
+        )
+        .await;
+    loop {
+        let v = h.recv().await;
+        if v.get("method") == Some(&json!("session/request_permission")) {
+            let id = v["id"].clone();
+            h.write(json!({
+                "jsonrpc": "2.0",
+                "id": id,
+                "result": { "outcome": { "outcome": "selected", "optionId": "allow" } },
+            }))
+            .await;
+            continue;
+        }
+        if v["id"] == json!(p) {
+            return v;
+        }
+    }
+}
+
+/// Default off: a silent turn ends on the first end_turn with no extra round.
+/// This is the invariant that keeps the feature free for everyone who hasn't
+/// opted in.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_off_by_default() {
+    let llm = spawn_capturing_llm(vec![openai_text("done"), openai_text("unexpected")]).await;
+    let mut h = Harness::spawn(&llm.url).await;
+    let sid = init_session(&mut h, json!([])).await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        1,
+        "guard must be inert when unset, got {} LLM calls",
+        captured.len()
+    );
+    h.shutdown().await;
+}
+
+/// `BUZZ_AGENT_REQUIRE_REPLY=0` is off too — the toggle is numeric, so a
+/// literal `0` must not read as "set, therefore on".
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_explicit_zero_is_off() {
+    let llm = spawn_capturing_llm(vec![openai_text("done"), openai_text("unexpected")]).await;
+    let mut h = Harness::spawn_with_env(&llm.url, &[("BUZZ_AGENT_REQUIRE_REPLY", "0")]).await;
+    let sid = init_session(&mut h, json!([])).await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        1,
+        "REQUIRE_REPLY=0 must behave as off, got {} LLM calls",
+        captured.len()
+    );
+    h.shutdown().await;
+}
+
+/// Opted in and silent: exactly two reminders, then the turn is allowed to
+/// end. The guard is advisory — it must never trap a turn.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_nags_twice_then_lets_the_turn_end() {
+    // Budget defaults to 3, so the cap that stops the loop here is
+    // MAX_REPLY_NAGS = 2, not the rejection budget.
+    let llm = spawn_capturing_llm(vec![
+        openai_text("silent-1"),
+        openai_text("silent-2"),
+        openai_text("silent-3"),
+        openai_text("must-not-be-requested"),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(&llm.url, &[("BUZZ_AGENT_REQUIRE_REPLY", "1")]).await;
+    let sid = init_session(&mut h, json!([])).await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        3,
+        "expected 2 reminders then end_turn (3 LLM calls), got {}",
+        captured.len()
+    );
+    assert_eq!(
+        reply_nag_count(&captured[0]),
+        0,
+        "reminder before any end_turn"
+    );
+    assert_eq!(reply_nag_count(&captured[1]), 1);
+    assert_eq!(reply_nag_count(&captured[2]), 2);
+
+    // The reminder must name the command it wants and license silence, so it
+    // cannot fight the base prompt's "silence is usually correct".
+    let msgs = captured[2]["messages"].as_array().unwrap();
+    let nag = msgs
+        .iter()
+        .filter_map(|m| serde_json::from_str::<Value>(m["content"].as_str().unwrap_or("")).ok())
+        .find(|p| p["server"] == "buzz-agent")
+        .expect("reminder body");
+    let text = nag["text"].as_str().unwrap_or("");
+    assert!(
+        text.contains("buzz messages send"),
+        "reminder should name the command: {text}"
+    );
+    assert!(
+        text.contains("silence is genuinely correct"),
+        "reminder must license silence: {text}"
+    );
+    h.shutdown().await;
+}
+
+/// A real publish attempt through a registered shell tool satisfies the guard:
+/// no reminder, no extra round.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_satisfied_by_registered_shell_send() {
+    let llm = spawn_capturing_llm(vec![
+        openai_shell_send("tc1"),
+        openai_text("posted"),
+        openai_text("must-not-be-requested"),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(&llm.url, &[("BUZZ_AGENT_REQUIRE_REPLY", "1")]).await;
+    let sid = init_session_with_fake_mcp(
+        &mut h,
+        &[("FAKE_MCP_TOOL_COUNT", "1"), ("FAKE_MCP_SHELL_TOOL", "1")],
+    )
+    .await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        2,
+        "a recognized send must not be nagged, got {} LLM calls",
+        captured.len()
+    );
+    assert_eq!(reply_nag_count(&captured[1]), 0);
+    h.shutdown().await;
+}
+
+/// A publish-shaped call to a shell tool that is *not registered* never runs —
+/// preflight rejects it — so it must not disarm the guard. This is what the
+/// `has`/`is_hook` checks in the predicate buy.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_ignores_unregistered_shell_tool() {
+    // FAKE_MCP_SHELL_TOOL is absent, so `fake__shell` is a hallucination.
+    let llm = spawn_capturing_llm(vec![
+        openai_shell_send("tc1"),
+        openai_text("silent-1"),
+        openai_text("silent-2"),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_REQUIRE_REPLY", "1"),
+            ("BUZZ_AGENT_STOP_MAX_REJECTIONS", "1"),
+        ],
+    )
+    .await;
+    let sid = init_session_with_fake_mcp(&mut h, &[("FAKE_MCP_TOOL_COUNT", "1")]).await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        3,
+        "expected the hallucinated call to still be nagged, got {} LLM calls",
+        captured.len()
+    );
+    let msgs = captured[1]["messages"].as_array().unwrap();
+    assert!(
+        msgs.iter()
+            .any(|m| m["role"] == "tool"
+                && m["content"].as_str().unwrap_or("").contains("unknown tool")),
+        "expected preflight to reject the call: {msgs:?}"
+    );
+    assert_eq!(reply_nag_count(&captured[2]), 1);
+    h.shutdown().await;
+}
+
+/// A publish-shaped call discarded by the per-turn tool-call cap never runs,
+/// so it must not suppress the reminder either. Pins the check's placement
+/// after `calls.truncate(MAX_TOOL_CALLS_PER_TURN)`.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_ignores_calls_lost_to_the_turn_cap() {
+    // 64 filler calls (the cap) followed by the publish attempt, which is
+    // therefore truncated away. The shell tool *is* registered here, so only
+    // the placement — not tool identity — can explain the reminder.
+    let mut calls: Vec<Value> = (0..64)
+        .map(|i| {
+            json!({
+                "id": format!("c{i}"),
+                "type": "function",
+                "function": { "name": "fake__tool_0", "arguments": "{}" },
+            })
+        })
+        .collect();
+    calls.push(json!({
+        "id": "c-send",
+        "type": "function",
+        "function": {
+            "name": "fake__shell",
+            "arguments": json!({ "command": "buzz messages send --channel c --content hi" })
+                .to_string(),
+        },
+    }));
+    let truncated_send = json!({
+        "id": "cc-trunc", "object": "chat.completion", "model": "fake-model",
+        "choices": [{
+            "index": 0,
+            "message": { "role": "assistant", "content": null, "tool_calls": calls },
+            "finish_reason": "tool_calls",
+        }],
+    });
+    let llm = spawn_capturing_llm(vec![
+        truncated_send,
+        openai_text("silent-1"),
+        openai_text("silent-2"),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_REQUIRE_REPLY", "1"),
+            ("BUZZ_AGENT_STOP_MAX_REJECTIONS", "1"),
+        ],
+    )
+    .await;
+    let sid = init_session_with_fake_mcp(
+        &mut h,
+        &[("FAKE_MCP_TOOL_COUNT", "1"), ("FAKE_MCP_SHELL_TOOL", "1")],
+    )
+    .await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        3,
+        "a truncated send must still be nagged, got {} LLM calls",
+        captured.len()
+    );
+    assert_eq!(reply_nag_count(&captured[2]), 1);
+    h.shutdown().await;
+}
+
+/// The shared `_Stop` rejection budget is the outer cap: at 1 the guard gets
+/// one reminder instead of two. Documented degradation, not a bug.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_bounded_by_stop_rejection_budget() {
+    let llm = spawn_capturing_llm(vec![
+        openai_text("silent-1"),
+        openai_text("silent-2"),
+        openai_text("must-not-be-requested"),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_REQUIRE_REPLY", "1"),
+            ("BUZZ_AGENT_STOP_MAX_REJECTIONS", "1"),
+        ],
+    )
+    .await;
+    let sid = init_session(&mut h, json!([])).await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        2,
+        "budget 1 must allow exactly one reminder, got {} LLM calls",
+        captured.len()
+    );
+    assert_eq!(reply_nag_count(&captured[1]), 1);
+    h.shutdown().await;
+}
+
+/// Budget 0 disables every objection at the gate, including this one.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_off_when_stop_budget_is_zero() {
+    let llm = spawn_capturing_llm(vec![openai_text("done"), openai_text("unexpected")]).await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_REQUIRE_REPLY", "1"),
+            ("BUZZ_AGENT_STOP_MAX_REJECTIONS", "0"),
+        ],
+    )
+    .await;
+    let sid = init_session(&mut h, json!([])).await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        1,
+        "budget 0 must disable the guard, got {} LLM calls",
+        captured.len()
+    );
+    h.shutdown().await;
+}
+
+/// The two axes are independent inside one shared budget: a round carrying
+/// both a `_Stop` hook objection and a reminder costs one rejection and
+/// delivers both texts, and once the reminders are spent the hook objection
+/// continues alone.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn reply_guard_combines_with_stop_hook_objection() {
+    // The hook objects on its first 3 calls, then clears. Reminders stop
+    // after 2, so round 3 must carry the hook text and no new reminder.
+    let llm = spawn_capturing_llm(vec![
+        openai_text("silent-1"),
+        openai_text("silent-2"),
+        openai_text("silent-3"),
+        openai_text("silent-4"),
+    ])
+    .await;
+    let mut h = Harness::spawn_with_env(
+        &llm.url,
+        &[
+            ("BUZZ_AGENT_REQUIRE_REPLY", "1"),
+            ("MCP_HOOK_SERVERS", "fake"),
+            ("BUZZ_AGENT_STOP_MAX_REJECTIONS", "10"),
+        ],
+    )
+    .await;
+    let sid = init_session_with_fake_mcp(
+        &mut h,
+        &[
+            ("FAKE_MCP_TOOL_COUNT", "1"),
+            ("FAKE_MCP_STOP_HOOK", "1"),
+            ("FAKE_MCP_STOP_TEXT", "you have open todos"),
+            ("FAKE_MCP_STOP_COUNT", "3"),
+        ],
+    )
+    .await;
+
+    let r = prompt_to_completion(&mut h, &sid).await;
+    assert_eq!(r["result"]["stopReason"], "end_turn");
+
+    let captured = llm.captured.lock().await;
+    assert_eq!(
+        captured.len(),
+        4,
+        "expected 3 objecting rounds then a clear end, got {}",
+        captured.len()
+    );
+
+    let hook_objections = |req: &Value| -> usize {
+        req["messages"]
+            .as_array()
+            .map(|msgs| {
+                msgs.iter()
+                    .filter(|m| {
+                        m["content"]
+                            .as_str()
+                            .unwrap_or("")
+                            .contains("you have open todos")
+                    })
+                    .count()
+            })
+            .unwrap_or(0)
+    };
+
+    // Round 2 carries one of each — a single rejection bought both texts.
+    assert_eq!(reply_nag_count(&captured[1]), 1);
+    assert_eq!(hook_objections(&captured[1]), 1);
+    // Round 4: the hook objected three times, the guard only twice.
+    assert_eq!(reply_nag_count(&captured[3]), 2);
+    assert_eq!(hook_objections(&captured[3]), 3);
+    h.shutdown().await;
+}
+
+/// An unparseable toggle is a startup error, not a silent default. `parse_env`
+/// is generic over `FromStr`, so this also pins the numeric type: a `bool`
+/// field would have rejected the documented `1`.
+#[test]
+fn reply_guard_rejects_unparseable_toggle() {
+    let out = std::process::Command::new(env!("CARGO_BIN_EXE_buzz-agent"))
+        .env("BUZZ_AGENT_PROVIDER", "openai")
+        .env("OPENAI_COMPAT_API_KEY", "test")
+        .env("OPENAI_COMPAT_MODEL", "fake-model")
+        .env("BUZZ_AGENT_REQUIRE_REPLY", "true")
+        .stdin(Stdio::null())
+        .output()
+        .expect("run buzz-agent");
+    assert!(
+        !out.status.success(),
+        "expected a config error exit, got {:?}",
+        out.status
+    );
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(
+        stderr.contains("BUZZ_AGENT_REQUIRE_REPLY"),
+        "expected the offending key in the error, got: {stderr}"
+    );
+}
diff --git a/crates/buzz-backend-kubernetes/Cargo.toml b/crates/buzz-backend-kubernetes/Cargo.toml
new file mode 100644
index 0000000000..1cd17030db
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/Cargo.toml
@@ -0,0 +1,36 @@
+[package]
+name = "buzz-backend-kubernetes"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+description = "Kubernetes backend provider for Buzz remote agents (docs/remote-agents.md)"
+
+[[bin]]
+name = "buzz-backend-kubernetes"
+path = "src/main.rs"
+
+[dependencies]
+kube = { workspace = true }
+k8s-openapi = { workspace = true }
+nostr = { workspace = true }
+tokio = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+sha2 = { workspace = true }
+hex = { workspace = true }
+rand = { workspace = true }
+chrono = { workspace = true }
+http = "1"
+http-body-util = "0.1"
+
+# Explicit rustls dep with the ring provider — required to install the
+# process-level CryptoProvider at startup. Without it this binary panics on its
+# first TLS connection to the apiserver: the release build compiles every
+# sidecar in one cargo invocation (.github/workflows/release.yml), which unifies
+# both ring and aws-lc-rs features and leaves rustls unable to auto-select a
+# provider. Same dependency and reason as crates/buzz-cli/Cargo.toml.
+rustls = { version = "0.23", default-features = false, features = ["ring", "std"] }
+
+[dev-dependencies]
+tower = { workspace = true }
diff --git a/crates/buzz-backend-kubernetes/src/classify.rs b/crates/buzz-backend-kubernetes/src/classify.rs
new file mode 100644
index 0000000000..e9cfaba402
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/classify.rs
@@ -0,0 +1,377 @@
+//! The deploy state machine (spec §Deploy State Machine), as a pure function.
+//!
+//! `classify` maps a verified observation plus the desired create intent to
+//! one [`Action`]. It performs no I/O, so every row of the spec's table is a
+//! unit test with no cluster. `reconcile` executes actions and re-enters.
+//!
+//! Two invariants are structural rather than remembered:
+//!
+//! * [`Action::Delete`] carries the [`Fence`] from the exact observation that
+//!   authorized it. There is no way to build a delete without one, so a later
+//!   helper cannot re-read and silently substitute a fresher fence.
+//! * The pull-failure classifier ([`PullFailure`]) reaches only
+//!   [`Action::Report`] and [`Action::Observe`]. It is absent from
+//!   `Action::Delete`'s type, so "reason strings are never deletion
+//!   authority" is enforced by the compiler.
+
+use crate::intent::Fingerprint;
+
+/// The compare-and-delete fence: UID + resourceVersion from the observation
+/// that authorized the deletion. A failed precondition means the object
+/// changed since the read — re-enter, never retry the delete.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Fence {
+    pub uid: String,
+    pub resource_version: String,
+}
+
+/// Why a pod that never started looks permanently broken. Reporting only.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PullFailure {
+    /// Registry auth: a 403/401 `ImagePullBackOff` retries forever without
+    /// ever succeeding, so "the pull retries" is false for this case.
+    Unauthorized,
+    /// The digest or repository does not exist at that registry.
+    ManifestUnknown,
+    /// The image has no variant for the node's architecture.
+    ArchMismatch,
+}
+
+/// The container's startup state, already decoded from pod status. Decoding
+/// happens at the edge so this module stays free of API types.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Startup {
+    /// `state.running` — the harness process is up. This, not pod phase, is
+    /// what "live" means.
+    Started,
+    /// Started once and reached a terminal phase (Succeeded/Failed).
+    Terminated,
+    /// Never started, and self-healing is plausible: unschedulable during
+    /// scale-from-zero, an image pull in progress, a transient
+    /// `CreateContainerConfigError` whose Secret exists.
+    NeverStartedRecoverable,
+    /// Never started, and the provider *verified* the cause — not a reason
+    /// string. Either the referenced Secret is confirmed absent by a
+    /// most-recent read, or the image reference is structurally invalid.
+    NeverStartedProvablyBroken,
+    /// Never started; the pull is failing in a way that will not self-heal.
+    /// Still recoverable in the *never delete* sense — this only changes what
+    /// we report and how long we wait.
+    NeverStartedPullFailing(PullFailure),
+}
+
+/// A pod that passed identity and ownership verification: label-selected,
+/// full-pubkey annotation equal to the derived pubkey, management marker
+/// present. Constructing this type is the verification step's output, so an
+/// unverified object cannot reach `classify` at all.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct VerifiedPod {
+    pub name: String,
+    pub fence: Fence,
+    /// Set once the apiserver accepts a delete. In Kubernetes there is no
+    /// `Terminating` phase — a pod being gracefully deleted stays in phase
+    /// `Running` for its whole grace period — so this must be checked
+    /// *before* startup state or the dying pod reads as the no-op row.
+    pub deletion_marked: bool,
+    pub startup: Startup,
+    /// The `buzz.block.xyz/create-intent` annotation as recorded at create.
+    /// `None` for a pod written before the annotation existed, which counts
+    /// as divergence.
+    pub recorded_intent: Option<Fingerprint>,
+}
+
+/// What the reconciler should do next.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Action {
+    /// Create the pod, then wait for the harness container to start.
+    Create,
+    /// Compare-and-delete, poll for actual disappearance, then re-enter.
+    Delete { name: String, fence: Fence },
+    /// Wait for a deletion already in flight, then re-enter.
+    AwaitDisappearance { name: String },
+    /// Strict no-op: return this `agent_id`, mutate nothing.
+    NoOp { agent_id: String },
+    /// Keep observing until started or the operation deadline expires; on
+    /// expiry report the latest condition. Never deletes, on this call or any
+    /// later one.
+    Observe { name: String },
+    /// Surface an actionable condition immediately rather than burning the
+    /// deadline on a failure that will not self-heal.
+    Report { name: String, failure: PullFailure },
+}
+
+/// Apply the spec's ordered rules to one verified observation.
+///
+/// `desired` is the freshly computed create intent; comparison is always
+/// recorded-annotation vs freshly-computed, never a diff against the live pod
+/// (admission defaulting would make every pod look divergent).
+pub fn classify(observed: Option<&VerifiedPod>, desired: &Fingerprint) -> Action {
+    let Some(pod) = observed else {
+        // Row: no instance → create. First deploy, or after GC.
+        return Action::Create;
+    };
+
+    // Row: deletion-marked, ANY phase. Checked before startup state because
+    // there is no `Terminating` phase to match on — a gracefully deleting pod
+    // reports phase `Running` throughout its grace period, so testing startup
+    // first would mistake it for the live no-op row and return an id that
+    // evaporates.
+    if pod.deletion_marked {
+        return Action::AwaitDisappearance {
+            name: pod.name.clone(),
+        };
+    }
+
+    match &pod.startup {
+        // Row: live and started → strict no-op. Start must never kill a live
+        // agent mid-turn, whatever the fingerprint says.
+        Startup::Started => Action::NoOp {
+            agent_id: pod.name.clone(),
+        },
+
+        // Row: terminated → delete residue, then re-enter to create. This is
+        // the normal restart path — how a user revives a reaped agent.
+        Startup::Terminated => Action::Delete {
+            name: pod.name.clone(),
+            fence: pod.fence.clone(),
+        },
+
+        // Row: never started, provably non-recoverable → fenced replace.
+        // "Provably" means a verified absence or a structural defect, never a
+        // reason string.
+        Startup::NeverStartedProvablyBroken => Action::Delete {
+            name: pod.name.clone(),
+            fence: pod.fence.clone(),
+        },
+
+        // Inside the recoverable row: a pull that will not self-heal is
+        // reported immediately instead of consuming the 600s deadline. This
+        // changes reporting and wait behavior only — no delete authority.
+        Startup::NeverStartedPullFailing(failure) => Action::Report {
+            name: pod.name.clone(),
+            failure: *failure,
+        },
+
+        // Row: never started, recoverable — split on create-intent
+        // divergence. Divergence is evidence of a config change the user is
+        // waiting on, and it is the *only* thing that replaces a
+        // never-started pod. Pod age triggers nothing: any finite age
+        // threshold collides with Cluster Autoscaler's own pod-age delays,
+        // and delete-recreate resets exactly the age it keys on.
+        Startup::NeverStartedRecoverable => {
+            if pod.recorded_intent.as_ref() == Some(desired) {
+                Action::Observe {
+                    name: pod.name.clone(),
+                }
+            } else {
+                Action::Delete {
+                    name: pod.name.clone(),
+                    fence: pod.fence.clone(),
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn fp(seed: &str) -> Fingerprint {
+        Fingerprint::for_test(seed)
+    }
+
+    fn pod(startup: Startup, intent: Option<Fingerprint>) -> VerifiedPod {
+        VerifiedPod {
+            name: "buzz-agent-abc123def456".into(),
+            fence: Fence {
+                uid: "uid-1".into(),
+                resource_version: "rv-1".into(),
+            },
+            deletion_marked: false,
+            startup,
+            recorded_intent: intent,
+        }
+    }
+
+    #[test]
+    fn no_instance_creates() {
+        assert_eq!(classify(None, &fp("a")), Action::Create);
+    }
+
+    #[test]
+    fn started_pod_is_strict_no_op() {
+        let p = pod(Startup::Started, Some(fp("a")));
+        assert_eq!(
+            classify(Some(&p), &fp("a")),
+            Action::NoOp {
+                agent_id: p.name.clone()
+            }
+        );
+    }
+
+    /// The asymmetry the spec states plainly: an edit cannot reach a started
+    /// pod until it exits, but it *can* reach a never-started one — the
+    /// never-started pod is the one the user is editing because it did not
+    /// start.
+    #[test]
+    fn started_pod_no_ops_even_when_intent_diverges() {
+        let p = pod(Startup::Started, Some(fp("old")));
+        assert_eq!(
+            classify(Some(&p), &fp("new")),
+            Action::NoOp {
+                agent_id: p.name.clone()
+            }
+        );
+    }
+
+    /// In Kubernetes a gracefully deleting pod stays in phase `Running`. If
+    /// the deletion mark were checked after startup state, this pod would
+    /// take the no-op row and `deploy` would return an id that evaporates.
+    #[test]
+    fn deletion_mark_beats_every_startup_state() {
+        for startup in [
+            Startup::Started,
+            Startup::Terminated,
+            Startup::NeverStartedRecoverable,
+            Startup::NeverStartedProvablyBroken,
+            Startup::NeverStartedPullFailing(PullFailure::Unauthorized),
+        ] {
+            let mut p = pod(startup.clone(), Some(fp("a")));
+            p.deletion_marked = true;
+            assert_eq!(
+                classify(Some(&p), &fp("a")),
+                Action::AwaitDisappearance {
+                    name: p.name.clone()
+                },
+                "deletion mark ignored for {startup:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn terminated_pod_is_replaced() {
+        let p = pod(Startup::Terminated, Some(fp("a")));
+        assert_eq!(
+            classify(Some(&p), &fp("a")),
+            Action::Delete {
+                name: p.name.clone(),
+                fence: p.fence.clone()
+            }
+        );
+    }
+
+    /// A never-started winner is repairable: pod exists, Secret confirmed
+    /// absent, container never started. A later deploy must delete-recreate
+    /// rather than no-op — the test that pins started-not-phase as the no-op
+    /// criterion.
+    #[test]
+    fn provably_broken_never_started_pod_is_replaced() {
+        let p = pod(Startup::NeverStartedProvablyBroken, Some(fp("a")));
+        assert_eq!(
+            classify(Some(&p), &fp("a")),
+            Action::Delete {
+                name: p.name.clone(),
+                fence: p.fence.clone()
+            }
+        );
+    }
+
+    /// The anti-livelock rule: identical desired intent means *never* delete,
+    /// however long the pod has been pending. Age is not an input to this
+    /// function at all, which is the strongest way to say so.
+    #[test]
+    fn recoverable_with_matching_intent_only_observes() {
+        let p = pod(Startup::NeverStartedRecoverable, Some(fp("same")));
+        assert_eq!(
+            classify(Some(&p), &fp("same")),
+            Action::Observe {
+                name: p.name.clone()
+            }
+        );
+    }
+
+    /// Repeated identical Starts can never delete anything — the same
+    /// classification, arbitrarily many times.
+    #[test]
+    fn repeated_identical_starts_never_delete() {
+        let p = pod(Startup::NeverStartedRecoverable, Some(fp("same")));
+        for _ in 0..100 {
+            assert!(!matches!(
+                classify(Some(&p), &fp("same")),
+                Action::Delete { .. }
+            ));
+        }
+    }
+
+    /// The wedge escape: the user corrected a resource request or image, so
+    /// the never-started pod is built from configuration they have since
+    /// changed. Without this row the edit could never materialize.
+    #[test]
+    fn recoverable_with_divergent_intent_is_replaced() {
+        let p = pod(Startup::NeverStartedRecoverable, Some(fp("old")));
+        assert_eq!(
+            classify(Some(&p), &fp("new")),
+            Action::Delete {
+                name: p.name.clone(),
+                fence: p.fence.clone()
+            }
+        );
+    }
+
+    /// A pod predating the annotation has no recorded intent — that is
+    /// absence, which the spec groups with divergence.
+    #[test]
+    fn missing_recorded_intent_counts_as_divergence() {
+        let p = pod(Startup::NeverStartedRecoverable, None);
+        assert_eq!(
+            classify(Some(&p), &fp("any")),
+            Action::Delete {
+                name: p.name.clone(),
+                fence: p.fence.clone()
+            }
+        );
+    }
+
+    /// Permanent-looking pull failures report immediately instead of burning
+    /// 600s — and, critically, never delete.
+    #[test]
+    fn pull_failures_report_and_never_delete() {
+        for failure in [
+            PullFailure::Unauthorized,
+            PullFailure::ManifestUnknown,
+            PullFailure::ArchMismatch,
+        ] {
+            let p = pod(Startup::NeverStartedPullFailing(failure), Some(fp("a")));
+            // Divergent intent too — still no delete from this arm.
+            for desired in [fp("a"), fp("different")] {
+                assert_eq!(
+                    classify(Some(&p), &desired),
+                    Action::Report {
+                        name: p.name.clone(),
+                        failure
+                    }
+                );
+            }
+        }
+    }
+
+    /// Every delete carries the fence from the observation that authorized
+    /// it. Exhaustive over the delete-producing states, so a future arm that
+    /// forgets is caught here rather than in a cluster.
+    #[test]
+    fn every_delete_carries_the_authorizing_fence() {
+        let states = [
+            (Startup::Terminated, fp("a")),
+            (Startup::NeverStartedProvablyBroken, fp("a")),
+            (Startup::NeverStartedRecoverable, fp("divergent")),
+        ];
+        for (startup, desired) in states {
+            let p = pod(startup, Some(fp("a")));
+            match classify(Some(&p), &desired) {
+                Action::Delete { fence, .. } => assert_eq!(fence, p.fence),
+                other => panic!("expected Delete, got {other:?}"),
+            }
+        }
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/client.rs b/crates/buzz-backend-kubernetes/src/client.rs
new file mode 100644
index 0000000000..0c3bed65b7
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/client.rs
@@ -0,0 +1,182 @@
+//! Cluster auth and client construction (spec §Cluster auth,
+//! `docs/remote-agents.md:985-995`).
+//!
+//! Standard kubeconfig resolution (`$KUBECONFIG` → `~/.kube/config`).
+//! `provider_config` carries `context` and `namespace` only — credentials
+//! never transit config (I2, `:196-198`).
+
+use kube::config::{ExecConfig, KubeConfigOptions, Kubeconfig};
+use kube::{Client, Config};
+use std::path::{Path, PathBuf};
+
+/// Directories prepended to `PATH` before the client is built.
+///
+/// Kubeconfigs at Block near-universally authenticate through `exec`
+/// credential plugins (`aws eks get-token`, `gke-gcloud-auth-plugin`) that
+/// resolve via `PATH` — and this provider inherits a Finder-launched
+/// desktop's minimal `PATH`, which contains none of the places those plugins
+/// install to (`:989-994`).
+const PATH_PREPEND: [&str; 2] = ["/opt/homebrew/bin", "/usr/local/bin"];
+
+/// Compute the new `PATH` value: plugin directories first, inherited entries
+/// after, in order. Pure so the ordering can be tested without mutating the
+/// process's environment.
+fn prepended_path(home: Option<&Path>, existing: &std::ffi::OsStr) -> Option<std::ffi::OsString> {
+    let mut dirs: Vec<PathBuf> = PATH_PREPEND.iter().map(PathBuf::from).collect();
+    if let Some(home) = home {
+        dirs.push(home.join(".local/bin"));
+    }
+    // An empty inherited PATH splits into one empty entry, which POSIX
+    // resolves as the current directory — a place a credential plugin should
+    // never be looked up. Drop empties rather than propagate them.
+    dirs.extend(std::env::split_paths(existing).filter(|p| !p.as_os_str().is_empty()));
+    std::env::join_paths(dirs).ok()
+}
+
+/// Prepend the plugin directories to this process's `PATH`.
+///
+/// Modifies the provider's own environment, which is sound here: one process
+/// per operation, called before any client or task exists, and the child
+/// processes that read it are exactly the credential plugins this exists for.
+fn prepend_plugin_path() {
+    let home = std::env::var_os("HOME");
+    let existing = std::env::var_os("PATH").unwrap_or_default();
+    if let Some(joined) = prepended_path(home.as_ref().map(Path::new), &existing) {
+        std::env::set_var("PATH", joined);
+    }
+}
+
+/// Is `command` runnable — an executable on `PATH`, or an existing path?
+fn resolves_on_path(command: &str) -> bool {
+    if command.contains(std::path::MAIN_SEPARATOR) {
+        return Path::new(command).is_file();
+    }
+    std::env::var_os("PATH")
+        .map(|path| std::env::split_paths(&path).any(|dir| dir.join(command).is_file()))
+        .unwrap_or(false)
+}
+
+/// The exec plugin the selected context authenticates with, if any.
+///
+/// Read from the kubeconfig directly rather than from `Config`, which does not
+/// expose it. A read failure yields `None`: this lookup exists only to improve
+/// an error message, and must never be the thing that fails a deploy.
+fn exec_plugin_for(context: Option<&str>) -> Option<ExecConfig> {
+    let kubeconfig = Kubeconfig::read().ok()?;
+    let context_name = context
+        .map(str::to_string)
+        .or_else(|| kubeconfig.current_context.clone())?;
+    let user_name = kubeconfig
+        .contexts
+        .iter()
+        .find(|c| c.name == context_name)
+        .and_then(|c| c.context.as_ref())
+        .and_then(|c| c.user.clone())?;
+    kubeconfig
+        .auth_infos
+        .iter()
+        .find(|a| a.name == user_name)
+        .and_then(|a| a.auth_info.as_ref())
+        .and_then(|a| a.exec.clone())
+}
+
+/// Turn a client-construction failure into an error a user can act on.
+///
+/// When the context authenticates through an exec plugin that is not on
+/// `PATH`, that is almost always the cause, and the actionable fact is the
+/// plugin's name — not a kube-rs error chain (`:994-995`).
+fn explain(context: Option<&str>, error: &kube::Error) -> String {
+    if let Some(command) = exec_plugin_for(context).and_then(|e| e.command) {
+        if !resolves_on_path(&command) {
+            return format!(
+                "kubeconfig context {} authenticates with the credential plugin \
+                 {command:?}, which is not on PATH. Install it or add its \
+                 directory to PATH, then try again.",
+                context.unwrap_or("(current)")
+            );
+        }
+    }
+    format!(
+        "could not connect to the cluster using kubeconfig context {}: {error}",
+        context.unwrap_or("(current)")
+    )
+}
+
+/// Build a client for the selected context.
+pub async fn connect(context: Option<&str>) -> Result<Client, String> {
+    prepend_plugin_path();
+
+    let options = KubeConfigOptions {
+        context: context.map(str::to_string),
+        ..Default::default()
+    };
+    let config = Config::from_kubeconfig(&options).await.map_err(|e| {
+        // A named context that does not exist is a user typo, and the
+        // kube-rs message for it is already specific.
+        format!(
+            "could not load kubeconfig for context {}: {e}",
+            context.unwrap_or("(current)")
+        )
+    })?;
+
+    Client::try_from(config).map_err(|e| explain(context, &e))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The three plugin directories must end up ahead of the inherited PATH,
+    /// or a Finder-launched desktop never finds `aws`/`gke-gcloud-auth-plugin`.
+    /// Tested on the pure computation: mutating the process PATH here would
+    /// race every other test in the binary.
+    #[test]
+    fn plugin_directories_are_prepended_in_order() {
+        let joined = prepended_path(
+            Some(Path::new("/tmp/fake-home")),
+            std::ffi::OsStr::new("/inherited/bin:/usr/bin"),
+        )
+        .unwrap();
+        let dirs: Vec<PathBuf> = std::env::split_paths(&joined).collect();
+        assert_eq!(
+            dirs,
+            [
+                "/opt/homebrew/bin",
+                "/usr/local/bin",
+                "/tmp/fake-home/.local/bin",
+                "/inherited/bin",
+                "/usr/bin",
+            ]
+            .map(PathBuf::from)
+        );
+    }
+
+    /// No `HOME` is not a failure — the two absolute directories still apply.
+    #[test]
+    fn missing_home_still_prepends_the_absolute_directories() {
+        let joined = prepended_path(None, std::ffi::OsStr::new("/inherited/bin")).unwrap();
+        let dirs: Vec<PathBuf> = std::env::split_paths(&joined).collect();
+        assert_eq!(
+            dirs,
+            ["/opt/homebrew/bin", "/usr/local/bin", "/inherited/bin"].map(PathBuf::from)
+        );
+    }
+
+    /// An empty inherited PATH must not produce an empty entry, which the
+    /// shell and `resolves_on_path` would both read as the cwd.
+    #[test]
+    fn empty_inherited_path_yields_no_empty_entry() {
+        let joined = prepended_path(None, std::ffi::OsStr::new("")).unwrap();
+        let dirs: Vec<PathBuf> = std::env::split_paths(&joined).collect();
+        assert_eq!(
+            dirs,
+            ["/opt/homebrew/bin", "/usr/local/bin"].map(PathBuf::from)
+        );
+    }
+
+    #[test]
+    fn resolves_absolute_paths_directly() {
+        assert!(resolves_on_path("/bin/sh"));
+        assert!(!resolves_on_path("/nonexistent/plugin-binary"));
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/cluster.rs b/crates/buzz-backend-kubernetes/src/cluster.rs
new file mode 100644
index 0000000000..755f41f6c8
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/cluster.rs
@@ -0,0 +1,427 @@
+//! The real [`Substrate`]: kube-rs against a live apiserver.
+//!
+//! Everything that *decides* lives in `classify`/`gc`; this module only
+//! performs I/O and maps apiserver responses onto the trait's vocabulary.
+//! Three mappings here are normative rather than incidental:
+//!
+//! * **409 is discriminated on `Status.reason`, never on the code.** A create
+//!   409 is `AlreadyExists`; a delete 409 from a failed precondition is
+//!   `Conflict`. Branching on `code == 409` conflates a lost create race with
+//!   a stale fence and is the trap the spec names (`:780-794`).
+//! * **Reads leave `resourceVersion` unset**, which is the quorum read. `"0"`
+//!   is the cache read, and a confirmed absence from a cache is proof of
+//!   nothing (`:761-769`).
+//! * **Deletes never set `grace_period_seconds`**, so the object's own 60s
+//!   budget applies. Passing `0` is a force-kill that discards the shutdown
+//!   window the pod declares (`:1185-1189`).
+
+use crate::classify::Fence;
+use crate::reconcile::{CreateOutcome, DeleteOutcome, Substrate};
+use chrono::{DateTime, Utc};
+use k8s_openapi::api::core::v1::{Namespace, Pod, Secret};
+use kube::api::{Api, DeleteParams, GetParams, ListParams, PostParams, Preconditions};
+use kube::core::ErrorResponse;
+use kube::{Client, Resource};
+use std::time::{Duration, Instant};
+
+/// `Status.reason` values we branch on. Spelled once so the two 409 arms are
+/// visibly the same discriminator read two ways.
+///
+/// These are wire strings `apimachinery` chooses, not names this crate picks:
+/// `StatusReasonAlreadyExists`, `StatusReasonConflict`, `StatusReasonNotFound`,
+/// and `StatusReasonForbidden` in `k8s.io/apimachinery/pkg/apis/meta/v1/types.go`.
+/// kube-core types `ErrorResponse::reason` as a bare `String`, so there is no
+/// upstream constant to bind to and the spelling is pinned by test instead.
+const REASON_ALREADY_EXISTS: &str = "AlreadyExists";
+const REASON_CONFLICT: &str = "Conflict";
+const REASON_NOT_FOUND: &str = "NotFound";
+const REASON_FORBIDDEN: &str = "Forbidden";
+
+/// The apiserver-backed substrate for one deploy operation.
+pub struct Cluster {
+    client: Client,
+    namespace: String,
+    /// Start of *this operation*, for the deadline. Monotonic: the 600s budget
+    /// must not move when the wall clock does.
+    started: Instant,
+}
+
+/// The typed API error underneath a `kube::Error`, if it is one.
+fn api_error(error: &kube::Error) -> Option<&ErrorResponse> {
+    match error {
+        kube::Error::Api(response) => Some(response),
+        _ => None,
+    }
+}
+
+/// Does this error carry the given `Status.reason`?
+fn reason_is(error: &kube::Error, reason: &str) -> bool {
+    api_error(error).is_some_and(|e| e.reason == reason)
+}
+
+impl Cluster {
+    pub fn new(client: Client, namespace: &str) -> Self {
+        Self {
+            client,
+            namespace: namespace.to_string(),
+            started: Instant::now(),
+        }
+    }
+
+    fn pods(&self) -> Api<Pod> {
+        Api::namespaced(self.client.clone(), &self.namespace)
+    }
+
+    fn secrets(&self) -> Api<Secret> {
+        Api::namespaced(self.client.clone(), &self.namespace)
+    }
+
+    /// List an object kind through the raw client so the response's HTTP
+    /// `Date` header is reachable.
+    ///
+    /// `Api::list` returns only the decoded body, and the apiserver's clock is
+    /// the *only* clock the orphan-Secret age gate may use — a desktop's local
+    /// clock running fast computes every in-flight Secret as expired
+    /// (`:1321-1335`). So the list goes through `Client::send`, which hands
+    /// back the whole `http::Response`.
+    async fn list_with_date<K>(
+        &self,
+        selector: &str,
+    ) -> Result<(Vec<K>, Option<DateTime<Utc>>), String>
+    where
+        K: Resource<Scope = k8s_openapi::NamespaceResourceScope>
+            + Clone
+            + serde::de::DeserializeOwned
+            + std::fmt::Debug,
+        K::DynamicType: Default,
+    {
+        let dt = K::DynamicType::default();
+        let url = K::url_path(&dt, Some(&self.namespace));
+        // resourceVersion deliberately unset: quorum read.
+        let params = ListParams {
+            label_selector: Some(selector.to_string()),
+            ..Default::default()
+        };
+        let request = kube::core::Request::new(url)
+            .list(&params)
+            .map_err(|e| format!("could not build a list request: {e}"))?;
+        let (parts, body) = request.into_parts();
+        let response = self
+            .client
+            .send(http::Request::from_parts(parts, body.into()))
+            .await
+            .map_err(|e| format!("could not list {}: {e}", K::plural(&dt)))?;
+
+        // Parsed before the body is consumed, and independently of it: a
+        // missing or malformed header is not a list failure, it just means the
+        // orphan sweep has no clock and skips.
+        let server_now = response
+            .headers()
+            .get(http::header::DATE)
+            .and_then(|v| v.to_str().ok())
+            .and_then(|v| DateTime::parse_from_rfc2822(v).ok())
+            .map(|v| v.with_timezone(&Utc));
+
+        let bytes = http_body_util::BodyExt::collect(response.into_body())
+            .await
+            .map_err(|e| format!("could not read the {} list body: {e}", K::plural(&dt)))?
+            .to_bytes();
+        let list: kube::core::ObjectList<K> = serde_json::from_slice(&bytes)
+            .map_err(|e| format!("could not decode the {} list: {e}", K::plural(&dt)))?;
+
+        Ok((list.items, server_now))
+    }
+}
+
+impl Substrate for Cluster {
+    async fn ensure_namespace(&self, namespace: &str) -> Result<(), String> {
+        let api: Api<Namespace> = Api::all(self.client.clone());
+        if api
+            .get_opt(namespace)
+            .await
+            .map_err(|e| format!("could not check whether namespace {namespace} exists: {e}"))?
+            .is_some()
+        {
+            return Ok(());
+        }
+
+        let spec = Namespace {
+            metadata: kube::core::ObjectMeta {
+                name: Some(namespace.to_string()),
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+        match api.create(&PostParams::default(), &spec).await {
+            Ok(_) => Ok(()),
+            // Someone else created it between our check and our create. That
+            // is the desired end state, not a failure.
+            Err(e) if reason_is(&e, REASON_ALREADY_EXISTS) => Ok(()),
+            // Namespace-create is frequently denied on shared clusters. Name
+            // the exact command an operator runs, and never silently fall back
+            // to `default` — deploying an agent into someone else's namespace
+            // is worse than refusing (`:1002-1005`).
+            Err(e) if reason_is(&e, REASON_FORBIDDEN) => Err(format!(
+                "not authorized to create namespace {namespace}. Ask a cluster \
+                 administrator to run `kubectl create namespace {namespace}`, \
+                 then try again."
+            )),
+            Err(e) => Err(format!("could not create namespace {namespace}: {e}")),
+        }
+    }
+
+    async fn list_pods(&self, selector: &str) -> Result<(Vec<Pod>, Option<DateTime<Utc>>), String> {
+        self.list_with_date::<Pod>(selector).await
+    }
+
+    async fn list_secrets(&self, selector: &str) -> Result<Vec<Secret>, String> {
+        Ok(self.list_with_date::<Secret>(selector).await?.0)
+    }
+
+    async fn secret_exists(&self, name: &str) -> Result<bool, String> {
+        // `GetParams::default()` leaves resourceVersion unset — the quorum
+        // read this check requires to be proof of anything.
+        match self.secrets().get_with(name, &GetParams::default()).await {
+            Ok(_) => Ok(true),
+            Err(e) if reason_is(&e, REASON_NOT_FOUND) => Ok(false),
+            Err(e) => Err(format!("could not check whether secret {name} exists: {e}")),
+        }
+    }
+
+    async fn create_secret(&self, secret: &Secret) -> Result<(), String> {
+        let name = secret.metadata.name.clone().unwrap_or_default();
+        self.secrets()
+            .create(&PostParams::default(), secret)
+            .await
+            .map(|_| ())
+            .map_err(|e| format!("could not create secret {name}: {e}"))
+    }
+
+    async fn create_pod(&self, pod: &Pod) -> Result<CreateOutcome, String> {
+        let name = pod.metadata.name.clone().unwrap_or_default();
+        match self.pods().create(&PostParams::default(), pod).await {
+            Ok(_) => Ok(CreateOutcome::Created),
+            // The deterministic name is taken: a concurrent attempt won the
+            // election. Discriminated on the reason — a 409 whose reason is
+            // `Conflict` is a different condition and must not be read as a
+            // lost race.
+            Err(e) if reason_is(&e, REASON_ALREADY_EXISTS) => Ok(CreateOutcome::AlreadyExists),
+            Err(e) => Err(format!("could not create pod {name}: {e}")),
+        }
+    }
+
+    async fn delete_pod(&self, name: &str, fence: &Fence) -> Result<DeleteOutcome, String> {
+        let params = DeleteParams {
+            preconditions: Some(Preconditions {
+                uid: Some(fence.uid.clone()),
+                resource_version: Some(fence.resource_version.clone()),
+            }),
+            // grace_period_seconds deliberately unset: the pod's own 60s
+            // budget applies.
+            ..Default::default()
+        };
+        match self.pods().delete(name, &params).await {
+            Ok(_) => Ok(DeleteOutcome::Accepted),
+            Err(e) if reason_is(&e, REASON_NOT_FOUND) => Ok(DeleteOutcome::NotFound),
+            // The object changed since the observation that authorized this
+            // delete. Same HTTP code as the create race above, different
+            // reason, different meaning.
+            Err(e) if reason_is(&e, REASON_CONFLICT) => Ok(DeleteOutcome::PreconditionFailed),
+            Err(e) => Err(format!("could not delete pod {name}: {e}")),
+        }
+    }
+
+    async fn delete_secret(&self, name: &str) -> Result<(), String> {
+        match self.secrets().delete(name, &DeleteParams::default()).await {
+            Ok(_) => Ok(()),
+            // Already gone is the desired end state.
+            Err(e) if reason_is(&e, REASON_NOT_FOUND) => Ok(()),
+            Err(e) => Err(format!("could not delete secret {name}: {e}")),
+        }
+    }
+
+    async fn get_pod(&self, name: &str) -> Result<Option<Pod>, String> {
+        match self.pods().get_with(name, &GetParams::default()).await {
+            Ok(pod) => Ok(Some(pod)),
+            Err(e) if reason_is(&e, REASON_NOT_FOUND) => Ok(None),
+            Err(e) => Err(format!("could not read pod {name}: {e}")),
+        }
+    }
+
+    async fn sleep(&self, duration: Duration) {
+        tokio::time::sleep(duration).await;
+    }
+
+    fn elapsed(&self) -> Duration {
+        self.started.elapsed()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use http::Response;
+    use kube::client::Body;
+    use std::sync::{Arc, Mutex};
+    use tower::service_fn;
+
+    fn list_response(date: Option<&str>) -> Response<Body> {
+        let mut response = Response::builder().status(200);
+        if let Some(date) = date {
+            response = response.header(http::header::DATE, date);
+        }
+        response
+            .body(Body::from(
+                serde_json::to_vec(&serde_json::json!({
+                    "apiVersion": "v1",
+                    "kind": "PodList",
+                    "metadata": {"resourceVersion": "17"},
+                    "items": [{
+                        "apiVersion": "v1",
+                        "kind": "Pod",
+                        "metadata": {"name": "sprig"},
+                        "spec": {"containers": [{"name": "agent", "image": "example.invalid/sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}]}
+                    }]
+                }))
+                .unwrap(),
+            ))
+            .unwrap()
+    }
+
+    async fn list_through_real_request_path(
+        date: Option<&'static str>,
+    ) -> (Vec<Pod>, Option<DateTime<Utc>>, String) {
+        let observed_uri = Arc::new(Mutex::new(None));
+        let service_uri = Arc::clone(&observed_uri);
+        let service = service_fn(move |request: http::Request<Body>| {
+            let service_uri = Arc::clone(&service_uri);
+            async move {
+                *service_uri.lock().unwrap() = Some(request.uri().to_string());
+                Ok::<_, std::convert::Infallible>(list_response(date))
+            }
+        });
+        let cluster = Cluster::new(Client::new(service, "ignored"), "owned-ns");
+        let result = cluster
+            .list_with_date::<Pod>("app.kubernetes.io/managed-by=buzz-backend-kubernetes")
+            .await
+            .unwrap();
+        let uri = observed_uri.lock().unwrap().take().unwrap();
+        (result.0, result.1, uri)
+    }
+
+    /// Exercise the shipped `Request` + `Client::send` seam. A fake
+    /// reconciler would not prove that kube-rs emits a quorum list request or
+    /// that the apiserver's clock survives body decoding.
+    #[tokio::test]
+    async fn list_with_date_uses_a_quorum_request_and_returns_the_server_clock() {
+        let (pods, server_now, uri) =
+            list_through_real_request_path(Some("Sun, 02 Aug 2026 04:00:00 GMT")).await;
+
+        assert_eq!(pods.len(), 1, "fixture must contain one decoded pod");
+        assert_eq!(pods[0].metadata.name.as_deref(), Some("sprig"));
+        assert!(uri.starts_with("/api/v1/namespaces/owned-ns/pods?"));
+        assert!(
+            uri.contains("labelSelector=app.kubernetes.io%2Fmanaged-by%3Dbuzz-backend-kubernetes")
+        );
+        assert!(
+            !uri.contains("resourceVersion"),
+            "cache read leaked into {uri}"
+        );
+        assert_eq!(
+            server_now.unwrap().to_rfc3339(),
+            "2026-08-02T04:00:00+00:00"
+        );
+    }
+
+    /// Header failure is deliberately not list failure: without a trustworthy
+    /// apiserver clock the orphan sweep skips, but normal reconciliation still
+    /// receives the decoded objects.
+    #[tokio::test]
+    async fn list_with_date_keeps_items_when_the_server_clock_is_unusable() {
+        for date in [Some("not a date"), None] {
+            let (pods, server_now, _) = list_through_real_request_path(date).await;
+            assert_eq!(pods.len(), 1, "fixture must contain one decoded pod");
+            assert!(server_now.is_none(), "unexpected clock for {date:?}");
+        }
+    }
+
+    /// A typed apiserver error, as kube-rs surfaces it.
+    fn api(reason: &str, code: u16) -> kube::Error {
+        kube::Error::Api(ErrorResponse {
+            status: "Failure".into(),
+            message: String::new(),
+            reason: reason.into(),
+            code,
+        })
+    }
+
+    /// The one discriminator the whole file rests on, and the trap the spec
+    /// predicts: "an implementation that branches on the code alone will
+    /// eventually take the adoption path on a failed delete or vice versa"
+    /// (`:788-790`).
+    ///
+    /// Both of these are 409. Reading the *code* makes them identical; reading
+    /// `Status.reason` keeps a lost create race and a stale fence apart. The
+    /// mutation that must fail this test is `e.reason == …` → `e.code == 409`,
+    /// which no other test in the crate would catch — the fakes never produce
+    /// a real `kube::Error`.
+    #[test]
+    fn the_two_409s_are_never_conflated() {
+        let already_exists = api(REASON_ALREADY_EXISTS, 409);
+        let conflict = api(REASON_CONFLICT, 409);
+
+        assert!(reason_is(&already_exists, REASON_ALREADY_EXISTS));
+        assert!(reason_is(&conflict, REASON_CONFLICT));
+        // The cross terms are the whole point.
+        assert!(!reason_is(&already_exists, REASON_CONFLICT));
+        assert!(!reason_is(&conflict, REASON_ALREADY_EXISTS));
+    }
+
+    /// A transport-level failure is not an apiserver verdict. It must fall
+    /// through to the error arm rather than being read as any reason — a
+    /// connection reset silently classified as `NotFound` would report a pod
+    /// as confirmed-absent, which the classifier treats as proof.
+    #[test]
+    fn a_non_api_error_carries_no_reason() {
+        let transport = kube::Error::LinesCodecMaxLineLengthExceeded;
+        assert!(api_error(&transport).is_none());
+        for reason in [
+            REASON_ALREADY_EXISTS,
+            REASON_CONFLICT,
+            REASON_NOT_FOUND,
+            REASON_FORBIDDEN,
+        ] {
+            assert!(!reason_is(&transport, reason), "matched {reason}");
+        }
+    }
+
+    /// `reason` is `#[serde(default)]` in kube-core, so an apiserver that
+    /// omits it yields an empty string. That must match nothing rather than
+    /// matching an empty pattern by accident.
+    #[test]
+    fn an_absent_reason_matches_nothing() {
+        let bare = api("", 409);
+        assert!(!reason_is(&bare, REASON_ALREADY_EXISTS));
+        assert!(!reason_is(&bare, REASON_CONFLICT));
+    }
+
+    /// The consts are the apiserver's spelling, asserted against literals
+    /// rather than against themselves.
+    ///
+    /// Every other test here references the consts symbolically on both sides
+    /// — fixture *and* assertion — which is true for any pair of distinct
+    /// values. That tests the discriminator is self-consistent, not that it is
+    /// correct: swapping the two 409 values inverts `AlreadyExists` and
+    /// `Conflict` at a real apiserver (`:788-790`'s failure, reached by
+    /// editing a string instead of a branch) with every other test still
+    /// green. These are `apimachinery`'s wire strings and kube-core exposes no
+    /// constant for them, so a literal is the only external anchor available.
+    /// Found by Quinn's mutation matrix; M2/M3/M4 survived without it.
+    #[test]
+    fn the_reason_consts_are_the_apiservers_spelling() {
+        assert_eq!(REASON_ALREADY_EXISTS, "AlreadyExists");
+        assert_eq!(REASON_CONFLICT, "Conflict");
+        assert_eq!(REASON_NOT_FOUND, "NotFound");
+        assert_eq!(REASON_FORBIDDEN, "Forbidden");
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/config.rs b/crates/buzz-backend-kubernetes/src/config.rs
new file mode 100644
index 0000000000..4d96735b7b
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/config.rs
@@ -0,0 +1,470 @@
+//! `provider_config` parsing and the `info` config schema
+//! (spec §`provider_config` v1 fields, `docs/remote-agents.md:1384-1389`).
+//!
+//! Nine fields, all optional except `image` (required at parse time; the
+//! schema offers the published sprig image as a prefill default — §Image).
+//! No credential field exists, by I2: cluster auth comes from ambient
+//! kubeconfig resolution and nothing else (`:196-198`).
+
+use crate::image::{self, ImageRef};
+
+/// Resource requests and limits (§Pod shape: 1cpu/2Gi → 2cpu/4Gi, all four
+/// configurable — `cargo build` in an agent workspace makes 500m/1Gi
+/// unrealistic).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Resources {
+    pub cpu_request: String,
+    pub memory_request: String,
+    pub cpu_limit: String,
+    pub memory_limit: String,
+}
+
+impl Default for Resources {
+    fn default() -> Self {
+        Self {
+            cpu_request: "1".into(),
+            memory_request: "2Gi".into(),
+            cpu_limit: "2".into(),
+            memory_limit: "4Gi".into(),
+        }
+    }
+}
+
+/// Default inactivity budget: the I5 opt-in (§Auto-Stop). The config field and
+/// `BUZZ_ACP_EXIT_AFTER_INACTIVITY` are one knob, not two.
+pub const DEFAULT_INACTIVITY_SECONDS: u64 = 7200;
+
+/// Default `image` schema prefill: the published sprig image, in tag+digest
+/// form so the tag stays human-traceable to its git SHA while the digest does
+/// the pinning (§Image — tag-only refs are rejected; `image::parse` drops the
+/// tag on normalization). This is a UI prefill, not a baked fallback: `image`
+/// stays required, an empty value still fails closed, and the value always
+/// arrives explicitly in `provider_config`, so create-intent fingerprints are
+/// unaffected by provider upgrades.
+pub const DEFAULT_IMAGE: &str = "ghcr.io/block/buzz-sprig:sha-6530b58@sha256:17facfc7608d8ddb33bc056c9aaba1098f4ef6abe5655702fbfd7584d1f74d76";
+
+/// Fixed nonzero UID/GID for the agent container (§Pod shape hardening).
+pub const RUN_AS_UID: i64 = 10001;
+pub const RUN_AS_GID: i64 = 10001;
+
+/// Writable workspace root; also `HOME` and the harness's cwd
+/// (§Working directory).
+pub const WORKSPACE_PATH: &str = "/home/agent";
+
+/// `terminationGracePeriodSeconds` — a declared budget, not a derived sum
+/// (§Pod shape). Kubernetes' default 30s would SIGKILL the harness mid-drain.
+pub const TERMINATION_GRACE_SECONDS: i64 = 60;
+
+/// The only restart policy v1 ships. `OnFailure` is double-gated on the
+/// harness exit-code contract *and* a crash-loop classification row the state
+/// machine does not have (`:1121-1139`); until both land the provider refuses
+/// the combination rather than shipping against an undefended convention.
+pub const RESTART_POLICY: &str = "Never";
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderConfig {
+    /// kubeconfig context; `None` uses the current context.
+    pub context: Option<String>,
+    pub namespace: String,
+    pub image: ImageRef,
+    pub resources: Resources,
+    /// `None` when `inactivity_seconds` was 0 — refused in v1, see [`parse`].
+    pub inactivity_seconds: Option<u64>,
+    pub service_account: Option<String>,
+}
+
+/// Read an optional non-empty string field. Rejects non-string scalars rather
+/// than stringifying them, so a mistyped field is named at the boundary.
+fn optional_string(cfg: &serde_json::Value, field: &str) -> Result<Option<String>, String> {
+    match cfg.get(field) {
+        None | Some(serde_json::Value::Null) => Ok(None),
+        Some(serde_json::Value::String(s)) if s.trim().is_empty() => Ok(None),
+        Some(serde_json::Value::String(s)) => Ok(Some(s.trim().to_string())),
+        Some(other) => Err(format!(
+            "provider_config.{field} must be a string, got {other}"
+        )),
+    }
+}
+
+/// Read an optional unsigned integer. The desktop's form omits blank numeric
+/// fields rather than sending `""`, but a hand-crafted payload may send a
+/// numeric string — accept both, refuse anything else.
+fn optional_u64(cfg: &serde_json::Value, field: &str) -> Result<Option<u64>, String> {
+    match cfg.get(field) {
+        None | Some(serde_json::Value::Null) => Ok(None),
+        Some(serde_json::Value::Number(n)) => n.as_u64().map(Some).ok_or_else(|| {
+            format!("provider_config.{field} must be a non-negative integer, got {n}")
+        }),
+        Some(serde_json::Value::String(s)) if s.trim().is_empty() => Ok(None),
+        Some(serde_json::Value::String(s)) => s.trim().parse::<u64>().map(Some).map_err(|_| {
+            format!("provider_config.{field} must be a non-negative integer, got {s:?}")
+        }),
+        Some(other) => Err(format!(
+            "provider_config.{field} must be a non-negative integer, got {other}"
+        )),
+    }
+}
+
+/// A Kubernetes namespace name: RFC 1123 label, ≤63 chars. Validated here so a
+/// typo fails with a named field instead of an apiserver rejection partway
+/// through a deploy.
+fn valid_namespace(name: &str) -> bool {
+    !name.is_empty()
+        && name.len() <= 63
+        && name.starts_with(|c: char| c.is_ascii_lowercase() || c.is_ascii_digit())
+        && name.ends_with(|c: char| c.is_ascii_lowercase() || c.is_ascii_digit())
+        && name
+            .chars()
+            .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-')
+}
+
+pub fn parse(cfg: &serde_json::Value) -> Result<ProviderConfig, String> {
+    if !cfg.is_object() && !cfg.is_null() {
+        return Err("provider_config must be a JSON object".to_string());
+    }
+
+    let namespace = optional_string(cfg, "namespace")?.ok_or_else(|| {
+        "provider_config.namespace is required: the info schema supplies a \
+         generated default, so an empty value means the form was cleared"
+            .to_string()
+    })?;
+    if !valid_namespace(&namespace) {
+        return Err(format!(
+            "provider_config.namespace {namespace:?} is not a valid Kubernetes \
+             namespace (lowercase alphanumerics and '-', ≤63 characters)"
+        ));
+    }
+
+    let image = image::parse(optional_string(cfg, "image")?.unwrap_or_default().as_str())?;
+
+    let defaults = Resources::default();
+    let resources = Resources {
+        cpu_request: optional_string(cfg, "cpu_request")?.unwrap_or(defaults.cpu_request),
+        memory_request: optional_string(cfg, "memory_request")?.unwrap_or(defaults.memory_request),
+        cpu_limit: optional_string(cfg, "cpu_limit")?.unwrap_or(defaults.cpu_limit),
+        memory_limit: optional_string(cfg, "memory_limit")?.unwrap_or(defaults.memory_limit),
+    };
+
+    // `inactivity_seconds: 0` is a legal, blessed value in the spec (§Auto-Stop)
+    // meaning "no auto-stop" — but it selects `restartPolicy: OnFailure`, which
+    // §Pod shape forbids until the harness exit-code contract is pinned AND the
+    // state machine gains a crash-loop row. Refusing the *combination* is what
+    // the spec asks for; silently downgrading to `Never` would ship an
+    // indefinite agent that dies on its first crash.
+    let inactivity_seconds = match optional_u64(cfg, "inactivity_seconds")? {
+        None => Some(DEFAULT_INACTIVITY_SECONDS),
+        Some(0) => {
+            return Err(
+                "provider_config.inactivity_seconds: 0 (indefinite lifetime) is not \
+                 supported in this version: it requires restartPolicy OnFailure, \
+                 which is gated on the harness exit-code contract. Set a positive \
+                 number of seconds."
+                    .to_string(),
+            )
+        }
+        Some(n) => Some(n),
+    };
+
+    Ok(ProviderConfig {
+        context: optional_string(cfg, "context")?,
+        namespace,
+        image,
+        resources,
+        inactivity_seconds,
+        service_account: optional_string(cfg, "service_account")?,
+    })
+}
+
+/// A fresh `buzz-agents-<rand6>` namespace default.
+///
+/// Computed per `info` call, which is how "random default" is satisfied with
+/// zero UI changes: the schema's `default` prefills the form (§K8s Namespace).
+pub fn generated_namespace() -> String {
+    use rand::RngExt;
+    const ALPHABET: &[u8] = b"abcdefghijklmnopqrstuvwxyz0123456789";
+    let mut rng = rand::rng();
+    let suffix: String = (0..6)
+        .map(|_| ALPHABET[rng.random_range(0..ALPHABET.len())] as char)
+        .collect();
+    format!("buzz-agents-{suffix}")
+}
+
+/// The `config_schema` returned by `info`. Drives the UI form:
+/// `properties[*].default` prefill, scalar coercion, `required` gating
+/// (`:407-411`).
+pub fn config_schema() -> serde_json::Value {
+    let defaults = Resources::default();
+    serde_json::json!({
+        "type": "object",
+        "properties": {
+            "context": {
+                "type": "string",
+                "title": "Kubeconfig context",
+                "description": "Context from your kubeconfig. Leave empty to use the current context."
+            },
+            "namespace": {
+                "type": "string",
+                "title": "Namespace",
+                "description": "Created if it does not exist.",
+                "default": generated_namespace()
+            },
+            "image": {
+                "type": "string",
+                "title": "Agent image",
+                "description": "Digest-pinned image containing the buzz-acp runtime ABI, e.g. ghcr.io/block/buzz-sprig@sha256:<digest>. Tags alone are not accepted: this pod holds the agent's private key.",
+                "default": DEFAULT_IMAGE
+            },
+            "cpu_request": {
+                "type": "string", "title": "CPU request", "default": defaults.cpu_request
+            },
+            "memory_request": {
+                "type": "string", "title": "Memory request", "default": defaults.memory_request
+            },
+            "cpu_limit": {
+                "type": "string", "title": "CPU limit", "default": defaults.cpu_limit
+            },
+            "memory_limit": {
+                "type": "string", "title": "Memory limit", "default": defaults.memory_limit
+            },
+            "inactivity_seconds": {
+                "type": "number",
+                "title": "Stop after inactivity (seconds)",
+                "description": "The agent exits after this long with no work, and can be started again at any time.",
+                "default": DEFAULT_INACTIVITY_SECONDS
+            },
+            "service_account": {
+                "type": "string",
+                "title": "Service account",
+                "description": "Scheduling/RBAC identity only. No API token is mounted."
+            }
+        },
+        "required": ["namespace", "image"]
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn digest_ref() -> String {
+        format!("ghcr.io/block/buzz-sprig@sha256:{}", "a".repeat(64))
+    }
+
+    fn minimal() -> serde_json::Value {
+        serde_json::json!({"namespace": "buzz-agents-abc123", "image": digest_ref()})
+    }
+
+    #[test]
+    fn applies_spec_defaults() {
+        let c = parse(&minimal()).unwrap();
+        assert_eq!(c.resources, Resources::default());
+        assert_eq!(c.resources.cpu_request, "1");
+        assert_eq!(c.resources.memory_request, "2Gi");
+        assert_eq!(c.resources.cpu_limit, "2");
+        assert_eq!(c.resources.memory_limit, "4Gi");
+        assert_eq!(c.inactivity_seconds, Some(DEFAULT_INACTIVITY_SECONDS));
+        assert_eq!(c.context, None);
+        assert_eq!(c.service_account, None);
+    }
+
+    #[test]
+    fn all_four_resources_are_configurable() {
+        let mut cfg = minimal();
+        cfg["cpu_request"] = "500m".into();
+        cfg["memory_request"] = "1Gi".into();
+        cfg["cpu_limit"] = "4".into();
+        cfg["memory_limit"] = "8Gi".into();
+        let c = parse(&cfg).unwrap();
+        assert_eq!(
+            c.resources,
+            Resources {
+                cpu_request: "500m".into(),
+                memory_request: "1Gi".into(),
+                cpu_limit: "4".into(),
+                memory_limit: "8Gi".into(),
+            }
+        );
+    }
+
+    /// The desktop's form omits blank numeric fields; a hand-crafted payload
+    /// may send a numeric string. Both must mean the same thing.
+    #[test]
+    fn inactivity_accepts_number_string_and_omission() {
+        let mut cfg = minimal();
+        cfg["inactivity_seconds"] = serde_json::json!(300);
+        assert_eq!(parse(&cfg).unwrap().inactivity_seconds, Some(300));
+
+        cfg["inactivity_seconds"] = serde_json::json!("300");
+        assert_eq!(parse(&cfg).unwrap().inactivity_seconds, Some(300));
+
+        cfg["inactivity_seconds"] = serde_json::json!("");
+        assert_eq!(
+            parse(&cfg).unwrap().inactivity_seconds,
+            Some(DEFAULT_INACTIVITY_SECONDS)
+        );
+    }
+
+    /// Indefinite lifetime selects `OnFailure`, which is gated. Refuse rather
+    /// than silently downgrade — a downgraded agent dies on its first crash
+    /// while the user believes they asked for indefinite.
+    #[test]
+    fn refuses_indefinite_lifetime() {
+        let mut cfg = minimal();
+        cfg["inactivity_seconds"] = serde_json::json!(0);
+        let err = parse(&cfg).unwrap_err();
+        assert!(err.contains("inactivity_seconds"), "got: {err}");
+        assert!(
+            err.contains("OnFailure"),
+            "error should name the gate: {err}"
+        );
+    }
+
+    #[test]
+    fn rejects_negative_and_non_numeric_inactivity() {
+        for bad in [
+            serde_json::json!(-1),
+            serde_json::json!(1.5),
+            serde_json::json!("soon"),
+            serde_json::json!(true),
+        ] {
+            let mut cfg = minimal();
+            cfg["inactivity_seconds"] = bad.clone();
+            assert!(parse(&cfg).is_err(), "accepted {bad}");
+        }
+    }
+
+    #[test]
+    fn image_is_required_and_must_be_digest_pinned() {
+        let mut cfg = minimal();
+        cfg.as_object_mut().unwrap().remove("image");
+        assert!(parse(&cfg).unwrap_err().contains("provider_config.image"));
+
+        cfg["image"] = "ghcr.io/block/buzz-sprig:latest".into();
+        assert!(parse(&cfg).unwrap_err().contains("digest-pinned"));
+    }
+
+    #[test]
+    fn rejects_invalid_namespace_names() {
+        for bad in [
+            "",
+            "Buzz-Agents",
+            "-leading",
+            "trailing-",
+            "has_underscore",
+            &"n".repeat(64),
+        ] {
+            let mut cfg = minimal();
+            cfg["namespace"] = bad.into();
+            assert!(parse(&cfg).is_err(), "accepted namespace {bad:?}");
+        }
+    }
+
+    /// I2 corollary: there is no config path for cluster credentials, so a
+    /// caller that tries to supply one gets no effect from it. Asserting the
+    /// parsed struct has no such field is the closest a test can get to
+    /// "the type makes it impossible".
+    #[test]
+    fn credential_fields_have_no_effect() {
+        let mut cfg = minimal();
+        cfg["token"] = "hunter2".into();
+        cfg["client_key"] = "hunter2".into();
+        let c = parse(&cfg).unwrap();
+        let rendered = format!("{c:?}");
+        assert!(
+            !rendered.contains("hunter2"),
+            "config absorbed a credential: {rendered}"
+        );
+    }
+
+    #[test]
+    fn mistyped_string_fields_are_named() {
+        let mut cfg = minimal();
+        cfg["namespace"] = serde_json::json!(42);
+        assert!(parse(&cfg)
+            .unwrap_err()
+            .contains("provider_config.namespace"));
+    }
+
+    #[test]
+    fn generated_namespaces_are_fresh_and_valid() {
+        let a = generated_namespace();
+        let b = generated_namespace();
+        assert_ne!(a, b, "namespace default is not random");
+        assert!(valid_namespace(&a), "{a} is not a valid namespace");
+        assert!(a.starts_with("buzz-agents-"));
+        assert_eq!(a.len(), "buzz-agents-".len() + 6);
+    }
+
+    /// The schema's own namespace default must be a value the parser accepts —
+    /// otherwise the UI prefills a form that fails on submit.
+    #[test]
+    fn schema_default_namespace_round_trips_through_parse() {
+        let schema = config_schema();
+        let default = schema["properties"]["namespace"]["default"]
+            .as_str()
+            .unwrap();
+        let cfg = serde_json::json!({"namespace": default, "image": digest_ref()});
+        assert_eq!(parse(&cfg).unwrap().namespace, default);
+    }
+
+    /// Same guarantee for the image prefill: the schema's default must be a
+    /// value `image::parse` accepts, or the UI prefills a form that fails on
+    /// submit. Its tag+digest form normalizes to the tagless canonical form.
+    #[test]
+    fn schema_default_image_round_trips_through_parse() {
+        let schema = config_schema();
+        let default = schema["properties"]["image"]["default"].as_str().unwrap();
+        assert_eq!(default, DEFAULT_IMAGE);
+        let cfg = serde_json::json!({"namespace": "buzz-agents-abc123", "image": default});
+        let parsed = parse(&cfg).unwrap();
+        assert_eq!(
+            parsed.image.as_str(),
+            "ghcr.io/block/buzz-sprig@sha256:17facfc7608d8ddb33bc056c9aaba1098f4ef6abe5655702fbfd7584d1f74d76"
+        );
+    }
+
+    /// Nine fields exactly (§`provider_config` v1 fields). The cap is 20; the
+    /// count is pinned so a field added without a spec change is caught here.
+    #[test]
+    fn schema_declares_exactly_the_nine_v1_fields() {
+        let schema = config_schema();
+        let props = schema["properties"].as_object().unwrap();
+        let mut keys: Vec<&str> = props.keys().map(String::as_str).collect();
+        keys.sort();
+        assert_eq!(
+            keys,
+            [
+                "context",
+                "cpu_limit",
+                "cpu_request",
+                "image",
+                "inactivity_seconds",
+                "memory_limit",
+                "memory_request",
+                "namespace",
+                "service_account"
+            ]
+        );
+        assert_eq!(
+            schema["required"],
+            serde_json::json!(["namespace", "image"])
+        );
+    }
+
+    /// I2's key lint rejects any field whose word-split contains
+    /// secret|password|token|key|credential. A schema field tripping it would
+    /// make every deploy fail validation desktop-side (`:185-198`).
+    #[test]
+    fn no_schema_field_trips_the_i2_key_lint() {
+        const BANNED: [&str; 5] = ["secret", "password", "token", "key", "credential"];
+        let schema = config_schema();
+        for field in schema["properties"].as_object().unwrap().keys() {
+            for word in field.split(['_', '-']) {
+                assert!(
+                    !BANNED.contains(&word),
+                    "field {field:?} contains I2-banned word {word:?}"
+                );
+            }
+        }
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/env.rs b/crates/buzz-backend-kubernetes/src/env.rs
new file mode 100644
index 0000000000..badff621e8
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/env.rs
@@ -0,0 +1,732 @@
+//! Building the pod environment (spec §Launch data, §Entrypoint mapping table).
+//!
+//! The three tiers are resolved *here*, before serialization, because a
+//! Kubernetes Secret's `data` is a flat map with no precedence of its own: if
+//! two tiers supplied the same key, whichever entry landed in the map would
+//! win silently. Resolving in-provider makes later-wins explicit and testable.
+
+use crate::wire::{AgentPayload, LaunchBlock};
+use std::collections::BTreeMap;
+
+/// Keys the authoritative tier owns.
+///
+/// Load-bearing, not documentation: tier 3 *clears* every key on this list
+/// before writing its own values, so a key the authoritative tier has no value
+/// for is **removed** rather than left holding a lower-tier value. Plain
+/// overwrite is not enough — most of these are written conditionally
+/// (`BUZZ_ACP_AGENT_ARGS` only when `launch.args` is non-empty,
+/// `BUZZ_ACP_RESPOND_TO` only when set), and without the clear, a lower tier
+/// could supply the value for exactly the cases the authoritative tier stays
+/// silent on. Clearing is also what the local spawn does: the desktop strips
+/// reserved keys from user env before the authoritative layer is written
+/// (`env_vars.rs:54-57`), so absent-means-absent in both paths.
+const AUTHORITATIVE_KEYS: &[&str] = &[
+    "BUZZ_RELAY_URL",
+    "BUZZ_PRIVATE_KEY",
+    "NOSTR_PRIVATE_KEY",
+    "BUZZ_AUTH_TAG",
+    "BUZZ_ACP_AGENT_OWNER",
+    "BUZZ_ACP_AGENT_COMMAND",
+    "BUZZ_ACP_AGENT_ARGS",
+    "BUZZ_ACP_RESPOND_TO",
+    "BUZZ_ACP_RESPOND_TO_ALLOWLIST",
+    "BUZZ_ACP_MCP_COMMAND",
+    "BUZZ_ACP_EXIT_AFTER_INACTIVITY",
+    START_NONCE_KEY,
+];
+
+/// The attempt's generation, as the harness sees it. Also the Secret's name
+/// suffix — one generation, one identity — so the reconciler restamps this on
+/// every create attempt rather than letting the caller's value persist across
+/// a retry.
+pub const START_NONCE_KEY: &str = "BUZZ_MANAGED_AGENT_START_NONCE";
+
+/// Presence is the only remote liveness signal (I3), so a launch that
+/// suppresses it is non-conforming (L1 item 2) — and unlike a reserved-key
+/// collision, there is no "authoritative value" to overwrite it with. Refuse.
+const FORBIDDEN_KEY: &str = "BUZZ_ACP_NO_PRESENCE";
+
+/// Kubernetes' own cap on the summed value bytes of a Secret
+/// (`MaxSecretSize`, `pkg/apis/core/types.go`). Enforced here so an oversized
+/// env surfaces as a named provider error rather than an apiserver rejection
+/// partway through a deploy.
+const MAX_SECRET_BYTES: usize = 1024 * 1024;
+
+/// A POSIX-shaped env var name: `[A-Za-z_][A-Za-z0-9_]*`.
+///
+/// Kubernetes validates Secret *keys* as `IsConfigMapKey`
+/// (`[-._a-zA-Z0-9]+`), which is looser — `foo.bar` is a legal Secret key.
+/// What the kubelet then does with such a key **changed between versions**:
+/// through 1.29 it filtered invalid env names out of `envFrom` and emitted an
+/// `InvalidEnvironmentVariableNames` warning event
+/// (`pkg/kubelet/kubelet_pods.go:646,654` at v1.29.0); from 1.30 that filter
+/// is gone (KEP-4369) and the key is injected verbatim. The same manifest
+/// would silently drop a variable on one cluster and set it on another, so we
+/// fail closed on the provider side and get one deterministic behavior.
+fn is_posix_env_key(key: &str) -> bool {
+    let mut chars = key.chars();
+    match chars.next() {
+        Some(c) if c == '_' || c.is_ascii_alphabetic() => {}
+        _ => return false,
+    }
+    chars.all(|c| c == '_' || c.is_ascii_alphanumeric())
+}
+
+/// An identity component (L1 item 1) is present only if it is nonempty after
+/// trimming — and the **trimmed form is what gets stored**. The validator and
+/// the writer must never disagree about the value: a guard that accepts
+/// `"  wss://relay  "` and then writes it with the padding intact has only
+/// moved the failure from a loud refusal to a connect error in the harness.
+fn identity_component(value: &str) -> Option<&str> {
+    let trimmed = value.trim();
+    (!trimmed.is_empty()).then_some(trimmed)
+}
+
+/// The harness's `allowlist` gate mode, spelled as the desktop serializes
+/// `RespondTo` (kebab-case) and as `buzz-acp`'s CLI parses it.
+const RESPOND_TO_ALLOWLIST: &str = "allowlist";
+
+/// Every gate mode `buzz-acp` accepts, spelled as its `clap::ValueEnum` parses
+/// them (`config.rs:95-101`, kebab-case via `RespondTo`'s `Display`).
+///
+/// Deliberately the **harness's** four and not the desktop's three: the desktop
+/// rejects `nobody` on purpose (`managed_agents/types.rs:871-880`), but the
+/// harness starts fine with it. This guard exists to cover non-desktop callers,
+/// so inheriting a desktop-only narrowing would refuse a launch that works.
+const RESPOND_TO_MODES: [&str; 4] = ["owner-only", RESPOND_TO_ALLOWLIST, "anyone", "nobody"];
+
+/// Refuse a respond-to gate the harness will reject at config parse.
+///
+/// The local spawn path re-validates this before spawning — "doing it here
+/// means we never spawn a doomed process" (`runtime.rs:378`) — but the deploy
+/// path projects the record's fields straight through. Without this, a gate
+/// the harness refuses becomes a pod that exits 1 at startup; `restartPolicy:
+/// Never` turns that into `Terminated` → `Delete` → recreate, and each cycle
+/// leaves a Secret the in-call path never reaps (only a later deploy's orphan
+/// sweep does, at `ORPHAN_SECRET_MIN_AGE_SECS`). The user-visible ending is
+/// "startup not confirmed", indistinguishable from a slow cluster.
+///
+/// Mirrors `buzz-acp`'s own rules exactly (`config.rs:95-101,996-1004,629-641`),
+/// deliberately including their asymmetry: the allowlist is validated **only**
+/// in allowlist mode, and merely warned about otherwise. Validating it in
+/// every mode would refuse a deploy whose identical local spawn succeeds —
+/// and a stale list is already harmless here, since
+/// `BUZZ_ACP_RESPOND_TO_ALLOWLIST` is an authoritative key that tier 3 clears.
+fn validate_respond_to_gate(respond_to: &str, allowlist: Option<&[String]>) -> Result<(), String> {
+    // Exact, untrimmed: `clap` does not trim, so `" allowlist "` is `rc=2` at
+    // the harness — a parse failure even earlier than the config errors below.
+    if !RESPOND_TO_MODES.contains(&respond_to) {
+        return Err(format!(
+            "deploy refused: respond_to {respond_to:?} is not a mode the \
+             harness accepts (expected one of {}) — the pod would fail to \
+             parse its arguments, be replaced, and leave a Secret behind on \
+             every attempt",
+            RESPOND_TO_MODES.join(", ")
+        ));
+    }
+    if respond_to != RESPOND_TO_ALLOWLIST {
+        return Ok(());
+    }
+    let entries = allowlist.unwrap_or_default();
+    if entries.is_empty() {
+        return Err(format!(
+            "deploy refused: respond_to is {RESPOND_TO_ALLOWLIST:?} but the \
+             allowlist is empty — the harness refuses this at startup, so the \
+             pod would fail, be replaced, and leave a Secret behind on every \
+             attempt"
+        ));
+    }
+    for entry in entries {
+        let trimmed = entry.trim();
+        if trimmed.len() != 64 || !trimmed.chars().all(|c| c.is_ascii_hexdigit()) {
+            return Err(format!(
+                "deploy refused: invalid pubkey in respond_to_allowlist: \
+                 {entry:?} (must be exactly 64 hex characters)"
+            ));
+        }
+    }
+    Ok(())
+}
+
+/// Inputs the provider itself supplies to the authoritative tier.
+pub struct AuthoritativeInputs<'a> {
+    /// The attempt's generation token — also the Secret's name suffix, so the
+    /// lifecycle correlator and the Secret generation are one identity.
+    pub generation: &'a str,
+    /// Resolved from `provider_config.inactivity_seconds`; `None` when the
+    /// indefinite opt-in was chosen (which this version refuses elsewhere).
+    pub inactivity_seconds: Option<u64>,
+}
+
+/// Resolve the full pod environment.
+///
+/// Order is the spec's, and the function body is deliberately three writes in
+/// that order — tier 1, tier 2, tier 3 — so "later wins" is visible rather
+/// than argued.
+pub fn build_env(
+    agent: &AgentPayload,
+    auth: AuthoritativeInputs<'_>,
+) -> Result<BTreeMap<String, String>, String> {
+    let default_launch = LaunchBlock::default();
+    let launch = agent.launch.as_ref().unwrap_or(&default_launch);
+
+    let mut env: BTreeMap<String, String> = BTreeMap::new();
+
+    // Tier 1 — overridable behavior defaults.
+    env.extend(launch.policy_env.clone());
+
+    // Tier 2 — user/layered env. The descriptor already merged
+    // global < persona < agent, so `agent.env_vars` is NOT re-merged on top
+    // (§Launch data tier 2) — doing so would resurrect a layer the desktop
+    // already resolved. When the desktop predates the `launch` block we fall
+    // back to the legacy field, which is the only case it is the truth.
+    if agent.launch.is_some() {
+        env.extend(launch.env.clone());
+    } else {
+        env.extend(agent.env_vars.clone());
+    }
+
+    // Validate what the lower tiers contributed, before the authoritative
+    // tier overwrites any of it. A reserved-key collision is NOT fatal: the
+    // spec's precedence is later-wins, so tier 3 simply overwrites it, which
+    // is exactly what a local spawn does. Only a key that has no
+    // authoritative counterpart to overwrite it — presence suppression — is
+    // a refusal.
+    for key in env.keys() {
+        if !is_posix_env_key(key) {
+            return Err(format!(
+                "env key {key:?} is not a POSIX environment variable name \
+                 ([A-Za-z_][A-Za-z0-9_]*); Kubernetes would treat it \
+                 inconsistently across cluster versions"
+            ));
+        }
+        if key.eq_ignore_ascii_case(FORBIDDEN_KEY) {
+            return Err(format!(
+                "{FORBIDDEN_KEY} must not be set on a remote agent: presence \
+                 is the only signal that a remote agent is alive"
+            ));
+        }
+    }
+
+    // Tier 3 — authoritative. Every key it owns is cleared first, then the
+    // values it has are written, so it wins at a key whether or not it has a
+    // value there (see [`AUTHORITATIVE_KEYS`]).
+    for key in AUTHORITATIVE_KEYS {
+        env.remove(*key);
+    }
+    // Identity comes from top-level payload fields, never from `env_vars`
+    // (§Reserved-key rule). All three components must be nonempty: an agent
+    // that cannot reach a relay is the identityless launch L1 item 1 exists to
+    // prevent, and a blank field would otherwise sail through into the Secret
+    // and produce a pod that starts, fails to connect, and looks like a
+    // network problem.
+    let Some(relay_url) = identity_component(&agent.relay_url) else {
+        return Err("deploy refused: relay_url is empty — the agent would have \
+                    no relay to connect to"
+            .to_string());
+    };
+    env.insert("BUZZ_RELAY_URL".into(), relay_url.to_string());
+    env.insert("BUZZ_PRIVATE_KEY".into(), agent.private_key_nsec.clone());
+    // The git credential/signing helpers read NOSTR_PRIVATE_KEY.
+    env.insert("NOSTR_PRIVATE_KEY".into(), agent.private_key_nsec.clone());
+
+    // Owner: at least one of these must resolve, or the harness cannot match
+    // `!shutdown` and §Stop describes a mechanism that does not work.
+    let auth_tag = agent.auth_tag.as_deref().and_then(identity_component);
+    let owner = launch.owner_pubkey.as_deref().and_then(identity_component);
+    match (auth_tag, owner) {
+        (None, None) => {
+            return Err("deploy refused: neither auth_tag nor launch.owner_pubkey \
+                        resolved — without an owner the agent cannot honor \
+                        !shutdown"
+                .to_string())
+        }
+        (tag, own) => {
+            if let Some(t) = tag {
+                env.insert("BUZZ_AUTH_TAG".into(), t.to_string());
+            }
+            if let Some(o) = own {
+                env.insert("BUZZ_ACP_AGENT_OWNER".into(), o.to_string());
+            }
+        }
+    }
+
+    // The harness and MCP binaries are resolved against the *image's* PATH.
+    // A host path forwarded from the desktop is guaranteed absent in the
+    // container (§Launch data, host-resolved values).
+    if let Some(command) = launch.command.as_deref().filter(|c| !c.is_empty()) {
+        env.insert("BUZZ_ACP_AGENT_COMMAND".into(), command.to_string());
+    }
+    if !launch.args.is_empty() {
+        // Comma-joined because that is what the harness's CLI parser decodes,
+        // and what the desktop's local spawn does. An argument containing a
+        // comma is unrepresentable in both paths; inventing an escaping
+        // scheme here would produce args the harness cannot decode.
+        env.insert("BUZZ_ACP_AGENT_ARGS".into(), launch.args.join(","));
+    }
+    env.insert("BUZZ_ACP_MCP_COMMAND".into(), "buzz-dev-mcp".into());
+
+    if let Some(respond_to) = agent.respond_to.as_deref().filter(|s| !s.is_empty()) {
+        validate_respond_to_gate(respond_to, agent.respond_to_allowlist.as_deref())?;
+        env.insert("BUZZ_ACP_RESPOND_TO".into(), respond_to.to_string());
+    }
+    if let Some(list) = agent
+        .respond_to_allowlist
+        .as_ref()
+        .filter(|l| !l.is_empty())
+    {
+        env.insert("BUZZ_ACP_RESPOND_TO_ALLOWLIST".into(), list.join(","));
+    }
+
+    if let Some(secs) = auth.inactivity_seconds {
+        env.insert("BUZZ_ACP_EXIT_AFTER_INACTIVITY".into(), secs.to_string());
+    }
+    // The generation token doubles as the lifecycle-frame correlator, so pod
+    // logs and observer frames share one identity (§K8s Secrets).
+    env.insert(START_NONCE_KEY.into(), auth.generation.to_string());
+
+    let total: usize = env.values().map(String::len).sum();
+    if total > MAX_SECRET_BYTES {
+        return Err(format!(
+            "agent environment is {total} bytes; Kubernetes caps Secret data \
+             at {MAX_SECRET_BYTES}"
+        ));
+    }
+
+    Ok(env)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn payload_json(extra_agent: serde_json::Value) -> AgentPayload {
+        let mut agent = serde_json::json!({
+            "name": "a",
+            "relay_url": "wss://relay.example",
+            "private_key_nsec": "nsec1example",
+            "auth_tag": "tag-1",
+        });
+        let (serde_json::Value::Object(base), serde_json::Value::Object(extra)) =
+            (&mut agent, extra_agent)
+        else {
+            panic!("expected objects")
+        };
+        base.extend(extra);
+        serde_json::from_value(agent).unwrap()
+    }
+
+    fn build(agent: &AgentPayload) -> Result<BTreeMap<String, String>, String> {
+        build_env(
+            agent,
+            AuthoritativeInputs {
+                generation: "gen0001",
+                inactivity_seconds: Some(7200),
+            },
+        )
+    }
+
+    #[test]
+    fn identity_comes_from_top_level_fields() {
+        let env = build(&payload_json(serde_json::json!({}))).unwrap();
+        assert_eq!(env["BUZZ_RELAY_URL"], "wss://relay.example");
+        assert_eq!(env["BUZZ_PRIVATE_KEY"], "nsec1example");
+        assert_eq!(env["NOSTR_PRIVATE_KEY"], "nsec1example");
+        assert_eq!(env["BUZZ_AUTH_TAG"], "tag-1");
+    }
+
+    /// Wren's amendment, and the spec's later-wins rule: a lower tier that
+    /// spoofs an authoritative key is *overwritten*, not refused. Refusing
+    /// would diverge from the local spawn, where the same env is written
+    /// before the authoritative layer and simply loses.
+    #[test]
+    fn lower_tiers_cannot_spoof_authoritative_values() {
+        let agent = payload_json(serde_json::json!({
+            "launch": {
+                "command": "goose",
+                "policy_env": {
+                    "BUZZ_PRIVATE_KEY": "nsec1attacker",
+                    "BUZZ_MANAGED_AGENT_START_NONCE": "forged",
+                },
+                "env": {
+                    "BUZZ_RELAY_URL": "wss://attacker.example",
+                    "NOSTR_PRIVATE_KEY": "nsec1attacker",
+                    "BUZZ_AUTH_TAG": "forged-tag",
+                    "BUZZ_ACP_AGENT_OWNER": "cafe",
+                    "BUZZ_ACP_AGENT_COMMAND": "/bin/sh",
+                    "BUZZ_ACP_MCP_COMMAND": "/bin/sh",
+                    "BUZZ_ACP_EXIT_AFTER_INACTIVITY": "0",
+                },
+                "owner_pubkey": "beef"
+            }
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["BUZZ_PRIVATE_KEY"], "nsec1example");
+        assert_eq!(env["NOSTR_PRIVATE_KEY"], "nsec1example");
+        assert_eq!(env["BUZZ_RELAY_URL"], "wss://relay.example");
+        assert_eq!(env["BUZZ_AUTH_TAG"], "tag-1");
+        assert_eq!(env["BUZZ_ACP_AGENT_OWNER"], "beef");
+        assert_eq!(env["BUZZ_ACP_AGENT_COMMAND"], "goose");
+        assert_eq!(env["BUZZ_ACP_MCP_COMMAND"], "buzz-dev-mcp");
+        assert_eq!(env["BUZZ_ACP_EXIT_AFTER_INACTIVITY"], "7200");
+        assert_eq!(env["BUZZ_MANAGED_AGENT_START_NONCE"], "gen0001");
+    }
+
+    /// Tier 1 is *overridable* — user env beats policy defaults, matching the
+    /// local spawn, where the user layer is written after them. Getting this
+    /// backwards would make remote agents ignore overrides local agents honor.
+    #[test]
+    fn user_env_overrides_policy_defaults() {
+        let agent = payload_json(serde_json::json!({
+            "launch": {
+                "policy_env": {"GOOSE_MODE": "auto", "BUZZ_ACP_MODEL": "sonnet"},
+                "env": {"GOOSE_MODE": "chat"},
+                "owner_pubkey": "beef"
+            }
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["GOOSE_MODE"], "chat");
+        assert_eq!(env["BUZZ_ACP_MODEL"], "sonnet");
+    }
+
+    /// `launch.env` already contains the merged user env, so re-merging the
+    /// legacy field would undo a layering the desktop already resolved.
+    #[test]
+    fn legacy_env_vars_are_not_remerged_when_launch_present() {
+        let agent = payload_json(serde_json::json!({
+            "env_vars": {"STALE": "yes", "SHARED": "legacy"},
+            "launch": {"env": {"SHARED": "resolved"}, "owner_pubkey": "beef"}
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["SHARED"], "resolved");
+        assert!(!env.contains_key("STALE"), "legacy env_vars re-merged");
+    }
+
+    /// ...but a desktop predating the `launch` block has nothing else to
+    /// offer, so the legacy field is the truth in exactly that case.
+    #[test]
+    fn legacy_env_vars_used_when_launch_absent() {
+        let agent = payload_json(serde_json::json!({"env_vars": {"API": "v"}}));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["API"], "v");
+    }
+
+    #[test]
+    fn refuses_when_no_owner_resolves() {
+        let agent = payload_json(serde_json::json!({"auth_tag": null}));
+        let err = build(&agent).unwrap_err();
+        assert!(err.contains("!shutdown"), "unhelpful error: {err}");
+    }
+
+    /// An empty string is not an owner. Without this the refusal is
+    /// bypassable by a blank field and the pod launches unable to be stopped.
+    #[test]
+    fn empty_owner_fields_count_as_absent() {
+        for blank in ["", "   "] {
+            let agent = payload_json(serde_json::json!({
+                "auth_tag": blank,
+                "launch": {"owner_pubkey": blank}
+            }));
+            assert!(
+                build(&agent).is_err(),
+                "whitespace resolved as an owner: {blank:?}"
+            );
+        }
+    }
+
+    /// The other half of every identity guard: what is *stored*. A validator
+    /// that trims and a writer that doesn't disagree about the value, and the
+    /// padding reaches the harness inside the Secret. Assert on the stored
+    /// string — asserting only that the deploy was accepted passes either way.
+    #[test]
+    fn identity_components_are_stored_trimmed() {
+        let agent = payload_json(serde_json::json!({
+            "relay_url": "  wss://relay.example  ",
+            "auth_tag": "  tag-1  ",
+            "launch": {"owner_pubkey": "  beefcafe  "}
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["BUZZ_RELAY_URL"], "wss://relay.example");
+        assert_eq!(env["BUZZ_AUTH_TAG"], "tag-1");
+        assert_eq!(env["BUZZ_ACP_AGENT_OWNER"], "beefcafe");
+    }
+
+    /// L1 item 1's third identity component. The nsec arm is enforced in
+    /// `naming.rs` and the owner arm above; without this one an agent
+    /// deploys with nothing to connect to — a pod that starts, fails at the
+    /// relay, and reads as a network fault rather than a refused launch.
+    #[test]
+    fn refuses_empty_relay_url() {
+        for blank in ["", "   "] {
+            let agent = payload_json(serde_json::json!({"relay_url": blank}));
+            let err = build(&agent).unwrap_err();
+            assert!(err.contains("relay_url"), "unhelpful error: {err}");
+        }
+    }
+
+    #[test]
+    fn owner_pubkey_alone_is_sufficient() {
+        let agent = payload_json(serde_json::json!({
+            "auth_tag": null,
+            "launch": {"owner_pubkey": "beefcafe"}
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["BUZZ_ACP_AGENT_OWNER"], "beefcafe");
+        assert!(!env.contains_key("BUZZ_AUTH_TAG"));
+    }
+
+    #[test]
+    fn refuses_presence_suppression() {
+        let agent = payload_json(serde_json::json!({
+            "launch": {"env": {"BUZZ_ACP_NO_PRESENCE": "1"}, "owner_pubkey": "beef"}
+        }));
+        let err = build(&agent).unwrap_err();
+        assert!(err.contains("BUZZ_ACP_NO_PRESENCE"), "got: {err}");
+    }
+
+    /// `foo.bar` is a legal Secret key but not a legal env name: pre-1.30
+    /// kubelets drop it, 1.30+ inject it. Refuse rather than behave
+    /// differently depending on the cluster.
+    #[test]
+    fn refuses_non_posix_env_keys() {
+        for bad in ["foo.bar", "foo-bar", "1LEADING", "", "has space"] {
+            let agent = payload_json(serde_json::json!({
+                "launch": {"env": {bad: "v"}, "owner_pubkey": "beef"}
+            }));
+            assert!(build(&agent).is_err(), "accepted non-POSIX key {bad:?}");
+        }
+    }
+
+    #[test]
+    fn args_are_comma_joined_and_omitted_when_empty() {
+        let agent = payload_json(serde_json::json!({
+            "launch": {"command": "goose", "args": ["run", "--no-session"], "owner_pubkey": "b"}
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["BUZZ_ACP_AGENT_ARGS"], "run,--no-session");
+
+        let agent = payload_json(serde_json::json!({
+            "launch": {"command": "goose", "args": [], "owner_pubkey": "b"}
+        }));
+        assert!(!build(&agent).unwrap().contains_key("BUZZ_ACP_AGENT_ARGS"));
+    }
+
+    /// The top-level `model`/`provider` fields are display inputs; their
+    /// environment consequence is per-runtime and arrives already resolved
+    /// inside `launch`. A provider-side mapping is wrong for three of the
+    /// four built-in runtimes.
+    #[test]
+    fn provider_never_maps_model_or_provider_itself() {
+        let agent = payload_json(serde_json::json!({
+            "model": "claude-opus", "provider": "anthropic",
+            "launch": {"owner_pubkey": "beef"}
+        }));
+        let env = build(&agent).unwrap();
+        for key in [
+            "BUZZ_AGENT_PROVIDER",
+            "BUZZ_AGENT_MODEL",
+            "GOOSE_PROVIDER",
+            "GOOSE_MODEL",
+        ] {
+            assert!(!env.contains_key(key), "provider mapped {key} itself");
+        }
+    }
+
+    /// `turn_timeout_seconds` is deprecated and ignored upstream; the local
+    /// spawn does not emit it either.
+    #[test]
+    fn turn_timeout_is_not_mapped() {
+        let agent = payload_json(serde_json::json!({
+            "turn_timeout_seconds": 30, "launch": {"owner_pubkey": "b"}
+        }));
+        let env = build(&agent).unwrap();
+        assert!(!env.keys().any(|k| k.contains("TURN_TIMEOUT")));
+    }
+
+    #[test]
+    fn inactivity_omitted_when_unset() {
+        let agent = payload_json(serde_json::json!({"launch": {"owner_pubkey": "b"}}));
+        let env = build_env(
+            &agent,
+            AuthoritativeInputs {
+                generation: "g",
+                inactivity_seconds: None,
+            },
+        )
+        .unwrap();
+        assert!(!env.contains_key("BUZZ_ACP_EXIT_AFTER_INACTIVITY"));
+    }
+
+    /// Structural guard over the whole authoritative list at once: whatever
+    /// the lower tiers contain, no authoritative key holds a lower-tier value
+    /// — including the conditionally-written ones the authoritative tier has
+    /// nothing to say about, which must be **absent** rather than spoofed.
+    /// This test caught exactly that: `BUZZ_ACP_AGENT_ARGS` is only written
+    /// when `launch.args` is non-empty, so plain later-wins overwrite left the
+    /// spoofed value in place.
+    #[test]
+    fn no_authoritative_key_retains_a_lower_tier_value() {
+        let spoofed: serde_json::Map<String, serde_json::Value> = AUTHORITATIVE_KEYS
+            .iter()
+            .map(|k| ((*k).to_string(), serde_json::json!("SPOOFED")))
+            .collect();
+        // Split across both lower tiers: policy_env and env are separate
+        // insertion points, and a fix that only cleared one would pass a
+        // single-tier test.
+        let agent = payload_json(serde_json::json!({
+            "launch": {
+                "command": "goose",
+                "policy_env": spoofed.clone(),
+                "env": spoofed,
+                "owner_pubkey": "beef"
+            }
+        }));
+        let env = build(&agent).unwrap();
+        for key in AUTHORITATIVE_KEYS {
+            assert_ne!(
+                env.get(*key).map(String::as_str),
+                Some("SPOOFED"),
+                "{key} kept its lower-tier value"
+            );
+        }
+        // The keys the authoritative tier had no value for are gone, not
+        // merely different.
+        for absent in [
+            "BUZZ_ACP_AGENT_ARGS",
+            "BUZZ_ACP_RESPOND_TO",
+            "BUZZ_ACP_RESPOND_TO_ALLOWLIST",
+        ] {
+            assert!(!env.contains_key(absent), "{absent} survived the clear");
+        }
+    }
+
+    /// A 64-hex pubkey, the only allowlist entry shape the harness accepts.
+    fn pubkey(fill: char) -> String {
+        std::iter::repeat_n(fill, 64).collect()
+    }
+
+    /// The gate the harness refuses first (`config.rs:996-1004`). Refusing it
+    /// here is the difference between one error message and an unbounded
+    /// fail-replace loop that leaves a Secret per attempt.
+    #[test]
+    fn allowlist_mode_with_an_empty_list_is_refused() {
+        for empty in [serde_json::json!([]), serde_json::Value::Null] {
+            let agent = payload_json(serde_json::json!({
+                "respond_to": "allowlist",
+                "respond_to_allowlist": empty,
+            }));
+            let err = build(&agent).unwrap_err();
+            assert!(
+                err.contains("the allowlist is empty"),
+                "unexpected error: {err}"
+            );
+        }
+    }
+
+    /// `config.rs:629-641` — each entry must be exactly 64 hex characters.
+    /// The rejects are the distinct ways to miss that: too short, right length
+    /// but not hex, empty, and one character short of valid.
+    #[test]
+    fn an_allowlist_entry_that_is_not_64_hex_is_refused() {
+        for bad in ["abc1234", &"z".repeat(64), "", &pubkey('a')[..63]] {
+            let agent = payload_json(serde_json::json!({
+                "respond_to": "allowlist",
+                "respond_to_allowlist": [pubkey('a'), bad],
+            }));
+            let err = build(&agent).unwrap_err();
+            assert!(
+                err.contains("must be exactly 64 hex characters"),
+                "{bad:?} was accepted; error was: {err}"
+            );
+        }
+    }
+
+    /// The positive control: the guard refuses bad gates, not every gate.
+    /// Without this, a validator that refused unconditionally would pass both
+    /// tests above.
+    #[test]
+    fn a_valid_allowlist_gate_is_accepted_and_comma_joined() {
+        let agent = payload_json(serde_json::json!({
+            "respond_to": "allowlist",
+            "respond_to_allowlist": [pubkey('a'), pubkey('b')],
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["BUZZ_ACP_RESPOND_TO"], "allowlist");
+        assert_eq!(
+            env["BUZZ_ACP_RESPOND_TO_ALLOWLIST"],
+            format!("{},{}", pubkey('a'), pubkey('b'))
+        );
+    }
+
+    /// The harness validates the allowlist **only** in allowlist mode and
+    /// merely warns otherwise (`config.rs:1005-1010`). A stricter provider
+    /// would refuse a deploy whose identical local spawn succeeds, so this
+    /// pins the asymmetry rather than leaving it to look like an oversight.
+    #[test]
+    fn a_junk_allowlist_is_tolerated_outside_allowlist_mode() {
+        for mode in ["owner-only", "anyone"] {
+            let agent = payload_json(serde_json::json!({
+                "respond_to": mode,
+                "respond_to_allowlist": ["not-a-pubkey"],
+            }));
+            let env = build(&agent)
+                .unwrap_or_else(|e| panic!("{mode} with a stale list must deploy: {e}"));
+            assert_eq!(env["BUZZ_ACP_RESPOND_TO"], mode);
+        }
+    }
+
+    /// `respond_to` is an opaque `String` on the wire but a `clap::ValueEnum`
+    /// at the harness, so an unrecognized mode dies at `rc=2` — before config
+    /// parsing runs at all, earlier than either refusal above. Measured
+    /// against the built binary: `invalid value 'npub1abc' for '--respond-to'`.
+    /// This is the shape our own fixture carried until it was corrected.
+    #[test]
+    fn a_mode_the_harness_cannot_parse_is_refused() {
+        for bad in ["npub1abc", "OWNER-ONLY", "owner_only", "allowlistt", "x"] {
+            let agent = payload_json(serde_json::json!({ "respond_to": bad }));
+            let err = build(&agent).unwrap_err();
+            assert!(
+                err.contains("is not a mode the harness accepts"),
+                "{bad:?} was accepted; error was: {err}"
+            );
+        }
+    }
+
+    /// `clap` does not trim its value-enum input, so a padded mode is `rc=2`
+    /// even though the same string trimmed is valid. Measured: `invalid value
+    /// ' allowlist ' for '--respond-to'`. Trimming here would accept a deploy
+    /// the harness refuses — the exact direction this guard exists to prevent.
+    #[test]
+    fn a_padded_mode_is_refused_because_clap_does_not_trim() {
+        for padded in [" allowlist ", "allowlist ", " owner-only", "\tnobody"] {
+            let agent = payload_json(serde_json::json!({
+                "respond_to": padded,
+                "respond_to_allowlist": [pubkey('a')],
+            }));
+            let err = build(&agent).unwrap_err();
+            assert!(
+                err.contains("is not a mode the harness accepts"),
+                "{padded:?} was accepted; error was: {err}"
+            );
+        }
+    }
+
+    /// Positive control for the mode check, and the reason it validates the
+    /// harness's four rather than the desktop's three: `nobody` is rejected by
+    /// `parse_wire` on purpose (`managed_agents/types.rs:871-880`) but starts
+    /// fine at the harness. A guard mirroring the desktop enum would refuse a
+    /// working launch from a non-desktop caller — the callers this guard is
+    /// for. Without this test, refusing `nobody` would pass everything above.
+    #[test]
+    fn every_mode_the_harness_accepts_is_deployable() {
+        for mode in ["owner-only", "allowlist", "anyone", "nobody"] {
+            let agent = payload_json(serde_json::json!({
+                "respond_to": mode,
+                "respond_to_allowlist": [pubkey('a')],
+            }));
+            let env = build(&agent)
+                .unwrap_or_else(|e| panic!("{mode} is valid at the harness but was refused: {e}"));
+            assert_eq!(env["BUZZ_ACP_RESPOND_TO"], mode);
+        }
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/gc.rs b/crates/buzz-backend-kubernetes/src/gc.rs
new file mode 100644
index 0000000000..2e18825aa4
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/gc.rs
@@ -0,0 +1,368 @@
+//! Preflight garbage collection (spec §K8s GC, `docs/remote-agents.md:1282-1335`).
+//!
+//! GC runs on every deploy, after identity derivation and before the state
+//! transition. It deletes terminated pods (and their referenced Secrets) and
+//! age-eligible orphan Secrets — every one of which must pass the full-pubkey
+//! annotation check *and* carry the management marker. An unmarked object is
+//! never GC'd regardless of its labels.
+//!
+//! The decision layer here is pure. The effectful caller supplies the observed
+//! objects and the apiserver's clock; this module decides what may be deleted.
+
+use crate::naming::AgentIdentity;
+use crate::observe::{referenced_secret, secret_is_ours};
+use chrono::{DateTime, Utc};
+use k8s_openapi::api::core::v1::{Pod, Secret};
+
+/// The deploy operation deadline (spec §Deploy: `timeout: 600s`).
+pub const OPERATION_DEADLINE_SECS: i64 = 600;
+
+/// An unreferenced Secret is GC-eligible only once it is older than **twice**
+/// the deploy deadline. Rationale: Secret-create → pod-create is not atomic
+/// against an independent GC pass, so without the gate a concurrent attempt's
+/// preflight GC can delete a Secret whose pod has not been created yet and
+/// strand that deploy. The age bound makes "unreferenced" mean "provably
+/// abandoned" — any attempt that could still reference it has exceeded its own
+/// deadline (`:1301-1319`).
+pub const ORPHAN_SECRET_MIN_AGE_SECS: i64 = 2 * OPERATION_DEADLINE_SECS;
+
+/// What a GC pass decided to delete. Names only: the caller re-reads each
+/// object's own fence at delete time.
+#[derive(Debug, Default, PartialEq, Eq)]
+pub struct GcPlan {
+    /// Terminated, verified, marker-bearing pods.
+    pub pods: Vec<String>,
+    /// Age-eligible, verified, marker-bearing orphan Secrets.
+    pub secrets: Vec<String>,
+}
+
+/// Plan a GC pass.
+///
+/// `now` is the apiserver's clock — the HTTP `Date` header from the very list
+/// call that produced `secrets`. `None` means the header was absent or
+/// unparseable, in which case **orphan-Secret GC is skipped entirely** rather
+/// than falling back to local time: this provider runs on a user's desktop,
+/// and a local clock fast by more than the margin does not race — it
+/// deterministically computes every in-flight Secret as expired, on every
+/// pass, reopening exactly the interleaving the gate exists to close
+/// (`:1321-1335`). A deferred cleanup is free; a wrong deletion is not.
+///
+/// Terminated-pod GC does not use the clock and is unaffected.
+pub fn plan(
+    identity: &AgentIdentity,
+    pods: &[Pod],
+    secrets: &[Secret],
+    terminated: impl Fn(&Pod) -> bool,
+    now: Option<DateTime<Utc>>,
+) -> GcPlan {
+    // Only pods that pass the full fence participate — in either direction.
+    // An unverified pod is neither deleted nor allowed to protect a Secret:
+    // it cannot be ours, so its `envFrom` cannot reference our generation.
+    let ours: Vec<&Pod> = pods
+        .iter()
+        .filter(|p| {
+            crate::observe::verify(p, identity, crate::classify::Startup::Started).is_some()
+        })
+        .collect();
+
+    let doomed_pods: Vec<&&Pod> = ours.iter().filter(|p| terminated(p)).collect();
+
+    // A Secret referenced by ANY existing pod is protected — deliberately
+    // including not-yet-started pods, whose `envFrom` is exactly as
+    // load-bearing as a running pod's (`:1262-1264`). Pods being GC'd in this
+    // same pass are excluded, so their Secrets go with them.
+    let doomed_names: Vec<&str> = doomed_pods
+        .iter()
+        .filter_map(|p| p.metadata.name.as_deref())
+        .collect();
+    let protected: Vec<String> = ours
+        .iter()
+        .filter(|p| !doomed_names.contains(&p.metadata.name.as_deref().unwrap_or_default()))
+        .filter_map(|p| referenced_secret(p))
+        .collect();
+
+    let mut plan = GcPlan {
+        pods: doomed_names.iter().map(|n| n.to_string()).collect(),
+        secrets: doomed_pods
+            .iter()
+            .filter_map(|p| referenced_secret(p))
+            .collect(),
+    };
+
+    // Orphan sweep: only with a server clock.
+    if let Some(now) = now {
+        for secret in secrets {
+            if !secret_is_ours(secret, identity) {
+                continue;
+            }
+            let Some(name) = secret.metadata.name.as_deref() else {
+                continue;
+            };
+            if protected.contains(&name.to_string()) || plan.secrets.iter().any(|s| s == name) {
+                continue;
+            }
+            let Some(created) = secret.metadata.creation_timestamp.as_ref() else {
+                // No server-assigned timestamp means no age proof. Skip.
+                continue;
+            };
+            if (now - created.0).num_seconds() >= ORPHAN_SECRET_MIN_AGE_SECS {
+                plan.secrets.push(name.to_string());
+            }
+        }
+    }
+
+    plan
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::naming::{ANNOTATION_PUBKEY_FULL, LABEL_MANAGED_BY};
+    use k8s_openapi::api::core::v1::{Container, EnvFromSource, PodSpec, SecretEnvSource};
+    use k8s_openapi::apimachinery::pkg::apis::meta::v1::{ObjectMeta, Time};
+    use std::collections::BTreeMap;
+
+    fn identity() -> AgentIdentity {
+        use nostr::nips::nip19::ToBech32;
+        let keys = nostr::Keys::generate();
+        AgentIdentity::from_nsec(&keys.secret_key().to_bech32().unwrap()).unwrap()
+    }
+
+    fn pod_named(id: &AgentIdentity, name: &str, secret: Option<&str>) -> Pod {
+        Pod {
+            metadata: ObjectMeta {
+                name: Some(name.into()),
+                uid: Some(format!("uid-{name}")),
+                resource_version: Some("1".into()),
+                labels: Some(id.labels()),
+                annotations: Some(
+                    [(
+                        ANNOTATION_PUBKEY_FULL.to_string(),
+                        id.pubkey_hex().to_string(),
+                    )]
+                    .into_iter()
+                    .collect::<BTreeMap<_, _>>(),
+                ),
+                ..Default::default()
+            },
+            spec: secret.map(|s| PodSpec {
+                containers: vec![Container {
+                    name: "agent".into(),
+                    env_from: Some(vec![EnvFromSource {
+                        secret_ref: Some(SecretEnvSource {
+                            name: s.into(),
+                            optional: Some(false),
+                        }),
+                        ..Default::default()
+                    }]),
+                    ..Default::default()
+                }],
+                ..Default::default()
+            }),
+            ..Default::default()
+        }
+    }
+
+    fn secret_named(id: &AgentIdentity, name: &str, age_secs: i64, now: DateTime<Utc>) -> Secret {
+        Secret {
+            metadata: ObjectMeta {
+                name: Some(name.into()),
+                labels: Some(id.labels()),
+                annotations: Some(
+                    [(
+                        ANNOTATION_PUBKEY_FULL.to_string(),
+                        id.pubkey_hex().to_string(),
+                    )]
+                    .into_iter()
+                    .collect::<BTreeMap<_, _>>(),
+                ),
+                creation_timestamp: Some(Time(now - chrono::Duration::seconds(age_secs))),
+                ..Default::default()
+            },
+            ..Default::default()
+        }
+    }
+
+    fn never(_: &Pod) -> bool {
+        false
+    }
+    fn always(_: &Pod) -> bool {
+        true
+    }
+
+    #[test]
+    fn terminated_pods_and_their_secrets_are_collected_together() {
+        let id = identity();
+        let now = Utc::now();
+        let pod = pod_named(&id, "buzz-agent-dead", Some("buzz-agent-dead-gen1"));
+        let plan = plan(&id, &[pod], &[], always, Some(now));
+        assert_eq!(plan.pods, ["buzz-agent-dead"]);
+        assert_eq!(plan.secrets, ["buzz-agent-dead-gen1"]);
+    }
+
+    #[test]
+    fn live_pods_are_never_collected() {
+        let id = identity();
+        let pod = pod_named(&id, "buzz-agent-live", Some("buzz-agent-live-gen1"));
+        let plan = plan(&id, &[pod], &[], never, Some(Utc::now()));
+        assert_eq!(plan, GcPlan::default());
+    }
+
+    /// The auto-repair fence applies to GC identically: an object that lacks
+    /// the marker, or carries a different pubkey, is never touched — however
+    /// well its labels match.
+    #[test]
+    fn unmarked_and_mismatched_objects_are_never_collected() {
+        let id = identity();
+        let other = identity();
+        let now = Utc::now();
+
+        let mut unmarked = pod_named(&id, "look-alike", Some("look-alike-gen1"));
+        let mut labels = id.labels();
+        labels.remove(LABEL_MANAGED_BY);
+        unmarked.metadata.labels = Some(labels);
+
+        let mut foreign = pod_named(&id, "someone-elses", Some("someone-elses-gen1"));
+        foreign.metadata.annotations = Some(
+            [(
+                ANNOTATION_PUBKEY_FULL.to_string(),
+                other.pubkey_hex().to_string(),
+            )]
+            .into_iter()
+            .collect(),
+        );
+
+        let mut unmarked_secret = secret_named(&id, "orphan-unmarked", 100_000, now);
+        unmarked_secret.metadata.labels = Some(BTreeMap::new());
+        let mut foreign_secret = secret_named(&id, "orphan-foreign", 100_000, now);
+        foreign_secret.metadata.annotations = Some(
+            [(
+                ANNOTATION_PUBKEY_FULL.to_string(),
+                other.pubkey_hex().to_string(),
+            )]
+            .into_iter()
+            .collect(),
+        );
+
+        let plan = plan(
+            &id,
+            &[unmarked, foreign],
+            &[unmarked_secret, foreign_secret],
+            always,
+            Some(now),
+        );
+        assert_eq!(
+            plan,
+            GcPlan::default(),
+            "GC touched an object it does not own"
+        );
+    }
+
+    /// The interleaving the age gate exists to close: attempt A creates its
+    /// Secret; concurrent attempt B's preflight GC runs before A creates its
+    /// pod. Without the gate B deletes A's Secret and strands A.
+    #[test]
+    fn young_unreferenced_secrets_are_protected() {
+        let id = identity();
+        let now = Utc::now();
+        let fresh = secret_named(&id, "buzz-agent-x-gen-inflight", 5, now);
+        assert_eq!(
+            plan(&id, &[], &[fresh], never, Some(now)),
+            GcPlan::default()
+        );
+    }
+
+    /// Past twice the deadline, any attempt that could still reference the
+    /// Secret has exceeded its own deadline — so it is provably abandoned.
+    #[test]
+    fn secrets_older_than_twice_the_deadline_are_collected() {
+        let id = identity();
+        let now = Utc::now();
+        let old = secret_named(
+            &id,
+            "buzz-agent-x-gen-abandoned",
+            ORPHAN_SECRET_MIN_AGE_SECS + 1,
+            now,
+        );
+        let plan = plan(&id, &[], &[old], never, Some(now));
+        assert_eq!(plan.secrets, ["buzz-agent-x-gen-abandoned"]);
+    }
+
+    /// The boundary itself, both sides. `>= 1200s` is eligible.
+    #[test]
+    fn age_gate_boundary_is_exact() {
+        let id = identity();
+        let now = Utc::now();
+        let just_under = secret_named(&id, "under", ORPHAN_SECRET_MIN_AGE_SECS - 1, now);
+        let exactly = secret_named(&id, "exact", ORPHAN_SECRET_MIN_AGE_SECS, now);
+        assert!(plan(&id, &[], &[just_under], never, Some(now))
+            .secrets
+            .is_empty());
+        assert_eq!(
+            plan(&id, &[], &[exactly], never, Some(now)).secrets,
+            ["exact"]
+        );
+    }
+
+    /// The same-clock rule. No apiserver `Date` header → skip the orphan
+    /// sweep entirely. A local clock fast by more than the margin would
+    /// silently delete every in-flight Secret on every pass.
+    #[test]
+    fn without_a_server_clock_the_orphan_sweep_is_skipped() {
+        let id = identity();
+        let now = Utc::now();
+        let ancient = secret_named(&id, "buzz-agent-x-gen-ancient", 10_000_000, now);
+        let plan = plan(&id, &[], &[ancient], never, None);
+        assert!(
+            plan.secrets.is_empty(),
+            "orphan swept without a server clock — a fast local clock would delete live Secrets"
+        );
+    }
+
+    /// ...but terminated-pod GC does not consult the clock, so it still runs.
+    #[test]
+    fn terminated_pod_gc_runs_without_a_server_clock() {
+        let id = identity();
+        let pod = pod_named(&id, "buzz-agent-dead", Some("buzz-agent-dead-gen1"));
+        let plan = plan(&id, &[pod], &[], always, None);
+        assert_eq!(plan.pods, ["buzz-agent-dead"]);
+        assert_eq!(plan.secrets, ["buzz-agent-dead-gen1"]);
+    }
+
+    /// "Existing" includes not-yet-started pods: a Secret referenced by a pod
+    /// still pulling its image must not be swept, however old it is.
+    #[test]
+    fn secrets_referenced_by_a_pending_pod_are_protected() {
+        let id = identity();
+        let now = Utc::now();
+        let pending = pod_named(&id, "buzz-agent-pending", Some("buzz-agent-pending-gen1"));
+        let old = secret_named(&id, "buzz-agent-pending-gen1", 10_000_000, now);
+        let plan = plan(&id, &[pending], &[old], never, Some(now));
+        assert!(plan.secrets.is_empty(), "swept a referenced Secret");
+    }
+
+    /// A Secret with no server-assigned creationTimestamp has no age proof,
+    /// so it is skipped rather than assumed old.
+    #[test]
+    fn secrets_without_a_creation_timestamp_are_skipped() {
+        let id = identity();
+        let now = Utc::now();
+        let mut no_timestamp = secret_named(&id, "buzz-agent-x-gen-unknown", 10_000_000, now);
+        no_timestamp.metadata.creation_timestamp = None;
+        assert!(plan(&id, &[], &[no_timestamp], never, Some(now))
+            .secrets
+            .is_empty());
+    }
+
+    /// A Secret belonging to a pod being collected in this same pass goes with
+    /// it, and must not be listed twice.
+    #[test]
+    fn a_collected_pods_secret_is_listed_once() {
+        let id = identity();
+        let now = Utc::now();
+        let dead = pod_named(&id, "buzz-agent-dead", Some("buzz-agent-dead-gen1"));
+        let its_secret = secret_named(&id, "buzz-agent-dead-gen1", 10_000_000, now);
+        let plan = plan(&id, &[dead], &[its_secret], always, Some(now));
+        assert_eq!(plan.secrets, ["buzz-agent-dead-gen1"]);
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/image.rs b/crates/buzz-backend-kubernetes/src/image.rs
new file mode 100644
index 0000000000..409989fda9
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/image.rs
@@ -0,0 +1,184 @@
+//! Image reference validation (spec §Image).
+//!
+//! The object holding this reference runs with an nsec, so the reference must
+//! be **immutable**. Registry tags are mutable pointers — Kubernetes itself
+//! distinguishes them from digests for exactly this reason — so a tag-only
+//! reference is rejected, not just `:latest`.
+//!
+//! There is no parse-time fallback: `image` is required, and its absence
+//! fails closed with a named field. The published `ghcr.io/block/buzz-sprig`
+//! digest is offered only as a schema `default` (a UI prefill the desktop
+//! submits explicitly — see `config::DEFAULT_IMAGE`), so the create-intent
+//! fingerprint never depends on compiled-in provider state.
+
+/// A validated, digest-qualified image reference.
+///
+/// The inner string is always in canonical tagless form `name@sha256:<hex>`:
+/// `name:tag@sha256:…` normalizes by dropping the tag, because the tag is
+/// decorative once a digest pins the content, and leaving it in would make
+/// two references to identical bytes produce different create-intent
+/// fingerprints.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ImageRef(String);
+
+impl ImageRef {
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl std::fmt::Display for ImageRef {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+/// Parse and normalize a user-supplied image reference.
+pub fn parse(raw: &str) -> Result<ImageRef, String> {
+    let reference = raw.trim();
+    if reference.is_empty() {
+        return Err("provider_config.image is required: no image is assumed \
+                    at parse time, so the digest-pinned image to run must be \
+                    given explicitly"
+            .to_string());
+    }
+
+    let mut parts = reference.split('@');
+    let name_and_tag = parts.next().unwrap_or_default();
+    let digest = match (parts.next(), parts.next()) {
+        (Some(d), None) => d,
+        (None, _) => {
+            return Err(format!(
+                "provider_config.image {reference:?} is not digest-pinned: a \
+                 tag is a mutable pointer, and this object runs with the \
+                 agent's private key. Use name@sha256:<64 hex chars>"
+            ))
+        }
+        (Some(_), Some(_)) => {
+            return Err(format!(
+                "provider_config.image {reference:?} contains more than one '@'"
+            ))
+        }
+    };
+
+    let hex = digest.strip_prefix("sha256:").ok_or_else(|| {
+        format!("provider_config.image digest {digest:?} must start with 'sha256:'")
+    })?;
+    // Lowercase only: OCI canonicalizes digest hex, and accepting uppercase
+    // would let two spellings of one digest produce two fingerprints.
+    if hex.len() != 64
+        || !hex
+            .chars()
+            .all(|c| c.is_ascii_digit() || ('a'..='f').contains(&c))
+    {
+        return Err(format!(
+            "provider_config.image digest {digest:?} must be exactly 64 \
+             lowercase hex characters"
+        ));
+    }
+
+    // Drop any tag: `name:tag@sha256:…` and `name@sha256:…` name the same
+    // bytes and must fingerprint identically. Only a *final* colon segment
+    // that isn't a port counts as a tag — `host:5000/name` has no tag.
+    let name = match name_and_tag.rfind(':') {
+        Some(colon) if !name_and_tag[colon + 1..].contains('/') => &name_and_tag[..colon],
+        _ => name_and_tag,
+    };
+    if name.is_empty() {
+        return Err(format!(
+            "provider_config.image {reference:?} has no repository name"
+        ));
+    }
+
+    Ok(ImageRef(format!("{name}@sha256:{hex}")))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn accepts_digest_pinned_reference() {
+        let d = "a".repeat(64);
+        let r = parse(&format!("ghcr.io/block/buzz-sprig@sha256:{d}")).unwrap();
+        assert_eq!(r.as_str(), format!("ghcr.io/block/buzz-sprig@sha256:{d}"));
+    }
+
+    /// The normalization that keeps the fingerprint stable: two spellings of
+    /// the same bytes must produce one reference.
+    #[test]
+    fn strips_tag_from_tag_plus_digest_form() {
+        let d = "b".repeat(64);
+        let tagged = parse(&format!("ghcr.io/block/buzz-sprig:v1.2@sha256:{d}")).unwrap();
+        let plain = parse(&format!("ghcr.io/block/buzz-sprig@sha256:{d}")).unwrap();
+        assert_eq!(tagged, plain);
+    }
+
+    /// A registry port is not a tag. `host:5000/name` must keep its port.
+    #[test]
+    fn registry_port_is_not_mistaken_for_a_tag() {
+        let d = "c".repeat(64);
+        let r = parse(&format!("localhost:5000/buzz-sprig@sha256:{d}")).unwrap();
+        assert_eq!(r.as_str(), format!("localhost:5000/buzz-sprig@sha256:{d}"));
+    }
+
+    #[test]
+    fn port_and_tag_together_drops_only_the_tag() {
+        let d = "d".repeat(64);
+        let r = parse(&format!("localhost:5000/buzz-sprig:dev@sha256:{d}")).unwrap();
+        assert_eq!(r.as_str(), format!("localhost:5000/buzz-sprig@sha256:{d}"));
+    }
+
+    /// Wren's amendment: *every* tag-only reference is rejected, not just
+    /// `:latest`. A `sha-<gitsha>` tag is traceable but still movable.
+    #[test]
+    fn rejects_every_tag_only_reference() {
+        for bad in [
+            "ghcr.io/block/buzz-sprig:latest",
+            "ghcr.io/block/buzz-sprig:v1.2.3",
+            "ghcr.io/block/buzz-sprig:sha-abc1234",
+            "ghcr.io/block/buzz-sprig",
+            "localhost:5000/buzz-sprig",
+        ] {
+            let err = parse(bad).unwrap_err();
+            assert!(err.contains("digest-pinned"), "for {bad:?} got: {err}");
+        }
+    }
+
+    /// Uppercase hex is a second spelling of one digest; accepting it would
+    /// let the same image fingerprint two ways.
+    #[test]
+    fn rejects_uppercase_digest_hex() {
+        let d = "A".repeat(64);
+        assert!(parse(&format!("img@sha256:{d}")).is_err());
+    }
+
+    #[test]
+    fn rejects_malformed_digests() {
+        let short = "a".repeat(63);
+        let long = "a".repeat(65);
+        let ok = "a".repeat(64);
+        for bad in [
+            format!("img@sha256:{short}"),
+            format!("img@sha256:{long}"),
+            format!("img@sha512:{ok}"),
+            format!("img@{ok}"),
+            format!("img@sha256:{}", "g".repeat(64)),
+            format!("img@sha256:{ok}@sha256:{ok}"),
+            format!("@sha256:{ok}"),
+        ] {
+            assert!(parse(&bad).is_err(), "accepted {bad:?}");
+        }
+    }
+
+    /// Parsing has no fallback (the schema default is a UI prefill, not a
+    /// parse-time substitute), so an absent image is an error that names the
+    /// field rather than a silent fallback.
+    #[test]
+    fn empty_reference_names_the_field() {
+        for empty in ["", "   "] {
+            let err = parse(empty).unwrap_err();
+            assert!(err.contains("provider_config.image"), "got: {err}");
+        }
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/intent.rs b/crates/buzz-backend-kubernetes/src/intent.rs
new file mode 100644
index 0000000000..73218f83bf
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/intent.rs
@@ -0,0 +1,309 @@
+//! The create-intent fingerprint (spec §Deploy State Machine, create-intent
+//! fingerprint, `docs/remote-agents.md:796-828`).
+//!
+//! The fingerprint is an unkeyed SHA-256 over a canonical serialization of the
+//! provider's non-secret create-intent template. A plain hash is safe *only*
+//! because of the scope rule: the input covers exactly the provider-controlled
+//! fields that can affect scheduling or container creation, and **never Secret
+//! data or attempt identity**. Hashing low-entropy secrets into a
+//! world-readable annotation would be a dictionary oracle.
+//!
+//! That rule is enforced structurally rather than remembered. [`IntentTemplate`]
+//! is a *pre-binding* type: it has no field that can hold Secret material or a
+//! generation token, so there is no expression that hashes one. The
+//! per-attempt Secret name never appears — the pod's `envFrom` is represented
+//! by the fixed [`SECRET_PLACEHOLDER`], because otherwise every attempt would
+//! diverge from every other by construction.
+//!
+//! Server- and admission-produced output (UID, `resourceVersion`, timestamps,
+//! defaulted fields, the annotation itself) is excluded the same way: the
+//! serializer is only ever handed this template, never a live `Pod`, so the
+//! exclusion is checkable by inspection.
+
+use crate::image::ImageRef;
+use serde::Serialize;
+use sha2::{Digest, Sha256};
+
+/// Stands in for the per-attempt Secret name in the `envFrom` position.
+/// A real generation token here would make every attempt diverge.
+const SECRET_PLACEHOLDER: &str = "<per-attempt-secret>";
+
+/// The recorded/computed create intent: a hex SHA-256 digest.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Fingerprint(String);
+
+impl Fingerprint {
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+
+    /// Read a fingerprint off a pod annotation. Any recorded string is
+    /// accepted verbatim: comparison is equality against a freshly computed
+    /// value, so a malformed annotation simply reads as divergence — which is
+    /// the correct outcome for a pod this provider version did not write.
+    pub fn from_annotation(value: &str) -> Self {
+        Self(value.to_string())
+    }
+
+    #[cfg(test)]
+    pub fn for_test(seed: &str) -> Self {
+        Self(format!("test-{seed}"))
+    }
+}
+
+impl std::fmt::Display for Fingerprint {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+/// The non-secret, pre-binding description of the pod this deploy would
+/// create. Every field is provider-controlled and scheduling-relevant; there
+/// is deliberately no field for env values, Secret data, or the generation.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct IntentTemplate {
+    /// Schema version of the template itself. Bumping it re-fingerprints every
+    /// pod, which is the intended way to roll out a pod-shape change.
+    pub template_version: u32,
+    pub namespace: String,
+    /// Normalized, digest-qualified image reference.
+    pub image: String,
+    pub cpu_request: String,
+    pub memory_request: String,
+    pub cpu_limit: String,
+    pub memory_limit: String,
+    pub service_account: Option<String>,
+    pub restart_policy: &'static str,
+    pub termination_grace_period_seconds: i64,
+    /// Env *keys* only, sorted. Keys are pod-shape (a renamed key changes the
+    /// container's contract); values are Secret material and must not be here.
+    pub env_keys: Vec<String>,
+    /// Fixed placeholder for the per-attempt Secret in `envFrom`.
+    pub env_from_secret: &'static str,
+    pub workspace_mount_path: String,
+    pub run_as_user: i64,
+    pub run_as_group: i64,
+}
+
+/// Current template schema version.
+pub const TEMPLATE_VERSION: u32 = 1;
+
+impl IntentTemplate {
+    /// Compute the fingerprint. `serde_json` on a struct with declared field
+    /// order plus pre-sorted `env_keys` is a canonical serialization: the same
+    /// template always produces the same bytes.
+    pub fn fingerprint(&self) -> Fingerprint {
+        let canonical = serde_json::to_vec(self).expect("intent template is plain data");
+        Fingerprint(hex::encode(Sha256::digest(&canonical)))
+    }
+
+    /// Build from resolved pod-shape inputs. `env_keys` is sorted here rather
+    /// than at the call site so key ordering can never leak into the digest.
+    ///
+    /// The fixed pod-shape constants are read from [`crate::config`] rather
+    /// than passed in: `pod::build_pod` stamps the pod from those same
+    /// constants, so the fingerprint cannot describe a pod shape different
+    /// from the one actually created. Threading them through as arguments
+    /// would make that agreement a thing to test instead of a thing that holds.
+    pub fn new(
+        namespace: &str,
+        image: &ImageRef,
+        resources: &crate::config::Resources,
+        service_account: Option<&str>,
+        env_keys: impl IntoIterator<Item = String>,
+    ) -> Self {
+        let mut env_keys: Vec<String> = env_keys.into_iter().collect();
+        env_keys.sort();
+        Self {
+            template_version: TEMPLATE_VERSION,
+            namespace: namespace.to_string(),
+            image: image.as_str().to_string(),
+            cpu_request: resources.cpu_request.clone(),
+            memory_request: resources.memory_request.clone(),
+            cpu_limit: resources.cpu_limit.clone(),
+            memory_limit: resources.memory_limit.clone(),
+            service_account: service_account.map(str::to_string),
+            restart_policy: crate::config::RESTART_POLICY,
+            termination_grace_period_seconds: crate::config::TERMINATION_GRACE_SECONDS,
+            env_keys,
+            env_from_secret: SECRET_PLACEHOLDER,
+            workspace_mount_path: crate::config::WORKSPACE_PATH.to_string(),
+            run_as_user: crate::config::RUN_AS_UID,
+            run_as_group: crate::config::RUN_AS_GID,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::Resources;
+
+    fn image(byte: char) -> ImageRef {
+        crate::image::parse(&format!(
+            "ghcr.io/block/buzz-sprig@sha256:{}",
+            byte.to_string().repeat(64)
+        ))
+        .unwrap()
+    }
+
+    fn template() -> IntentTemplate {
+        IntentTemplate::new(
+            "buzz-agents",
+            &image('a'),
+            &Resources::default(),
+            None,
+            ["BUZZ_RELAY_URL".to_string(), "GOOSE_MODE".to_string()],
+        )
+    }
+
+    #[test]
+    fn fingerprint_is_deterministic() {
+        assert_eq!(template().fingerprint(), template().fingerprint());
+    }
+
+    #[test]
+    fn fingerprint_is_hex_sha256() {
+        let fp = template().fingerprint();
+        assert_eq!(fp.as_str().len(), 64);
+        assert!(fp.as_str().chars().all(|c| c.is_ascii_hexdigit()));
+    }
+
+    /// Key *order* must not reach the digest, or two identical environments
+    /// built in different orders would look like a config change.
+    #[test]
+    fn env_key_order_does_not_affect_the_digest() {
+        let a = IntentTemplate::new(
+            "ns",
+            &image('a'),
+            &Resources::default(),
+            None,
+            ["A".to_string(), "B".to_string(), "C".to_string()],
+        );
+        let b = IntentTemplate::new(
+            "ns",
+            &image('a'),
+            &Resources::default(),
+            None,
+            ["C".to_string(), "A".to_string(), "B".to_string()],
+        );
+        assert_eq!(a.fingerprint(), b.fingerprint());
+    }
+
+    /// A mutation applied to a fresh template clone, named for its assertion
+    /// message.
+    type Mutation = (&'static str, Box<dyn Fn(&mut IntentTemplate)>);
+
+    /// Every scheduling-relevant knob must move the digest — this is the
+    /// wedge escape (§Deploy State Machine never-started recoverable row).
+    /// Exhaustive by construction: each mutation is applied to a fresh clone.
+    #[test]
+    fn every_scheduling_field_changes_the_digest() {
+        let base = template();
+        let baseline = base.fingerprint();
+
+        let mutations: Vec<Mutation> = vec![
+            (
+                "template_version",
+                Box::new(|t: &mut IntentTemplate| t.template_version += 1),
+            ),
+            (
+                "namespace",
+                Box::new(|t: &mut IntentTemplate| t.namespace = "other".into()),
+            ),
+            (
+                "image",
+                Box::new(|t: &mut IntentTemplate| t.image = image('b').as_str().into()),
+            ),
+            (
+                "cpu_request",
+                Box::new(|t: &mut IntentTemplate| t.cpu_request = "4".into()),
+            ),
+            (
+                "memory_request",
+                Box::new(|t: &mut IntentTemplate| t.memory_request = "8Gi".into()),
+            ),
+            (
+                "cpu_limit",
+                Box::new(|t: &mut IntentTemplate| t.cpu_limit = "8".into()),
+            ),
+            (
+                "memory_limit",
+                Box::new(|t: &mut IntentTemplate| t.memory_limit = "16Gi".into()),
+            ),
+            (
+                "service_account",
+                Box::new(|t: &mut IntentTemplate| t.service_account = Some("sa".into())),
+            ),
+            (
+                "restart_policy",
+                Box::new(|t: &mut IntentTemplate| t.restart_policy = "OnFailure"),
+            ),
+            (
+                "grace_period",
+                Box::new(|t: &mut IntentTemplate| t.termination_grace_period_seconds = 30),
+            ),
+            (
+                "env_keys",
+                Box::new(|t: &mut IntentTemplate| t.env_keys.push("NEW_KEY".into())),
+            ),
+            (
+                "workspace_mount_path",
+                Box::new(|t: &mut IntentTemplate| t.workspace_mount_path = "/w".into()),
+            ),
+            (
+                "run_as_user",
+                Box::new(|t: &mut IntentTemplate| t.run_as_user = 2000),
+            ),
+            (
+                "run_as_group",
+                Box::new(|t: &mut IntentTemplate| t.run_as_group = 2000),
+            ),
+        ];
+
+        for (name, mutate) in mutations {
+            let mut t = base.clone();
+            mutate(&mut t);
+            assert_ne!(
+                t.fingerprint(),
+                baseline,
+                "{name} did not affect the digest"
+            );
+        }
+    }
+
+    /// The scope rule, asserted on the bytes: no Secret value and no
+    /// generation token can appear in the serialization, because the type has
+    /// nowhere to put them. The placeholder is what `envFrom` contributes.
+    #[test]
+    fn serialization_contains_no_secret_material_or_attempt_identity() {
+        let json = serde_json::to_string(&template()).unwrap();
+        for forbidden in ["nsec1", "SPOOFED", "wss://", "gen0001"] {
+            assert!(
+                !json.contains(forbidden),
+                "template leaked {forbidden}: {json}"
+            );
+        }
+        assert!(json.contains(SECRET_PLACEHOLDER));
+    }
+
+    /// Two attempts for the same agent differ only in generation, which is
+    /// absent from the template — so their fingerprints must be equal, or the
+    /// divergence discriminator would fire on every single deploy.
+    #[test]
+    fn attempts_differing_only_by_generation_do_not_diverge() {
+        // There is no generation input to pass; that *is* the property. The
+        // test states it explicitly so a future field addition breaks here.
+        assert_eq!(template().fingerprint(), template().fingerprint());
+        let json = serde_json::to_string(&template()).unwrap();
+        assert_eq!(json.matches(SECRET_PLACEHOLDER).count(), 1);
+    }
+
+    /// A recorded annotation this provider version did not write reads as
+    /// divergence rather than an error.
+    #[test]
+    fn unrecognized_annotation_reads_as_divergence() {
+        let recorded = Fingerprint::from_annotation("not-a-digest");
+        assert_ne!(recorded, template().fingerprint());
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/main.rs b/crates/buzz-backend-kubernetes/src/main.rs
new file mode 100644
index 0000000000..5d521a9d37
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/main.rs
@@ -0,0 +1,199 @@
+//! Kubernetes backend provider for Buzz remote agents
+//! (spec `docs/remote-agents.md`).
+//!
+//! One process per operation: read exactly one JSON request from stdin, write
+//! exactly one JSON response to stdout, exit. The exit code carries exactly
+//! one bit — 0 for a response that was produced, 1 for a failure to produce
+//! one. Everything a caller needs to distinguish is *inside* the response's
+//! `ok` field, because a provider that encoded outcomes in exit codes would
+//! have a second, redundant error channel to keep in sync (§Provider Protocol).
+
+mod classify;
+mod client;
+mod cluster;
+mod config;
+mod env;
+mod gc;
+mod image;
+mod intent;
+mod naming;
+mod observe;
+mod pod;
+mod reconcile;
+mod wire;
+
+use std::io::Read;
+use wire::{Request, Response};
+
+/// The provider a shared-compute agent resolves to. Refused here as the
+/// spec's backstop: a mesh agent runs on the relay's compute, so deploying it
+/// as a pod would create a second, contending consumer of the same agent
+/// identity (`:214-219`).
+const RELAY_MESH_PROVIDER: &str = "relay-mesh";
+
+fn main() {
+    // rustls needs a process-level provider before the first TLS connection.
+    // The release build compiles every sidecar in one cargo invocation, which
+    // unifies the `ring` and `aws-lc-rs` features and leaves rustls unable to
+    // auto-select — so this is an explicit install, not a default.
+    let _ = rustls::crypto::ring::default_provider().install_default();
+
+    let mut input = String::new();
+    if let Err(e) = std::io::stdin().read_to_string(&mut input) {
+        // No request means no request_id and no response contract to honor.
+        // This is the one path that exits nonzero.
+        eprintln!("could not read the request from stdin: {e}");
+        std::process::exit(1);
+    }
+
+    let response = respond(&input);
+    println!(
+        "{}",
+        serde_json::to_string(&response).unwrap_or_else(|e| {
+            // The response types are plain data; this cannot fail in practice,
+            // and a hand-built object is still a conforming response.
+            format!(r#"{{"ok":false,"error":"could not serialize a response: {e}"}}"#)
+        })
+    );
+}
+
+/// Produce the single response for one request. Separated from `main` so the
+/// whole dispatch is testable without a process.
+fn respond(input: &str) -> Response {
+    // Parsed as raw JSON first: the relay-mesh refusal below MUST see the wire
+    // value, and `AgentPayload` deliberately does not carry `provider`.
+    let raw: serde_json::Value = match serde_json::from_str(input) {
+        Ok(value) => value,
+        Err(e) => return Response::error(format!("request is not valid JSON: {e}")),
+    };
+
+    if let Some(refusal) = refuse_relay_mesh(&raw) {
+        return Response::error(refusal);
+    }
+
+    let request: Request = match serde_json::from_value(raw) {
+        Ok(request) => request,
+        Err(e) => return Response::error(format!("could not understand the request: {e}")),
+    };
+
+    match request {
+        Request::Info => Response::info(),
+        Request::Deploy(deploy) => {
+            let runtime = match tokio::runtime::Builder::new_current_thread()
+                .enable_all()
+                .build()
+            {
+                Ok(runtime) => runtime,
+                Err(e) => return Response::error(format!("could not start the runtime: {e}")),
+            };
+            match runtime.block_on(deploy_agent(&deploy)) {
+                Ok(agent_id) => Response::deployed(agent_id),
+                Err(e) => Response::error(e),
+            }
+        }
+    }
+}
+
+/// Refuse a shared-compute agent, reading the **raw wire value**.
+///
+/// Trimmed before comparing: the desktop's own layers disagree about padding
+/// (`relay_mesh.rs:17` and `effective_config/mod.rs:46` trim; the deploy guard
+/// at `agents_deploy.rs:116` did not), and `non_blank` preserves surrounding
+/// whitespace on a non-blank value. A backstop that shares its bypass with the
+/// layer it backs is not a backstop.
+fn refuse_relay_mesh(raw: &serde_json::Value) -> Option<String> {
+    let provider = raw.get("agent")?.get("provider")?.as_str()?;
+    (provider.trim() == RELAY_MESH_PROVIDER).then(|| {
+        "deploy refused: this agent is configured for shared compute \
+         (relay-mesh), which runs on the relay rather than in a pod. \
+         Switch the agent to a local runtime before deploying it to \
+         Kubernetes."
+            .to_string()
+    })
+}
+
+/// Run one deploy to a terminal outcome.
+async fn deploy_agent(request: &wire::DeployRequest) -> Result<String, String> {
+    let cfg = config::parse(&request.provider_config)?;
+    // Identity before any cluster contact: a malformed nsec is a refusal, not
+    // a failed connection (§Deploy State Machine step 0).
+    let identity = naming::AgentIdentity::from_nsec(&request.agent.private_key_nsec)?;
+
+    // One generation for this operation's first attempt; the reconciler mints
+    // its own per attempt and restamps the correlator to match.
+    let env = env::build_env(
+        &request.agent,
+        env::AuthoritativeInputs {
+            generation: &naming::new_generation(),
+            inactivity_seconds: cfg.inactivity_seconds,
+        },
+    )?;
+
+    let client = client::connect(cfg.context.as_deref()).await?;
+    let substrate = cluster::Cluster::new(client, &cfg.namespace);
+    reconcile::deploy(&substrate, &identity, &cfg, env).await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn error_of(response: &Response) -> String {
+        let json = serde_json::to_value(response).unwrap();
+        assert_eq!(json["ok"], false, "expected a refusal: {json}");
+        json["error"].as_str().unwrap().to_string()
+    }
+
+    /// The spec's backstop for the relay-mesh MUST. The desktop refuses first
+    /// (`agents_deploy.rs:116`); this is the layer that owes the obligation.
+    #[test]
+    fn refuses_a_relay_mesh_agent() {
+        let request = r#"{"op":"deploy","agent":{
+            "relay_url":"wss://r","private_key_nsec":"nsec1x","provider":"relay-mesh"},
+            "provider_config":{"namespace":"ns"}}"#;
+        assert!(error_of(&respond(request)).contains("relay-mesh"));
+    }
+
+    /// Padding must not bypass the backstop. Reachable by construction:
+    /// `GlobalConfig.provider` is a bare `Option<String>` with no trim on
+    /// write, and `non_blank` rejects whitespace-only while preserving
+    /// surrounding whitespace on everything else.
+    #[test]
+    fn refuses_a_padded_relay_mesh_agent() {
+        let request = r#"{"op":"deploy","agent":{
+            "relay_url":"wss://r","private_key_nsec":"nsec1x","provider":"  relay-mesh  "},
+            "provider_config":{"namespace":"ns"}}"#;
+        assert!(error_of(&respond(request)).contains("relay-mesh"));
+    }
+
+    /// The refusal must not fire on a normal agent — a guard that refuses
+    /// everything passes its own test and ships a provider that deploys
+    /// nothing.
+    #[test]
+    fn does_not_refuse_a_normal_provider() {
+        let raw: serde_json::Value =
+            serde_json::from_str(r#"{"agent":{"provider":"openai"}}"#).unwrap();
+        assert!(refuse_relay_mesh(&raw).is_none());
+        // …nor when the field is absent entirely, which is the common case:
+        // `AgentPayload` does not carry `provider`.
+        let bare: serde_json::Value = serde_json::from_str(r#"{"agent":{}}"#).unwrap();
+        assert!(refuse_relay_mesh(&bare).is_none());
+    }
+
+    /// Malformed input still produces exactly one conforming response.
+    #[test]
+    fn malformed_input_is_an_in_band_error() {
+        assert!(error_of(&respond("not json")).contains("valid JSON"));
+        assert!(error_of(&respond(r#"{"op":"undeploy"}"#)).contains("understand"));
+    }
+
+    /// `info` answers without touching a cluster — it is what the desktop
+    /// calls to render the config form, before any kubeconfig exists.
+    #[test]
+    fn info_answers_with_the_protocol_version_and_schema() {
+        let json = serde_json::to_value(respond(r#"{"op":"info"}"#)).unwrap();
+        assert_eq!(json["ok"], true);
+        assert_eq!(json["protocol_version"], wire::PROTOCOL_VERSION);
+        assert!(json["config_schema"]["properties"]["namespace"].is_object());
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/naming.rs b/crates/buzz-backend-kubernetes/src/naming.rs
new file mode 100644
index 0000000000..4b9d7ea035
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/naming.rs
@@ -0,0 +1,223 @@
+//! Identity derivation and the object-naming contract (spec §Pod shape).
+//!
+//! Every name, label, and annotation below is derived from the pubkey the
+//! provider decoded itself from `private_key_nsec` — never from a
+//! caller-supplied pubkey (§Deploy State Machine step 0).
+
+use nostr::nips::nip19::FromBech32;
+
+/// `app.kubernetes.io/managed-by` value: the management marker's identity half.
+pub const MANAGED_BY: &str = "buzz-backend-kubernetes";
+
+/// Label key carrying [`MANAGED_BY`].
+pub const LABEL_MANAGED_BY: &str = "app.kubernetes.io/managed-by";
+
+/// Label key carrying [`BINDING_VERSION`] — the marker's schema half.
+pub const LABEL_BINDING_VERSION: &str = "buzz.block.xyz/binding-version";
+
+/// Schema version of the object layout this provider writes. Bumped when the
+/// pod/Secret shape changes in a way a older provider would mis-handle.
+pub const BINDING_VERSION: &str = "1";
+
+/// Label key: truncated pubkey, the reconciliation and GC selector.
+pub const LABEL_AGENT_PUBKEY: &str = "buzz.block.xyz/agent-pubkey";
+
+/// Annotation key: full pubkey. Load-bearing — the truncated label is
+/// collision-*resistant*, this is what makes it safe (§Deploy State Machine
+/// step 1).
+pub const ANNOTATION_PUBKEY_FULL: &str = "buzz.block.xyz/agent-pubkey-full";
+
+/// Annotation key: the recorded create-intent fingerprint.
+pub const ANNOTATION_CREATE_INTENT: &str = "buzz.block.xyz/create-intent";
+
+/// Annotation key: the image reference this generation actually resolved to,
+/// for post-hoc attribution (§Image).
+pub const ANNOTATION_IMAGE: &str = "buzz.block.xyz/image";
+
+/// An agent identity the provider derived itself, plus every name it implies.
+///
+/// Constructing this type is the *only* way to obtain the names — so a
+/// caller-supplied pubkey cannot reach a selector by any path.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AgentIdentity {
+    pubkey_hex: String,
+}
+
+impl AgentIdentity {
+    /// Derive from the payload's `private_key_nsec`.
+    ///
+    /// Accepts bech32 `nsec1…`; a malformed or undecodable key is an
+    /// immediate error, before any substrate read or mutation
+    /// (§Deploy State Machine step 0).
+    pub fn from_nsec(nsec: &str) -> Result<Self, String> {
+        let secret = nostr::SecretKey::from_bech32(nsec.trim())
+            .map_err(|_| "private_key_nsec is not a decodable nsec1 key".to_string())?;
+        let keys = nostr::Keys::new(secret);
+        Ok(Self {
+            pubkey_hex: keys.public_key().to_hex(),
+        })
+    }
+
+    /// Full 64-hex public key — the annotation value and the comparison
+    /// operand for candidate authentication.
+    pub fn pubkey_hex(&self) -> &str {
+        &self.pubkey_hex
+    }
+
+    /// Selector label value: first 32 hex chars (128 bits). A full hex pubkey
+    /// is 64 chars and label values cap at 63, which is why this is truncated
+    /// and why the annotation check is normative rather than decorative.
+    pub fn label_pubkey(&self) -> &str {
+        &self.pubkey_hex[..32]
+    }
+
+    /// Deterministic pod name, also the returned `agent_id`.
+    pub fn pod_name(&self) -> String {
+        format!("buzz-agent-{}", &self.pubkey_hex[..12])
+    }
+
+    /// Per-attempt Secret name. `generation` is a fresh random token per
+    /// create attempt — never reused — which is what makes payload and Secret
+    /// atomic at the pod-spec boundary (§K8s Secrets).
+    pub fn secret_name(&self, generation: &str) -> String {
+        format!("buzz-agent-{}-{}", &self.pubkey_hex[..12], generation)
+    }
+
+    /// Label selector matching this identity's objects *and* our management
+    /// marker. Selecting on the marker as well as the identity means an
+    /// unmarked look-alike never even enters the candidate list.
+    pub fn selector(&self) -> String {
+        format!(
+            "{LABEL_AGENT_PUBKEY}={},{LABEL_MANAGED_BY}={MANAGED_BY}",
+            self.label_pubkey()
+        )
+    }
+
+    /// The label set stamped on every object this provider creates.
+    pub fn labels(&self) -> std::collections::BTreeMap<String, String> {
+        [
+            (
+                LABEL_AGENT_PUBKEY.to_string(),
+                self.label_pubkey().to_string(),
+            ),
+            (LABEL_MANAGED_BY.to_string(), MANAGED_BY.to_string()),
+            (
+                LABEL_BINDING_VERSION.to_string(),
+                BINDING_VERSION.to_string(),
+            ),
+        ]
+        .into_iter()
+        .collect()
+    }
+}
+
+/// A fresh generation token: 8 lowercase hex chars from the OS RNG.
+///
+/// Appears in the Secret name and as `BUZZ_MANAGED_AGENT_START_NONCE`, so the
+/// Secret generation and the harness's lifecycle-frame correlator are one
+/// identity (§Launch data tier 3).
+pub fn new_generation() -> String {
+    use rand::RngExt;
+    let n: u32 = rand::rng().random();
+    format!("{n:08x}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// A fixed test key. Deriving the pubkey (rather than hardcoding both
+    /// halves) is the point: the test exercises the same derivation the
+    /// reconciler depends on.
+    fn identity() -> AgentIdentity {
+        let keys = nostr::Keys::generate();
+        let nsec = {
+            use nostr::nips::nip19::ToBech32;
+            keys.secret_key().to_bech32().unwrap()
+        };
+        let id = AgentIdentity::from_nsec(&nsec).unwrap();
+        assert_eq!(id.pubkey_hex(), keys.public_key().to_hex());
+        id
+    }
+
+    #[test]
+    fn rejects_malformed_nsec() {
+        for bad in ["", "nsec1", "not-a-key", "npub1abc"] {
+            assert!(
+                AgentIdentity::from_nsec(bad).is_err(),
+                "accepted malformed key {bad:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn tolerates_surrounding_whitespace() {
+        let keys = nostr::Keys::generate();
+        use nostr::nips::nip19::ToBech32;
+        let nsec = keys.secret_key().to_bech32().unwrap();
+        let padded = format!("  {nsec}\n");
+        assert_eq!(
+            AgentIdentity::from_nsec(&padded).unwrap().pubkey_hex(),
+            keys.public_key().to_hex()
+        );
+    }
+
+    /// Kubernetes label *values* cap at 63 chars; a full hex pubkey is 64,
+    /// one over. That one-char overflow is the whole reason the selector is
+    /// truncated, so it gets an explicit test.
+    #[test]
+    fn label_value_fits_kubernetes_limit() {
+        let id = identity();
+        assert_eq!(id.pubkey_hex().len(), 64);
+        assert_eq!(id.label_pubkey().len(), 32);
+        assert!(id.label_pubkey().len() <= 63);
+    }
+
+    #[test]
+    fn pod_name_is_deterministic_and_dns_safe() {
+        let id = identity();
+        assert_eq!(id.pod_name(), id.pod_name());
+        assert_eq!(
+            id.pod_name(),
+            format!("buzz-agent-{}", &id.pubkey_hex()[..12])
+        );
+        assert!(id.pod_name().len() <= 253);
+        assert!(id
+            .pod_name()
+            .chars()
+            .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-'));
+    }
+
+    /// Two attempts must never share a Secret name — that uniqueness is what
+    /// stops a losing contender from overwriting the winner's identity.
+    #[test]
+    fn secret_names_are_per_attempt() {
+        let id = identity();
+        let a = id.secret_name(&new_generation());
+        let b = id.secret_name(&new_generation());
+        assert_ne!(a, b);
+        assert!(a.starts_with(&id.pod_name()));
+        assert!(a.len() <= 253);
+    }
+
+    #[test]
+    fn selector_requires_the_management_marker() {
+        let id = identity();
+        let sel = id.selector();
+        assert!(sel.contains(&format!("{LABEL_AGENT_PUBKEY}={}", id.label_pubkey())));
+        assert!(sel.contains(&format!("{LABEL_MANAGED_BY}={MANAGED_BY}")));
+    }
+
+    #[test]
+    fn every_created_object_carries_the_marker() {
+        let labels = identity().labels();
+        assert_eq!(
+            labels.get(LABEL_MANAGED_BY).map(String::as_str),
+            Some(MANAGED_BY)
+        );
+        assert_eq!(
+            labels.get(LABEL_BINDING_VERSION).map(String::as_str),
+            Some(BINDING_VERSION)
+        );
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/observe.rs b/crates/buzz-backend-kubernetes/src/observe.rs
new file mode 100644
index 0000000000..1c6c883563
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/observe.rs
@@ -0,0 +1,592 @@
+//! Decoding API objects into verified observations (spec §Deploy State
+//! Machine step 1).
+//!
+//! Pure: `Pod` in, [`VerifiedPod`] out. Keeping the decode here means the
+//! conformance tests drive the *shipped* decoder with real API types rather
+//! than a test-only stand-in, and it keeps `classify.rs` free of API types.
+//!
+//! Verification is the gate, not a filter: [`verify`] returns `None` for any
+//! object whose full-pubkey annotation does not equal the derived pubkey or
+//! that lacks the management marker, so an unverified object cannot reach
+//! classification, deletion, or the returned `agent_id`.
+
+use crate::classify::{Fence, PullFailure, Startup, VerifiedPod};
+use crate::intent::Fingerprint;
+use crate::naming::{
+    AgentIdentity, ANNOTATION_CREATE_INTENT, ANNOTATION_PUBKEY_FULL, BINDING_VERSION,
+    LABEL_BINDING_VERSION, LABEL_MANAGED_BY, MANAGED_BY,
+};
+use k8s_openapi::api::core::v1::{Pod, Secret};
+
+/// Container name the provider creates; status is read from this container.
+pub const CONTAINER_NAME: &str = "agent";
+
+/// The startup state, or a state that cannot be settled without one more read.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum StartupObservation {
+    Resolved(Startup),
+    /// `CreateContainerConfigError` — recoverable *unless* the referenced
+    /// Secret is confirmed absent by a most-recent read. The kubelet's reason
+    /// string is a hint; the provider verifies before treating it as fatal
+    /// (§Deploy State Machine: "provably" means a verified absence, never a
+    /// reason string).
+    ConfigErrorPendingSecretCheck {
+        secret_name: String,
+    },
+}
+
+/// Does this object carry the management marker (§Pod shape)?
+///
+/// Identity labels prove identity; the marker asserts protocol ownership.
+/// Without it an object that merely matches our schema fails closed.
+fn has_marker(labels: Option<&std::collections::BTreeMap<String, String>>) -> bool {
+    let Some(labels) = labels else { return false };
+    labels.get(LABEL_MANAGED_BY).map(String::as_str) == Some(MANAGED_BY)
+        && labels.get(LABEL_BINDING_VERSION).map(String::as_str) == Some(BINDING_VERSION)
+}
+
+/// Does the full-pubkey annotation equal the derived pubkey?
+///
+/// The 32-hex label is collision-*resistant*, not collision-free, which is
+/// why this check is normative rather than decorative (`:1152-1166`).
+fn annotation_matches(
+    annotations: Option<&std::collections::BTreeMap<String, String>>,
+    identity: &AgentIdentity,
+) -> bool {
+    annotations
+        .and_then(|a| a.get(ANNOTATION_PUBKEY_FULL))
+        .map(|v| v == identity.pubkey_hex())
+        .unwrap_or(false)
+}
+
+/// Is this Secret ours and this identity's? The same fence GC applies before
+/// deleting anything.
+pub fn secret_is_ours(secret: &Secret, identity: &AgentIdentity) -> bool {
+    has_marker(secret.metadata.labels.as_ref())
+        && annotation_matches(secret.metadata.annotations.as_ref(), identity)
+}
+
+/// Decode a pod's startup state from its status.
+///
+/// "Started" means `state.running` on our container — not pod phase. A pod can
+/// sit in phase `Running` with a container that never started, and a pod being
+/// gracefully deleted stays in phase `Running` for its whole grace period.
+pub fn decode_startup(pod: &Pod) -> StartupObservation {
+    use StartupObservation::Resolved;
+
+    let status = pod.status.as_ref();
+    let phase = status.and_then(|s| s.phase.as_deref());
+
+    let container = status
+        .and_then(|s| s.container_statuses.as_ref())
+        .and_then(|cs| cs.iter().find(|c| c.name == CONTAINER_NAME));
+
+    if let Some(state) = container.and_then(|c| c.state.as_ref()) {
+        if state.running.is_some() {
+            return Resolved(Startup::Started);
+        }
+        if state.terminated.is_some() {
+            return Resolved(Startup::Terminated);
+        }
+        if let Some(waiting) = state.waiting.as_ref() {
+            let reason = waiting.reason.as_deref().unwrap_or_default();
+            let message = waiting.message.as_deref().unwrap_or_default();
+            return match reason {
+                // Structurally invalid reference: no retry can fix it.
+                "InvalidImageName" => Resolved(Startup::NeverStartedProvablyBroken),
+                "ErrImagePull" | "ImagePullBackOff" => match classify_pull_failure(message) {
+                    Some(failure) => Resolved(Startup::NeverStartedPullFailing(failure)),
+                    None => Resolved(Startup::NeverStartedRecoverable),
+                },
+                "CreateContainerConfigError" => match referenced_secret(pod) {
+                    Some(secret_name) => {
+                        StartupObservation::ConfigErrorPendingSecretCheck { secret_name }
+                    }
+                    None => Resolved(Startup::NeverStartedRecoverable),
+                },
+                _ => Resolved(Startup::NeverStartedRecoverable),
+            };
+        }
+    }
+
+    // No container status yet (unscheduled, image pulling before the kubelet
+    // reports, quota-blocked). A terminal phase without container status still
+    // means the pod is done.
+    match phase {
+        Some("Succeeded") | Some("Failed") => Resolved(Startup::Terminated),
+        _ => Resolved(Startup::NeverStartedRecoverable),
+    }
+}
+
+/// The Secret name this pod's `envFrom` references, if any.
+pub fn referenced_secret(pod: &Pod) -> Option<String> {
+    pod.spec
+        .as_ref()?
+        .containers
+        .iter()
+        .flat_map(|c| c.env_from.iter().flatten())
+        .find_map(|source| source.secret_ref.as_ref().map(|r| r.name.clone()))
+}
+
+/// Classify a pull failure from the kubelet's message.
+///
+/// Reporting only — [`PullFailure`] is structurally excluded from
+/// `Action::Delete`, so a wrong guess here can delay a report but can never
+/// destroy anything. `None` means "no permanent cause recognized", which
+/// leaves the pod on the ordinary observational path.
+fn classify_pull_failure(message: &str) -> Option<PullFailure> {
+    let m = message.to_ascii_lowercase();
+    if m.contains("401")
+        || m.contains("unauthorized")
+        || m.contains("403")
+        || m.contains("denied")
+        || m.contains("authentication required")
+    {
+        return Some(PullFailure::Unauthorized);
+    }
+    if m.contains("manifest unknown")
+        || m.contains("not found")
+        || m.contains("manifest_unknown")
+        || m.contains("repository does not exist")
+    {
+        return Some(PullFailure::ManifestUnknown);
+    }
+    if m.contains("no match for platform") || m.contains("no matching manifest") {
+        return Some(PullFailure::ArchMismatch);
+    }
+    None
+}
+
+/// The redacted, actionable condition text for a pull failure.
+///
+/// Names the registry and the immutable reference — never credentials, and
+/// never the kubelet's raw message, which can echo a registry token.
+pub fn pull_failure_message(failure: PullFailure, image: &str) -> String {
+    let registry = image.split('/').next().unwrap_or(image);
+    match failure {
+        PullFailure::Unauthorized => format!(
+            "the cluster is not authorized to pull {image} from {registry}. \
+             This pull retries indefinitely and will not succeed on its own: \
+             grant the cluster's nodes access to that registry."
+        ),
+        PullFailure::ManifestUnknown => {
+            format!("{registry} has no image at {image}. Check the digest and repository.")
+        }
+        PullFailure::ArchMismatch => format!(
+            "{image} has no variant for the architecture of the nodes it was \
+             scheduled on."
+        ),
+    }
+}
+
+/// The latest actionable condition for a pod that has not started, redacted.
+///
+/// Two sources, deliberately treated differently:
+///
+/// * The container's waiting **reason** is included; its **message** is not.
+///   Waiting messages are kubelet-composed and echo the thing that failed —
+///   for a pull that is the registry request, which can carry credential
+///   material. The reason token alone (`ImagePullBackOff`,
+///   `CreateContainerConfigError`) is the diagnostic; the message adds
+///   exposure, not information the user can act on.
+/// * Pod-condition messages **are** included. They are scheduler- and
+///   kubelet-composed from the pod's own spec and cluster capacity
+///   ("0/3 nodes are available: Insufficient memory"), which is precisely the
+///   actionable half and contains nothing derived from Secret data.
+pub fn condition(pod: &Pod) -> Option<String> {
+    let status = pod.status.as_ref()?;
+
+    if let Some(state) = status
+        .container_statuses
+        .as_ref()
+        .and_then(|cs| cs.iter().find(|c| c.name == CONTAINER_NAME))
+        .and_then(|c| c.state.as_ref())
+    {
+        if let Some(waiting) = state.waiting.as_ref() {
+            if let Some(reason) = waiting.reason.as_deref() {
+                return Some(format!("the container is waiting, reason {reason}"));
+            }
+        }
+        // Exit code and reason only — the terminated `message` is
+        // process-composed output and falls under the same redaction rule as
+        // waiting messages.
+        if let Some(terminated) = state.terminated.as_ref() {
+            return Some(match terminated.reason.as_deref() {
+                Some(reason) => format!(
+                    "the container exited with code {} ({reason})",
+                    terminated.exit_code
+                ),
+                None => format!("the container exited with code {}", terminated.exit_code),
+            });
+        }
+    }
+
+    if let Some((type_, reason, message)) = status.conditions.as_ref().and_then(|cs| {
+        cs.iter().find(|c| c.status == "False").map(|c| {
+            (
+                c.type_.clone(),
+                c.reason.clone().unwrap_or_default(),
+                c.message.clone().unwrap_or_default(),
+            )
+        })
+    }) {
+        let detail = [reason, message]
+            .into_iter()
+            .filter(|s| !s.is_empty())
+            .collect::<Vec<_>>()
+            .join(": ");
+        return Some(if detail.is_empty() {
+            format!("pod condition {type_} is false")
+        } else {
+            format!("pod condition {type_} is false: {detail}")
+        });
+    }
+
+    status.phase.as_deref().map(|p| format!("the pod is {p}"))
+}
+
+/// Verify a label-selected pod and decode it, or reject it.
+///
+/// `startup` is supplied by the caller because settling
+/// `CreateContainerConfigError` needs a most-recent Secret read the pure layer
+/// must not perform.
+pub fn verify(pod: &Pod, identity: &AgentIdentity, startup: Startup) -> Option<VerifiedPod> {
+    if !has_marker(pod.metadata.labels.as_ref()) {
+        return None;
+    }
+    if !annotation_matches(pod.metadata.annotations.as_ref(), identity) {
+        return None;
+    }
+    Some(VerifiedPod {
+        name: pod.metadata.name.clone()?,
+        fence: Fence {
+            uid: pod.metadata.uid.clone()?,
+            resource_version: pod.metadata.resource_version.clone()?,
+        },
+        deletion_marked: pod.metadata.deletion_timestamp.is_some(),
+        startup,
+        recorded_intent: pod
+            .metadata
+            .annotations
+            .as_ref()
+            .and_then(|a| a.get(ANNOTATION_CREATE_INTENT))
+            .map(|v| Fingerprint::from_annotation(v)),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use k8s_openapi::api::core::v1::{
+        ContainerState, ContainerStateRunning, ContainerStateTerminated, ContainerStateWaiting,
+        ContainerStatus, PodStatus,
+    };
+    use k8s_openapi::apimachinery::pkg::apis::meta::v1::{ObjectMeta, Time};
+    use std::collections::BTreeMap;
+
+    fn identity() -> AgentIdentity {
+        use nostr::nips::nip19::ToBech32;
+        let keys = nostr::Keys::generate();
+        AgentIdentity::from_nsec(&keys.secret_key().to_bech32().unwrap()).unwrap()
+    }
+
+    fn base_pod(id: &AgentIdentity) -> Pod {
+        Pod {
+            metadata: ObjectMeta {
+                name: Some(id.pod_name()),
+                uid: Some("uid-1".into()),
+                resource_version: Some("100".into()),
+                labels: Some(id.labels()),
+                annotations: Some(
+                    [(
+                        ANNOTATION_PUBKEY_FULL.to_string(),
+                        id.pubkey_hex().to_string(),
+                    )]
+                    .into_iter()
+                    .collect::<BTreeMap<_, _>>(),
+                ),
+                ..Default::default()
+            },
+            ..Default::default()
+        }
+    }
+
+    fn with_container_state(mut pod: Pod, state: ContainerState) -> Pod {
+        pod.status = Some(PodStatus {
+            phase: Some("Running".into()),
+            container_statuses: Some(vec![ContainerStatus {
+                name: CONTAINER_NAME.into(),
+                state: Some(state),
+                ..Default::default()
+            }]),
+            ..Default::default()
+        });
+        pod
+    }
+
+    fn waiting(reason: &str, message: &str) -> ContainerState {
+        ContainerState {
+            waiting: Some(ContainerStateWaiting {
+                reason: Some(reason.into()),
+                message: Some(message.into()),
+            }),
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn running_container_is_started() {
+        let id = identity();
+        let pod = with_container_state(
+            base_pod(&id),
+            ContainerState {
+                running: Some(ContainerStateRunning::default()),
+                ..Default::default()
+            },
+        );
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::Resolved(Startup::Started)
+        );
+    }
+
+    /// Pod phase is not the criterion. A pod in phase `Running` whose
+    /// container never started must NOT read as started, or the reconciler
+    /// no-ops on a pod that will never serve.
+    #[test]
+    fn phase_running_with_waiting_container_is_not_started() {
+        let id = identity();
+        let pod = with_container_state(base_pod(&id), waiting("ContainerCreating", ""));
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::Resolved(Startup::NeverStartedRecoverable)
+        );
+    }
+
+    #[test]
+    fn terminated_container_is_terminated() {
+        let id = identity();
+        let pod = with_container_state(
+            base_pod(&id),
+            ContainerState {
+                terminated: Some(ContainerStateTerminated {
+                    exit_code: 0,
+                    ..Default::default()
+                }),
+                ..Default::default()
+            },
+        );
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::Resolved(Startup::Terminated)
+        );
+    }
+
+    /// A terminal phase with no container status (evicted before the kubelet
+    /// reported) is still terminated — otherwise the residue is never GC'd.
+    #[test]
+    fn terminal_phase_without_container_status_is_terminated() {
+        let id = identity();
+        for phase in ["Succeeded", "Failed"] {
+            let mut pod = base_pod(&id);
+            pod.status = Some(PodStatus {
+                phase: Some(phase.into()),
+                ..Default::default()
+            });
+            assert_eq!(
+                decode_startup(&pod),
+                StartupObservation::Resolved(Startup::Terminated),
+                "phase {phase}"
+            );
+        }
+    }
+
+    #[test]
+    fn invalid_image_name_is_provably_broken() {
+        let id = identity();
+        let pod = with_container_state(base_pod(&id), waiting("InvalidImageName", "bad ref"));
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::Resolved(Startup::NeverStartedProvablyBroken)
+        );
+    }
+
+    /// Permanent pull failures are recognized from the message; anything
+    /// unrecognized stays on the ordinary observational path rather than
+    /// being guessed at.
+    #[test]
+    fn permanent_pull_failures_are_classified() {
+        let id = identity();
+        let cases = [
+            ("401 Unauthorized", PullFailure::Unauthorized),
+            ("pull access denied", PullFailure::Unauthorized),
+            ("manifest unknown", PullFailure::ManifestUnknown),
+            (
+                "no match for platform in manifest",
+                PullFailure::ArchMismatch,
+            ),
+        ];
+        for (message, expected) in cases {
+            let pod = with_container_state(base_pod(&id), waiting("ErrImagePull", message));
+            assert_eq!(
+                decode_startup(&pod),
+                StartupObservation::Resolved(Startup::NeverStartedPullFailing(expected)),
+                "message {message:?}"
+            );
+        }
+
+        let pod = with_container_state(
+            base_pod(&id),
+            waiting("ImagePullBackOff", "dial tcp: i/o timeout"),
+        );
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::Resolved(Startup::NeverStartedRecoverable),
+            "a transient network failure must not be reported as permanent"
+        );
+    }
+
+    /// The kubelet's reason string is a hint, not proof: a config error defers
+    /// to a most-recent Secret read before anything is called broken.
+    #[test]
+    fn config_error_defers_to_a_secret_read() {
+        let id = identity();
+        let mut pod =
+            with_container_state(base_pod(&id), waiting("CreateContainerConfigError", ""));
+        pod.spec = Some(k8s_openapi::api::core::v1::PodSpec {
+            containers: vec![k8s_openapi::api::core::v1::Container {
+                name: CONTAINER_NAME.into(),
+                env_from: Some(vec![k8s_openapi::api::core::v1::EnvFromSource {
+                    secret_ref: Some(k8s_openapi::api::core::v1::SecretEnvSource {
+                        name: "buzz-agent-abc-gen1".into(),
+                        optional: Some(false),
+                    }),
+                    ..Default::default()
+                }]),
+                ..Default::default()
+            }],
+            ..Default::default()
+        });
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::ConfigErrorPendingSecretCheck {
+                secret_name: "buzz-agent-abc-gen1".into()
+            }
+        );
+    }
+
+    /// The auto-repair fence: an object that matches our schema but lacks the
+    /// marker, or carries someone else's pubkey, is never verified — so it can
+    /// never be no-op'd against, deleted, or returned as an `agent_id`.
+    #[test]
+    fn unmarked_or_mismatched_objects_fail_verification() {
+        let id = identity();
+        let other = identity();
+
+        let mut unmarked = base_pod(&id);
+        unmarked.metadata.labels = Some(BTreeMap::new());
+        assert!(
+            verify(&unmarked, &id, Startup::Started).is_none(),
+            "unmarked pod verified"
+        );
+
+        let mut wrong_version = base_pod(&id);
+        let mut labels = id.labels();
+        labels.insert(LABEL_BINDING_VERSION.to_string(), "999".to_string());
+        wrong_version.metadata.labels = Some(labels);
+        assert!(verify(&wrong_version, &id, Startup::Started).is_none());
+
+        let mut mismatched = base_pod(&id);
+        mismatched.metadata.annotations = Some(
+            [(
+                ANNOTATION_PUBKEY_FULL.to_string(),
+                other.pubkey_hex().to_string(),
+            )]
+            .into_iter()
+            .collect(),
+        );
+        assert!(
+            verify(&mismatched, &id, Startup::Started).is_none(),
+            "collision verified"
+        );
+
+        let mut missing = base_pod(&id);
+        missing.metadata.annotations = Some(BTreeMap::new());
+        assert!(verify(&missing, &id, Startup::Started).is_none());
+
+        assert!(
+            verify(&base_pod(&id), &id, Startup::Started).is_some(),
+            "own pod rejected"
+        );
+    }
+
+    /// The fence must come from the observed object, and the deletion mark
+    /// must be read even though the phase says `Running`.
+    #[test]
+    fn verified_pod_carries_the_fence_and_deletion_mark() {
+        let id = identity();
+        let mut pod = base_pod(&id);
+        pod.metadata.deletion_timestamp = Some(Time(chrono::Utc::now()));
+        let verified = verify(&pod, &id, Startup::Started).unwrap();
+        assert_eq!(verified.fence.uid, "uid-1");
+        assert_eq!(verified.fence.resource_version, "100");
+        assert!(verified.deletion_marked);
+    }
+
+    /// A pod with no recorded intent reads as `None`, which the classifier
+    /// groups with divergence.
+    #[test]
+    fn missing_intent_annotation_decodes_as_none() {
+        let id = identity();
+        assert!(verify(&base_pod(&id), &id, Startup::Started)
+            .unwrap()
+            .recorded_intent
+            .is_none());
+    }
+
+    /// A pull-failure report must name the registry and the immutable
+    /// reference and nothing else — never the kubelet's raw message, which
+    /// can echo a registry token.
+    #[test]
+    fn pull_failure_messages_are_actionable_and_redacted() {
+        let image = format!("ghcr.io/block/buzz-sprig@sha256:{}", "a".repeat(64));
+        for failure in [
+            PullFailure::Unauthorized,
+            PullFailure::ManifestUnknown,
+            PullFailure::ArchMismatch,
+        ] {
+            let msg = pull_failure_message(failure, &image);
+            assert!(msg.contains("ghcr.io"), "{msg}");
+            assert!(msg.contains(&image), "{msg}");
+            for secret in ["Bearer", "password", "nsec1", "token"] {
+                assert!(!msg.contains(secret), "leaked {secret}: {msg}");
+            }
+        }
+    }
+
+    #[test]
+    fn secret_ownership_requires_marker_and_annotation() {
+        let id = identity();
+        let other = identity();
+        let ours = Secret {
+            metadata: ObjectMeta {
+                labels: Some(id.labels()),
+                annotations: Some(
+                    [(
+                        ANNOTATION_PUBKEY_FULL.to_string(),
+                        id.pubkey_hex().to_string(),
+                    )]
+                    .into(),
+                ),
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+        assert!(secret_is_ours(&ours, &id));
+        assert!(!secret_is_ours(&ours, &other));
+
+        let mut unmarked = ours.clone();
+        unmarked.metadata.labels = Some(BTreeMap::new());
+        assert!(!secret_is_ours(&unmarked, &id));
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/pod.rs b/crates/buzz-backend-kubernetes/src/pod.rs
new file mode 100644
index 0000000000..725f98fc7d
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/pod.rs
@@ -0,0 +1,446 @@
+//! Pod and Secret construction (spec §Pod shape, §K8s Secrets).
+//!
+//! The builder is pure: it turns resolved inputs into API objects and performs
+//! no I/O, so every normative field is a unit assertion.
+
+use crate::config::{
+    ProviderConfig, RESTART_POLICY, RUN_AS_GID, RUN_AS_UID, TERMINATION_GRACE_SECONDS,
+    WORKSPACE_PATH,
+};
+use crate::intent::{Fingerprint, IntentTemplate};
+use crate::naming::{
+    AgentIdentity, ANNOTATION_CREATE_INTENT, ANNOTATION_IMAGE, ANNOTATION_PUBKEY_FULL,
+};
+use k8s_openapi::api::core::v1::{
+    Capabilities, Container, EmptyDirVolumeSource, EnvFromSource, Pod, PodSecurityContext, PodSpec,
+    ResourceRequirements, SeccompProfile, Secret, SecretEnvSource, SecurityContext, Volume,
+    VolumeMount,
+};
+use k8s_openapi::apimachinery::pkg::api::resource::Quantity;
+use k8s_openapi::apimachinery::pkg::apis::meta::v1::ObjectMeta;
+use std::collections::BTreeMap;
+
+/// Volume name for the agent's writable workspace.
+const WORKSPACE_VOLUME: &str = "workspace";
+
+/// The container name. Fixed: log and exec tooling addresses it by name.
+const CONTAINER_NAME: &str = "agent";
+
+/// Build the per-attempt Secret holding the resolved environment.
+///
+/// `immutable: true` — the Secret is written once per attempt and never
+/// updated, which is what lets the pod's `envFrom` reference be treated as an
+/// atomic binding to this exact payload (§K8s Secrets).
+pub fn build_secret(
+    identity: &AgentIdentity,
+    namespace: &str,
+    generation: &str,
+    env: BTreeMap<String, String>,
+) -> Secret {
+    Secret {
+        metadata: ObjectMeta {
+            name: Some(identity.secret_name(generation)),
+            namespace: Some(namespace.to_string()),
+            labels: Some(identity.labels()),
+            annotations: Some(
+                [(
+                    ANNOTATION_PUBKEY_FULL.to_string(),
+                    identity.pubkey_hex().to_string(),
+                )]
+                .into_iter()
+                .collect(),
+            ),
+            ..Default::default()
+        },
+        string_data: Some(env),
+        immutable: Some(true),
+        ..Default::default()
+    }
+}
+
+/// Build the pod for one create attempt.
+///
+/// The `fingerprint` is computed from [`intent_template`] over a type that
+/// cannot contain the generation or any Secret value, so it is stable across
+/// attempts of the same configuration.
+pub fn build_pod(
+    identity: &AgentIdentity,
+    cfg: &ProviderConfig,
+    generation: &str,
+    fingerprint: &Fingerprint,
+) -> Pod {
+    let annotations: BTreeMap<String, String> = [
+        (
+            ANNOTATION_PUBKEY_FULL.to_string(),
+            identity.pubkey_hex().to_string(),
+        ),
+        (
+            ANNOTATION_CREATE_INTENT.to_string(),
+            fingerprint.as_str().to_string(),
+        ),
+        (ANNOTATION_IMAGE.to_string(), cfg.image.as_str().to_string()),
+    ]
+    .into_iter()
+    .collect();
+
+    let requests: BTreeMap<String, Quantity> = [
+        (
+            "cpu".to_string(),
+            Quantity(cfg.resources.cpu_request.clone()),
+        ),
+        (
+            "memory".to_string(),
+            Quantity(cfg.resources.memory_request.clone()),
+        ),
+    ]
+    .into_iter()
+    .collect();
+    let limits: BTreeMap<String, Quantity> = [
+        ("cpu".to_string(), Quantity(cfg.resources.cpu_limit.clone())),
+        (
+            "memory".to_string(),
+            Quantity(cfg.resources.memory_limit.clone()),
+        ),
+    ]
+    .into_iter()
+    .collect();
+
+    let container = Container {
+        name: CONTAINER_NAME.to_string(),
+        image: Some(cfg.image.as_str().to_string()),
+        // No `command`/`args`: the image's entrypoint execs the harness as
+        // PID 1 (§Entrypoint). Overriding it here would be how a provider
+        // accidentally puts a shell in front of the signal receiver.
+        env_from: Some(vec![EnvFromSource {
+            secret_ref: Some(SecretEnvSource {
+                name: identity.secret_name(generation),
+                optional: Some(false),
+            }),
+            ..Default::default()
+        }]),
+        resources: Some(ResourceRequirements {
+            requests: Some(requests),
+            limits: Some(limits),
+            ..Default::default()
+        }),
+        volume_mounts: Some(vec![VolumeMount {
+            name: WORKSPACE_VOLUME.to_string(),
+            mount_path: WORKSPACE_PATH.to_string(),
+            ..Default::default()
+        }]),
+        security_context: Some(SecurityContext {
+            allow_privilege_escalation: Some(false),
+            capabilities: Some(Capabilities {
+                drop: Some(vec!["ALL".to_string()]),
+                ..Default::default()
+            }),
+            // `readOnlyRootFilesystem` is deliberately unset: the sprig
+            // toolchain writes outside the workspace mount (§Pod shape).
+            ..Default::default()
+        }),
+        ..Default::default()
+    };
+
+    Pod {
+        metadata: ObjectMeta {
+            name: Some(identity.pod_name()),
+            namespace: Some(cfg.namespace.clone()),
+            labels: Some(identity.labels()),
+            annotations: Some(annotations),
+            ..Default::default()
+        },
+        spec: Some(PodSpec {
+            containers: vec![container],
+            restart_policy: Some(RESTART_POLICY.to_string()),
+            termination_grace_period_seconds: Some(TERMINATION_GRACE_SECONDS),
+            // The agent runs prompted, untrusted code while holding an nsec;
+            // an ambient ServiceAccount token would be an API-stealable
+            // credential it never needs (§Pod shape hardening). Naming a
+            // service account selects a scheduling/RBAC identity and MUST NOT
+            // re-enable token mounting.
+            automount_service_account_token: Some(false),
+            service_account_name: cfg.service_account.clone(),
+            security_context: Some(PodSecurityContext {
+                run_as_non_root: Some(true),
+                run_as_user: Some(RUN_AS_UID),
+                run_as_group: Some(RUN_AS_GID),
+                fs_group: Some(RUN_AS_GID),
+                seccomp_profile: Some(SeccompProfile {
+                    type_: "RuntimeDefault".to_string(),
+                    ..Default::default()
+                }),
+                ..Default::default()
+            }),
+            volumes: Some(vec![Volume {
+                name: WORKSPACE_VOLUME.to_string(),
+                empty_dir: Some(EmptyDirVolumeSource::default()),
+                ..Default::default()
+            }]),
+            ..Default::default()
+        }),
+        ..Default::default()
+    }
+}
+
+/// The create-intent template for this configuration (§Deploy State Machine).
+pub fn intent_template(
+    cfg: &ProviderConfig,
+    env_keys: impl IntoIterator<Item = String>,
+) -> IntentTemplate {
+    IntentTemplate::new(
+        &cfg.namespace,
+        &cfg.image,
+        &cfg.resources,
+        cfg.service_account.as_deref(),
+        env_keys,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config;
+
+    fn identity() -> AgentIdentity {
+        use nostr::nips::nip19::ToBech32;
+        let keys = nostr::Keys::generate();
+        AgentIdentity::from_nsec(&keys.secret_key().to_bech32().unwrap()).unwrap()
+    }
+
+    fn provider_config() -> ProviderConfig {
+        config::parse(&serde_json::json!({
+            "namespace": "buzz-agents-test",
+            "image": format!("ghcr.io/block/buzz-sprig@sha256:{}", "a".repeat(64)),
+        }))
+        .unwrap()
+    }
+
+    fn pod() -> Pod {
+        let cfg = provider_config();
+        build_pod(
+            &identity(),
+            &cfg,
+            "gen00001",
+            &intent_template(&cfg, ["BUZZ_RELAY_URL".to_string()]).fingerprint(),
+        )
+    }
+
+    fn spec(pod: &Pod) -> &PodSpec {
+        pod.spec.as_ref().unwrap()
+    }
+
+    /// Every hardening default from §Pod shape, asserted individually so a
+    /// dropped one names itself.
+    #[test]
+    fn hardening_defaults_are_all_present() {
+        let pod = pod();
+        let spec = spec(&pod);
+        assert_eq!(spec.automount_service_account_token, Some(false));
+
+        let sc = spec
+            .security_context
+            .as_ref()
+            .expect("pod security context");
+        assert_eq!(sc.run_as_non_root, Some(true));
+        assert_eq!(sc.run_as_user, Some(RUN_AS_UID));
+        assert_ne!(sc.run_as_user, Some(0), "root UID");
+        assert_eq!(sc.run_as_group, Some(RUN_AS_GID));
+        assert_eq!(
+            sc.seccomp_profile.as_ref().map(|p| p.type_.as_str()),
+            Some("RuntimeDefault")
+        );
+
+        let csc = spec.containers[0]
+            .security_context
+            .as_ref()
+            .expect("container sc");
+        assert_eq!(csc.allow_privilege_escalation, Some(false));
+        assert_eq!(
+            csc.capabilities.as_ref().and_then(|c| c.drop.clone()),
+            Some(vec!["ALL".to_string()])
+        );
+        assert_ne!(csc.privileged, Some(true));
+    }
+
+    /// The forbidden host-namespace and hostPath escapes, asserted as absence.
+    #[test]
+    fn never_uses_host_namespaces_or_host_paths() {
+        let pod = pod();
+        let spec = spec(&pod);
+        assert!(spec.host_pid.is_none() || spec.host_pid == Some(false));
+        assert!(spec.host_network.is_none() || spec.host_network == Some(false));
+        assert!(spec.host_ipc.is_none() || spec.host_ipc == Some(false));
+        for volume in spec.volumes.as_ref().unwrap() {
+            assert!(
+                volume.host_path.is_none(),
+                "hostPath volume {}",
+                volume.name
+            );
+        }
+    }
+
+    /// `Never` only. `OnFailure` is gated on the harness exit-code contract
+    /// *and* a crash-loop classification row (`:1121-1139`); the config layer
+    /// refuses `inactivity_seconds: 0` so this arm is unreachable, and the
+    /// assertion keeps it that way.
+    #[test]
+    fn restart_policy_is_never() {
+        assert_eq!(spec(&pod()).restart_policy.as_deref(), Some("Never"));
+    }
+
+    /// 60s, not Kubernetes' default 30s — which would SIGKILL the harness
+    /// mid-drain and leave presence stale-online (§Pod shape).
+    #[test]
+    fn declares_the_sixty_second_grace_budget() {
+        assert_eq!(spec(&pod()).termination_grace_period_seconds, Some(60));
+    }
+
+    /// The pod must not override the image's entrypoint: the image execs the
+    /// harness as PID 1, and a `command` here is how a shell ends up in front
+    /// of the signal receiver (§Entrypoint).
+    #[test]
+    fn does_not_override_the_image_entrypoint() {
+        let pod = pod();
+        let container = &spec(&pod).containers[0];
+        assert!(container.command.is_none(), "overrode the entrypoint");
+        assert!(container.args.is_none());
+    }
+
+    #[test]
+    fn workspace_is_an_emptydir_mounted_at_home() {
+        let pod = pod();
+        let spec = spec(&pod);
+        let volume = &spec.volumes.as_ref().unwrap()[0];
+        assert!(volume.empty_dir.is_some());
+        assert!(volume.persistent_volume_claim.is_none());
+        let mount = &spec.containers[0].volume_mounts.as_ref().unwrap()[0];
+        assert_eq!(mount.name, volume.name);
+        assert_eq!(mount.mount_path, WORKSPACE_PATH);
+    }
+
+    #[test]
+    fn resources_carry_the_configured_requests_and_limits() {
+        let mut cfg = provider_config();
+        cfg.resources.cpu_limit = "4".into();
+        let pod = build_pod(&identity(), &cfg, "g", &Fingerprint::from_annotation("f"));
+        let r = spec(&pod).containers[0].resources.as_ref().unwrap();
+        assert_eq!(r.requests.as_ref().unwrap()["cpu"], Quantity("1".into()));
+        assert_eq!(
+            r.requests.as_ref().unwrap()["memory"],
+            Quantity("2Gi".into())
+        );
+        assert_eq!(r.limits.as_ref().unwrap()["cpu"], Quantity("4".into()));
+        assert_eq!(r.limits.as_ref().unwrap()["memory"], Quantity("4Gi".into()));
+    }
+
+    /// `envFrom` must point at this attempt's Secret and must NOT be optional:
+    /// an optional reference starts the container with no identity at all,
+    /// turning a missing-Secret bug into an agent that silently cannot
+    /// authenticate.
+    #[test]
+    fn env_from_references_this_attempts_secret_and_is_required() {
+        let id = identity();
+        let cfg = provider_config();
+        let pod = build_pod(&id, &cfg, "gen00042", &Fingerprint::from_annotation("f"));
+        let source = &spec(&pod).containers[0].env_from.as_ref().unwrap()[0];
+        let secret_ref = source.secret_ref.as_ref().unwrap();
+        assert_eq!(secret_ref.name, id.secret_name("gen00042"));
+        assert_eq!(secret_ref.optional, Some(false));
+        assert!(source.config_map_ref.is_none());
+    }
+
+    /// Identity, ownership marker, and the recorded intent all travel on the
+    /// pod — the GC and reconciliation fences read exactly these.
+    #[test]
+    fn pod_carries_identity_marker_and_recorded_intent() {
+        let id = identity();
+        let cfg = provider_config();
+        let fp = intent_template(&cfg, ["A".to_string()]).fingerprint();
+        let pod = build_pod(&id, &cfg, "g", &fp);
+        let meta = &pod.metadata;
+        assert_eq!(meta.name.as_deref(), Some(id.pod_name().as_str()));
+        assert_eq!(meta.namespace.as_deref(), Some("buzz-agents-test"));
+        assert_eq!(meta.labels.as_ref().unwrap(), &id.labels());
+        let ann = meta.annotations.as_ref().unwrap();
+        assert_eq!(ann[ANNOTATION_PUBKEY_FULL], id.pubkey_hex());
+        assert_eq!(ann[ANNOTATION_CREATE_INTENT], fp.as_str());
+        assert_eq!(ann[ANNOTATION_IMAGE], cfg.image.as_str());
+    }
+
+    /// The Secret is immutable and marker-bearing: immutability is what makes
+    /// the pod's `envFrom` an atomic binding, and the marker is what GC
+    /// requires before it will delete anything.
+    #[test]
+    fn secret_is_immutable_marked_and_holds_the_env() {
+        let id = identity();
+        let env: BTreeMap<String, String> =
+            [("BUZZ_RELAY_URL".to_string(), "wss://r".to_string())].into();
+        let secret = build_secret(&id, "ns", "gen1", env.clone());
+        assert_eq!(secret.immutable, Some(true));
+        assert_eq!(secret.string_data.as_ref().unwrap(), &env);
+        assert_eq!(
+            secret.metadata.name.as_deref(),
+            Some(id.secret_name("gen1").as_str())
+        );
+        assert_eq!(secret.metadata.labels.as_ref().unwrap(), &id.labels());
+        assert_eq!(
+            secret.metadata.annotations.as_ref().unwrap()[ANNOTATION_PUBKEY_FULL],
+            id.pubkey_hex()
+        );
+        // `data` must stay unset — setting both is an apiserver rejection.
+        assert!(secret.data.is_none());
+    }
+
+    /// Naming a service account selects a scheduling identity; it must not
+    /// re-enable token mounting (§Pod shape hardening, `:1221-1225`).
+    #[test]
+    fn service_account_does_not_re_enable_token_mounting() {
+        let mut cfg = provider_config();
+        cfg.service_account = Some("agent-sa".into());
+        let pod = build_pod(&identity(), &cfg, "g", &Fingerprint::from_annotation("f"));
+        assert_eq!(spec(&pod).service_account_name.as_deref(), Some("agent-sa"));
+        assert_eq!(spec(&pod).automount_service_account_token, Some(false));
+    }
+
+    /// The fingerprint recorded on the pod is the one the classifier will
+    /// recompute — pinned end-to-end so a builder change that forgets to feed
+    /// the template a field cannot pass silently.
+    #[test]
+    fn recorded_fingerprint_matches_a_fresh_computation() {
+        let cfg = provider_config();
+        let keys = ["BUZZ_RELAY_URL".to_string(), "GOOSE_MODE".to_string()];
+        let fp = intent_template(&cfg, keys.clone()).fingerprint();
+        let pod = build_pod(&identity(), &cfg, "gen-a", &fp);
+        let recorded = Fingerprint::from_annotation(
+            &pod.metadata.annotations.as_ref().unwrap()[ANNOTATION_CREATE_INTENT],
+        );
+        assert_eq!(recorded, intent_template(&cfg, keys).fingerprint());
+    }
+
+    /// Two attempts differing only in generation must record the *same*
+    /// fingerprint, or the divergence discriminator fires on every deploy and
+    /// the never-started row deletes healthy pending pods.
+    #[test]
+    fn generation_does_not_change_the_recorded_fingerprint() {
+        let cfg = provider_config();
+        let keys = ["BUZZ_RELAY_URL".to_string()];
+        let a = intent_template(&cfg, keys.clone()).fingerprint();
+        let b = intent_template(&cfg, keys).fingerprint();
+        let id = identity();
+        let pod_a = build_pod(&id, &cfg, "gen-1", &a);
+        let pod_b = build_pod(&id, &cfg, "gen-2", &b);
+        let read =
+            |p: &Pod| p.metadata.annotations.as_ref().unwrap()[ANNOTATION_CREATE_INTENT].clone();
+        assert_eq!(read(&pod_a), read(&pod_b));
+        // ...while the Secret they reference differs.
+        let secret_of = |p: &Pod| {
+            spec(p).containers[0].env_from.as_ref().unwrap()[0]
+                .secret_ref
+                .as_ref()
+                .unwrap()
+                .name
+                .clone()
+        };
+        assert_ne!(secret_of(&pod_a), secret_of(&pod_b));
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/reconcile.rs b/crates/buzz-backend-kubernetes/src/reconcile.rs
new file mode 100644
index 0000000000..df2f99789f
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/reconcile.rs
@@ -0,0 +1,1585 @@
+//! The deploy loop: executes [`crate::classify`]'s actions against a substrate
+//! and re-enters (spec §Deploy State Machine).
+//!
+//! The substrate is a trait so the conformance tests drive this exact
+//! reconciler — the shipped code path, not a test-only reimplementation — with
+//! a fake cluster and a fake clock.
+//!
+//! Two shapes are worth naming up front, because they are what keep the loop
+//! terminating:
+//!
+//! * **Success means the harness container started** (`:696-699`). There is no
+//!   "deployed but not confirmed" success: `deploy` returns an `agent_id` or an
+//!   in-band error carrying the latest condition. The wire has no third form.
+//! * **A create-conflict loser never repairs.** It verifies the winner, drops
+//!   its own Secret, and *observes* until the winner starts. Applying the
+//!   divergence row to the pod that just beat it is exactly the ping-pong the
+//!   spec forbids (`:845-850`), and the escape it names is the *next* deploy,
+//!   not this one.
+
+use crate::classify::{self, Action, Fence, Startup, VerifiedPod};
+use crate::config::ProviderConfig;
+use crate::gc;
+use crate::naming::AgentIdentity;
+use crate::observe::{self, StartupObservation};
+use chrono::{DateTime, Utc};
+use k8s_openapi::api::core::v1::{Pod, Secret};
+use std::collections::BTreeMap;
+use std::time::Duration;
+
+/// Outcome of a create against the deterministic pod name.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CreateOutcome {
+    Created,
+    /// 409 with `Status.reason: AlreadyExists` — a concurrent attempt won.
+    /// Discriminated on the typed reason, never on the HTTP code alone: 409 is
+    /// also `Conflict`, which means a failed precondition (`:780-794`).
+    AlreadyExists,
+}
+
+/// Outcome of a fenced delete.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DeleteOutcome {
+    Accepted,
+    /// Already gone. Delete-not-found is success (`:842`).
+    NotFound,
+    /// 409 with `Status.reason: Conflict` — the object changed since the
+    /// observation that authorized this delete. Neither an error nor
+    /// permission to retry: re-enter and classify what exists now
+    /// (`:775-777`).
+    PreconditionFailed,
+}
+
+/// The cluster operations the reconciler needs. Everything here is I/O;
+/// everything that decides is pure and lives in `classify`/`gc`.
+#[allow(async_fn_in_trait)]
+pub trait Substrate {
+    /// Create the namespace if absent. On RBAC denial the error MUST name the
+    /// literal `kubectl create namespace <name>` command and MUST NOT fall
+    /// back to `default` (`:1002-1005`).
+    async fn ensure_namespace(&self, namespace: &str) -> Result<(), String>;
+
+    /// Most-recent read of the pods matching this identity's selector, plus
+    /// the apiserver's clock from the same call's HTTP `Date` header. `None`
+    /// clock means the header was absent or unparseable, which makes the
+    /// orphan-Secret sweep skip (`:1321-1335`).
+    async fn list_pods(&self, selector: &str) -> Result<(Vec<Pod>, Option<DateTime<Utc>>), String>;
+
+    async fn list_secrets(&self, selector: &str) -> Result<Vec<Secret>, String>;
+
+    /// Most-recent existence check (`resourceVersion` explicitly unset, not
+    /// `"0"`): the classifier treats a confirmed absence as proof, so a
+    /// possibly-stale cache read would be proof of nothing (`:761-769`).
+    async fn secret_exists(&self, name: &str) -> Result<bool, String>;
+
+    async fn create_secret(&self, secret: &Secret) -> Result<(), String>;
+
+    async fn create_pod(&self, pod: &Pod) -> Result<CreateOutcome, String>;
+
+    /// Compare-and-delete against the fence from the authorizing observation.
+    /// Uses the object's own grace period — never `grace_period_seconds: 0`,
+    /// which is a force-kill that discards the declared 60s shutdown budget
+    /// (`:1185-1189`).
+    async fn delete_pod(&self, name: &str, fence: &Fence) -> Result<DeleteOutcome, String>;
+
+    /// Best-effort: the Secret may already be gone, which is success.
+    async fn delete_secret(&self, name: &str) -> Result<(), String>;
+
+    /// Read one pod by name, most-recent. `None` is a confirmed absence.
+    async fn get_pod(&self, name: &str) -> Result<Option<Pod>, String>;
+
+    async fn sleep(&self, duration: Duration);
+
+    /// Monotonic elapsed time since the operation began. Fake-clock driven in
+    /// tests; the deadline must not depend on wall-clock adjustments.
+    fn elapsed(&self) -> Duration;
+}
+
+/// Interval between reconciler polls. Short enough that a fast start is
+/// reported promptly, long enough not to hammer the apiserver for 600s.
+const POLL_INTERVAL: Duration = Duration::from_secs(2);
+
+/// The deploy operation deadline (spec §Deploy: `timeout: 600s`).
+const DEADLINE: Duration = Duration::from_secs(gc::OPERATION_DEADLINE_SECS as u64);
+
+/// Settle a pod's startup state, performing the one most-recent Secret read
+/// that `CreateContainerConfigError` requires.
+async fn settle(substrate: &impl Substrate, pod: &Pod) -> Result<Startup, String> {
+    Ok(match observe::decode_startup(pod) {
+        StartupObservation::Resolved(startup) => startup,
+        StartupObservation::ConfigErrorPendingSecretCheck { secret_name } => {
+            // A confirmed absence is proof; anything else stays recoverable,
+            // because the kubelet's reason string alone is not evidence.
+            if substrate.secret_exists(&secret_name).await? {
+                Startup::NeverStartedRecoverable
+            } else {
+                Startup::NeverStartedProvablyBroken
+            }
+        }
+    })
+}
+
+/// Observe the single pod owned by this identity, verified.
+///
+/// `Ok(None)` conflates "absent" with "present but not ours" on purpose *here*
+/// — both mean the classifier has nothing it may act on. The create path
+/// separates them, because only there is the difference actionable.
+async fn observe_pod(
+    substrate: &impl Substrate,
+    identity: &AgentIdentity,
+) -> Result<Option<VerifiedPod>, String> {
+    let Some(pod) = substrate.get_pod(&identity.pod_name()).await? else {
+        return Ok(None);
+    };
+    let startup = settle(substrate, &pod).await?;
+    Ok(observe::verify(&pod, identity, startup))
+}
+
+/// The latest condition to report, read fresh at the moment of reporting.
+///
+/// Reading it here rather than threading it through every loop iteration is
+/// what "the *latest* redacted condition" (`:689`) asks for, and it costs a
+/// read only on the paths that are already failing.
+async fn latest_condition(substrate: &impl Substrate, identity: &AgentIdentity) -> String {
+    match substrate.get_pod(&identity.pod_name()).await {
+        Ok(Some(pod)) => observe::condition(&pod)
+            .unwrap_or_else(|| "no condition reported by the cluster".to_string()),
+        Ok(None) => "the pod no longer exists".to_string(),
+        Err(e) => format!("the pod's condition could not be read: {e}"),
+    }
+}
+
+/// Preflight GC (§K8s GC). Failures are logged and swallowed: GC is hygiene,
+/// and a deploy must not fail because a stale object could not be listed or
+/// removed. A denial that actually blocks this deploy resurfaces at create,
+/// where the message names the operation the user was denied.
+async fn preflight_gc(substrate: &impl Substrate, identity: &AgentIdentity) {
+    if let Err(e) = try_preflight_gc(substrate, identity).await {
+        eprintln!("gc: preflight pass skipped: {e}");
+    }
+}
+
+async fn try_preflight_gc(
+    substrate: &impl Substrate,
+    identity: &AgentIdentity,
+) -> Result<(), String> {
+    let selector = identity.selector();
+    let (pods, server_now) = substrate.list_pods(&selector).await?;
+    let secrets = substrate.list_secrets(&selector).await?;
+
+    let mut terminated: Vec<String> = Vec::new();
+    for pod in &pods {
+        if matches!(settle(substrate, pod).await?, Startup::Terminated) {
+            if let Some(name) = pod.metadata.name.clone() {
+                terminated.push(name);
+            }
+        }
+    }
+
+    let plan = gc::plan(
+        identity,
+        &pods,
+        &secrets,
+        |pod| {
+            pod.metadata
+                .name
+                .as_deref()
+                .map(|n| terminated.iter().any(|t| t == n))
+                .unwrap_or(false)
+        },
+        server_now,
+    );
+
+    for name in &plan.pods {
+        // Re-read to fence the delete against the object we just observed; a
+        // pod that changed since the list is simply skipped this pass.
+        let Some(pod) = substrate.get_pod(name).await? else {
+            continue;
+        };
+        let (Some(uid), Some(rv)) = (
+            pod.metadata.uid.clone(),
+            pod.metadata.resource_version.clone(),
+        ) else {
+            continue;
+        };
+        if !matches!(settle(substrate, &pod).await?, Startup::Terminated) {
+            continue;
+        }
+        let fence = Fence {
+            uid,
+            resource_version: rv,
+        };
+        if let Err(e) = substrate.delete_pod(name, &fence).await {
+            eprintln!("gc: could not delete terminated pod {name}: {e}");
+        }
+    }
+    for name in &plan.secrets {
+        if let Err(e) = substrate.delete_secret(name).await {
+            eprintln!("gc: could not delete secret {name}: {e}");
+        }
+    }
+    Ok(())
+}
+
+/// Wait for a pod to actually disappear.
+///
+/// Mandatory before recreating: `DELETE` returns success while the object
+/// still exists, and the deterministic name stays taken for the whole grace
+/// period (`:1177-1195`).
+async fn await_disappearance(substrate: &impl Substrate, name: &str) -> Result<(), String> {
+    while substrate.elapsed() < DEADLINE {
+        if substrate.get_pod(name).await?.is_none() {
+            return Ok(());
+        }
+        substrate.sleep(POLL_INTERVAL).await;
+    }
+    Err(format!(
+        "timed out after {}s waiting for {name} to finish terminating",
+        DEADLINE.as_secs()
+    ))
+}
+
+/// Is `secret` referenced by any pod that currently exists under this
+/// identity's selector?
+///
+/// Protection deliberately spans *all* our pods, not just the winner: an
+/// `envFrom` reference from a pod still pulling its image is exactly as
+/// load-bearing as one from a running pod (`:1261-1264`).
+async fn secret_is_referenced(
+    substrate: &impl Substrate,
+    identity: &AgentIdentity,
+    secret: &str,
+) -> Result<bool, String> {
+    let (pods, _) = substrate.list_pods(&identity.selector()).await?;
+    Ok(pods
+        .iter()
+        .filter_map(observe::referenced_secret)
+        .any(|name| name == secret))
+}
+
+/// Drop this attempt's own Secret once nothing references it.
+///
+/// Only ever called with a name this process generated, and gated on the
+/// reference check: "never the winner's, never any Secret referenced by an
+/// existing pod" (`:1259-1264`). Failure is logged, not fatal — a leaked
+/// Secret is collected by the age-gated sweep.
+async fn drop_own_secret(substrate: &impl Substrate, identity: &AgentIdentity, secret: &str) {
+    match secret_is_referenced(substrate, identity, secret).await {
+        Ok(false) => {
+            if let Err(e) = substrate.delete_secret(secret).await {
+                eprintln!("could not clean up own unreferenced secret {secret}: {e}");
+            }
+        }
+        Ok(true) => {}
+        Err(e) => eprintln!("could not check whether {secret} is still referenced: {e}"),
+    }
+}
+
+/// Lost the create race: adopt the elected winner.
+///
+/// Observe-only by construction — this function has no delete edge for the
+/// pod. A winner that is terminated or provably broken is reported, not
+/// repaired; the spec's escape is "a *subsequent* deploy that walks in and
+/// observes that never-started divergent winner replaces it normally"
+/// (`:849-850`).
+async fn adopt_winner(
+    substrate: &impl Substrate,
+    identity: &AgentIdentity,
+    own_secret: &str,
+) -> Result<String, String> {
+    let name = identity.pod_name();
+
+    // Verify before adopting. A pod under our deterministic name that fails
+    // the marker/annotation check is not ours to adopt, wait for, or touch —
+    // and it will never become ours, so this is terminal rather than a retry.
+    match substrate.get_pod(&name).await? {
+        None => {}
+        Some(pod) => {
+            let startup = settle(substrate, &pod).await?;
+            if observe::verify(&pod, identity, startup).is_none() {
+                drop_own_secret(substrate, identity, own_secret).await;
+                return Err(format!(
+                    "a pod named {name} already exists in this namespace but is not \
+                     managed by this provider for this agent (it lacks the management \
+                     marker or carries a different agent identity). Remove it, or \
+                     deploy this agent to a different namespace."
+                ));
+            }
+        }
+    }
+
+    drop_own_secret(substrate, identity, own_secret).await;
+
+    // Then wait for the winner exactly as we would wait for our own pod:
+    // success still means the harness container started.
+    loop {
+        if substrate.elapsed() >= DEADLINE {
+            return Err(format!(
+                "startup not confirmed within {}s for {name} (another deploy of this \
+                 agent created it): {}",
+                DEADLINE.as_secs(),
+                latest_condition(substrate, identity).await
+            ));
+        }
+        match observe_pod(substrate, identity).await? {
+            Some(pod) if matches!(pod.startup, Startup::Started) => return Ok(pod.name),
+            Some(pod) if pod.deletion_marked => {
+                return Err(format!(
+                    "{name} was created by another deploy of this agent and is already \
+                     being deleted; try again"
+                ))
+            }
+            Some(pod)
+                if matches!(
+                    pod.startup,
+                    Startup::Terminated | Startup::NeverStartedProvablyBroken
+                ) =>
+            {
+                return Err(format!(
+                    "{name} was created by another deploy of this agent and did not \
+                     start: {}",
+                    latest_condition(substrate, identity).await
+                ))
+            }
+            // Gone again, or still coming up: keep observing under this
+            // operation's deadline.
+            _ => substrate.sleep(POLL_INTERVAL).await,
+        }
+    }
+}
+
+/// Run the deploy state machine to a terminal outcome: the started pod's name,
+/// or an in-band error carrying the latest condition.
+pub async fn deploy(
+    substrate: &impl Substrate,
+    identity: &AgentIdentity,
+    cfg: &ProviderConfig,
+    env: BTreeMap<String, String>,
+) -> Result<String, String> {
+    substrate.ensure_namespace(&cfg.namespace).await?;
+    preflight_gc(substrate, identity).await;
+
+    let desired = crate::pod::intent_template(cfg, env.keys().cloned()).fingerprint();
+
+    // Has THIS call created a pod? Set once its create lands. The replacement
+    // rows below are for residue from a previous life; once this call has made
+    // its own attempt, a replace-classification means that attempt failed —
+    // and startup verification is part of create, so the failure is reported
+    // in-band rather than retried. Without this bound a deterministic startup
+    // failure (the harness starts, rejects its configuration, exits) is
+    // delete-recreated every poll for the whole deadline, minting an immutable
+    // Secret per cycle — measured live at 107 Secrets in one 600s call, every
+    // one younger than the orphan sweep's age gate.
+    let mut created_this_call = false;
+
+    loop {
+        if substrate.elapsed() >= DEADLINE {
+            return Err(format!(
+                "startup not confirmed within {}s for {}: {}",
+                DEADLINE.as_secs(),
+                identity.pod_name(),
+                latest_condition(substrate, identity).await
+            ));
+        }
+
+        let observed = observe_pod(substrate, identity).await?;
+        match classify::classify(observed.as_ref(), &desired) {
+            // The only success edge: the harness container is running.
+            Action::NoOp { agent_id } => return Ok(agent_id),
+
+            // Self-healing states. Never delete, on this call or any later one
+            // — what replaces a never-started pod is a config change, never a
+            // deadline (`:717-729`).
+            Action::Observe { .. } => substrate.sleep(POLL_INTERVAL).await,
+
+            // A pull that will not self-heal: report now rather than spend the
+            // remaining deadline on it. Still no delete authority.
+            Action::Report { name, failure } => {
+                return Err(format!(
+                    "{name} did not start: {}",
+                    observe::pull_failure_message(failure, cfg.image.as_str())
+                ))
+            }
+
+            Action::AwaitDisappearance { name } => await_disappearance(substrate, &name).await?,
+
+            Action::Delete { name, fence } => {
+                // This call already made its own attempt, and that attempt is
+                // what the classification wants replaced: it terminated (the
+                // deterministic startup failure — the harness starts, rejects
+                // its configuration, exits) or was proven broken. Replacing it
+                // here retries the identical configuration against the same
+                // cluster: a hot delete/mint/create cycle every poll for the
+                // whole deadline, an immutable Secret per cycle — measured
+                // live at 107 Secrets in one 600s call, all younger than the
+                // orphan sweep's age gate. Report in-band instead. The residue
+                // is deliberate: the next Start's preflight GC collects the
+                // terminated pod and its referenced Secret together, so retry
+                // is gated on fresh owner intent and litter stays bounded at
+                // one pod + one Secret per press.
+                if created_this_call {
+                    return Err(format!(
+                        "{name} was created by this deploy and did not stay \
+                         running: {}. Not retrying in this call — an immediate \
+                         exit recurs until its cause is fixed. Check the \
+                         agent's configuration and press Start to try again.",
+                        latest_condition(substrate, identity).await
+                    ));
+                }
+                match substrate.delete_pod(&name, &fence).await? {
+                    // Accepted or already gone: both need the disappearance
+                    // poll before the name is free again.
+                    DeleteOutcome::Accepted | DeleteOutcome::NotFound => {
+                        await_disappearance(substrate, &name).await?
+                    }
+                    // The object changed since the observation that authorized
+                    // this delete. Discard the action and re-classify — never
+                    // retry with a fresher fence, which would delete something
+                    // we never examined. Sleep before re-entering: the losing
+                    // race is against another writer, and re-reading at full
+                    // speed is a busy-retry with no better odds than a paced
+                    // one.
+                    DeleteOutcome::PreconditionFailed => substrate.sleep(POLL_INTERVAL).await,
+                }
+            }
+
+            Action::Create => {
+                let generation = crate::naming::new_generation();
+                let secret_name = identity.secret_name(&generation);
+
+                // The generation is minted *per attempt*, and it is two things
+                // at once: the Secret's name suffix and the lifecycle
+                // correlator the harness reports. `build_env` stamped the
+                // caller's generation, so on any attempt after the first the
+                // two would name different generations — pod logs correlating
+                // to a Secret that is not the one mounted. Restamp so there is
+                // exactly one generation per attempt (§K8s Secrets).
+                let mut env = env.clone();
+                env.insert(crate::env::START_NONCE_KEY.to_string(), generation.clone());
+
+                // Secret first: the pod's spec references this exact name, so
+                // payload and Secret are atomic at the pod-spec boundary.
+                let secret = crate::pod::build_secret(identity, &cfg.namespace, &generation, env);
+                substrate.create_secret(&secret).await?;
+
+                let pod = crate::pod::build_pod(identity, cfg, &generation, &desired);
+                match substrate.create_pod(&pod).await? {
+                    // Re-enter rather than wait inline: the next iteration
+                    // observes what we just created and runs the same rows
+                    // every other state runs through. One loop, one table.
+                    //
+                    // Sleep first. A just-created pod cannot already be
+                    // started, so the immediate observation has no outcome but
+                    // "still coming up" — and if it ever came back
+                    // unverifiable, re-entering without advancing the clock
+                    // would hot-spin creates against the apiserver for the
+                    // whole deadline.
+                    CreateOutcome::Created => {
+                        created_this_call = true;
+                        substrate.sleep(POLL_INTERVAL).await
+                    }
+                    CreateOutcome::AlreadyExists => {
+                        return adopt_winner(substrate, identity, &secret_name).await
+                    }
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::Resources;
+    use crate::naming::{ANNOTATION_CREATE_INTENT, ANNOTATION_PUBKEY_FULL, LABEL_MANAGED_BY};
+    use k8s_openapi::api::core::v1::{
+        ContainerState, ContainerStateRunning, ContainerStateTerminated, ContainerStateWaiting,
+        ContainerStatus, PodStatus,
+    };
+    use k8s_openapi::apimachinery::pkg::apis::meta::v1::Time;
+    use std::cell::RefCell;
+    use std::future::Future;
+    use std::pin::pin;
+    use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};
+
+    /// Mutates the pod map after a poll, so a test can script a pod that
+    /// starts (or vanishes) partway through an observation loop.
+    type PollHook = Box<dyn Fn(&mut BTreeMap<String, Pod>)>;
+
+    /// A scripted cluster. Single-threaded on purpose: the reconciler is one
+    /// process per operation, and `RefCell` keeps the assertions readable.
+    ///
+    /// This drives the *shipped* `deploy` — the point of the `Substrate` seam.
+    /// Every fake here answers with real `k8s_openapi` objects, so the decode
+    /// and verification layers under test are the ones that run in a cluster.
+    #[derive(Default)]
+    struct Fake {
+        pods: RefCell<BTreeMap<String, Pod>>,
+        secrets: RefCell<Vec<Secret>>,
+        /// Server clock for the GC age gate; `None` models a missing `Date`.
+        server_now: Option<DateTime<Utc>>,
+        /// Elapsed time, advanced only by `sleep` — a fake clock, so a 600s
+        /// deadline test runs instantly and cannot flake on a slow machine.
+        elapsed: RefCell<Duration>,
+        /// Queued create outcomes; the default is `Created`.
+        create_outcomes: RefCell<Vec<CreateOutcome>>,
+        /// Installed when a create loses the race. A winner must be *absent*
+        /// at the observation that decides to create and *present* by the time
+        /// the create lands — pre-seeding it instead makes the loop no-op
+        /// before it ever reaches the create edge.
+        winner: RefCell<Option<Pod>>,
+        /// Every Secret ever created, retained across deletion.
+        created_secrets: RefCell<Vec<Secret>>,
+        /// Queued delete outcomes; the default is `Accepted`.
+        delete_outcomes: RefCell<Vec<DeleteOutcome>>,
+        /// Every mutating call, in order — the anti-mutation assertions read
+        /// this rather than guessing from final state.
+        calls: RefCell<Vec<String>>,
+        /// Applied to the pod map after each poll, so a test can script a pod
+        /// that starts (or vanishes) partway through an observation loop.
+        on_poll: RefCell<Vec<PollHook>>,
+        /// `ensure_namespace` fails with this, if set.
+        namespace_error: Option<String>,
+    }
+
+    impl Fake {
+        fn with_pod(self, pod: Pod) -> Self {
+            self.pods
+                .borrow_mut()
+                .insert(pod.metadata.name.clone().unwrap(), pod);
+            self
+        }
+        fn log(&self, entry: impl Into<String>) {
+            self.calls.borrow_mut().push(entry.into());
+        }
+        fn mutations(&self) -> Vec<String> {
+            self.calls.borrow().clone()
+        }
+    }
+
+    impl Substrate for Fake {
+        async fn ensure_namespace(&self, namespace: &str) -> Result<(), String> {
+            match &self.namespace_error {
+                Some(e) => Err(e.clone()),
+                None => {
+                    self.log(format!("ensure_namespace {namespace}"));
+                    Ok(())
+                }
+            }
+        }
+
+        async fn list_pods(
+            &self,
+            _selector: &str,
+        ) -> Result<(Vec<Pod>, Option<DateTime<Utc>>), String> {
+            Ok((
+                self.pods.borrow().values().cloned().collect(),
+                self.server_now,
+            ))
+        }
+
+        async fn list_secrets(&self, _selector: &str) -> Result<Vec<Secret>, String> {
+            Ok(self.secrets.borrow().clone())
+        }
+
+        async fn secret_exists(&self, name: &str) -> Result<bool, String> {
+            Ok(self
+                .secrets
+                .borrow()
+                .iter()
+                .any(|s| s.metadata.name.as_deref() == Some(name)))
+        }
+
+        async fn create_secret(&self, secret: &Secret) -> Result<(), String> {
+            let name = secret.metadata.name.clone().unwrap();
+            self.log(format!("create_secret {name}"));
+            self.secrets.borrow_mut().push(secret.clone());
+            // Kept even after the Secret is deleted: assertions about what an
+            // attempt *wrote* must not be silently vacuous once cleanup runs.
+            self.created_secrets.borrow_mut().push(secret.clone());
+            Ok(())
+        }
+
+        async fn create_pod(&self, pod: &Pod) -> Result<CreateOutcome, String> {
+            let name = pod.metadata.name.clone().unwrap();
+            self.log(format!("create_pod {name}"));
+            let outcome = if self.create_outcomes.borrow().is_empty() {
+                CreateOutcome::Created
+            } else {
+                self.create_outcomes.borrow_mut().remove(0)
+            };
+            if outcome == CreateOutcome::Created {
+                // The apiserver stamps these on admission; a builder never
+                // carries them. Without them the pod fails `verify`'s fence
+                // extraction and the loop can never see what it just created.
+                let mut pod = pod.clone();
+                pod.metadata.uid = Some(format!("uid-created-{}", self.calls.borrow().len()));
+                pod.metadata.resource_version = Some("1".into());
+                self.pods.borrow_mut().insert(name, pod);
+            } else if let Some(winner) = self.winner.borrow_mut().take() {
+                // The concurrent attempt's pod becomes visible exactly when our
+                // create is rejected — the ordering a real race produces.
+                self.pods.borrow_mut().insert(name, winner);
+            }
+            Ok(outcome)
+        }
+
+        async fn delete_pod(&self, name: &str, fence: &Fence) -> Result<DeleteOutcome, String> {
+            self.log(format!(
+                "delete_pod {name} uid={} rv={}",
+                fence.uid, fence.resource_version
+            ));
+            let outcome = if self.delete_outcomes.borrow().is_empty() {
+                DeleteOutcome::Accepted
+            } else {
+                self.delete_outcomes.borrow_mut().remove(0)
+            };
+            if outcome == DeleteOutcome::Accepted {
+                self.pods.borrow_mut().remove(name);
+            }
+            Ok(outcome)
+        }
+
+        async fn delete_secret(&self, name: &str) -> Result<(), String> {
+            self.log(format!("delete_secret {name}"));
+            self.secrets
+                .borrow_mut()
+                .retain(|s| s.metadata.name.as_deref() != Some(name));
+            Ok(())
+        }
+
+        async fn get_pod(&self, name: &str) -> Result<Option<Pod>, String> {
+            Ok(self.pods.borrow().get(name).cloned())
+        }
+
+        async fn sleep(&self, duration: Duration) {
+            *self.elapsed.borrow_mut() += duration;
+            let hooks = self.on_poll.borrow();
+            let mut pods = self.pods.borrow_mut();
+            for hook in hooks.iter() {
+                hook(&mut pods);
+            }
+        }
+
+        fn elapsed(&self) -> Duration {
+            *self.elapsed.borrow()
+        }
+    }
+
+    fn identity() -> AgentIdentity {
+        use nostr::nips::nip19::ToBech32;
+        let keys = nostr::Keys::generate();
+        AgentIdentity::from_nsec(&keys.secret_key().to_bech32().unwrap()).unwrap()
+    }
+
+    fn config() -> ProviderConfig {
+        ProviderConfig {
+            context: None,
+            namespace: "buzz-agents-test".into(),
+            image: crate::image::parse(&format!(
+                "ghcr.io/block/buzz-sprig@sha256:{}",
+                "a".repeat(64)
+            ))
+            .unwrap(),
+            resources: Resources::default(),
+            inactivity_seconds: Some(7200),
+            service_account: None,
+        }
+    }
+
+    fn env() -> BTreeMap<String, String> {
+        [("BUZZ_RELAY_URL".to_string(), "wss://r".to_string())]
+            .into_iter()
+            .collect()
+    }
+
+    /// A pod exactly as this provider would have created it — same builder the
+    /// reconciler uses, so verification is exercised rather than bypassed.
+    fn our_pod(id: &AgentIdentity, cfg: &ProviderConfig, state: Option<ContainerState>) -> Pod {
+        let fp = crate::pod::intent_template(cfg, env().keys().cloned()).fingerprint();
+        let mut pod = crate::pod::build_pod(id, cfg, "gen-existing", &fp);
+        pod.metadata.uid = Some("uid-1".into());
+        pod.metadata.resource_version = Some("100".into());
+        pod.status = Some(PodStatus {
+            phase: Some("Running".into()),
+            container_statuses: state.map(|s| {
+                vec![ContainerStatus {
+                    name: crate::observe::CONTAINER_NAME.into(),
+                    state: Some(s),
+                    ..Default::default()
+                }]
+            }),
+            ..Default::default()
+        });
+        pod
+    }
+
+    fn running() -> ContainerState {
+        ContainerState {
+            running: Some(ContainerStateRunning::default()),
+            ..Default::default()
+        }
+    }
+
+    fn terminated() -> ContainerState {
+        ContainerState {
+            terminated: Some(ContainerStateTerminated::default()),
+            ..Default::default()
+        }
+    }
+
+    fn waiting(reason: &str) -> ContainerState {
+        ContainerState {
+            waiting: Some(ContainerStateWaiting {
+                reason: Some(reason.into()),
+                message: None,
+            }),
+            ..Default::default()
+        }
+    }
+
+    fn run(fake: &Fake, id: &AgentIdentity, cfg: &ProviderConfig) -> Result<String, String> {
+        block_on(deploy(fake, id, cfg, env()))
+    }
+
+    /// Minimal executor: the fake never yields to a reactor (no timers, no
+    /// I/O — `sleep` just advances a counter), so polling to completion is
+    /// sufficient and avoids pulling a runtime into the unit job.
+    fn block_on<T>(fut: impl Future<Output = T>) -> T {
+        fn noop_waker() -> Waker {
+            fn nop(_: *const ()) {}
+            fn clone(_: *const ()) -> RawWaker {
+                RawWaker::new(std::ptr::null(), &VTABLE)
+            }
+            static VTABLE: RawWakerVTable = RawWakerVTable::new(clone, nop, nop, nop);
+            unsafe { Waker::from_raw(RawWaker::new(std::ptr::null(), &VTABLE)) }
+        }
+
+        let waker = noop_waker();
+        let mut cx = Context::from_waker(&waker);
+        let mut fut = pin!(fut);
+        match fut.as_mut().poll(&mut cx) {
+            Poll::Ready(v) => v,
+            Poll::Pending => panic!("fake substrate future parked — it has no reactor"),
+        }
+    }
+
+    // ---- the state machine's rows, end to end -------------------------------
+
+    /// First deploy: Secret before pod, and the returned id is the pod name.
+    #[test]
+    fn creates_secret_then_pod_and_returns_the_pod_name() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default();
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                if let Some(pod) = pods.get_mut(&name) {
+                    pod.status = Some(PodStatus {
+                        phase: Some("Running".into()),
+                        container_statuses: Some(vec![ContainerStatus {
+                            name: crate::observe::CONTAINER_NAME.into(),
+                            state: Some(running()),
+                            ..Default::default()
+                        }]),
+                        ..Default::default()
+                    });
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+
+        let calls = fake.mutations();
+        let secret_at = calls
+            .iter()
+            .position(|c| c.starts_with("create_secret"))
+            .unwrap();
+        let pod_at = calls
+            .iter()
+            .position(|c| c.starts_with("create_pod"))
+            .unwrap();
+        assert!(
+            secret_at < pod_at,
+            "pod created before its Secret: {calls:?}"
+        );
+    }
+
+    /// The strict no-op row: a started pod returns its id having mutated
+    /// nothing at all. Asserted on the *call log*, not on final state — a
+    /// delete-then-recreate would leave identical final state.
+    #[test]
+    fn started_pod_is_a_zero_mutation_no_op() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(running())));
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert_eq!(
+            fake.mutations(),
+            [format!("ensure_namespace {}", cfg.namespace)],
+            "the no-op row mutated something"
+        );
+    }
+
+    /// ...including when the desired intent has diverged. Edits reach a
+    /// started pod only via the next generation (`:861-865`).
+    #[test]
+    fn started_pod_no_ops_under_divergent_intent() {
+        let id = identity();
+        let cfg = config();
+        let mut pod = our_pod(&id, &cfg, Some(running()));
+        pod.metadata.annotations.as_mut().unwrap().insert(
+            ANNOTATION_CREATE_INTENT.to_string(),
+            "stale-fingerprint".into(),
+        );
+        let fake = Fake::default().with_pod(pod);
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "divergence deleted a started pod"
+        );
+    }
+
+    /// Terminated → fenced delete → disappearance → recreate. The normal
+    /// restart path, and the fence must carry the observed uid/rv.
+    #[test]
+    fn terminated_pod_is_replaced_with_a_fenced_delete() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(terminated())));
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                if let Some(pod) = pods.get_mut(&name) {
+                    if pod
+                        .status
+                        .as_ref()
+                        .and_then(|s| s.container_statuses.as_ref())
+                        .is_none()
+                    {
+                        pod.status = Some(PodStatus {
+                            phase: Some("Running".into()),
+                            container_statuses: Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(running()),
+                                ..Default::default()
+                            }]),
+                            ..Default::default()
+                        });
+                    }
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        let calls = fake.mutations();
+        assert!(
+            calls
+                .iter()
+                .any(|c| c == &format!("delete_pod {} uid=uid-1 rv=100", id.pod_name())),
+            "delete was not fenced to the observed uid+resourceVersion: {calls:?}"
+        );
+        assert!(calls.iter().any(|c| c.starts_with("create_pod")));
+    }
+
+    /// A failed precondition is neither an error nor permission to retry the
+    /// delete: re-enter and classify what exists now (`:775-777`). Here the
+    /// object has become a *started* pod, so the correct outcome is the no-op
+    /// row — never a second delete with a fresher fence.
+    #[test]
+    fn precondition_failure_reclassifies_instead_of_retrying() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(terminated())));
+        fake.delete_outcomes
+            .borrow_mut()
+            .push(DeleteOutcome::PreconditionFailed);
+        // The writer we lost the race to: between our observation and our
+        // delete, the pod under this name became a *started* one with a new
+        // resourceVersion. Installed on the poll that follows the failed
+        // precondition, so the sequence is observe → delete → lose → re-observe.
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            let started = {
+                let mut p = our_pod(&id, &cfg, Some(running()));
+                p.metadata.resource_version = Some("200".into());
+                p
+            };
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                pods.insert(name.clone(), started.clone());
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        let deletes: Vec<_> = fake
+            .mutations()
+            .into_iter()
+            .filter(|c| c.starts_with("delete_pod"))
+            .collect();
+        // Two call sites legitimately target a terminated pod: preflight GC's
+        // sweep (which is the one that loses the precondition here) and the
+        // state machine's terminated row. Both are fenced on their own
+        // observation. What must never happen is a *third* — a retry of the
+        // failed delete — so the invariant is the fence, not the count: every
+        // delete carries rv=100, the version we observed. A retry would carry
+        // the racing writer's rv=200.
+        assert_eq!(deletes.len(), 2, "unexpected delete traffic: {deletes:?}");
+        assert!(
+            deletes.iter().all(|d| d.contains("rv=100")),
+            "retried with a fresher fence: {deletes:?}"
+        );
+    }
+
+    /// The anti-livelock rule, at the loop level: a recoverable pod whose
+    /// intent matches is observed until the deadline and **never** deleted —
+    /// the case that would otherwise reset the pod age Cluster Autoscaler
+    /// keys on (`:689`).
+    #[test]
+    fn recoverable_pod_with_matching_intent_is_never_deleted() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(waiting("Unschedulable"))));
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("startup not confirmed"), "got: {err}");
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "deleted a recoverable pod: {:?}",
+            fake.mutations()
+        );
+        assert!(fake.elapsed() >= DEADLINE, "gave up before the deadline");
+    }
+
+    /// The same pod, provisioned late: the observation loop must *succeed*
+    /// when the autoscaler eventually lands the node, not merely avoid
+    /// deleting.
+    #[test]
+    fn recoverable_pod_that_starts_late_succeeds() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(waiting("Unschedulable"))));
+        let polls = RefCell::new(0);
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                *polls.borrow_mut() += 1;
+                if *polls.borrow() >= 5 {
+                    if let Some(pod) = pods.get_mut(&name) {
+                        pod.status.as_mut().unwrap().container_statuses =
+                            Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(running()),
+                                ..Default::default()
+                            }]);
+                    }
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(fake.elapsed() < DEADLINE);
+    }
+
+    /// A permanent pull failure reports immediately rather than burning the
+    /// deadline — and still never deletes.
+    #[test]
+    fn permanent_pull_failure_reports_without_deleting() {
+        let id = identity();
+        let cfg = config();
+        let mut pod = our_pod(&id, &cfg, None);
+        pod.status = Some(PodStatus {
+            phase: Some("Pending".into()),
+            container_statuses: Some(vec![ContainerStatus {
+                name: crate::observe::CONTAINER_NAME.into(),
+                state: Some(ContainerState {
+                    waiting: Some(ContainerStateWaiting {
+                        reason: Some("ImagePullBackOff".into()),
+                        message: Some("manifest unknown".into()),
+                    }),
+                    ..Default::default()
+                }),
+                ..Default::default()
+            }]),
+            ..Default::default()
+        });
+        let fake = Fake::default().with_pod(pod);
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("no image at"), "got: {err}");
+        assert!(
+            fake.elapsed() < DEADLINE,
+            "burned the deadline on a permanent failure"
+        );
+        assert!(!fake.mutations().iter().any(|c| c.starts_with("delete_pod")));
+    }
+
+    /// The kubelet's pull *message* can echo a registry request; only the
+    /// classified outcome and the image reference reach the user.
+    #[test]
+    fn pull_failure_message_is_not_echoed_verbatim() {
+        let id = identity();
+        let cfg = config();
+        let mut pod = our_pod(&id, &cfg, None);
+        pod.status = Some(PodStatus {
+            phase: Some("Pending".into()),
+            container_statuses: Some(vec![ContainerStatus {
+                name: crate::observe::CONTAINER_NAME.into(),
+                state: Some(ContainerState {
+                    waiting: Some(ContainerStateWaiting {
+                        reason: Some("ErrImagePull".into()),
+                        message: Some(
+                            "unauthorized: authentication required, token=SUPERSECRET".into(),
+                        ),
+                    }),
+                    ..Default::default()
+                }),
+                ..Default::default()
+            }]),
+            ..Default::default()
+        });
+        let fake = Fake::default().with_pod(pod);
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(
+            !err.contains("SUPERSECRET"),
+            "kubelet message echoed: {err}"
+        );
+    }
+
+    /// A pod being gracefully deleted stays in phase `Running` for its whole
+    /// grace period. The reconciler must wait it out and recreate, not return
+    /// an id that evaporates.
+    #[test]
+    fn deletion_marked_pod_is_awaited_then_recreated() {
+        let id = identity();
+        let cfg = config();
+        let mut dying = our_pod(&id, &cfg, Some(running()));
+        dying.metadata.deletion_timestamp = Some(Time(Utc::now()));
+        let fake = Fake::default().with_pod(dying);
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                match pods
+                    .get(&name)
+                    .map(|p| p.metadata.deletion_timestamp.is_some())
+                {
+                    // The grace period elapses: the object disappears.
+                    Some(true) => {
+                        pods.remove(&name);
+                    }
+                    // The replacement we create then starts.
+                    Some(false) => {
+                        let pod = pods.get_mut(&name).unwrap();
+                        pod.status = Some(PodStatus {
+                            phase: Some("Running".into()),
+                            container_statuses: Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(running()),
+                                ..Default::default()
+                            }]),
+                            ..Default::default()
+                        });
+                    }
+                    None => {}
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "deleted a pod that was already terminating"
+        );
+    }
+
+    /// `CreateContainerConfigError` is settled by a most-recent Secret read,
+    /// never by the reason string: Secret present → recoverable (observe).
+    #[test]
+    fn config_error_with_a_present_secret_is_recoverable() {
+        let id = identity();
+        let cfg = config();
+        let pod = our_pod(&id, &cfg, Some(waiting("CreateContainerConfigError")));
+        let referenced = crate::observe::referenced_secret(&pod).unwrap();
+        let fake = Fake::default().with_pod(pod);
+        fake.secrets.borrow_mut().push(crate::pod::build_secret(
+            &id,
+            &cfg.namespace,
+            "gen-existing",
+            env(),
+        ));
+        assert_eq!(referenced, id.secret_name("gen-existing"));
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("startup not confirmed"), "got: {err}");
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "deleted a pod whose Secret exists"
+        );
+    }
+
+    /// ...and Secret confirmed absent → provably broken → fenced replace.
+    #[test]
+    fn config_error_with_a_confirmed_absent_secret_is_replaced() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(
+            &id,
+            &cfg,
+            Some(waiting("CreateContainerConfigError")),
+        ));
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                if let Some(pod) = pods.get_mut(&name) {
+                    if pod
+                        .status
+                        .as_ref()
+                        .and_then(|s| s.container_statuses.as_ref())
+                        .is_none()
+                    {
+                        pod.status = Some(PodStatus {
+                            phase: Some("Running".into()),
+                            container_statuses: Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(running()),
+                                ..Default::default()
+                            }]),
+                            ..Default::default()
+                        });
+                    }
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(fake.mutations().iter().any(|c| c.starts_with("delete_pod")));
+    }
+
+    /// The generation is the Secret's name suffix *and* the lifecycle
+    /// correlator inside it. They must name the same generation, or pod logs
+    /// point at a Secret that was never mounted. The caller stamps one
+    /// generation into the env once; each create attempt mints its own, so
+    /// only a restamp keeps the pair together across a retry.
+    #[test]
+    fn each_attempt_stamps_its_own_generation_into_its_own_secret() {
+        let id = identity();
+        let cfg = config();
+        // First attempt loses the create race and is cleaned up; the operation
+        // then adopts. Two creates, two generations.
+        let fake = Fake::default();
+        *fake.winner.borrow_mut() = Some(our_pod(&id, &cfg, Some(running())));
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+
+        run(&fake, &id, &cfg).unwrap();
+
+        let created = fake.created_secrets.borrow();
+        // Guard the guard: this assertion is over a list that cleanup empties,
+        // so an empty list would make every check below vacuously true.
+        assert_eq!(created.len(), 1, "expected one create attempt");
+        for secret in created.iter() {
+            let name = secret.metadata.name.as_deref().unwrap();
+            let nonce = secret
+                .string_data
+                .as_ref()
+                .and_then(|d| d.get(crate::env::START_NONCE_KEY))
+                .expect("no lifecycle correlator in the Secret");
+            assert!(
+                name.ends_with(nonce.as_str()),
+                "secret {name} carries a correlator for a different generation ({nonce})"
+            );
+        }
+    }
+
+    // ---- bounded replacement ------------------------------------------------
+
+    /// Installs a hook that makes every pod under `name` crash-exit before the
+    /// next poll — a deterministic startup failure (the harness starts, rejects
+    /// its configuration, and exits) as observed live: the container reaches
+    /// `state.terminated` with a nonzero exit code.
+    fn crash_exits_immediately(fake: &Fake, name: String) {
+        fake.on_poll
+            .borrow_mut()
+            .push(Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                if let Some(pod) = pods.get_mut(&name) {
+                    if pod
+                        .status
+                        .as_ref()
+                        .and_then(|s| s.container_statuses.as_ref())
+                        .is_none()
+                    {
+                        pod.status = Some(PodStatus {
+                            phase: Some("Failed".into()),
+                            container_statuses: Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(ContainerState {
+                                    terminated: Some(ContainerStateTerminated {
+                                        exit_code: 1,
+                                        reason: Some("Error".into()),
+                                        ..Default::default()
+                                    }),
+                                    ..Default::default()
+                                }),
+                                ..Default::default()
+                            }]),
+                            ..Default::default()
+                        });
+                    }
+                }
+            }));
+    }
+
+    /// A pod that this call created and that crash-exits deterministically is
+    /// reported in-band after exactly ONE attempt — never hot-replaced until
+    /// the deadline. The live failure this pins: one delete/create cycle every
+    /// ~4s minted 107 immutable Secrets in a single 600s deploy call, all
+    /// younger than the orphan sweep's age gate.
+    #[test]
+    fn a_deterministic_crash_exit_is_reported_not_hot_replaced() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default();
+        crash_exits_immediately(&fake, id.pod_name());
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+
+        let creates = fake
+            .mutations()
+            .iter()
+            .filter(|c| c.starts_with("create_secret"))
+            .count();
+        assert_eq!(
+            creates, 1,
+            "hot replacement loop: {creates} Secrets minted in one deploy call"
+        );
+        assert!(
+            err.contains("exited with code 1"),
+            "error does not carry the exit: {err}"
+        );
+        // The failed attempt is left in place as evidence — no cleanup on the
+        // error path. Its Secret stays referenced by the terminated pod, so
+        // the next deploy's preflight GC collects both together.
+        assert!(
+            !fake
+                .mutations()
+                .iter()
+                .any(|c| c.starts_with("delete_pod") || c.starts_with("delete_secret")),
+            "the failed attempt was cleaned up on the error path: {:?}",
+            fake.mutations()
+        );
+        assert!(
+            fake.elapsed() < DEADLINE,
+            "burned the whole deadline on a deterministic failure"
+        );
+    }
+
+    /// The revive path is untouched: terminated residue from a *previous*
+    /// life is still replaced — the bound is on pods this call created, not
+    /// on the row.
+    #[test]
+    fn pre_existing_terminated_residue_is_still_replaced_once() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(terminated())));
+        crash_exits_immediately(&fake, id.pod_name());
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("exited with code 1"), "got: {err}");
+
+        let calls = fake.mutations();
+        let deletes = calls.iter().filter(|c| c.starts_with("delete_pod")).count();
+        let creates = calls
+            .iter()
+            .filter(|c| c.starts_with("create_secret"))
+            .count();
+        // Exactly one residue delete (the normal restart path) and one fresh
+        // attempt — then report, not another cycle.
+        assert_eq!(deletes, 1, "unexpected delete traffic: {calls:?}");
+        assert_eq!(creates, 1, "unexpected create traffic: {calls:?}");
+    }
+
+    /// Retry is gated on fresh owner intent: the *next* deploy call clears
+    /// the crashed attempt (preflight GC collects the terminated pod and its
+    /// referenced Secret together) and makes exactly one new attempt — total
+    /// litter stays one pod + one Secret however many times Start is pressed.
+    #[test]
+    fn the_next_deploy_collects_the_crashed_attempt_before_its_own_attempt() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default();
+        crash_exits_immediately(&fake, id.pod_name());
+
+        run(&fake, &id, &cfg).unwrap_err();
+        // Second Start: fresh call, fresh clock.
+        *fake.elapsed.borrow_mut() = Duration::ZERO;
+        run(&fake, &id, &cfg).unwrap_err();
+
+        assert_eq!(
+            fake.secrets.borrow().len(),
+            1,
+            "crashed attempts accumulated Secrets across calls"
+        );
+        assert_eq!(fake.pods.borrow().len(), 1, "crashed pods accumulated");
+    }
+
+    // ---- the auto-repair fence ----------------------------------------------
+
+    /// An object under our deterministic name that lacks the management
+    /// marker is not ours. The reconciler must not adopt it, delete it, or
+    /// return its name — it fails closed to the operator (`:1156-1162`).
+    #[test]
+    fn an_unmarked_look_alike_is_never_touched_or_adopted() {
+        let id = identity();
+        let cfg = config();
+        let mut look_alike = our_pod(&id, &cfg, Some(running()));
+        look_alike
+            .metadata
+            .labels
+            .as_mut()
+            .unwrap()
+            .remove(LABEL_MANAGED_BY);
+        let fake = Fake::default();
+        // Our create loses to the object already sitting on the name.
+        *fake.winner.borrow_mut() = Some(look_alike);
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("not managed by this provider"), "got: {err}");
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "deleted an object we do not own"
+        );
+    }
+
+    /// Same fence, other direction: the marker is present but the annotation
+    /// carries a different agent's pubkey. The 32-hex label is
+    /// collision-resistant, not collision-free (`:1152-1155`).
+    #[test]
+    fn a_pubkey_mismatch_is_never_adopted() {
+        let id = identity();
+        let other = identity();
+        let cfg = config();
+        let mut foreign = our_pod(&id, &cfg, Some(running()));
+        foreign.metadata.annotations.as_mut().unwrap().insert(
+            ANNOTATION_PUBKEY_FULL.to_string(),
+            other.pubkey_hex().to_string(),
+        );
+        let fake = Fake::default();
+        *fake.winner.borrow_mut() = Some(foreign);
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("different agent identity"), "got: {err}");
+        assert!(!fake.mutations().iter().any(|c| c.starts_with("delete_pod")));
+    }
+
+    // ---- create-conflict convergence ---------------------------------------
+
+    /// The loser adopts the winner, returns the winner's id, and deletes
+    /// **only its own** Secret — never the winner's (`:1259-1264`).
+    #[test]
+    fn create_loser_adopts_the_winner_and_drops_only_its_own_secret() {
+        let id = identity();
+        let cfg = config();
+        let winner = our_pod(&id, &cfg, Some(running()));
+        let winners_secret = crate::observe::referenced_secret(&winner).unwrap();
+        let fake = Fake::default();
+        *fake.winner.borrow_mut() = Some(winner);
+        fake.secrets.borrow_mut().push(crate::pod::build_secret(
+            &id,
+            &cfg.namespace,
+            "gen-existing",
+            env(),
+        ));
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+
+        let deleted: Vec<_> = fake
+            .mutations()
+            .into_iter()
+            .filter(|c| c.starts_with("delete_secret"))
+            .collect();
+        assert_eq!(
+            deleted.len(),
+            1,
+            "expected exactly our own Secret dropped: {deleted:?}"
+        );
+        assert!(
+            !deleted[0].contains(&winners_secret),
+            "deleted the winner's Secret: {deleted:?}"
+        );
+        assert!(
+            fake.secrets
+                .borrow()
+                .iter()
+                .any(|s| s.metadata.name.as_deref() == Some(winners_secret.as_str())),
+            "the winner's Secret is gone"
+        );
+    }
+
+    /// The loser must not apply the divergence row to the pod that just beat
+    /// it — that is the ping-pong the spec forbids (`:845-850`). A divergent
+    /// *started* winner is adopted as-is.
+    #[test]
+    fn create_loser_does_not_replace_a_divergent_winner() {
+        let id = identity();
+        let cfg = config();
+        let mut winner = our_pod(&id, &cfg, Some(running()));
+        winner.metadata.annotations.as_mut().unwrap().insert(
+            ANNOTATION_CREATE_INTENT.to_string(),
+            "a-different-intent".into(),
+        );
+        let fake = Fake::default();
+        *fake.winner.borrow_mut() = Some(winner);
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "the create loser deleted the winner"
+        );
+    }
+
+    /// The loser waits for the winner to *start* — adopting a not-yet-started
+    /// winner as success would report an agent that is not running.
+    #[test]
+    fn create_loser_waits_for_the_winner_to_start() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default();
+        *fake.winner.borrow_mut() = Some(our_pod(&id, &cfg, Some(waiting("ContainerCreating"))));
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+        let polls = RefCell::new(0);
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                *polls.borrow_mut() += 1;
+                if *polls.borrow() >= 3 {
+                    if let Some(pod) = pods.get_mut(&name) {
+                        pod.status.as_mut().unwrap().container_statuses =
+                            Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(running()),
+                                ..Default::default()
+                            }]);
+                    }
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(fake.elapsed() > Duration::ZERO, "did not wait at all");
+    }
+
+    // ---- deadline and namespace --------------------------------------------
+
+    /// Deadline expiry reports the *latest* condition, not a generic timeout
+    /// (`:699-701`), and triggers no cleanup (`:720-724`).
+    #[test]
+    fn deadline_expiry_reports_the_condition_and_cleans_up_nothing() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(waiting("ContainerCreating"))));
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("ContainerCreating"), "generic timeout: {err}");
+        let calls = fake.mutations();
+        assert!(
+            !calls.iter().any(|c| c.starts_with("delete_")),
+            "deadline expiry triggered cleanup: {calls:?}"
+        );
+    }
+
+    /// An RBAC denial on namespace create fails the deploy with the literal
+    /// command to run, before any Secret is written (`:1002-1005`).
+    #[test]
+    fn namespace_denial_fails_before_writing_any_secret() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake {
+            namespace_error: Some(format!(
+                "not authorized to create namespaces: run `kubectl create namespace {}`",
+                cfg.namespace
+            )),
+            ..Default::default()
+        };
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("kubectl create namespace"), "got: {err}");
+        assert!(
+            fake.mutations().is_empty(),
+            "wrote something after a namespace denial: {:?}",
+            fake.mutations()
+        );
+    }
+
+    /// GC failures are hygiene, not deploy failures: a list the user cannot
+    /// perform must not block a deploy they can.
+    #[test]
+    fn a_gc_failure_does_not_fail_the_deploy() {
+        struct GcDenied(Fake);
+        impl Substrate for GcDenied {
+            async fn ensure_namespace(&self, ns: &str) -> Result<(), String> {
+                self.0.ensure_namespace(ns).await
+            }
+            async fn list_pods(
+                &self,
+                _s: &str,
+            ) -> Result<(Vec<Pod>, Option<DateTime<Utc>>), String> {
+                Err("forbidden: cannot list pods".into())
+            }
+            async fn list_secrets(&self, _s: &str) -> Result<Vec<Secret>, String> {
+                Err("forbidden: cannot list secrets".into())
+            }
+            async fn secret_exists(&self, n: &str) -> Result<bool, String> {
+                self.0.secret_exists(n).await
+            }
+            async fn create_secret(&self, s: &Secret) -> Result<(), String> {
+                self.0.create_secret(s).await
+            }
+            async fn create_pod(&self, p: &Pod) -> Result<CreateOutcome, String> {
+                self.0.create_pod(p).await
+            }
+            async fn delete_pod(&self, n: &str, f: &Fence) -> Result<DeleteOutcome, String> {
+                self.0.delete_pod(n, f).await
+            }
+            async fn delete_secret(&self, n: &str) -> Result<(), String> {
+                self.0.delete_secret(n).await
+            }
+            async fn get_pod(&self, n: &str) -> Result<Option<Pod>, String> {
+                self.0.get_pod(n).await
+            }
+            async fn sleep(&self, d: Duration) {
+                self.0.sleep(d).await
+            }
+            fn elapsed(&self) -> Duration {
+                self.0.elapsed()
+            }
+        }
+
+        let id = identity();
+        let cfg = config();
+        let inner = Fake::default().with_pod(our_pod(&id, &cfg, Some(running())));
+        let fake = GcDenied(inner);
+
+        assert_eq!(
+            block_on(deploy(&fake, &id, &cfg, env())).unwrap(),
+            id.pod_name()
+        );
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/wire.rs b/crates/buzz-backend-kubernetes/src/wire.rs
new file mode 100644
index 0000000000..89b78b364d
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/wire.rs
@@ -0,0 +1,250 @@
+//! The stdin/stdout JSON protocol (spec §Provider Protocol).
+//!
+//! One process per operation: one JSON object in, one JSON object out.
+//! These types are this provider's view of the contract; the golden fixtures
+//! in `tests/fixtures/provider-wire/` are the arbiter shared with the desktop.
+
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+
+/// The wire-contract version this provider speaks (spec §Info).
+pub const PROTOCOL_VERSION: u32 = 1;
+
+/// Request envelope. `op` discriminates; unknown ops are an in-band error.
+///
+/// `request_id` is deliberately absent from every variant. The desktop sends
+/// it, but the exchange is one request and one response per process, so there
+/// is nothing to correlate and nothing in the response schema to echo it into
+/// (`:387`, `:416` — neither response shape carries it). Serde ignores it on
+/// the way in, so a caller that sends it is accepted; typing it would only
+/// create a field nothing reads.
+#[derive(Debug, Deserialize)]
+#[serde(tag = "op", rename_all = "lowercase")]
+pub enum Request {
+    Info,
+    Deploy(Box<DeployRequest>),
+}
+
+#[derive(Debug, Deserialize)]
+pub struct DeployRequest {
+    pub agent: AgentPayload,
+    #[serde(default)]
+    pub provider_config: serde_json::Value,
+}
+
+/// The agent payload (spec §Deploy).
+///
+/// Only the fields this binding actually consumes are typed. `name` (display
+/// name), `model`, `provider`, and `turn_timeout_seconds` are deliberately
+/// absent: object names derive from the pubkey, not the display name
+/// (`:1150-1152`), the model/provider pair arrives already resolved inside
+/// `launch`, and the timeout is ignored upstream — typing any of them would
+/// invite a provider-side remap the spec forbids.
+#[derive(Debug, Deserialize)]
+pub struct AgentPayload {
+    pub relay_url: String,
+    pub private_key_nsec: String,
+    #[serde(default)]
+    pub auth_tag: Option<String>,
+    #[serde(default)]
+    pub respond_to: Option<String>,
+    #[serde(default)]
+    pub respond_to_allowlist: Option<Vec<String>>,
+    /// User env, already merged global < persona < agent by the desktop and
+    /// already stripped of reserved keys. Superseded by `launch.env` when
+    /// `launch` is present — a provider MUST NOT re-merge it on top
+    /// (§Launch data, precedence tier 2).
+    #[serde(default)]
+    pub env_vars: BTreeMap<String, String>,
+    /// The desktop-resolved launch contract. Absent only from a desktop
+    /// predating Known Defect 3's fix.
+    #[serde(default)]
+    pub launch: Option<LaunchBlock>,
+}
+
+/// Desktop-resolved launch data (spec §Launch data).
+#[derive(Debug, Default, Deserialize)]
+pub struct LaunchBlock {
+    /// Command *name*, resolved against the image's PATH — never a host path.
+    #[serde(default)]
+    pub command: Option<String>,
+    #[serde(default)]
+    pub args: Vec<String>,
+    /// Layered env: baked → runtime metadata → definition → global → persona
+    /// → agent. Precedence tier 2.
+    #[serde(default)]
+    pub env: BTreeMap<String, String>,
+    /// Overridable behavior defaults. Precedence tier 1 — user env beats
+    /// these, matching the local spawn.
+    #[serde(default)]
+    pub policy_env: BTreeMap<String, String>,
+    /// Resolved workspace owner (hex). The respond-to gate's one
+    /// irreducible input; without it or `auth_tag` the harness cannot match
+    /// `!shutdown`.
+    #[serde(default)]
+    pub owner_pubkey: Option<String>,
+}
+
+/// Response envelope. Serialized flat — `{"ok": true, …}` — because the
+/// desktop reads `ok`, `error`, and `agent_id` off the top level.
+#[derive(Debug, Serialize)]
+#[serde(untagged)]
+pub enum Response {
+    Info(InfoResponse),
+    Deploy(DeployResponse),
+    Error(ErrorResponse),
+}
+
+#[derive(Debug, Serialize)]
+pub struct InfoResponse {
+    pub ok: bool,
+    pub name: &'static str,
+    pub version: &'static str,
+    pub protocol_version: u32,
+    pub description: &'static str,
+    pub config_schema: serde_json::Value,
+}
+
+#[derive(Debug, Serialize)]
+pub struct DeployResponse {
+    pub ok: bool,
+    pub agent_id: String,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ErrorResponse {
+    pub ok: bool,
+    pub error: String,
+}
+
+impl Response {
+    pub fn error(message: impl Into<String>) -> Self {
+        Response::Error(ErrorResponse {
+            ok: false,
+            error: message.into(),
+        })
+    }
+
+    /// The provider's self-description (spec §Info). Pure — no cluster
+    /// contact — because the desktop calls it to render the config form
+    /// before a kubeconfig is known to exist.
+    pub fn info() -> Self {
+        Response::Info(InfoResponse {
+            ok: true,
+            name: "kubernetes",
+            version: env!("CARGO_PKG_VERSION"),
+            protocol_version: PROTOCOL_VERSION,
+            description: "Runs agents as pods in a Kubernetes cluster",
+            config_schema: crate::config::config_schema(),
+        })
+    }
+
+    pub fn deployed(agent_id: impl Into<String>) -> Self {
+        Response::Deploy(DeployResponse {
+            ok: true,
+            agent_id: agent_id.into(),
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_info_request() {
+        let r: Request = serde_json::from_str(r#"{"op":"info","request_id":"abc"}"#).unwrap();
+        assert!(matches!(r, Request::Info));
+    }
+
+    /// The desktop sends `request_id` on every call, but the exchange is 1:1
+    /// per process — a provider that hard-required it would fail a
+    /// conforming-but-minimal caller for no safety gain.
+    #[test]
+    fn request_id_is_optional() {
+        let r: Request = serde_json::from_str(r#"{"op":"info"}"#).unwrap();
+        assert!(matches!(r, Request::Info));
+    }
+
+    #[test]
+    fn rejects_unknown_op() {
+        assert!(serde_json::from_str::<Request>(r#"{"op":"undeploy"}"#).is_err());
+    }
+
+    /// Payload fields this binding does not consume must not break parsing:
+    /// the desktop sends `model`, `provider`, `system_prompt` and more, and a
+    /// provider that rejected them would break on every real deploy.
+    #[test]
+    fn ignores_unconsumed_payload_fields() {
+        let json = r#"{
+            "op":"deploy","request_id":"r1",
+            "agent":{
+                "name":"a","relay_url":"wss://r","private_key_nsec":"nsec1x",
+                "model":"gpt-5","provider":"openai","system_prompt":"hi",
+                "turn_timeout_seconds":30,"parallelism":10,
+                "agent_command":"goose","agent_args":[]
+            },
+            "provider_config":{"namespace":"ns"}
+        }"#;
+        let r: Request = serde_json::from_str(json).unwrap();
+        let Request::Deploy(d) = r else {
+            panic!("wrong op")
+        };
+        assert_eq!(d.agent.relay_url, "wss://r");
+        assert!(d.agent.launch.is_none());
+    }
+
+    #[test]
+    fn parses_launch_block() {
+        let json = r#"{
+            "op":"deploy",
+            "agent":{
+                "relay_url":"wss://r","private_key_nsec":"nsec1x",
+                "launch":{
+                    "command":"goose","args":["run","--x"],
+                    "env":{"GOOSE_MODEL":"m"},
+                    "policy_env":{"GOOSE_MODE":"auto"},
+                    "owner_pubkey":"deadbeef"
+                }
+            }
+        }"#;
+        let Request::Deploy(d) = serde_json::from_str::<Request>(json).unwrap() else {
+            panic!("wrong op")
+        };
+        let l = d.agent.launch.unwrap();
+        assert_eq!(l.command.as_deref(), Some("goose"));
+        assert_eq!(l.args, ["run", "--x"]);
+        assert_eq!(l.env["GOOSE_MODEL"], "m");
+        assert_eq!(l.policy_env["GOOSE_MODE"], "auto");
+        assert_eq!(l.owner_pubkey.as_deref(), Some("deadbeef"));
+    }
+
+    /// A null `owner_pubkey`/`auth_tag` must parse (the refusal is a policy
+    /// decision made later, with a specific message), not fail as a type error.
+    #[test]
+    fn null_owner_fields_parse() {
+        let json = r#"{"op":"deploy","agent":{
+            "relay_url":"wss://r","private_key_nsec":"nsec1x","auth_tag":null,
+            "launch":{"owner_pubkey":null}
+        }}"#;
+        let Request::Deploy(d) = serde_json::from_str::<Request>(json).unwrap() else {
+            panic!("wrong op")
+        };
+        assert!(d.agent.auth_tag.is_none());
+        assert!(d.agent.launch.unwrap().owner_pubkey.is_none());
+    }
+
+    /// The desktop reads `ok`/`error`/`agent_id` off the top level, so the
+    /// enum must serialize flat with no variant tag.
+    #[test]
+    fn responses_serialize_flat() {
+        let v = serde_json::to_value(Response::deployed("buzz-agent-abc")).unwrap();
+        assert_eq!(v["ok"], true);
+        assert_eq!(v["agent_id"], "buzz-agent-abc");
+        assert!(v.get("Deploy").is_none());
+
+        let v = serde_json::to_value(Response::error("boom")).unwrap();
+        assert_eq!(v["ok"], false);
+        assert_eq!(v["error"], "boom");
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/README.md b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/README.md
new file mode 100644
index 0000000000..56a972f894
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/README.md
@@ -0,0 +1,39 @@
+# Provider wire fixtures
+
+The shared arbiter for the stdin/stdout contract between the desktop
+(`agents_deploy.rs`) and this provider (spec §Provider Protocol).
+
+Each `*.request.json` is a request the desktop can emit; each matching
+`*.response.json` is the exact response this provider produces for it. The
+provider side is asserted by `tests/wire_fixtures.rs`; the desktop side should
+assert that its emitted payloads parse as the corresponding request.
+
+Three rules keep these useful rather than decorative:
+
+* **Requests are recorded, not invented.** A fixture that no caller emits
+  tests a contract nobody has. "Recorded" means *executed and transcribed* —
+  `deploy-full-launch.request.json` is the output of the desktop's real
+  `build_launch_block` → `deploy_payload_json` path, not a shape derived by
+  reading those functions. Deriving it is how this fixture acquired four
+  impossible values at once: a `respond_to` that was a pubkey where the
+  desktop serializes a kebab-case `RespondTo` enum, allowlist and owner
+  values failing `validate_respond_to_allowlist`'s 64-hex rule
+  (`types.rs:897`), an invented `BUZZ_ACP_PARALLELISM` where the emitter
+  writes `BUZZ_ACP_AGENTS` (`runtime.rs:729`), and a `launch.env` key from
+  no layer of `resolve_effective_harness_descriptor`.
+* **The provider cannot police this file, so the desktop must.** Every field
+  above is one this provider is deliberately indifferent to — `respond_to` is
+  an opaque `Option<String>`, the allowlist an opaque `Vec<String>`,
+  `policy_env` an arbitrary map — so `the_full_desktop_payload_is_accepted`
+  passes on invented data exactly as happily as on recorded data. The
+  enforcement is the desktop's whole-object equality test, which *builds* the
+  payload and compares it to this file. A completeness guard (the case-list
+  directory scan in `wire_fixtures.rs`) stops a case from going missing; it
+  cannot tell you a case is false.
+* **Responses are byte-compared after key-sorted re-serialization**, so a
+  field rename or a type change fails here rather than in a desktop that
+  silently reads `undefined`.
+
+`deploy-*` fixtures cover only responses reachable without a cluster —
+refusals and malformed input. A successful deploy needs an apiserver and is
+covered by the conformance suite, not by a static fixture.
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-full-launch.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-full-launch.request.json
new file mode 100644
index 0000000000..28fe6ce90e
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-full-launch.request.json
@@ -0,0 +1,52 @@
+{
+  "op": "deploy",
+  "request_id": "req-6",
+  "agent": {
+    "agent_args": [],
+    "agent_command": "goose",
+    "auth_tag": "tag-1",
+    "env_vars": {
+      "USER_KEY": "user-value"
+    },
+    "idle_timeout_seconds": null,
+    "launch": {
+      "args": [
+        "acp"
+      ],
+      "command": "goose",
+      "env": {
+        "GOOSE_MODEL": "gpt-5",
+        "GOOSE_PROVIDER": "openai",
+        "USER_KEY": "user-value"
+      },
+      "owner_pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "policy_env": {
+        "BUZZ_ACP_AGENTS": "10",
+        "BUZZ_ACP_LAZY_POOL": "true",
+        "BUZZ_ACP_MODEL": "gpt-5",
+        "BUZZ_ACP_RELAY_OBSERVER": "true",
+        "BUZZ_ACP_SESSION_TITLE": "worker",
+        "GOOSE_MODE": "auto"
+      }
+    },
+    "max_turn_duration_seconds": null,
+    "model": "gpt-5",
+    "name": "worker",
+    "parallelism": 10,
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+    "provider": "openai",
+    "relay_url": "wss://relay.example",
+    "respond_to": "allowlist",
+    "respond_to_allowlist": [
+      "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+    ],
+    "system_prompt": null,
+    "turn_timeout_seconds": 300
+  },
+  "provider_config": {
+    "namespace": "buzz-agents-test",
+    "image": "ghcr.io/block/buzz-sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "inactivity_seconds": 3600
+  }
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.request.json
new file mode 100644
index 0000000000..4f56082bbb
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.request.json
@@ -0,0 +1,9 @@
+{
+  "op": "deploy",
+  "request_id": "req-5",
+  "agent": {
+    "relay_url": "wss://relay.example",
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5"
+  },
+  "provider_config": {"namespace": "buzz-agents-test", "image": "ghcr.io/block/buzz-sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.response.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.response.json
new file mode 100644
index 0000000000..c6011b899a
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.response.json
@@ -0,0 +1 @@
+{"ok":false,"error":"deploy refused: neither auth_tag nor launch.owner_pubkey resolved — without an owner the agent cannot honor !shutdown"}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.request.json
new file mode 100644
index 0000000000..2160909b8f
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.request.json
@@ -0,0 +1,11 @@
+{
+  "op": "deploy",
+  "request_id": "req-3",
+  "agent": {
+    "relay_url": "wss://relay.example",
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+    "auth_tag": "tag-1",
+    "provider": "  relay-mesh  "
+  },
+  "provider_config": {"namespace": "buzz-agents-test", "image": "ghcr.io/block/buzz-sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.response.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.response.json
new file mode 100644
index 0000000000..0f0c995fd8
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.response.json
@@ -0,0 +1 @@
+{"ok":false,"error":"deploy refused: this agent is configured for shared compute (relay-mesh), which runs on the relay rather than in a pod. Switch the agent to a local runtime before deploying it to Kubernetes."}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.request.json
new file mode 100644
index 0000000000..71ce9f067e
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.request.json
@@ -0,0 +1,12 @@
+{
+  "op": "deploy",
+  "request_id": "req-2",
+  "agent": {
+    "name": "mesh-agent",
+    "relay_url": "wss://relay.example",
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+    "auth_tag": "tag-1",
+    "provider": "relay-mesh"
+  },
+  "provider_config": {"namespace": "buzz-agents-test", "image": "ghcr.io/block/buzz-sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.response.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.response.json
new file mode 100644
index 0000000000..0f0c995fd8
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.response.json
@@ -0,0 +1 @@
+{"ok":false,"error":"deploy refused: this agent is configured for shared compute (relay-mesh), which runs on the relay rather than in a pod. Switch the agent to a local runtime before deploying it to Kubernetes."}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.request.json
new file mode 100644
index 0000000000..232d9dcf43
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.request.json
@@ -0,0 +1,10 @@
+{
+  "op": "deploy",
+  "request_id": "req-4",
+  "agent": {
+    "relay_url": "wss://relay.example",
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+    "auth_tag": "tag-1"
+  },
+  "provider_config": {"namespace": "buzz-agents-test", "image": "ghcr.io/block/buzz-sprig:latest"}
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.response.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.response.json
new file mode 100644
index 0000000000..e67fa6a47f
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.response.json
@@ -0,0 +1 @@
+{"ok":false,"error":"provider_config.image \"ghcr.io/block/buzz-sprig:latest\" is not digest-pinned: a tag is a mutable pointer, and this object runs with the agent's private key. Use name@sha256:<64 hex chars>"}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/info.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/info.request.json
new file mode 100644
index 0000000000..db99c86c00
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/info.request.json
@@ -0,0 +1 @@
+{"op":"info","request_id":"req-1"}
diff --git a/crates/buzz-backend-kubernetes/tests/wire_fixtures.rs b/crates/buzz-backend-kubernetes/tests/wire_fixtures.rs
new file mode 100644
index 0000000000..b3049a98ef
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/wire_fixtures.rs
@@ -0,0 +1,222 @@
+//! Golden wire fixtures (spec §Provider Protocol).
+//!
+//! These drive the **built binary** over a real pipe rather than calling an
+//! in-process function: the contract the desktop depends on is
+//! `stdin → one JSON object on stdout → exit code`, and an in-process test
+//! would assert the shape of a value while skipping the three things that
+//! actually break — the process writing nothing, writing two objects, or
+//! signalling the outcome through the exit code.
+
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::process::{Command, Stdio};
+
+fn fixtures() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/provider-wire")
+}
+
+/// Feed one request to the binary; return `(stdout, exit code)`.
+fn run(request: &str) -> (String, i32) {
+    let mut child = Command::new(env!("CARGO_BIN_EXE_buzz-backend-kubernetes"))
+        // A kubeconfig that does not exist, so a fixture that accidentally
+        // reaches the cluster fails loudly here instead of depending on
+        // whatever cluster the developer is pointed at.
+        .env("KUBECONFIG", "/nonexistent/kubeconfig-for-fixture-tests")
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .spawn()
+        .expect("could not run the provider binary");
+    child
+        .stdin
+        .take()
+        .expect("no stdin")
+        .write_all(request.as_bytes())
+        .expect("could not write the request");
+    let out = child.wait_with_output().expect("provider did not exit");
+    (
+        String::from_utf8(out.stdout).expect("stdout was not UTF-8"),
+        out.status.code().unwrap_or(-1),
+    )
+}
+
+fn read(name: &str) -> String {
+    std::fs::read_to_string(fixtures().join(name))
+        .unwrap_or_else(|e| panic!("could not read fixture {name}: {e}"))
+}
+
+/// Every response fixture, byte-compared after key-sorted re-serialization so
+/// a field rename fails here rather than in a desktop reading `undefined`.
+#[test]
+fn responses_match_their_fixtures() {
+    let cases = [
+        "deploy-relay-mesh",
+        "deploy-relay-mesh-padded",
+        "deploy-tag-image",
+        "deploy-no-owner",
+    ];
+    // The list must cover every response fixture on disk. A literal array is
+    // never empty, so `!is_empty()` would assert nothing; what can actually go
+    // wrong is a fixture added to the directory and never added here, which
+    // reads as a passing suite that exercises one case fewer than it appears to.
+    let mut on_disk: Vec<String> = std::fs::read_dir(fixtures())
+        .expect("could not read the fixture directory")
+        .filter_map(|entry| entry.ok()?.file_name().into_string().ok())
+        .filter_map(|name| Some(name.strip_suffix(".response.json")?.to_string()))
+        .collect();
+    on_disk.sort();
+    let mut listed: Vec<String> = cases.iter().map(|c| c.to_string()).collect();
+    listed.sort();
+    assert_eq!(on_disk, listed, "response fixtures and cases disagree");
+
+    for case in cases {
+        let (stdout, code) = run(&read(&format!("{case}.request.json")));
+        assert_eq!(code, 0, "{case}: a produced response must exit 0");
+
+        // Exactly one object, terminated by exactly one newline. Two responses
+        // would leave the desktop's reader holding a second one forever.
+        assert_eq!(
+            stdout.matches('\n').count(),
+            1,
+            "{case}: expected exactly one line, got {stdout:?}"
+        );
+
+        let actual: serde_json::Value =
+            serde_json::from_str(&stdout).unwrap_or_else(|e| panic!("{case}: {e}: {stdout:?}"));
+        let expected: serde_json::Value =
+            serde_json::from_str(&read(&format!("{case}.response.json"))).unwrap();
+        assert_eq!(
+            actual, expected,
+            "{case}: response drifted from its fixture"
+        );
+    }
+}
+
+/// `info` is checked on the fields the desktop reads rather than byte-for-byte:
+/// the namespace default is randomly generated per call (§K8s Namespace), so a
+/// golden copy of it would be a test that fails every run.
+#[test]
+fn info_response_carries_the_contract_fields() {
+    let (stdout, code) = run(&read("info.request.json"));
+    assert_eq!(code, 0);
+    let info: serde_json::Value = serde_json::from_str(&stdout).unwrap();
+    assert_eq!(info["ok"], true);
+    assert_eq!(info["protocol_version"], 1);
+    assert_eq!(info["name"], "kubernetes");
+    let schema = &info["config_schema"];
+    assert_eq!(
+        schema["required"],
+        serde_json::json!(["namespace", "image"])
+    );
+    let default = schema["properties"]["namespace"]["default"]
+        .as_str()
+        .expect("no generated namespace default");
+    assert!(
+        default.starts_with("buzz-agents-"),
+        "unexpected namespace default: {default}"
+    );
+    let image_default = schema["properties"]["image"]["default"]
+        .as_str()
+        .expect("no image default");
+    assert!(
+        image_default.starts_with("ghcr.io/block/buzz-sprig:")
+            && image_default.contains("@sha256:"),
+        "unexpected image default: {image_default}"
+    );
+}
+
+/// The desktop's richest payload must parse. No response fixture: this one
+/// reaches the cluster, so its outcome depends on a kubeconfig. What it
+/// guards is that every field the desktop sends is *accepted* — a payload the
+/// provider rejects at parse time is a deploy that never starts.
+#[test]
+fn the_full_desktop_payload_is_accepted() {
+    let (stdout, code) = run(&read("deploy-full-launch.request.json"));
+    assert_eq!(code, 0);
+    let response: serde_json::Value = serde_json::from_str(&stdout).unwrap();
+    let error = response["error"].as_str().unwrap_or_default();
+    // It fails — there is no cluster — but it must fail at the *connection*,
+    // having accepted every field above it.
+    assert!(
+        error.contains("kubeconfig"),
+        "the full payload was rejected before reaching the cluster: {error}"
+    );
+}
+
+/// Sami's pre-registered respond-to matrix, driven through the built binary.
+///
+/// `build_env` runs at `main.rs:124`, `client::connect` at `:132`, so under a
+/// kubeconfig that cannot exist the error string *is* the ordering assertion:
+/// "kubeconfig" means the gate passed and we reached the cluster, anything
+/// else means we refused before writing a Secret. A test asserting only
+/// `ok: false` would pass on the connection error and prove nothing.
+///
+/// The cases are applied to the real full-launch request so each one differs
+/// from a known-good deploy in exactly the field under test.
+#[test]
+fn the_respond_to_gate_matches_the_harness_acceptance_surface() {
+    let key_a = "a".repeat(64);
+    let padded_upper = format!("  {}  ", "A".repeat(64));
+    // (name, respond_to, allowlist, must reach the cluster)
+    let cases: Vec<(&str, &str, Option<Vec<String>>, bool)> = vec![
+        ("allowlist + []", "allowlist", Some(vec![]), false),
+        ("allowlist + absent", "allowlist", None, false),
+        (
+            "allowlist + junk",
+            "allowlist",
+            Some(vec!["beefcafe".into()]),
+            false,
+        ),
+        ("unparseable mode", "npub1abc", None, false),
+        ("padded mode", " allowlist ", None, false),
+        (
+            "allowlist + two valid",
+            "allowlist",
+            Some(vec![key_a.clone(), "b".repeat(64)]),
+            true,
+        ),
+        (
+            "owner-only + junk list",
+            "owner-only",
+            Some(vec!["beefcafe".into()]),
+            true,
+        ),
+        (
+            "allowlist + padded upper",
+            "allowlist",
+            Some(vec![padded_upper]),
+            true,
+        ),
+        ("nobody", "nobody", None, true),
+        ("anyone", "anyone", None, true),
+    ];
+
+    let base: serde_json::Value =
+        serde_json::from_str(&read("deploy-full-launch.request.json")).unwrap();
+
+    for (name, mode, allowlist, reaches_cluster) in cases {
+        let mut request = base.clone();
+        let agent = &mut request["agent"];
+        agent["respond_to"] = serde_json::json!(mode);
+        agent["respond_to_allowlist"] = match &allowlist {
+            Some(list) => serde_json::json!(list),
+            None => serde_json::Value::Null,
+        };
+
+        let (stdout, code) = run(&request.to_string());
+        assert_eq!(code, 0, "{name}: provider did not exit cleanly");
+        let response: serde_json::Value = serde_json::from_str(&stdout).unwrap();
+        let error = response["error"].as_str().unwrap_or_default();
+        let reached = error.contains("kubeconfig");
+
+        assert_eq!(
+            reached, reaches_cluster,
+            "{name}: expected reaches_cluster={reaches_cluster}, got error: {error}"
+        );
+        if !reaches_cluster {
+            assert!(
+                error.contains("deploy refused"),
+                "{name}: refused, but not by the gate: {error}"
+            );
+        }
+    }
+}
diff --git a/crates/buzz-cli/README.md b/crates/buzz-cli/README.md
index 40699459fc..a2dcdce6d2 100644
--- a/crates/buzz-cli/README.md
+++ b/crates/buzz-cli/README.md
@@ -56,6 +56,7 @@ buzz reactions get --event <event-id>
 buzz users get                          # your own profile
 buzz users get --pubkey <hex>           # single user
 buzz users get --pubkey <hex> --pubkey <hex>  # batch (max 200)
+buzz users get --name Honey --owner me  # exact-name lookup in your managed agents
 buzz users set-presence --status online
 buzz users set-status --text "heads down on the CLI" --emoji "🚀"
 buzz users set-status --clear                 # remove your status
diff --git a/crates/buzz-cli/src/commands/messages.rs b/crates/buzz-cli/src/commands/messages.rs
index 290cc59fa8..40a9ae80b5 100644
--- a/crates/buzz-cli/src/commands/messages.rs
+++ b/crates/buzz-cli/src/commands/messages.rs
@@ -9,8 +9,7 @@ use crate::validate::{
     validate_content_size, validate_hex64, validate_uuid, MAX_DIFF_BYTES,
 };
 use buzz_sdk::mentions::{
-    extract_at_mentions_with_known, extract_nostr_uris, merge_mentions, strip_code_regions,
-    MENTION_CAP,
+    extract_at_mentions_with_known, extract_nostr_uris, strip_code_regions, MENTION_CAP,
 };
 
 /// Extract the thread root event ID from a Nostr tag array.
@@ -119,47 +118,82 @@ async fn resolve_channel_id(client: &BuzzClient, event_id: &str) -> Result<Uuid,
     )))
 }
 
-/// Resolve `@name` mentions in `content` against this channel's members.
+fn resolve_names_to_pubkeys(
+    names: &[String],
+    name_to_pubkeys: &std::collections::HashMap<String, Vec<String>>,
+    has_explicit_mentions: bool,
+) -> Result<Vec<String>, CliError> {
+    let mut resolved = Vec::new();
+    for name in names {
+        match name_to_pubkeys
+            .get(name)
+            .map(Vec::as_slice)
+            .unwrap_or_default()
+        {
+            [pubkey] => resolved.push(pubkey.clone()),
+            [] if has_explicit_mentions => {}
+            [] => {
+                return Err(CliError::Usage(format!(
+                    "mention '@{name}' does not match a current channel member; retry with --mention <pubkey>"
+                )))
+            }
+            _ if has_explicit_mentions => {}
+            candidates => {
+                return Err(CliError::Usage(format!(
+                    "mention '@{name}' is ambiguous; candidates: {}. Retry with --mention <pubkey>",
+                    candidates.join(", ")
+                )))
+            }
+        }
+    }
+    Ok(resolved)
+}
+
+/// Resolve mention text against the channel membership snapshot.
 ///
-/// Queries kind 39002 (channel members) then kind 0 (profiles), parses
-/// display names once, and feeds them to [`extract_at_mentions_with_known`]
-/// for multi-word matching. On any I/O or parse failure, returns an empty
-/// vec — auto-tagging is best-effort and must never block a send.
+/// Returns both the current member set and uniquely name-resolved pubkeys.
+/// Lookup failures are fatal when mention processing is requested: publishing
+/// visible mention text without its intended `p` tag is worse than not sending.
 async fn resolve_content_mentions(
     client: &BuzzClient,
     channel_id: &str,
     content: &str,
-) -> Vec<String> {
-    if !content.contains('@') {
-        return vec![];
+    has_explicit_mentions: bool,
+) -> Result<(Vec<String>, Vec<String>), CliError> {
+    let stripped = strip_code_regions(content);
+    if !stripped.contains('@') && !has_explicit_mentions {
+        return Ok((vec![], vec![]));
     }
 
-    // 1. Membership list (kind 39002 is parameterized-replaceable, addressed by `d` tag).
     let members_filter = serde_json::json!({
         "kinds": [39002],
         "#d": [channel_id],
         "limit": 1,
     });
-    let member_pubkeys = match fetch_member_pubkeys(client, &members_filter).await {
-        Some(pks) if !pks.is_empty() => pks,
-        _ => return vec![],
-    };
+    let member_pubkeys = fetch_member_pubkeys(client, &members_filter)
+        .await
+        .ok_or_else(|| {
+            CliError::Other("could not load channel membership for mention preflight".into())
+        })?;
+
+    if !stripped.contains('@') {
+        return Ok((member_pubkeys, vec![]));
+    }
 
-    // 2. Profiles for those members (kind 0).
     let profiles_filter = serde_json::json!({
         "kinds": [0],
         "authors": member_pubkeys,
         "limit": member_pubkeys.len(),
     });
-    let profile_events = match fetch_events(client, &profiles_filter).await {
-        Some(v) => v,
-        None => return vec![],
-    };
+    let profile_events = fetch_events(client, &profiles_filter)
+        .await
+        .ok_or_else(|| {
+            CliError::Other("could not load member profiles for mention resolution".into())
+        })?;
 
-    // 3. Single parse: extract (pubkey, display_name) pairs from profile JSON.
     let mut name_to_pubkeys: std::collections::HashMap<String, Vec<String>> =
         std::collections::HashMap::new();
-    let mut display_names: Vec<String> = Vec::new();
+    let mut display_names = Vec::new();
     for e in &profile_events {
         let Some(pubkey) = e.get("pubkey").and_then(|v| v.as_str()) else {
             continue;
@@ -178,26 +212,82 @@ async fn resolve_content_mentions(
         else {
             continue;
         };
-        let lower = name.to_ascii_lowercase();
         name_to_pubkeys
-            .entry(lower)
+            .entry(name.to_ascii_lowercase())
             .or_default()
             .push(pubkey.to_string());
         display_names.push(name.to_string());
     }
 
-    // 4. Two-pass extraction: known multi-word names first, single-word fallback.
-    let known_refs: Vec<&str> = display_names.iter().map(|s| s.as_str()).collect();
-    let names = extract_at_mentions_with_known(content, &known_refs);
+    let known_refs: Vec<&str> = display_names.iter().map(String::as_str).collect();
+    let names = extract_at_mentions_with_known(&stripped, &known_refs);
+    let resolved = resolve_names_to_pubkeys(&names, &name_to_pubkeys, has_explicit_mentions)?;
+    Ok((member_pubkeys, resolved))
+}
+
+fn normalize_explicit_mentions(values: &[String]) -> Result<Vec<String>, CliError> {
+    let mut normalized = Vec::new();
+    for value in values {
+        let pubkey = PublicKey::parse(value.trim())
+            .map_err(|_| CliError::Usage(format!("invalid --mention pubkey: {value}")))?;
+        let hex = pubkey.to_hex();
+        if !normalized.contains(&hex) {
+            normalized.push(hex);
+        }
+    }
+    if normalized.len() > MENTION_CAP {
+        return Err(CliError::Usage(format!(
+            "too many --mention values (max {MENTION_CAP})"
+        )));
+    }
+    Ok(normalized)
+}
+
+fn merge_message_mentions(
+    explicit: &[String],
+    uri_pubkeys: &[String],
+    auto_resolved: &[String],
+) -> Result<Vec<String>, CliError> {
+    let mut mentions = Vec::new();
+    for pubkey in explicit
+        .iter()
+        .chain(uri_pubkeys.iter())
+        .chain(auto_resolved.iter())
+    {
+        if !mentions.contains(pubkey) {
+            mentions.push(pubkey.clone());
+        }
+    }
+    if mentions.len() > MENTION_CAP {
+        return Err(CliError::Usage(format!(
+            "too many unique message mentions (max {MENTION_CAP})"
+        )));
+    }
+    Ok(mentions)
+}
 
-    // 5. Look up matched names → pubkeys via the map we already built.
-    names
+fn missing_members(mentions: &[String], members: &[String]) -> Vec<String> {
+    let members: std::collections::HashSet<&str> = members.iter().map(String::as_str).collect();
+    mentions
         .iter()
-        .flat_map(|n| name_to_pubkeys.get(n).into_iter().flatten())
+        .filter(|pk| !members.contains(pk.as_str()))
         .cloned()
         .collect()
 }
 
+fn event_mention_pubkeys(event: &nostr::Event) -> Vec<String> {
+    event
+        .tags
+        .iter()
+        .filter_map(|tag| {
+            let parts = tag.as_slice();
+            (parts.first().map(String::as_str) == Some("p"))
+                .then(|| parts.get(1).cloned())
+                .flatten()
+        })
+        .collect()
+}
+
 /// Fetch raw events for `filter` via the relay's `/query` endpoint.
 /// Returns `None` on any I/O or parse failure.
 async fn fetch_events(
@@ -478,6 +568,7 @@ pub struct SendMessageParams {
     pub reply_to: Option<String>,
     pub broadcast: bool,
     pub files: Vec<String>,
+    pub mentions: Vec<String>,
 }
 
 pub async fn cmd_send_message(
@@ -495,6 +586,30 @@ pub async fn cmd_send_message(
     }
     let channel_uuid = parse_uuid(&p.channel_id)?;
 
+    let explicit_mentions = normalize_explicit_mentions(&p.mentions)?;
+    let stripped = strip_code_regions(&p.content);
+    let uri_pubkeys = extract_nostr_uris(&stripped);
+    // Supplying any identity explicitly authorizes unresolved or ambiguous @Name text
+    // as presentation-only, matching Desktop's separate visible-label and p-tag model.
+    // Uniquely resolvable member names still add their own p-tags; callers must supply
+    // every intended identity whose visible label cannot be resolved uniquely.
+    let has_explicit_mentions = !explicit_mentions.is_empty() || !uri_pubkeys.is_empty();
+    let (member_pubkeys, auto_resolved) =
+        resolve_content_mentions(client, &p.channel_id, &p.content, has_explicit_mentions).await?;
+    let mention_pubkeys = merge_message_mentions(&explicit_mentions, &uri_pubkeys, &auto_resolved)?;
+
+    let missing = missing_members(&mention_pubkeys, &member_pubkeys);
+    if !missing.is_empty() {
+        return Err(CliError::Usage(
+            serde_json::json!({
+                "message": "mentioned pubkeys are not channel members; add them explicitly before retrying",
+                "missing_member_pubkeys": missing,
+                "add_member_command": format!("buzz channels add-member --channel {} --pubkey <pubkey> --role <member|bot>", p.channel_id),
+            })
+            .to_string(),
+        ));
+    }
+
     // Upload files and build imeta tags
     let mut media_tags: Vec<Vec<String>> = Vec::new();
     let mut media_content = String::new();
@@ -526,16 +641,7 @@ pub async fn cmd_send_message(
         None
     };
 
-    // Resolve @name mentions in the author-written body only — not the media markdown we
-    // append above, which is derived from upload metadata and can't carry `@names`.
-    let mut auto_resolved = resolve_content_mentions(client, &p.channel_id, &p.content).await;
-
-    // NIP-27: also extract nostr:npub1… inline references (skipping code regions)
-    let stripped = strip_code_regions(&p.content);
-    let uri_pubkeys = extract_nostr_uris(&stripped);
-    merge_mentions(&mut auto_resolved, &uri_pubkeys, MENTION_CAP);
-
-    let mention_refs: Vec<&str> = auto_resolved.iter().map(|s| s.as_str()).collect();
+    let mention_refs: Vec<&str> = mention_pubkeys.iter().map(String::as_str).collect();
 
     let builder = match p.kind {
         Some(45001) => {
@@ -572,9 +678,17 @@ pub async fn cmd_send_message(
     };
 
     let event = client.sign_event(builder)?;
-
+    let emitted_mentions = event_mention_pubkeys(&event);
     let resp = client.submit_event(event).await?;
-    println!("{}", normalize_write_response(&resp));
+    let mut output: serde_json::Value = serde_json::from_str(&normalize_write_response(&resp))
+        .unwrap_or_else(|_| serde_json::json!({ "response": resp }));
+    if let Some(object) = output.as_object_mut() {
+        object.insert(
+            "mention_pubkeys".into(),
+            serde_json::json!(emitted_mentions),
+        );
+    }
+    println!("{output}");
     Ok(())
 }
 
@@ -765,6 +879,7 @@ pub async fn dispatch(
             reply_to,
             broadcast,
             files,
+            mentions,
         } => {
             cmd_send_message(
                 client,
@@ -775,6 +890,7 @@ pub async fn dispatch(
                     reply_to,
                     broadcast,
                     files,
+                    mentions,
                 },
             )
             .await
@@ -876,7 +992,11 @@ pub async fn dispatch(
 
 #[cfg(test)]
 mod tests {
-    use super::{find_root_from_tags, match_profiles_by_name, parse_member_pubkeys};
+    use super::{
+        event_mention_pubkeys, find_root_from_tags, match_profiles_by_name, merge_message_mentions,
+        missing_members, normalize_explicit_mentions, parse_member_pubkeys,
+        resolve_names_to_pubkeys,
+    };
     use buzz_sdk::mentions::{
         extract_at_mentions_with_known, extract_at_names, match_names_to_profiles, MentionProfile,
     };
@@ -1103,6 +1223,94 @@ mod tests {
         assert_eq!(parse_member_pubkeys(&event), vec![PK_VALID_A, PK_VALID_A]);
     }
 
+    #[test]
+    fn explicit_mentions_accept_hex_and_npub_and_deduplicate() {
+        use nostr::ToBech32;
+        let npub = nostr::PublicKey::from_hex(PK_VALID_A)
+            .unwrap()
+            .to_bech32()
+            .unwrap();
+        assert_eq!(
+            normalize_explicit_mentions(&[PK_VALID_A.into(), npub]).unwrap(),
+            vec![PK_VALID_A]
+        );
+        assert!(normalize_explicit_mentions(&["not-a-key".into()]).is_err());
+    }
+
+    #[test]
+    fn explicit_mentions_authorize_presentation_text_without_name_resolution() {
+        let names = vec!["renamed user".into()];
+        let profiles = std::collections::HashMap::new();
+        assert_eq!(
+            resolve_names_to_pubkeys(&names, &profiles, true).unwrap(),
+            Vec::<String>::new()
+        );
+        assert!(resolve_names_to_pubkeys(&names, &profiles, false).is_err());
+    }
+
+    #[test]
+    fn explicit_mentions_authorize_ambiguous_presentation_text() {
+        let names = vec!["alice".into()];
+        let profiles = std::collections::HashMap::from([(
+            "alice".into(),
+            vec![PK_VALID_A.into(), PK_VALID_B.into()],
+        )]);
+        assert_eq!(
+            resolve_names_to_pubkeys(&names, &profiles, true).unwrap(),
+            Vec::<String>::new()
+        );
+        let error = resolve_names_to_pubkeys(&names, &profiles, false).unwrap_err();
+        assert!(error.to_string().contains(PK_VALID_A));
+        assert!(error.to_string().contains(PK_VALID_B));
+    }
+
+    #[test]
+    fn explicit_mentions_make_all_at_names_presentation_only() {
+        let names = vec!["alice".into(), "bob".into()];
+        let profiles = std::collections::HashMap::from([("alice".into(), vec![PK_VALID_A.into()])]);
+        assert_eq!(
+            resolve_names_to_pubkeys(&names, &profiles, true).unwrap(),
+            vec![PK_VALID_A]
+        );
+        assert!(resolve_names_to_pubkeys(&names, &profiles, false).is_err());
+    }
+
+    #[test]
+    fn combined_mention_union_errors_instead_of_truncating() {
+        let explicit: Vec<String> = (0..50).map(|i| format!("explicit-{i}")).collect();
+        assert!(merge_message_mentions(&explicit, &[], &["resolved-bob".into()]).is_err());
+
+        let mut with_duplicate = explicit.clone();
+        with_duplicate.push(explicit[0].clone());
+        assert_eq!(
+            merge_message_mentions(&with_duplicate, &[explicit[1].clone()], &[])
+                .unwrap()
+                .len(),
+            50
+        );
+    }
+
+    #[test]
+    fn membership_preflight_lists_only_missing_mentions() {
+        assert_eq!(
+            missing_members(
+                &[PK_VALID_A.into(), PK_VALID_B.into()],
+                &[PK_VALID_A.into()]
+            ),
+            vec![PK_VALID_B]
+        );
+    }
+
+    #[test]
+    fn mention_evidence_comes_from_signed_event_tags() {
+        use nostr::{EventBuilder, Keys, Tag};
+        let event = EventBuilder::text_note("hello")
+            .tags(vec![Tag::parse(["p", PK_VALID_A]).unwrap()])
+            .sign_with_keys(&Keys::generate())
+            .unwrap();
+        assert_eq!(event_mention_pubkeys(&event), vec![PK_VALID_A]);
+    }
+
     // ---- match_profiles_by_name (author resolution for `messages search --author`) ----
 
     fn profile_event(
diff --git a/crates/buzz-cli/src/commands/mod.rs b/crates/buzz-cli/src/commands/mod.rs
index 8691590636..1ccc37a702 100644
--- a/crates/buzz-cli/src/commands/mod.rs
+++ b/crates/buzz-cli/src/commands/mod.rs
@@ -12,9 +12,37 @@ pub mod notes;
 pub mod pack;
 pub mod patches;
 pub mod pr;
+pub mod projects;
 pub mod reactions;
 pub mod repos;
 pub mod social;
 pub mod upload;
 pub mod users;
 pub mod workflows;
+
+use crate::{client::normalize_write_response, error::CliError};
+
+/// Parse a relay write-response JSON blob, mapping a duplicate (dominated)
+/// write to [`CliError::Conflict`] with the caller-supplied message.
+///
+/// Used by every command that publishes an NIP-33 addressable event and
+/// needs to tell accepted from duplicate/dominated.
+pub fn parse_write_response(raw: &str, conflict_msg: &str) -> Result<String, CliError> {
+    let response: serde_json::Value = serde_json::from_str(raw)
+        .map_err(|e| CliError::Other(format!("relay response is not JSON: {e} ({raw})")))?;
+    let accepted = response
+        .get("accepted")
+        .and_then(serde_json::Value::as_bool)
+        .unwrap_or(false);
+    let message = response
+        .get("message")
+        .and_then(serde_json::Value::as_str)
+        .unwrap_or("");
+    if !accepted {
+        return Err(CliError::Other(format!("relay rejected event: {message}")));
+    }
+    if message == "duplicate" || message.starts_with("duplicate:") {
+        return Err(CliError::Conflict(conflict_msg.to_string()));
+    }
+    Ok(normalize_write_response(raw))
+}
diff --git a/crates/buzz-cli/src/commands/projects.rs b/crates/buzz-cli/src/commands/projects.rs
new file mode 100644
index 0000000000..e6798dbfc4
--- /dev/null
+++ b/crates/buzz-cli/src/commands/projects.rs
@@ -0,0 +1,1198 @@
+//! `buzz projects` commands — NIP-MP kind:30621 write path.
+//!
+//! All mutations follow a read-modify-write pattern:
+//!   1. Fetch the caller's own live head via `kinds:[30621] + authors:[self] + #d:[slug]`.
+//!   2. Mutate the tag set (strip `auth`, apply change).
+//!   3. Re-validate the full envelope through Layer A before submitting.
+//!   4. Set `created_at = head.created_at + 1` (never wall-clock) to avoid
+//!      overwriting a concurrently advancing head.
+//!
+//! Limitations recorded in this phase:
+//!   - Relay hints are read-preserved but not authored (`--repo` carries
+//!     a coordinate only; existing hinted tags survive RMW unchanged).
+//!   - `delete` targets signer-self only (NIP-OA owner-delete path deferred).
+//!   - Deletion durability against later arrival (watermark follow-up) is
+//!     not in scope.
+
+use buzz_core::kind::KIND_PROJECT;
+use buzz_sdk::{
+    build_delete_addressable, build_project, build_project_with_tags, ProjectMemberCoord,
+    PROJECT_D_MAX_LEN,
+};
+use nostr::{Event, EventBuilder, Tag, Timestamp};
+
+use crate::client::BuzzClient;
+use crate::commands::parse_write_response;
+use crate::error::CliError;
+
+// ── Buzz repo-ID grammar (bare --repo shorthand) ─────────────────────────────
+
+/// Pattern for a Buzz-hosted repo identifier (bare `--repo` shorthand).
+/// `[a-zA-Z0-9._-]{1,64}` — no colons, so guaranteed collision-free with
+/// `30617:<owner>:<d>` full coordinates.
+fn is_bare_repo_id(s: &str) -> bool {
+    !s.is_empty()
+        && s.len() <= 64
+        && s.chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '_' || c == '-')
+}
+
+/// Expand a CLI `--repo` argument into a full `30617:<owner>:<d>` coordinate.
+///
+/// Bare form (`[a-zA-Z0-9._-]{1,64}`): owner defaults to the caller's pubkey.
+/// Full form (`30617:<owner-hex>:<d>`): used verbatim.
+fn expand_repo_coord(s: &str, caller_pubkey: &str) -> Result<ProjectMemberCoord, CliError> {
+    if is_bare_repo_id(s) {
+        // Bare form: expand to full coordinate with caller as owner.
+        let full = format!("30617:{caller_pubkey}:{s}");
+        ProjectMemberCoord::parse_full(&full)
+            .map_err(|e| CliError::Usage(format!("invalid repo coordinate: {e}")))
+    } else {
+        // Full form: must be parseable as a complete coordinate.
+        ProjectMemberCoord::parse_full(s)
+            .map_err(|e| CliError::Usage(format!("invalid repo coordinate: {e}")))
+    }
+}
+
+// ── Head-fetch helper ─────────────────────────────────────────────────────────
+
+fn parse_events(json: &str) -> Result<Vec<Event>, CliError> {
+    serde_json::from_str(json)
+        .map_err(|e| CliError::Other(format!("failed to parse relay response: {e}")))
+}
+
+/// Fetch the caller's own live kind:30621 head for `slug`.
+async fn fetch_own_project(client: &BuzzClient, slug: &str) -> Result<Option<Event>, CliError> {
+    fetch_project(client, slug, None).await
+}
+
+/// Fetch a project head by slug and optional owner pubkey.
+async fn fetch_project(
+    client: &BuzzClient,
+    slug: &str,
+    owner: Option<&str>,
+) -> Result<Option<Event>, CliError> {
+    let pubkey = match owner {
+        Some(pk) => {
+            crate::validate::validate_hex64(pk)?;
+            pk.to_string()
+        }
+        None => client.keys().public_key().to_hex(),
+    };
+    let filter = serde_json::json!({
+        "kinds": [KIND_PROJECT],
+        "authors": [pubkey],
+        "#d": [slug],
+        "limit": 1,
+    });
+    let raw = client.query(&filter).await?;
+    let mut events = parse_events(&raw)?;
+    events.sort_by_key(|e| std::cmp::Reverse(e.created_at));
+    Ok(events.into_iter().next())
+}
+
+// ── Tag helpers ───────────────────────────────────────────────────────────────
+
+fn tag_name(tag: &Tag) -> Option<&str> {
+    tag.as_slice().first().map(String::as_str)
+}
+
+fn tag_value(tag: &Tag) -> Option<&str> {
+    tag.as_slice().get(1).map(String::as_str)
+}
+
+fn make_tag(parts: &[&str]) -> Result<Tag, CliError> {
+    Tag::parse(parts.iter().copied())
+        .map_err(|e| CliError::Other(format!("tag construction failed: {e}")))
+}
+
+// ── Submit helper ─────────────────────────────────────────────────────────────
+
+async fn submit_project(client: &BuzzClient, builder: EventBuilder) -> Result<(), CliError> {
+    let event = client.sign_event(builder)?;
+    let raw = client.submit_event(event).await?;
+    println!(
+        "{}",
+        parse_write_response(&raw, "project changed concurrently; retry")?
+    );
+    Ok(())
+}
+
+// ── Build helpers ─────────────────────────────────────────────────────────────
+
+/// Advance the `created_at` counter off an observed head.
+fn next_timestamp(head: &Event) -> Result<Timestamp, CliError> {
+    head.created_at
+        .as_secs()
+        .checked_add(1)
+        .map(Timestamp::from)
+        .ok_or_else(|| CliError::Other("project timestamp cannot be advanced".into()))
+}
+
+/// Strip `auth` from a tag list and pass the resulting envelope through
+/// Layer A validation. Returns a validated `EventBuilder` at `next_ts`.
+fn rebuild_project(
+    content: &str,
+    tags: Vec<Tag>,
+    next_ts: Timestamp,
+) -> Result<EventBuilder, CliError> {
+    // Strip auth tags.
+    let clean_tags: Vec<Tag> = tags
+        .into_iter()
+        .filter(|t| tag_name(t) != Some("auth"))
+        .collect();
+
+    build_project_with_tags(content, clean_tags)
+        .map_err(|e| CliError::Other(format!("envelope validation failed: {e}")))
+        .map(|b| b.custom_created_at(next_ts))
+}
+
+// ── Command implementations ───────────────────────────────────────────────────
+
+/// `buzz projects create`
+pub async fn cmd_create(
+    client: &BuzzClient,
+    slug: &str,
+    repos: &[String],
+    name: Option<&str>,
+    description: Option<&str>,
+    channel: Option<&str>,
+    visibility: Option<&str>,
+) -> Result<(), CliError> {
+    // ── Local validation (all checks before any .await) ───────────────────
+    validate_project_slug(slug)?;
+
+    let caller_pubkey = client.keys().public_key().to_hex();
+
+    // Expand and validate repo coordinates.
+    let members: Vec<ProjectMemberCoord> = repos
+        .iter()
+        .map(|r| expand_repo_coord(r, &caller_pubkey))
+        .collect::<Result<Vec<_>, _>>()?;
+
+    // Dedupe: preserve first occurrence, reject duplicates with Usage.
+    let mut seen = std::collections::HashSet::new();
+    for m in &members {
+        if !seen.insert(m.coord.clone()) {
+            return Err(CliError::Usage(format!(
+                "duplicate --repo coordinate in this invocation: {:?}",
+                m.coord
+            )));
+        }
+    }
+
+    // Validate optional metadata (early, before any network call).
+    if let Some(ch) = channel {
+        crate::validate::validate_uuid(ch)?;
+    }
+    if let Some(vis) = visibility {
+        validate_visibility(vis)?;
+    }
+    if let Some(n) = name {
+        if n.len() > 256 {
+            return Err(CliError::Usage(format!(
+                "project name must not exceed 256 bytes (got {})",
+                n.len()
+            )));
+        }
+    }
+
+    // ── Network: collision preflight ──────────────────────────────────────
+    if fetch_own_project(client, slug).await?.is_some() {
+        return Err(CliError::Conflict(format!(
+            "project {slug:?} already exists; use 'buzz projects update' to modify it"
+        )));
+    }
+
+    // ── Build via Layer B (enforces all writer policy) ────────────────────
+    let builder = build_project(slug, name, description, &members, channel, visibility)
+        .map_err(|e| CliError::Usage(e.to_string()))?;
+    submit_project(client, builder).await
+}
+
+/// `buzz projects get`
+pub async fn cmd_get(client: &BuzzClient, slug: &str, owner: Option<&str>) -> Result<(), CliError> {
+    validate_project_slug(slug)?;
+    let resp = match fetch_project(client, slug, owner).await? {
+        Some(event) => serde_json::json!({
+            "event_id": event.id.to_hex(),
+            "pubkey": event.pubkey.to_hex(),
+            "created_at": event.created_at.as_secs(),
+            "kind": event.kind.as_u16(),
+            "tags": event.tags.iter().map(|t| t.as_slice().to_vec()).collect::<Vec<_>>(),
+            "content": event.content,
+        }),
+        None => {
+            let owner_desc = owner.unwrap_or("current identity");
+            return Err(CliError::NotFound(format!(
+                "project {slug:?} not found for {owner_desc}"
+            )));
+        }
+    };
+    println!("{resp}");
+    Ok(())
+}
+
+/// `buzz projects list`
+pub async fn cmd_list(
+    client: &BuzzClient,
+    owner: Option<&str>,
+    limit: Option<u32>,
+) -> Result<(), CliError> {
+    let pubkey = match owner {
+        Some(pk) => {
+            crate::validate::validate_hex64(pk)?;
+            pk.to_string()
+        }
+        None => client.keys().public_key().to_hex(),
+    };
+    let mut filter = serde_json::json!({
+        "kinds": [KIND_PROJECT],
+        "authors": [pubkey],
+    });
+    if let Some(n) = limit {
+        filter["limit"] = serde_json::json!(n);
+    }
+    let resp = client.query(&filter).await?;
+    println!("{resp}");
+    Ok(())
+}
+
+/// `buzz projects add-repo`
+pub async fn cmd_add_repo(
+    client: &BuzzClient,
+    slug: &str,
+    repos: &[String],
+) -> Result<(), CliError> {
+    validate_project_slug(slug)?;
+    let caller_pubkey = client.keys().public_key().to_hex();
+
+    // ── Local validation before any .await ────────────────────────────────
+    let new_members: Vec<ProjectMemberCoord> = repos
+        .iter()
+        .map(|r| expand_repo_coord(r, &caller_pubkey))
+        .collect::<Result<Vec<_>, _>>()?;
+
+    // Dedupe within this invocation: first occurrence wins, duplicate → Usage.
+    let mut seen = std::collections::HashSet::new();
+    for m in &new_members {
+        if !seen.insert(m.coord.clone()) {
+            return Err(CliError::Usage(format!(
+                "duplicate --repo coordinate in this invocation: {:?}",
+                m.coord
+            )));
+        }
+    }
+
+    // ── Network: fetch head ───────────────────────────────────────────────
+    let head = fetch_own_project(client, slug)
+        .await?
+        .ok_or_else(|| CliError::NotFound(format!("project {slug:?} not found")))?;
+    let next_ts = next_timestamp(&head)?;
+
+    // Build the new tag set: keep existing tags (including hinted members),
+    // append new members only if not already present (by coordinate).
+    let mut tags: Vec<Tag> = head.tags.iter().cloned().collect();
+    let existing_coords: std::collections::HashSet<String> = head
+        .tags
+        .iter()
+        .filter(|t| tag_name(t) == Some("a"))
+        .filter_map(|t| tag_value(t).map(String::from))
+        .collect();
+    let mut added = 0usize;
+    for m in &new_members {
+        if !existing_coords.contains(m.coord.as_str()) {
+            let parts = m.to_tag_parts();
+            let parts_ref: Vec<&str> = parts.iter().map(String::as_str).collect();
+            tags.push(
+                Tag::parse(parts_ref.iter().copied())
+                    .map_err(|e| CliError::Other(format!("member tag construction failed: {e}")))?,
+            );
+            added += 1;
+        }
+    }
+
+    // All requested coordinates were already present — no change to publish.
+    if added == 0 {
+        return Err(CliError::Conflict(format!(
+            "all requested repositories are already members of project {slug:?}"
+        )));
+    }
+
+    let builder = rebuild_project(&head.content, tags, next_ts)?;
+    submit_project(client, builder).await
+}
+
+/// `buzz projects remove-repo`
+pub async fn cmd_remove_repo(
+    client: &BuzzClient,
+    slug: &str,
+    repos: &[String],
+) -> Result<(), CliError> {
+    validate_project_slug(slug)?;
+    let caller_pubkey = client.keys().public_key().to_hex();
+
+    // ── Local validation before any .await ────────────────────────────────
+    let to_remove: Vec<ProjectMemberCoord> = repos
+        .iter()
+        .map(|r| expand_repo_coord(r, &caller_pubkey))
+        .collect::<Result<Vec<_>, _>>()?;
+
+    // ── Network: fetch head ───────────────────────────────────────────────
+    let head = fetch_own_project(client, slug)
+        .await?
+        .ok_or_else(|| CliError::NotFound(format!("project {slug:?} not found")))?;
+    let next_ts = next_timestamp(&head)?;
+
+    // Verify all requested repos exist in the project.
+    let existing_coords: std::collections::HashSet<String> = head
+        .tags
+        .iter()
+        .filter(|t| tag_name(t) == Some("a"))
+        .filter_map(|t| tag_value(t).map(String::from))
+        .collect();
+    for m in &to_remove {
+        if !existing_coords.contains(m.coord.as_str()) {
+            return Err(CliError::NotFound(format!(
+                "project {slug:?} does not contain member {:?}",
+                m.coord
+            )));
+        }
+    }
+
+    let remove_coords: std::collections::HashSet<&str> =
+        to_remove.iter().map(|m| m.coord.as_str()).collect();
+
+    // Keep all tags except auth and the removed members.
+    let tags: Vec<Tag> = head
+        .tags
+        .iter()
+        .filter(|t| {
+            if tag_name(t) == Some("auth") {
+                return false;
+            }
+            if tag_name(t) == Some("a") {
+                if let Some(coord) = tag_value(t) {
+                    return !remove_coords.contains(coord);
+                }
+            }
+            true
+        })
+        .cloned()
+        .collect();
+
+    // Single rebuild validates the full envelope and strips any remaining auth.
+    let builder = rebuild_project(&head.content, tags, next_ts)?;
+    submit_project(client, builder).await
+}
+
+/// `buzz projects update`
+///
+/// Requires at least one setter or clearer; a no-op call is a usage error.
+#[allow(clippy::too_many_arguments)]
+pub async fn cmd_update(
+    client: &BuzzClient,
+    slug: &str,
+    name: Option<&str>,
+    clear_name: bool,
+    description: Option<&str>,
+    clear_description: bool,
+    channel: Option<&str>,
+    clear_channel: bool,
+    visibility: Option<&str>,
+    clear_visibility: bool,
+) -> Result<(), CliError> {
+    // Guard: at least one mutation required. The clap `ArgGroup` with
+    // `required(true).multiple(true)` enforces this at parse time; this
+    // runtime check is a defense-in-depth safety net for callers that invoke
+    // `cmd_update` directly (e.g. tests and future programmatic callers).
+    let has_mutation = name.is_some()
+        || clear_name
+        || description.is_some()
+        || clear_description
+        || channel.is_some()
+        || clear_channel
+        || visibility.is_some()
+        || clear_visibility;
+    if !has_mutation {
+        return Err(CliError::Usage(
+            "buzz projects update requires at least one of: \
+             --name, --clear-name, --description, --clear-description, \
+             --channel, --clear-channel, --visibility, --clear-visibility"
+                .into(),
+        ));
+    }
+
+    validate_project_slug(slug)?;
+    if let Some(ch) = channel {
+        crate::validate::validate_uuid(ch)?;
+    }
+    if let Some(vis) = visibility {
+        validate_visibility(vis)?;
+    }
+
+    let head = fetch_own_project(client, slug)
+        .await?
+        .ok_or_else(|| CliError::NotFound(format!("project {slug:?} not found")))?;
+    let next_ts = next_timestamp(&head)?;
+
+    // Build the new tag set. For each singleton metadata field:
+    //   - setter present: replace value (strip old, append new)
+    //   - clear flag set: drop the tag
+    //   - neither: keep existing
+    // Non-singleton / non-metadata tags (d, a, unknown) are preserved as-is.
+    let singleton_fields = ["name", "description", "buzz-channel", "buzz-visibility"];
+    let mut tags: Vec<Tag> = head
+        .tags
+        .iter()
+        .filter(|t| {
+            if tag_name(t) == Some("auth") {
+                return false;
+            }
+            // Drop singletons we're replacing or clearing.
+            if let Some(field) = tag_name(t) {
+                if singleton_fields.contains(&field) {
+                    let clear = match field {
+                        "name" => clear_name || name.is_some(),
+                        "description" => clear_description || description.is_some(),
+                        "buzz-channel" => clear_channel || channel.is_some(),
+                        "buzz-visibility" => clear_visibility || visibility.is_some(),
+                        _ => false,
+                    };
+                    return !clear;
+                }
+            }
+            true
+        })
+        .cloned()
+        .collect();
+
+    // Append new singleton values.
+    if let Some(n) = name {
+        tags.push(make_tag(&["name", n])?);
+    }
+    if let Some(d) = description {
+        tags.push(make_tag(&["description", d])?);
+    }
+    if let Some(ch) = channel {
+        tags.push(make_tag(&["buzz-channel", ch])?);
+    }
+    if let Some(vis) = visibility {
+        tags.push(make_tag(&["buzz-visibility", vis])?);
+    }
+
+    let builder = build_project_with_tags(&head.content, tags)
+        .map_err(|e| CliError::Other(format!("envelope validation failed: {e}")))?
+        .custom_created_at(next_ts);
+    submit_project(client, builder).await
+}
+
+/// `buzz projects delete`
+///
+/// Head-based and verified:
+///   1. Fetch own live head — `NotFound` if absent.
+///   2. Build tombstone at `head.created_at + 1`.
+///   3. Submit.
+///   4. Re-query the coordinate; if a newer head survived → `Conflict`.
+pub async fn cmd_delete(client: &BuzzClient, slug: &str) -> Result<(), CliError> {
+    validate_project_slug(slug)?;
+
+    let head = fetch_own_project(client, slug)
+        .await?
+        .ok_or_else(|| CliError::NotFound(format!("project {slug:?} not found")))?;
+    let next_ts = next_timestamp(&head)?;
+
+    let pubkey_hex = client.keys().public_key().to_hex();
+    let tombstone = build_delete_addressable(KIND_PROJECT, &pubkey_hex, slug)
+        .map_err(|e| CliError::Other(format!("failed to build delete event: {e}")))?
+        .custom_created_at(next_ts);
+
+    let event = client.sign_event(tombstone)?;
+    let raw = client.submit_event(event).await?;
+    parse_write_response(&raw, "delete event was dominated; a newer head exists")?;
+
+    // Post-submit verification: re-query to confirm the head is gone.
+    if let Some(survivor) = fetch_own_project(client, slug).await? {
+        // A newer head survived the tombstone.
+        return Err(CliError::Conflict(format!(
+            "project {slug:?} still exists (head at {}); a concurrent write raced the delete",
+            survivor.created_at.as_secs()
+        )));
+    }
+
+    println!("{}", serde_json::json!({ "deleted": slug, "status": "ok" }));
+    Ok(())
+}
+
+// ── Validation helpers ────────────────────────────────────────────────────────
+
+/// Validate a project slug: non-empty, ≤1024 bytes, verbatim.
+/// Does NOT impose the Buzz repo-ID grammar — project slugs are more permissive.
+fn validate_project_slug(slug: &str) -> Result<(), CliError> {
+    if slug.is_empty() {
+        return Err(CliError::Usage("project slug must not be empty".into()));
+    }
+    if slug.len() > PROJECT_D_MAX_LEN {
+        return Err(CliError::Usage(format!(
+            "project slug must not exceed {PROJECT_D_MAX_LEN} bytes (got {})",
+            slug.len()
+        )));
+    }
+    Ok(())
+}
+
+/// Validate a `buzz-visibility` value at the writer level.
+fn validate_visibility(vis: &str) -> Result<(), CliError> {
+    if vis != "listed" && vis != "unlisted" {
+        return Err(CliError::Usage(format!(
+            "visibility must be 'listed' or 'unlisted' (got {vis:?})"
+        )));
+    }
+    Ok(())
+}
+
+// ── Dispatch ──────────────────────────────────────────────────────────────────
+
+pub async fn dispatch(cmd: crate::ProjectsCmd, client: &BuzzClient) -> Result<(), CliError> {
+    use crate::ProjectsCmd;
+    match cmd {
+        ProjectsCmd::Create {
+            slug,
+            repo,
+            name,
+            description,
+            channel,
+            visibility,
+        } => {
+            cmd_create(
+                client,
+                &slug,
+                &repo,
+                name.as_deref(),
+                description.as_deref(),
+                channel.as_deref(),
+                visibility.map(|v| v.as_str()),
+            )
+            .await
+        }
+        ProjectsCmd::Get { slug, owner } => cmd_get(client, &slug, owner.as_deref()).await,
+        ProjectsCmd::List { owner, limit } => cmd_list(client, owner.as_deref(), limit).await,
+        ProjectsCmd::AddRepo { slug, repo } => cmd_add_repo(client, &slug, &repo).await,
+        ProjectsCmd::RemoveRepo { slug, repo } => cmd_remove_repo(client, &slug, &repo).await,
+        ProjectsCmd::Update {
+            slug,
+            name,
+            clear_name,
+            description,
+            clear_description,
+            channel,
+            clear_channel,
+            visibility,
+            clear_visibility,
+        } => {
+            cmd_update(
+                client,
+                &slug,
+                name.as_deref(),
+                clear_name,
+                description.as_deref(),
+                clear_description,
+                channel.as_deref(),
+                clear_channel,
+                visibility.map(|v| v.as_str()),
+                clear_visibility,
+            )
+            .await
+        }
+        ProjectsCmd::Delete { slug } => cmd_delete(client, &slug).await,
+    }
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use buzz_sdk::{validate_project_envelope, PROJECT_MEMBER_CAP};
+    use nostr::Tag;
+
+    use super::*;
+
+    // ── Coordinate expansion ──────────────────────────────────────────────────
+
+    const OWNER_HEX: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+    const OWNER_B_HEX: &str = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+
+    #[test]
+    fn expand_repo_coord_bare_expands_with_caller_pubkey() {
+        let coord = expand_repo_coord("my-repo", OWNER_HEX).unwrap();
+        assert_eq!(coord.coord, format!("30617:{OWNER_HEX}:my-repo"));
+    }
+
+    #[test]
+    fn expand_repo_coord_full_passes_through() {
+        let full = format!("30617:{OWNER_HEX}:some-repo");
+        let coord = expand_repo_coord(&full, OWNER_B_HEX).unwrap();
+        // Owner from the full coord, not the caller.
+        assert_eq!(coord.coord, full);
+    }
+
+    #[test]
+    fn expand_repo_coord_full_cross_owner() {
+        let full = format!("30617:{OWNER_B_HEX}:infra");
+        let coord = expand_repo_coord(&full, OWNER_HEX).unwrap();
+        assert_eq!(coord.coord, full);
+    }
+
+    #[test]
+    fn expand_repo_coord_rejects_uppercase_owner() {
+        let upper = "30617:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA:buzz";
+        assert!(expand_repo_coord(upper, OWNER_HEX).is_err());
+    }
+
+    #[test]
+    fn expand_repo_coord_rejects_coordinate_shaped_bare_value() {
+        // A value with a colon is never a bare id.
+        let not_bare = "30617:something";
+        // parse_full will fail because it's not a valid full coordinate either.
+        assert!(expand_repo_coord(not_bare, OWNER_HEX).is_err());
+    }
+
+    // ── validate_project_slug ─────────────────────────────────────────────────
+
+    #[test]
+    fn validate_project_slug_accepts_normal() {
+        assert!(validate_project_slug("my-project").is_ok());
+        assert!(validate_project_slug("platform:v2").is_ok()); // colons allowed — more permissive than repo-id
+    }
+
+    #[test]
+    fn validate_project_slug_rejects_empty() {
+        assert!(validate_project_slug("").is_err());
+    }
+
+    #[test]
+    fn validate_project_slug_rejects_over_1024() {
+        let long = "a".repeat(1025);
+        assert!(validate_project_slug(&long).is_err());
+    }
+
+    #[test]
+    fn validate_project_slug_accepts_1024() {
+        let at_limit = "a".repeat(1024);
+        assert!(validate_project_slug(&at_limit).is_ok());
+    }
+
+    // ── validate_visibility ───────────────────────────────────────────────────
+
+    #[test]
+    fn validate_visibility_accepts_listed_and_unlisted() {
+        assert!(validate_visibility("listed").is_ok());
+        assert!(validate_visibility("unlisted").is_ok());
+    }
+
+    #[test]
+    fn validate_visibility_rejects_unknown_token() {
+        assert!(validate_visibility("chartreuse").is_err());
+        assert!(validate_visibility("").is_err());
+    }
+
+    // ── is_bare_repo_id ───────────────────────────────────────────────────────
+
+    #[test]
+    fn bare_repo_id_accepts_valid() {
+        assert!(is_bare_repo_id("buzz"));
+        assert!(is_bare_repo_id("my-repo_1.0"));
+    }
+
+    #[test]
+    fn bare_repo_id_rejects_colon() {
+        assert!(!is_bare_repo_id("30617:something"));
+        assert!(!is_bare_repo_id("has:colon"));
+    }
+
+    #[test]
+    fn bare_repo_id_rejects_empty() {
+        assert!(!is_bare_repo_id(""));
+    }
+
+    #[test]
+    fn bare_repo_id_rejects_over_64() {
+        let long = "a".repeat(65);
+        assert!(!is_bare_repo_id(&long));
+    }
+
+    // ── tag helpers ───────────────────────────────────────────────────────────
+
+    fn make_test_tag(parts: &[&str]) -> Tag {
+        Tag::parse(parts.iter().copied()).unwrap()
+    }
+
+    // ── rebuild_project: hinted / unknown tag preservation ───────────────────
+
+    #[test]
+    fn rebuild_project_preserves_hinted_member_tags() {
+        // A member 'a' tag with a relay hint must survive RMW untouched.
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let hint = "wss://relay.example.com";
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            Tag::parse(["a", &coord, hint]).unwrap(),
+        ];
+        let ts = Timestamp::from(1_700_000_001u64);
+        let b = rebuild_project("", tags, ts).unwrap();
+        let ev = b.sign_with_keys(&nostr::Keys::generate()).expect("sign");
+        let a_tag = ev
+            .tags
+            .iter()
+            .find(|t| tag_name(t) == Some("a"))
+            .expect("a tag present");
+        assert_eq!(
+            a_tag.as_slice(),
+            &["a".to_string(), coord, hint.to_string()],
+            "relay hint must survive rebuild"
+        );
+    }
+
+    #[test]
+    fn rebuild_project_preserves_unknown_tags() {
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            make_test_tag(&["future-metadata", "value"]),
+        ];
+        let ts = Timestamp::from(1_700_000_001u64);
+        let b = rebuild_project("", tags, ts).unwrap();
+        let ev = b.sign_with_keys(&nostr::Keys::generate()).expect("sign");
+        assert!(ev
+            .tags
+            .iter()
+            .any(|t| tag_name(t) == Some("future-metadata")));
+    }
+
+    #[test]
+    fn rebuild_project_strips_auth_tag() {
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            make_test_tag(&["auth", &"a".repeat(64), "kind=30617", &"b".repeat(128)]),
+        ];
+        let ts = Timestamp::from(1_700_000_001u64);
+        let b = rebuild_project("", tags, ts).unwrap();
+        let ev = b.sign_with_keys(&nostr::Keys::generate()).expect("sign");
+        assert!(
+            !ev.tags.iter().any(|t| tag_name(t) == Some("auth")),
+            "auth tag must be stripped"
+        );
+    }
+
+    #[test]
+    fn rebuild_project_rejects_over_cap_foreign_head() {
+        // A foreign head with 65 members must fail Layer A on republish.
+        let mut tags = vec![make_test_tag(&["d", "wide"])];
+        for i in 0..=64u32 {
+            let coord = format!("30617:{OWNER_HEX}:repo-{i:02}");
+            tags.push(make_test_tag(&["a", &coord]));
+        }
+        assert_eq!(
+            tags.iter().filter(|t| tag_name(t) == Some("a")).count(),
+            65,
+            "65 a-tags"
+        );
+        let ts = Timestamp::from(1_700_000_001u64);
+        // rebuild_project strips auth, but 65 a-tags still exceeds cap.
+        assert!(
+            rebuild_project("", tags, ts).is_err(),
+            "over-cap foreign head must fail rebuild"
+        );
+    }
+
+    #[test]
+    fn rebuild_project_at_exact_cap_succeeds() {
+        let mut tags = vec![make_test_tag(&["d", "wide"])];
+        for i in 0..PROJECT_MEMBER_CAP {
+            let coord = format!("30617:{OWNER_HEX}:repo-{i:02}");
+            tags.push(make_test_tag(&["a", &coord]));
+        }
+        let ts = Timestamp::from(1_700_000_001u64);
+        assert!(rebuild_project("", tags, ts).is_ok());
+    }
+
+    // ── clear-flag semantics ──────────────────────────────────────────────────
+
+    /// Build a minimal head Event for testing update semantics without the relay.
+    fn make_head_tags(extra: &[Tag]) -> Vec<Tag> {
+        let mut tags = vec![make_test_tag(&["d", "platform"])];
+        tags.extend_from_slice(extra);
+        tags
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    fn apply_update_tags(
+        head_tags: Vec<Tag>,
+        name: Option<&str>,
+        clear_name: bool,
+        description: Option<&str>,
+        clear_description: bool,
+        channel: Option<&str>,
+        clear_channel: bool,
+        visibility: Option<&str>,
+        clear_visibility: bool,
+    ) -> Vec<Tag> {
+        // Replicate the tag-mutation logic from cmd_update (sans relay I/O).
+        let singleton_fields = ["name", "description", "buzz-channel", "buzz-visibility"];
+        let mut tags: Vec<Tag> = head_tags
+            .iter()
+            .filter(|t| {
+                if tag_name(t) == Some("auth") {
+                    return false;
+                }
+                if let Some(field) = tag_name(t) {
+                    if singleton_fields.contains(&field) {
+                        let clear = match field {
+                            "name" => clear_name || name.is_some(),
+                            "description" => clear_description || description.is_some(),
+                            "buzz-channel" => clear_channel || channel.is_some(),
+                            "buzz-visibility" => clear_visibility || visibility.is_some(),
+                            _ => false,
+                        };
+                        return !clear;
+                    }
+                }
+                true
+            })
+            .cloned()
+            .collect();
+        if let Some(n) = name {
+            tags.push(make_test_tag(&["name", n]));
+        }
+        if let Some(d) = description {
+            tags.push(make_test_tag(&["description", d]));
+        }
+        if let Some(ch) = channel {
+            tags.push(make_test_tag(&["buzz-channel", ch]));
+        }
+        if let Some(vis) = visibility {
+            tags.push(make_test_tag(&["buzz-visibility", vis]));
+        }
+        tags
+    }
+
+    #[test]
+    fn update_omission_preserves_existing_field() {
+        let head = make_head_tags(&[make_test_tag(&["name", "Old Name"])]);
+        let result = apply_update_tags(head, None, false, None, false, None, false, None, false);
+        assert!(result.iter().any(|t| tag_value(t) == Some("Old Name")));
+    }
+
+    #[test]
+    fn update_setter_replaces_existing_field() {
+        let head = make_head_tags(&[make_test_tag(&["name", "Old Name"])]);
+        let result = apply_update_tags(
+            head,
+            Some("New Name"),
+            false,
+            None,
+            false,
+            None,
+            false,
+            None,
+            false,
+        );
+        assert!(result.iter().any(|t| tag_value(t) == Some("New Name")));
+        assert!(!result.iter().any(|t| tag_value(t) == Some("Old Name")));
+    }
+
+    #[test]
+    fn update_clear_drops_existing_field() {
+        let head = make_head_tags(&[make_test_tag(&["name", "Old Name"])]);
+        let result = apply_update_tags(head, None, true, None, false, None, false, None, false);
+        assert!(!result.iter().any(|t| tag_name(t) == Some("name")));
+    }
+
+    #[test]
+    fn update_clear_visibility_drops_tag() {
+        let head = make_head_tags(&[make_test_tag(&["buzz-visibility", "unlisted"])]);
+        let result = apply_update_tags(head, None, false, None, false, None, false, None, true);
+        assert!(!result
+            .iter()
+            .any(|t| tag_name(t) == Some("buzz-visibility")));
+    }
+
+    #[test]
+    fn update_exactly_one_singleton_after_replace() {
+        // Start with a buzz-channel; replace with a new one; must have exactly one.
+        let uuid1 = "3580ca9b-47b4-4af9-b22a-1068778f26c6";
+        let uuid2 = "00000000-0000-0000-0000-000000000000";
+        let head = make_head_tags(&[make_test_tag(&["buzz-channel", uuid1])]);
+        let result = apply_update_tags(
+            head,
+            None,
+            false,
+            None,
+            false,
+            Some(uuid2),
+            false,
+            None,
+            false,
+        );
+        let channels: Vec<_> = result
+            .iter()
+            .filter(|t| tag_name(t) == Some("buzz-channel"))
+            .collect();
+        assert_eq!(channels.len(), 1);
+        assert_eq!(tag_value(channels[0]), Some(uuid2));
+    }
+
+    // ── duplicate-member rejection on republish ───────────────────────────────
+
+    #[test]
+    fn duplicate_member_in_foreign_head_fails_rebuild() {
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            make_test_tag(&["a", &coord]),
+            make_test_tag(&["a", &coord]), // duplicate
+        ];
+        let ts = Timestamp::from(1_700_000_001u64);
+        assert!(rebuild_project("", tags, ts).is_err());
+    }
+
+    // ── validate_project_envelope integration ────────────────────────────────
+
+    #[test]
+    fn validate_project_envelope_accepts_hinted_member() {
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            Tag::parse(["a", &coord, "wss://relay.example.com"]).unwrap(),
+        ];
+        assert!(validate_project_envelope(&tags, "").is_ok());
+    }
+
+    #[test]
+    fn validate_project_envelope_rejects_four_element_member() {
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            Tag::parse(["a", &coord, "wss://relay.example.com", "extra"]).unwrap(),
+        ];
+        assert!(validate_project_envelope(&tags, "").is_err());
+    }
+
+    // ── next_timestamp ordering ───────────────────────────────────────────────
+
+    /// `next_timestamp` must return `head.created_at + 1` regardless of the wall
+    /// clock.  NIP-MP Deletion rule: a tombstone older than the live head does
+    /// NOT remove it, so we must advance strictly off the observed head — never
+    /// use wall-clock time, which could be behind a head that was bumped
+    /// multiple times in the same second.
+    #[test]
+    fn next_timestamp_returns_head_plus_one_when_head_is_ahead_of_wall_clock() {
+        // Build a minimal signed event with a created_at far in the future.
+        let keys = nostr::Keys::generate();
+        let far_future_ts = Timestamp::from(9_999_999_999u64); // year 2286
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            make_test_tag(&["a", &format!("30617:{OWNER_HEX}:buzz")]),
+        ];
+        let builder = rebuild_project("", tags, far_future_ts).expect("valid head envelope");
+        let head = builder.sign_with_keys(&keys).expect("sign");
+        // Verify the event actually has our future timestamp.
+        assert_eq!(head.created_at, far_future_ts);
+
+        // next_timestamp must return far_future + 1, not now().
+        let next = next_timestamp(&head).expect("no overflow");
+        assert_eq!(
+            next.as_secs(),
+            far_future_ts.as_secs() + 1,
+            "tombstone must be strictly after head, even when head is far in the future"
+        );
+    }
+
+    // ── empty update guard ────────────────────────────────────────────────────
+
+    /// `cmd_update` with no setters or clearers must return `CliError::Usage`
+    /// before making any network call.  The guard is synchronous (before the
+    /// first `.await`) so we can drive it with a dummy client whose address
+    /// would reject any real connection attempt.
+    #[tokio::test]
+    async fn empty_update_returns_usage_error_before_any_network_call() {
+        let keys = nostr::Keys::generate();
+        // Port 9 is the discard protocol — any real connect will be refused
+        // immediately, but the guard fires before the first await so this
+        // never reaches the network.
+        let client = crate::client::BuzzClient::new("http://127.0.0.1:9".into(), keys, None, None)
+            .expect("client construction");
+
+        let err = cmd_update(
+            &client, "my-slug", None, false, // name / clear_name
+            None, false, // description / clear_description
+            None, false, // channel / clear_channel
+            None, false, // visibility / clear_visibility
+        )
+        .await
+        .expect_err("empty update must fail");
+
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage, got {err:?}"
+        );
+    }
+
+    // ── no-network malformed-input tests ─────────────────────────────────────
+    //
+    // All three cases use port 9 (discard protocol): any real connection is
+    // refused immediately, but local validation fires before the first .await
+    // so the network is never touched.
+
+    fn discard_client() -> crate::client::BuzzClient {
+        let keys = nostr::Keys::generate();
+        crate::client::BuzzClient::new("http://127.0.0.1:9".into(), keys, None, None)
+            .expect("client construction")
+    }
+
+    /// Invalid visibility token must return Usage before touching the relay.
+    #[tokio::test]
+    async fn create_invalid_visibility_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let err = cmd_create(
+            &client,
+            "my-slug",
+            &["buzz".to_string()],
+            None,
+            None,
+            None,
+            Some("chartreuse"),
+        )
+        .await
+        .expect_err("invalid visibility must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for invalid visibility, got {err:?}"
+        );
+    }
+
+    /// A name longer than 256 bytes must return Usage before touching the relay.
+    #[tokio::test]
+    async fn create_overlong_name_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let long_name = "a".repeat(257);
+        let err = cmd_create(
+            &client,
+            "my-slug",
+            &["buzz".to_string()],
+            Some(&long_name),
+            None,
+            None,
+            None,
+        )
+        .await
+        .expect_err("overlong name must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for overlong name, got {err:?}"
+        );
+    }
+
+    /// A malformed --repo coordinate must return Usage before touching the relay.
+    #[tokio::test]
+    async fn create_malformed_repo_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let err = cmd_create(
+            &client,
+            "my-slug",
+            &["nope:bad".to_string()],
+            None,
+            None,
+            None,
+            None,
+        )
+        .await
+        .expect_err("malformed repo must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for malformed repo, got {err:?}"
+        );
+    }
+
+    /// A malformed --repo coordinate on add-repo must return Usage before touching the relay.
+    #[tokio::test]
+    async fn add_repo_malformed_coord_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let err = cmd_add_repo(&client, "my-slug", &["nope:bad".to_string()])
+            .await
+            .expect_err("malformed repo must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for malformed repo on add-repo, got {err:?}"
+        );
+    }
+
+    /// A malformed --repo coordinate on remove-repo must return Usage before touching the relay.
+    #[tokio::test]
+    async fn remove_repo_malformed_coord_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let err = cmd_remove_repo(&client, "my-slug", &["nope:bad".to_string()])
+            .await
+            .expect_err("malformed repo must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for malformed repo on remove-repo, got {err:?}"
+        );
+    }
+
+    // ── duplicate --repo within one invocation ────────────────────────────────
+
+    /// Supplying the same coordinate twice in one create call must return Usage
+    /// (names the duplicate) before any network call.
+    #[tokio::test]
+    async fn create_duplicate_repo_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let err = cmd_create(
+            &client,
+            "my-slug",
+            &[coord.clone(), coord.clone()],
+            None,
+            None,
+            None,
+            None,
+        )
+        .await
+        .expect_err("duplicate repo must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for duplicate repo, got {err:?}"
+        );
+        // Error message must name the duplicate coordinate.
+        assert!(
+            format!("{err}").contains("buzz"),
+            "Usage message must name the duplicate coordinate, got {err:?}"
+        );
+    }
+
+    /// Supplying the same coordinate twice in one add-repo call must return Usage
+    /// (names the duplicate) before any network call.
+    #[tokio::test]
+    async fn add_repo_duplicate_coord_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let err = cmd_add_repo(&client, "my-slug", &[coord.clone(), coord.clone()])
+            .await
+            .expect_err("duplicate repo must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for duplicate repo on add-repo, got {err:?}"
+        );
+    }
+
+    // ── create collision guard ────────────────────────────────────────────────
+
+    // The create-collision Conflict path is pinned by the live transcript
+    // (step: duplicate create → Conflict, exit=5). No relay mock is available
+    // for a unit test; the no-network tests above cover all pre-await paths.
+
+    // ── add-repo no-op guard ──────────────────────────────────────────────────
+
+    // The add-repo no-op Conflict path is pinned by the live transcript
+    // (step 7: buzz already present → exit=5). No relay mock is available
+    // for a unit test; the async no-network tests above cover all pre-await paths.
+}
diff --git a/crates/buzz-cli/src/commands/repos.rs b/crates/buzz-cli/src/commands/repos.rs
index 0f570df1aa..15e064d9c3 100644
--- a/crates/buzz-cli/src/commands/repos.rs
+++ b/crates/buzz-cli/src/commands/repos.rs
@@ -4,7 +4,8 @@ use buzz_core::{
 };
 use nostr::{Event, EventBuilder, Tag, Timestamp};
 
-use crate::client::{normalize_write_response, BuzzClient};
+use crate::client::BuzzClient;
+use crate::commands::parse_write_response;
 use crate::error::CliError;
 use crate::validate::validate_repo_id;
 
@@ -83,27 +84,36 @@ fn build_protection_tag(
     Tag::parse(values).map_err(tag_error)
 }
 
-enum ProtectionChange {
-    Set(Box<Tag>),
-    Remove(String),
+enum RepoChange {
+    SetProtection(Box<Tag>),
+    RemoveProtection(String),
+    /// Bind (or rebind) the repo to a channel: replaces every existing
+    /// `buzz-channel` tag with exactly one carrying the validated UUID.
+    BindChannel(String),
 }
 
 fn build_updated_repo_announcement(
     existing: &Event,
-    change: ProtectionChange,
+    change: RepoChange,
 ) -> Result<EventBuilder, CliError> {
     let repo_id = repo_id_from_event(existing)?;
-    let (pattern, replacement) = match change {
-        ProtectionChange::Set(tag) => {
+    // What to strip beyond `auth` (always stripped), and what to append.
+    let (removed_pattern, removed_channel, replacement) = match change {
+        RepoChange::SetProtection(tag) => {
             let pattern = protection_pattern(&tag)
                 .ok_or_else(|| CliError::Other("replacement is not a protection tag".into()))?
                 .to_string();
-            (pattern, Some(*tag))
+            (Some(pattern), false, Some(*tag))
         }
-        ProtectionChange::Remove(pattern) => {
+        RepoChange::RemoveProtection(pattern) => {
             RefPattern::parse(&pattern)
                 .map_err(|error| CliError::Usage(format!("invalid ref pattern: {error}")))?;
-            (pattern, None)
+            (Some(pattern), false, None)
+        }
+        RepoChange::BindChannel(channel) => {
+            crate::validate::validate_uuid(&channel)?;
+            let tag = Tag::parse(["buzz-channel", channel.as_str()]).map_err(tag_error)?;
+            (None, true, Some(tag))
         }
     };
 
@@ -111,7 +121,13 @@ fn build_updated_repo_announcement(
         .tags
         .iter()
         .filter(|tag| {
-            !has_tag_name(tag, "auth") && protection_pattern(tag) != Some(pattern.as_str())
+            if has_tag_name(tag, "auth") {
+                return false;
+            }
+            if removed_channel && has_tag_name(tag, "buzz-channel") {
+                return false;
+            }
+            removed_pattern.is_none() || protection_pattern(tag) != removed_pattern.as_deref()
         })
         .cloned()
         .collect();
@@ -171,25 +187,10 @@ fn protection_rules_json(event: &Event) -> Result<serde_json::Value, CliError> {
 }
 
 fn validate_write_response(raw: &str) -> Result<String, CliError> {
-    let response: serde_json::Value = serde_json::from_str(raw)
-        .map_err(|error| CliError::Other(format!("relay response is not JSON: {error} ({raw})")))?;
-    let accepted = response
-        .get("accepted")
-        .and_then(serde_json::Value::as_bool)
-        .unwrap_or(false);
-    let message = response
-        .get("message")
-        .and_then(serde_json::Value::as_str)
-        .unwrap_or("");
-    if !accepted {
-        return Err(CliError::Other(format!("relay rejected event: {message}")));
-    }
-    if message == "duplicate" || message.starts_with("duplicate:") {
-        return Err(CliError::Conflict(
-            "repository changed concurrently; fetch the latest rules and retry".into(),
-        ));
-    }
-    Ok(normalize_write_response(raw))
+    parse_write_response(
+        raw,
+        "repository changed concurrently; fetch the latest rules and retry",
+    )
 }
 
 async fn submit_repo_update(client: &BuzzClient, builder: EventBuilder) -> Result<(), CliError> {
@@ -199,21 +200,30 @@ async fn submit_repo_update(client: &BuzzClient, builder: EventBuilder) -> Resul
     Ok(())
 }
 
-pub async fn cmd_create_repo(
-    client: &BuzzClient,
+/// Build the kind:30617 announcement for `repos create`, including the
+/// `buzz-channel` binding when requested.
+///
+/// Pure (no I/O) so the emitted tags are unit-testable. Exactly one
+/// validated `buzz-channel` tag is appended — the tag is the git ACL
+/// (issue #3527: without it the relay 404s every clone/fetch/push), so the
+/// UUID is shape-validated here and its existence/membership is the relay's
+/// authority at git-access time, same posture as `repos bind`.
+#[allow(clippy::too_many_arguments)]
+fn build_create_announcement(
     repo_id: &str,
     name: Option<&str>,
     description: Option<&str>,
     clone_urls: &[String],
     web_url: Option<&str>,
     relays: &[String],
-) -> Result<(), CliError> {
+    channel: Option<&str>,
+) -> Result<EventBuilder, CliError> {
     validate_repo_id(repo_id)?;
 
     let clone_refs: Vec<&str> = clone_urls.iter().map(|s| s.as_str()).collect();
     let relay_refs: Vec<&str> = relays.iter().map(|s| s.as_str()).collect();
 
-    let builder = buzz_sdk::build_repo_announcement(
+    let mut builder = buzz_sdk::build_repo_announcement(
         repo_id,
         name,
         description,
@@ -223,6 +233,33 @@ pub async fn cmd_create_repo(
     )
     .map_err(|e| CliError::Other(format!("build_repo_announcement failed: {e}")))?;
 
+    if let Some(channel) = channel {
+        crate::validate::validate_uuid(channel)?;
+        builder = builder.tag(Tag::parse(["buzz-channel", channel]).map_err(tag_error)?);
+    }
+    Ok(builder)
+}
+
+#[allow(clippy::too_many_arguments)]
+pub async fn cmd_create_repo(
+    client: &BuzzClient,
+    repo_id: &str,
+    name: Option<&str>,
+    description: Option<&str>,
+    clone_urls: &[String],
+    web_url: Option<&str>,
+    relays: &[String],
+    channel: Option<&str>,
+) -> Result<(), CliError> {
+    let builder = build_create_announcement(
+        repo_id,
+        name,
+        description,
+        clone_urls,
+        web_url,
+        relays,
+        channel,
+    )?;
     let event = client.sign_event(builder)?;
     let resp = client.submit_event(event).await?;
     println!("{resp}");
@@ -320,7 +357,8 @@ async fn cmd_protect_set(
         require_patch,
     )?;
     let event = current_repo(client, repo_id).await?;
-    let builder = build_updated_repo_announcement(&event, ProtectionChange::Set(Box::new(tag)))?;
+    let builder =
+        build_updated_repo_announcement(&event, RepoChange::SetProtection(Box::new(tag)))?;
     submit_repo_update(client, builder).await
 }
 
@@ -341,8 +379,27 @@ async fn cmd_protect_remove(
             "repository {repo_id:?} has no protection rule for {ref_pattern:?}"
         )));
     }
+    let builder = build_updated_repo_announcement(
+        &event,
+        RepoChange::RemoveProtection(ref_pattern.to_string()),
+    )?;
+    submit_repo_update(client, builder).await
+}
+
+/// Bind (or rebind) a repository to a channel — the fix path for issue
+/// #3527's permanently-404 repos. Publishes a read-modify-write update of
+/// the caller's own kind:30617 with exactly one `buzz-channel` tag; all
+/// other metadata (protections, name, description, future tags) is
+/// preserved by the same machinery `repos protect` uses.
+///
+/// The UUID is validated for *shape* only — deliberately. Channel existence
+/// and the caller's membership are the relay's authority at git-access
+/// time; a CLI-side network pre-check would just be TOCTOU with extra
+/// latency.
+async fn cmd_bind_repo(client: &BuzzClient, repo_id: &str, channel: &str) -> Result<(), CliError> {
+    let event = current_repo(client, repo_id).await?;
     let builder =
-        build_updated_repo_announcement(&event, ProtectionChange::Remove(ref_pattern.to_string()))?;
+        build_updated_repo_announcement(&event, RepoChange::BindChannel(channel.to_string()))?;
     submit_repo_update(client, builder).await
 }
 
@@ -356,6 +413,7 @@ pub async fn dispatch(cmd: crate::ReposCmd, client: &BuzzClient) -> Result<(), C
             clone_urls,
             web,
             relays,
+            channel,
         } => {
             cmd_create_repo(
                 client,
@@ -365,11 +423,13 @@ pub async fn dispatch(cmd: crate::ReposCmd, client: &BuzzClient) -> Result<(), C
                 &clone_urls,
                 web.as_deref(),
                 &relays,
+                channel.as_deref(),
             )
             .await
         }
         ReposCmd::Get { id, owner } => cmd_get_repo(client, &id, owner.as_deref()).await,
         ReposCmd::List { owner, limit } => cmd_list_repos(client, owner.as_deref(), limit).await,
+        ReposCmd::Bind { id, channel } => cmd_bind_repo(client, &id, &channel).await,
         ReposCmd::Protect(command) => match command {
             ReposProtectCmd::List { id } => cmd_protect_list(client, &id).await,
             ReposProtectCmd::Set {
@@ -403,8 +463,8 @@ mod tests {
     use nostr::{EventBuilder, Keys, Kind, Tag, Timestamp};
 
     use super::{
-        build_protection_tag, build_updated_repo_announcement, protection_rules_json,
-        validate_write_response, ProtectionChange,
+        build_create_announcement, build_protection_tag, build_updated_repo_announcement,
+        protection_rules_json, validate_write_response, RepoChange,
     };
 
     fn signed_repo(tags: Vec<Tag>, content: &str, created_at: u64) -> nostr::Event {
@@ -439,7 +499,7 @@ mod tests {
 
         let updated = build_updated_repo_announcement(
             &existing,
-            ProtectionChange::Set(Box::new(replacement)),
+            RepoChange::SetProtection(Box::new(replacement)),
         )
         .expect("build update")
         .sign_with_keys(&Keys::generate())
@@ -501,7 +561,7 @@ mod tests {
 
         let updated = build_updated_repo_announcement(
             &existing,
-            ProtectionChange::Remove("refs/heads/main".into()),
+            RepoChange::RemoveProtection("refs/heads/main".into()),
         )
         .expect("build removal")
         .sign_with_keys(&Keys::generate())
@@ -538,7 +598,7 @@ mod tests {
 
         let error = build_updated_repo_announcement(
             &existing,
-            ProtectionChange::Set(Box::new(replacement)),
+            RepoChange::SetProtection(Box::new(replacement)),
         )
         .expect_err("malformed existing rule must fail closed");
 
@@ -564,7 +624,7 @@ mod tests {
 
         let error = build_updated_repo_announcement(
             &existing,
-            ProtectionChange::Set(Box::new(replacement)),
+            RepoChange::SetProtection(Box::new(replacement)),
         )
         .expect_err("the 51st rule must be rejected");
 
@@ -615,6 +675,145 @@ mod tests {
             .is_some_and(|error| error.contains("needs pattern + at least one rule")));
     }
 
+    #[test]
+    fn bind_channel_replaces_duplicates_and_preserves_everything_else() {
+        let channel = uuid::Uuid::new_v4().to_string();
+        let existing = signed_repo(
+            vec![
+                tag(&["d", "demo"]),
+                tag(&["name", "Demo"]),
+                // Two stale bindings — e.g. from a buggy or vanilla client.
+                tag(&["buzz-channel", "old-and-broken"]),
+                tag(&["buzz-channel", &uuid::Uuid::new_v4().to_string()]),
+                tag(&["auth", &"a".repeat(64), "kind=30617", &"b".repeat(128)]),
+                tag(&["buzz-protect", "refs/heads/main", "push:admin"]),
+                tag(&["future-metadata", "preserve-me"]),
+            ],
+            "repository content",
+            100,
+        );
+
+        let updated =
+            build_updated_repo_announcement(&existing, RepoChange::BindChannel(channel.clone()))
+                .expect("build bind update")
+                .sign_with_keys(&Keys::generate())
+                .expect("sign bind update");
+
+        assert_eq!(updated.content, "repository content");
+        assert_eq!(updated.created_at.as_secs(), 101);
+        // Exactly one binding remains, and it is the requested one.
+        let bindings: Vec<_> = updated
+            .tags
+            .iter()
+            .filter(|tag| tag.as_slice().first().map(String::as_str) == Some("buzz-channel"))
+            .collect();
+        assert_eq!(bindings.len(), 1);
+        assert_eq!(bindings[0].as_slice(), ["buzz-channel", channel.as_str()]);
+        // Auth stripped (relay re-stamps); everything else preserved.
+        assert!(!updated
+            .tags
+            .iter()
+            .any(|tag| tag.as_slice().first().map(String::as_str) == Some("auth")));
+        assert!(updated
+            .tags
+            .iter()
+            .any(|tag| tag.as_slice() == ["buzz-protect", "refs/heads/main", "push:admin"]));
+        assert!(updated
+            .tags
+            .iter()
+            .any(|tag| tag.as_slice() == ["future-metadata", "preserve-me"]));
+        assert!(updated
+            .tags
+            .iter()
+            .any(|tag| tag.as_slice() == ["name", "Demo"]));
+    }
+
+    #[test]
+    fn bind_channel_adds_binding_to_unbound_repo() {
+        let channel = uuid::Uuid::new_v4().to_string();
+        let existing = signed_repo(vec![tag(&["d", "demo"])], "", 10);
+
+        let updated =
+            build_updated_repo_announcement(&existing, RepoChange::BindChannel(channel.clone()))
+                .expect("build bind update")
+                .sign_with_keys(&Keys::generate())
+                .expect("sign bind update");
+
+        assert!(updated
+            .tags
+            .iter()
+            .any(|tag| tag.as_slice() == ["buzz-channel", channel.as_str()]));
+    }
+
+    #[test]
+    fn bind_channel_rejects_malformed_uuid() {
+        let existing = signed_repo(vec![tag(&["d", "demo"])], "", 10);
+
+        let error =
+            build_updated_repo_announcement(&existing, RepoChange::BindChannel("nope".into()))
+                .expect_err("malformed channel id must not build an update");
+
+        assert!(matches!(error, crate::error::CliError::Usage(_)));
+    }
+
+    /// Issue #3527: `repos create --channel` must emit exactly one
+    /// `buzz-channel` tag so the primary create command stops producing
+    /// repos the relay 404s forever.
+    #[test]
+    fn create_with_channel_emits_exactly_one_binding_tag() {
+        let channel = uuid::Uuid::new_v4().to_string();
+        let event = build_create_announcement(
+            "demo",
+            Some("Demo"),
+            None,
+            &["https://relay.example/git/owner/demo".to_string()],
+            None,
+            &[],
+            Some(&channel),
+        )
+        .expect("build create announcement")
+        .sign_with_keys(&Keys::generate())
+        .expect("sign create announcement");
+
+        assert_eq!(event.kind, Kind::Custom(30617));
+        let bindings: Vec<_> = event
+            .tags
+            .iter()
+            .filter(|tag| tag.as_slice().first().map(String::as_str) == Some("buzz-channel"))
+            .collect();
+        assert_eq!(bindings.len(), 1, "exactly one buzz-channel tag");
+        assert_eq!(bindings[0].as_slice(), ["buzz-channel", channel.as_str()]);
+        // The standard metadata still rides along.
+        assert!(event.tags.iter().any(|tag| tag.as_slice() == ["d", "demo"]));
+        assert!(event
+            .tags
+            .iter()
+            .any(|tag| tag.as_slice() == ["name", "Demo"]));
+    }
+
+    #[test]
+    fn create_without_channel_emits_no_binding_tag() {
+        let event = build_create_announcement("demo", None, None, &[], None, &[], None)
+            .expect("build create announcement")
+            .sign_with_keys(&Keys::generate())
+            .expect("sign create announcement");
+
+        assert!(
+            !event
+                .tags
+                .iter()
+                .any(|tag| tag.as_slice().first().map(String::as_str) == Some("buzz-channel")),
+            "no --channel means no binding tag (vanilla NIP-34 stays possible)"
+        );
+    }
+
+    #[test]
+    fn create_rejects_malformed_channel_uuid() {
+        let error = build_create_announcement("demo", None, None, &[], None, &[], Some("nope"))
+            .expect_err("malformed channel id must not build an announcement");
+        assert!(matches!(error, crate::error::CliError::Usage(_)));
+    }
+
     #[test]
     fn duplicate_write_response_is_a_conflict() {
         let error = validate_write_response(
diff --git a/crates/buzz-cli/src/commands/users.rs b/crates/buzz-cli/src/commands/users.rs
index f5a0bee879..7c15d285a0 100644
--- a/crates/buzz-cli/src/commands/users.rs
+++ b/crates/buzz-cli/src/commands/users.rs
@@ -1,4 +1,7 @@
-use crate::client::{normalize_write_response, BuzzClient};
+use buzz_core::kind::KIND_MANAGED_AGENT;
+use nostr::PublicKey;
+
+use crate::client::{extract_d_tag, normalize_write_response, BuzzClient};
 use crate::error::CliError;
 use crate::validate::validate_hex64;
 
@@ -13,6 +16,7 @@ pub async fn cmd_get_users(
     client: &BuzzClient,
     pubkeys: &[String],
     name: Option<&str>,
+    owner: Option<&str>,
     format: &crate::OutputFormat,
 ) -> Result<(), CliError> {
     if let Some(query) = name {
@@ -21,7 +25,11 @@ pub async fn cmd_get_users(
                 "--name and --pubkey are mutually exclusive".into(),
             ));
         }
-        return search_by_name(client, query, format).await;
+        return search_by_name(client, query, owner, format).await;
+    }
+
+    if owner.is_some() {
+        return Err(CliError::Usage("--owner requires --name".into()));
     }
 
     for pk in pubkeys {
@@ -76,68 +84,269 @@ pub async fn cmd_get_users(
     Ok(())
 }
 
-/// Search for users by display name via NIP-50 full-text search on kind:0 profiles.
-/// Returns [] if the relay does not implement NIP-50 search.
-async fn search_by_name(
+fn effective_owner(client: &BuzzClient) -> String {
+    client
+        .auth_tag_owner_hex()
+        .unwrap_or_else(|| client.keys().public_key().to_hex())
+}
+
+fn resolve_owner(client: &BuzzClient, owner: Option<&str>) -> Result<Option<String>, CliError> {
+    owner
+        .map(|owner| {
+            if owner == "me" {
+                Ok(effective_owner(client))
+            } else {
+                PublicKey::parse(owner)
+                    .map(|pubkey| pubkey.to_hex())
+                    .map_err(|e| {
+                        CliError::Usage(format!("--owner must be `me`, a pubkey, or npub: {e}"))
+                    })
+            }
+        })
+        .transpose()
+}
+
+fn owned_agent_pubkeys_from_events(events: &[serde_json::Value], query: &str) -> Vec<String> {
+    let mut pubkeys: Vec<String> = events
+        .iter()
+        .filter_map(|event| {
+            let content: serde_json::Value =
+                serde_json::from_str(event.get("content")?.as_str()?).ok()?;
+            let name = content.get("name")?.as_str()?;
+            if !name.eq_ignore_ascii_case(query) {
+                return None;
+            }
+            let pubkey = extract_d_tag(event);
+            (!pubkey.is_empty()).then_some(pubkey)
+        })
+        .collect();
+    pubkeys.sort();
+    pubkeys.dedup();
+    pubkeys
+}
+
+async fn owned_agent_pubkeys_by_name(
     client: &BuzzClient,
+    owner: &str,
     query: &str,
-    format: &crate::OutputFormat,
-) -> Result<(), CliError> {
-    if query.trim().is_empty() {
-        return Err(CliError::Usage("--name cannot be empty".into()));
-    }
-
+) -> Result<Vec<String>, CliError> {
     let filter = serde_json::json!({
-        "kinds": [0],
-        "search": query,
-        "limit": 100
+        "kinds": [KIND_MANAGED_AGENT],
+        "authors": [owner],
     });
-    let raw = client.query(&filter).await?;
-
-    // Parse and filter client-side for case-insensitive substring match
-    // on display_name or name fields (NIP-50 may return broader matches).
-    let events: serde_json::Value = serde_json::from_str(&raw)
-        .map_err(|e| CliError::Other(format!("failed to parse response: {e}")))?;
+    let events = client.query_all(filter).await?;
+    Ok(owned_agent_pubkeys_from_events(&events, query))
+}
 
-    let Some(arr) = events.as_array() else {
-        println!("[]");
-        return Ok(());
-    };
+fn profile_content(event: &serde_json::Value) -> serde_json::Map<String, serde_json::Value> {
+    event
+        .get("content")
+        .and_then(|value| value.as_str())
+        .and_then(|content| serde_json::from_str::<serde_json::Value>(content).ok())
+        .and_then(|content| content.as_object().cloned())
+        .unwrap_or_default()
+}
 
+fn name_search_profiles(events: &[serde_json::Value], query: &str) -> Vec<serde_json::Value> {
     let lower_query = query.to_ascii_lowercase();
-    let profiles: Vec<serde_json::Value> = arr
+    events
         .iter()
         .filter_map(|event| {
-            let content_str = event.get("content").and_then(|v| v.as_str())?;
-            let content: serde_json::Value = serde_json::from_str(content_str).ok()?;
-            let display_name = content
+            let mut profile = profile_content(event);
+            let display_name = profile
                 .get("display_name")
-                .and_then(|v| v.as_str())
+                .and_then(|value| value.as_str())
+                .unwrap_or("");
+            let name = profile
+                .get("name")
+                .and_then(|value| value.as_str())
                 .unwrap_or("");
-            let name = content.get("name").and_then(|v| v.as_str()).unwrap_or("");
             if !display_name.to_ascii_lowercase().contains(&lower_query)
                 && !name.to_ascii_lowercase().contains(&lower_query)
             {
                 return None;
             }
-            let mut profile = content;
-            if let Some(obj) = profile.as_object_mut() {
-                obj.insert(
-                    "pubkey".to_string(),
-                    serde_json::json!(event.get("pubkey").and_then(|v| v.as_str()).unwrap_or("")),
-                );
+            profile.insert(
+                "pubkey".to_string(),
+                serde_json::json!(event
+                    .get("pubkey")
+                    .and_then(|value| value.as_str())
+                    .unwrap_or("")),
+            );
+            Some(serde_json::Value::Object(profile))
+        })
+        .collect()
+}
+
+fn auth_tag_values(event: &serde_json::Value) -> Vec<&serde_json::Value> {
+    event
+        .get("tags")
+        .and_then(|tags| tags.as_array())
+        .into_iter()
+        .flatten()
+        .filter(|tag| {
+            tag.as_array()
+                .and_then(|values| values.first())
+                .and_then(|value| value.as_str())
+                == Some("auth")
+        })
+        .collect()
+}
+
+fn auth_conditions_apply(auth_tag: &serde_json::Value, event: &serde_json::Value) -> bool {
+    let Some(conditions) = auth_tag
+        .as_array()
+        .and_then(|values| values.get(2))
+        .and_then(|value| value.as_str())
+    else {
+        return false;
+    };
+    let Some(kind) = event.get("kind").and_then(|value| value.as_u64()) else {
+        return false;
+    };
+    let Some(created_at) = event.get("created_at").and_then(|value| value.as_u64()) else {
+        return false;
+    };
+
+    conditions.split('&').all(|clause| {
+        if let Some(value) = clause.strip_prefix("kind=") {
+            value.parse::<u64>() == Ok(kind)
+        } else if let Some(value) = clause.strip_prefix("created_at<") {
+            value.parse::<u64>().is_ok_and(|bound| created_at < bound)
+        } else if let Some(value) = clause.strip_prefix("created_at>") {
+            value.parse::<u64>().is_ok_and(|bound| created_at > bound)
+        } else {
+            clause.is_empty()
+        }
+    })
+}
+
+fn owner_verification(event: &serde_json::Value, expected_owner: &str) -> &'static str {
+    let Some(agent_pubkey) = event
+        .get("pubkey")
+        .and_then(|value| value.as_str())
+        .and_then(|value| PublicKey::parse(value).ok())
+    else {
+        return "invalid_agent_pubkey";
+    };
+    let auth_tags = auth_tag_values(event);
+    let [auth_tag] = auth_tags.as_slice() else {
+        return if auth_tags.is_empty() {
+            "missing_auth"
+        } else {
+            "multiple_auth_tags"
+        };
+    };
+    let Ok(auth_tag_json) = serde_json::to_string(auth_tag) else {
+        return "invalid_auth";
+    };
+    match buzz_sdk::nip_oa::verify_auth_tag(&auth_tag_json, &agent_pubkey) {
+        Ok(owner) if owner.to_hex() != expected_owner => "owner_mismatch",
+        Ok(_) if !auth_conditions_apply(auth_tag, event) => "condition_mismatch",
+        Ok(_) => "verified",
+        Err(_) => "invalid_auth",
+    }
+}
+
+fn owner_scoped_profiles(
+    events: &[serde_json::Value],
+    pubkeys: &[String],
+    owner: &str,
+    effective_owner: &str,
+) -> Vec<serde_json::Value> {
+    pubkeys
+        .iter()
+        .map(|pubkey| {
+            let event = events.iter().find(|event| {
+                event.get("pubkey").and_then(|value| value.as_str()) == Some(pubkey.as_str())
+            });
+            let mut profile = event.map(profile_content).unwrap_or_default();
+            let verification = if PublicKey::parse(pubkey).is_err() {
+                "invalid_agent_pubkey"
+            } else {
+                event
+                    .map(|event| owner_verification(event, owner))
+                    .unwrap_or("missing_profile")
+            };
+            profile.insert("pubkey".to_string(), serde_json::json!(pubkey));
+            profile.insert("verification".to_string(), serde_json::json!(verification));
+            profile.insert(
+                "owned_by_me".to_string(),
+                serde_json::json!(verification == "verified" && owner == effective_owner),
+            );
+            if verification == "verified" {
+                profile.insert("owner_pubkey".to_string(), serde_json::json!(owner));
             }
-            Some(profile)
+            serde_json::Value::Object(profile)
         })
-        .collect();
+        .collect()
+}
+
+/// Search for users by display name. Owner-scoped searches resolve managed-agent records
+/// and verify their profiles; unscoped searches use NIP-50 and return [] if unsupported.
+async fn search_by_name(
+    client: &BuzzClient,
+    query: &str,
+    owner: Option<&str>,
+    format: &crate::OutputFormat,
+) -> Result<(), CliError> {
+    if query.trim().is_empty() {
+        return Err(CliError::Usage("--name cannot be empty".into()));
+    }
+
+    let owner = resolve_owner(client, owner)?;
+    let profiles = if let Some(owner) = owner {
+        let pubkeys = owned_agent_pubkeys_by_name(client, &owner, query).await?;
+        if pubkeys.is_empty() {
+            println!("[]");
+            return Ok(());
+        }
+        let valid_pubkeys: Vec<&String> = pubkeys
+            .iter()
+            .filter(|pubkey| PublicKey::parse(pubkey.as_str()).is_ok())
+            .collect();
+        let events = if valid_pubkeys.is_empty() {
+            Vec::new()
+        } else {
+            let filter = serde_json::json!({
+                "kinds": [0],
+                "authors": valid_pubkeys,
+                "limit": valid_pubkeys.len(),
+            });
+            let raw = client.query(&filter).await?;
+            serde_json::from_str(&raw)
+                .map_err(|e| CliError::Other(format!("failed to parse response: {e}")))?
+        };
+        owner_scoped_profiles(&events, &pubkeys, &owner, &effective_owner(client))
+    } else {
+        let filter = serde_json::json!({
+            "kinds": [0],
+            "search": query,
+            "limit": 100
+        });
+        let raw = client.query(&filter).await?;
+        let events: Vec<serde_json::Value> = serde_json::from_str(&raw)
+            .map_err(|e| CliError::Other(format!("failed to parse response: {e}")))?;
+        name_search_profiles(&events, query)
+    };
     let output = match format {
         crate::OutputFormat::Compact => {
             let compact: Vec<serde_json::Value> = profiles
                 .iter()
-                .map(|p| serde_json::json!({
-                    "pubkey": p.get("pubkey").cloned().unwrap_or_default(),
-                    "display_name": p.get("display_name").or_else(|| p.get("name")).cloned().unwrap_or_default(),
-                }))
+                .map(|p| {
+                    let mut value = serde_json::json!({
+                        "pubkey": p.get("pubkey").cloned().unwrap_or_default(),
+                        "display_name": p.get("display_name").or_else(|| p.get("name")).cloned().unwrap_or_default(),
+                    });
+                    if let Some(obj) = value.as_object_mut() {
+                        for field in ["owner_pubkey", "owned_by_me", "verification"] {
+                            if let Some(field_value) = p.get(field) {
+                                obj.insert(field.to_string(), field_value.clone());
+                            }
+                        }
+                    }
+                    value
+                })
                 .collect();
             serde_json::to_string(&compact).unwrap_or_default()
         }
@@ -327,9 +536,11 @@ pub async fn dispatch(
 ) -> Result<(), CliError> {
     use crate::UsersCmd;
     match cmd {
-        UsersCmd::Get { pubkeys, name } => {
-            cmd_get_users(client, &pubkeys, name.as_deref(), format).await
-        }
+        UsersCmd::Get {
+            pubkeys,
+            name,
+            owner,
+        } => cmd_get_users(client, &pubkeys, name.as_deref(), owner.as_deref(), format).await,
         UsersCmd::SetProfile {
             name,
             avatar,
@@ -362,9 +573,178 @@ pub async fn dispatch(
 
 #[cfg(test)]
 mod tests {
-    use super::presence_subject;
+    use super::{
+        owned_agent_pubkeys_from_events, owner_scoped_profiles, owner_verification,
+        presence_subject,
+    };
+    use nostr::Keys;
     use serde_json::json;
 
+    #[test]
+    fn owned_agent_lookup_matches_exact_name_case_insensitively() {
+        let events = vec![
+            json!({"content": r#"{"name":"Honey"}"#, "tags": [["d", "b"]]}),
+            json!({"content": r#"{"name":"Honeybee"}"#, "tags": [["d", "c"]]}),
+            json!({"content": r#"{"name":"honey"}"#, "tags": [["d", "a"]]}),
+        ];
+        assert_eq!(
+            owned_agent_pubkeys_from_events(&events, "Honey"),
+            vec!["a", "b"]
+        );
+    }
+
+    #[test]
+    fn owned_agent_lookup_ignores_malformed_events() {
+        let events = vec![
+            json!({"content": "not json", "tags": [["d", "a"]]}),
+            json!({"content": r#"{"name":"Honey"}"#, "tags": [["p", "b"]]}),
+        ];
+        assert!(owned_agent_pubkeys_from_events(&events, "Honey").is_empty());
+    }
+
+    fn profile_event(agent_keys: &Keys, auth_tags: Vec<serde_json::Value>) -> serde_json::Value {
+        json!({
+            "pubkey": agent_keys.public_key().to_hex(),
+            "kind": 0,
+            "created_at": 100,
+            "content": r#"{"display_name":"Renamed Honey"}"#,
+            "tags": auth_tags,
+        })
+    }
+
+    #[test]
+    fn owner_verification_requires_one_valid_auth_tag_for_requested_owner() {
+        let owner_keys = Keys::generate();
+        let agent_keys = Keys::generate();
+        let foreign_owner_keys = Keys::generate();
+        let valid_tag: serde_json::Value = serde_json::from_str(
+            &buzz_sdk::nip_oa::compute_auth_tag(&owner_keys, &agent_keys.public_key(), "kind=0")
+                .unwrap(),
+        )
+        .unwrap();
+        let foreign_tag: serde_json::Value = serde_json::from_str(
+            &buzz_sdk::nip_oa::compute_auth_tag(
+                &foreign_owner_keys,
+                &agent_keys.public_key(),
+                "kind=9",
+            )
+            .unwrap(),
+        )
+        .unwrap();
+
+        assert_eq!(
+            owner_verification(
+                &profile_event(&agent_keys, vec![valid_tag.clone()]),
+                &owner_keys.public_key().to_hex(),
+            ),
+            "verified"
+        );
+        assert_eq!(
+            owner_verification(
+                &profile_event(&agent_keys, vec![foreign_tag]),
+                &owner_keys.public_key().to_hex(),
+            ),
+            "owner_mismatch"
+        );
+        assert_eq!(
+            owner_verification(
+                &profile_event(&agent_keys, vec![]),
+                &owner_keys.public_key().to_hex()
+            ),
+            "missing_auth"
+        );
+        assert_eq!(
+            owner_verification(
+                &profile_event(&agent_keys, vec![valid_tag.clone(), valid_tag]),
+                &owner_keys.public_key().to_hex(),
+            ),
+            "multiple_auth_tags"
+        );
+        assert_eq!(
+            owner_verification(
+                &profile_event(
+                    &agent_keys,
+                    vec![json!([
+                        "auth",
+                        owner_keys.public_key().to_hex(),
+                        "kind=9",
+                        "0".repeat(128)
+                    ])],
+                ),
+                &owner_keys.public_key().to_hex(),
+            ),
+            "invalid_auth"
+        );
+    }
+
+    #[test]
+    fn owner_verification_requires_conditions_to_apply_to_profile_event() {
+        let owner_keys = Keys::generate();
+        let agent_keys = Keys::generate();
+        let verification = |conditions: &str| {
+            let auth_tag: serde_json::Value = serde_json::from_str(
+                &buzz_sdk::nip_oa::compute_auth_tag(
+                    &owner_keys,
+                    &agent_keys.public_key(),
+                    conditions,
+                )
+                .unwrap(),
+            )
+            .unwrap();
+            owner_verification(
+                &profile_event(&agent_keys, vec![auth_tag]),
+                &owner_keys.public_key().to_hex(),
+            )
+        };
+
+        assert_eq!(verification("kind=9"), "condition_mismatch");
+        assert_eq!(verification("created_at<100"), "condition_mismatch");
+        assert_eq!(verification("created_at>100"), "condition_mismatch");
+        assert_eq!(
+            verification("kind=0&created_at>99&created_at<101"),
+            "verified"
+        );
+    }
+
+    #[test]
+    fn owner_scoped_profiles_keep_drifted_and_missing_profiles_without_claiming_ownership() {
+        let owner_keys = Keys::generate();
+        let agent_keys = Keys::generate();
+        let missing_keys = Keys::generate();
+        let auth_tag: serde_json::Value = serde_json::from_str(
+            &buzz_sdk::nip_oa::compute_auth_tag(&owner_keys, &agent_keys.public_key(), "kind=0")
+                .unwrap(),
+        )
+        .unwrap();
+        let events = vec![profile_event(&agent_keys, vec![auth_tag])];
+        let pubkeys = vec![
+            agent_keys.public_key().to_hex(),
+            missing_keys.public_key().to_hex(),
+            "malformed".to_string(),
+        ];
+
+        let profiles = owner_scoped_profiles(
+            &events,
+            &pubkeys,
+            &owner_keys.public_key().to_hex(),
+            &owner_keys.public_key().to_hex(),
+        );
+
+        assert_eq!(profiles[0]["display_name"], "Renamed Honey");
+        assert_eq!(profiles[0]["verification"], "verified");
+        assert_eq!(profiles[0]["owned_by_me"], true);
+        assert_eq!(
+            profiles[0]["owner_pubkey"],
+            owner_keys.public_key().to_hex()
+        );
+        assert_eq!(profiles[1]["verification"], "missing_profile");
+        assert_eq!(profiles[1]["owned_by_me"], false);
+        assert!(profiles[1].get("owner_pubkey").is_none());
+        assert_eq!(profiles[2]["verification"], "invalid_agent_pubkey");
+        assert_eq!(profiles[2]["owned_by_me"], false);
+        assert!(profiles[2].get("owner_pubkey").is_none());
+    }
+
     #[test]
     fn presence_subject_uses_p_tag() {
         let event = json!({"pubkey": "relay", "tags": [["p", "user"]]});
diff --git a/crates/buzz-cli/src/lib.rs b/crates/buzz-cli/src/lib.rs
index 0b46734584..f745e7b280 100644
--- a/crates/buzz-cli/src/lib.rs
+++ b/crates/buzz-cli/src/lib.rs
@@ -82,11 +82,11 @@ struct Cli {
     relay: String,
 
     /// Nostr private key (hex or nsec). This is the CLI's identity.
-    #[arg(long, env = "BUZZ_PRIVATE_KEY")]
+    #[arg(long, env = "BUZZ_PRIVATE_KEY", hide_env_values = true)]
     private_key: Option<String>,
 
     /// NIP-OA auth tag JSON (owner attestation). Injected into every signed event.
-    #[arg(long, env = "BUZZ_AUTH_TAG")]
+    #[arg(long, env = "BUZZ_AUTH_TAG", hide_env_values = true)]
     auth_tag: Option<String>,
 
     /// Output format: 'json' (default, full fields) or 'compact' (reduced fields).
@@ -212,6 +212,9 @@ enum Cmd {
     /// Announce and discover git repositories (NIP-34)
     #[command(subcommand)]
     Repos(ReposCmd),
+    /// Create and manage multi-repo projects (NIP-MP)
+    #[command(subcommand)]
+    Projects(ProjectsCmd),
     /// Send, get, list, and set status on git patches (NIP-34)
     #[command(subcommand)]
     Patches(PatchesCmd),
@@ -369,6 +372,9 @@ pub enum MessagesCmd {
         /// Attach file(s) — uploads and includes as imeta tags
         #[arg(long = "file")]
         files: Vec<String>,
+        /// Pubkey to mention (hex or npub; repeatable). Supplying any explicit identity permits unresolved or ambiguous @Name text as presentation-only; uniquely resolved member names still notify.
+        #[arg(long = "mention")]
+        mentions: Vec<String>,
     },
     /// Send a code diff / patch to a channel
     SendDiff {
@@ -808,6 +814,9 @@ pub enum UsersCmd {
         /// Search by display name (case-insensitive substring match)
         #[arg(long = "name")]
         name: Option<String>,
+        /// Scope an exact-name agent lookup to its owner (`me`, hex, or npub)
+        #[arg(long = "owner", requires = "name")]
+        owner: Option<String>,
     },
     /// Update the current identity's profile
     #[command(name = "set-profile")]
@@ -1126,6 +1135,11 @@ pub enum ReposCmd {
         /// Preferred Nostr relay(s) for repo discovery — can be specified multiple times
         #[arg(long = "nostr-relay")]
         relays: Vec<String>,
+        /// Channel UUID to bind the repo to. The `buzz-channel` tag is the
+        /// git ACL: without it the relay 404s every clone/fetch/push until
+        /// the author runs `buzz repos bind` (issue #3527).
+        #[arg(long)]
+        channel: Option<String>,
     },
     /// Get a repository announcement
     Get {
@@ -1145,6 +1159,20 @@ pub enum ReposCmd {
         #[arg(long)]
         limit: Option<u32>,
     },
+    /// Bind (or rebind) one of your repositories to a channel.
+    ///
+    /// The `buzz-channel` tag on the announcement is the git ACL: the relay
+    /// authorizes clone/fetch/push by membership in the bound channel. A
+    /// repo announced without it (e.g. by a vanilla NIP-34 client) returns
+    /// 404 for everyone until its author binds it here.
+    Bind {
+        /// Repository identifier (d-tag).
+        #[arg(long)]
+        id: String,
+        /// Channel UUID to bind. Replaces any existing binding.
+        #[arg(long)]
+        channel: String,
+    },
     /// Manage branch and tag protection rules on one of your repositories.
     #[command(subcommand)]
     Protect(ReposProtectCmd),
@@ -1202,6 +1230,122 @@ pub enum RepoPushRole {
     Member,
 }
 
+/// Visibility of a multi-repo project listing.
+#[derive(Clone, Copy, Debug, clap::ValueEnum)]
+pub enum ProjectVisibility {
+    /// Project appears in public listings (default).
+    Listed,
+    /// Project is hidden from public listings.
+    Unlisted,
+}
+
+impl ProjectVisibility {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            ProjectVisibility::Listed => "listed",
+            ProjectVisibility::Unlisted => "unlisted",
+        }
+    }
+}
+
+#[derive(Subcommand)]
+pub enum ProjectsCmd {
+    /// Create a new multi-repo project (NIP-MP kind:30621)
+    ///
+    /// Requires at least one --repo. Fails with Conflict if the project already exists.
+    Create {
+        /// Project identifier (slug), up to 1024 bytes
+        slug: String,
+        /// Member repository coordinate: bare Buzz repo id (e.g. `buzz`) or full
+        /// `30617:<owner-hex>:<repo-d>` for cross-owner or colon-bearing repo ids.
+        /// At least one --repo is required.
+        #[arg(long = "repo", required = true)]
+        repo: Vec<String>,
+        /// Display name (≤256 bytes)
+        #[arg(long)]
+        name: Option<String>,
+        /// Description (≤2048 bytes)
+        #[arg(long)]
+        description: Option<String>,
+        /// Associated Buzz channel UUID
+        #[arg(long)]
+        channel: Option<String>,
+        /// Visibility: `listed` (default) or `unlisted`
+        #[arg(long)]
+        visibility: Option<ProjectVisibility>,
+    },
+    /// Get a project by slug
+    Get {
+        /// Project slug
+        slug: String,
+        /// Owner pubkey (64-char hex). Defaults to the current identity.
+        #[arg(long)]
+        owner: Option<String>,
+    },
+    /// List projects
+    List {
+        /// Owner pubkey (64-char hex). Defaults to the current identity.
+        #[arg(long)]
+        owner: Option<String>,
+        /// Maximum number of results
+        #[arg(long)]
+        limit: Option<u32>,
+    },
+    /// Add one or more member repositories to a project
+    #[command(name = "add-repo")]
+    AddRepo {
+        /// Project slug
+        slug: String,
+        /// Member repository coordinate (bare id or full `30617:<owner-hex>:<repo-d>`)
+        #[arg(long = "repo", required = true)]
+        repo: Vec<String>,
+    },
+    /// Remove one or more member repositories from a project
+    #[command(name = "remove-repo")]
+    RemoveRepo {
+        /// Project slug
+        slug: String,
+        /// Member repository coordinate to remove (bare id or full `30617:<owner-hex>:<repo-d>`)
+        #[arg(long = "repo", required = true)]
+        repo: Vec<String>,
+    },
+    /// Update project metadata (at least one setter or clearer required)
+    #[command(group = clap::ArgGroup::new("mutation").required(true).multiple(true))]
+    Update {
+        /// Project slug
+        slug: String,
+        /// Set the display name
+        #[arg(long, group = "mutation")]
+        name: Option<String>,
+        /// Remove the display name
+        #[arg(long, group = "mutation", conflicts_with = "name")]
+        clear_name: bool,
+        /// Set the description
+        #[arg(long, group = "mutation")]
+        description: Option<String>,
+        /// Remove the description
+        #[arg(long, group = "mutation", conflicts_with = "description")]
+        clear_description: bool,
+        /// Set the associated Buzz channel UUID
+        #[arg(long, group = "mutation")]
+        channel: Option<String>,
+        /// Remove the associated channel
+        #[arg(long, group = "mutation", conflicts_with = "channel")]
+        clear_channel: bool,
+        /// Set visibility: `listed` or `unlisted`
+        #[arg(long, group = "mutation")]
+        visibility: Option<ProjectVisibility>,
+        /// Remove the visibility tag (absence defaults to `listed`)
+        #[arg(long, group = "mutation", conflicts_with = "visibility")]
+        clear_visibility: bool,
+    },
+    /// Delete a project (head-based tombstone; verified after submit)
+    Delete {
+        /// Project slug
+        slug: String,
+    },
+}
+
 #[derive(Subcommand)]
 pub enum PatchesCmd {
     /// Send a git patch (NIP-34 kind:1617)
@@ -1743,6 +1887,41 @@ pub enum ModerationCmd {
     },
 }
 
+/// Normalize hand-authored `BUZZ_AUTH_TAG` input to strict JSON.
+///
+/// `.env` files and shell exports sometimes carry the tag in the unquoted
+/// shorthand `[auth,<hex>,<conditions>,<hex>]` (quotes dropped by hand).
+/// When the input is not valid JSON but is bracket-delimited, rewrite it as
+/// a JSON array of the comma-separated fields (an empty field `,,` becomes
+/// `""`, matching the canonical form `["auth","hex","","hex"]`).
+///
+/// This is presentation-layer leniency at the configuration edge only: the
+/// output is always fed through the SDK's strict `parse_auth_tag` /
+/// `verify_auth_tag`, which enforce structure, hex, the conditions grammar,
+/// and the BIP-340 signature. Inputs that are already valid JSON — or not
+/// recognizable as the shorthand — are returned unchanged so the strict
+/// parser reports the error on the original bytes.
+fn normalize_auth_tag_input(input: &str) -> String {
+    let trimmed = input.trim();
+    if serde_json::from_str::<serde_json::Value>(trimmed).is_ok() {
+        return trimmed.to_owned();
+    }
+    if trimmed.starts_with('[') && trimmed.ends_with(']') {
+        let fields: Vec<&str> = trimmed[1..trimmed.len() - 1]
+            .split(',')
+            .map(str::trim)
+            .collect();
+        // Only a plausible 4-field auth tag is rewritten; anything else is
+        // passed through untouched for the strict parser to reject with an
+        // error that references the caller's original input.
+        if fields.len() == 4 && !fields.iter().any(|f| f.contains('"')) {
+            // serde_json cannot fail serializing a Vec<&str>.
+            return serde_json::to_string(&fields).expect("string array serializes");
+        }
+    }
+    trimmed.to_owned()
+}
+
 async fn run(cli: Cli) -> Result<(), CliError> {
     let relay_url = client::normalize_relay_url(&cli.relay);
 
@@ -1763,17 +1942,28 @@ async fn run(cli: Cli) -> Result<(), CliError> {
         .map_err(|e| CliError::Key(format!("invalid BUZZ_PRIVATE_KEY: {e}")))?;
 
     // NIP-OA: parse and verify the auth tag if provided.
+    //
+    // `BUZZ_AUTH_TAG` is hand-authored configuration, so the unquoted raw
+    // shorthand `[auth,hex,,hex]` is normalized to JSON here — at this input
+    // edge only. The SDK grammar and the `x-auth-tag` wire format stay strict
+    // JSON; all validation and signature verification happen on the strict
+    // path below, unchanged.
     let (auth_tag, auth_tag_json) = match cli.auth_tag {
-        Some(ref json) if !json.is_empty() => {
-            let tag = buzz_sdk::nip_oa::parse_auth_tag(json)
+        Some(ref input) if !input.is_empty() => {
+            let json = normalize_auth_tag_input(input);
+            let tag = buzz_sdk::nip_oa::parse_auth_tag(&json)
                 .map_err(|e| CliError::Auth(format!("BUZZ_AUTH_TAG is malformed: {e}")))?;
-            buzz_sdk::nip_oa::verify_auth_tag(json, &keys.public_key()).map_err(|e| {
+            buzz_sdk::nip_oa::verify_auth_tag(&json, &keys.public_key()).map_err(|e| {
                 CliError::Auth(format!(
                     "BUZZ_AUTH_TAG verification failed for pubkey {}: {e}",
                     keys.public_key().to_hex()
                 ))
             })?;
-            (Some(tag), Some(json.clone()))
+            // Canonical wire form derives from the parsed-and-verified tag
+            // (same shape as buzz-acp's RestClient), never from raw input.
+            let canonical = serde_json::to_string(tag.as_slice())
+                .map_err(|e| CliError::Auth(format!("BUZZ_AUTH_TAG serialization failed: {e}")))?;
+            (Some(tag), Some(canonical))
         }
         _ => (None, None),
     };
@@ -1794,6 +1984,7 @@ async fn run(cli: Cli) -> Result<(), CliError> {
         Cmd::Social(sub) => commands::social::dispatch(sub, &client).await,
         Cmd::Notes(sub) => commands::notes::dispatch(sub, &client).await,
         Cmd::Repos(sub) => commands::repos::dispatch(sub, &client).await,
+        Cmd::Projects(sub) => commands::projects::dispatch(sub, &client).await,
         Cmd::Patches(sub) => commands::patches::dispatch(sub, &client).await,
         Cmd::Issues(sub) => commands::issues::dispatch(sub, &client).await,
         Cmd::Pr(sub) => commands::pr::dispatch(sub, &client).await,
@@ -1810,6 +2001,51 @@ mod tests {
     use super::*;
     use clap::CommandFactory;
 
+    /// Raw shorthand `[auth,hex,,hex]` normalizes to strict JSON; the empty
+    /// conditions field becomes `""`.
+    #[test]
+    fn normalize_auth_tag_raw_shorthand() {
+        let owner = "a".repeat(64);
+        let sig = "b".repeat(128);
+
+        let raw = format!("[auth,{owner},,{sig}]");
+        let json = normalize_auth_tag_input(&raw);
+        let parsed: Vec<String> = serde_json::from_str(&json).expect("output must be JSON");
+        assert_eq!(parsed, vec!["auth", &owner, "", &sig]);
+
+        // With conditions and surrounding whitespace (shell/.env artifacts).
+        let raw = format!("  [auth, {owner} , kind=9, {sig}]  \n");
+        let json = normalize_auth_tag_input(&raw);
+        let parsed: Vec<String> = serde_json::from_str(&json).expect("output must be JSON");
+        assert_eq!(parsed, vec!["auth", &owner, "kind=9", &sig]);
+    }
+
+    /// Valid JSON input passes through byte-identical (modulo outer trim) —
+    /// the normalizer must never rewrite well-formed input.
+    #[test]
+    fn normalize_auth_tag_json_passthrough() {
+        let owner = "a".repeat(64);
+        let sig = "b".repeat(128);
+        let json_in = serde_json::json!(["auth", owner, "kind=9", sig]).to_string();
+        assert_eq!(normalize_auth_tag_input(&json_in), json_in);
+    }
+
+    /// Inputs that are neither JSON nor a plausible 4-field shorthand pass
+    /// through unchanged, so the strict parser rejects the original bytes.
+    #[test]
+    fn normalize_auth_tag_leaves_garbage_untouched() {
+        for garbage in [
+            "not a tag",
+            "[auth,too,few]",
+            "[a,b,c,d,e]",
+            r#"[auth,"quoted",x,y]"#, // quote chars => not the shorthand
+            "[]",
+            "{\"auth\":1}",
+        ] {
+            assert_eq!(normalize_auth_tag_input(garbage), garbage.trim());
+        }
+    }
+
     /// Smoke test: CLI definition is valid and parseable.
     #[test]
     fn cli_definition_is_valid() {
@@ -1858,6 +2094,7 @@ mod tests {
             "pack",
             "patches",
             "pr",
+            "projects",
             "reactions",
             "repos",
             "social",
@@ -1988,7 +2225,7 @@ mod tests {
         );
         assert_eq!(
             names(&cmd, "repos"),
-            vec!["create", "get", "list", "protect"]
+            vec!["bind", "create", "get", "list", "protect"]
         );
         let repos = cmd
             .get_subcommands()
@@ -2013,6 +2250,18 @@ mod tests {
             names(&cmd, "patches"),
             vec!["get", "list", "send", "status"]
         );
+        assert_eq!(
+            names(&cmd, "projects"),
+            vec![
+                "add-repo",
+                "create",
+                "delete",
+                "get",
+                "list",
+                "remove-repo",
+                "update"
+            ]
+        );
         assert_eq!(
             names(&cmd, "issues"),
             vec!["create", "get", "list", "status"]
@@ -2050,8 +2299,9 @@ mod tests {
             ("pack", 2),
             ("patches", 4),
             ("pr", 5),
+            ("projects", 7),
             ("reactions", 3),
-            ("repos", 4),
+            ("repos", 5),
             ("social", 7),
             ("upload", 1),
             ("users", 5),
@@ -2075,4 +2325,153 @@ mod tests {
             );
         }
     }
+
+    /// Collect all args (recursing into subcommands) whose env var name looks
+    /// like a credential but does NOT have `hide_env_values` set.
+    fn collect_unhidden_secret_args(cmd: &clap::Command) -> Vec<(String, String)> {
+        const SECRET_PATTERNS: &[&str] = &["KEY", "SECRET", "TOKEN", "PASSWORD", "CRED", "AUTH"];
+
+        let mut violations: Vec<(String, String)> = Vec::new();
+
+        for arg in cmd.get_arguments() {
+            if let Some(env_key) = arg.get_env() {
+                let env_name = env_key.to_string_lossy().to_uppercase();
+                let is_secret = SECRET_PATTERNS.iter().any(|pat| env_name.contains(pat));
+                if is_secret && !arg.is_hide_env_values_set() {
+                    violations.push((cmd.get_name().to_string(), env_name));
+                }
+            }
+        }
+
+        for sub in cmd.get_subcommands() {
+            violations.extend(collect_unhidden_secret_args(sub));
+        }
+
+        violations
+    }
+
+    /// Every arg whose env var name contains KEY/SECRET/TOKEN/PASSWORD/CRED/AUTH
+    /// must set `hide_env_values = true` to prevent credential leakage in --help.
+    #[test]
+    fn secret_env_args_hide_their_values_in_help() {
+        let cmd = Cli::command();
+        let violations = collect_unhidden_secret_args(&cmd);
+        assert!(
+            violations.is_empty(),
+            "Found secret-bearing env args without hide_env_values=true. \
+             Add `hide_env_values = true` to each:\n{}",
+            violations
+                .iter()
+                .map(|(cmd, env)| format!("  command={cmd:?} env={env:?}"))
+                .collect::<Vec<_>>()
+                .join("\n")
+        );
+    }
+
+    // ── projects update mutation group ────────────────────────────────────────
+
+    /// Multiple independent fields must be accepted in the same invocation.
+    #[test]
+    fn projects_update_multi_field_is_accepted() {
+        assert!(
+            Cli::try_parse_from([
+                "buzz",
+                "projects",
+                "update",
+                "my-slug",
+                "--name",
+                "X",
+                "--description",
+                "Y",
+            ])
+            .is_ok(),
+            "--name and --description together must be accepted"
+        );
+    }
+
+    /// A setter for one field and a clearer for a different field must be accepted.
+    #[test]
+    fn projects_update_setter_with_other_clearer_is_accepted() {
+        assert!(
+            Cli::try_parse_from([
+                "buzz",
+                "projects",
+                "update",
+                "my-slug",
+                "--name",
+                "X",
+                "--clear-description",
+            ])
+            .is_ok(),
+            "--name with --clear-description must be accepted"
+        );
+    }
+
+    /// A setter and its own clearer are mutually exclusive — clap must reject this.
+    #[test]
+    fn projects_update_setter_with_own_clearer_is_rejected() {
+        assert!(
+            Cli::try_parse_from([
+                "buzz",
+                "projects",
+                "update",
+                "my-slug",
+                "--name",
+                "X",
+                "--clear-name",
+            ])
+            .is_err(),
+            "--name and --clear-name together must be rejected by clap"
+        );
+    }
+
+    /// Providing no mutation options at all must be rejected by clap (required group).
+    #[test]
+    fn projects_update_no_mutation_is_rejected_by_clap() {
+        // Without credentials, a valid parse would reach authentication and fail
+        // with auth_error — but a clap-level rejection happens before any I/O.
+        // We verify it's a clap error (not just any error) by checking the error
+        // kind is not a runtime/auth failure — Cli::try_parse_from returns Err
+        // immediately for argument violations.
+        assert!(
+            Cli::try_parse_from(["buzz", "projects", "update", "my-slug"]).is_err(),
+            "update with no setters or clearers must be rejected at parse time"
+        );
+    }
+
+    /// An unrecognised visibility token must be rejected by clap before any I/O.
+    #[test]
+    fn projects_create_invalid_visibility_is_rejected_by_clap() {
+        assert!(
+            Cli::try_parse_from([
+                "buzz",
+                "projects",
+                "create",
+                "my-slug",
+                "--repo",
+                "buzz",
+                "--visibility",
+                "chartreuse",
+            ])
+            .is_err(),
+            "--visibility chartreuse must be rejected at parse time"
+        );
+    }
+
+    /// An unrecognised visibility token on update must be rejected by clap before any I/O.
+    #[test]
+    fn projects_update_invalid_visibility_is_rejected_by_clap() {
+        assert!(
+            Cli::try_parse_from([
+                "buzz",
+                "projects",
+                "update",
+                "my-slug",
+                "--visibility",
+                "chartreuse",
+            ])
+            .is_err(),
+            "--visibility chartreuse on update must be rejected at parse time"
+        );
+    }
 }
diff --git a/crates/buzz-core/src/git_perms.rs b/crates/buzz-core/src/git_perms.rs
index 53acd704b9..391781163b 100644
--- a/crates/buzz-core/src/git_perms.rs
+++ b/crates/buzz-core/src/git_perms.rs
@@ -15,6 +15,30 @@
 use crate::channel::MemberRole;
 use std::fmt;
 
+/// Machine-readable token prefixing the push-policy denial for a kind:30617
+/// announcement with no `buzz-channel` binding.
+///
+/// This is a **declared cross-component contract**, not a log string. Known
+/// consumers switch on it:
+/// - relay `api/git/policy.rs` — produces [`GIT_NO_CHANNEL_BINDING_BODY`]
+/// - desktop `src-tauri/commands/project_git_workflow.rs` — merge-failure
+///   classifier maps it to a structured `no_channel_binding` error code
+/// - desktop `src/features/projects/lib/projectBranchErrors.ts` — dialog
+///   copy matcher (TS re-types the literal; its test pins the value)
+pub const GIT_NO_CHANNEL_BINDING_TOKEN: &str = "no_channel_binding";
+
+/// Full push-policy denial body for an unbound repository.
+///
+/// Format: `<token>: <legacy phrase>`. The trailing prose deliberately
+/// repeats the token's meaning because desktops already in the field match
+/// the exact phrase `no channel binding` (spaces, not underscores — the
+/// token alone would NOT satisfy that matcher). Do not "fix" the redundancy:
+/// removing the phrase silently breaks every shipped desktop, and removing
+/// the token breaks the structured consumers above. A relay-side test pins
+/// both matchers.
+pub const GIT_NO_CHANNEL_BINDING_BODY: &str =
+    "no_channel_binding: repository has no channel binding";
+
 /// Maximum number of `buzz-protect` tags per repo.
 pub const MAX_PROTECTION_RULES: usize = 50;
 /// Maximum character length of a ref pattern.
diff --git a/crates/buzz-core/src/kind.rs b/crates/buzz-core/src/kind.rs
index afec52305a..b1be7c5038 100644
--- a/crates/buzz-core/src/kind.rs
+++ b/crates/buzz-core/src/kind.rs
@@ -182,29 +182,43 @@ pub const P_GATED_KINDS: &[u32] = &[
 /// or more than one `shared` tag) so no ambiguous heads can exist.
 pub const KIND_PERSONA: u32 = 30175;
 
-/// Returns `true` if `kind` uses the author-only-unless-shared read model
-/// (currently only `KIND_PERSONA` / 30175).
+/// Kinds that use the author-only-unless-shared read model.
 ///
 /// Events of these kinds may only be delivered to foreign readers when the
-/// event carries exactly `["shared", "true"]`. Used by all relay read
-/// chokepoints: REQ historical delivery, live fan-out, COUNT fallback,
-/// and the `ids`-lookup result gate.
-pub fn is_persona_shared_kind(kind: u32) -> bool {
-    kind == KIND_PERSONA
+/// event carries exactly `["shared", "true"]`. Every relay read chokepoint
+/// consults this set: REQ historical delivery, live fan-out, COUNT fallback,
+/// the `ids`-lookup result gate, both HTTP surfaces, and the pre-`LIMIT` SQL
+/// visibility pushdown in `buzz-db`.
+///
+/// Membership is a privacy decision, not a convenience: adding a kind here
+/// makes its events invisible to foreign readers until their author opts in,
+/// and the opt-in must be a `shared` TAG (not a content field) so that
+/// toggling it leaves content bytes — and any content hash derived from them —
+/// unchanged.
+///
+/// `KIND_TEAM` (30176) is deliberately NOT a member. Its writers never emit
+/// `shared`, so catalog opt-in semantics do not describe it; it needs
+/// owner-private read semantics instead, which is a separate change.
+pub const SHARED_GATED_KINDS: &[u32] = &[KIND_PERSONA, KIND_TEAM_CATALOG];
+
+/// Returns `true` if `kind` uses the author-only-unless-shared read model
+/// (see [`SHARED_GATED_KINDS`]).
+pub fn is_shared_gated_kind(kind: u32) -> bool {
+    SHARED_GATED_KINDS.contains(&kind)
 }
 
-/// Returns `true` if the event is a persona-shared-catalog kind AND the
-/// requester is NOT the author AND the event does NOT carry `["shared",
-/// "true"]`. All three conditions must hold to withhold the event.
+/// Returns `true` if the event is a shared-gated kind AND the requester is NOT
+/// the author AND the event does NOT carry `["shared", "true"]`. All three
+/// conditions must hold to withhold the event.
 ///
 /// This is the per-event gate used by REQ historical delivery, live fan-out,
 /// and COUNT fallback paths. It is intentionally independent of
-/// `is_author_only_event` — persona events with `["shared", "true"]` MUST
+/// `is_author_only_event` — shared-gated events with `["shared", "true"]` MUST
 /// reach foreign readers; stripping them at the author-only layer would break
 /// the catalog query.
-pub fn is_unshared_persona_event(event: &nostr::Event, requester_pubkey_bytes: &[u8]) -> bool {
+pub fn is_unshared_gated_event(event: &nostr::Event, requester_pubkey_bytes: &[u8]) -> bool {
     let kind = event.kind.as_u16() as u32;
-    if !is_persona_shared_kind(kind) {
+    if !is_shared_gated_kind(kind) {
         return false;
     }
     // Author reads are always allowed.
@@ -212,18 +226,23 @@ pub fn is_unshared_persona_event(event: &nostr::Event, requester_pubkey_bytes: &
         return false;
     }
     // Foreign reader: allowed only if the event is explicitly shared.
-    !persona_event_is_shared(event)
+    !event_is_shared(event)
 }
 
 /// Returns `true` if the event carries exactly one `["shared", "true"]` tag.
 ///
+/// Kind-agnostic: this is purely the tag-shape predicate. The kind check lives
+/// in [`is_shared_gated_kind`], so callers that need "is this event shared"
+/// for a kind they already know (e.g. a client deciding whether its own
+/// retained head is published) can use this directly.
+///
 /// Requires the tag to have exactly two elements so that a three-element shape
 /// like `["shared","true","extra"]` is NOT treated as shared. Ingest enforces
 /// the same exact shape, so a well-stored event either has no `shared` tag
 /// (author-only) or exactly one with precisely two elements and value `"true"`
 /// (community-readable). This helper fails closed on any non-exact shape
 /// independently of ingest guarantees.
-pub fn persona_event_is_shared(event: &nostr::Event) -> bool {
+pub fn event_is_shared(event: &nostr::Event) -> bool {
     let mut count = 0usize;
     for tag in event.tags.iter() {
         let parts = tag.as_slice();
@@ -258,6 +277,34 @@ pub const KIND_TEAM: u32 = 30176;
 /// since these events are world-readable on the relay.
 pub const KIND_MANAGED_AGENT: u32 = 30177;
 
+/// NIP-AP: Team Catalog projection (parameterized replaceable, owner-authored).
+///
+/// The shareable projection of a team, addressed by `(pubkey, kind, d_tag)`
+/// where `d_tag` is the team's stable id. Content is a versioned JSON body
+/// carrying sanitized team fields plus ordered, EMBEDDED member definition
+/// projections.
+///
+/// # Why this is not a `shared` tag on [`KIND_TEAM`]
+///
+/// A team's members live in kind 30175 events that are author-only unless
+/// individually shared, so a foreign reader of a shared team could never
+/// hydrate its members. This kind therefore embeds the member projections
+/// rather than referencing them: the share is atomic, it covers built-in
+/// members that have no 30175 head at all, it is immune to local-id/d-tag
+/// divergence, and an unshared 30175 stays private. Kind 30176's wire body is
+/// untouched, so device sync keeps its contract.
+///
+/// # Access control
+///
+/// Member of [`SHARED_GATED_KINDS`]: author-only unless the event carries
+/// exactly `["shared", "true"]`. Ingest additionally requires exactly one
+/// non-empty, bounded `d` tag — generic NIP-33 storage maps a missing `d` to
+/// the empty coordinate, which would collapse every team into one slot.
+///
+/// Content carries only sanitized fields: no env vars, no `respond_to`
+/// allowlist pubkeys, no source or local ids, no filesystem paths, no secrets.
+pub const KIND_TEAM_CATALOG: u32 = 30178;
+
 // NIP-56 reporting
 /// NIP-56: Report an event, pubkey, or blob to relay moderators (kind:1984).
 ///
@@ -562,6 +609,15 @@ pub const KIND_GIT_STATUS_CLOSED: u32 = 1632;
 /// NIP-34: Status — Draft.
 pub const KIND_GIT_STATUS_DRAFT: u32 = 1633;
 
+/// NIP-MP: Multi-repo project — a named grouping of `kind:30617` repository
+/// announcements (parameterized replaceable, d=project slug).
+///
+/// Members are `a` tags holding `30617:<owner-hex>:<repo-d>` coordinates, so one
+/// project may span repositories owned by different pubkeys. The signer gains no
+/// authority over any member: push policy reads the repository's own
+/// announcement, never a project. See `docs/nips/NIP-MP.md`.
+pub const KIND_PROJECT: u32 = 30621;
+
 /// All registered kind constants — used for duplicate detection and iteration.
 pub const ALL_KINDS: &[u32] = &[
     KIND_PROFILE,
@@ -586,6 +642,7 @@ pub const ALL_KINDS: &[u32] = &[
     KIND_PERSONA,
     KIND_TEAM,
     KIND_MANAGED_AGENT,
+    KIND_TEAM_CATALOG,
     KIND_REPORT,
     KIND_PRODUCT_FEEDBACK,
     KIND_NIP29_PUT_USER,
@@ -691,6 +748,7 @@ pub const ALL_KINDS: &[u32] = &[
     KIND_GIT_STATUS_MERGED,
     KIND_GIT_STATUS_CLOSED,
     KIND_GIT_STATUS_DRAFT,
+    KIND_PROJECT,
 ];
 
 /// Returns `true` if `kind` is in the ephemeral range (20000–29999).
@@ -784,9 +842,11 @@ const _: () = assert!(is_replaceable(KIND_AGENT_PROFILE)); // 10100 ∈ 10000–
 const _: () = assert!(is_parameterized_replaceable(KIND_PERSONA)); // 30175 ∈ 30000–39999
 const _: () = assert!(is_parameterized_replaceable(KIND_TEAM)); // 30176 ∈ 30000–39999
 const _: () = assert!(is_parameterized_replaceable(KIND_MANAGED_AGENT)); // 30177 ∈ 30000–39999
+const _: () = assert!(is_parameterized_replaceable(KIND_TEAM_CATALOG)); // 30178 ∈ 30000–39999
 const _: () = assert!(is_parameterized_replaceable(KIND_WORKFLOW_DEF)); // 30620 ∈ 30000–39999
 const _: () = assert!(is_parameterized_replaceable(KIND_EVENT_REMINDER)); // 30300 ∈ 30000–39999
 const _: () = assert!(is_parameterized_replaceable(KIND_DM_VISIBILITY)); // 30622 ∈ 30000–39999
+const _: () = assert!(is_parameterized_replaceable(KIND_PROJECT)); // 30621 ∈ 30000–39999
 const _: () = assert!(is_parameterized_replaceable(KIND_THREAD_SUMMARY)); // 39005 ∈ 30000–39999
 const _: () = assert!(is_parameterized_replaceable(KIND_WINDOW_BOUNDS)); // 39006 ∈ 30000–39999
 
@@ -858,64 +918,68 @@ mod tests {
         }
     }
 
-    // ── persona_event_is_shared / is_unshared_persona_event ──────────────
+    // ── event_is_shared / is_unshared_gated_event ────────────────────────
 
-    fn make_persona_event(tags: &[&[&str]]) -> nostr::Event {
+    fn make_event_of_kind(kind: u32, tags: &[&[&str]]) -> nostr::Event {
         use nostr::{EventBuilder, Keys, Kind, Tag};
         let keys = Keys::generate();
         let tag_vec: Vec<Tag> = tags
             .iter()
             .map(|parts| Tag::parse(parts.iter().copied()).unwrap())
             .collect();
-        EventBuilder::new(Kind::Custom(KIND_PERSONA as u16), "")
+        EventBuilder::new(Kind::Custom(kind as u16), "")
             .tags(tag_vec)
             .sign_with_keys(&keys)
             .unwrap()
     }
 
+    fn make_persona_event(tags: &[&[&str]]) -> nostr::Event {
+        make_event_of_kind(KIND_PERSONA, tags)
+    }
+
     #[test]
-    fn persona_event_is_shared_true_tag() {
+    fn event_is_shared_true_tag() {
         let ev = make_persona_event(&[&["d", "my-agent"], &["shared", "true"]]);
-        assert!(persona_event_is_shared(&ev));
+        assert!(event_is_shared(&ev));
     }
 
     #[test]
-    fn persona_event_is_shared_no_tag() {
+    fn event_is_shared_no_tag() {
         let ev = make_persona_event(&[&["d", "my-agent"]]);
-        assert!(!persona_event_is_shared(&ev));
+        assert!(!event_is_shared(&ev));
     }
 
     #[test]
-    fn persona_event_is_shared_wrong_value() {
+    fn event_is_shared_wrong_value() {
         let ev = make_persona_event(&[&["d", "my-agent"], &["shared", "false"]]);
-        assert!(!persona_event_is_shared(&ev));
+        assert!(!event_is_shared(&ev));
     }
 
     #[test]
-    fn persona_event_is_shared_duplicate_shared_tags() {
+    fn event_is_shared_duplicate_shared_tags() {
         // Two ["shared","true"] tags → ambiguous; not considered shared.
         let ev =
             make_persona_event(&[&["d", "my-agent"], &["shared", "true"], &["shared", "true"]]);
-        assert!(!persona_event_is_shared(&ev));
+        assert!(!event_is_shared(&ev));
     }
 
     #[test]
-    fn persona_event_is_shared_three_element_tag_not_shared() {
+    fn event_is_shared_three_element_tag_not_shared() {
         // ["shared","true","extra"] — three elements — must NOT be treated as shared.
         // The helper fails closed on any non-exact shape independently of ingest guarantees.
         let ev = make_persona_event(&[&["d", "my-agent"], &["shared", "true", "extra"]]);
-        assert!(!persona_event_is_shared(&ev));
+        assert!(!event_is_shared(&ev));
     }
 
     #[test]
-    fn persona_event_is_shared_one_element_tag_not_shared() {
+    fn event_is_shared_one_element_tag_not_shared() {
         // ["shared"] — only one element — not shared (fails the == 2 check).
         let ev = make_persona_event(&[&["d", "my-agent"], &["shared"]]);
-        assert!(!persona_event_is_shared(&ev));
+        assert!(!event_is_shared(&ev));
     }
 
     #[test]
-    fn is_unshared_persona_event_author_always_allowed() {
+    fn is_unshared_gated_event_author_always_allowed() {
         // Even without a shared tag the event author should not be blocked.
         use nostr::{EventBuilder, Keys, Kind, Tag};
         let keys = Keys::generate();
@@ -924,32 +988,83 @@ mod tests {
             .sign_with_keys(&keys)
             .unwrap();
         let author_bytes = keys.public_key().to_bytes();
-        assert!(!is_unshared_persona_event(&ev, &author_bytes));
+        assert!(!is_unshared_gated_event(&ev, &author_bytes));
     }
 
     #[test]
-    fn is_unshared_persona_event_foreign_no_tag() {
+    fn is_unshared_gated_event_foreign_no_tag() {
         let ev = make_persona_event(&[&["d", "my-agent"]]);
         let foreign = [0u8; 32];
-        assert!(is_unshared_persona_event(&ev, &foreign));
+        assert!(is_unshared_gated_event(&ev, &foreign));
     }
 
     #[test]
-    fn is_unshared_persona_event_foreign_shared_tag() {
+    fn is_unshared_gated_event_foreign_shared_tag() {
         let ev = make_persona_event(&[&["d", "my-agent"], &["shared", "true"]]);
         let foreign = [0u8; 32];
-        assert!(!is_unshared_persona_event(&ev, &foreign));
+        assert!(!is_unshared_gated_event(&ev, &foreign));
     }
 
     #[test]
-    fn is_unshared_persona_event_non_persona_kind_passthrough() {
+    fn is_unshared_gated_event_ungated_kind_passthrough() {
         use nostr::{EventBuilder, Keys, Kind};
         let keys = Keys::generate();
         let ev = EventBuilder::new(Kind::Custom(KIND_TEAM as u16), "")
             .sign_with_keys(&keys)
             .unwrap();
         let foreign = [0u8; 32];
-        // Non-persona kinds are never blocked by this gate.
-        assert!(!is_unshared_persona_event(&ev, &foreign));
+        // Kinds outside SHARED_GATED_KINDS are never blocked by this gate.
+        assert!(!is_unshared_gated_event(&ev, &foreign));
+    }
+
+    #[test]
+    fn is_unshared_gated_event_team_catalog_foreign_no_tag() {
+        // The gate must cover 30178 identically to 30175 — an unshared team
+        // catalog projection is author-only.
+        let ev = make_event_of_kind(KIND_TEAM_CATALOG, &[&["d", "team-1"]]);
+        let foreign = [0u8; 32];
+        assert!(is_unshared_gated_event(&ev, &foreign));
+    }
+
+    #[test]
+    fn is_unshared_gated_event_team_catalog_foreign_shared_tag() {
+        let ev = make_event_of_kind(KIND_TEAM_CATALOG, &[&["d", "team-1"], &["shared", "true"]]);
+        let foreign = [0u8; 32];
+        assert!(!is_unshared_gated_event(&ev, &foreign));
+    }
+
+    #[test]
+    fn is_unshared_gated_event_team_catalog_author_always_allowed() {
+        use nostr::{EventBuilder, Keys, Kind, Tag};
+        let keys = Keys::generate();
+        let ev = EventBuilder::new(Kind::Custom(KIND_TEAM_CATALOG as u16), "")
+            .tags(vec![Tag::parse(["d", "team-1"]).unwrap()])
+            .sign_with_keys(&keys)
+            .unwrap();
+        let author_bytes = keys.public_key().to_bytes();
+        assert!(!is_unshared_gated_event(&ev, &author_bytes));
+    }
+
+    #[test]
+    fn is_unshared_gated_event_team_catalog_malformed_shared_tag_fails_closed() {
+        // A three-element `shared` tag can never be stored (ingest rejects it),
+        // but the read gate must independently treat it as NOT shared.
+        let ev = make_event_of_kind(
+            KIND_TEAM_CATALOG,
+            &[&["d", "team-1"], &["shared", "true", "extra"]],
+        );
+        let foreign = [0u8; 32];
+        assert!(is_unshared_gated_event(&ev, &foreign));
+    }
+
+    #[test]
+    fn shared_gated_kinds_membership() {
+        assert!(is_shared_gated_kind(KIND_PERSONA));
+        assert!(is_shared_gated_kind(KIND_TEAM_CATALOG));
+        // 30176 has owner-private semantics, not catalog opt-in semantics: its
+        // writers never emit `shared`, so gating it here would hide every team
+        // from its own delegated readers.
+        assert!(!is_shared_gated_kind(KIND_TEAM));
+        assert!(!is_shared_gated_kind(KIND_MANAGED_AGENT));
     }
 }
diff --git a/crates/buzz-db/Cargo.toml b/crates/buzz-db/Cargo.toml
index 01f1e172b6..6f76a11bc1 100644
--- a/crates/buzz-db/Cargo.toml
+++ b/crates/buzz-db/Cargo.toml
@@ -21,6 +21,8 @@ tracing     = { workspace = true }
 thiserror   = { workspace = true }
 nostr       = { workspace = true }
 rand        = { workspace = true }
+metrics     = { workspace = true }
 
 [dev-dependencies]
 tokio = { workspace = true }
+metrics-util = { workspace = true }
diff --git a/crates/buzz-db/src/event.rs b/crates/buzz-db/src/event.rs
index 520fd1536f..a670a13402 100644
--- a/crates/buzz-db/src/event.rs
+++ b/crates/buzz-db/src/event.rs
@@ -11,12 +11,19 @@ use uuid::Uuid;
 
 use buzz_core::kind::{
     event_kind_i32, is_ephemeral, is_parameterized_replaceable, KIND_AUTH, KIND_EVENT_REMINDER,
-    KIND_HUDDLE_STARTED,
+    KIND_HUDDLE_STARTED, SHARED_GATED_KINDS,
 };
 use buzz_core::{CommunityId, StoredEvent};
 
 use crate::error::{DbError, Result};
 
+/// Largest page [`query_events`] will return when [`EventQuery::max_limit`] is
+/// unset — the effective ceiling on any client-requested `limit`.
+///
+/// This is the value the relay advertises as NIP-11 `limitation.max_limit`, so
+/// the advertised ceiling and the enforced one cannot drift.
+pub const DEFAULT_MAX_PAGE_LIMIT: i64 = 1_000;
+
 /// Optional filters for [`query_events`].
 #[derive(Debug, Clone)]
 pub struct EventQuery {
@@ -67,17 +74,19 @@ pub struct EventQuery {
     /// channel-less global events. Applied before SQL `LIMIT` so access-filtered
     /// historical pages have exact exhaustion semantics.
     pub channel_ids: Option<Vec<uuid::Uuid>>,
-    /// Override the default limit clamp (1000). Used by COUNT fallback path
-    /// which needs to fetch all matching events for post-filter counting.
-    /// When None, the default clamp of 1000 applies.
+    /// Override the default page clamp ([`DEFAULT_MAX_PAGE_LIMIT`]). Used by
+    /// the COUNT fallback path, which needs to fetch all matching events for
+    /// post-filter counting. When None, the default clamp applies.
     pub max_limit: Option<i64>,
-    /// Persona visibility reader: when set, append an SQL visibility clause
-    /// for kind 30175 before ORDER/LIMIT so private personas are excluded from
-    /// the candidate page rather than discarded after it.
+    /// Shared-gated visibility reader: when set, append an SQL visibility
+    /// clause for every kind in [`SHARED_GATED_KINDS`] before ORDER/LIMIT so
+    /// private events are excluded from the candidate page rather than
+    /// discarded after it.
     ///
-    /// The clause is: `AND (kind != 30175 OR pubkey = $reader OR tags @> ?)`,
-    /// where `?` is the JSONB literal `[["shared","true"]]`.  The GIN index on
-    /// `tags` (migration 0004, jsonb_path_ops) makes the containment check fast.
+    /// The clause is: `AND (kind NOT IN (...) OR pubkey = $reader OR tags @> ?)`,
+    /// where the `IN` list is [`SHARED_GATED_KINDS`] and `?` is the JSONB
+    /// literal `[["shared","true"]]`.  The GIN index on `tags` (migration 0004,
+    /// jsonb_path_ops) makes the containment check fast.
     ///
     /// NOTE: `tags @> '[["shared","true"]]'` uses JSONB containment, which
     /// matches any tag array that is a superset of `[["shared","true"]]` — it
@@ -85,7 +94,7 @@ pub struct EventQuery {
     /// 2` exact-shape check ensures such malformed tags are never stored, so the
     /// SQL pushdown is sound.  Keeping `event_visible_to_reader` as post-filter
     /// defense-in-depth catches any residual mismatch.
-    pub persona_reader: Option<Vec<u8>>,
+    pub shared_gated_reader: Option<Vec<u8>>,
 }
 
 impl EventQuery {
@@ -114,7 +123,7 @@ impl EventQuery {
             e_tags: None,
             channel_ids: None,
             max_limit: None,
-            persona_reader: None,
+            shared_gated_reader: None,
         }
     }
 }
@@ -316,6 +325,17 @@ pub async fn insert_event(
 /// Uses `QueryBuilder` for dynamic filter composition — avoids string concatenation
 /// while keeping all user values in bind parameters.
 pub async fn query_events(pool: &PgPool, q: &EventQuery) -> Result<Vec<StoredEvent>> {
+    let mut conn = pool.acquire().await?;
+    query_events_on(&mut conn, q).await
+}
+
+/// [`query_events`] on a specific session — the replica-routing path runs
+/// follow-up (aux) queries on the exact reader connection whose heartbeat
+/// observation proved coverage for the page they annotate.
+pub(crate) async fn query_events_on(
+    conn: &mut sqlx::PgConnection,
+    q: &EventQuery,
+) -> Result<Vec<StoredEvent>> {
     // Composite cursor requires both halves.
     if q.before_id.is_some() && q.until.is_none() {
         return Err(DbError::InvalidData(
@@ -344,7 +364,7 @@ pub async fn query_events(pool: &PgPool, q: &EventQuery) -> Result<Vec<StoredEve
         return Ok(vec![]);
     }
 
-    let clamp = q.max_limit.unwrap_or(1000);
+    let clamp = q.max_limit.unwrap_or(DEFAULT_MAX_PAGE_LIMIT);
     let limit_val = q.limit.unwrap_or(100).min(clamp);
     let offset_val = q.offset.unwrap_or(0);
 
@@ -501,25 +521,28 @@ pub async fn query_events(pool: &PgPool, q: &EventQuery) -> Result<Vec<StoredEve
         }
     }
 
-    // Persona visibility pushdown: exclude kind 30175 events that are neither
-    // authored by the reader nor explicitly shared.  Applied BEFORE ORDER/LIMIT
-    // so that a page of newer private personas does not push visible shared ones
-    // off the end of the result set (the catalog query pattern).
+    // Shared-gated visibility pushdown: exclude SHARED_GATED_KINDS events that
+    // are neither authored by the reader nor explicitly shared.  Applied BEFORE
+    // ORDER/LIMIT so that a page of newer private events does not push visible
+    // shared ones off the end of the result set (the catalog query pattern).
     //
-    // Clause: AND (kind != 30175 OR pubkey = $reader OR tags @> '[["shared","true"]]')
+    // Clause: AND (kind NOT IN (30175, 30178) OR pubkey = $reader
+    //              OR tags @> '[["shared","true"]]')
     //
     // The JSONB containment check is served by idx_events_tags_gin (migration
     // 0004, jsonb_path_ops).  `tags @> '[["shared","true"]]'` matches any array
     // that contains exactly the sub-array — a two-element `["shared","true"]`
-    // tag passes; a tag-absent event does not.  Because ingest now requires
-    // exactly two elements for the shared tag (parts.len() == 2), no stored
-    // event can carry a three-element superset.
-    if let Some(ref reader_bytes) = q.persona_reader {
-        let kind_30175: i32 = 30175;
+    // tag passes; a tag-absent event does not.  Because ingest requires exactly
+    // two elements for the shared tag (parts.len() == 2), no stored event can
+    // carry a three-element superset.
+    if let Some(ref reader_bytes) = q.shared_gated_reader {
         let shared_containment = serde_json::json!([["shared", "true"]]);
-        qb.push(format!(" AND ({col_prefix}kind != "));
-        qb.push_bind(kind_30175);
-        qb.push(format!(" OR {col_prefix}pubkey = "));
+        qb.push(format!(" AND ({col_prefix}kind NOT IN ("));
+        let mut sep = qb.separated(", ");
+        for kind in SHARED_GATED_KINDS {
+            sep.push_bind(*kind as i32);
+        }
+        qb.push(format!(") OR {col_prefix}pubkey = "));
         qb.push_bind(reader_bytes.clone());
         qb.push(format!(" OR {col_prefix}tags @> "));
         qb.push_bind(shared_containment);
@@ -538,7 +561,7 @@ pub async fn query_events(pool: &PgPool, q: &EventQuery) -> Result<Vec<StoredEve
     qb.push_bind(limit_val);
     qb.push(" OFFSET ").push_bind(offset_val);
 
-    let rows = qb.build().fetch_all(pool).await?;
+    let rows = qb.build().fetch_all(&mut *conn).await?;
 
     let mut out = Vec::with_capacity(rows.len());
     for row in rows {
@@ -596,6 +619,14 @@ pub(crate) fn row_to_stored_event(row: sqlx::postgres::PgRow) -> Result<Option<S
 ///
 /// Uses the same filter logic as `query_events` but returns only the count.
 pub async fn count_events(pool: &PgPool, q: &EventQuery) -> Result<i64> {
+    let mut conn = pool.acquire().await?;
+    count_events_on(&mut conn, q).await
+}
+
+/// [`count_events`] on a specific session — the replica-routing path runs
+/// the count on the exact reader connection whose heartbeat observation
+/// proved its predicate.
+pub(crate) async fn count_events_on(conn: &mut sqlx::PgConnection, q: &EventQuery) -> Result<i64> {
     // Empty list means "match nothing" — return 0 immediately.
     if q.kinds.as_deref().is_some_and(|k| k.is_empty()) {
         return Ok(0);
@@ -730,7 +761,7 @@ pub async fn count_events(pool: &PgPool, q: &EventQuery) -> Result<i64> {
         }
     }
 
-    let row = qb.build().fetch_one(pool).await?;
+    let row = qb.build().fetch_one(&mut *conn).await?;
     let cnt: i64 = row.try_get("cnt")?;
 
     Ok(cnt)
@@ -758,7 +789,8 @@ pub async fn soft_delete_event(
 }
 
 /// Soft-delete the live row for an addressable coordinate
-/// `(kind, pubkey, d_tag)` — the NIP-33 replacement key.
+/// `(kind, pubkey, d_tag)` — the NIP-33 replacement key — provided it is not
+/// newer than the deletion request.
 ///
 /// Used by `handle_a_tag_deletion` to honour NIP-09 a-tag deletions for any
 /// parameterized-replaceable kind. The WHERE clause mirrors
@@ -766,23 +798,45 @@ pub async fn soft_delete_event(
 /// `channel_id` is intentionally NOT in the key (NIP-33 replacement is global
 /// per the spec — `channel_id` is stored for query scoping, not identity).
 ///
+/// `deletion_created_at_secs` is the deletion event's own `created_at`. NIP-09
+/// scopes an `a`-tag deletion to versions at or before that instant, so a
+/// delayed or replayed tombstone signed between two versions must not erase the
+/// newer replacement. `events.created_at` is immutable per row, so the predicate
+/// guarantees a tombstone can never erase a version newer than itself — the UPDATE
+/// re-evaluates its WHERE clause after any lock wait, so a replacement that races
+/// the deletion and lands with a later `created_at` is always spared.
+///
+/// This does NOT guarantee deletion completeness when a same-coordinate
+/// replacement races the deletion: the deletion may evaluate its predicate before
+/// the replacement arrives, miss the incoming head, and return `Ok(false)`. That
+/// outcome is state-identical to the deletion having arrived first (old head
+/// gone, new head present), which is a valid Nostr ordering — Nostr never fixes
+/// the order of concurrent writes from different signers, and even same-signer
+/// ordering is advisory. The return value feeds only a debug log, not a
+/// correctness gate.
+///
 /// Returns `Ok(true)` if a row was deleted, `Ok(false)` if no live row matched
-/// (already deleted, or never existed).
+/// (already deleted, never existed, or strictly newer than the deletion).
 pub async fn soft_delete_by_coordinate(
     pool: &PgPool,
     community_id: CommunityId,
     kind: i32,
     pubkey: &[u8],
     d_tag: &str,
+    deletion_created_at_secs: i64,
 ) -> Result<bool> {
+    let deletion_created_at = DateTime::from_timestamp(deletion_created_at_secs, 0)
+        .ok_or(DbError::InvalidTimestamp(deletion_created_at_secs))?;
     let result = sqlx::query(
         "UPDATE events SET deleted_at = NOW() \
-         WHERE community_id = $1 AND kind = $2 AND pubkey = $3 AND d_tag = $4 AND deleted_at IS NULL",
+         WHERE community_id = $1 AND kind = $2 AND pubkey = $3 AND d_tag = $4 AND deleted_at IS NULL \
+         AND created_at <= $5",
     )
     .bind(community_id.as_uuid())
     .bind(kind)
     .bind(pubkey)
     .bind(d_tag)
+    .bind(deletion_created_at)
     .execute(pool)
     .await?;
 
@@ -990,6 +1044,21 @@ pub async fn get_events_by_ids(
     pool: &PgPool,
     community_id: CommunityId,
     ids: &[&[u8]],
+) -> Result<Vec<StoredEvent>> {
+    if ids.is_empty() {
+        return Ok(vec![]);
+    }
+    let mut conn = pool.acquire().await?;
+    get_events_by_ids_on(&mut conn, community_id, ids).await
+}
+
+/// [`get_events_by_ids`] on a specific session — the replica-routing path
+/// runs the query on the exact reader connection whose heartbeat
+/// observation proved its predicate.
+pub(crate) async fn get_events_by_ids_on(
+    conn: &mut sqlx::PgConnection,
+    community_id: CommunityId,
+    ids: &[&[u8]],
 ) -> Result<Vec<StoredEvent>> {
     if ids.is_empty() {
         return Ok(vec![]);
@@ -1008,7 +1077,7 @@ pub async fn get_events_by_ids(
     }
     qb.push(")");
 
-    let rows = qb.build().fetch_all(pool).await?;
+    let rows = qb.build().fetch_all(&mut *conn).await?;
 
     let mut out = Vec::with_capacity(rows.len());
     for row in rows {
diff --git a/crates/buzz-db/src/feed.rs b/crates/buzz-db/src/feed.rs
index 511a2a6083..40e58d0d06 100644
--- a/crates/buzz-db/src/feed.rs
+++ b/crates/buzz-db/src/feed.rs
@@ -132,6 +132,29 @@ pub async fn query_mentions(
     accessible_channel_ids: &[Uuid],
     since: Option<DateTime<Utc>>,
     limit: i64,
+) -> Result<Vec<StoredEvent>> {
+    let mut conn = pool.acquire().await?;
+    query_mentions_on(
+        &mut conn,
+        community,
+        pubkey_bytes,
+        accessible_channel_ids,
+        since,
+        limit,
+    )
+    .await
+}
+
+/// [`query_mentions`] on a specific session — the replica-routing path runs
+/// the query on the exact reader connection whose heartbeat observation
+/// proved its predicate.
+pub(crate) async fn query_mentions_on(
+    conn: &mut sqlx::PgConnection,
+    community: CommunityId,
+    pubkey_bytes: &[u8],
+    accessible_channel_ids: &[Uuid],
+    since: Option<DateTime<Utc>>,
+    limit: i64,
 ) -> Result<Vec<StoredEvent>> {
     let mut qb = build_mentions_query(
         community,
@@ -140,7 +163,7 @@ pub async fn query_mentions(
         since,
         limit,
     );
-    let rows = qb.build().fetch_all(pool).await?;
+    let rows = qb.build().fetch_all(&mut *conn).await?;
     collect_stored_events(rows)
 }
 
@@ -193,6 +216,27 @@ pub async fn query_needs_action(
     accessible_channel_ids: &[Uuid],
     since: Option<DateTime<Utc>>,
     limit: i64,
+) -> Result<Vec<StoredEvent>> {
+    let mut conn = pool.acquire().await?;
+    query_needs_action_on(
+        &mut conn,
+        community,
+        pubkey_bytes,
+        accessible_channel_ids,
+        since,
+        limit,
+    )
+    .await
+}
+
+/// [`query_needs_action`] on a specific session — see [`query_mentions_on`].
+pub(crate) async fn query_needs_action_on(
+    conn: &mut sqlx::PgConnection,
+    community: CommunityId,
+    pubkey_bytes: &[u8],
+    accessible_channel_ids: &[Uuid],
+    since: Option<DateTime<Utc>>,
+    limit: i64,
 ) -> Result<Vec<StoredEvent>> {
     let mut qb = build_needs_action_query(
         community,
@@ -201,7 +245,7 @@ pub async fn query_needs_action(
         since,
         limit,
     );
-    let rows = qb.build().fetch_all(pool).await?;
+    let rows = qb.build().fetch_all(&mut *conn).await?;
     collect_stored_events(rows)
 }
 
@@ -241,9 +285,21 @@ pub async fn query_activity(
     accessible_channel_ids: &[Uuid],
     since: Option<DateTime<Utc>>,
     limit: i64,
+) -> Result<Vec<StoredEvent>> {
+    let mut conn = pool.acquire().await?;
+    query_activity_on(&mut conn, community, accessible_channel_ids, since, limit).await
+}
+
+/// [`query_activity`] on a specific session — see [`query_mentions_on`].
+pub(crate) async fn query_activity_on(
+    conn: &mut sqlx::PgConnection,
+    community: CommunityId,
+    accessible_channel_ids: &[Uuid],
+    since: Option<DateTime<Utc>>,
+    limit: i64,
 ) -> Result<Vec<StoredEvent>> {
     let mut qb = build_activity_query(community, accessible_channel_ids, since, limit);
-    let rows = qb.build().fetch_all(pool).await?;
+    let rows = qb.build().fetch_all(&mut *conn).await?;
     collect_stored_events(rows)
 }
 
diff --git a/crates/buzz-db/src/lib.rs b/crates/buzz-db/src/lib.rs
index 2a3ba9a63e..9b26876747 100644
--- a/crates/buzz-db/src/lib.rs
+++ b/crates/buzz-db/src/lib.rs
@@ -55,7 +55,7 @@ pub mod user;
 pub mod workflow;
 
 pub use error::{DbError, Result};
-pub use event::{EventQuery, ReactionEventInsertOutcome};
+pub use event::{EventQuery, ReactionEventInsertOutcome, DEFAULT_MAX_PAGE_LIMIT};
 
 use chrono::{DateTime, Utc};
 use sqlx::postgres::{PgConnection, PgPoolOptions};
@@ -181,12 +181,289 @@ pub struct Db {
     /// route here (see [`Db::read`]); locks, transactions, and anything
     /// consistency-critical stays on `pool`.
     pub(crate) read_pool: Option<PgPool>,
+    /// Maximum connections configured for the read-replica pool (from
+    /// [`DbConfig::read_max_connections`], defaulting to the writer's
+    /// sizing). Kept separately from `max_connections` so
+    /// [`Db::read_pool_stats`] reports the reader's own ceiling — a
+    /// utilisation gauge derived from the writer's max would understate
+    /// reader saturation by exactly the ratio of the two pool sizes.
+    pub(crate) read_max_connections: u32,
     /// Freshness fence gating cursor-page routing to the replica.
     ///
     /// Starts closed; a background probe ([`replica_fence::run_probe`])
-    /// advances it after each verified writer→replica LSN handshake. When
-    /// closed or stale, every cursor page routes to the writer.
+    /// commits heartbeat tokens and retains proof entries. Routing proves
+    /// coverage per request on the serving reader session; when the ring is
+    /// empty or stale, every routed read stays on the writer.
     pub(crate) fence: std::sync::Arc<replica_fence::ReplicaFence>,
+    /// Bounded-staleness routing budget `B`: a read routed under
+    /// [`RoutePredicate::Bounded`] may be served from a proved replica
+    /// session only when the proved heartbeat entry is at most this old.
+    /// `None` disables the bounded arm entirely (the rollout default) —
+    /// bounded-stale read semantics are a product decision, not an
+    /// invariant, so the gate ships off.
+    pub(crate) replica_read_max_age: Option<Duration>,
+    /// Whether the reader endpoint supports the Aurora PostgreSQL identity
+    /// function ([`replica_fence::AURORA_IDENTITY_FN`]) — probed
+    /// once per process on the first routed read (on a plain autocommit
+    /// checkout, outside any request transaction) and cached. Unset means
+    /// not yet probed (or the probe hit a transient error and will retry).
+    /// Shared across `Db` clones.
+    pub(crate) reader_aurora_identity: std::sync::Arc<std::sync::OnceLock<bool>>,
+}
+
+/// The session that served (or will serve) a routed read, so follow-up
+/// queries in the same request (the channel-window aux closure) run on the
+/// **same proved snapshot** — a different pooled reader session may sit at a
+/// different replay position, and even the same connection advances its
+/// snapshot between autocommit statements.
+///
+/// `Replica` holds the request's `REPEATABLE READ, READ ONLY` transaction:
+/// the heartbeat observation was its first statement, so the snapshot the
+/// proof was taken against is exactly the snapshot every follow-up sees.
+/// Dropping the session rolls the read-only transaction back and returns
+/// the connection to the pool.
+///
+/// `Writer` carries the writer pool: follow-ups there are authoritative by
+/// construction and need no session pinning.
+pub struct ReadSession {
+    inner: ReadSessionInner,
+}
+
+enum ReadSessionInner {
+    /// The proved replica request transaction (snapshot-anchored), plus the
+    /// writer pool so a mid-request replica failure (e.g. a hot-standby
+    /// recovery conflict cancelling the held snapshot) degrades the session
+    /// to the writer instead of surfacing an error: degraded capacity,
+    /// never holes — and never a 500 the writer could have served.
+    Replica {
+        tx: sqlx::Transaction<'static, sqlx::Postgres>,
+        writer: PgPool,
+    },
+    /// The writer pool (cheap clone; Arc-backed).
+    Writer(PgPool),
+}
+
+impl ReadSession {
+    /// Query events on this session (see [`Db::query_events`]).
+    ///
+    /// If the proved replica transaction fails mid-request, the session
+    /// permanently degrades to the writer and the query is re-run there.
+    /// The writer is always at or ahead of any replica replay position, so
+    /// the degraded follow-up can only observe *more* than the proof-time
+    /// snapshot, never less — fresher aux rows, the same failure semantics
+    /// as a request that routed to the writer to begin with.
+    pub async fn query_events(&mut self, q: &EventQuery) -> Result<Vec<StoredEvent>> {
+        let degraded = match &mut self.inner {
+            ReadSessionInner::Replica { tx, writer } => {
+                match event::query_events_on(tx, q).await {
+                    Ok(rows) => return Ok(rows),
+                    Err(e) => {
+                        tracing::warn!(
+                            error = %e,
+                            "replica session query failed mid-request; degrading to writer"
+                        );
+                        // Deliberately not a `buzz_db_route_decision` event:
+                        // the page's route was already recorded, and the
+                        // offload metric must stay one-event-per-request.
+                        metrics::counter!("buzz_db_read_session_degraded").increment(1);
+                        writer.clone()
+                    }
+                }
+            }
+            ReadSessionInner::Writer(pool) => return event::query_events(pool, q).await,
+        };
+        // Replacing the inner drops the replica transaction (rolling it
+        // back and returning the reader connection to its pool).
+        self.inner = ReadSessionInner::Writer(degraded.clone());
+        event::query_events(&degraded, q).await
+    }
+
+    /// Whether this session is a proved replica connection (observability).
+    pub fn is_replica(&self) -> bool {
+        matches!(self.inner, ReadSessionInner::Replica { .. })
+    }
+}
+
+/// Where one routed read is served (see [`Db::route_read`]).
+enum RouteDecision {
+    /// A reader request transaction whose first-statement heartbeat
+    /// observation proved this fence entry — the page runs inside it. The
+    /// `&'static str` is the metric reason (`covered`/`fresh`); the caller
+    /// records the route only once the page is actually served from the
+    /// replica, so a post-verification writer re-run or a mid-query replica
+    /// failure emits exactly one `buzz_db_route_decision` event per request
+    /// (the offload percentage is read straight off `decision="replica"`).
+    Replica(
+        sqlx::Transaction<'static, sqlx::Postgres>,
+        replica_fence::TokenEntry,
+        &'static str,
+    ),
+    /// Fail closed: serve from the writer pool (already recorded).
+    Writer,
+}
+
+/// The ONLY place [`route_proof::ChannelScoped`] can be constructed. A
+/// crate-root tuple struct would be mintable via `ChannelScoped(())` from
+/// every descendant module — tuple-struct field privacy is module-scoped —
+/// so the token lives in its own module and E0423 enforces the invariant.
+mod route_proof {
+    use uuid::Uuid;
+
+    /// Proof that a query/page can only return rows with
+    /// `channel_id IS NOT NULL` — the domain of the commit-time floor guard
+    /// (migration 0021). `channel_ids` (retains channel-NULL rows) and
+    /// `global_only = false` are explicitly NOT proofs.
+    ///
+    /// Each constructor keys off *how* its path proves channel-bearing-ness:
+    /// a pinned query filter, a bare `Uuid` argument, or a `NOT NULL` column
+    /// reached through an inner join. Do not add a universal constructor
+    /// callers reshape their inputs to fit, and never fabricate a throwaway
+    /// `EventQuery` purely to mint a token — the proof must be the SQL's
+    /// shape, not "someone assembled a struct".
+    #[derive(Clone, Copy)]
+    pub(crate) struct ChannelScoped(());
+
+    impl ChannelScoped {
+        /// Constructor 1: the query pins a single channel
+        /// (`EventQuery.channel_id = Some(_)`, compiled to a
+        /// `channel_id = $n` predicate). This proof covers BOTH query
+        /// builders — the SELECT builder (`event::query_events_on`) and the
+        /// COUNT builder (`event::count_events`) pin identically; if the
+        /// two ever drift, this comment is a lie and the routed COUNT seam
+        /// is unsound.
+        /// Sound under conjunction: any additional clause (e.g.
+        /// `channel_ids`, which alone retains channel-NULL rows) is ANDed,
+        /// and `channel_id = <uuid>` never matches NULL — the pin strictly
+        /// narrows and cannot be widened back out to global rows.
+        pub(crate) fn from_pinned_channel(q: &crate::event::EventQuery) -> Option<Self> {
+            q.channel_id.map(|_| ChannelScoped(()))
+        }
+
+        /// Constructor 2 (thread pages): the page is an inner JOIN from
+        /// `thread_metadata` to `events`, and `thread_metadata.channel_id`
+        /// is `UUID NOT NULL` — every writer that creates a row passes a
+        /// concrete channel (`ThreadMetadataParams.channel_id: Uuid`,
+        /// non-Option). Channel-bearing by construction of the join, not by
+        /// query predicate.
+        pub(crate) fn from_thread_metadata_join() -> Self {
+            ChannelScoped(())
+        }
+
+        /// Constructor 3 (channel windows): the channel arrives as a bare
+        /// `Uuid` argument and the SQL binds it unconditionally
+        /// (`e.channel_id = $2` in `get_channel_window_on`); every served
+        /// row is channel-bearing. No `EventQuery` exists on this path.
+        pub(crate) fn from_channel_id(_channel_id: Uuid) -> Self {
+            ChannelScoped(())
+        }
+    }
+}
+use route_proof::ChannelScoped;
+
+/// The predicate one routed read must satisfy (see [`Db::route_read`]).
+///
+/// Discipline: no `Default`, no `Deserialize`, stays non-`pub` — any of
+/// those re-opens the [`ChannelScoped`] mint.
+enum RoutePredicate {
+    /// Bounded staleness: the proved entry must be within the configured
+    /// read budget `B` (default off). Bounds TIME — the page misses at most
+    /// the freshest `B` of writes. Sound for ANY query shape, including
+    /// global (channel-NULL) rows: it relies only on heartbeat commit order,
+    /// not the floor guard.
+    Bounded,
+    /// Completeness: the proved wall must cover the page's upper bound.
+    /// Bounds CONTENT — every row at/below `upper` is present, meaningful
+    /// even when the cursor is hours old, where `B`-freshness says nothing.
+    /// Sound ONLY on the floor guard's domain (channel-bearing rows), hence
+    /// the proof token. `upper` is non-optional: the no-upper-bound
+    /// post-verifying case is [`RoutePredicate::CoveredPostVerified`].
+    ///
+    /// Bounds INSERT-completeness only — "no missing rows", not "no extra
+    /// rows". Soft deletes are `UPDATE .. SET deleted_at` commits outside
+    /// the floor guard and never touch `created_at`, so a covered page can
+    /// briefly serve a row the writer already excludes; deletion visibility
+    /// is bounded by replication lag under `FENCE_STALENESS` (30s), not by
+    /// `upper` or `B`. Do not extend the covered arm to a surface that
+    /// cannot absorb extra rows (this is why the routed COUNT seam is
+    /// bounded-only).
+    Covered {
+        upper: DateTime<Utc>,
+        /// Never read — the field exists so constructing this variant
+        /// requires minting the token through `route_proof`.
+        #[allow(dead_code)]
+        proof: ChannelScoped,
+    },
+    /// Forward-walking thread pages: no upper bound is derivable from the
+    /// cursor; the caller post-verifies the served rows against the proved
+    /// wall (full page + tail at/below the wall, else re-run on the writer).
+    /// Only the thread path constructs this — a general routed caller does
+    /// no post-verification and must never self-certify.
+    CoveredPostVerified {
+        #[allow(dead_code)]
+        proof: ChannelScoped,
+    },
+    /// Either arm admits, covered tried first (it has no budget dependence).
+    /// For general routed reads that are channel-pinned AND carry an
+    /// `until` upper bound.
+    BoundedOrCovered {
+        upper: DateTime<Utc>,
+        /// Never read — see [`RoutePredicate::Covered::proof`].
+        #[allow(dead_code)]
+        proof: ChannelScoped,
+    },
+}
+
+impl RoutePredicate {
+    /// A channel-window request: cursor pages are covered-only — for deep
+    /// keyset pages only coverage answers "have all rows below the cursor
+    /// replayed?" — and a head fetch is bounded. The channel id is the
+    /// bare-`Uuid` proof that the window SQL pins a channel.
+    fn from_channel_cursor(channel_id: Uuid, cursor: &Option<(DateTime<Utc>, Vec<u8>)>) -> Self {
+        match cursor {
+            Some((ts, _)) => RoutePredicate::Covered {
+                upper: *ts,
+                proof: ChannelScoped::from_channel_id(channel_id),
+            },
+            None => RoutePredicate::Bounded,
+        }
+    }
+
+    /// General entry point for the routed query seams: derives the strongest
+    /// sound predicate from the query shape. Never produces a covered arm
+    /// without both a channel-scope proof AND a real upper bound.
+    ///
+    /// `routing_enabled` is whether `BUZZ_REPLICA_READ_MAX_AGE_MS` is set
+    /// (non-zero). When it is NOT, this returns `Bounded` — which the zero
+    /// budget then fails closed — so the new seams are genuinely dark at
+    /// the deploy default even for channel-pinned queries carrying `until`.
+    /// Without this gate, `BoundedOrCovered` would take the covered arm
+    /// (which has no budget dependence) and route on day one with no env
+    /// var set and no kill switch short of removing the replica URL
+    /// (Dawn's covered-at-zero-budget catch). The pre-existing cursor
+    /// paths (`Covered`/`CoveredPostVerified` from channel windows and
+    /// thread pages) intentionally still route at B=0 — status quo,
+    /// unchanged.
+    fn for_query(q: &event::EventQuery, routing_enabled: bool) -> Self {
+        if !routing_enabled {
+            return RoutePredicate::Bounded;
+        }
+        match (ChannelScoped::from_pinned_channel(q), q.until) {
+            (Some(proof), Some(upper)) => RoutePredicate::BoundedOrCovered { upper, proof },
+            _ => RoutePredicate::Bounded,
+        }
+    }
+}
+
+/// Map the configured read budget (`BUZZ_REPLICA_READ_MAX_AGE_MS`) to the
+/// runtime gate: `0` disables bounded-staleness routing; anything above the
+/// fence staleness gate is clamped to it (an entry older than the staleness
+/// gate never routes anyway, so a larger budget would only misrepresent the
+/// config).
+fn read_budget_from_ms(ms: u64) -> Option<Duration> {
+    match ms {
+        0 => None,
+        ms => Some(Duration::from_millis(ms).min(replica_fence::FENCE_STALENESS)),
+    }
 }
 
 /// Snapshot of Postgres connection pool utilisation.
@@ -232,6 +509,9 @@ pub struct DbConfig {
     pub read_database_url: Option<String>,
     /// Maximum number of connections in the pool.
     pub max_connections: u32,
+    /// Maximum connections in the read-replica pool (env
+    /// `BUZZ_DB_READ_POOL_SIZE`). `None` inherits [`Self::max_connections`].
+    pub read_max_connections: Option<u32>,
     /// Minimum number of idle connections to maintain.
     pub min_connections: u32,
     /// Seconds to wait when acquiring a connection before timing out.
@@ -240,6 +520,13 @@ pub struct DbConfig {
     pub max_lifetime_secs: u64,
     /// Seconds a connection may sit idle before being closed.
     pub idle_timeout_secs: u64,
+    /// Replica read budget `B` in milliseconds (bounded arm, env
+    /// `BUZZ_REPLICA_READ_MAX_AGE_MS`). `0` disables bounded-staleness
+    /// routing — the rollout default. Values above
+    /// [`replica_fence::FENCE_STALENESS`] are clamped to it: an entry older
+    /// than the staleness gate never routes anyway, so a larger budget
+    /// would only misrepresent the config.
+    pub replica_read_max_age_ms: u64,
 }
 
 impl Default for DbConfig {
@@ -251,10 +538,12 @@ impl Default for DbConfig {
             database_url: "postgres://buzz:buzz_dev@localhost:5432/buzz".to_string(), // sadscan:disable np.postgres.1
             read_database_url: None,
             max_connections: 20,
+            read_max_connections: None,
             min_connections: 2,
             acquire_timeout_secs: 3,
             max_lifetime_secs: 1800,
             idle_timeout_secs: 600,
+            replica_read_max_age_ms: 0,
         }
     }
 }
@@ -361,15 +650,22 @@ impl Db {
     /// proof hold for every insert path that goes through this pool.
     pub async fn new(config: &DbConfig) -> Result<Self> {
         let pool = Self::connect_pool(config, &config.database_url, true).await?;
+        let read_max_connections = config
+            .read_max_connections
+            .unwrap_or(config.max_connections);
         let read_pool = match &config.read_database_url {
-            Some(url) => Some(Self::connect_pool(config, url, false).await?),
+            Some(url) => Some(Self::connect_read_pool(config, url, read_max_connections)?),
             None => None,
         };
+        let replica_read_max_age = read_budget_from_ms(config.replica_read_max_age_ms);
         Ok(Self {
             pool,
             max_connections: config.max_connections,
             read_pool,
+            read_max_connections,
             fence: std::sync::Arc::new(replica_fence::ReplicaFence::new()),
+            replica_read_max_age,
+            reader_aurora_identity: std::sync::Arc::new(std::sync::OnceLock::new()),
         })
     }
 
@@ -401,13 +697,90 @@ impl Db {
         Ok(options.connect(url).await?)
     }
 
+    /// Reader acquire timeout — deliberately far below the writer's
+    /// (seconds-denominated) timeout. Failing closed to the writer must be
+    /// fast: a saturated reader pool that made routed reads wait the full
+    /// writer-style timeout would add dead latency during exactly the load
+    /// spike the offload exists for. A miss here surfaces as
+    /// `writer/reader_acquire_timeout` (see [`Db::proved_reader`] for why
+    /// the reason names the mechanism rather than a diagnosis).
+    const READER_ACQUIRE_TIMEOUT: Duration = Duration::from_millis(150);
+
+    /// Connect the read-replica pool **lazily** — no connection is
+    /// attempted at construction, so a reader that is down at boot cannot
+    /// crash the relay (it starts all-writer with the fence closed and
+    /// recovers when the replica returns).
+    ///
+    /// `min_connections` is pinned to 0 explicitly: sqlx's lazy pool still
+    /// spawns an eager background connect task to satisfy a nonzero
+    /// minimum, which would reintroduce boot-time reader dial attempts (and
+    /// their log noise) that "lazy" is meant to avoid. With 0, connections
+    /// are dialed only on first acquire; the ~10-minute reaper never tops
+    /// the pool back up, which is fine — routed reads re-fill it on demand.
+    ///
+    /// No floor guard: replica sessions are read-only, the trigger never
+    /// fires there (see [`Db::connect_pool`]).
+    fn connect_read_pool(config: &DbConfig, url: &str, max_connections: u32) -> Result<PgPool> {
+        Ok(PgPoolOptions::new()
+            .max_connections(max_connections)
+            .min_connections(0)
+            .acquire_timeout(Self::READER_ACQUIRE_TIMEOUT)
+            .max_lifetime(Duration::from_secs(config.max_lifetime_secs))
+            .idle_timeout(Duration::from_secs(config.idle_timeout_secs))
+            .connect_lazy(url)?)
+    }
+
+    /// Spawn a one-shot reader reachability probe that only WARNs.
+    ///
+    /// With a lazy pool and `min_connections(0)`, nothing dials the replica
+    /// until the first routed read — so a misconfigured `READ_DATABASE_URL`
+    /// would otherwise be invisible until traffic arrives and quietly falls
+    /// back to the writer. This ping is the only boot-time reader-down
+    /// visibility; it must never gate startup or [`Db::spawn_fence_probe`].
+    ///
+    /// On success it also primes the Aurora identity capability cache
+    /// ([`Db::reader_aurora_identity`]) on the connection it already holds,
+    /// so the first routed read doesn't spend a second acquire (up to
+    /// another [`Db::READER_ACQUIRE_TIMEOUT`]) inside
+    /// [`Db::reader_aurora_capability_on`]. Prime failure is fine: the routed
+    /// path re-probes on the connection it already holds, so a failed prime
+    /// costs a round trip rather than a second acquire budget.
+    pub fn spawn_read_pool_boot_ping(&self) {
+        let Some(read_pool) = self.read_pool.clone() else {
+            return;
+        };
+        let aurora_identity = self.reader_aurora_identity.clone();
+        tokio::spawn(async move {
+            match read_pool.acquire().await {
+                Ok(mut conn) => {
+                    tracing::info!("read replica reachable at boot");
+                    match replica_fence::reader_supports_aurora_identity(&mut conn).await {
+                        Ok(supported) => {
+                            let _ = aurora_identity.set(supported);
+                        }
+                        Err(e) => tracing::debug!(
+                            error = %e,
+                            "aurora identity boot prime failed; first routed read will probe"
+                        ),
+                    }
+                }
+                Err(e) => tracing::warn!(
+                    "read replica unreachable at boot; serving all-writer until it recovers: {e}"
+                ),
+            }
+        });
+    }
+
     /// Creates a `Db` from an existing `PgPool` (useful in tests).
     pub fn from_pool(pool: PgPool) -> Self {
         Self {
             max_connections: pool.options().get_max_connections(),
+            read_max_connections: pool.options().get_max_connections(),
             pool,
             read_pool: None,
             fence: std::sync::Arc::new(replica_fence::ReplicaFence::new()),
+            replica_read_max_age: None,
+            reader_aurora_identity: std::sync::Arc::new(std::sync::OnceLock::new()),
         }
     }
 
@@ -421,12 +794,21 @@ impl Db {
     pub fn from_pools(pool: PgPool, read_pool: PgPool) -> Self {
         Self {
             max_connections: pool.options().get_max_connections(),
+            read_max_connections: read_pool.options().get_max_connections(),
             pool,
             read_pool: Some(read_pool),
             fence: std::sync::Arc::new(replica_fence::ReplicaFence::new()),
+            replica_read_max_age: None,
+            reader_aurora_identity: std::sync::Arc::new(std::sync::OnceLock::new()),
         }
     }
 
+    /// Test hook: set the head-fetch routing budget (Predicate A), which
+    /// [`Db::from_pools`] leaves disabled.
+    pub fn set_replica_read_max_age_for_tests(&mut self, budget: Option<Duration>) {
+        self.replica_read_max_age = budget;
+    }
+
     /// The freshness fence gating replica routing (see [`replica_fence`]).
     pub fn fence(&self) -> &std::sync::Arc<replica_fence::ReplicaFence> {
         &self.fence
@@ -438,7 +820,7 @@ impl Db {
     /// Ordering matters (Perci, PR #2084 review): this must run **after**
     /// the migration decision. On a relay with `BUZZ_AUTO_MIGRATE` off, the
     /// writer pool arms the GUC regardless, but if migration 0021 has not
-    /// been applied there is no trigger enforcing it — and an LSN probe
+    /// been applied there is no trigger enforcing it — and a heartbeat probe
     /// would open the fence over an unenforced floor. So the probe is gated
     /// on an unconditional two-part verification against the live schema:
     /// catalog shape ([`replica_fence::verify_floor_guard_catalog`]) and
@@ -449,14 +831,13 @@ impl Db {
     /// stays closed: every cursor page routes to the writer. The relay keeps
     /// serving — degraded capacity, never holes.
     pub async fn spawn_fence_probe(&self) -> Result<bool> {
-        let Some(read_pool) = &self.read_pool else {
+        if self.read_pool.is_none() {
             return Ok(false);
-        };
+        }
         replica_fence::verify_floor_guard_catalog(&self.pool).await?;
         replica_fence::verify_floor_guard_behavior(&self.pool).await?;
         tokio::spawn(replica_fence::run_probe(
             self.pool.clone(),
-            read_pool.clone(),
             std::sync::Arc::clone(&self.fence),
         ));
         Ok(true)
@@ -465,11 +846,13 @@ impl Db {
     /// The pool for lag-tolerant reads: the read replica when configured,
     /// otherwise the writer pool.
     ///
-    /// Routing contract — a query may use this pool only when a stale (bounded
-    /// replication lag) result is acceptable to its caller. Keyset-cursor
-    /// pagination over immutable history qualifies; head-of-channel fetches,
-    /// auth/membership checks, locks, and anything inside a transaction do not.
-    pub fn read(&self) -> &PgPool {
+    /// Removed as a public escape hatch (Dawn, review of 1b0aa0dfa): the
+    /// raw replica pool carries **no fence proof**, which is exactly the
+    /// bug class the routed-read machinery exists to eliminate. All replica
+    /// reads must go through [`Db::route_read`]-backed entry points; this
+    /// remains only for the fence's own plumbing tests.
+    #[cfg(test)]
+    fn read(&self) -> &PgPool {
         self.read_pool.as_ref().unwrap_or(&self.pool)
     }
 
@@ -478,6 +861,153 @@ impl Db {
         self.read_pool.is_some()
     }
 
+    /// Open a reader request transaction and complete the connection-local
+    /// half of the fence proof: `BEGIN ISOLATION LEVEL REPEATABLE READ, READ
+    /// ONLY`, then observe the heartbeat token/epoch as the transaction's
+    /// **first statement** — anchoring the snapshot every follow-up
+    /// statement (page, participants, aux closure) sees to exactly the
+    /// snapshot the proof was taken against — and resolve it against the
+    /// retained ring. Returns the open transaction together with the
+    /// strongest [`replica_fence::TokenEntry`] its observation supports, or
+    /// the fail-closed reason for route metrics.
+    ///
+    /// `REPEATABLE READ` is the strongest isolation a hot standby supports
+    /// (`SERIALIZABLE` is writer-only); `READ ONLY` documents intent and
+    /// rejects accidental writes. Everything but `Ok` fails closed — begin
+    /// failure, missing heartbeat row (migration not yet replayed there),
+    /// observation error, epoch mismatch, or a token below every retained
+    /// entry all route the request to the writer.
+    async fn proved_reader(
+        &self,
+        read_pool: &PgPool,
+    ) -> std::result::Result<
+        (
+            sqlx::Transaction<'static, sqlx::Postgres>,
+            replica_fence::TokenEntry,
+        ),
+        &'static str,
+    > {
+        // One checkout per routed read. The Aurora capability probe and the
+        // read-only transaction share a single `acquire()` so the request path
+        // spends exactly one READER_ACQUIRE_TIMEOUT budget. Probing through
+        // `read_pool` separately would spend a second budget whenever the
+        // capability is uncached — i.e. after a failed boot ping, which is
+        // precisely the reader-unavailable case the bound must hold for.
+        let conn = match read_pool.acquire().await {
+            Ok(conn) => conn,
+            Err(sqlx::Error::PoolTimedOut) => {
+                tracing::warn!("reader pool acquire timed out; routing to writer");
+                return Err("reader_acquire_timeout");
+            }
+            Err(e) => {
+                tracing::warn!(error = %e, "reader connection acquire failed; routing to writer");
+                return Err("reader_validation_error");
+            }
+        };
+        let mut conn = conn;
+        let aurora = self.reader_aurora_capability_on(&mut conn).await;
+        let mut tx = match sqlx::Transaction::begin(
+            conn,
+            Some(sqlx::SqlStr::from_static(
+                "BEGIN ISOLATION LEVEL REPEATABLE READ, READ ONLY",
+            )),
+        )
+        .await
+        {
+            Ok(tx) => tx,
+            // The acquire miss gets its own reason code: the reader pool's
+            // short acquire timeout (READER_ACQUIRE_TIMEOUT) makes this the
+            // fast fail-closed path under load, and
+            // `buzz_db_route_decision{decision="writer",reason="reader_acquire_timeout"}`
+            // is the operator's alert signal for a struggling reader pool.
+            //
+            // The reason deliberately names the mechanism, not a diagnosis:
+            // `PoolTimedOut` proves only that no connection was handed out
+            // within the 150ms budget. That budget includes cold connect
+            // (TCP+TLS+auth), and sqlx's `size` counts in-flight dials, so
+            // this fires for slow connection establishment as well as for
+            // established-connection contention — and neither `size == 0`
+            // nor `size >= max` recovers the missing causal bit (in-flight
+            // dials hold a size slot, and a cold burst can push
+            // `active = size - idle` toward max with zero busy connections).
+            // Runbook: correlate with `buzz_db_read_pool_active` / `_max`
+            // and reader connection health/latency; high active suggests
+            // contention, but this metric alone does not distinguish
+            // contention from slow connects. Note the gauge is a coarse
+            // sample (BUZZ_POOL_METRICS_INTERVAL_SECS, default 10s) while
+            // the event it explains lasts ~150ms — a short burst may fall
+            // between samples entirely, so absence of elevated active is
+            // NOT evidence of a cold connect.
+            Err(sqlx::Error::PoolTimedOut) => {
+                tracing::warn!("reader pool acquire timed out; routing to writer");
+                return Err("reader_acquire_timeout");
+            }
+            Err(e) => {
+                tracing::warn!(error = %e, "reader transaction begin failed; routing to writer");
+                return Err("reader_validation_error");
+            }
+        };
+        let obs = match replica_fence::observe_heartbeat(&mut tx, aurora).await {
+            Ok(Some(observation)) => observation,
+            Ok(None) => return Err("reader_validation_error"),
+            Err(e) => {
+                tracing::warn!(error = %e, "heartbeat observation failed; routing to writer");
+                return Err("reader_validation_error");
+            }
+        };
+        match self.fence.resolve(obs.token, obs.epoch) {
+            replica_fence::ResolveOutcome::Proved(entry) => {
+                tracing::debug!(
+                    token = obs.token,
+                    proved_token = entry.token,
+                    backend = %obs.backend,
+                    "reader snapshot proved fence coverage"
+                );
+                Ok((tx, entry))
+            }
+            replica_fence::ResolveOutcome::EpochMismatch => Err("reader_validation_error"),
+            replica_fence::ResolveOutcome::TokenBehind => Err("reader_token_behind"),
+        }
+    }
+
+    /// Whether the reader endpoint supports the Aurora PostgreSQL identity
+    /// function ([`replica_fence::AURORA_IDENTITY_FN`]), probed
+    /// once per process and cached (see [`Db::reader_aurora_identity`]).
+    /// The probe runs on a plain autocommit checkout — never inside the
+    /// request transaction, where an undefined-function error would abort
+    /// it. Probe failure (acquire or transient) degrades to the plain
+    /// identity tuple for THIS request without caching, so a later request
+    /// retries; identity is evidence, never a routing gate.
+    /// Aurora capability on a connection the caller already holds, so the
+    /// routed path never spends a second acquire budget.
+    async fn reader_aurora_capability_on(
+        &self,
+        conn: &mut sqlx::pool::PoolConnection<sqlx::Postgres>,
+    ) -> bool {
+        if let Some(cached) = self.reader_aurora_identity.get() {
+            return *cached;
+        }
+        match replica_fence::reader_supports_aurora_identity(conn).await {
+            Ok(supported) => *self.reader_aurora_identity.get_or_init(|| supported),
+            Err(e) => {
+                tracing::debug!(error = %e, "aurora identity probe failed; will retry");
+                false
+            }
+        }
+    }
+
+    /// Record one route decision (Rev 2 observability): which path, where it
+    /// went, and why.
+    fn record_route(path: &'static str, decision: &'static str, reason: &'static str) {
+        metrics::counter!(
+            "buzz_db_route_decision",
+            "path" => path,
+            "decision" => decision,
+            "reason" => reason,
+        )
+        .increment(1);
+    }
+
     /// Run pending database migrations.
     pub async fn migrate(&self) -> Result<()> {
         migration::run_migrations(&self.pool).await
@@ -502,11 +1032,18 @@ impl Db {
     }
 
     /// Pool utilisation stats for the read-replica pool, when configured.
+    ///
+    /// `max` is the **reader's** ceiling ([`Db::read_max_connections`]), not
+    /// the writer's: `buzz_db_read_pool_active / buzz_db_read_pool_max` is
+    /// the operator's utilisation signal for tuning `BUZZ_DB_READ_POOL_SIZE`,
+    /// and deriving it from the writer's max would misreport saturation by
+    /// exactly the ratio of the two pool sizes — in the direction that hides
+    /// the problem.
     pub fn read_pool_stats(&self) -> Option<DbPoolStats> {
         self.read_pool.as_ref().map(|p| DbPoolStats {
             size: p.size(),
             idle: p.num_idle() as u32,
-            max: self.max_connections,
+            max: self.read_max_connections,
         })
     }
 
@@ -1094,15 +1631,126 @@ impl Db {
     }
 
     /// Queries events matching the given filter parameters.
+    ///
+    /// Always reads from the WRITER pool. If the result influences a write
+    /// or a permission decision, this is the method to call. Display-path
+    /// callers that tolerate bounded staleness should use
+    /// [`Db::query_events_routed`] instead — converting a caller is an
+    /// explicit, per-callsite decision, never a change to this method.
     pub async fn query_events(&self, q: &EventQuery) -> Result<Vec<StoredEvent>> {
         event::query_events(&self.pool, q).await
     }
 
+    /// [`Db::query_events`] with replica routing — the opt-in fast path for
+    /// display reads.
+    ///
+    /// Rule of thumb: **if the result influences a write or a permission,
+    /// it reads from the writer** — do not convert such a caller to this
+    /// method. Every new caller must be added to the caller-classification
+    /// table in `PLANS/REPLICA_FULL_READ_ROUTING_DESIGN.md`.
+    ///
+    /// Routing derives the strongest sound predicate from the query shape
+    /// ([`RoutePredicate::for_query`]): a channel-pinned query with an
+    /// `until` upper bound may be served covered (provably complete below
+    /// the fence wall); anything else is bounded-staleness only. The whole
+    /// seam is gated on `BUZZ_REPLICA_READ_MAX_AGE_MS` (default off): when
+    /// unset, even covered-eligible queries stay on the writer, so merging
+    /// this seam is a true no-op until the budget is configured. Every
+    /// failure fails closed to the writer.
+    pub async fn query_events_routed(
+        &self,
+        path: &'static str,
+        q: &EventQuery,
+    ) -> Result<Vec<StoredEvent>> {
+        let predicate = RoutePredicate::for_query(q, self.replica_read_max_age.is_some());
+        match self.route_read(path, predicate).await {
+            RouteDecision::Replica(mut tx, _entry, reason) => {
+                match event::query_events_on(&mut tx, q).await {
+                    Ok(events) => {
+                        Self::record_route(path, "replica", reason);
+                        Ok(events)
+                    }
+                    Err(e) => {
+                        // Mid-query replica failure: fail closed to the
+                        // writer rather than surfacing a routed error.
+                        tracing::warn!(path, "replica read failed; re-running on writer: {e}");
+                        Self::record_route(path, "writer", "replica_error");
+                        event::query_events(&self.pool, q).await
+                    }
+                }
+            }
+            RouteDecision::Writer => event::query_events(&self.pool, q).await,
+        }
+    }
+
+    /// [`Db::query_events_routed`] restricted to the BOUNDED arm — for
+    /// reads whose result feeds a COUNT rather than a displayed page.
+    ///
+    /// The covered arm bounds insert-completeness only; stale deletions can
+    /// briefly inflate the result set (see [`RoutePredicate::Covered`]). A
+    /// display page absorbs that per-row; a number derived from the rows
+    /// does not. Same classification-table requirement as
+    /// [`Db::query_events_routed`].
+    pub async fn query_events_routed_bounded(
+        &self,
+        path: &'static str,
+        q: &EventQuery,
+    ) -> Result<Vec<StoredEvent>> {
+        match self.route_read(path, RoutePredicate::Bounded).await {
+            RouteDecision::Replica(mut tx, _entry, reason) => {
+                match event::query_events_on(&mut tx, q).await {
+                    Ok(events) => {
+                        Self::record_route(path, "replica", reason);
+                        Ok(events)
+                    }
+                    Err(e) => {
+                        tracing::warn!(path, "replica read failed; re-running on writer: {e}");
+                        Self::record_route(path, "writer", "replica_error");
+                        event::query_events(&self.pool, q).await
+                    }
+                }
+            }
+            RouteDecision::Writer => event::query_events(&self.pool, q).await,
+        }
+    }
+
     /// Count events matching the given query (NIP-45 COUNT support).
+    ///
+    /// Always reads from the WRITER pool — see [`Db::query_events`] for the
+    /// writer-vs-routed rule.
     pub async fn count_events(&self, q: &EventQuery) -> Result<i64> {
         event::count_events(&self.pool, q).await
     }
 
+    /// [`Db::count_events`] with replica routing — same contract, rules,
+    /// and classification-table requirement as [`Db::query_events_routed`].
+    ///
+    /// Counts route on the BOUNDED arm only, never covered: the covered
+    /// arm bounds insert-completeness but not deletion visibility (soft
+    /// deletes are UPDATEs outside the floor guard), and a count has no
+    /// downstream per-row re-filter to absorb extra rows — a silently
+    /// inflated number for up to `FENCE_STALENESS` is a different product
+    /// statement than a page briefly showing a deleted row. `Bounded` ties
+    /// the error to the accepted budget `B`.
+    pub async fn count_events_routed(&self, path: &'static str, q: &EventQuery) -> Result<i64> {
+        match self.route_read(path, RoutePredicate::Bounded).await {
+            RouteDecision::Replica(mut tx, _entry, reason) => {
+                match event::count_events_on(&mut tx, q).await {
+                    Ok(count) => {
+                        Self::record_route(path, "replica", reason);
+                        Ok(count)
+                    }
+                    Err(e) => {
+                        tracing::warn!(path, "replica count failed; re-running on writer: {e}");
+                        Self::record_route(path, "writer", "replica_error");
+                        event::count_events(&self.pool, q).await
+                    }
+                }
+            }
+            RouteDecision::Writer => event::count_events(&self.pool, q).await,
+        }
+    }
+
     /// Return whether a creator-signed huddle-start event links a parent
     /// channel to an ephemeral huddle channel.
     pub async fn huddle_started_link_exists(
@@ -1165,16 +1813,27 @@ impl Db {
         event::soft_delete_event(&self.pool, community_id, event_id).await
     }
 
-    /// Soft-delete the live row for an addressable coordinate `(kind, pubkey, d_tag)`.
-    /// Used by NIP-09 a-tag deletion for parameterized-replaceable kinds.
+    /// Soft-delete the live row for an addressable coordinate `(kind, pubkey, d_tag)`
+    /// when it is not newer than the deletion request.
+    /// Used by NIP-09 a-tag deletion for parameterized-replaceable kinds;
+    /// `deletion_created_at_secs` is the deletion event's `created_at`.
     pub async fn soft_delete_by_coordinate(
         &self,
         community_id: CommunityId,
         kind: i32,
         pubkey: &[u8],
         d_tag: &str,
+        deletion_created_at_secs: i64,
     ) -> Result<bool> {
-        event::soft_delete_by_coordinate(&self.pool, community_id, kind, pubkey, d_tag).await
+        event::soft_delete_by_coordinate(
+            &self.pool,
+            community_id,
+            kind,
+            pubkey,
+            d_tag,
+            deletion_created_at_secs,
+        )
+        .await
     }
 
     /// Atomically soft-delete an event and decrement thread reply counters.
@@ -1222,6 +1881,37 @@ impl Db {
         event::get_events_by_ids(&self.pool, community_id, ids).await
     }
 
+    /// [`Db::get_events_by_ids`] with replica routing — same contract and
+    /// classification-table requirement as [`Db::query_events_routed`].
+    ///
+    /// By-id fetches route on the BOUNDED arm only: an id list carries no
+    /// channel pin, so no fence floor can prove insert-completeness — the
+    /// covered arm is structurally unavailable. Used for FTS hit hydration,
+    /// where a missing row degrades to a skipped search hit downstream.
+    pub async fn get_events_by_ids_routed(
+        &self,
+        path: &'static str,
+        community_id: CommunityId,
+        ids: &[&[u8]],
+    ) -> Result<Vec<StoredEvent>> {
+        match self.route_read(path, RoutePredicate::Bounded).await {
+            RouteDecision::Replica(mut tx, _entry, reason) => {
+                match event::get_events_by_ids_on(&mut tx, community_id, ids).await {
+                    Ok(events) => {
+                        Self::record_route(path, "replica", reason);
+                        Ok(events)
+                    }
+                    Err(e) => {
+                        tracing::warn!(path, "replica read failed; re-running on writer: {e}");
+                        Self::record_route(path, "writer", "replica_error");
+                        event::get_events_by_ids(&self.pool, community_id, ids).await
+                    }
+                }
+            }
+            RouteDecision::Writer => event::get_events_by_ids(&self.pool, community_id, ids).await,
+        }
+    }
+
     /// Exclusively claim a batch of due matcher jobs from one community.
     pub async fn claim_due_push_match_batch(
         &self,
@@ -1990,19 +2680,25 @@ impl Db {
 
     /// Fetch replies under a root event.
     ///
-    /// Routing: the head fetch (`cursor: None`) always reads the writer.
-    /// Cursor-bearing pages may read the replica pool when one is configured
-    /// AND the freshness fence is open ([`replica_fence`]). Thread pagination
-    /// walks forward from oldest to newest, so a replica page is served only
-    /// when it is provably complete:
+    /// Routing mirrors [`Db::get_channel_window_with_session`]: a head
+    /// fetch (`cursor: None`) is Predicate A (bounded staleness, gated by
+    /// the default-off head budget); cursor pages are Predicate B
+    /// (completeness). Thread pagination walks **forward** from oldest to
+    /// newest, so a cursor carries no upper bound — instead the served page
+    /// is post-verified against the wall the serving session proved:
     ///
     /// - an under-`limit` page is a candidate terminal page — the client
     ///   treats it as EOF, so it is re-run on the writer to keep the EOF
     ///   decision authoritative (a lagged replica could truncate the tail);
-    /// - a full page whose newest row exceeds the fence could straddle a row
-    ///   the replica has not replayed (commit order is not `created_at`
-    ///   order), so it is also re-run on the writer. Only a full page that
-    ///   sits entirely at or below the fence is served from the replica.
+    /// - a full page whose newest row exceeds the proved fence wall could
+    ///   straddle a row the session has not replayed (commit order is not
+    ///   `created_at` order), so it is also re-run on the writer. Only a
+    ///   full page that sits entirely at or below the proved wall is served
+    ///   from the replica.
+    ///
+    /// A head fetch routed under Predicate A skips the re-run: bounded
+    /// staleness (missing at most the freshest budget-window of replies) is
+    /// exactly the semantic the head gate accepts.
     pub async fn get_thread_replies(
         &self,
         community_id: CommunityId,
@@ -2011,25 +2707,59 @@ impl Db {
         limit: u32,
         cursor: Option<&[u8]>,
     ) -> Result<Vec<thread::ThreadReply>> {
-        if cursor.is_some() && self.has_read_pool() && self.fence.verified_through().is_some() {
-            let replies = thread::get_thread_replies(
-                self.read(),
+        let (path, predicate): (&'static str, RoutePredicate) = match cursor {
+            Some(_) => (
+                "thread_cursor",
+                RoutePredicate::CoveredPostVerified {
+                    proof: ChannelScoped::from_thread_metadata_join(),
+                },
+            ),
+            None => ("thread_head", RoutePredicate::Bounded),
+        };
+        if let RouteDecision::Replica(mut tx, entry, reason) =
+            self.route_read(path, predicate).await
+        {
+            match thread::get_thread_replies_on(
+                &mut tx,
                 community_id,
                 root_event_id,
                 depth_limit,
                 limit,
                 cursor,
             )
-            .await?;
-            let full = replies.len() >= limit as usize;
-            let below_fence = replies
-                .last()
-                .is_some_and(|tail| self.fence.covers(tail.created_at));
-            if full && below_fence {
-                return Ok(replies);
+            .await
+            {
+                Ok(replies) => {
+                    if cursor.is_none() {
+                        // Predicate A: bounded-stale head page, served as proved.
+                        Self::record_route(path, "replica", reason);
+                        return Ok(replies);
+                    }
+                    let full = replies.len() >= limit as usize;
+                    let below_fence = replies
+                        .last()
+                        .is_some_and(|tail| tail.created_at <= entry.fence_wall);
+                    if full && below_fence {
+                        Self::record_route(path, "replica", reason);
+                        return Ok(replies);
+                    }
+                    // Candidate terminal page, or page reaching above the
+                    // proved wall — verify against the writer. Recorded as
+                    // the request's ONLY route event: the replica leg was
+                    // discarded, so counting it would overstate offload.
+                    Self::record_route("thread_eof", "writer", "stale");
+                }
+                Err(e) => {
+                    // Mid-request replica failure (e.g. a hot-standby
+                    // recovery conflict) fails closed to the writer.
+                    tracing::warn!(
+                        error = %e,
+                        path,
+                        "replica thread query failed; re-running on writer"
+                    );
+                    Self::record_route(path, "writer", "replica_error");
+                }
             }
-            // Candidate terminal page, or page reaching above the fence —
-            // verify against the writer.
         }
         thread::get_thread_replies(
             &self.pool,
@@ -2053,15 +2783,8 @@ impl Db {
 
     /// One channel window: top-level rows + summaries + server `has_more`.
     ///
-    /// Routing: the head fetch (`cursor: None`) always reads the writer — it
-    /// must include just-committed events. A cursor-bearing page scrolls
-    /// *backward* into history bounded above by the cursor timestamp
-    /// (`created_at < ts`, or `= ts` with the id tiebreak), so it may read
-    /// the replica when one is configured AND the freshness fence covers the
-    /// cursor timestamp: every row the page could contain is then provably
-    /// replayed on the replica ([`replica_fence`]). Pages whose cursor
-    /// reaches above the fence — the freshest sliver of history — stay on
-    /// the writer.
+    /// Convenience wrapper over [`Db::get_channel_window_with_session`] for
+    /// callers with no follow-up queries; the serving session is released.
     pub async fn get_channel_window(
         &self,
         community_id: CommunityId,
@@ -2070,11 +2793,199 @@ impl Db {
         cursor: Option<(DateTime<Utc>, Vec<u8>)>,
         kind_filter: Option<&[u32]>,
     ) -> Result<thread::ChannelWindow> {
-        let pool = match &cursor {
-            Some((ts, _)) if self.has_read_pool() && self.fence.covers(*ts) => self.read(),
-            _ => &self.pool,
+        self.get_channel_window_with_session(community_id, channel_id, limit, cursor, kind_filter)
+            .await
+            .map(|(window, _session)| window)
+    }
+
+    /// [`Db::get_channel_window`], additionally returning the session that
+    /// served the page so request-scoped follow-ups (the aux closure) run on
+    /// the same proved connection.
+    ///
+    /// Routing:
+    ///
+    /// - **Cursor page** (Predicate B — completeness): scrolls *backward*
+    ///   into history bounded above by the cursor timestamp (`created_at <
+    ///   ts`, or `= ts` with the id tiebreak), so it may be served by a
+    ///   replica session when one is configured AND that session **proves**
+    ///   coverage of the cursor timestamp: the heartbeat token/epoch is
+    ///   observed on the exact connection that will serve the page and
+    ///   resolved against the fence's retained ring ([`replica_fence`]).
+    /// - **Head fetch** (Predicate A — bounded staleness): served by a
+    ///   proved replica session only when the head gate is configured
+    ///   ([`DbConfig::replica_read_max_age_ms`], default off) and the
+    ///   proved entry is within the budget. This trades a bounded staleness
+    ///   window (budget plus probe cadence) on the GET leg for writer
+    ///   offload. NOTE: enabling the budget also breaks read-your-own-writes
+    ///   on the GET leg; the client-side WS `since`-overlap union intended
+    ///   to cover fresh events has NOT shipped yet — do not enable
+    ///   `BUZZ_REPLICA_HEAD_MAX_AGE_SECS` until it has, proven by a
+    ///   post-then-immediately-refetch test.
+    ///
+    /// Every failure fails closed to the writer and is recorded in
+    /// `buzz_db_route_decision`.
+    pub async fn get_channel_window_with_session(
+        &self,
+        community_id: CommunityId,
+        channel_id: Uuid,
+        limit: u32,
+        cursor: Option<(DateTime<Utc>, Vec<u8>)>,
+        kind_filter: Option<&[u32]>,
+    ) -> Result<(thread::ChannelWindow, ReadSession)> {
+        let path: &'static str = if cursor.is_some() {
+            "channel_cursor"
+        } else {
+            "channel_head"
+        };
+        match self
+            .route_read(
+                path,
+                RoutePredicate::from_channel_cursor(channel_id, &cursor),
+            )
+            .await
+        {
+            RouteDecision::Replica(mut tx, _entry, reason) => {
+                match thread::get_channel_window_on(
+                    &mut tx,
+                    community_id,
+                    channel_id,
+                    limit,
+                    cursor.clone(),
+                    kind_filter,
+                )
+                .await
+                {
+                    Ok(window) => {
+                        Self::record_route(path, "replica", reason);
+                        return Ok((
+                            window,
+                            ReadSession {
+                                inner: ReadSessionInner::Replica {
+                                    tx,
+                                    writer: self.pool.clone(),
+                                },
+                            },
+                        ));
+                    }
+                    Err(e) => {
+                        // A mid-request replica failure (e.g. a hot-standby
+                        // recovery conflict cancelling the held snapshot)
+                        // fails closed to the writer: a stale-but-served
+                        // page, never an error the writer could have
+                        // answered. Dropping `tx` rolls the reader
+                        // transaction back.
+                        tracing::warn!(
+                            error = %e,
+                            path,
+                            "replica window query failed; re-running on writer"
+                        );
+                        Self::record_route(path, "writer", "replica_error");
+                    }
+                }
+            }
+            RouteDecision::Writer => {}
+        }
+        let window = thread::get_channel_window(
+            &self.pool,
+            community_id,
+            channel_id,
+            limit,
+            cursor,
+            kind_filter,
+        )
+        .await?;
+        Ok((
+            window,
+            ReadSession {
+                inner: ReadSessionInner::Writer(self.pool.clone()),
+            },
+        ))
+    }
+
+    /// Shared route decision for one read: evaluate the predicate against a
+    /// proved reader session and record the decision. Fail closed to the
+    /// writer everywhere.
+    async fn route_read(&self, path: &'static str, predicate: RoutePredicate) -> RouteDecision {
+        let Some(read_pool) = &self.read_pool else {
+            Self::record_route(path, "writer", "disabled");
+            return RouteDecision::Writer;
+        };
+        // Cheap prechecks on the shared ring before spending a reader
+        // checkout; the connection-local observation still has to prove it.
+        let Some(newest) = self.fence.newest() else {
+            Self::record_route(path, "writer", "uninitialized");
+            return RouteDecision::Writer;
+        };
+        // Precheck helpers against the newest shared entry: if the newest
+        // cannot satisfy an arm, no proved (older-or-equal) entry can.
+        let bounded_precheck =
+            |budget: &Option<Duration>| -> std::result::Result<(), &'static str> {
+                match budget {
+                    Some(budget) if newest.committed_at.elapsed() <= *budget => Ok(()),
+                    Some(_) => Err("stale"),
+                    None => Err("disabled"),
+                }
+            };
+        let covered_precheck = |upper: &DateTime<Utc>| -> std::result::Result<(), &'static str> {
+            if *upper <= newest.fence_wall {
+                Ok(())
+            } else {
+                Err("stale")
+            }
         };
-        thread::get_channel_window(pool, community_id, channel_id, limit, cursor, kind_filter).await
+        let precheck = match &predicate {
+            RoutePredicate::Bounded => bounded_precheck(&self.replica_read_max_age),
+            RoutePredicate::Covered { upper, .. } => covered_precheck(upper),
+            // No upper bound: the caller post-verifies served rows.
+            RoutePredicate::CoveredPostVerified { .. } => Ok(()),
+            // Covered first (no budget dependence), else bounded.
+            RoutePredicate::BoundedOrCovered { upper, .. } => {
+                covered_precheck(upper).or_else(|_| bounded_precheck(&self.replica_read_max_age))
+            }
+        };
+        if let Err(reason) = precheck {
+            Self::record_route(path, "writer", reason);
+            return RouteDecision::Writer;
+        }
+        match self.proved_reader(read_pool).await {
+            Ok((tx, entry)) => {
+                // Re-evaluate against the entry the session actually proved
+                // (it may be older than the shared newest).
+                let bounded_holds = || {
+                    self.replica_read_max_age
+                        .is_some_and(|budget| entry.committed_at.elapsed() <= budget)
+                };
+                let verdict: Option<&'static str> = match &predicate {
+                    RoutePredicate::Bounded => bounded_holds().then_some("fresh"),
+                    RoutePredicate::Covered { upper, .. } => {
+                        (*upper <= entry.fence_wall).then_some("covered")
+                    }
+                    // No upper bound: the caller post-verifies the served
+                    // rows against the proved wall.
+                    RoutePredicate::CoveredPostVerified { .. } => Some("covered"),
+                    RoutePredicate::BoundedOrCovered { upper, .. } => {
+                        if *upper <= entry.fence_wall {
+                            Some("covered")
+                        } else {
+                            bounded_holds().then_some("fresh")
+                        }
+                    }
+                };
+                match verdict {
+                    Some(reason) => RouteDecision::Replica(tx, entry, reason),
+                    None => {
+                        // The session proves an older entry than the
+                        // predicate needs (replication lag) — fail closed.
+                        Self::record_route(path, "writer", "stale");
+                        RouteDecision::Writer
+                    }
+                }
+            }
+            Err(reason) => {
+                Self::record_route(path, "writer", reason);
+                RouteDecision::Writer
+            }
+        }
     }
 
     /// Look up a single thread_metadata row by event_id.
@@ -2239,6 +3150,67 @@ impl Db {
         .await
     }
 
+    /// [`Db::query_feed_mentions`] with replica routing — same contract and
+    /// classification-table requirement as [`Db::query_events_routed`].
+    ///
+    /// Feed queries route on the BOUNDED arm only: the `accessible_channel_ids`
+    /// parameter admits community-global rows alongside channel rows, so no
+    /// single channel's fence floor can prove completeness — the covered arm
+    /// is structurally unavailable, not merely unchosen.
+    pub async fn query_feed_mentions_routed(
+        &self,
+        path: &'static str,
+        community: CommunityId,
+        pubkey_bytes: &[u8],
+        accessible_channel_ids: &[Uuid],
+        since: Option<DateTime<Utc>>,
+        limit: i64,
+    ) -> Result<Vec<StoredEvent>> {
+        match self.route_read(path, RoutePredicate::Bounded).await {
+            RouteDecision::Replica(mut tx, _entry, reason) => {
+                match feed::query_mentions_on(
+                    &mut tx,
+                    community,
+                    pubkey_bytes,
+                    accessible_channel_ids,
+                    since,
+                    limit,
+                )
+                .await
+                {
+                    Ok(events) => {
+                        Self::record_route(path, "replica", reason);
+                        Ok(events)
+                    }
+                    Err(e) => {
+                        tracing::warn!(path, "replica read failed; re-running on writer: {e}");
+                        Self::record_route(path, "writer", "replica_error");
+                        feed::query_mentions(
+                            &self.pool,
+                            community,
+                            pubkey_bytes,
+                            accessible_channel_ids,
+                            since,
+                            limit,
+                        )
+                        .await
+                    }
+                }
+            }
+            RouteDecision::Writer => {
+                feed::query_mentions(
+                    &self.pool,
+                    community,
+                    pubkey_bytes,
+                    accessible_channel_ids,
+                    since,
+                    limit,
+                )
+                .await
+            }
+        }
+    }
+
     /// Find events that require action from the given pubkey.
     pub async fn query_feed_needs_action(
         &self,
@@ -2259,6 +3231,63 @@ impl Db {
         .await
     }
 
+    /// [`Db::query_feed_needs_action`] with replica routing — BOUNDED arm
+    /// only; see [`Db::query_feed_mentions_routed`] for why the covered arm
+    /// is structurally unavailable to feed queries.
+    pub async fn query_feed_needs_action_routed(
+        &self,
+        path: &'static str,
+        community: CommunityId,
+        pubkey_bytes: &[u8],
+        accessible_channel_ids: &[Uuid],
+        since: Option<DateTime<Utc>>,
+        limit: i64,
+    ) -> Result<Vec<StoredEvent>> {
+        match self.route_read(path, RoutePredicate::Bounded).await {
+            RouteDecision::Replica(mut tx, _entry, reason) => {
+                match feed::query_needs_action_on(
+                    &mut tx,
+                    community,
+                    pubkey_bytes,
+                    accessible_channel_ids,
+                    since,
+                    limit,
+                )
+                .await
+                {
+                    Ok(events) => {
+                        Self::record_route(path, "replica", reason);
+                        Ok(events)
+                    }
+                    Err(e) => {
+                        tracing::warn!(path, "replica read failed; re-running on writer: {e}");
+                        Self::record_route(path, "writer", "replica_error");
+                        feed::query_needs_action(
+                            &self.pool,
+                            community,
+                            pubkey_bytes,
+                            accessible_channel_ids,
+                            since,
+                            limit,
+                        )
+                        .await
+                    }
+                }
+            }
+            RouteDecision::Writer => {
+                feed::query_needs_action(
+                    &self.pool,
+                    community,
+                    pubkey_bytes,
+                    accessible_channel_ids,
+                    since,
+                    limit,
+                )
+                .await
+            }
+        }
+    }
+
     /// Find recent activity across accessible channels.
     pub async fn query_feed_activity(
         &self,
@@ -2270,6 +3299,53 @@ impl Db {
         feed::query_activity(&self.pool, community, accessible_channel_ids, since, limit).await
     }
 
+    /// [`Db::query_feed_activity`] with replica routing — BOUNDED arm only;
+    /// see [`Db::query_feed_mentions_routed`] for why the covered arm is
+    /// structurally unavailable to feed queries.
+    pub async fn query_feed_activity_routed(
+        &self,
+        path: &'static str,
+        community: CommunityId,
+        accessible_channel_ids: &[Uuid],
+        since: Option<DateTime<Utc>>,
+        limit: i64,
+    ) -> Result<Vec<StoredEvent>> {
+        match self.route_read(path, RoutePredicate::Bounded).await {
+            RouteDecision::Replica(mut tx, _entry, reason) => {
+                match feed::query_activity_on(
+                    &mut tx,
+                    community,
+                    accessible_channel_ids,
+                    since,
+                    limit,
+                )
+                .await
+                {
+                    Ok(events) => {
+                        Self::record_route(path, "replica", reason);
+                        Ok(events)
+                    }
+                    Err(e) => {
+                        tracing::warn!(path, "replica read failed; re-running on writer: {e}");
+                        Self::record_route(path, "writer", "replica_error");
+                        feed::query_activity(
+                            &self.pool,
+                            community,
+                            accessible_channel_ids,
+                            since,
+                            limit,
+                        )
+                        .await
+                    }
+                }
+            }
+            RouteDecision::Writer => {
+                feed::query_activity(&self.pool, community, accessible_channel_ids, since, limit)
+                    .await
+            }
+        }
+    }
+
     /// Create a new API token record.
     #[allow(clippy::too_many_arguments)]
     pub async fn create_api_token(
@@ -2923,8 +3999,33 @@ impl Db {
     }
 
     /// Returns `true` if `pubkey` (64-char hex) is a member of `community`.
+    ///
+    /// Replica-routed on the bounded arm — the one PERMISSION read routed by
+    /// explicit product decision (bounded-stale membership beats the 10s
+    /// cache it replaced). Admits and revokes may lag by at most the budget
+    /// `B`; everything else fails closed to the writer, exactly like
+    /// [`Db::query_events_routed_bounded`]. Not precedent for routing other
+    /// permission reads.
     pub async fn is_relay_member(&self, community: CommunityId, pubkey: &str) -> Result<bool> {
-        relay_members::is_relay_member(&self.pool, community, pubkey).await
+        let path = "relay_membership";
+        match self.route_read(path, RoutePredicate::Bounded).await {
+            RouteDecision::Replica(mut tx, _entry, reason) => {
+                match relay_members::is_relay_member_on(&mut tx, community, pubkey).await {
+                    Ok(is_member) => {
+                        Self::record_route(path, "replica", reason);
+                        Ok(is_member)
+                    }
+                    Err(e) => {
+                        tracing::warn!(path, "replica read failed; re-running on writer: {e}");
+                        Self::record_route(path, "writer", "replica_error");
+                        relay_members::is_relay_member(&self.pool, community, pubkey).await
+                    }
+                }
+            }
+            RouteDecision::Writer => {
+                relay_members::is_relay_member(&self.pool, community, pubkey).await
+            }
+        }
     }
 
     /// Returns the relay member record for `pubkey` in `community`, or `None` if not found.
@@ -3020,6 +4121,12 @@ impl Db {
         relay_members::bootstrap_owner(&self.pool, community, owner_pubkey).await
     }
 
+    /// Returns `true` if any member of `community` holds the `admin` or
+    /// `owner` role.
+    pub async fn has_admin_or_owner(&self, community: CommunityId) -> Result<bool> {
+        relay_members::has_admin_or_owner(&self.pool, community).await
+    }
+
     /// Atomically transfers ownership of `community` to `new_owner_pubkey`,
     /// demoting the previous owner(s) to `member`. Verifies
     /// `expected_owner_pubkey` matches the current owner inside the same
@@ -4164,23 +5271,92 @@ mod tests {
 
     #[tokio::test]
     #[ignore = "requires Postgres"]
-    async fn duplicate_nip_rs_discriminator_tags_keep_legacy_retention() {
+    async fn coordinate_delete_spares_head_newer_than_the_deletion() {
         use nostr::{EventBuilder, Keys, Kind, Tag, Timestamp};
 
         let db = setup_db().await;
         let community = CommunityId::from_uuid(make_community(&db.pool).await);
         let keys = Keys::generate();
+        let kind = buzz_core::kind::KIND_PROJECT as i32;
+        let d_tag = "stale-tombstone-project";
+        let pubkey = keys.public_key().to_bytes().to_vec();
         let base = Timestamp::now().as_secs();
 
-        for (case, tags) in [
-            (
-                "duplicate-d",
-                vec![
-                    Tag::parse(["d", &format!("read-state:{}", "c".repeat(32))])
-                        .expect("first d tag"),
-                    Tag::parse(["d", &format!("read-state:{}", "d".repeat(32))])
-                        .expect("second d tag"),
-                    Tag::parse(["t", "read-state"]).expect("t tag"),
+        let version = |content: &str, offset: u64| {
+            EventBuilder::new(Kind::Custom(buzz_core::kind::KIND_PROJECT as u16), content)
+                .tags(vec![Tag::parse(["d", d_tag]).expect("d tag")])
+                .custom_created_at(Timestamp::from(base + offset))
+                .sign_with_keys(&keys)
+                .expect("sign project version")
+        };
+
+        for (content, offset) in [("v1", 0), ("v2", 100)] {
+            assert!(
+                db.replace_parameterized_event(community, &version(content, offset), d_tag, None)
+                    .await
+                    .expect("store project version")
+                    .1
+            );
+        }
+
+        // Tombstone timestamped between V1 and V2: it authorizes deleting V1,
+        // never the newer head that replaced it.
+        let stale_deleted = db
+            .soft_delete_by_coordinate(community, kind, &pubkey, d_tag, (base + 50) as i64)
+            .await
+            .expect("stale coordinate delete");
+        assert!(
+            !stale_deleted,
+            "a tombstone older than the live head must delete nothing"
+        );
+
+        let live_content: Option<String> = sqlx::query_scalar(
+            "SELECT content FROM events \
+             WHERE community_id=$1 AND kind=$2 AND pubkey=$3 AND d_tag=$4 AND deleted_at IS NULL",
+        )
+        .bind(community.as_uuid())
+        .bind(kind)
+        .bind(&pubkey)
+        .bind(d_tag)
+        .fetch_optional(&db.pool)
+        .await
+        .expect("read live head");
+        assert_eq!(
+            live_content.as_deref(),
+            Some("v2"),
+            "the newer head must survive a stale tombstone"
+        );
+
+        // A tombstone at or after the head's own timestamp still deletes it.
+        let current_deleted = db
+            .soft_delete_by_coordinate(community, kind, &pubkey, d_tag, (base + 100) as i64)
+            .await
+            .expect("current coordinate delete");
+        assert!(
+            current_deleted,
+            "a tombstone at the head's timestamp must delete it (NIP-09 is at-or-before)"
+        );
+    }
+
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn duplicate_nip_rs_discriminator_tags_keep_legacy_retention() {
+        use nostr::{EventBuilder, Keys, Kind, Tag, Timestamp};
+
+        let db = setup_db().await;
+        let community = CommunityId::from_uuid(make_community(&db.pool).await);
+        let keys = Keys::generate();
+        let base = Timestamp::now().as_secs();
+
+        for (case, tags) in [
+            (
+                "duplicate-d",
+                vec![
+                    Tag::parse(["d", &format!("read-state:{}", "c".repeat(32))])
+                        .expect("first d tag"),
+                    Tag::parse(["d", &format!("read-state:{}", "d".repeat(32))])
+                        .expect("second d tag"),
+                    Tag::parse(["t", "read-state"]).expect("t tag"),
                 ],
             ),
             (
@@ -4715,15 +5891,21 @@ mod tests {
     #[tokio::test]
     #[ignore = "requires Postgres"]
     async fn test_usage_metrics_lock_has_single_owner_and_releases_on_drop() {
-        let database_url =
-            std::env::var("TEST_DATABASE_URL").unwrap_or_else(|_| TEST_DB_URL.into());
-        let pool = PgPoolOptions::new()
-            .max_connections(2)
-            .connect(&database_url)
+        // Use a private scratch database — not the shared TEST_DATABASE_URL.
+        // Postgres advisory locks are per-database; hardcoding the production
+        // USAGE_METRICS_LOCK_KEY (0x4255_5A5A_4D45_5452) on the shared test DB
+        // races any live buzz-relay on the same database (see #3619).
+        let admin_url = std::env::var("TEST_DATABASE_URL").unwrap_or_else(|_| TEST_DB_URL.into());
+        let admin = PgPoolOptions::new()
+            .max_connections(1)
+            .connect(&admin_url)
             .await
-            .expect("connect to test DB");
+            .expect("connect admin to create scratch db");
+        let (pool, scratch_name) = create_scratch_db(&admin, "usage_metrics_lock").await;
         let first = Db::from_pool(pool.clone());
-        let second = Db::from_pool(pool);
+        let second = Db::from_pool(pool.clone());
+        // Same key as production (`buzz-relay` USAGE_METRICS_LOCK_KEY) — safe here
+        // because the scratch DB is empty of other holders.
         let key = 0x4255_5A5A_4D45_5452;
 
         let mut leader = first
@@ -4750,6 +5932,11 @@ mod tests {
                 .is_some(),
             "dropping the detached session releases its advisory lock"
         );
+
+        // Release any remaining session state before DROP DATABASE.
+        drop(first);
+        drop(second);
+        drop_scratch_db(&admin, pool, &scratch_name).await;
     }
 
     #[tokio::test]
@@ -5436,6 +6623,163 @@ mod tests {
         assert!(db.read_pool_stats().is_none());
     }
 
+    #[test]
+    fn read_budget_zero_disables_and_large_values_clamp_to_staleness() {
+        assert_eq!(read_budget_from_ms(0), None, "0 = bounded routing off");
+        assert_eq!(
+            read_budget_from_ms(1000),
+            Some(std::time::Duration::from_millis(1000))
+        );
+        assert_eq!(
+            read_budget_from_ms(10_000_000),
+            Some(replica_fence::FENCE_STALENESS),
+            "budgets above the staleness gate clamp to it"
+        );
+    }
+
+    /// Truth table for [`RoutePredicate::for_query`]: the strongest sound
+    /// predicate per query shape, and — the deploy-day default row — that
+    /// `routing_enabled = false` (BUZZ_REPLICA_READ_MAX_AGE_MS unset)
+    /// forces `Bounded` even for covered-eligible shapes, so the zero
+    /// budget fails the new seams closed (Dawn's covered-at-zero-budget
+    /// catch, design doc rev 5).
+    #[test]
+    fn for_query_predicate_truth_table() {
+        let community = CommunityId::from_uuid(Uuid::new_v4());
+        let channel = Uuid::new_v4();
+        let until = chrono::Utc::now();
+
+        let pinned_with_until = {
+            let mut q = event::EventQuery::for_community(community);
+            q.channel_id = Some(channel);
+            q.until = Some(until);
+            q
+        };
+        let pinned_no_until = {
+            let mut q = event::EventQuery::for_community(community);
+            q.channel_id = Some(channel);
+            q
+        };
+        let unpinned_with_until = {
+            let mut q = event::EventQuery::for_community(community);
+            q.until = Some(until);
+            q
+        };
+        let global_only = {
+            let mut q = event::EventQuery::for_community(community);
+            q.global_only = true;
+            q.until = Some(until);
+            q
+        };
+
+        // Deploy-day default: budget unset ⇒ Bounded regardless of shape.
+        // The zero budget then fails Bounded closed, so the new seams
+        // record writer/disabled — merging with no env var set is a no-op.
+        assert!(
+            matches!(
+                RoutePredicate::for_query(&pinned_with_until, false),
+                RoutePredicate::Bounded
+            ),
+            "budget unset must not reach the covered arm even when eligible"
+        );
+
+        // Budget set + channel pin + until ⇒ the strongest predicate.
+        assert!(matches!(
+            RoutePredicate::for_query(&pinned_with_until, true),
+            RoutePredicate::BoundedOrCovered { .. }
+        ));
+
+        // Missing either covered precondition ⇒ Bounded.
+        assert!(matches!(
+            RoutePredicate::for_query(&pinned_no_until, true),
+            RoutePredicate::Bounded
+        ));
+        assert!(matches!(
+            RoutePredicate::for_query(&unpinned_with_until, true),
+            RoutePredicate::Bounded
+        ));
+        // global_only implies `channel_id = None`, so the channel-pin
+        // precondition fails and no covered arm is possible — `for_query`
+        // never inspects `global_only` itself; the row holds because
+        // constructor 1 (channel pin) returns None for an unpinned query.
+        assert!(matches!(
+            RoutePredicate::for_query(&global_only, true),
+            RoutePredicate::Bounded
+        ));
+    }
+
+    /// The pre-existing cursor paths are NOT budget-gated: a channel-window
+    /// cursor page still derives `Covered` with no `routing_enabled` input
+    /// at all — at B=0 today it routes covered, and that status quo is
+    /// intentionally unchanged by the `for_query` gate (Max's matrix row:
+    /// old paths route at budget-unset; only the new seams go dark).
+    #[test]
+    fn channel_cursor_predicate_is_not_budget_gated() {
+        let channel = Uuid::new_v4();
+        let cursor = Some((chrono::Utc::now(), vec![1u8; 32]));
+        assert!(matches!(
+            RoutePredicate::from_channel_cursor(channel, &cursor),
+            RoutePredicate::Covered { .. }
+        ));
+        // Head fetch (no cursor) is bounded — gated by the budget.
+        assert!(matches!(
+            RoutePredicate::from_channel_cursor(channel, &None),
+            RoutePredicate::Bounded
+        ));
+    }
+
+    /// D5 wiring: `read_pool_stats().max` must be the READER pool's own
+    /// ceiling, not the writer's — `buzz_db_read_pool_active / _max` is the
+    /// operator's utilisation signal and inheriting the writer's max hides
+    /// reader saturation by exactly the sizing ratio. Pure wiring test:
+    /// `connect_lazy` never touches the network, but it does spawn the
+    /// pool reaper task, which needs a Tokio runtime — hence
+    /// `#[tokio::test]` despite the test body itself never awaiting.
+    #[tokio::test]
+    async fn read_pool_stats_reports_reader_ceiling_not_writer() {
+        let writer = sqlx::postgres::PgPoolOptions::new()
+            .max_connections(20)
+            .connect_lazy(TEST_DB_URL)
+            .expect("lazy writer pool");
+        let reader = sqlx::postgres::PgPoolOptions::new()
+            .max_connections(40)
+            .connect_lazy(TEST_DB_URL)
+            .expect("lazy reader pool");
+        let db = Db::from_pools(writer, reader);
+        assert_eq!(db.pool_stats().max, 20);
+        assert_eq!(
+            db.read_pool_stats().expect("read pool configured").max,
+            40,
+            "reader gauge must report the reader's own ceiling"
+        );
+    }
+
+    /// D4 wiring: the reader pool is built lazily with `min_connections(0)`
+    /// and the short reader acquire timeout — construction must succeed
+    /// with no replica listening (reader-down at boot must not crash the
+    /// relay), and `read_max_connections` must honour
+    /// `DbConfig::read_max_connections` over the writer sizing.
+    /// `#[tokio::test]` because `connect_lazy` spawns the pool reaper task,
+    /// which needs a Tokio runtime even though nothing is dialed.
+    #[tokio::test]
+    async fn connect_read_pool_is_lazy_and_independently_sized() {
+        let config = DbConfig {
+            max_connections: 20,
+            read_max_connections: Some(7),
+            ..DbConfig::default()
+        };
+        // Unroutable per RFC 5737 TEST-NET-1: proves nothing is dialed at
+        // construction time.
+        let pool = Db::connect_read_pool(&config, "postgres://user:pw@192.0.2.1:5432/none", 7)
+            .expect("lazy construction must not dial the replica");
+        assert_eq!(pool.options().get_max_connections(), 7);
+        assert_eq!(pool.options().get_min_connections(), 0);
+        assert_eq!(
+            pool.options().get_acquire_timeout(),
+            Db::READER_ACQUIRE_TIMEOUT
+        );
+    }
+
     /// Channel window: head fetch (no cursor) reads the WRITER; cursor pages
     /// read the REPLICA. Divergent fixtures prove which pool served each.
     #[tokio::test]
@@ -5519,18 +6863,20 @@ mod tests {
         drop_scratch_db(&admin, writer, &wname).await;
     }
 
-    /// Thread replies: head fetch reads the writer; a FULL cursor page is
-    /// served by the replica; an UNDER-limit cursor page (candidate terminal
-    /// page) is re-run on the writer so a lagged replica can never truncate
-    /// the tail into a false EOF.
+    /// Fail-closed on a mid-request replica failure (Dawn, review of
+    /// 1b0aa0dfa): a replica-routed page whose query errors *after* the
+    /// proof (the live shape is a hot-standby recovery conflict — 40001 /
+    /// 25P02 — cancelling the held snapshot under `max_standby_streaming_delay`)
+    /// must be re-run on the writer and served, never surfaced as an error
+    /// the writer could have answered. Degraded capacity, never holes.
     #[tokio::test]
     #[ignore = "requires Postgres"]
-    async fn thread_replies_cursor_pages_route_to_replica_with_writer_terminal_verification() {
+    async fn replica_window_failure_falls_back_to_writer() {
         let admin = PgPool::connect(&admin_url().await)
             .await
             .expect("connect admin");
-        let (writer, wname) = create_scratch_db(&admin, "routing_tw").await;
-        let (replica, rname) = create_scratch_db(&admin, "routing_tr").await;
+        let (writer, wname) = create_scratch_db(&admin, "fb_w").await;
+        let (replica, rname) = create_scratch_db(&admin, "fb_r").await;
 
         let author = nostr::Keys::generate();
         let community = Uuid::new_v4();
@@ -5539,107 +6885,78 @@ mod tests {
         seed_community_channel(&replica, community, channel, &author).await;
 
         let base = 1_700_000_000u64;
-        let root = signed_event_at(&author, "root", base);
+        let m1 = signed_event_at(&author, "m1", base);
+        let m2 = signed_event_at(&author, "m2", base + 10);
+        let m3 = signed_event_at(&author, "m3", base + 20);
         for pool in [&writer, &replica] {
-            insert_top_level(pool, community, channel, &root).await;
-        }
-
-        // Writer holds replies r1..r5; the lagged replica only has r1..r3.
-        let replies: Vec<nostr::Event> = (1..=5)
-            .map(|i| signed_event_at(&author, &format!("r{i}"), base + 10 * i as u64))
-            .collect();
-        for reply in &replies {
-            insert_thread_reply(&writer, community, channel, &root, reply).await;
-        }
-        for reply in &replies[..3] {
-            insert_thread_reply(&replica, community, channel, &root, reply).await;
+            for ev in [&m1, &m2, &m3] {
+                insert_top_level(pool, community, channel, ev).await;
+            }
         }
+        let marker = signed_event_at(&author, "replica-only-marker", base + 5);
+        insert_top_level(&replica, community, channel, &marker).await;
 
         let db = Db::from_pools(writer.clone(), replica.clone());
-        // Open the fence through "now" — fixture history is far in the past.
         db.fence().force_open_for_tests(chrono::Utc::now());
         let cid = CommunityId::from_uuid(community);
 
-        // Page 1 (no cursor) → writer.
-        let page1 = db
-            .get_thread_replies(cid, root.id.as_bytes(), Some(10), 2, None)
+        let head = db
+            .get_channel_window(cid, channel, 1, None, None)
             .await
-            .expect("page 1");
-        let contents: Vec<&str> = page1
-            .iter()
-            .map(|r| r.stored_event.event.content.as_str())
-            .collect();
-        assert_eq!(contents, vec!["r1", "r2"], "head page from writer");
+            .expect("head window");
+        let cursor = head.next_cursor.expect("has_more implies next_cursor");
 
-        // Page 2: replica serves a FULL page (r3 exists there) — but wait:
-        // replica has r1..r3, page after r2 with limit 2 returns only [r3]
-        // (under limit) → terminal-verification re-runs on the writer, which
-        // returns [r3, r4]. A lag-truncated EOF must never surface.
-        let cur2 = thread_cursor(page1.last().expect("page 1 non-empty"));
-        let page2 = db
-            .get_thread_replies(cid, root.id.as_bytes(), Some(10), 2, Some(&cur2))
+        // Guard against a vacuous pass: the cursor page must actually be
+        // replica-eligible before we break the replica.
+        let healthy = db
+            .get_channel_window(cid, channel, 10, Some(cursor.clone()), None)
             .await
-            .expect("page 2");
-        let contents: Vec<&str> = page2
-            .iter()
-            .map(|r| r.stored_event.event.content.as_str())
-            .collect();
-        assert_eq!(
-            contents,
-            vec!["r3", "r4"],
-            "under-limit replica page must be re-verified on the writer"
+            .expect("healthy cursor window");
+        assert!(
+            healthy
+                .rows
+                .iter()
+                .any(|r| r.stored_event.event.content == "replica-only-marker"),
+            "fixture must route the cursor page to the replica while healthy"
         );
 
-        // Full-page replica serve: with limit 1, the page after r2 is [r3] —
-        // exactly `limit` rows, so the replica result stands. Prove it came
-        // from the replica with a replica-only divergent reply.
-        let ghost = signed_event_at(&author, "replica-only-ghost", base + 25);
-        insert_thread_reply(&replica, community, channel, &root, &ghost).await;
-        let page_replica = db
-            .get_thread_replies(cid, root.id.as_bytes(), Some(10), 1, Some(&cur2))
+        // Break the replica AFTER the proof point: the heartbeat table stays
+        // intact (the observation succeeds), the page query then fails.
+        sqlx::query("DROP TABLE events CASCADE")
+            .execute(&replica)
             .await
-            .expect("full replica page");
-        let contents: Vec<&str> = page_replica
+            .expect("drop replica events");
+
+        let page = db
+            .get_channel_window(cid, channel, 10, Some(cursor), None)
+            .await
+            .expect("replica failure must fall back to the writer, not error");
+        let contents: Vec<&str> = page
+            .rows
             .iter()
             .map(|r| r.stored_event.event.content.as_str())
             .collect();
         assert_eq!(
             contents,
-            vec!["replica-only-ghost"],
-            "a full cursor page must be served by the replica"
+            vec!["m2", "m1"],
+            "fallback page must be the writer's answer (no replica marker)"
         );
 
-        // Same query with no replica configured reads the writer and cannot
-        // see the ghost.
-        let db_writer_only = Db::from_pool(writer.clone());
-        let page_writer = db_writer_only
-            .get_thread_replies(cid, root.id.as_bytes(), Some(10), 1, Some(&cur2))
-            .await
-            .expect("writer-only page");
-        let contents: Vec<&str> = page_writer
-            .iter()
-            .map(|r| r.stored_event.event.content.as_str())
-            .collect();
-        assert_eq!(contents, vec!["r3"], "unset replica falls back to writer");
-
         drop_scratch_db(&admin, replica, &rname).await;
         drop_scratch_db(&admin, writer, &wname).await;
     }
 
-    /// Channel DESC scrollback, out-of-order commit adversary: the replica is
-    /// missing a MIDDLE row (`m2`) because a transaction with an older
-    /// client-signed `created_at` committed late and has not replayed yet.
-    /// The replica's cursor page would be `[m1]` — silently skipping `m2`
-    /// forever, since the next cursor advances past it. The fence must route
-    /// any cursor above it to the writer.
+    /// [`replica_window_failure_falls_back_to_writer`] for the thread-replies
+    /// path: a replica-routed thread page whose query errors after the proof
+    /// re-runs on the writer instead of surfacing an error.
     #[tokio::test]
     #[ignore = "requires Postgres"]
-    async fn channel_cursor_above_fence_stays_on_writer_preventing_middle_hole() {
+    async fn replica_thread_failure_falls_back_to_writer() {
         let admin = PgPool::connect(&admin_url().await)
             .await
             .expect("connect admin");
-        let (writer, wname) = create_scratch_db(&admin, "fence_cw").await;
-        let (replica, rname) = create_scratch_db(&admin, "fence_cr").await;
+        let (writer, wname) = create_scratch_db(&admin, "fbt_w").await;
+        let (replica, rname) = create_scratch_db(&admin, "fbt_r").await;
 
         let author = nostr::Keys::generate();
         let community = Uuid::new_v4();
@@ -5648,79 +6965,1156 @@ mod tests {
         seed_community_channel(&replica, community, channel, &author).await;
 
         let base = 1_700_000_000u64;
-        let m1 = signed_event_at(&author, "m1", base);
-        let m2 = signed_event_at(&author, "m2-late-commit", base + 10);
-        let m3 = signed_event_at(&author, "m3", base + 20);
-        let m4 = signed_event_at(&author, "m4", base + 30);
-        for ev in [&m1, &m2, &m3, &m4] {
-            insert_top_level(&writer, community, channel, ev).await;
+        let root = signed_event_at(&author, "root", base);
+        for pool in [&writer, &replica] {
+            insert_top_level(pool, community, channel, &root).await;
         }
-        // Replica replayed everything EXCEPT the late-committed m2.
-        for ev in [&m1, &m3, &m4] {
-            insert_top_level(&replica, community, channel, ev).await;
+        let replies: Vec<nostr::Event> = (1..=3)
+            .map(|i| signed_event_at(&author, &format!("r{i}"), base + 10 * i as u64))
+            .collect();
+        for pool in [&writer, &replica] {
+            for reply in &replies {
+                insert_thread_reply(pool, community, channel, &root, reply).await;
+            }
         }
+        // Replica-only divergent reply between r2 and r3 marks replica serves.
+        let ghost = signed_event_at(&author, "replica-only-ghost", base + 25);
+        insert_thread_reply(&replica, community, channel, &root, &ghost).await;
 
         let db = Db::from_pools(writer.clone(), replica.clone());
+        db.fence().force_open_for_tests(chrono::Utc::now());
         let cid = CommunityId::from_uuid(community);
 
-        // Head page (writer): [m4, m3]; cursor lands on m3 (base+20).
-        let head = db
-            .get_channel_window(cid, channel, 2, None, None)
+        let page1 = db
+            .get_thread_replies(cid, root.id.as_bytes(), Some(10), 2, None)
             .await
-            .expect("head window");
-        let cursor = head.next_cursor.expect("has_more implies next_cursor");
+            .expect("head page");
+        let cur = thread_cursor(page1.last().expect("page 1 non-empty"));
 
-        // Fence closed → cursor page must come from the writer: m2 present.
-        let contents = |w: &thread::ChannelWindow| -> Vec<String> {
-            w.rows
-                .iter()
-                .map(|r| r.stored_event.event.content.clone())
-                .collect()
-        };
-        let page_closed = db
-            .get_channel_window(cid, channel, 10, Some(cursor.clone()), None)
+        // Healthy: the full page after r2 is the replica's [ghost].
+        let healthy = db
+            .get_thread_replies(cid, root.id.as_bytes(), Some(10), 1, Some(&cur))
             .await
-            .expect("cursor page, fence closed");
+            .expect("healthy replica page");
         assert_eq!(
-            contents(&page_closed),
-            vec!["m2-late-commit".to_string(), "m1".to_string()],
-            "fence closed: cursor pages route to the writer"
+            healthy[0].stored_event.event.content, "replica-only-ghost",
+            "fixture must route the cursor page to the replica while healthy"
         );
 
-        // Fence open but BELOW the cursor timestamp (covers base+5 only):
-        // the cursor (base+20) is not covered → writer again.
-        db.fence().force_open_for_tests(
-            chrono::DateTime::from_timestamp(base as i64 + 5, 0).expect("ts"),
-        );
-        let page_below = db
-            .get_channel_window(cid, channel, 10, Some(cursor.clone()), None)
+        sqlx::query("DROP TABLE events CASCADE")
+            .execute(&replica)
             .await
-            .expect("cursor page, fence below cursor");
-        assert_eq!(
-            contents(&page_below),
-            vec!["m2-late-commit".to_string(), "m1".to_string()],
-            "cursor above the fence must stay on the writer"
-        );
+            .expect("drop replica events");
 
-        // Counterfactual pinning the hazard: were the fence (wrongly) open
-        // through now, the replica would serve the page WITHOUT m2 — the
-        // permanent-skip hole this fence exists to prevent.
-        db.fence().force_open_for_tests(chrono::Utc::now());
-        let page_hazard = db
-            .get_channel_window(cid, channel, 10, Some(cursor), None)
+        let page = db
+            .get_thread_replies(cid, root.id.as_bytes(), Some(10), 1, Some(&cur))
             .await
-            .expect("cursor page, fence wrongly open");
+            .expect("replica failure must fall back to the writer, not error");
         assert_eq!(
-            contents(&page_hazard),
-            vec!["m1".to_string()],
-            "fixture models the inversion: an over-open fence would skip m2"
+            page[0].stored_event.event.content, "r3",
+            "fallback page must be the writer's answer"
         );
 
         drop_scratch_db(&admin, replica, &rname).await;
         drop_scratch_db(&admin, writer, &wname).await;
     }
 
-    /// Thread ASC pagination, out-of-order commit adversary: the replica
+    /// Mid-request degradation of the held session (Dawn, review of
+    /// 1b0aa0dfa): when the proved replica transaction dies between the page
+    /// and an aux follow-up (stand-in: `pg_terminate_backend` on the reader
+    /// connection, the same tx-fatal shape as a recovery-conflict cancel),
+    /// [`ReadSession::query_events`] must re-run the query on the writer and
+    /// permanently degrade the session instead of surfacing the error.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn read_session_degrades_to_writer_when_replica_connection_dies() {
+        let admin = PgPool::connect(&admin_url().await)
+            .await
+            .expect("connect admin");
+        let (writer, wname) = create_scratch_db(&admin, "deg_w").await;
+        let (replica, rname) = create_scratch_db(&admin, "deg_r").await;
+
+        let author = nostr::Keys::generate();
+        let community = Uuid::new_v4();
+        let channel = Uuid::new_v4();
+        seed_community_channel(&writer, community, channel, &author).await;
+        seed_community_channel(&replica, community, channel, &author).await;
+
+        let base = 1_700_000_000u64;
+        let m1 = signed_event_at(&author, "m1", base);
+        let m2 = signed_event_at(&author, "m2", base + 10);
+        for pool in [&writer, &replica] {
+            for ev in [&m1, &m2] {
+                insert_top_level(pool, community, channel, ev).await;
+            }
+        }
+        // Writer-only row proves the degraded aux ran on the writer.
+        let fresh = signed_event_at(&author, "fresh-writer-only", base + 20);
+        insert_top_level(&writer, community, channel, &fresh).await;
+
+        let db = Db::from_pools(writer.clone(), replica.clone());
+        db.fence().force_open_for_tests(chrono::Utc::now());
+        let cid = CommunityId::from_uuid(community);
+
+        let head = db
+            .get_channel_window(cid, channel, 1, None, None)
+            .await
+            .expect("head window");
+        let cursor = head.next_cursor.expect("has_more implies next_cursor");
+        let (_window, mut session) = db
+            .get_channel_window_with_session(cid, channel, 10, Some(cursor), None)
+            .await
+            .expect("routed cursor window");
+        assert!(
+            session.is_replica(),
+            "fixture must route this page to the replica"
+        );
+
+        // Kill the reader's backend out from under the held transaction.
+        sqlx::query(
+            "SELECT pg_terminate_backend(pid) FROM pg_stat_activity \
+             WHERE datname = $1 AND pid <> pg_backend_pid()",
+        )
+        .bind(&rname)
+        .execute(&admin)
+        .await
+        .expect("terminate replica backends");
+
+        let mut aux = EventQuery::for_community(cid);
+        aux.channel_id = Some(channel);
+        let rows = session
+            .query_events(&aux)
+            .await
+            .expect("session must degrade to the writer, not error");
+        assert!(
+            rows.iter()
+                .any(|se| se.event.content == "fresh-writer-only"),
+            "degraded aux must be served by the writer"
+        );
+        assert!(
+            !session.is_replica(),
+            "the session must be permanently degraded to the writer"
+        );
+
+        drop(session);
+        drop_scratch_db(&admin, replica, &rname).await;
+        drop_scratch_db(&admin, writer, &wname).await;
+    }
+
+    /// Snapshot continuity (Wren, review of 17ea2ff6a): the routed request
+    /// runs inside ONE `REPEATABLE READ, READ ONLY` transaction whose first
+    /// statement was the heartbeat observation — so a row committed on the
+    /// replica *after* the proof must be invisible to every follow-up
+    /// statement in the same request (page, participants, aux). This
+    /// distinguishes the transaction contract from mere connection reuse:
+    /// autocommit statements on the same backend advance their snapshot
+    /// per statement and WOULD see the mid-request row.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn routed_request_holds_one_snapshot_across_page_and_aux() {
+        let admin = PgPool::connect(&admin_url().await)
+            .await
+            .expect("connect admin");
+        let (writer, wname) = create_scratch_db(&admin, "snap_w").await;
+        let (replica, rname) = create_scratch_db(&admin, "snap_r").await;
+
+        let author = nostr::Keys::generate();
+        let community = Uuid::new_v4();
+        let channel = Uuid::new_v4();
+        seed_community_channel(&writer, community, channel, &author).await;
+        seed_community_channel(&replica, community, channel, &author).await;
+
+        let base = 1_700_000_000u64;
+        let m1 = signed_event_at(&author, "m1", base);
+        let m2 = signed_event_at(&author, "m2", base + 10);
+        for pool in [&writer, &replica] {
+            for ev in [&m1, &m2] {
+                insert_top_level(pool, community, channel, ev).await;
+            }
+        }
+
+        let db = Db::from_pools(writer.clone(), replica.clone());
+        db.fence().force_open_for_tests(chrono::Utc::now());
+        let cid = CommunityId::from_uuid(community);
+
+        // Head page on the writer yields the cursor for a replica-routed page.
+        let head = db
+            .get_channel_window(cid, channel, 1, None, None)
+            .await
+            .expect("head window");
+        let cursor = head.next_cursor.expect("has_more implies next_cursor");
+
+        // Route the cursor page to the replica and HOLD the session.
+        let (window, mut session) = db
+            .get_channel_window_with_session(cid, channel, 10, Some(cursor), None)
+            .await
+            .expect("routed cursor window");
+        assert!(
+            session.is_replica(),
+            "fixture must route this page to the replica"
+        );
+        assert_eq!(window.rows.len(), 1, "page after m2 is [m1]");
+
+        // Mid-request: a new event commits on the replica (stands in for
+        // replay advancing between the page and the aux closure).
+        let mid = signed_event_at(&author, "mid-request-commit", base + 5);
+        insert_top_level(&replica, community, channel, &mid).await;
+
+        // A fresh autocommit statement on ANOTHER session sees it — the row
+        // is really there (control for the assertion below).
+        let mut control = EventQuery::for_community(cid);
+        control.channel_id = Some(channel);
+        let visible_elsewhere = event::query_events(&replica, &control)
+            .await
+            .expect("control query");
+        assert!(
+            visible_elsewhere
+                .iter()
+                .any(|se| se.event.content == "mid-request-commit"),
+            "control: the mid-request row must be committed and visible to a new snapshot"
+        );
+
+        // The held request session must NOT see it: its snapshot was
+        // anchored by the heartbeat observation, before the commit.
+        let mut aux = EventQuery::for_community(cid);
+        aux.channel_id = Some(channel);
+        let in_request = session.query_events(&aux).await.expect("aux query");
+        assert!(
+            !in_request
+                .iter()
+                .any(|se| se.event.content == "mid-request-commit"),
+            "request transaction must hold the proof-time snapshot; a \
+             mid-request commit leaking in means the aux ran outside the \
+             request transaction (autocommit connection reuse)"
+        );
+        // Rows from the proof-time snapshot are still served.
+        assert!(
+            in_request.iter().any(|se| se.event.content == "m1"),
+            "proof-time rows must remain visible in the request snapshot"
+        );
+
+        drop(session);
+        drop_scratch_db(&admin, replica, &rname).await;
+        drop_scratch_db(&admin, writer, &wname).await;
+    }
+
+    /// Head gate (Predicate A): with the budget unset, a head fetch reads
+    /// the writer even over an open fence; with a budget set and a fresh
+    /// proved entry, the head page is served by the replica session
+    /// (bounded staleness accepted); with a budget the fence entry exceeds,
+    /// the head page falls back to the writer.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn head_fetch_routes_by_configured_budget() {
+        let admin = PgPool::connect(&admin_url().await)
+            .await
+            .expect("connect admin");
+        let (writer, wname) = create_scratch_db(&admin, "head_w").await;
+        let (replica, rname) = create_scratch_db(&admin, "head_r").await;
+
+        let author = nostr::Keys::generate();
+        let community = Uuid::new_v4();
+        let channel = Uuid::new_v4();
+        seed_community_channel(&writer, community, channel, &author).await;
+        seed_community_channel(&replica, community, channel, &author).await;
+
+        let base = 1_700_000_000u64;
+        let shared = signed_event_at(&author, "shared", base);
+        for pool in [&writer, &replica] {
+            insert_top_level(pool, community, channel, &shared).await;
+        }
+        // Divergent heads prove which pool served the fetch.
+        let fresh = signed_event_at(&author, "fresh-writer-only", base + 30);
+        insert_top_level(&writer, community, channel, &fresh).await;
+        let marker = signed_event_at(&author, "replica-only-marker", base + 20);
+        insert_top_level(&replica, community, channel, &marker).await;
+
+        let mut db = Db::from_pools(writer.clone(), replica.clone());
+        db.fence().force_open_for_tests(chrono::Utc::now());
+        let cid = CommunityId::from_uuid(community);
+        let head_contents = |w: &thread::ChannelWindow| -> Vec<String> {
+            w.rows
+                .iter()
+                .map(|r| r.stored_event.event.content.clone())
+                .collect()
+        };
+
+        // Budget unset (rollout default): head → writer, fence open or not.
+        let head = db
+            .get_channel_window(cid, channel, 2, None, None)
+            .await
+            .expect("head, gate off");
+        assert_eq!(
+            head_contents(&head),
+            vec!["fresh-writer-only".to_string(), "shared".to_string()],
+            "head routing must default off"
+        );
+
+        // Budget set, entry fresh (just recorded): head → replica.
+        db.set_replica_read_max_age_for_tests(Some(std::time::Duration::from_secs(5)));
+        let head = db
+            .get_channel_window(cid, channel, 2, None, None)
+            .await
+            .expect("head, gate on");
+        assert_eq!(
+            head_contents(&head),
+            vec!["replica-only-marker".to_string(), "shared".to_string()],
+            "a fresh proved entry within budget must serve the head from the replica"
+        );
+
+        // Entry older than the budget: head falls back to the writer.
+        db.fence().close();
+        db.fence().force_open_for_tests_at(
+            chrono::Utc::now(),
+            std::time::Instant::now() - std::time::Duration::from_secs(10),
+        );
+        let head = db
+            .get_channel_window(cid, channel, 2, None, None)
+            .await
+            .expect("head, entry too old");
+        assert_eq!(
+            head_contents(&head),
+            vec!["fresh-writer-only".to_string(), "shared".to_string()],
+            "an over-budget entry must fail the head gate closed"
+        );
+
+        drop_scratch_db(&admin, replica, &rname).await;
+        drop_scratch_db(&admin, writer, &wname).await;
+    }
+
+    /// End-to-end deploy-default proof for the NEW routed seams: with the
+    /// budget unset, a covered-eligible query (channel-pinned + `until`)
+    /// through [`Db::query_events_routed`] is served by the WRITER — the
+    /// `for_query` gate keeps the covered arm dark (rev 5). With the budget
+    /// set and a fresh proved entry, the same query routes to the replica.
+    /// Divergent fixtures prove which pool served each read.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn query_events_routed_defaults_dark_and_routes_covered_when_enabled() {
+        let admin = PgPool::connect(&admin_url().await)
+            .await
+            .expect("connect admin");
+        let (writer, wname) = create_scratch_db(&admin, "qer_w").await;
+        let (replica, rname) = create_scratch_db(&admin, "qer_r").await;
+
+        let author = nostr::Keys::generate();
+        let community = Uuid::new_v4();
+        let channel = Uuid::new_v4();
+        seed_community_channel(&writer, community, channel, &author).await;
+        seed_community_channel(&replica, community, channel, &author).await;
+
+        let base = 1_700_000_000u64;
+        let shared = signed_event_at(&author, "shared", base);
+        for pool in [&writer, &replica] {
+            insert_top_level(pool, community, channel, &shared).await;
+        }
+        let writer_only = signed_event_at(&author, "writer-only", base + 10);
+        insert_top_level(&writer, community, channel, &writer_only).await;
+        let replica_only = signed_event_at(&author, "replica-only", base + 20);
+        insert_top_level(&replica, community, channel, &replica_only).await;
+
+        let mut db = Db::from_pools(writer.clone(), replica.clone());
+        db.fence().force_open_for_tests(chrono::Utc::now());
+        let cid = CommunityId::from_uuid(community);
+
+        // Covered-eligible shape: channel-pinned with an `until` upper
+        // bound below the (now) fence wall.
+        let q = {
+            let mut q = EventQuery::for_community(cid);
+            q.channel_id = Some(channel);
+            q.until = chrono::DateTime::from_timestamp((base + 60) as i64, 0);
+            q
+        };
+        let contents = |evs: &[StoredEvent]| -> std::collections::BTreeSet<String> {
+            evs.iter().map(|e| e.event.content.clone()).collect()
+        };
+
+        // Deploy default: budget unset ⇒ writer, even though the shape is
+        // covered-eligible and the fence is open.
+        let rows = db
+            .query_events_routed("test_routed", &q)
+            .await
+            .expect("routed query, gate off");
+        assert!(
+            contents(&rows).contains("writer-only"),
+            "budget unset must serve the writer"
+        );
+        assert!(
+            !contents(&rows).contains("replica-only"),
+            "budget unset must not reach the replica via the covered arm"
+        );
+
+        // Budget set ⇒ the covered arm serves it from the replica.
+        db.set_replica_read_max_age_for_tests(Some(std::time::Duration::from_secs(5)));
+        let rows = db
+            .query_events_routed("test_routed", &q)
+            .await
+            .expect("routed query, gate on");
+        assert!(
+            contents(&rows).contains("replica-only"),
+            "budget set + covered-eligible must route to the replica"
+        );
+        assert!(!contents(&rows).contains("writer-only"));
+
+        drop_scratch_db(&admin, replica, &rname).await;
+        drop_scratch_db(&admin, writer, &wname).await;
+    }
+
+    /// COUNT is bounded-only (rev 5 deletion-visibility rule): a
+    /// covered-eligible shape must NOT let a count take the covered arm.
+    /// With the budget unset the count reads the WRITER even with an open
+    /// fence; with the budget set and a fresh entry it reads the replica
+    /// under the bounded arm. Divergent row counts prove the serving pool.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn count_events_routed_is_bounded_only() {
+        let admin = PgPool::connect(&admin_url().await)
+            .await
+            .expect("connect admin");
+        let (writer, wname) = create_scratch_db(&admin, "cnt_w").await;
+        let (replica, rname) = create_scratch_db(&admin, "cnt_r").await;
+
+        let author = nostr::Keys::generate();
+        let community = Uuid::new_v4();
+        let channel = Uuid::new_v4();
+        seed_community_channel(&writer, community, channel, &author).await;
+        seed_community_channel(&replica, community, channel, &author).await;
+
+        let base = 1_700_000_000u64;
+        // Writer: 2 rows. Replica: 1 row.
+        for (i, content) in ["a", "b"].iter().enumerate() {
+            let ev = signed_event_at(&author, content, base + i as u64);
+            insert_top_level(&writer, community, channel, &ev).await;
+        }
+        let ev = signed_event_at(&author, "c", base);
+        insert_top_level(&replica, community, channel, &ev).await;
+
+        let mut db = Db::from_pools(writer.clone(), replica.clone());
+        db.fence().force_open_for_tests(chrono::Utc::now());
+        let cid = CommunityId::from_uuid(community);
+
+        // Covered-eligible shape on purpose: pinned + until. A count must
+        // ignore that eligibility.
+        let q = {
+            let mut q = EventQuery::for_community(cid);
+            q.channel_id = Some(channel);
+            q.until = chrono::DateTime::from_timestamp((base + 60) as i64, 0);
+            q
+        };
+
+        // Budget unset ⇒ bounded arm disabled ⇒ writer.
+        let n = db
+            .count_events_routed("test_count", &q)
+            .await
+            .expect("count, gate off");
+        assert_eq!(n, 2, "budget unset must count on the writer");
+
+        // Budget set + fresh entry ⇒ bounded arm ⇒ replica.
+        db.set_replica_read_max_age_for_tests(Some(std::time::Duration::from_secs(5)));
+        let n = db
+            .count_events_routed("test_count", &q)
+            .await
+            .expect("count, gate on");
+        assert_eq!(n, 1, "budget set must count on the replica (bounded)");
+
+        // Entry older than the budget ⇒ bounded fails ⇒ writer. Covered
+        // would still hold here (upper <= wall) — proving count never
+        // consults it.
+        db.fence().close();
+        db.fence().force_open_for_tests_at(
+            chrono::Utc::now(),
+            std::time::Instant::now() - std::time::Duration::from_secs(10),
+        );
+        let n = db
+            .count_events_routed("test_count", &q)
+            .await
+            .expect("count, entry too old");
+        assert_eq!(
+            n, 2,
+            "an over-budget entry must fail the count closed to the writer, \
+             even when the covered arm would admit the shape"
+        );
+
+        drop_scratch_db(&admin, replica, &rname).await;
+        drop_scratch_db(&admin, writer, &wname).await;
+    }
+
+    /// Routed relay-membership check: budget unset ⇒ writer; budget set +
+    /// fresh proved entry ⇒ replica (bounded arm); over-budget entry ⇒
+    /// writer. Divergent membership rows prove which pool answered.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn is_relay_member_is_bounded_routed_and_fails_closed() {
+        let admin = PgPool::connect(&admin_url().await)
+            .await
+            .expect("connect admin");
+        let (writer, wname) = create_scratch_db(&admin, "mem_w").await;
+        let (replica, rname) = create_scratch_db(&admin, "mem_r").await;
+
+        let community = Uuid::new_v4();
+        for pool in [&writer, &replica] {
+            sqlx::query("INSERT INTO communities (id, host) VALUES ($1, $2)")
+                .bind(community)
+                .bind(format!("member-routing-{}.example", community.simple()))
+                .execute(pool)
+                .await
+                .expect("insert community");
+        }
+        let cid = CommunityId::from_uuid(community);
+        let writer_only = "aa".repeat(32);
+        let replica_only = "bb".repeat(32);
+        relay_members::add_relay_member(&writer, cid, &writer_only, "member", None)
+            .await
+            .expect("seed writer member");
+        relay_members::add_relay_member(&replica, cid, &replica_only, "member", None)
+            .await
+            .expect("seed replica member");
+
+        let mut db = Db::from_pools(writer.clone(), replica.clone());
+        db.fence().force_open_for_tests(chrono::Utc::now());
+
+        // Budget unset ⇒ bounded arm disabled ⇒ writer.
+        assert!(
+            db.is_relay_member(cid, &writer_only)
+                .await
+                .expect("gate off"),
+            "budget unset must answer from the writer"
+        );
+        assert!(!db.is_relay_member(cid, &replica_only).await.unwrap());
+
+        // Budget set + fresh entry ⇒ replica.
+        db.set_replica_read_max_age_for_tests(Some(std::time::Duration::from_secs(5)));
+        assert!(
+            db.is_relay_member(cid, &replica_only)
+                .await
+                .expect("gate on"),
+            "budget set must answer from the replica"
+        );
+        assert!(!db.is_relay_member(cid, &writer_only).await.unwrap());
+
+        // Entry older than the budget ⇒ fail closed to the writer. Close
+        // first so no prior fresh entry can be the one proved (matches the
+        // count test; today `force_open_for_tests_at` also clears the ring).
+        db.fence().close();
+        db.fence().force_open_for_tests_at(
+            chrono::Utc::now(),
+            std::time::Instant::now() - std::time::Duration::from_secs(10),
+        );
+        assert!(
+            db.is_relay_member(cid, &writer_only)
+                .await
+                .expect("entry too old"),
+            "an over-budget entry must fail closed to the writer"
+        );
+
+        drop_scratch_db(&admin, replica, &rname).await;
+        drop_scratch_db(&admin, writer, &wname).await;
+    }
+
+    /// Community separation across every routed seam, verified on
+    /// REPLICA-SERVED reads.
+    ///
+    /// The pre-existing feed/event scoping tests prove the shared SQL
+    /// builders confine rows to one community, but they exercise those
+    /// builders through the WRITER wrapper. `_on` variants are
+    /// executor-only refactors, so scoping *should* be identical — this
+    /// test refuses to take that on faith and re-proves it through the
+    /// routed executor, on a snapshot the replica actually served.
+    ///
+    /// Construction: two communities A and B exist in BOTH databases with
+    /// the same ids. The replica additionally holds a `replica-only` row in
+    /// each — divergent fixtures, so any row bearing that content proves
+    /// the replica (not the writer) served the read. Every assertion
+    /// requests A and demands B's rows never appear, including B's
+    /// `replica-only` row, which is the one a leaky predicate would surface.
+    /// The routed fallback must cost ONE reader acquire budget, even when the
+    /// Aurora capability cache is cold.
+    ///
+    /// Regression test for a stacked-budget bug found at `9fa3c9c0b`: the
+    /// capability probe used to `acquire()` from the pool itself and return
+    /// `false` *uncached* on `PoolTimedOut`, so the routed read then spent a
+    /// SECOND `READER_ACQUIRE_TIMEOUT` inside `begin`. Measured 302ms against
+    /// a ~150ms documented bound. Boot priming
+    /// ([`Db::spawn_read_pool_boot_ping`]) hid it only when the boot ping
+    /// SUCCEEDED — and a reader that is unavailable at boot is exactly the
+    /// case the bound is specified for, so the two failures are correlated.
+    ///
+    /// The fixture reproduces that state deliberately: a size-1 reader whose
+    /// sole connection is established and then HELD (so every further acquire
+    /// must time out), with `reader_aurora_identity` asserted cold. It routes
+    /// through `count_events_routed` rather than calling `proved_reader`
+    /// directly, because `buzz_db_route_decision` is emitted by `route_read`
+    /// — a direct call would prove the timing but never emit the label.
+    ///
+    /// Timing uses an upper bound of 2x the budget minus a margin: it must
+    /// fail for two stacked budgets (~300ms) while tolerating scheduler
+    /// jitter on one (~150ms). Asserting a lower bound too would pin the
+    /// budget's own value, which `reader_acquire_timeout_is_the_documented_budget`
+    /// already covers.
+    #[tokio::test(flavor = "current_thread")]
+    #[ignore = "requires Postgres"]
+    async fn routed_fallback_spends_one_acquire_budget_when_aurora_cache_is_cold() {
+        let admin = PgPool::connect(&admin_url().await)
+            .await
+            .expect("connect admin");
+        let (seed, wname) = create_scratch_db(&admin, "one_budget").await;
+        seed.close().await;
+        let base = admin_url().await;
+        let scratch_url = {
+            let idx = base.rfind('/').expect("db url has a path segment");
+            format!("{}/{}", &base[..idx], wname)
+        };
+
+        // `Db::new` so the writer arms the floor guard and the reader is the
+        // real lazy `connect_read_pool` pool (min_connections=0, 150ms
+        // acquire timeout). Reader is sized 1 so holding one connection
+        // saturates it.
+        let mut db = Db::new(&DbConfig {
+            database_url: scratch_url.clone(),
+            read_database_url: Some(scratch_url),
+            max_connections: 4,
+            read_max_connections: Some(1),
+            ..DbConfig::default()
+        })
+        .await
+        .expect("connect armed Db with size-1 lazy reader");
+        db.fence().force_open_for_tests(chrono::Utc::now());
+        db.set_replica_read_max_age_for_tests(Some(Duration::from_secs(5)));
+
+        let read_pool = db.read_pool.clone().expect("reader pool configured");
+        // Establish and hold the reader's only connection: saturated.
+        let held = read_pool
+            .acquire()
+            .await
+            .expect("establish the reader's sole connection");
+        assert_eq!(
+            db.read_max_connections, 1,
+            "reader max must report 1 for this fixture to test saturation"
+        );
+        assert_eq!(
+            read_pool.size(),
+            1,
+            "the sole reader connection is established and held"
+        );
+        // The bug is only observable with the capability cache cold; if a
+        // future change primes it here, this fixture would silently stop
+        // discriminating.
+        assert!(
+            db.reader_aurora_identity.get().is_none(),
+            "Aurora capability must be UNPRIMED (post-boot-ping-failure state)"
+        );
+
+        let recorder = metrics_util::debugging::DebuggingRecorder::new();
+        let snapshotter = recorder.snapshotter();
+        let query = EventQuery::for_community(CommunityId::from_uuid(Uuid::new_v4()));
+
+        // The recorder is installed thread-locally, so it must stay installed
+        // across the `.await` — hence the guard form rather than
+        // `with_local_recorder`, whose closure cannot host an await. The
+        // `current_thread` flavor keeps the route decision on this thread; on
+        // a multi-thread runtime the emit could land on a worker where no
+        // local recorder is installed and the label assertions would vacuously
+        // see an empty snapshot.
+        let start = std::time::Instant::now();
+        let count = {
+            let _guard = metrics::set_default_local_recorder(&recorder);
+            db.count_events_routed("one_budget_probe", &query).await
+        }
+        .expect("writer fallback still answers the read");
+        let elapsed = start.elapsed();
+
+        assert_eq!(count, 0, "writer answered on an empty scratch database");
+        assert!(
+            elapsed < Duration::from_millis(250),
+            "routed fallback must spend ONE {}ms acquire budget, not two; took {}ms",
+            Db::READER_ACQUIRE_TIMEOUT.as_millis(),
+            elapsed.as_millis()
+        );
+
+        let reasons: std::collections::HashMap<(String, String), u64> = snapshotter
+            .snapshot()
+            .into_vec()
+            .into_iter()
+            .filter(|(key, ..)| key.key().name() == "buzz_db_route_decision")
+            .map(|(key, _, _, value)| {
+                let metrics_util::debugging::DebugValue::Counter(n) = value else {
+                    panic!("buzz_db_route_decision must be a counter");
+                };
+                let labels: Vec<_> = key.key().labels().collect();
+                let get = |name: &str| {
+                    labels
+                        .iter()
+                        .find(|l| l.key() == name)
+                        .map(|l| l.value().to_owned())
+                        .unwrap_or_default()
+                };
+                ((get("decision"), get("reason")), n)
+            })
+            .collect();
+
+        assert_eq!(
+            reasons.get(&("writer".to_owned(), "reader_acquire_timeout".to_owned())),
+            Some(&1),
+            "saturated reader must fall back as writer/reader_acquire_timeout; got {reasons:?}"
+        );
+        // `reader_validation_error` would mean we misclassified a timeout as a
+        // broken reader, and `pool_busy` is the retired name — neither may
+        // appear in ANY emitted label.
+        assert!(
+            !reasons
+                .keys()
+                .any(|(_, reason)| reason == "reader_validation_error" || reason == "pool_busy"),
+            "no reader_validation_error or retired pool_busy label may be emitted; got {reasons:?}"
+        );
+
+        drop(held);
+        drop_scratch_db(&admin, db.pool.clone(), &wname).await;
+    }
+
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn routed_reads_are_confined_to_the_requested_community() {
+        let admin = PgPool::connect(&admin_url().await)
+            .await
+            .expect("connect admin");
+        let (writer, wname) = create_scratch_db(&admin, "sep_w").await;
+        let (replica, rname) = create_scratch_db(&admin, "sep_r").await;
+
+        let author = nostr::Keys::generate();
+        let (comm_a, chan_a) = (Uuid::new_v4(), Uuid::new_v4());
+        let (comm_b, chan_b) = (Uuid::new_v4(), Uuid::new_v4());
+        for pool in [&writer, &replica] {
+            seed_community_channel(pool, comm_a, chan_a, &author).await;
+            seed_community_channel(pool, comm_b, chan_b, &author).await;
+        }
+
+        // A p-tag mention is what makes a row eligible for the mentions and
+        // needs-action feeds. Kind 9 satisfies mentions + activity;
+        // needs-action admits only approval/reminder kinds, so each
+        // community also gets a kind-46010 row.
+        let mentioned = nostr::Keys::generate();
+        let mentioned_hex = mentioned.public_key().to_hex();
+        let mentioned_bytes = mentioned.public_key().to_bytes();
+        let tagged_kind = |kind: u16, content: &str, secs: u64| {
+            nostr::EventBuilder::new(nostr::Kind::Custom(kind), content)
+                .tags([nostr::Tag::parse(["p", mentioned_hex.as_str()]).expect("p tag")])
+                .custom_created_at(nostr::Timestamp::from(secs))
+                .sign_with_keys(&author)
+                .expect("sign event")
+        };
+        let tagged = |content: &str, secs: u64| tagged_kind(9, content, secs);
+
+        let base = 1_700_000_000u64;
+        // Shared rows (both DBs) + replica-only rows (divergence) per community.
+        let a_shared = tagged("a-shared", base);
+        let b_shared = tagged("b-shared", base + 1);
+        for pool in [&writer, &replica] {
+            insert_top_level(pool, comm_a, chan_a, &a_shared).await;
+            insert_mentions(
+                pool,
+                CommunityId::from_uuid(comm_a),
+                &a_shared,
+                Some(chan_a),
+            )
+            .await
+            .expect("mentions a-shared");
+            insert_top_level(pool, comm_b, chan_b, &b_shared).await;
+            insert_mentions(
+                pool,
+                CommunityId::from_uuid(comm_b),
+                &b_shared,
+                Some(chan_b),
+            )
+            .await
+            .expect("mentions b-shared");
+        }
+        let a_replica_only = tagged("a-replica-only", base + 10);
+        let b_replica_only = tagged("b-replica-only", base + 11);
+        insert_top_level(&replica, comm_a, chan_a, &a_replica_only).await;
+        insert_mentions(
+            &replica,
+            CommunityId::from_uuid(comm_a),
+            &a_replica_only,
+            Some(chan_a),
+        )
+        .await
+        .expect("mentions a-replica-only");
+        insert_top_level(&replica, comm_b, chan_b, &b_replica_only).await;
+        insert_mentions(
+            &replica,
+            CommunityId::from_uuid(comm_b),
+            &b_replica_only,
+            Some(chan_b),
+        )
+        .await
+        .expect("mentions b-replica-only");
+
+        // Needs-action fixtures: approval kind, replica-only in BOTH
+        // communities, so the assertion below is replica-served on A and
+        // must still not see B's.
+        let a_approval = tagged_kind(46010, "a-approval-replica-only", base + 20);
+        let b_approval = tagged_kind(46010, "b-approval-replica-only", base + 21);
+        insert_top_level(&replica, comm_a, chan_a, &a_approval).await;
+        insert_mentions(
+            &replica,
+            CommunityId::from_uuid(comm_a),
+            &a_approval,
+            Some(chan_a),
+        )
+        .await
+        .expect("mentions a-approval");
+        insert_top_level(&replica, comm_b, chan_b, &b_approval).await;
+        insert_mentions(
+            &replica,
+            CommunityId::from_uuid(comm_b),
+            &b_approval,
+            Some(chan_b),
+        )
+        .await
+        .expect("mentions b-approval");
+
+        let mut db = Db::from_pools(writer.clone(), replica.clone());
+        db.fence().force_open_for_tests(chrono::Utc::now());
+        db.set_replica_read_max_age_for_tests(Some(std::time::Duration::from_secs(5)));
+        let cid_a = CommunityId::from_uuid(comm_a);
+
+        let contents = |evs: &[StoredEvent]| -> std::collections::BTreeSet<String> {
+            evs.iter().map(|e| e.event.content.clone()).collect()
+        };
+        // Every routed seam must (a) have been served by the replica —
+        // proven by a divergent row absent from the writer — and (b) contain
+        // no row belonging to community B. All B fixtures are named `b-*`,
+        // so the leak check is a single prefix scan.
+        let assert_a_only = |rows: &[StoredEvent], marker: &str, seam: &str| {
+            let got = contents(rows);
+            assert!(
+                got.contains(marker),
+                "{seam}: must be replica-served (divergent row `{marker}` absent from writer); got {got:?}"
+            );
+            assert!(
+                !got.iter().any(|c| c.starts_with("b-")),
+                "{seam}: community B rows leaked into a community A read; got {got:?}"
+            );
+        };
+
+        // 1. Generic query — covered arm (channel-pinned + `until`).
+        let mut q = EventQuery::for_community(cid_a);
+        q.channel_id = Some(chan_a);
+        q.until = chrono::DateTime::from_timestamp((base + 60) as i64, 0);
+        let rows = db
+            .query_events_routed("sep_query", &q)
+            .await
+            .expect("routed query");
+        assert_a_only(&rows, "a-replica-only", "query_events_routed");
+
+        // 2. Generic query — bounded arm (no channel pin at all, so a
+        //    missing community predicate could not be masked by the pin).
+        let unpinned = EventQuery::for_community(cid_a);
+        let rows = db
+            .query_events_routed_bounded("sep_query_bounded", &unpinned)
+            .await
+            .expect("routed bounded query");
+        assert_a_only(&rows, "a-replica-only", "query_events_routed_bounded");
+
+        // 3. COUNT — bounded-only. Community A holds 3 rows on the replica
+        //    (shared + replica-only + approval) but only 1 on the writer,
+        //    and 3 more exist in community B. Exactly 3 proves the read was
+        //    both replica-served and community-confined.
+        let count = db
+            .count_events_routed("sep_count", &unpinned)
+            .await
+            .expect("routed count");
+        assert_eq!(
+            count, 3,
+            "count must see A's three replica rows only — not B's, not the writer's one"
+        );
+
+        // 4. By-ID hydration — ids carry no channel pin, and B's ids are
+        //    requested alongside A's. Only A's may hydrate.
+        let ids: Vec<&[u8]> = vec![
+            a_shared.id.as_bytes(),
+            a_replica_only.id.as_bytes(),
+            b_shared.id.as_bytes(),
+            b_replica_only.id.as_bytes(),
+        ];
+        let rows = db
+            .get_events_by_ids_routed("sep_by_ids", cid_a, &ids)
+            .await
+            .expect("routed by-ids");
+        assert_a_only(&rows, "a-replica-only", "get_events_by_ids_routed");
+
+        // 5-7. All three feed builders, each given BOTH channels as
+        //      accessible — so only the community predicate can exclude B.
+        let both = [chan_a, chan_b];
+        let rows = db
+            .query_feed_mentions_routed("sep_feed", cid_a, &mentioned_bytes, &both, None, 50)
+            .await
+            .expect("routed mentions");
+        assert_a_only(&rows, "a-replica-only", "query_feed_mentions_routed");
+
+        let rows = db
+            .query_feed_needs_action_routed("sep_feed", cid_a, &mentioned_bytes, &both, None, 50)
+            .await
+            .expect("routed needs action");
+        assert_a_only(
+            &rows,
+            "a-approval-replica-only",
+            "query_feed_needs_action_routed",
+        );
+
+        let rows = db
+            .query_feed_activity_routed("sep_feed", cid_a, &both, None, 50)
+            .await
+            .expect("routed activity");
+        assert_a_only(&rows, "a-replica-only", "query_feed_activity_routed");
+
+        drop_scratch_db(&admin, replica, &rname).await;
+        drop_scratch_db(&admin, writer, &wname).await;
+    }
+
+    /// D4: a LAZY reader pool (connect_lazy, min_connections=0, never yet
+    /// used) must still let [`Db::spawn_fence_probe`] verify the writer's
+    /// floor guard and spawn — reader-down or reader-idle at boot must not
+    /// disable fence probing.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn lazy_reader_pool_still_spawns_fence_probe() {
+        let admin = PgPool::connect(&admin_url().await)
+            .await
+            .expect("connect admin");
+        let (seed, wname) = create_scratch_db(&admin, "lazy_w").await;
+        seed.close().await;
+
+        let writer_url = {
+            let base = admin_url().await;
+            let idx = base.rfind('/').expect("db url has a path segment");
+            format!("{}/{}", &base[..idx], wname)
+        };
+        // `Db::new` (not `from_pools`) so the WRITER pool arms the
+        // `buzz.created_at_floor` GUC — `spawn_fence_probe` verifies the
+        // floor guard on a writer connection, and `create_scratch_db`'s
+        // plain `PgPool::connect` never arms it. The reader is still the
+        // lazy `connect_read_pool` pool this test is about.
+        let db = Db::new(&DbConfig {
+            database_url: writer_url.clone(),
+            read_database_url: Some(writer_url),
+            max_connections: 2,
+            ..DbConfig::default()
+        })
+        .await
+        .expect("connect armed Db with lazy reader");
+
+        let spawned = db
+            .spawn_fence_probe()
+            .await
+            .expect("floor-guard verification must pass on the migrated writer");
+        assert!(spawned, "a configured (lazy) reader must spawn the probe");
+
+        drop_scratch_db(&admin, db.pool.clone(), &wname).await;
+    }
+
+    /// Thread replies: head fetch reads the writer; a FULL cursor page is
+    /// served by the replica; an UNDER-limit cursor page (candidate terminal
+    /// page) is re-run on the writer so a lagged replica can never truncate
+    /// the tail into a false EOF.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn thread_replies_cursor_pages_route_to_replica_with_writer_terminal_verification() {
+        let admin = PgPool::connect(&admin_url().await)
+            .await
+            .expect("connect admin");
+        let (writer, wname) = create_scratch_db(&admin, "routing_tw").await;
+        let (replica, rname) = create_scratch_db(&admin, "routing_tr").await;
+
+        let author = nostr::Keys::generate();
+        let community = Uuid::new_v4();
+        let channel = Uuid::new_v4();
+        seed_community_channel(&writer, community, channel, &author).await;
+        seed_community_channel(&replica, community, channel, &author).await;
+
+        let base = 1_700_000_000u64;
+        let root = signed_event_at(&author, "root", base);
+        for pool in [&writer, &replica] {
+            insert_top_level(pool, community, channel, &root).await;
+        }
+
+        // Writer holds replies r1..r5; the lagged replica only has r1..r3.
+        let replies: Vec<nostr::Event> = (1..=5)
+            .map(|i| signed_event_at(&author, &format!("r{i}"), base + 10 * i as u64))
+            .collect();
+        for reply in &replies {
+            insert_thread_reply(&writer, community, channel, &root, reply).await;
+        }
+        for reply in &replies[..3] {
+            insert_thread_reply(&replica, community, channel, &root, reply).await;
+        }
+
+        let db = Db::from_pools(writer.clone(), replica.clone());
+        // Open the fence through "now" — fixture history is far in the past.
+        db.fence().force_open_for_tests(chrono::Utc::now());
+        let cid = CommunityId::from_uuid(community);
+
+        // Page 1 (no cursor) → writer.
+        let page1 = db
+            .get_thread_replies(cid, root.id.as_bytes(), Some(10), 2, None)
+            .await
+            .expect("page 1");
+        let contents: Vec<&str> = page1
+            .iter()
+            .map(|r| r.stored_event.event.content.as_str())
+            .collect();
+        assert_eq!(contents, vec!["r1", "r2"], "head page from writer");
+
+        // Page 2: replica serves a FULL page (r3 exists there) — but wait:
+        // replica has r1..r3, page after r2 with limit 2 returns only [r3]
+        // (under limit) → terminal-verification re-runs on the writer, which
+        // returns [r3, r4]. A lag-truncated EOF must never surface.
+        let cur2 = thread_cursor(page1.last().expect("page 1 non-empty"));
+        let page2 = db
+            .get_thread_replies(cid, root.id.as_bytes(), Some(10), 2, Some(&cur2))
+            .await
+            .expect("page 2");
+        let contents: Vec<&str> = page2
+            .iter()
+            .map(|r| r.stored_event.event.content.as_str())
+            .collect();
+        assert_eq!(
+            contents,
+            vec!["r3", "r4"],
+            "under-limit replica page must be re-verified on the writer"
+        );
+
+        // Full-page replica serve: with limit 1, the page after r2 is [r3] —
+        // exactly `limit` rows, so the replica result stands. Prove it came
+        // from the replica with a replica-only divergent reply.
+        let ghost = signed_event_at(&author, "replica-only-ghost", base + 25);
+        insert_thread_reply(&replica, community, channel, &root, &ghost).await;
+        let page_replica = db
+            .get_thread_replies(cid, root.id.as_bytes(), Some(10), 1, Some(&cur2))
+            .await
+            .expect("full replica page");
+        let contents: Vec<&str> = page_replica
+            .iter()
+            .map(|r| r.stored_event.event.content.as_str())
+            .collect();
+        assert_eq!(
+            contents,
+            vec!["replica-only-ghost"],
+            "a full cursor page must be served by the replica"
+        );
+
+        // Same query with no replica configured reads the writer and cannot
+        // see the ghost.
+        let db_writer_only = Db::from_pool(writer.clone());
+        let page_writer = db_writer_only
+            .get_thread_replies(cid, root.id.as_bytes(), Some(10), 1, Some(&cur2))
+            .await
+            .expect("writer-only page");
+        let contents: Vec<&str> = page_writer
+            .iter()
+            .map(|r| r.stored_event.event.content.as_str())
+            .collect();
+        assert_eq!(contents, vec!["r3"], "unset replica falls back to writer");
+
+        drop_scratch_db(&admin, replica, &rname).await;
+        drop_scratch_db(&admin, writer, &wname).await;
+    }
+
+    /// Channel DESC scrollback, out-of-order commit adversary: the replica is
+    /// missing a MIDDLE row (`m2`) because a transaction with an older
+    /// client-signed `created_at` committed late and has not replayed yet.
+    /// The replica's cursor page would be `[m1]` — silently skipping `m2`
+    /// forever, since the next cursor advances past it. The fence must route
+    /// any cursor above it to the writer.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn channel_cursor_above_fence_stays_on_writer_preventing_middle_hole() {
+        let admin = PgPool::connect(&admin_url().await)
+            .await
+            .expect("connect admin");
+        let (writer, wname) = create_scratch_db(&admin, "fence_cw").await;
+        let (replica, rname) = create_scratch_db(&admin, "fence_cr").await;
+
+        let author = nostr::Keys::generate();
+        let community = Uuid::new_v4();
+        let channel = Uuid::new_v4();
+        seed_community_channel(&writer, community, channel, &author).await;
+        seed_community_channel(&replica, community, channel, &author).await;
+
+        let base = 1_700_000_000u64;
+        let m1 = signed_event_at(&author, "m1", base);
+        let m2 = signed_event_at(&author, "m2-late-commit", base + 10);
+        let m3 = signed_event_at(&author, "m3", base + 20);
+        let m4 = signed_event_at(&author, "m4", base + 30);
+        for ev in [&m1, &m2, &m3, &m4] {
+            insert_top_level(&writer, community, channel, ev).await;
+        }
+        // Replica replayed everything EXCEPT the late-committed m2.
+        for ev in [&m1, &m3, &m4] {
+            insert_top_level(&replica, community, channel, ev).await;
+        }
+
+        let db = Db::from_pools(writer.clone(), replica.clone());
+        let cid = CommunityId::from_uuid(community);
+
+        // Head page (writer): [m4, m3]; cursor lands on m3 (base+20).
+        let head = db
+            .get_channel_window(cid, channel, 2, None, None)
+            .await
+            .expect("head window");
+        let cursor = head.next_cursor.expect("has_more implies next_cursor");
+
+        // Fence closed → cursor page must come from the writer: m2 present.
+        let contents = |w: &thread::ChannelWindow| -> Vec<String> {
+            w.rows
+                .iter()
+                .map(|r| r.stored_event.event.content.clone())
+                .collect()
+        };
+        let page_closed = db
+            .get_channel_window(cid, channel, 10, Some(cursor.clone()), None)
+            .await
+            .expect("cursor page, fence closed");
+        assert_eq!(
+            contents(&page_closed),
+            vec!["m2-late-commit".to_string(), "m1".to_string()],
+            "fence closed: cursor pages route to the writer"
+        );
+
+        // Fence open but BELOW the cursor timestamp (covers base+5 only):
+        // the cursor (base+20) is not covered → writer again.
+        db.fence().force_open_for_tests(
+            chrono::DateTime::from_timestamp(base as i64 + 5, 0).expect("ts"),
+        );
+        let page_below = db
+            .get_channel_window(cid, channel, 10, Some(cursor.clone()), None)
+            .await
+            .expect("cursor page, fence below cursor");
+        assert_eq!(
+            contents(&page_below),
+            vec!["m2-late-commit".to_string(), "m1".to_string()],
+            "cursor above the fence must stay on the writer"
+        );
+
+        // Counterfactual pinning the hazard: were the fence (wrongly) open
+        // through now, the replica would serve the page WITHOUT m2 — the
+        // permanent-skip hole this fence exists to prevent.
+        db.fence().force_open_for_tests(chrono::Utc::now());
+        let page_hazard = db
+            .get_channel_window(cid, channel, 10, Some(cursor), None)
+            .await
+            .expect("cursor page, fence wrongly open");
+        assert_eq!(
+            contents(&page_hazard),
+            vec!["m1".to_string()],
+            "fixture models the inversion: an over-open fence would skip m2"
+        );
+
+        drop_scratch_db(&admin, replica, &rname).await;
+        drop_scratch_db(&admin, writer, &wname).await;
+    }
+
+    /// Thread ASC pagination, out-of-order commit adversary: the replica
     /// holds a FULL page whose newest row (`r4`) has a later key than a
     /// not-yet-replayed row (`r3`). The old under-limit check alone would
     /// serve `[r4]` and the client cursor would advance past `r3` forever.
@@ -6012,21 +8406,39 @@ mod tests {
 
         let base = admin_url().await;
         let idx = base.rfind('/').expect("db url has a path segment");
-        let db = Db::new(&DbConfig {
-            database_url: format!("{}/{}", &base[..idx], wname),
-            read_database_url: Some(format!("{}/{}", &base[..idx], rname)),
+        let writer_url = format!("{}/{}", &base[..idx], wname);
+        let replica_url = format!("{}/{}", &base[..idx], rname);
+
+        // Healthy schema: verification passes, probe starts. A SEPARATE Db
+        // instance, because its background probe legitimately opens its own
+        // fence (the heartbeat probe is writer-side only) — the refusal
+        // assertions below must run against a fence whose spawns were all
+        // refused.
+        let db_healthy = Db::new(&DbConfig {
+            database_url: writer_url.clone(),
+            read_database_url: Some(replica_url.clone()),
             max_connections: 2,
             ..DbConfig::default()
         })
         .await
         .expect("connect armed Db with replica");
-
-        // Healthy schema: verification passes, probe starts.
         assert!(
-            db.spawn_fence_probe().await.expect("verification passes"),
+            db_healthy
+                .spawn_fence_probe()
+                .await
+                .expect("verification passes"),
             "probe must start on a verified schema"
         );
 
+        let db = Db::new(&DbConfig {
+            database_url: writer_url,
+            read_database_url: Some(replica_url),
+            max_connections: 2,
+            ..DbConfig::default()
+        })
+        .await
+        .expect("connect armed Db with replica");
+
         // Sabotage A: catalog-shaped no-op — same trigger, gutted function
         // body. Catalog check alone would pass; behavior check must refuse.
         sqlx::query(
@@ -6066,6 +8478,10 @@ mod tests {
             "fence must remain closed when verification refuses the probe"
         );
 
+        db_healthy.pool.close().await;
+        if let Some(rp) = &db_healthy.read_pool {
+            rp.close().await;
+        }
         db.pool.close().await;
         if let Some(rp) = &db.read_pool {
             rp.close().await;
diff --git a/crates/buzz-db/src/migration.rs b/crates/buzz-db/src/migration.rs
index 1d1b7e05d4..6985916bba 100644
--- a/crates/buzz-db/src/migration.rs
+++ b/crates/buzz-db/src/migration.rs
@@ -347,6 +347,7 @@ mod tests {
             "push_gateway_delivery_auth_replays",
             "push_gateway_delivery_request_replays",
             "product_feedback",
+            "replica_heartbeat",
         ] {
             if normalized[insert_pos..].contains(&format!("'{value}'")) {
                 globals.insert(value.to_owned());
@@ -560,7 +561,7 @@ mod tests {
         let mut migrations: Vec<_> = MIGRATOR.iter().collect();
         migrations.sort_by_key(|migration| migration.version);
 
-        assert_eq!(migrations.len(), 25);
+        assert_eq!(migrations.len(), 26);
         assert_eq!(migrations[0].version, 1);
         assert_eq!(&*migrations[0].description, "initial schema");
         assert!(migrations[0]
@@ -904,6 +905,20 @@ mod tests {
             desired_schema.contains("CREATE TABLE join_policy_acceptances"),
             "desired-state schema must include join-policy evidence used by invite claims",
         );
+
+        // Replica heartbeat (this branch, renumbered to 0026 after
+        // 0025_relay_invites landed on main): the fence's portable read-side
+        // observation. A single CHECK'd row makes the token update the
+        // serialization point (multi-pod commit ordering), and the epoch
+        // column is what detects token resets — both are load-bearing for
+        // the routing proof.
+        assert_eq!(migrations[25].version, 26);
+        let heartbeat = migrations[25].sql.as_str();
+        assert!(heartbeat.contains("CREATE TABLE replica_heartbeat"));
+        assert!(heartbeat.contains("CHECK (id = 1)"));
+        assert!(heartbeat.contains("epoch"));
+        assert!(heartbeat.contains("INSERT INTO replica_heartbeat (id) VALUES (1)"));
+        assert!(heartbeat.contains("_operator_global_tables"));
     }
 
     #[test]
@@ -1146,7 +1161,7 @@ mod tests {
         run_migrations(&pool)
             .await
             .expect("retry succeeds after operator repair");
-        assert_eq!(applied_versions(&pool).await.last().copied(), Some(25));
+        assert_eq!(applied_versions(&pool).await.last().copied(), Some(26));
     }
 
     #[tokio::test]
diff --git a/crates/buzz-db/src/relay_members.rs b/crates/buzz-db/src/relay_members.rs
index 3805745f9b..402229cdec 100644
--- a/crates/buzz-db/src/relay_members.rs
+++ b/crates/buzz-db/src/relay_members.rs
@@ -29,14 +29,41 @@ pub struct RelayMember {
 
 /// Returns `true` if `pubkey` (64-char hex) is a member of `community`.
 pub async fn is_relay_member(pool: &PgPool, community: CommunityId, pubkey: &str) -> Result<bool> {
+    let mut conn = pool.acquire().await?;
+    is_relay_member_on(&mut conn, community, pubkey).await
+}
+
+/// [`is_relay_member`] on a specific session — the replica-routing path runs
+/// the lookup on the exact reader connection whose heartbeat observation
+/// proved fence coverage.
+pub(crate) async fn is_relay_member_on(
+    conn: &mut sqlx::PgConnection,
+    community: CommunityId,
+    pubkey: &str,
+) -> Result<bool> {
     let row = sqlx::query("SELECT 1 FROM relay_members WHERE community_id = $1 AND pubkey = $2")
         .bind(community.as_uuid())
         .bind(pubkey)
-        .fetch_optional(pool)
+        .fetch_optional(conn)
         .await?;
     Ok(row.is_some())
 }
 
+/// Returns `true` if any member of `community` holds the `admin` or `owner`
+/// role. Open relays don't *enforce* the roster, but startup
+/// (`bootstrap_owner`) and operator provisioning still populate it — this is
+/// how the workspace-profile gate detects whether a steward exists.
+pub async fn has_admin_or_owner(pool: &PgPool, community: CommunityId) -> Result<bool> {
+    let row = sqlx::query(
+        "SELECT 1 FROM relay_members \
+         WHERE community_id = $1 AND role IN ('admin', 'owner') LIMIT 1",
+    )
+    .bind(community.as_uuid())
+    .fetch_optional(pool)
+    .await?;
+    Ok(row.is_some())
+}
+
 /// Returns the relay member record for `pubkey` in `community`, or `None`.
 pub async fn get_relay_member(
     pool: &PgPool,
@@ -376,7 +403,7 @@ pub enum TransferResult {
 /// Default maximum number of communities a single pubkey can own. Enforced at
 /// the relay layer — the authoritative layer — so that concurrent transfers or
 /// transfer-vs-create races cannot both pass a preflight count.
-pub const MAX_COMMUNITIES_PER_OWNER: i64 = 3;
+pub const MAX_COMMUNITIES_PER_OWNER: i64 = 5;
 
 /// Effective per-owner community limit for this deployment.
 ///
diff --git a/crates/buzz-db/src/replica_fence.rs b/crates/buzz-db/src/replica_fence.rs
index 03bc1c77f0..c840db393e 100644
--- a/crates/buzz-db/src/replica_fence.rs
+++ b/crates/buzz-db/src/replica_fence.rs
@@ -9,38 +9,59 @@
 //!    (`clock_timestamp()`, evaluated inside commit processing). Enforcement
 //!    is armed per session via the `buzz.created_at_floor` GUC, which the
 //!    relay's writer pool sets on every connection.
-//! 2. **Ordered LSN handshake** (this module): on one pinned writer
-//!    connection, three separately-awaited statements sample
+//! 2. **Ordered heartbeat handshake** (this module): on one pinned writer
+//!    connection, separately-awaited statements sample
 //!    `S = clock_timestamp()`, then scan `pg_stat_activity` for the oldest
-//!    open transaction, then capture `L = pg_current_wal_lsn()` **last**.
-//!    Once the replica reports `pg_last_wal_replay_lsn() >= L`, every
-//!    transaction partitions into exactly three buckets:
-//!      (a) finished before the activity scan — its commit WAL precedes `L`,
-//!          so the replica has replayed it;
+//!    open transaction, then — **last** — commit heartbeat token `M` via a
+//!    single-row `UPDATE replica_heartbeat ... RETURNING token, epoch`
+//!    (migration 0026). Because the single-row UPDATE serializes all pods'
+//!    probes, tokens are globally commit-ordered. A reader **session** that
+//!    observes `token >= M` on its own connection has, by WAL/storage replay
+//!    order, also replayed every commit that preceded M's commit; every
+//!    transaction then partitions into exactly three buckets:
+//!      (a) finished before the activity scan — its commit precedes `M`'s
+//!          commit, so the replica session has replayed it;
 //!      (b) open at the activity scan — represented by `xact_start`, so it is
 //!          bounded by the `oldest_xact_start` term;
 //!      (c) started after the activity scan — its deferred floor guard runs
 //!          after `S`, so it cannot commit a row with
 //!          `created_at < S - floor`.
-//!    There is no fourth bucket. The fence therefore advances to
-//!    `min(oldest_xact_start, S) - floor - clock_margin`, and every
-//!    channel-window row with `created_at <= fence` is on the replica.
+//!    There is no fourth bucket. Each committed token `M` therefore proves a
+//!    **fence wall** of `min(oldest_xact_start, S) - floor - clock_margin`:
+//!    every channel-window row with `created_at <= fence_wall(M)` is present
+//!    on any reader session observing `token >= M`.
+//!
+//! Unlike the previous WAL-LSN observation (`pg_last_wal_replay_lsn()`, which
+//! Aurora reader endpoints hide), the token observation is portable and —
+//! critically — **snapshot-local**: routing opens a `REPEATABLE READ, READ
+//! ONLY` transaction on the reader session that will serve the page and
+//! observes the heartbeat as its first statement, so the proof binds to the
+//! exact snapshot every follow-up statement in the request (page,
+//! participants, aux closure) reads from — never to a different pooled
+//! session (readers behind one endpoint may sit at different replay
+//! positions), and never to a later autocommit snapshot on the same wire.
+//! An observed token lower than the newest retained `M` is ordinary
+//! replication lag, not a fault; the resolver simply proves from an older
+//! retained `M`. Regression detection is writer-side only: a non-monotonic
+//! `RETURNING token` or an epoch change (restore/re-seed) clears the retained
+//! ring, so no stale entry can masquerade as fresh coverage.
 //!
 //! Everything fails **closed**: probe errors, masked `pg_stat_activity`
-//! visibility, NULL/absent replica LSN (Aurora observability differences),
-//! non-advancing replay, or probe staleness all close the fence, which routes
-//! all reads back to the writer — degraded capacity, never holes.
+//! visibility, an unreadable heartbeat row on the reader session, an epoch
+//! mismatch, or an observed token below every retained entry all route the
+//! request back to the writer — degraded capacity, never holes.
 //!
 //! Operational bypasses (sessions without the GUC, `session_replication_role
 //! = replica` restores) are outside the proof by design and require holding
 //! the fence closed for their duration; see `migrations/0021`.
 
-use std::sync::atomic::{AtomicI64, Ordering};
-use std::sync::Arc;
-use std::time::Duration;
+use std::collections::VecDeque;
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
 
 use chrono::{DateTime, Utc};
-use sqlx::{PgPool, Row};
+use sqlx::{PgConnection, PgPool, Row};
+use uuid::Uuid;
 
 /// Seconds of `created_at` history the commit-time floor guard tolerates.
 ///
@@ -58,79 +79,231 @@ pub const CREATED_AT_FLOOR_SECS: i64 = 960;
 /// between machines.
 pub const FENCE_CLOCK_MARGIN_SECS: i64 = 5;
 
-/// How often the probe samples the writer and checks the replica.
-pub const PROBE_INTERVAL: Duration = Duration::from_secs(5);
+/// How often the probe samples the writer and commits a heartbeat token.
+///
+/// 500ms keeps the cadence at least 2x under the smallest sensible bounded
+/// budget (`BUZZ_REPLICA_READ_MAX_AGE_MS`, deploy plan 1000ms) so
+/// eligibility doesn't flap between beats. Cost is one single-row UPDATE
+/// tuple of WAL per beat per pod — ~20 beats/s fleet-wide, <0.1% of the
+/// writer.
+pub const PROBE_INTERVAL: Duration = Duration::from_millis(500);
 
-/// A fence older than this is stale: the probe has stopped confirming
-/// freshness and the fence closes until a new handshake completes.
+/// A fence whose newest entry is older than this is stale: the probe has
+/// stopped committing tokens and routing eligibility closes until a new
+/// handshake completes.
+///
+/// Note this is an availability hygiene gate, not a soundness requirement:
+/// a retained entry's proof (`token >= M` on a session implies every row
+/// `<= fence_wall(M)` is present there) never decays. Closing on staleness
+/// just stops spending reader checkouts once the probe is evidently dead.
 pub const FENCE_STALENESS: Duration = Duration::from_secs(30);
 
-/// Sentinel: fence closed (no verified replica coverage).
-const CLOSED: i64 = i64::MIN;
+/// How many `(token, fence_wall)` entries the fence retains. At one probe
+/// per [`PROBE_INTERVAL`] (500ms) this is ~60 seconds of history — a reader
+/// session lagging further than that behind the newest token fails closed
+/// (routes to the writer) rather than proving from thin air. Aurora reader
+/// lag is typically tens of milliseconds; a reader minutes behind is a
+/// fault, not a routing candidate.
+const RING_CAPACITY: usize = 120;
 
-/// Shared fence state. `Db` holds an `Arc` of this; the probe task advances
-/// it and cursor routing consults it.
-#[derive(Debug)]
+// The retained window must outlast the staleness gate: if the ring held
+// less than FENCE_STALENESS of history, a non-stale newest entry could
+// coexist with proved-but-evicted older entries, failing sessions closed
+// for capacity rather than lag. Compile-checked so a future cadence or
+// capacity tweak can't silently shrink the window below the gate.
+const _: () = assert!(
+    RING_CAPACITY as u64 * PROBE_INTERVAL.as_millis() as u64 > FENCE_STALENESS.as_millis() as u64,
+    "fence ring must retain more history than the staleness gate"
+);
+
+/// One retained heartbeat observation: proof material for reader sessions.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct TokenEntry {
+    /// The committed heartbeat token `M`.
+    pub token: i64,
+    /// Monotonic instant captured just before `M` was committed. `elapsed()`
+    /// bounds (from above) how old a session observing `token >= M` can be —
+    /// the freshness term of the head-routing predicate.
+    pub committed_at: Instant,
+    /// `min(oldest_xact_start, S) - floor - clock_margin` for `M`'s
+    /// handshake: every channel-window row with `created_at <= fence_wall`
+    /// is present on any session observing `token >= M`.
+    pub fence_wall: DateTime<Utc>,
+}
+
+#[derive(Debug, Default)]
+struct FenceInner {
+    /// Epoch the retained ring belongs to. `None` until the first probe —
+    /// or after the test hook, whose injected entry deliberately bypasses
+    /// the epoch comparison in [`ReplicaFence::resolve`].
+    epoch: Option<Uuid>,
+    /// Retained entries in strictly increasing token order.
+    ring: VecDeque<TokenEntry>,
+}
+
+/// Outcome of recording one probe sample.
+#[derive(Debug, PartialEq, Eq)]
+pub enum RecordOutcome {
+    /// Entry retained; proofs may cite it.
+    Recorded,
+    /// The token went backwards within the same epoch — a restore that kept
+    /// the old epoch. The ring was cleared and the entry discarded; the
+    /// probe must rotate the epoch before recording again (a reader still on
+    /// the pre-rewind timeline could otherwise observe a *higher* token that
+    /// proves nothing about the new timeline).
+    TokenRegression,
+}
+
+/// Outcome of resolving one reader-session observation against the ring.
+/// Everything but [`ResolveOutcome::Proved`] fails closed (routes to the
+/// writer); the variants exist so route metrics can name the reason.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ResolveOutcome {
+    /// The observation proves this retained entry.
+    Proved(TokenEntry),
+    /// The observed epoch is not the ring's epoch — the session is on a
+    /// different timeline (restore) or the ring was rotated under it.
+    EpochMismatch,
+    /// The observed token is below every retained entry: the reader lags
+    /// further than the ring's history (or the ring is empty).
+    TokenBehind,
+}
+
+impl ResolveOutcome {
+    /// The proved entry, if any.
+    pub fn proved(self) -> Option<TokenEntry> {
+        match self {
+            ResolveOutcome::Proved(entry) => Some(entry),
+            _ => None,
+        }
+    }
+}
+
+/// Shared fence state. `Db` holds an `Arc` of this; the probe task records
+/// entries and per-request routing resolves proofs against it.
+#[derive(Debug, Default)]
 pub struct ReplicaFence {
-    /// Unix micros of the newest verified-complete timestamp, or `CLOSED`.
-    fence_micros: AtomicI64,
-    /// Unix micros when the fence was last advanced (staleness check).
-    updated_micros: AtomicI64,
+    inner: Mutex<FenceInner>,
 }
 
 impl ReplicaFence {
-    /// A new fence, initially closed.
+    /// A new fence, initially closed (empty ring).
     pub fn new() -> Self {
-        Self {
-            fence_micros: AtomicI64::new(CLOSED),
-            updated_micros: AtomicI64::new(CLOSED),
-        }
+        Self::default()
     }
 
-    /// Close the fence: all cursor reads route to the writer.
+    /// Close the fence: drop all retained proofs; reads route to the writer.
     pub fn close(&self) {
-        self.fence_micros.store(CLOSED, Ordering::Relaxed);
+        let mut inner = self.inner.lock().expect("fence lock poisoned");
+        inner.ring.clear();
     }
 
-    fn advance(&self, fence: DateTime<Utc>) {
-        self.fence_micros
-            .store(fence.timestamp_micros(), Ordering::Relaxed);
-        self.updated_micros
-            .store(Utc::now().timestamp_micros(), Ordering::Relaxed);
+    /// Record one probe sample. Epoch changes (re-seed) clear the ring and
+    /// start a new one under the observed epoch — sound, because an entry
+    /// only proves commits on its own timeline and readers must match the
+    /// epoch to cite it. A same-epoch token regression is the unsafe case:
+    /// see [`RecordOutcome::TokenRegression`].
+    pub fn record(
+        &self,
+        token: i64,
+        epoch: Uuid,
+        committed_at: Instant,
+        fence_wall: DateTime<Utc>,
+    ) -> RecordOutcome {
+        let mut inner = self.inner.lock().expect("fence lock poisoned");
+        if inner.epoch != Some(epoch) {
+            inner.ring.clear();
+            inner.epoch = Some(epoch);
+        } else if inner.ring.back().is_some_and(|last| token <= last.token) {
+            inner.ring.clear();
+            return RecordOutcome::TokenRegression;
+        }
+        if inner.ring.len() == RING_CAPACITY {
+            inner.ring.pop_front();
+        }
+        inner.ring.push_back(TokenEntry {
+            token,
+            committed_at,
+            fence_wall,
+        });
+        RecordOutcome::Recorded
     }
 
-    /// The current fence, or `None` when closed or stale.
+    /// Resolve the strongest proof a reader session's observation supports:
+    /// the greatest retained entry with `entry.token <= observed_token`,
+    /// provided the observed epoch matches the ring's. Non-`Proved` outcomes
+    /// fail closed; they are distinguished only for route metrics.
+    pub fn resolve(&self, observed_token: i64, observed_epoch: Uuid) -> ResolveOutcome {
+        let inner = self.inner.lock().expect("fence lock poisoned");
+        match inner.epoch {
+            Some(e) if e != observed_epoch => return ResolveOutcome::EpochMismatch,
+            // `None` with a non-empty ring only happens via the test hook;
+            // the epoch comparison is deliberately skipped there.
+            _ => {}
+        }
+        inner
+            .ring
+            .iter()
+            .rev()
+            .find(|entry| entry.token <= observed_token)
+            .copied()
+            .map_or(ResolveOutcome::TokenBehind, ResolveOutcome::Proved)
+    }
+
+    /// The newest retained entry, staleness-gated. Used as the cheap
+    /// pre-check before spending a reader checkout, and for observability.
+    pub fn newest(&self) -> Option<TokenEntry> {
+        let inner = self.inner.lock().expect("fence lock poisoned");
+        inner
+            .ring
+            .back()
+            .filter(|entry| entry.committed_at.elapsed() <= FENCE_STALENESS)
+            .copied()
+    }
+
+    /// Age of the newest retained entry, ungated (observability: how long
+    /// since the probe last committed a token).
+    pub fn heartbeat_age(&self) -> Option<Duration> {
+        let inner = self.inner.lock().expect("fence lock poisoned");
+        inner.ring.back().map(|entry| entry.committed_at.elapsed())
+    }
+
+    /// The newest fence wall, or `None` when closed or stale.
     ///
-    /// Rows with `created_at <= fence` are verified present on the replica.
+    /// Rows with `created_at <= fence` are verified present on a reader
+    /// session that proves the newest entry; whether a *given* session does
+    /// is decided per request via [`ReplicaFence::resolve`].
     pub fn verified_through(&self) -> Option<DateTime<Utc>> {
-        let raw = self.fence_micros.load(Ordering::Relaxed);
-        if raw == CLOSED {
-            return None;
-        }
-        let updated = self.updated_micros.load(Ordering::Relaxed);
-        let age_micros = Utc::now().timestamp_micros().saturating_sub(updated);
-        if age_micros > FENCE_STALENESS.as_micros() as i64 {
-            return None;
-        }
-        DateTime::from_timestamp_micros(raw)
+        self.newest().map(|entry| entry.fence_wall)
     }
 
-    /// Whether the replica verifiably holds every channel-window row at or
-    /// before `ts`.
+    /// Whether some retained entry's wall covers `ts` — the cheap routing
+    /// pre-check (the connection-local observation still has to prove it).
     pub fn covers(&self, ts: DateTime<Utc>) -> bool {
         self.verified_through().is_some_and(|fence| ts <= fence)
     }
 
     /// Test hook: force the fence open through `ts` without a probe.
-    /// Used by routing tests that stand up a divergent fake replica.
+    /// Injects an entry any observed token satisfies (`i64::MIN`) with no
+    /// epoch recorded, so the epoch comparison is bypassed — routing tests
+    /// stand up a divergent fake replica whose heartbeat epoch differs from
+    /// the writer's.
     pub fn force_open_for_tests(&self, ts: DateTime<Utc>) {
-        self.advance(ts);
+        self.force_open_for_tests_at(ts, Instant::now());
     }
-}
 
-impl Default for ReplicaFence {
-    fn default() -> Self {
-        Self::new()
+    /// [`ReplicaFence::force_open_for_tests`] with an explicit commit
+    /// instant, for pinning age-gated behavior (head-budget and staleness
+    /// tests inject entries "committed" in the past).
+    pub fn force_open_for_tests_at(&self, ts: DateTime<Utc>, committed_at: Instant) {
+        let mut inner = self.inner.lock().expect("fence lock poisoned");
+        inner.epoch = None;
+        inner.ring.clear();
+        inner.ring.push_back(TokenEntry {
+            token: i64::MIN,
+            committed_at,
+            fence_wall: ts,
+        });
     }
 }
 
@@ -332,15 +505,20 @@ struct WriterSample {
     /// Oldest open transaction among other client backends at scan time,
     /// or `None` when no transaction was open.
     oldest_xact_start: Option<DateTime<Utc>>,
-    /// `L`: writer `pg_current_wal_lsn()` captured last, as text.
-    wal_lsn: String,
+    /// `M`: the heartbeat token committed **last**, after the scan.
+    token: i64,
+    /// Heartbeat epoch returned with `M`.
+    epoch: Uuid,
+    /// Monotonic instant captured immediately before committing `M` — an
+    /// upper bound on how old a session observing `token >= M` can be.
+    committed_at: Instant,
 }
 
 /// Errors that close the fence. All variants are logged and treated
 /// identically: fail closed.
 #[derive(Debug, thiserror::Error)]
 pub enum ProbeError {
-    /// A probe query against writer or replica failed.
+    /// A probe query against the writer failed.
     #[error("writer probe query failed: {0}")]
     Writer(#[from] sqlx::Error),
     /// `pg_stat_activity` hid state for another backend that could hold an
@@ -353,14 +531,15 @@ pub enum ProbeError {
         /// Number of other client backends with masked/unknown state.
         masked: i64,
     },
-    /// The replica returned NULL for the replay-LSN comparison.
-    #[error("replica did not report a comparable replay LSN")]
-    ReplicaLsnUnavailable,
+    /// The single heartbeat row (migration 0026) is missing on the writer.
+    #[error("replica_heartbeat row missing on the writer — migration 0026 not applied?")]
+    HeartbeatRowMissing,
 }
 
-/// Take one ordered writer sample: S, then activity scan, then L **last**.
+/// Take one ordered writer sample: S, then activity scan, then commit the
+/// heartbeat token **last**.
 ///
-/// The three statements are separately awaited on a single pinned connection;
+/// The statements are separately awaited on a single pinned connection;
 /// a single SELECT would not guarantee evaluation order across the
 /// subexpressions, reopening the race this ordering exists to close.
 async fn sample_writer(writer: &PgPool) -> Result<WriterSample, ProbeError> {
@@ -393,8 +572,8 @@ async fn sample_writer(writer: &PgPool) -> Result<WriterSample, ProbeError> {
     //
     //    Prepared transactions (2PC) are a bucket of their own: while
     //    prepared they have left `pg_stat_activity` but can still commit
-    //    after `L`. Their deferred floor guard already ran at PREPARE, so
-    //    `pg_prepared_xacts.prepared` bounds their rows exactly like
+    //    after the token. Their deferred floor guard already ran at PREPARE,
+    //    so `pg_prepared_xacts.prepared` bounds their rows exactly like
     //    `xact_start`; fold it into the same minimum.
     let row = sqlx::query(
         r#"
@@ -423,80 +602,171 @@ async fn sample_writer(writer: &PgPool) -> Result<WriterSample, ProbeError> {
     }
     let oldest_xact_start: Option<DateTime<Utc>> = row.get("oldest_xact_start");
 
-    // 3. L last.
-    let wal_lsn: String = sqlx::query_scalar("SELECT pg_current_wal_lsn()::text")
-        .fetch_one(&mut *conn)
-        .await?;
+    // 3. Token commit LAST, on the same pinned connection. The single-row
+    //    UPDATE serializes concurrent pods' probes, so RETURNING token is
+    //    globally commit-ordered. `committed_at` is captured before the
+    //    round trip so `elapsed()` over-estimates the observation's age —
+    //    the conservative direction for the head-freshness bound.
+    let committed_at = Instant::now();
+    let row = sqlx::query(
+        "UPDATE replica_heartbeat SET token = token + 1 WHERE id = 1 RETURNING token, epoch",
+    )
+    .fetch_optional(&mut *conn)
+    .await?
+    .ok_or(ProbeError::HeartbeatRowMissing)?;
 
     Ok(WriterSample {
         sampled_at,
         oldest_xact_start,
-        wal_lsn,
+        token: row.get("token"),
+        epoch: row.get("epoch"),
+        committed_at,
     })
 }
 
-/// Whether the replica has replayed at least through `wal_lsn`.
-///
-/// The comparison happens on the replica in pg_lsn domain. The
-/// `pg_is_in_recovery()` gate is load-bearing: after crash recovery or
-/// promotion a *primary* returns a static non-NULL `pg_last_wal_replay_lsn()`
-/// rather than NULL, so NULL-checking alone would not reliably detect a
-/// misrouted "replica" URL. Not-in-recovery, NULL replay LSN, or Aurora
-/// hiding either is an error → fence closes.
-async fn replica_covers(replica: &PgPool, wal_lsn: &str) -> Result<bool, ProbeError> {
-    let covered: Option<bool> = sqlx::query_scalar(
-        r#"
-        SELECT CASE
-            WHEN pg_is_in_recovery() THEN pg_last_wal_replay_lsn() >= $1::pg_lsn
-            ELSE NULL
-        END
-        "#,
-    )
-    .bind(wal_lsn)
-    .fetch_one(replica)
-    .await?;
-    covered.ok_or(ProbeError::ReplicaLsnUnavailable)
+/// The fence wall proved by one handshake:
+/// `min(oldest_xact_start, S) - floor - clock_margin`.
+fn fence_wall(sample_s: DateTime<Utc>, oldest_xact_start: Option<DateTime<Utc>>) -> DateTime<Utc> {
+    let lower = match oldest_xact_start {
+        Some(oldest) => oldest.min(sample_s),
+        None => sample_s,
+    };
+    lower
+        - chrono::Duration::seconds(CREATED_AT_FLOOR_SECS)
+        - chrono::Duration::seconds(FENCE_CLOCK_MARGIN_SECS)
 }
 
-/// Run one full handshake and, on success, advance the fence.
+/// Run one full handshake and record the resulting `(token, fence_wall)`.
 ///
-/// Returns the new fence value for observability. `Ok(None)` means the
-/// replica has not yet replayed past the sample; the fence is left as-is
-/// (staleness will close it if this persists).
-pub async fn probe_once(
-    writer: &PgPool,
-    replica: &PgPool,
-    fence: &ReplicaFence,
-) -> Result<Option<DateTime<Utc>>, ProbeError> {
+/// On a same-epoch token regression (the writer was restored from a backup
+/// that kept its epoch), the retained ring has already been cleared by
+/// [`ReplicaFence::record`]; this additionally **rotates the epoch** on the
+/// writer and records the rotated token, so a reader still serving the
+/// pre-rewind timeline (whose old, higher token would otherwise satisfy
+/// `token >= M`) fails the epoch check instead of proving stale coverage.
+pub async fn probe_once(writer: &PgPool, fence: &ReplicaFence) -> Result<TokenEntry, ProbeError> {
     let sample = sample_writer(writer).await?;
-    if !replica_covers(replica, &sample.wal_lsn).await? {
-        return Ok(None);
+    let wall = fence_wall(sample.sampled_at, sample.oldest_xact_start);
+    match fence.record(sample.token, sample.epoch, sample.committed_at, wall) {
+        RecordOutcome::Recorded => Ok(TokenEntry {
+            token: sample.token,
+            committed_at: sample.committed_at,
+            fence_wall: wall,
+        }),
+        RecordOutcome::TokenRegression => {
+            tracing::warn!(
+                token = sample.token,
+                "replica heartbeat token regressed within its epoch (restore?); rotating epoch"
+            );
+            // The rotation commit happens after this sample's activity scan,
+            // so the same three-bucket argument (and the same wall) holds
+            // for the rotated token.
+            let committed_at = Instant::now();
+            let row = sqlx::query(
+                "UPDATE replica_heartbeat SET epoch = gen_random_uuid(), token = token + 1 \
+                 WHERE id = 1 RETURNING token, epoch",
+            )
+            .fetch_optional(writer)
+            .await?
+            .ok_or(ProbeError::HeartbeatRowMissing)?;
+            let token: i64 = row.get("token");
+            let epoch: Uuid = row.get("epoch");
+            // A fresh epoch always clears and records; regression is
+            // impossible against an empty ring.
+            fence.record(token, epoch, committed_at, wall);
+            Ok(TokenEntry {
+                token,
+                committed_at,
+                fence_wall: wall,
+            })
+        }
     }
-    let lower = match sample.oldest_xact_start {
-        Some(oldest) => oldest.min(sample.sampled_at),
-        None => sample.sampled_at,
+}
+
+/// The Aurora **PostgreSQL** instance-identity function. Named once so the
+/// capability probe and the observation query can never disagree — and
+/// pinned by a unit test, because the MySQL-family spelling
+/// (`aurora_server_id`) is a near-miss that would make the capability probe
+/// cache a permanent `false` on real Aurora (42883) and silently strip the
+/// instance id from canary evidence.
+pub const AURORA_IDENTITY_FN: &str = "aurora_db_instance_identifier";
+
+/// Whether this reader endpoint supports [`AURORA_IDENTITY_FN`] — probed
+/// ONCE per process on a plain autocommit checkout, never inside a request
+/// transaction (an undefined-function error would abort the transaction
+/// and fail the proof). `Ok(false)` is the definitive "not Aurora" answer
+/// (undefined_function, SQLSTATE 42883); transient errors surface as `Err`
+/// so the caller can retry the probe on a later request instead of caching
+/// a wrong answer.
+pub async fn reader_supports_aurora_identity(conn: &mut PgConnection) -> Result<bool, sqlx::Error> {
+    match sqlx::query(sqlx::AssertSqlSafe(format!(
+        "SELECT {AURORA_IDENTITY_FN}()"
+    )))
+    .fetch_one(&mut *conn)
+    .await
+    {
+        Ok(_) => Ok(true),
+        Err(sqlx::Error::Database(e)) if e.code().as_deref() == Some("42883") => Ok(false),
+        Err(e) => Err(e),
+    }
+}
+
+/// Observe the heartbeat on a specific reader session — the
+/// connection-local half of the proof. Returns the observed token/epoch
+/// plus the backend identity of the session for route-decision evidence:
+/// `addr:port pid=N` (`local` on unix sockets), prefixed with the Aurora
+/// instance id when `aurora` is set (only pass `true` after
+/// [`reader_supports_aurora_identity`] confirmed it — the function
+/// reference fails at parse time on plain Postgres). `None` when the row
+/// is missing there (migration not yet replayed): fail closed.
+pub async fn observe_heartbeat(
+    conn: &mut PgConnection,
+    aurora: bool,
+) -> Result<Option<HeartbeatObservation>, sqlx::Error> {
+    const ADDR_PID: &str = "COALESCE(host(inet_server_addr()) || ':' || \
+         inet_server_port()::text, 'local') || ' pid=' || pg_backend_pid()::text";
+    let sql = if aurora {
+        format!(
+            "SELECT token, epoch, {AURORA_IDENTITY_FN}() || ' @ ' || {ADDR_PID} AS backend \
+             FROM replica_heartbeat WHERE id = 1"
+        )
+    } else {
+        format!(
+            "SELECT token, epoch, {ADDR_PID} AS backend \
+             FROM replica_heartbeat WHERE id = 1"
+        )
     };
-    let new_fence = lower
-        - chrono::Duration::seconds(CREATED_AT_FLOOR_SECS)
-        - chrono::Duration::seconds(FENCE_CLOCK_MARGIN_SECS);
-    fence.advance(new_fence);
-    Ok(Some(new_fence))
+    let row = sqlx::query(sqlx::AssertSqlSafe(sql))
+        .fetch_optional(&mut *conn)
+        .await?;
+    Ok(row.map(|r| HeartbeatObservation {
+        token: r.get("token"),
+        epoch: r.get("epoch"),
+        backend: r.get("backend"),
+    }))
 }
 
-/// Background probe loop: sample every `PROBE_INTERVAL`, close the fence on
-/// any error. Runs for the life of the process.
-pub async fn run_probe(writer: PgPool, replica: PgPool, fence: Arc<ReplicaFence>) {
+/// One reader-session heartbeat observation (see [`observe_heartbeat`]).
+#[derive(Debug, Clone)]
+pub struct HeartbeatObservation {
+    /// The token the session has replayed through.
+    pub token: i64,
+    /// The epoch the session observes — must match the ring's.
+    pub epoch: Uuid,
+    /// Backend identity of the observed session, so live evidence records
+    /// which reader served both proof and page.
+    pub backend: String,
+}
+
+/// Background probe loop: commit a heartbeat token every `PROBE_INTERVAL`;
+/// close the fence on any error. Runs for the life of the process.
+pub async fn run_probe(writer: PgPool, fence: Arc<ReplicaFence>) {
     let mut interval = tokio::time::interval(PROBE_INTERVAL);
     interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
     loop {
         interval.tick().await;
-        match probe_once(&writer, &replica, &fence).await {
-            Ok(Some(_)) => {}
-            Ok(None) => {
-                // Replica behind the sample: leave the fence; staleness
-                // closes it if the replica stays behind.
-                tracing::debug!("replica fence: replay behind writer sample");
-            }
+        match probe_once(&writer, &fence).await {
+            Ok(_) => {}
             Err(e) => {
                 fence.close();
                 tracing::warn!(error = %e, "replica fence probe failed; fence closed");
@@ -515,14 +785,50 @@ mod tests {
         std::env::var("TEST_DATABASE_URL").unwrap_or_else(|_| TEST_DB_URL.into())
     }
 
+    /// A private scratch database with migrations applied: the probe tests
+    /// mutate the singleton heartbeat row (rewind/rotate), which must never
+    /// race the shared dev database or each other.
+    async fn scratch_db() -> (PgPool, PgPool, String) {
+        let admin = PgPool::connect(&test_db_url())
+            .await
+            .expect("connect admin");
+        let name = format!("fence_probe_{}", uuid::Uuid::new_v4().simple());
+        sqlx::query(sqlx::AssertSqlSafe(format!("CREATE DATABASE {name}")))
+            .execute(&admin)
+            .await
+            .expect("create scratch db");
+        let base = test_db_url();
+        let idx = base.rfind('/').expect("db url has a path segment");
+        let pool = PgPool::connect(&format!("{}/{}", &base[..idx], name))
+            .await
+            .expect("connect scratch db");
+        crate::migration::run_migrations(&pool)
+            .await
+            .expect("migrate scratch db");
+        (admin, pool, name)
+    }
+
+    async fn drop_scratch_db(admin: &PgPool, pool: PgPool, name: &str) {
+        pool.close().await;
+        let _ = sqlx::query(sqlx::AssertSqlSafe(format!(
+            "DROP DATABASE IF EXISTS {name} WITH (FORCE)"
+        )))
+        .execute(admin)
+        .await;
+    }
+
     #[test]
-    fn fence_starts_closed_and_opens_on_advance() {
+    fn fence_starts_closed_and_opens_on_record() {
         let fence = ReplicaFence::new();
         assert!(fence.verified_through().is_none(), "must start closed");
         assert!(!fence.covers(Utc::now() - chrono::Duration::days(365)));
 
         let ts = Utc::now();
-        fence.advance(ts);
+        let epoch = Uuid::new_v4();
+        assert_eq!(
+            fence.record(1, epoch, Instant::now(), ts),
+            RecordOutcome::Recorded
+        );
         assert_eq!(fence.verified_through(), Some(ts));
         assert!(fence.covers(ts - chrono::Duration::seconds(1)));
         assert!(fence.covers(ts), "boundary is inclusive");
@@ -537,19 +843,116 @@ mod tests {
     fn stale_fence_reads_as_closed() {
         let fence = ReplicaFence::new();
         let ts = Utc::now();
-        fence
-            .fence_micros
-            .store(ts.timestamp_micros(), Ordering::Relaxed);
-        // Last update older than the staleness budget.
-        let stale = (Utc::now()
-            - chrono::Duration::from_std(FENCE_STALENESS).expect("duration")
-            - chrono::Duration::seconds(1))
-        .timestamp_micros();
-        fence.updated_micros.store(stale, Ordering::Relaxed);
+        // Newest entry committed longer ago than the staleness budget.
+        let stale_instant = Instant::now() - (FENCE_STALENESS + Duration::from_secs(1));
+        fence.record(1, Uuid::new_v4(), stale_instant, ts);
         assert!(
             fence.verified_through().is_none(),
             "a fence the probe stopped confirming must read as closed"
         );
+        // heartbeat_age is deliberately ungated (observability).
+        assert!(fence.heartbeat_age().expect("entry retained") > FENCE_STALENESS);
+    }
+
+    /// Resolve picks the greatest retained entry <= the observed token —
+    /// a lagged reader proves from an older wall, never from thin air.
+    #[test]
+    fn resolve_picks_greatest_retained_token_at_or_below_observation() {
+        let fence = ReplicaFence::new();
+        let epoch = Uuid::new_v4();
+        let base = Utc::now();
+        for (token, secs) in [(10i64, 0i64), (20, 10), (30, 20)] {
+            fence.record(
+                token,
+                epoch,
+                Instant::now(),
+                base + chrono::Duration::seconds(secs),
+            );
+        }
+
+        // Exact hit.
+        assert_eq!(fence.resolve(20, epoch).proved().expect("proof").token, 20);
+        // Between entries: prove from the older one.
+        assert_eq!(fence.resolve(25, epoch).proved().expect("proof").token, 20);
+        // Ahead of everything retained: newest.
+        assert_eq!(
+            fence.resolve(1000, epoch).proved().expect("proof").token,
+            30
+        );
+        // Behind everything retained: no proof.
+        assert_eq!(
+            fence.resolve(9, epoch),
+            ResolveOutcome::TokenBehind,
+            "token below ring fails closed"
+        );
+        // Wrong epoch: no proof, regardless of token.
+        assert_eq!(
+            fence.resolve(1000, Uuid::new_v4()),
+            ResolveOutcome::EpochMismatch,
+            "epoch mismatch fails closed"
+        );
+    }
+
+    /// An epoch change clears the ring and starts a new one; a same-epoch
+    /// token regression clears the ring and reports the fault.
+    #[test]
+    fn record_epoch_change_resets_and_same_epoch_regression_fails() {
+        let fence = ReplicaFence::new();
+        let epoch_a = Uuid::new_v4();
+        let ts = Utc::now();
+        fence.record(10, epoch_a, Instant::now(), ts);
+        fence.record(11, epoch_a, Instant::now(), ts);
+
+        // New epoch, lower token: fine — new timeline, old proofs dropped.
+        let epoch_b = Uuid::new_v4();
+        assert_eq!(
+            fence.record(3, epoch_b, Instant::now(), ts),
+            RecordOutcome::Recorded
+        );
+        assert_eq!(
+            fence.resolve(11, epoch_a),
+            ResolveOutcome::EpochMismatch,
+            "entries from the old epoch must be gone"
+        );
+        assert_eq!(fence.resolve(3, epoch_b).proved().expect("proof").token, 3);
+
+        // Same epoch, non-increasing token: regression → cleared + reported.
+        assert_eq!(
+            fence.record(3, epoch_b, Instant::now(), ts),
+            RecordOutcome::TokenRegression
+        );
+        assert!(
+            fence.verified_through().is_none(),
+            "ring cleared on regression"
+        );
+        assert_eq!(
+            fence.resolve(i64::MAX, epoch_b),
+            ResolveOutcome::TokenBehind
+        );
+    }
+
+    /// The ring is bounded: old entries fall off and stop proving coverage.
+    #[test]
+    fn ring_capacity_evicts_oldest_entries() {
+        let fence = ReplicaFence::new();
+        let epoch = Uuid::new_v4();
+        let ts = Utc::now();
+        for token in 0..(RING_CAPACITY as i64 + 10) {
+            fence.record(token, epoch, Instant::now(), ts);
+        }
+        assert_eq!(
+            fence.resolve(5, epoch),
+            ResolveOutcome::TokenBehind,
+            "evicted tokens must no longer prove coverage"
+        );
+        assert_eq!(
+            fence
+                .resolve(i64::MAX, epoch)
+                .proved()
+                .expect("proof")
+                .token,
+            RING_CAPACITY as i64 + 9
+        );
     }
 
     /// The activity scan must (a) represent another session's open
@@ -582,9 +985,14 @@ mod tests {
             oldest <= during.sampled_at,
             "xact_start precedes the sample that observed it"
         );
-        // S is captured before the activity scan, L after: the sample's
-        // ordering invariant.
+        // S is captured before the activity scan, the token commit after:
+        // the sample's ordering invariant.
         assert!(during.sampled_at >= before.sampled_at);
+        assert!(
+            during.token > before.token,
+            "each sample must commit a strictly newer token"
+        );
+        assert_eq!(during.epoch, before.epoch, "epoch is stable across samples");
 
         tx.rollback().await.expect("rollback");
     }
@@ -641,21 +1049,140 @@ mod tests {
             .expect("drop role");
     }
 
-    /// A primary (non-replica) database returns NULL from
-    /// `pg_last_wal_replay_lsn()`; the probe must fail closed, never
-    /// synthesize freshness. This is also the Aurora-observability guard:
-    /// if the reader endpoint hides replay LSNs, routing stays writer-only.
+    /// The Aurora PostgreSQL identity function name is exact — the
+    /// MySQL-family near-miss (`aurora_server_id`) would make the
+    /// capability probe cache a permanent false on real Aurora and
+    /// silently strip the instance id from canary evidence (Wren, delta
+    /// review of a472327). AWS reference: aurora_db_instance_identifier()
+    /// (Aurora PostgreSQL user guide; also awslabs/pg-collector).
+    #[test]
+    fn aurora_identity_function_name_is_the_postgres_one() {
+        assert_eq!(AURORA_IDENTITY_FN, "aurora_db_instance_identifier");
+    }
+
+    /// The Aurora identity capability probe must answer a definitive
+    /// `false` on plain Postgres (undefined_function), not error — and the
+    /// error path must not poison the connection for later statements.
     #[tokio::test]
     #[ignore = "requires Postgres"]
-    async fn probe_fails_closed_when_replica_lsn_unavailable() {
+    async fn aurora_identity_probe_reports_false_on_plain_postgres() {
         let pool = PgPool::connect(&test_db_url()).await.expect("connect");
+        let mut conn = pool.acquire().await.expect("conn");
+        assert!(
+            !reader_supports_aurora_identity(&mut conn)
+                .await
+                .expect("probe must not error on plain postgres"),
+            "plain postgres must report no aurora identity support"
+        );
+        // The failed function lookup must not have wedged the session.
+        let one: i32 = sqlx::query_scalar("SELECT 1")
+            .fetch_one(&mut *conn)
+            .await
+            .expect("connection usable after probe");
+        assert_eq!(one, 1);
+    }
+
+    /// End-to-end probe against a real database: each probe commits a
+    /// strictly newer token, records a retained entry, and a session on the
+    /// same database observes a token/epoch that resolves that entry.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn probe_commits_tokens_and_sessions_prove_coverage() {
+        let (admin, pool, name) = scratch_db().await;
+        let fence = ReplicaFence::new();
+
+        let first = probe_once(&pool, &fence).await.expect("first probe");
+        let second = probe_once(&pool, &fence).await.expect("second probe");
+        assert!(second.token > first.token, "tokens strictly increase");
+        assert!(
+            second.fence_wall >= first.fence_wall
+                || second.fence_wall
+                    > first.fence_wall - chrono::Duration::seconds(FENCE_CLOCK_MARGIN_SECS),
+            "walls advance with the clock (modulo an open transaction)"
+        );
+
+        // A "reader" session on the same database observes at least the
+        // second token and proves the newest retained entry.
+        let mut conn = pool.acquire().await.expect("reader conn");
+        let obs = observe_heartbeat(&mut conn, false)
+            .await
+            .expect("observe")
+            .expect("heartbeat row present");
+        assert!(obs.token >= second.token);
+        assert!(
+            obs.backend.contains(" pid="),
+            "backend identity must carry the backend pid, got {:?}",
+            obs.backend
+        );
+        // TCP fixtures also carry addr:port; unix-socket fixtures read 'local'.
+        assert!(
+            obs.backend.starts_with("local pid=") || obs.backend.contains(':'),
+            "backend identity must carry addr:port or 'local', got {:?}",
+            obs.backend
+        );
+        let proof = fence
+            .resolve(obs.token, obs.epoch)
+            .proved()
+            .expect("proof resolves");
+        assert_eq!(proof.token, second.token, "newest retained entry cited");
+
+        // An epoch nobody committed proves nothing.
+        assert_eq!(
+            fence.resolve(obs.token, Uuid::new_v4()),
+            ResolveOutcome::EpochMismatch
+        );
+
+        drop(conn);
+        drop_scratch_db(&admin, pool, &name).await;
+    }
+
+    /// A same-epoch token rewind on the writer (restore adversary) must not
+    /// leave proofs standing: the probe rotates the epoch, so a reader still
+    /// on the pre-rewind timeline — observing a *higher* token under the old
+    /// epoch — fails the epoch check instead of proving stale coverage.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn probe_rotates_epoch_on_same_epoch_token_regression() {
+        let (admin, pool, name) = scratch_db().await;
         let fence = ReplicaFence::new();
-        fence.advance(Utc::now()); // pretend a previous handshake succeeded
 
-        // Using the primary as its own "replica": replay LSN is NULL.
-        let err = probe_once(&pool, &pool, &fence)
+        let before = probe_once(&pool, &fence).await.expect("probe");
+        let mut conn = pool.acquire().await.expect("conn");
+        let old_epoch = observe_heartbeat(&mut conn, false)
+            .await
+            .expect("observe")
+            .expect("row")
+            .epoch;
+
+        // Rewind the token in place, keeping the epoch: the restore shape.
+        sqlx::query("UPDATE replica_heartbeat SET token = 0 WHERE id = 1")
+            .execute(&pool)
+            .await
+            .expect("rewind token");
+
+        let after = probe_once(&pool, &fence).await.expect("recovery probe");
+        // The pre-rewind observation must no longer prove anything.
+        assert_eq!(
+            fence.resolve(before.token, old_epoch),
+            ResolveOutcome::EpochMismatch,
+            "old-epoch observations must fail closed after rotation"
+        );
+        // A fresh observation on the new timeline proves the rotated entry.
+        let obs = observe_heartbeat(&mut conn, false)
             .await
-            .expect_err("NULL replay LSN must be an error");
-        assert!(matches!(err, ProbeError::ReplicaLsnUnavailable));
+            .expect("observe")
+            .expect("row");
+        assert_ne!(obs.epoch, old_epoch, "epoch rotated");
+        assert_eq!(
+            fence
+                .resolve(obs.token, obs.epoch)
+                .proved()
+                .expect("proof")
+                .token,
+            after.token
+        );
+
+        drop(conn);
+        drop_scratch_db(&admin, pool, &name).await;
     }
 }
diff --git a/crates/buzz-db/src/thread.rs b/crates/buzz-db/src/thread.rs
index 3f92212dd5..007677e258 100644
--- a/crates/buzz-db/src/thread.rs
+++ b/crates/buzz-db/src/thread.rs
@@ -349,6 +349,30 @@ pub async fn get_thread_replies(
     depth_limit: Option<u32>,
     limit: u32,
     cursor: Option<&[u8]>,
+) -> Result<Vec<ThreadReply>> {
+    let mut conn = pool.acquire().await?;
+    get_thread_replies_on(
+        &mut conn,
+        community_id,
+        root_event_id,
+        depth_limit,
+        limit,
+        cursor,
+    )
+    .await
+}
+
+/// [`get_thread_replies`] on a specific session — the replica-routing path
+/// runs the page on the exact reader connection whose heartbeat observation
+/// proved coverage (the proof is connection-local; a different pooled
+/// session may sit at a different replay position).
+pub(crate) async fn get_thread_replies_on(
+    conn: &mut sqlx::PgConnection,
+    community_id: CommunityId,
+    root_event_id: &[u8],
+    depth_limit: Option<u32>,
+    limit: u32,
+    cursor: Option<&[u8]>,
 ) -> Result<Vec<ThreadReply>> {
     // Decode cursor bytes -> keyset (timestamp, optional event_id) for the
     // WHERE condition. Layout: 8-byte BE i64 seconds, then the raw event_id.
@@ -445,7 +469,7 @@ pub async fn get_thread_replies(
     }
     q = q.bind(limit as i32);
 
-    let rows = q.fetch_all(pool).await?;
+    let rows = q.fetch_all(&mut *conn).await?;
 
     let mut replies = Vec::with_capacity(rows.len());
     for row in rows {
@@ -569,6 +593,31 @@ pub async fn get_channel_window(
     limit: u32,
     cursor: Option<(DateTime<Utc>, Vec<u8>)>,
     kind_filter: Option<&[u32]>,
+) -> Result<ChannelWindow> {
+    let mut conn = pool.acquire().await?;
+    get_channel_window_on(
+        &mut conn,
+        community_id,
+        channel_id,
+        limit,
+        cursor,
+        kind_filter,
+    )
+    .await
+}
+
+/// [`get_channel_window`] on a specific session — the replica-routing path
+/// runs the page (and its participants batch) on the exact reader connection
+/// whose heartbeat observation proved coverage (the proof is
+/// connection-local; a different pooled session may sit at a different
+/// replay position).
+pub(crate) async fn get_channel_window_on(
+    conn: &mut sqlx::PgConnection,
+    community_id: CommunityId,
+    channel_id: Uuid,
+    limit: u32,
+    cursor: Option<(DateTime<Utc>, Vec<u8>)>,
+    kind_filter: Option<&[u32]>,
 ) -> Result<ChannelWindow> {
     let mut param_idx = 3u32; // $1 is community_id, $2 is channel_id
     let mut sql = String::from(
@@ -637,7 +686,7 @@ pub async fn get_channel_window(
     // The +1 probe row is the server-internal has_more evidence.
     q = q.bind(limit as i64 + 1);
 
-    let mut db_rows = q.fetch_all(pool).await?;
+    let mut db_rows = q.fetch_all(&mut *conn).await?;
 
     let has_more = db_rows.len() > limit as usize;
     db_rows.truncate(limit as usize);
@@ -722,7 +771,7 @@ pub async fn get_channel_window(
         )
         .bind(community_id.as_uuid())
         .bind(&roots)
-        .fetch_all(pool)
+        .fetch_all(&mut *conn)
         .await?;
 
         let mut by_root: std::collections::HashMap<Vec<u8>, Vec<Vec<u8>>> =
diff --git a/crates/buzz-media/src/config.rs b/crates/buzz-media/src/config.rs
index 047c08475e..3c70e4afe1 100644
--- a/crates/buzz-media/src/config.rs
+++ b/crates/buzz-media/src/config.rs
@@ -1,5 +1,38 @@
 //! Media storage configuration.
 
+use std::str::FromStr;
+
+/// S3 URL addressing style shared by media and Git/CAS storage.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, serde::Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum S3AddressingStyle {
+    /// Put the bucket in the request path (`https://endpoint/bucket/key`).
+    ///
+    /// This preserves compatibility with the bundled MinIO deployments, whose
+    /// internal DNS only resolves the endpoint hostname.
+    #[default]
+    Path,
+    /// Put the bucket in the hostname (`https://bucket.endpoint/key`).
+    ///
+    /// This is the standard S3 form and is required by providers such as new
+    /// Railway Storage Buckets.
+    Virtual,
+}
+
+impl FromStr for S3AddressingStyle {
+    type Err = String;
+
+    fn from_str(value: &str) -> Result<Self, Self::Err> {
+        match value {
+            "path" => Ok(Self::Path),
+            "virtual" => Ok(Self::Virtual),
+            _ => Err(format!(
+                "BUZZ_S3_ADDRESSING_STYLE must be 'path' or 'virtual', got {value:?}"
+            )),
+        }
+    }
+}
+
 fn default_max_video_bytes() -> u64 {
     524_288_000 // 500 MB
 }
@@ -31,6 +64,9 @@ pub struct MediaConfig {
     /// the value is not meaningfully checked.
     #[serde(default = "default_s3_region")]
     pub s3_region: String,
+    /// S3 URL addressing style. Defaults to path style for MinIO compatibility.
+    #[serde(default)]
+    pub s3_addressing_style: S3AddressingStyle,
     /// Maximum upload size for images (bytes). Default: 50 MB.
     pub max_image_bytes: u64,
     /// Maximum upload size for animated GIFs (bytes). Default: 10 MB.
@@ -123,7 +159,8 @@ impl MediaConfig {
 
 #[cfg(test)]
 mod tests {
-    use super::MediaConfig;
+    use super::{MediaConfig, S3AddressingStyle};
+    use std::str::FromStr;
 
     fn valid_config() -> MediaConfig {
         MediaConfig {
@@ -132,6 +169,7 @@ mod tests {
             s3_secret_key: "s".to_string(),
             s3_bucket: "buzz-media".to_string(),
             s3_region: "us-east-1".to_string(),
+            s3_addressing_style: S3AddressingStyle::Path,
             max_image_bytes: 1,
             max_gif_bytes: 1,
             max_video_bytes: 1,
@@ -143,6 +181,35 @@ mod tests {
         }
     }
 
+    #[test]
+    fn addressing_style_parses_supported_values() {
+        assert_eq!(
+            S3AddressingStyle::from_str("path"),
+            Ok(S3AddressingStyle::Path)
+        );
+        assert_eq!(
+            S3AddressingStyle::from_str("virtual"),
+            Ok(S3AddressingStyle::Virtual)
+        );
+    }
+
+    #[test]
+    fn addressing_style_defaults_to_path() {
+        assert_eq!(S3AddressingStyle::default(), S3AddressingStyle::Path);
+    }
+
+    #[test]
+    fn addressing_style_rejects_unknown_or_ambiguous_values() {
+        for invalid in ["", "auto", "PATH", "virtual-hosted"] {
+            let error =
+                S3AddressingStyle::from_str(invalid).expect_err("must reject invalid style");
+            assert!(
+                error.contains("BUZZ_S3_ADDRESSING_STYLE must be 'path' or 'virtual'"),
+                "unexpected error for {invalid:?}: {error}"
+            );
+        }
+    }
+
     #[test]
     fn upload_record_knobs_default_off_and_validate() {
         assert!(valid_config().validate().is_ok());
diff --git a/crates/buzz-media/src/lib.rs b/crates/buzz-media/src/lib.rs
index ac05ea6d51..67896d4ef2 100644
--- a/crates/buzz-media/src/lib.rs
+++ b/crates/buzz-media/src/lib.rs
@@ -17,7 +17,7 @@ pub use bucket_index::{
     classify_key, fold_bucket_listing, BucketAggregate, BucketSnapshot, CommunityStorage, KeyClass,
     Page, SweepError,
 };
-pub use config::MediaConfig;
+pub use config::{MediaConfig, S3AddressingStyle};
 pub use error::MediaError;
 pub use storage::{BlobHeadMeta, BlobMeta, ByteStream, MediaStorage};
 pub use types::BlobDescriptor;
diff --git a/crates/buzz-media/src/storage.rs b/crates/buzz-media/src/storage.rs
index 0e9809af2f..cbf980201f 100644
--- a/crates/buzz-media/src/storage.rs
+++ b/crates/buzz-media/src/storage.rs
@@ -5,7 +5,7 @@ use std::pin::Pin;
 
 use buzz_core::tenant::{CommunityId, TenantContext};
 
-use crate::config::MediaConfig;
+use crate::config::{MediaConfig, S3AddressingStyle};
 use crate::error::MediaError;
 use bytes::Bytes;
 use s3::creds::Credentials;
@@ -61,8 +61,11 @@ impl MediaStorage {
         }
         .map_err(|e| MediaError::StorageError(e.to_string()))?;
         let bucket = Bucket::new(&config.s3_bucket, region, creds)
-            .map_err(|e| MediaError::StorageError(e.to_string()))?
-            .with_path_style();
+            .map_err(|e| MediaError::StorageError(e.to_string()))?;
+        let bucket = match config.s3_addressing_style {
+            S3AddressingStyle::Path => bucket.with_path_style(),
+            S3AddressingStyle::Virtual => bucket,
+        };
         Ok(Self { bucket })
     }
 
@@ -285,6 +288,7 @@ mod tests {
             s3_secret_key: secret.to_string(),
             s3_bucket: "buzz-media".to_string(),
             s3_region: "us-west-2".to_string(),
+            s3_addressing_style: S3AddressingStyle::Path,
             max_image_bytes: 50 * 1024 * 1024,
             max_gif_bytes: 10 * 1024 * 1024,
             max_video_bytes: 524_288_000,
@@ -309,6 +313,23 @@ mod tests {
         }
     }
 
+    #[test]
+    fn client_constructor_applies_both_addressing_styles() {
+        let path = MediaStorage::new(&storage_config("buzz_dev", "buzz_dev_secret"))
+            .expect("path-style client");
+        assert!(path.bucket.is_path_style());
+        assert_eq!(path.bucket.url(), "http://localhost:9000/buzz-media");
+
+        let mut virtual_config = storage_config("buzz_dev", "buzz_dev_secret");
+        virtual_config.s3_addressing_style = S3AddressingStyle::Virtual;
+        let virtual_hosted = MediaStorage::new(&virtual_config).expect("virtual-hosted client");
+        assert!(virtual_hosted.bucket.is_subdomain_style());
+        assert_eq!(
+            virtual_hosted.bucket.url(),
+            "http://buzz-media.localhost:9000"
+        );
+    }
+
     #[test]
     fn partial_static_keys_are_rejected() {
         let err = match MediaStorage::new(&storage_config("buzz_dev", "")) {
diff --git a/crates/buzz-media/src/upload.rs b/crates/buzz-media/src/upload.rs
index 478ac114ef..524b033280 100644
--- a/crates/buzz-media/src/upload.rs
+++ b/crates/buzz-media/src/upload.rs
@@ -570,6 +570,7 @@ mod tests {
             s3_secret_key: String::new(),
             s3_bucket: String::new(),
             s3_region: "us-east-1".to_string(),
+            s3_addressing_style: crate::config::S3AddressingStyle::Path,
             max_image_bytes: 50 * 1024 * 1024,
             max_gif_bytes: 10 * 1024 * 1024,
             max_video_bytes: 524_288_000,
diff --git a/crates/buzz-media/src/validation.rs b/crates/buzz-media/src/validation.rs
index ee940dfb24..f1387fc9d6 100644
--- a/crates/buzz-media/src/validation.rs
+++ b/crates/buzz-media/src/validation.rs
@@ -949,6 +949,7 @@ mod tests {
             s3_secret_key: String::new(),
             s3_bucket: String::new(),
             s3_region: "us-east-1".to_string(),
+            s3_addressing_style: crate::config::S3AddressingStyle::Path,
             max_image_bytes: 50 * 1024 * 1024,
             max_gif_bytes: 10 * 1024 * 1024,
             max_video_bytes: 524_288_000,
diff --git a/crates/buzz-media/tests/static_creds_minio.rs b/crates/buzz-media/tests/static_creds_minio.rs
index d7591238c2..4c8c10702c 100644
--- a/crates/buzz-media/tests/static_creds_minio.rs
+++ b/crates/buzz-media/tests/static_creds_minio.rs
@@ -1,5 +1,5 @@
-//! Live round-trip test for the **static-credentials** S3 path against a local
-//! MinIO, guarded by `#[ignore]`.
+//! Live round-trip test for the **static-credentials** S3 path against an
+//! S3-compatible service. It is guarded by `#[ignore]`.
 //!
 //! This is the path local/dev and any static-key deployment uses
 //! (`s3_access_key`/`s3_secret_key` both non-empty -> `Credentials::new`). It
@@ -15,7 +15,8 @@
 //! ```
 //!
 //! Overridable via `BUZZ_S3_ENDPOINT` / `BUZZ_S3_ACCESS_KEY` /
-//! `BUZZ_S3_SECRET_KEY` / `BUZZ_S3_BUCKET`.
+//! `BUZZ_S3_SECRET_KEY` / `BUZZ_S3_BUCKET` / `BUZZ_S3_REGION` /
+//! `BUZZ_S3_ADDRESSING_STYLE`. The default remains `path` for MinIO.
 
 use buzz_media::config::MediaConfig;
 use buzz_media::storage::MediaStorage;
@@ -29,7 +30,11 @@ fn minio_config() -> MediaConfig {
         s3_secret_key: std::env::var("BUZZ_S3_SECRET_KEY")
             .unwrap_or_else(|_| "buzz_dev_secret".to_string()),
         s3_bucket: std::env::var("BUZZ_S3_BUCKET").unwrap_or_else(|_| "buzz-media".to_string()),
-        s3_region: "us-east-1".to_string(),
+        s3_region: std::env::var("BUZZ_S3_REGION").unwrap_or_else(|_| "us-east-1".to_string()),
+        s3_addressing_style: std::env::var("BUZZ_S3_ADDRESSING_STYLE")
+            .unwrap_or_else(|_| "path".to_string())
+            .parse()
+            .expect("BUZZ_S3_ADDRESSING_STYLE must be path or virtual"),
         max_image_bytes: 50 * 1024 * 1024,
         max_gif_bytes: 10 * 1024 * 1024,
         max_video_bytes: 524_288_000,
diff --git a/crates/buzz-pubsub/src/lib.rs b/crates/buzz-pubsub/src/lib.rs
index eae8c5ef9e..4f1690beef 100644
--- a/crates/buzz-pubsub/src/lib.rs
+++ b/crates/buzz-pubsub/src/lib.rs
@@ -328,7 +328,7 @@ impl PubSubManager {
         publisher::publish_event(&self.pool, ctx, topic, event).await
     }
 
-    /// Set presence with 60s TTL. Call on connect and every 30s heartbeat.
+    /// Set presence with 180s TTL. Call on connect and every 60s heartbeat.
     pub async fn set_presence(
         &self,
         ctx: &TenantContext,
diff --git a/crates/buzz-pubsub/src/presence.rs b/crates/buzz-pubsub/src/presence.rs
index 178ba7550a..e0c9dfd6c9 100644
--- a/crates/buzz-pubsub/src/presence.rs
+++ b/crates/buzz-pubsub/src/presence.rs
@@ -1,7 +1,7 @@
 //! Presence tracking — online/away status with TTL.
 //!
-//! Stored as `SET buzz:{community}:presence:{pubkey_hex} "online" EX 90`.
-//! TTL is 3x the 30s heartbeat interval so a single missed heartbeat doesn't
+//! Stored as `SET buzz:{community}:presence:{pubkey_hex} "online" EX 180`.
+//! TTL is 3x the 60s heartbeat interval so a single missed heartbeat doesn't
 //! cause presence flap. Clean disconnect deletes immediately.
 
 use buzz_core::TenantContext;
@@ -12,8 +12,8 @@ use std::collections::HashMap;
 use crate::error::PubSubError;
 use crate::topic::BUZZ_PREFIX;
 
-/// 3x the 30s heartbeat — single missed heartbeat won't cause presence flap.
-pub const PRESENCE_TTL_SECS: u64 = 90;
+/// 3x the 60s heartbeat — single missed heartbeat won't cause presence flap.
+pub const PRESENCE_TTL_SECS: u64 = 180;
 
 /// Returns the Redis key for the presence entry of `pubkey` under `ctx`.
 pub fn presence_key(ctx: &TenantContext, pubkey: &PublicKey) -> String {
@@ -109,6 +109,12 @@ mod tests {
         TenantContext::resolved(CommunityId::from_uuid(Uuid::from_u128(id)), host)
     }
 
+    #[test]
+    fn presence_ttl_is_three_one_minute_heartbeat_windows() {
+        assert_eq!(PRESENCE_TTL_SECS, 180);
+        assert_eq!(PRESENCE_TTL_SECS, 3 * 60);
+    }
+
     #[test]
     fn test_presence_key_format() {
         let pubkey = make_pubkey();
diff --git a/crates/buzz-relay/Cargo.toml b/crates/buzz-relay/Cargo.toml
index 01f78a2d49..41bdc3b9e9 100644
--- a/crates/buzz-relay/Cargo.toml
+++ b/crates/buzz-relay/Cargo.toml
@@ -84,8 +84,8 @@ async-compression = { version = "0.4.42", features = ["tokio", "gzip"] }
 dev = ["buzz-auth/dev"]
 
 [dev-dependencies]
-mesh-llm-sdk = { git = "https://github.com/Mesh-LLM/mesh-llm.git", tag = "v0.73.1", package = "mesh-llm-sdk", default-features = false, features = ["client", "serving"] }
-mesh-llm-host-runtime = { git = "https://github.com/Mesh-LLM/mesh-llm.git", tag = "v0.73.1", package = "mesh-llm-host-runtime", default-features = false, features = ["dynamic-native-runtime"] }
+mesh-llm-sdk = { git = "https://github.com/Mesh-LLM/mesh-llm.git", tag = "v0.74.0", package = "mesh-llm-sdk", default-features = false, features = ["client", "serving"] }
+mesh-llm-host-runtime = { git = "https://github.com/Mesh-LLM/mesh-llm.git", tag = "v0.74.0", package = "mesh-llm-host-runtime", default-features = false, features = ["dynamic-native-runtime"] }
 buzz-core = { workspace = true, features = ["test-utils"] }
 buzz-auth = { workspace = true, features = ["dev"] }
 reqwest = { workspace = true }
diff --git a/crates/buzz-relay/examples/mesh_agent_e2e.rs b/crates/buzz-relay/examples/mesh_agent_e2e.rs
index b6f723f35a..345ca4c746 100644
--- a/crates/buzz-relay/examples/mesh_agent_e2e.rs
+++ b/crates/buzz-relay/examples/mesh_agent_e2e.rs
@@ -278,7 +278,9 @@ async fn agent_chat_in_isolated_home(
         .env("OPENAI_COMPAT_API_KEY", "buzz-mesh-local")
         .env("OPENAI_COMPAT_API", "chat")
         .env("BUZZ_AGENT_MAX_OUTPUT_TOKENS", "4096")
-        .env("BUZZ_AGENT_THINKING_EFFORT", "none")
+        // No BUZZ_AGENT_THINKING_EFFORT: apply_relay_mesh_env() deliberately
+        // leaves it unset so each model's chat template picks its own default.
+        // Pinning a value here would test a config the product does not ship.
         .stdin(Stdio::piped())
         .stdout(Stdio::piped())
         .stderr(Stdio::null());
diff --git a/crates/buzz-relay/src/api/bridge.rs b/crates/buzz-relay/src/api/bridge.rs
index 2e00d6bd2f..a118ff453f 100644
--- a/crates/buzz-relay/src/api/bridge.rs
+++ b/crates/buzz-relay/src/api/bridge.rs
@@ -462,9 +462,9 @@ async fn handle_channel_window_filter(
         .as_ref()
         .map(|ks| ks.iter().map(|k| k.as_u16() as u32).collect());
 
-    let window = state
+    let (window, mut session) = state
         .db
-        .get_channel_window(
+        .get_channel_window_with_session(
             tenant.community(),
             ch_id,
             limit,
@@ -485,7 +485,12 @@ async fn handle_channel_window_filter(
 
     // 2. Aux closure: reactions/deletions/edits targeting retained rows, plus
     //    deletions targeting those aux events (the transitive second hop).
-    //    One round trip for the client instead of an #e fan-out.
+    //    One round trip for the client instead of an #e fan-out. Runs in the
+    //    SAME request transaction that served the window: when the page came
+    //    from a proved replica session, the heartbeat observation anchored a
+    //    REPEATABLE READ snapshot, so the aux hops see exactly the state the
+    //    proof covered — another pooled session (or even another autocommit
+    //    statement) could sit at a different replay position.
     if extension_flag(raw, "include_aux") && !row_ids_hex.is_empty() {
         let mut seen_aux: std::collections::HashSet<nostr::EventId> =
             std::collections::HashSet::new();
@@ -495,8 +500,7 @@ async fn handle_channel_window_filter(
             aux_query.kinds = Some(hop_kinds.iter().map(|k| *k as i32).collect());
             aux_query.e_tags = Some(std::mem::take(&mut hop_ids));
             aux_query.limit = Some(1000);
-            let aux_events = state
-                .db
+            let aux_events = session
                 .query_events(&aux_query)
                 .await
                 .map_err(|e| internal_error(&format!("window aux error: {e}")))?;
@@ -1083,7 +1087,8 @@ async fn query_events_authed(
             let type_events = match canonical {
                 "mentions" => state
                     .db
-                    .query_feed_mentions(
+                    .query_feed_mentions_routed(
+                        "bridge_feed",
                         tenant.community(),
                         &pubkey_bytes,
                         &accessible_channels,
@@ -1094,7 +1099,8 @@ async fn query_events_authed(
                     .map_err(|e| internal_error(&format!("feed mentions error: {e}")))?,
                 "needs_action" => state
                     .db
-                    .query_feed_needs_action(
+                    .query_feed_needs_action_routed(
+                        "bridge_feed",
                         tenant.community(),
                         &pubkey_bytes,
                         &accessible_channels,
@@ -1105,7 +1111,13 @@ async fn query_events_authed(
                     .map_err(|e| internal_error(&format!("feed needs_action error: {e}")))?,
                 "activity" => state
                     .db
-                    .query_feed_activity(tenant.community(), &accessible_channels, since, remaining)
+                    .query_feed_activity_routed(
+                        "bridge_feed",
+                        tenant.community(),
+                        &accessible_channels,
+                        since,
+                        remaining,
+                    )
                     .await
                     .map_err(|e| internal_error(&format!("feed activity error: {e}")))?,
                 _ => continue,
@@ -1224,10 +1236,10 @@ async fn query_events_authed(
             extract_channel_from_filter(filter),
             &accessible_channels,
         );
-        // Persona visibility pushdown: must mirror WS REQ so that a page of newer
-        // private personas does not starve older shared ones off the candidate page.
-        if crate::handlers::req::filter_can_match_persona_shared_kinds(filter) {
-            query.persona_reader = Some(pubkey_bytes.clone());
+        // Shared-gated visibility pushdown: must mirror WS REQ so that a page of
+        // newer private events does not starve older shared ones off the page.
+        if crate::handlers::req::filter_can_match_shared_gated_kinds(filter) {
+            query.shared_gated_reader = Some(pubkey_bytes.clone());
         }
 
         match extract_before_id(raw) {
@@ -1271,7 +1283,7 @@ async fn query_events_authed(
     let db = state.db.clone();
     let mut catchall_results = stream::iter(catchall_queries.into_iter().map(|(idx, query)| {
         let db = db.clone();
-        async move { (idx, db.query_events(&query).await) }
+        async move { (idx, db.query_events_routed("bridge_query", &query).await) }
     }))
     .buffered(crate::handlers::req::FILTER_QUERY_CONCURRENCY);
 
@@ -1441,11 +1453,11 @@ async fn count_events_authed(
                     filter,
                     &authed_pubkey_hex,
                 );
-        // Force per-event fallback for filters that can match kind:30175 —
-        // the fast SQL count_events() path has no per-event gate and would
-        // over-count foreign unshared persona events (existence leak).
-        let needs_persona_filtering =
-            crate::handlers::req::filter_can_match_persona_shared_kinds(filter);
+        // Force per-event fallback for filters that can match a shared-gated
+        // kind — the fast SQL count_events() path has no per-event gate and
+        // would over-count foreign unshared events (existence leak).
+        let needs_shared_gate_filtering =
+            crate::handlers::req::filter_can_match_shared_gated_kinds(filter);
 
         // If filter targets a specific channel, verify access.
         if let Some(ch_id) = extract_channel_from_filter(filter) {
@@ -1460,10 +1472,10 @@ async fn count_events_authed(
                 tenant.community(),
             )
             .await;
-            // Persona visibility pushdown: same as REQ and /query paths, so the
-            // fallback's query_events call doesn't over-fetch private persona rows.
-            if needs_persona_filtering {
-                query.persona_reader = Some(pubkey_bytes.clone());
+            // Shared-gated visibility pushdown: same as REQ and /query paths, so
+            // the fallback's query_events call doesn't over-fetch private rows.
+            if needs_shared_gate_filtering {
+                query.shared_gated_reader = Some(pubkey_bytes.clone());
             }
             let author_is_self = filter.authors.as_ref().is_some_and(|authors| {
                 !authors.is_empty()
@@ -1474,9 +1486,9 @@ async fn count_events_authed(
             if crate::handlers::req::filter_fully_pushable(filter)
                 && (!needs_author_only_filtering || author_is_self)
                 && !needs_result_gated_filtering
-                && !needs_persona_filtering
+                && !needs_shared_gate_filtering
             {
-                match state.db.count_events(&query).await {
+                match state.db.count_events_routed("bridge_count", &query).await {
                     Ok(n) => total += n as u64,
                     Err(e) => {
                         return Err(internal_error(&format!("count error: {e}")));
@@ -1486,7 +1498,11 @@ async fn count_events_authed(
                 // Fallback: query + post-filter for non-pushable constraints.
                 let mut q = query;
                 crate::handlers::req::apply_count_fallback_limit(&mut q);
-                match state.db.query_events(&q).await {
+                match state
+                    .db
+                    .query_events_routed_bounded("bridge_count_fallback", &q)
+                    .await
+                {
                     Ok(stored_events) => {
                         if crate::handlers::req::count_fallback_exceeded(stored_events.len()) {
                             metrics::counter!("buzz_count_fallback_rejections_total").increment(1);
@@ -1525,10 +1541,10 @@ async fn count_events_authed(
             )
             .await;
             query.channel_ids = Some(accessible_channels.to_vec());
-            // Persona visibility pushdown: pre-filter before ORDER/LIMIT on the
-            // fallback query_events path.
-            if needs_persona_filtering {
-                query.persona_reader = Some(pubkey_bytes.clone());
+            // Shared-gated visibility pushdown: pre-filter before ORDER/LIMIT on
+            // the fallback query_events path.
+            if needs_shared_gate_filtering {
+                query.shared_gated_reader = Some(pubkey_bytes.clone());
             }
 
             let author_is_self = filter.authors.as_ref().is_some_and(|authors| {
@@ -1540,10 +1556,10 @@ async fn count_events_authed(
             if crate::handlers::req::filter_fully_pushable(filter)
                 && (!needs_author_only_filtering || author_is_self)
                 && !needs_result_gated_filtering
-                && !needs_persona_filtering
+                && !needs_shared_gate_filtering
             {
                 query.limit = None;
-                match state.db.count_events(&query).await {
+                match state.db.count_events_routed("bridge_count", &query).await {
                     Ok(n) => total += n as u64,
                     Err(e) => {
                         return Err(internal_error(&format!("count error: {e}")));
@@ -1552,7 +1568,11 @@ async fn count_events_authed(
             } else {
                 // Fallback: query a bounded candidate set + post-filter.
                 crate::handlers::req::apply_count_fallback_limit(&mut query);
-                match state.db.query_events(&query).await {
+                match state
+                    .db
+                    .query_events_routed_bounded("bridge_count_fallback", &query)
+                    .await
+                {
                     Ok(stored_events) => {
                         if crate::handlers::req::count_fallback_exceeded(stored_events.len()) {
                             metrics::counter!("buzz_count_fallback_rejections_total").increment(1);
@@ -1725,7 +1745,7 @@ async fn handle_bridge_search(
         let id_refs: Vec<&[u8]> = hit_ids.iter().map(|b| b.as_slice()).collect();
         let stored_events = state
             .db
-            .get_events_by_ids(tenant.community(), &id_refs)
+            .get_events_by_ids_routed("bridge_search_hydrate", tenant.community(), &id_refs)
             .await
             .map_err(|e| internal_error(&format!("search fetch error: {e}")))?;
 
@@ -3022,6 +3042,27 @@ mod tests {
         assert_eq!(extract_page_offset(&raw, None), None);
     }
 
+    /// Offsets are sized from the *clamped* limit the DB will honor, not from
+    /// what the client asked for. `filter_to_query_params` clamps an absent or
+    /// over-ceiling `limit` to `DEFAULT_MAX_PAGE_LIMIT` (guarded in
+    /// `handlers::req::tests::req_filter_limit_clamps_to_advertised_nip11_max_limit`)
+    /// and that clamped value is what arrives here — so page N starts exactly
+    /// N-1 full pages in. Sizing from an unclamped limit would step past rows
+    /// the previous page never returned.
+    #[test]
+    fn extract_page_offset_sizes_pages_from_clamped_limit() {
+        let clamped = buzz_db::DEFAULT_MAX_PAGE_LIMIT;
+
+        assert_eq!(
+            extract_page_offset(&serde_json::json!({ "page": 2 }), Some(clamped)),
+            Some(clamped)
+        );
+        assert_eq!(
+            extract_page_offset(&serde_json::json!({ "page": 3 }), Some(clamped)),
+            Some(clamped * 2)
+        );
+    }
+
     #[test]
     fn extract_depth_limit_valid() {
         let raw = serde_json::json!({ "depth_limit": 3 });
diff --git a/crates/buzz-relay/src/api/git/binding.rs b/crates/buzz-relay/src/api/git/binding.rs
new file mode 100644
index 0000000000..7ee0eccb23
--- /dev/null
+++ b/crates/buzz-relay/src/api/git/binding.rs
@@ -0,0 +1,128 @@
+//! Repo → channel binding resolution, shared by the read gate and push policy.
+//!
+//! The `buzz-channel` tag on a kind:30617 announcement IS the git ACL: the
+//! read gate (SEC-005, `transport::authorize_git_read`) and the push policy
+//! endpoint (`policy::hook_callback`) both authorize against membership in
+//! the bound channel. Before this module they each parsed the tag with their
+//! own code that agreed only by coincidence; the resolver makes the
+//! agreement structural.
+//!
+//! # First-tag, fail-closed semantics
+//!
+//! Only the *first* `buzz-channel` tag is considered, and it must carry a
+//! valid UUID. A malformed first binding resolves to [`RepoBinding::Broken`]
+//! even if a later duplicate tag is valid — an ambiguous announcement must
+//! fail closed, not silently resolve to whichever duplicate happens to
+//! parse. If this ever became "find the first *parseable* tag", an author
+//! who can append a second `buzz-channel` tag would pick the channel.
+//!
+//! # What this deliberately does NOT do
+//!
+//! No DB access. A well-formed UUID that names a nonexistent or deleted
+//! channel still resolves to [`RepoBinding::Bound`]; each gate's own
+//! membership lookup then denies (`get_member_role` joins
+//! `channels … deleted_at IS NULL`, so a dead channel is indistinguishable
+//! from a non-member — the info-leak-safe posture). Likewise each gate keeps
+//! its own archived-channel policy: push denies on archived channels, read
+//! does not, and this resolver must not unify that asymmetry as a side
+//! effect.
+
+use uuid::Uuid;
+
+/// How a kind:30617 announcement binds (or fails to bind) a channel.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RepoBinding {
+    /// No `buzz-channel` tag at all. The announcement author (the only
+    /// identity that can rebind — 30617 is keyed by `(author, d)`) may be
+    /// offered remediation; everyone else gets the generic denial.
+    NotBound,
+    /// First `buzz-channel` tag carries a valid UUID.
+    Bound(Uuid),
+    /// First `buzz-channel` tag exists but its value is not a UUID.
+    /// Fail closed with the generic denial — never remediation, which
+    /// would leak that the repo exists.
+    Broken,
+}
+
+/// Resolve the channel binding of a kind:30617 announcement from its tags.
+pub fn resolve_repo_binding(event: &nostr::Event) -> RepoBinding {
+    let Some(first) = event
+        .tags
+        .iter()
+        .find(|t| t.as_slice().first().map(String::as_str) == Some("buzz-channel"))
+    else {
+        return RepoBinding::NotBound;
+    };
+    match first.as_slice().get(1).map(|v| Uuid::parse_str(v)) {
+        Some(Ok(id)) => RepoBinding::Bound(id),
+        _ => RepoBinding::Broken,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use nostr::{EventBuilder, Keys, Kind, Tag};
+
+    use super::{resolve_repo_binding, RepoBinding};
+
+    fn announcement(tags: Vec<Tag>) -> nostr::Event {
+        EventBuilder::new(Kind::Custom(30617), "")
+            .tags(tags)
+            .sign_with_keys(&Keys::generate())
+            .expect("sign 30617")
+    }
+
+    #[test]
+    fn extracts_valid_uuid() {
+        let ch = uuid::Uuid::new_v4();
+        let event = announcement(vec![
+            Tag::parse(["d", "repo"]).unwrap(),
+            Tag::parse(["buzz-channel", &ch.to_string()]).unwrap(),
+        ]);
+        assert_eq!(resolve_repo_binding(&event), RepoBinding::Bound(ch));
+    }
+
+    #[test]
+    fn absent_tag_is_not_bound() {
+        let event = announcement(vec![Tag::parse(["d", "repo"]).unwrap()]);
+        assert_eq!(resolve_repo_binding(&event), RepoBinding::NotBound);
+    }
+
+    #[test]
+    fn malformed_and_empty_values_are_broken_not_absent() {
+        let malformed = announcement(vec![
+            Tag::parse(["d", "repo"]).unwrap(),
+            Tag::parse(["buzz-channel", "not-a-uuid"]).unwrap(),
+        ]);
+        assert_eq!(resolve_repo_binding(&malformed), RepoBinding::Broken);
+
+        let empty = announcement(vec![
+            Tag::parse(["d", "repo"]).unwrap(),
+            Tag::parse(["buzz-channel"]).unwrap(),
+        ]);
+        assert_eq!(resolve_repo_binding(&empty), RepoBinding::Broken);
+    }
+
+    #[test]
+    fn fails_closed_on_ambiguous_duplicate_bindings() {
+        let ch = uuid::Uuid::new_v4();
+        let other = uuid::Uuid::new_v4();
+
+        // Malformed first + valid second: the ambiguity denies; the valid
+        // duplicate must NOT win, or the duplicate picks the channel.
+        let malformed_first = announcement(vec![
+            Tag::parse(["d", "repo"]).unwrap(),
+            Tag::parse(["buzz-channel", "not-a-uuid"]).unwrap(),
+            Tag::parse(["buzz-channel", &ch.to_string()]).unwrap(),
+        ]);
+        assert_eq!(resolve_repo_binding(&malformed_first), RepoBinding::Broken);
+
+        // Valid first + different second: first wins deterministically.
+        let valid_first = announcement(vec![
+            Tag::parse(["d", "repo"]).unwrap(),
+            Tag::parse(["buzz-channel", &ch.to_string()]).unwrap(),
+            Tag::parse(["buzz-channel", &other.to_string()]).unwrap(),
+        ]);
+        assert_eq!(resolve_repo_binding(&valid_first), RepoBinding::Bound(ch));
+    }
+}
diff --git a/crates/buzz-relay/src/api/git/cas_publish.rs b/crates/buzz-relay/src/api/git/cas_publish.rs
index 635dcf2a67..50bb36d818 100644
--- a/crates/buzz-relay/src/api/git/cas_publish.rs
+++ b/crates/buzz-relay/src/api/git/cas_publish.rs
@@ -1370,6 +1370,15 @@ mod tests {
         );
     }
 
+    #[test]
+    fn published_head_moves_to_surviving_branch_after_current_branch_deletion() {
+        let refs = BTreeMap::from([("refs/heads/master".to_string(), "1".repeat(40))]);
+        assert_eq!(
+            resolve_published_head(&refs, "refs/heads/main".to_string(), "refs/heads/main"),
+            "refs/heads/master"
+        );
+    }
+
     #[test]
     fn digest_from_key_strips_prefix() {
         let k = format!("manifests/{}", "a".repeat(64));
@@ -1583,22 +1592,15 @@ mod tests {
     }
 
     fn live_store() -> GitStore {
-        let endpoint = std::env::var("BUZZ_GIT_S3_ENDPOINT")
-            .or_else(|_| std::env::var("BUZZ_S3_ENDPOINT"))
-            .unwrap_or_else(|_| "http://localhost:9000".into());
-        let access_key = std::env::var("BUZZ_GIT_S3_ACCESS_KEY")
-            .or_else(|_| std::env::var("BUZZ_S3_ACCESS_KEY"))
-            .unwrap_or_else(|_| "buzz_dev".into());
-        let secret_key = std::env::var("BUZZ_GIT_S3_SECRET_KEY")
-            .or_else(|_| std::env::var("BUZZ_S3_SECRET_KEY"))
-            .unwrap_or_else(|_| "buzz_dev_secret".into());
-        let bucket = std::env::var("BUZZ_GIT_S3_BUCKET")
-            .or_else(|_| std::env::var("BUZZ_S3_BUCKET"))
-            .unwrap_or_else(|_| "buzz-media".into());
-        let region = std::env::var("BUZZ_GIT_S3_REGION")
-            .or_else(|_| std::env::var("BUZZ_S3_REGION"))
-            .unwrap_or_else(|_| "us-east-1".into());
-        GitStore::new(&endpoint, &access_key, &secret_key, &bucket, &region).expect("connect minio")
+        GitStore::new(
+            "http://localhost:9000",
+            "buzz_dev",
+            "buzz_dev_secret",
+            "buzz-media",
+            "us-east-1",
+            buzz_media::config::S3AddressingStyle::Path,
+        )
+        .expect("connect local MinIO")
     }
 
     fn tenant() -> TenantContext {
diff --git a/crates/buzz-relay/src/api/git/hydrate.rs b/crates/buzz-relay/src/api/git/hydrate.rs
index 064d01923e..3ce809d18f 100644
--- a/crates/buzz-relay/src/api/git/hydrate.rs
+++ b/crates/buzz-relay/src/api/git/hydrate.rs
@@ -543,8 +543,15 @@ mod tests {
     #[tokio::test]
     async fn materialized_repo_is_created_under_configured_scratch_dir() {
         let scratch = TempDir::new().unwrap();
-        let store = GitStore::new("http://localhost:9000", "x", "x", "x", "us-east-1")
-            .expect("construct store");
+        let store = GitStore::new(
+            "http://localhost:9000",
+            "x",
+            "x",
+            "x",
+            "us-east-1",
+            buzz_media::config::S3AddressingStyle::Path,
+        )
+        .expect("construct store");
         let manifest = Manifest {
             version: 1,
             head: "refs/heads/main".into(),
@@ -587,8 +594,9 @@ mod tests {
             "buzz_dev_secret",
             "buzz-git",
             "us-east-1",
+            buzz_media::config::S3AddressingStyle::Path,
         )
-        .expect("connect minio")
+        .expect("connect local MinIO")
     }
 
     /// Build a tiny on-disk repo, return (pack bytes, head_oid).
diff --git a/crates/buzz-relay/src/api/git/mod.rs b/crates/buzz-relay/src/api/git/mod.rs
index ab0510fbeb..dd69d7dc36 100644
--- a/crates/buzz-relay/src/api/git/mod.rs
+++ b/crates/buzz-relay/src/api/git/mod.rs
@@ -22,6 +22,7 @@ use tower_http::limit::RequestBodyLimitLayer;
 
 use crate::state::AppState;
 
+pub mod binding;
 pub mod cas_publish;
 pub mod hook;
 pub mod hydrate;
diff --git a/crates/buzz-relay/src/api/git/policy.rs b/crates/buzz-relay/src/api/git/policy.rs
index fd6c4fb688..32d63f4600 100644
--- a/crates/buzz-relay/src/api/git/policy.rs
+++ b/crates/buzz-relay/src/api/git/policy.rs
@@ -42,7 +42,10 @@ use tracing::{error, warn};
 use uuid::Uuid;
 
 use buzz_core::channel::MemberRole;
-use buzz_core::git_perms::{evaluate_push, parse_protection_tags, Denial, RefUpdate, UpdateKind};
+use buzz_core::git_perms::{
+    evaluate_push, parse_protection_tags, Denial, RefUpdate, UpdateKind,
+    GIT_NO_CHANNEL_BINDING_BODY,
+};
 use buzz_db::EventQuery;
 
 use crate::state::AppState;
@@ -297,12 +300,29 @@ pub async fn hook_policy_check(
         }
     };
 
-    // 6. Resolve channel and check archived state (applies to ALL pushers including owner).
-    let channel_id = tags
-        .iter()
-        .find(|t| t.first().map(|s| s.as_str()) == Some("buzz-channel"))
-        .and_then(|t| t.get(1))
-        .and_then(|id| Uuid::parse_str(id).ok());
+    // 6. Resolve channel binding via the shared resolver (same first-tag,
+    // fail-closed semantics as the read gate) and check archived state
+    // (applies to ALL pushers including owner).
+    //
+    // `Broken` denies HERE, before owner resolution: a malformed or
+    // ambiguous first binding fails closed for *everyone*, exactly like the
+    // read gate. Letting it fall through as "unbound" would hand the owner
+    // short-circuit below a push path through a binding the read gate
+    // refuses to honor — the tri-state exists precisely so Broken and
+    // NotBound cannot collapse. Only genuinely-NotBound repos proceed, and
+    // only they may earn the remediation-token denial.
+    let channel_id = match crate::api::git::binding::resolve_repo_binding(&repo_event.event) {
+        crate::api::git::binding::RepoBinding::Bound(id) => Some(id),
+        crate::api::git::binding::RepoBinding::NotBound => None,
+        crate::api::git::binding::RepoBinding::Broken => {
+            warn!(repo = %req.repo_id, "hook callback: broken buzz-channel binding");
+            // Deliberately NOT the no_channel_binding token body: the
+            // remediation contract is NotBound-only. A broken binding is
+            // ambiguity, and ambiguity gets a generic denial (matching the
+            // read gate's posture for the same announcement).
+            return (StatusCode::FORBIDDEN, "invalid channel binding").into_response();
+        }
+    };
 
     if let Some(ch_id) = channel_id {
         match state.db.get_channel(community, ch_id).await {
@@ -350,7 +370,10 @@ pub async fn hook_policy_check(
         match channel_id {
             None => {
                 warn!(repo = %req.repo_id, "hook callback: no buzz-channel binding");
-                return (StatusCode::FORBIDDEN, "no channel binding").into_response();
+                // Declared cross-component contract — see the const docs in
+                // buzz-core::git_perms for who consumes the token and why
+                // the body also repeats the legacy phrase.
+                return (StatusCode::FORBIDDEN, GIT_NO_CHANNEL_BINDING_BODY).into_response();
             }
             Some(ch_id) => {
                 match state
@@ -482,6 +505,30 @@ mod tests {
         assert!(!verify_hmac(b"wrong-secret", &req));
     }
 
+    /// Deploy-skew guard for the unbound-repo deny body. The token
+    /// (`no_channel_binding`, underscores) and the legacy phrase
+    /// (`no channel binding`, spaces) do NOT contain each other, so the body
+    /// must carry both: the token for structured consumers (Desktop's merge
+    /// classifier and dialog matcher), the phrase for desktops already in
+    /// the field that prose-match it. Relay ships continuously and Desktop
+    /// on release cadence — dropping the phrase strands every old desktop
+    /// on a new relay. Asserted against the shared consts, not re-typed
+    /// literals, so the const and this test cannot drift apart separately.
+    #[test]
+    fn no_channel_binding_body_satisfies_old_and_new_matchers() {
+        assert!(
+            GIT_NO_CHANNEL_BINDING_BODY.starts_with(&format!(
+                "{}: ",
+                buzz_core::git_perms::GIT_NO_CHANNEL_BINDING_TOKEN
+            )),
+            "new structured consumers match the token prefix"
+        );
+        assert!(
+            GIT_NO_CHANNEL_BINDING_BODY.contains("no channel binding"),
+            "shipped desktops prose-match this exact phrase (spaces, not underscores)"
+        );
+    }
+
     #[test]
     fn hmac_tampered_repo_id_rejected() {
         let secret = b"test-secret";
@@ -772,4 +819,169 @@ printf '%s' "$HMAC_INPUT" | openssl dgst -sha256 -hmac "{secret}" -hex 2>/dev/nu
             "Single-ref HMAC mismatch!\n  Rust: {rust_sig}\n  Bash: {bash_sig}"
         );
     }
+
+    // ── hook_policy_check binding gate (requires Postgres) ──────────────
+
+    const TEST_DB_URL: &str = "postgres://buzz:buzz_dev@localhost:5432/buzz"; // sadscan:disable np.postgres.1
+
+    async fn policy_test_state() -> Arc<AppState> {
+        let mut config = crate::config::Config::from_env().expect("default config loads");
+        config.require_relay_membership = false;
+        config.redis_url = "redis://127.0.0.1:1".to_string();
+        config.database_url = std::env::var("BUZZ_TEST_DATABASE_URL")
+            .or_else(|_| std::env::var("DATABASE_URL"))
+            .unwrap_or_else(|_| TEST_DB_URL.to_string());
+        let pool = sqlx::PgPool::connect(&config.database_url)
+            .await
+            .expect("connect test DB");
+        let db = buzz_db::Db::from_pool(pool.clone());
+        let redis_pool = deadpool_redis::Config::from_url(&config.redis_url)
+            .create_pool(Some(deadpool_redis::Runtime::Tokio1))
+            .expect("redis pool");
+        let pubsub = Arc::new(
+            buzz_pubsub::PubSubManager::new(&config.redis_url, redis_pool.clone())
+                .await
+                .expect("pubsub manager"),
+        );
+        let audit = buzz_audit::AuditService::new(pool.clone());
+        let auth = buzz_auth::AuthService::new(config.auth.clone());
+        let search = buzz_search::SearchService::new(pool.clone());
+        let workflow_engine = Arc::new(buzz_workflow::WorkflowEngine::new(
+            db.clone(),
+            buzz_workflow::WorkflowConfig::default(),
+        ));
+        let media_storage = buzz_media::MediaStorage::new(&config.media).expect("media storage");
+        let (state, _audit_shutdown) = AppState::new(
+            config,
+            db,
+            redis_pool,
+            audit,
+            pubsub,
+            auth,
+            search,
+            workflow_engine,
+            nostr::Keys::generate(),
+            media_storage,
+        );
+        Arc::new(state)
+    }
+
+    /// Announce `repo_id` with the given tags, then push to it as its own
+    /// announcement author and return the response.
+    async fn owner_push_response(
+        state: &Arc<AppState>,
+        community: buzz_core::CommunityId,
+        keys: &nostr::Keys,
+        repo_id: &str,
+        binding_tags: Vec<nostr::Tag>,
+    ) -> axum::response::Response {
+        use nostr::{EventBuilder, Kind, Tag};
+
+        let mut tags = vec![Tag::parse(["d", repo_id]).unwrap()];
+        tags.extend(binding_tags);
+        let event = EventBuilder::new(Kind::Custom(30617), "")
+            .tags(tags)
+            .sign_with_keys(keys)
+            .expect("sign 30617");
+        state
+            .db
+            .insert_event(community, &event, None)
+            .await
+            .expect("insert 30617");
+
+        let owner_hex = keys.public_key().to_hex();
+        let mut req = HookCallbackRequest {
+            repo_id: repo_id.to_string(),
+            repo_owner: owner_hex.clone(),
+            community_id: community.as_uuid().to_string(),
+            pusher_pubkey: owner_hex,
+            ref_updates: vec![HookRefUpdate {
+                old_oid: "0".repeat(40),
+                new_oid: "2".repeat(40),
+                ref_name: "refs/heads/main".to_string(),
+                is_ancestor: false,
+            }],
+            timestamp: SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap()
+                .as_secs(),
+            signature: String::new(),
+        };
+        let secret = state.config.git_hook_hmac_secret.clone();
+        sign_request(&mut req, secret.as_bytes());
+        hook_policy_check(State(Arc::clone(state)), Json(req)).await
+    }
+
+    async fn body_string(response: axum::response::Response) -> (StatusCode, String) {
+        let status = response.status();
+        let bytes = axum::body::to_bytes(response.into_body(), usize::MAX)
+            .await
+            .expect("read body");
+        (status, String::from_utf8(bytes.to_vec()).expect("utf-8"))
+    }
+
+    /// The tri-state trap the resolver exists to prevent: a broken (malformed
+    /// or ambiguous-first) binding must fail closed for EVERYONE on push —
+    /// including the announcement author — *before* the owner short-circuit
+    /// grants `MemberRole::Owner`. Collapsing `Broken` into "unbound" hands
+    /// the owner a push path through a binding the read gate refuses to
+    /// honor. The remediation token stays reserved for genuinely NotBound.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn push_gate_denies_owner_through_broken_binding() {
+        use nostr::{Keys, Tag};
+
+        let state = policy_test_state().await;
+        let host = format!("policy-{}.example", uuid::Uuid::new_v4().simple());
+        let community = state
+            .db
+            .ensure_configured_community(&host)
+            .await
+            .expect("community")
+            .id;
+        let keys = Keys::generate();
+
+        // Malformed first + valid-looking second: the ambiguity must deny,
+        // and the parseable duplicate must not rescue the push.
+        let response = owner_push_response(
+            &state,
+            community,
+            &keys,
+            &format!("repo-{}", uuid::Uuid::new_v4().simple()),
+            vec![
+                Tag::parse(["buzz-channel", "not-a-uuid"]).unwrap(),
+                Tag::parse(["buzz-channel", &uuid::Uuid::new_v4().to_string()]).unwrap(),
+            ],
+        )
+        .await;
+        let (status, body) = body_string(response).await;
+        assert_eq!(status, StatusCode::FORBIDDEN);
+        assert_eq!(
+            body, "invalid channel binding",
+            "owner pushing through a broken binding must be denied generically"
+        );
+        assert!(
+            !body.contains(buzz_core::git_perms::GIT_NO_CHANNEL_BINDING_TOKEN),
+            "remediation token is NotBound-only; Broken must never earn it"
+        );
+
+        // Control: the same owner pushing a genuinely NEVER-BOUND repo is
+        // allowed (owner authority over an unbound announcement is the
+        // long-standing push semantics). This pins the denial above to
+        // Broken specifically, not to some broader regression.
+        let response = owner_push_response(
+            &state,
+            community,
+            &keys,
+            &format!("repo-{}", uuid::Uuid::new_v4().simple()),
+            vec![],
+        )
+        .await;
+        let (status, body) = body_string(response).await;
+        assert_eq!(
+            status,
+            StatusCode::OK,
+            "owner push to a never-bound repo must remain allowed (got body: {body})"
+        );
+    }
 }
diff --git a/crates/buzz-relay/src/api/git/store.rs b/crates/buzz-relay/src/api/git/store.rs
index 43d210e648..bdfca8dcf2 100644
--- a/crates/buzz-relay/src/api/git/store.rs
+++ b/crates/buzz-relay/src/api/git/store.rs
@@ -174,7 +174,9 @@ pub struct GitStore {
 impl GitStore {
     /// Build a client against an S3-compatible endpoint (e.g. MinIO).
     ///
-    /// Uses path-style addressing for MinIO compatibility; AWS S3 accepts both.
+    /// `addressing_style` is shared with media storage so both paths sign and
+    /// route requests consistently. Path style supports the bundled MinIO DNS;
+    /// virtual-hosted style supports standard S3 and providers such as Railway.
     ///
     /// Credential selection mirrors [`buzz_media::MediaStorage::new`]:
     /// - both `access_key` and `secret_key` non-empty → static credentials
@@ -190,6 +192,7 @@ impl GitStore {
         secret_key: &str,
         bucket_name: &str,
         region: &str,
+        addressing_style: buzz_media::config::S3AddressingStyle,
     ) -> Result<Self, StoreError> {
         let region = Region::Custom {
             region: region.into(),
@@ -209,9 +212,11 @@ impl GitStore {
             }
         }
         .map_err(|e| StoreError::Backend(S3Error::Credentials(e)))?;
-        let bucket = Bucket::new(bucket_name, region, creds)
-            .map_err(StoreError::Backend)?
-            .with_path_style();
+        let bucket = Bucket::new(bucket_name, region, creds).map_err(StoreError::Backend)?;
+        let bucket = match addressing_style {
+            buzz_media::config::S3AddressingStyle::Path => bucket.with_path_style(),
+            buzz_media::config::S3AddressingStyle::Virtual => bucket,
+        };
         Ok(Self {
             bucket: Arc::from(bucket),
         })
@@ -950,6 +955,7 @@ mod tests {
             "buzz_dev_secret",
             "buzz-git",
             "us-west-2",
+            buzz_media::config::S3AddressingStyle::Path,
         )
         .expect("static creds should build a git store");
         match store.bucket.region {
@@ -958,6 +964,34 @@ mod tests {
         }
     }
 
+    #[test]
+    fn constructor_applies_both_addressing_styles() {
+        for (style, expected_url, path_style) in [
+            (
+                buzz_media::config::S3AddressingStyle::Path,
+                "https://storage.example/buzz-git",
+                true,
+            ),
+            (
+                buzz_media::config::S3AddressingStyle::Virtual,
+                "https://buzz-git.storage.example",
+                false,
+            ),
+        ] {
+            let store = GitStore::new(
+                "https://storage.example",
+                "buzz_dev",
+                "buzz_dev_secret",
+                "buzz-git",
+                "us-east-1",
+                style,
+            )
+            .expect("construct git store");
+            assert_eq!(store.bucket.url(), expected_url);
+            assert_eq!(store.bucket.is_path_style(), path_style);
+        }
+    }
+
     #[test]
     fn partial_static_keys_are_rejected() {
         for (access, secret) in [("buzz_dev", ""), ("", "buzz_dev_secret")] {
@@ -967,6 +1001,7 @@ mod tests {
                 secret,
                 "buzz-git",
                 "us-east-1",
+                buzz_media::config::S3AddressingStyle::Path,
             ) {
                 Ok(_) => {
                     panic!("partial static creds must not silently use the credential chain")
@@ -998,14 +1033,29 @@ mod probe {
     }
 
     fn store() -> GitStore {
+        // This is the dedicated backend conformance path, so all connection and
+        // signing inputs are overridable for a real provider such as Railway.
+        // The hydrate/CAS live tests use explicit local MinIO fixtures instead.
+        let endpoint =
+            std::env::var("BUZZ_S3_ENDPOINT").unwrap_or_else(|_| "http://localhost:9000".into());
+        let access_key = std::env::var("BUZZ_S3_ACCESS_KEY").unwrap_or_else(|_| "buzz_dev".into());
+        let secret_key =
+            std::env::var("BUZZ_S3_SECRET_KEY").unwrap_or_else(|_| "buzz_dev_secret".into());
+        let bucket = std::env::var("BUZZ_S3_BUCKET").unwrap_or_else(|_| "buzz-git".into());
+        let region = std::env::var("BUZZ_S3_REGION").unwrap_or_else(|_| "us-east-1".into());
+        let addressing_style = std::env::var("BUZZ_S3_ADDRESSING_STYLE")
+            .unwrap_or_else(|_| "path".into())
+            .parse()
+            .expect("BUZZ_S3_ADDRESSING_STYLE must be path or virtual");
         GitStore::new(
-            "http://localhost:9000",
-            "buzz_dev",
-            "buzz_dev_secret",
-            "buzz-git",
-            "us-east-1",
+            &endpoint,
+            &access_key,
+            &secret_key,
+            &bucket,
+            &region,
+            addressing_style,
         )
-        .expect("connect minio")
+        .expect("connect S3-compatible storage")
     }
 
     fn sha256_hex(b: &[u8]) -> String {
diff --git a/crates/buzz-relay/src/api/git/transport.rs b/crates/buzz-relay/src/api/git/transport.rs
index df5bdd4c3e..d3118d8a76 100644
--- a/crates/buzz-relay/src/api/git/transport.rs
+++ b/crates/buzz-relay/src/api/git/transport.rs
@@ -28,6 +28,7 @@ use tokio::process::Command;
 use tower_http::limit::RequestBodyLimitLayer;
 use tracing::{error, info, warn};
 
+use super::binding::{resolve_repo_binding, RepoBinding};
 use super::cas_publish::{cas_publish, CasError, ParentState, PublishLimits};
 use super::hook::install_hook;
 use super::hydrate::{
@@ -377,7 +378,15 @@ fn hydrate_error_to_response(owner: &str, repo: &str, err: HydrateError) -> Resp
 /// error all deny. There is deliberately **no repo-owner bypass**: an owner
 /// removed from the bound channel loses read access, which is the exact
 /// exploit shape this gate closes. Every denial is the same generic 404 as a
-/// nonexistent repo so membership cannot be probed through the git endpoints.
+/// nonexistent repo so membership cannot be probed through the git endpoints
+/// — with exactly one carve-out: a **never-bound** repo read by its own
+/// **announcement author** returns a 404 whose body tells the author how to
+/// bind it (issue #3527: a vanilla NIP-34 client can announce without a
+/// `buzz-channel` tag, and the repo then 404s forever with no explanation
+/// for anyone). The author already knows the repo exists — they announced it
+/// — so the remediation body leaks nothing, and only the author can rebind
+/// (kind:30617 is keyed by `(author, d)`). A *broken* binding stays generic
+/// even for the author: ambiguity fails closed.
 async fn authorize_git_read(
     db: &buzz_db::Db,
     community: buzz_core::CommunityId,
@@ -415,9 +424,32 @@ async fn authorize_git_read(
         }
     };
 
-    let Some(channel_id) = repo_bound_channel_id(&repo_event.event) else {
-        warn!(repo = %repo_name, "git read gate: missing/malformed buzz-channel binding (deny)");
-        return Err(denied());
+    let channel_id = match resolve_repo_binding(&repo_event.event) {
+        RepoBinding::Bound(id) => id,
+        RepoBinding::NotBound => {
+            // Remediation carve-out: author of a never-bound announcement.
+            // Status stays 404 — byte-identical to every other denial at the
+            // status level — so denial *class* is still unprobeable; only
+            // the body differs, and only for the one identity that already
+            // knows the repo exists. The body is a single verb-first line:
+            // Desktop error paths that keep one line keep the instruction.
+            if repo_event.event.pubkey == *caller {
+                warn!(repo = %repo_name, "git read gate: unbound repo read by its author (deny with remediation)");
+                return Err((
+                    StatusCode::NOT_FOUND,
+                    format!(
+                        "run: buzz repos bind --id {repo_name} --channel <channel-uuid> — repository {repo_name:?} has no channel binding, so the relay cannot authorize access"
+                    ),
+                )
+                    .into_response());
+            }
+            warn!(repo = %repo_name, "git read gate: missing buzz-channel binding (deny)");
+            return Err(denied());
+        }
+        RepoBinding::Broken => {
+            warn!(repo = %repo_name, "git read gate: malformed buzz-channel binding (deny)");
+            return Err(denied());
+        }
     };
 
     match db
@@ -433,24 +465,6 @@ async fn authorize_git_read(
     }
 }
 
-/// Extract the `buzz-channel` UUID from a kind:30617 announcement.
-///
-/// First-tag semantics, matching the push policy endpoint: only the *first*
-/// `buzz-channel` tag is considered, and it must carry a valid UUID. A
-/// malformed first binding denies even if a later duplicate tag is valid —
-/// an ambiguous announcement must fail closed, not silently resolve to
-/// whichever duplicate happens to parse.
-fn repo_bound_channel_id(event: &nostr::Event) -> Option<uuid::Uuid> {
-    let first = event
-        .tags
-        .iter()
-        .find(|t| t.as_slice().first().map(String::as_str) == Some("buzz-channel"))?;
-    first
-        .as_slice()
-        .get(1)
-        .and_then(|v| uuid::Uuid::parse_str(v).ok())
-}
-
 /// Pure decision for [`authorize_git_read`]: a read requires a current
 /// active membership row whose role the relay recognizes.
 ///
@@ -1050,7 +1064,7 @@ pub async fn receive_pack(
         state.config.bind_addr.port()
     );
     let hooks_dir = repo.path().join("hooks").display().to_string();
-    let hook_env = vec![
+    let mut hook_env = vec![
         ("BUZZ_HOOK_URL", hook_url),
         (
             "BUZZ_HOOK_SECRET",
@@ -1063,13 +1077,8 @@ pub async fn receive_pack(
             auth.tenant.community().as_uuid().to_string(),
         ),
         ("BUZZ_PUSHER_PUBKEY", pusher_hex.clone()),
-        // Override any repo-local core.hooksPath setting; defense in
-        // depth even though the hydrated workspace has no inherited
-        // config.
-        ("GIT_CONFIG_COUNT", "1".to_string()),
-        ("GIT_CONFIG_KEY_0", "core.hooksPath".to_string()),
-        ("GIT_CONFIG_VALUE_0", hooks_dir),
     ];
+    hook_env.extend(receive_pack_git_config(hooks_dir));
 
     // Run receive-pack against the tempdir. Returns the *owned* subprocess
     // output (PackOutput) — crucially NOT a Response, so the post-push
@@ -1097,6 +1106,23 @@ pub async fn receive_pack(
     Ok(finalize_push(&state, ctx).await)
 }
 
+/// Per-process git configuration for the hydrated receive-pack workspace.
+fn receive_pack_git_config(hooks_dir: String) -> Vec<(&'static str, String)> {
+    vec![
+        // Override any repo-local core.hooksPath setting; defense in depth
+        // even though the hydrated workspace has no inherited config.
+        ("GIT_CONFIG_COUNT", "2".to_string()),
+        ("GIT_CONFIG_KEY_0", "core.hooksPath".to_string()),
+        ("GIT_CONFIG_VALUE_0", hooks_dir),
+        // A bare repository rejects deletion of its symbolic HEAD branch by
+        // default. Hydrated repositories are ephemeral, and cas_publish
+        // selects a surviving branch for the next manifest HEAD, so allow
+        // receive-pack to apply the deletion before that selection runs.
+        ("GIT_CONFIG_KEY_1", "receive.denyDeleteCurrent".to_string()),
+        ("GIT_CONFIG_VALUE_1", "ignore".to_string()),
+    ]
+}
+
 /// Buffered output of a `git --stateless-rpc` subprocess.
 ///
 /// The handler holds this as an owned value between subprocess completion
@@ -1907,11 +1933,148 @@ mod track_c_tests {
     use buzz_core::CommunityId;
     use nostr::{EventBuilder, Keys, Kind, Tag};
     use std::collections::BTreeMap;
+    use std::io::Write;
+    use std::process::Output;
 
     fn oid_sha1() -> String {
         "cb09a769da1c01f458fa6959d4e8eded38fac8d3".to_string()
     }
 
+    fn run_test_git(cwd: &Path, args: &[&str], extra_env: &[(&str, String)]) -> Output {
+        let mut cmd = std::process::Command::new("git");
+        cmd.current_dir(cwd)
+            .args(args)
+            .env_clear()
+            .env("PATH", std::env::var("PATH").unwrap_or_default())
+            .env("GIT_CONFIG_NOSYSTEM", "1")
+            .env("GIT_CONFIG_GLOBAL", "/dev/null")
+            .env("HOME", "/dev/null");
+        for (key, value) in extra_env {
+            cmd.env(key, value);
+        }
+        cmd.output().expect("run git")
+    }
+
+    fn run_test_receive_pack(repo: &Path, request: &[u8], extra_env: &[(&str, String)]) -> Output {
+        let mut cmd = std::process::Command::new("git");
+        cmd.arg("receive-pack")
+            .arg("--stateless-rpc")
+            .arg(repo)
+            .stdin(std::process::Stdio::piped())
+            .stdout(std::process::Stdio::piped())
+            .stderr(std::process::Stdio::piped())
+            .env_clear()
+            .env("PATH", std::env::var("PATH").unwrap_or_default())
+            .env("GIT_CONFIG_NOSYSTEM", "1")
+            .env("GIT_CONFIG_GLOBAL", "/dev/null")
+            .env("HOME", "/dev/null");
+        for (key, value) in extra_env {
+            cmd.env(key, value);
+        }
+
+        let mut child = cmd.spawn().expect("spawn receive-pack");
+        child
+            .stdin
+            .take()
+            .expect("receive-pack stdin")
+            .write_all(request)
+            .expect("write receive-pack request");
+        child.wait_with_output().expect("wait for receive-pack")
+    }
+
+    fn assert_git_success(output: Output, operation: &str) {
+        assert!(
+            output.status.success(),
+            "{operation} failed: {}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+    }
+
+    #[test]
+    fn receive_pack_config_allows_deleting_current_branch() {
+        let root = tempfile::TempDir::new().expect("tempdir");
+        let remote = root.path().join("remote.git");
+        let source = root.path().join("source");
+        let remote_arg = remote.to_str().expect("utf-8 remote path");
+        let source_arg = source.to_str().expect("utf-8 source path");
+
+        assert_git_success(
+            run_test_git(
+                root.path(),
+                &["init", "--bare", "--initial-branch=main", remote_arg],
+                &[],
+            ),
+            "initialize bare remote",
+        );
+        assert_git_success(
+            run_test_git(
+                root.path(),
+                &["init", "--initial-branch=main", source_arg],
+                &[],
+            ),
+            "initialize source repository",
+        );
+        assert_git_success(
+            run_test_git(source.as_path(), &["config", "user.name", "Buzz Test"], &[]),
+            "configure user name",
+        );
+        assert_git_success(
+            run_test_git(
+                source.as_path(),
+                &["config", "user.email", "buzz-test@example.com"],
+                &[],
+            ),
+            "configure user email",
+        );
+        std::fs::write(source.join("README.md"), "test\n").expect("write fixture");
+        assert_git_success(
+            run_test_git(source.as_path(), &["add", "README.md"], &[]),
+            "stage fixture",
+        );
+        assert_git_success(
+            run_test_git(source.as_path(), &["commit", "-m", "fixture"], &[]),
+            "commit fixture",
+        );
+        assert_git_success(
+            run_test_git(
+                source.as_path(),
+                &["push", remote_arg, "main:main", "main:master"],
+                &[],
+            ),
+            "seed main and master",
+        );
+
+        let oid_output = run_test_git(remote.as_path(), &["rev-parse", "refs/heads/main"], &[]);
+        assert!(oid_output.status.success());
+        let old_oid = String::from_utf8(oid_output.stdout)
+            .expect("utf-8 oid")
+            .trim()
+            .to_string();
+        let command = format!(
+            "{old_oid} {} refs/heads/main\0report-status\n",
+            "0".repeat(40)
+        );
+        let mut request = format!("{:04x}", command.len() + 4).into_bytes();
+        request.extend_from_slice(command.as_bytes());
+        request.extend_from_slice(b"0000");
+
+        let git_config = receive_pack_git_config(remote.join("hooks").display().to_string());
+        let output = run_test_receive_pack(remote.as_path(), &request, &git_config);
+        assert!(
+            output.status.success(),
+            "receive-pack failed: {}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+        assert!(
+            !receive_pack_report_rejected(&output.stdout),
+            "receive-pack rejected the deletion: {}",
+            String::from_utf8_lossy(&output.stdout)
+        );
+
+        assert!(!remote.join("refs/heads/main").exists());
+        assert!(remote.join("refs/heads/master").exists());
+    }
+
     /// A gzip-encoded request body is transparently inflated before it
     /// reaches the git subprocess. Git's smart-HTTP client gzips the
     /// upload-pack/receive-pack request body past a size threshold (fires
@@ -2454,75 +2617,30 @@ mod sec005_read_gate_tests {
             .expect("sign 30617")
     }
 
-    #[test]
-    fn repo_bound_channel_id_extracts_valid_uuid() {
-        let keys = Keys::generate();
-        let ch = uuid::Uuid::new_v4();
-        let event = announcement(
-            &keys,
-            vec![
-                Tag::parse(["d", "r"]).unwrap(),
-                Tag::parse(["buzz-channel", &ch.to_string()]).unwrap(),
-            ],
-        );
-        assert_eq!(repo_bound_channel_id(&event), Some(ch));
-    }
-
-    #[test]
-    fn repo_bound_channel_id_rejects_absent_and_malformed_bindings() {
-        let keys = Keys::generate();
-        let absent = announcement(&keys, vec![Tag::parse(["d", "r"]).unwrap()]);
-        assert_eq!(repo_bound_channel_id(&absent), None);
-
-        let malformed = announcement(
-            &keys,
-            vec![
-                Tag::parse(["d", "r"]).unwrap(),
-                Tag::parse(["buzz-channel", "not-a-uuid"]).unwrap(),
-            ],
-        );
-        assert_eq!(repo_bound_channel_id(&malformed), None);
-
-        let empty = announcement(
-            &keys,
-            vec![
-                Tag::parse(["d", "r"]).unwrap(),
-                Tag::parse(["buzz-channel"]).unwrap(),
-            ],
-        );
-        assert_eq!(repo_bound_channel_id(&empty), None);
+    // Binding *parse* semantics (first-tag fails-closed, duplicate-tag
+    // ambiguity, malformed vs. absent) are unit-tested where the resolver
+    // lives: `super::super::binding`. The tests below prove the *gate* wires
+    // each resolver outcome to the right response — allow, generic denial
+    // body, or the author remediation body — which the resolver tests
+    // cannot see.
+
+    /// Collapse an `authorize_git_read` denial to `(status, body)` so tests
+    /// can assert on the exact bytes a git client would see. A blind
+    /// `.is_err()` cannot distinguish the generic 404 from the remediation
+    /// 404 — and that distinction IS the security property.
+    async fn denial_parts(result: Result<(), Response>) -> (StatusCode, String) {
+        let response = result.expect_err("expected a denial");
+        let status = response.status();
+        let bytes = axum::body::to_bytes(response.into_body(), usize::MAX)
+            .await
+            .expect("read denial body");
+        (
+            status,
+            String::from_utf8(bytes.to_vec()).expect("utf-8 body"),
+        )
     }
 
-    #[test]
-    fn repo_bound_channel_id_fails_closed_on_ambiguous_duplicate_bindings() {
-        // First-tag semantics: a malformed first binding must deny even when
-        // a later duplicate tag is valid. An ambiguous announcement must not
-        // silently resolve to whichever duplicate happens to parse.
-        let keys = Keys::generate();
-        let ch = uuid::Uuid::new_v4();
-        let malformed_first = announcement(
-            &keys,
-            vec![
-                Tag::parse(["d", "r"]).unwrap(),
-                Tag::parse(["buzz-channel", "not-a-uuid"]).unwrap(),
-                Tag::parse(["buzz-channel", &ch.to_string()]).unwrap(),
-            ],
-        );
-        assert_eq!(repo_bound_channel_id(&malformed_first), None);
-
-        // And the mirror image: a valid first binding wins, matching the
-        // push policy endpoint's first-tag resolution.
-        let other = uuid::Uuid::new_v4();
-        let valid_first = announcement(
-            &keys,
-            vec![
-                Tag::parse(["d", "r"]).unwrap(),
-                Tag::parse(["buzz-channel", &ch.to_string()]).unwrap(),
-                Tag::parse(["buzz-channel", &other.to_string()]).unwrap(),
-            ],
-        );
-        assert_eq!(repo_bound_channel_id(&valid_first), Some(ch));
-    }
+    const GENERIC_DENIAL: &str = "repository not found";
 
     // ── authorize_git_read matrix (requires Postgres) ────────────────────
 
@@ -2544,6 +2662,11 @@ mod sec005_read_gate_tests {
         Missing,
         /// `buzz-channel` tag whose value is not a UUID.
         Malformed,
+        /// `buzz-channel` tag carrying a well-formed UUID that names no
+        /// channel. The resolver reports `Bound`; the membership lookup
+        /// (whose SQL joins `channels … deleted_at IS NULL`) then returns
+        /// no role — the deliberate phase-1 posture for dead bindings.
+        UnknownChannel,
     }
 
     struct RepoFixture {
@@ -2609,6 +2732,9 @@ mod sec005_read_gate_tests {
             Binding::Malformed => {
                 tags.push(Tag::parse(["buzz-channel", "not-a-uuid"]).unwrap());
             }
+            Binding::UnknownChannel => {
+                tags.push(Tag::parse(["buzz-channel", &uuid::Uuid::new_v4().to_string()]).unwrap());
+            }
         }
         let event = announcement(&owner_keys, tags);
         db.insert_event(community, &event, None)
@@ -2676,32 +2802,63 @@ mod sec005_read_gate_tests {
     #[tokio::test]
     #[ignore = "requires Postgres"]
     async fn read_gate_denies_missing_or_malformed_binding_and_absent_repo() {
-        // Missing buzz-channel tag → deny even for a channel member.
+        // Missing buzz-channel tag → deny even for a channel member, with
+        // the generic body: the remediation carve-out is author-only.
         let f = setup_repo(Binding::Missing).await;
         let member = f.member_keys.public_key();
-        assert!(
-            authorize_git_read(&f.db, f.community, &member, &f.owner_hex, &f.repo)
-                .await
-                .is_err(),
-            "announcement without buzz-channel binding must deny"
+        let (status, body) = denial_parts(
+            authorize_git_read(&f.db, f.community, &member, &f.owner_hex, &f.repo).await,
+        )
+        .await;
+        assert_eq!(status, StatusCode::NOT_FOUND);
+        assert_eq!(
+            body, GENERIC_DENIAL,
+            "unbound repo read by a NON-author must get the generic body — \
+             remediation for anyone but the announcement author leaks repo existence"
         );
 
-        // Malformed buzz-channel tag → deny.
+        // Malformed buzz-channel tag → deny with the generic body EVEN FOR
+        // THE AUTHOR. This is the assertion that pins the carve-out to
+        // NotBound: if it ever fires on Broken, this fails on bytes, not
+        // on Ok/Err (which cannot see the difference).
         let g = setup_repo(Binding::Malformed).await;
-        let member_g = g.member_keys.public_key();
-        assert!(
-            authorize_git_read(&g.db, g.community, &member_g, &g.owner_hex, &g.repo)
-                .await
-                .is_err(),
-            "announcement with malformed buzz-channel binding must deny"
+        let g_owner = g.owner_keys.public_key();
+        let (status, body) = denial_parts(
+            authorize_git_read(&g.db, g.community, &g_owner, &g.owner_hex, &g.repo).await,
+        )
+        .await;
+        assert_eq!(status, StatusCode::NOT_FOUND);
+        assert_eq!(
+            body, GENERIC_DENIAL,
+            "broken binding must stay generic even for the author (ambiguity fails closed)"
+        );
+
+        // Well-formed UUID naming a nonexistent channel → resolver says
+        // Bound, membership lookup finds nothing → generic denial for
+        // everyone, author included. The dead-channel case must be
+        // indistinguishable from non-membership (phase-1 posture; ingest
+        // validation closes the front door in phase 2).
+        let u = setup_repo(Binding::UnknownChannel).await;
+        let u_owner = u.owner_keys.public_key();
+        let (status, body) = denial_parts(
+            authorize_git_read(&u.db, u.community, &u_owner, &u.owner_hex, &u.repo).await,
+        )
+        .await;
+        assert_eq!(status, StatusCode::NOT_FOUND);
+        assert_eq!(
+            body, GENERIC_DENIAL,
+            "binding to a nonexistent channel must deny generically, even for the author"
         );
 
         // Nonexistent announcement → deny.
-        assert!(
-            authorize_git_read(&f.db, f.community, &member, &f.owner_hex, "no-such-repo")
-                .await
-                .is_err(),
-            "nonexistent repo must deny"
+        let (status, body) = denial_parts(
+            authorize_git_read(&f.db, f.community, &member, &f.owner_hex, "no-such-repo").await,
+        )
+        .await;
+        assert_eq!(status, StatusCode::NOT_FOUND);
+        assert_eq!(
+            body, GENERIC_DENIAL,
+            "nonexistent repo must deny generically"
         );
 
         // Owner-mismatch: URL owner differs from announcement author → deny.
@@ -2722,6 +2879,53 @@ mod sec005_read_gate_tests {
         );
     }
 
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn read_gate_gives_author_of_unbound_repo_remediation_body() {
+        // Issue #3527: the author of a never-bound announcement is the one
+        // identity that can fix it (30617 is keyed by (author, d)) and the
+        // one identity remediation cannot leak anything to. Status must stay
+        // 404 — identical to every other denial — with the bind command in
+        // the body.
+        let f = setup_repo(Binding::Missing).await;
+        let author = f.owner_keys.public_key();
+
+        let response = authorize_git_read(&f.db, f.community, &author, &f.owner_hex, &f.repo)
+            .await
+            .expect_err("unbound repo must still deny its author");
+        assert_eq!(response.status(), StatusCode::NOT_FOUND);
+        // Guard against a future "tidy" into Json(...) or a custom
+        // IntoResponse: git prints `remote:` lines only for text/plain
+        // bodies — any other content-type makes the remediation silently
+        // invisible in the user's terminal with no failing assertion.
+        assert_eq!(
+            response
+                .headers()
+                .get(axum::http::header::CONTENT_TYPE)
+                .and_then(|v| v.to_str().ok()),
+            Some("text/plain; charset=utf-8"),
+            "remediation body must stay text/plain or git clients will swallow it"
+        );
+        let bytes = axum::body::to_bytes(response.into_body(), usize::MAX)
+            .await
+            .expect("read remediation body");
+        let body = String::from_utf8(bytes.to_vec()).expect("utf-8 body");
+        assert!(
+            body.starts_with(&format!("run: buzz repos bind --id {}", f.repo)),
+            "remediation must lead with the actionable command (got {body:?})"
+        );
+        assert_ne!(body, GENERIC_DENIAL);
+
+        // Same repo, same state, different caller: a member of some channel
+        // who is not the author still gets the generic body.
+        let member = f.member_keys.public_key();
+        let (_, body) = denial_parts(
+            authorize_git_read(&f.db, f.community, &member, &f.owner_hex, &f.repo).await,
+        )
+        .await;
+        assert_eq!(body, GENERIC_DENIAL, "remediation is author-only");
+    }
+
     #[tokio::test]
     #[ignore = "requires Postgres"]
     async fn read_gate_follows_current_announcement_not_stale_registry() {
@@ -2740,10 +2944,18 @@ mod sec005_read_gate_tests {
         );
 
         let owner_pk = f.owner_keys.public_key().to_bytes().to_vec();
+        // Tombstone timestamped after the announcement, per NIP-09's
+        // at-or-before scoping in `soft_delete_by_coordinate`.
         let deleted =
-            f.db.soft_delete_by_coordinate(f.community, 30617, &owner_pk, &f.repo)
-                .await
-                .expect("soft delete 30617");
+            f.db.soft_delete_by_coordinate(
+                f.community,
+                30617,
+                &owner_pk,
+                &f.repo,
+                chrono::Utc::now().timestamp() + 60,
+            )
+            .await
+            .expect("soft delete 30617");
         assert!(deleted, "precondition: a live announcement row was deleted");
 
         assert!(
diff --git a/crates/buzz-relay/src/config.rs b/crates/buzz-relay/src/config.rs
index a1691349d6..85a0ca2efe 100644
--- a/crates/buzz-relay/src/config.rs
+++ b/crates/buzz-relay/src/config.rs
@@ -56,6 +56,10 @@ pub struct Config {
     /// Optional read-replica connection URL (e.g. an Aurora `cluster-ro-`
     /// endpoint). Unset means all reads stay on the writer.
     pub read_database_url: Option<String>,
+    /// Replica read budget `B` in milliseconds (`BUZZ_REPLICA_READ_MAX_AGE_MS`).
+    /// `0` (the default) disables bounded-staleness replica routing; see
+    /// [`buzz_db::DbConfig::replica_read_max_age_ms`].
+    pub replica_read_max_age_ms: u64,
     /// Redis connection URL used by the pub/sub manager.
     pub redis_url: String,
     /// Maximum connections in the shared Redis pool. Defaults to 16.
@@ -72,6 +76,11 @@ pub struct Config {
     /// the per-pod pool and requests fail on acquire timeout while the
     /// database sits idle.
     pub db_pool_size: u32,
+    /// Maximum connections in the Postgres read-replica pool
+    /// (`BUZZ_DB_READ_POOL_SIZE`). Defaults to `db_pool_size`. Sized
+    /// independently so reader capacity can be tuned against the replica's
+    /// headroom without touching the writer pool.
+    pub db_read_pool_size: Option<u32>,
     /// Public WebSocket URL of this relay, advertised in NIP-11.
     pub relay_url: String,
     /// Public WebSocket URL of the dedicated device-pairing relay, when configured.
@@ -423,6 +432,27 @@ impl Config {
             .map(|v| v.trim().to_string())
             .filter(|v| !v.is_empty());
 
+        // The old seconds-denominated name is a hard startup error, not an
+        // alias: silently honouring it would mean 1000x the intended budget.
+        if std::env::var("BUZZ_REPLICA_HEAD_MAX_AGE_SECS").is_ok() {
+            return Err(ConfigError::InvalidValue(
+                "BUZZ_REPLICA_HEAD_MAX_AGE_SECS was renamed to BUZZ_REPLICA_READ_MAX_AGE_MS \
+                 (note: milliseconds, not seconds); refusing to start"
+                    .to_string(),
+            ));
+        }
+
+        // Replica read budget: 0 = off (the rollout default), so this is a
+        // non-negative parse, unlike `positive_u64_from_env`.
+        let replica_read_max_age_ms = match std::env::var("BUZZ_REPLICA_READ_MAX_AGE_MS") {
+            Ok(raw) => raw.trim().parse::<u64>().map_err(|_| {
+                ConfigError::InvalidValue(
+                    "BUZZ_REPLICA_READ_MAX_AGE_MS must be a non-negative integer".to_string(),
+                )
+            })?,
+            Err(_) => 0,
+        };
+
         let redis_url =
             std::env::var("REDIS_URL").unwrap_or_else(|_| "redis://localhost:6379".to_string());
 
@@ -438,6 +468,11 @@ impl Config {
             .filter(|&v| v > 0)
             .unwrap_or(50);
 
+        let db_read_pool_size = std::env::var("BUZZ_DB_READ_POOL_SIZE")
+            .ok()
+            .and_then(|v| v.parse::<u32>().ok())
+            .filter(|&v| v > 0);
+
         let relay_url =
             std::env::var("RELAY_URL").unwrap_or_else(|_| "ws://localhost:3000".to_string());
 
@@ -630,6 +665,16 @@ impl Config {
             .and_then(|v| v.parse().ok())
             .unwrap_or(9102);
 
+        let s3_addressing_style = match std::env::var("BUZZ_S3_ADDRESSING_STYLE") {
+            Ok(value) => value.parse().map_err(ConfigError::InvalidValue)?,
+            Err(std::env::VarError::NotPresent) => buzz_media::config::S3AddressingStyle::default(),
+            Err(std::env::VarError::NotUnicode(_)) => {
+                return Err(ConfigError::InvalidValue(
+                    "BUZZ_S3_ADDRESSING_STYLE must be valid Unicode and one of 'path' or 'virtual'"
+                        .to_string(),
+                ));
+            }
+        };
         let media = buzz_media::MediaConfig {
             s3_endpoint: std::env::var("BUZZ_S3_ENDPOINT")
                 .unwrap_or_else(|_| "http://localhost:9000".to_string()),
@@ -641,6 +686,7 @@ impl Config {
             s3_region: std::env::var("BUZZ_S3_REGION")
                 .or_else(|_| std::env::var("AWS_REGION"))
                 .unwrap_or_else(|_| "us-east-1".to_string()),
+            s3_addressing_style,
             max_image_bytes: std::env::var("BUZZ_MAX_IMAGE_BYTES")
                 .ok()
                 .and_then(|v| v.parse().ok())
@@ -887,9 +933,11 @@ impl Config {
             bind_addr,
             database_url,
             read_database_url,
+            replica_read_max_age_ms,
             redis_url,
             redis_pool_size,
             db_pool_size,
+            db_read_pool_size,
             relay_url,
             pairing_relay_url,
             max_connections,
@@ -990,6 +1038,11 @@ mod tests {
             !config.require_media_get_auth,
             "require_media_get_auth should default to false for staged client rollout"
         );
+        assert_eq!(
+            config.media.s3_addressing_style,
+            buzz_media::config::S3AddressingStyle::Path,
+            "S3 addressing must default to path style for bundled MinIO compatibility"
+        );
         assert!(
             config.join_policy.is_none(),
             "join_policy should default to None so policy prompts and acceptance receipts are opt-in"
@@ -1000,6 +1053,61 @@ mod tests {
         );
     }
 
+    #[test]
+    fn s3_addressing_style_env_accepts_virtual_and_rejects_invalid_values() {
+        let _guard = ENV_MUTEX.lock().unwrap();
+        let previous = std::env::var_os("BUZZ_S3_ADDRESSING_STYLE");
+
+        std::env::set_var("BUZZ_S3_ADDRESSING_STYLE", "virtual");
+        let configured = Config::from_env()
+            .expect("virtual style config")
+            .media
+            .s3_addressing_style;
+
+        std::env::set_var("BUZZ_S3_ADDRESSING_STYLE", "auto");
+        let invalid = Config::from_env();
+
+        if let Some(value) = previous {
+            std::env::set_var("BUZZ_S3_ADDRESSING_STYLE", value);
+        } else {
+            std::env::remove_var("BUZZ_S3_ADDRESSING_STYLE");
+        }
+
+        assert_eq!(configured, buzz_media::config::S3AddressingStyle::Virtual);
+        assert!(matches!(
+            invalid,
+            Err(ConfigError::InvalidValue(ref message))
+                if message.contains("BUZZ_S3_ADDRESSING_STYLE must be 'path' or 'virtual'")
+        ));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn s3_addressing_style_env_rejects_non_unicode_values() {
+        use std::os::unix::ffi::OsStringExt;
+
+        let _guard = ENV_MUTEX.lock().unwrap();
+        let previous = std::env::var_os("BUZZ_S3_ADDRESSING_STYLE");
+        std::env::set_var(
+            "BUZZ_S3_ADDRESSING_STYLE",
+            std::ffi::OsString::from_vec(vec![0xff]),
+        );
+
+        let invalid = Config::from_env();
+
+        if let Some(value) = previous {
+            std::env::set_var("BUZZ_S3_ADDRESSING_STYLE", value);
+        } else {
+            std::env::remove_var("BUZZ_S3_ADDRESSING_STYLE");
+        }
+
+        assert!(matches!(
+            invalid,
+            Err(ConfigError::InvalidValue(ref message))
+                if message.contains("must be valid Unicode")
+        ));
+    }
+
     #[test]
     fn redis_pool_size_env_override_and_invalid_fallback() {
         let _guard = ENV_MUTEX.lock().unwrap();
@@ -1050,6 +1158,35 @@ mod tests {
         assert_eq!(junk, 50, "unparsable value must fall back to the default");
     }
 
+    #[test]
+    fn db_read_pool_size_env_override_and_invalid_fallback() {
+        let _guard = ENV_MUTEX.lock().unwrap();
+        let previous = std::env::var_os("BUZZ_DB_READ_POOL_SIZE");
+
+        std::env::remove_var("BUZZ_DB_READ_POOL_SIZE");
+        let unset = Config::from_env().expect("config").db_read_pool_size;
+
+        std::env::set_var("BUZZ_DB_READ_POOL_SIZE", "40");
+        let overridden = Config::from_env().expect("config").db_read_pool_size;
+
+        std::env::set_var("BUZZ_DB_READ_POOL_SIZE", "0");
+        let zero = Config::from_env().expect("config").db_read_pool_size;
+
+        std::env::set_var("BUZZ_DB_READ_POOL_SIZE", "not-a-number");
+        let junk = Config::from_env().expect("config").db_read_pool_size;
+
+        if let Some(value) = previous {
+            std::env::set_var("BUZZ_DB_READ_POOL_SIZE", value);
+        } else {
+            std::env::remove_var("BUZZ_DB_READ_POOL_SIZE");
+        }
+
+        assert_eq!(unset, None, "unset must inherit the writer pool sizing");
+        assert_eq!(overridden, Some(40));
+        assert_eq!(zero, None, "zero must fall back to inheriting");
+        assert_eq!(junk, None, "unparsable value must fall back to inheriting");
+    }
+
     #[test]
     fn read_database_url_unset_or_blank_is_none() {
         let _guard = ENV_MUTEX.lock().unwrap();
@@ -1078,6 +1215,58 @@ mod tests {
         );
     }
 
+    #[test]
+    fn replica_read_max_age_defaults_off_and_rejects_junk() {
+        let _guard = ENV_MUTEX.lock().unwrap();
+        let previous = std::env::var_os("BUZZ_REPLICA_READ_MAX_AGE_MS");
+        let previous_old = std::env::var_os("BUZZ_REPLICA_HEAD_MAX_AGE_SECS");
+        std::env::remove_var("BUZZ_REPLICA_HEAD_MAX_AGE_SECS");
+
+        std::env::remove_var("BUZZ_REPLICA_READ_MAX_AGE_MS");
+        let unset = Config::from_env().expect("config").replica_read_max_age_ms;
+
+        std::env::set_var("BUZZ_REPLICA_READ_MAX_AGE_MS", "1000");
+        let set = Config::from_env().expect("config").replica_read_max_age_ms;
+
+        std::env::set_var("BUZZ_REPLICA_READ_MAX_AGE_MS", "0");
+        let zero = Config::from_env().expect("config").replica_read_max_age_ms;
+
+        std::env::set_var("BUZZ_REPLICA_READ_MAX_AGE_MS", "soon");
+        let junk = Config::from_env();
+
+        // The retired seconds-denominated name must be a hard startup
+        // error even alongside a valid new-name value: silently ignoring
+        // it (or honouring it) would mean 1000x the intended budget.
+        std::env::set_var("BUZZ_REPLICA_READ_MAX_AGE_MS", "1000");
+        std::env::set_var("BUZZ_REPLICA_HEAD_MAX_AGE_SECS", "5");
+        let old_name = Config::from_env();
+
+        std::env::remove_var("BUZZ_REPLICA_HEAD_MAX_AGE_SECS");
+        if let Some(value) = previous {
+            std::env::set_var("BUZZ_REPLICA_READ_MAX_AGE_MS", value);
+        } else {
+            std::env::remove_var("BUZZ_REPLICA_READ_MAX_AGE_MS");
+        }
+        if let Some(value) = previous_old {
+            std::env::set_var("BUZZ_REPLICA_HEAD_MAX_AGE_SECS", value);
+        }
+
+        assert_eq!(unset, 0, "replica read routing must default off");
+        assert_eq!(set, 1000);
+        assert_eq!(zero, 0, "explicit 0 is off");
+        assert!(
+            junk.is_err(),
+            "an unparsable budget must fail loudly, not silently disable"
+        );
+        match old_name {
+            Err(ConfigError::InvalidValue(message)) => assert!(
+                message.contains("BUZZ_REPLICA_READ_MAX_AGE_MS"),
+                "the error must name the replacement env var, got: {message}"
+            ),
+            other => panic!("old env name must hard-fail startup, got {other:?}"),
+        }
+    }
+
     #[test]
     fn audit_logging_defaults_on_and_accepts_explicit_off() {
         let _guard = ENV_MUTEX.lock().unwrap();
diff --git a/crates/buzz-relay/src/handlers/count.rs b/crates/buzz-relay/src/handlers/count.rs
index 614e54d7a0..3eeab5e807 100644
--- a/crates/buzz-relay/src/handlers/count.rs
+++ b/crates/buzz-relay/src/handlers/count.rs
@@ -7,8 +7,8 @@ use tracing::warn;
 
 use crate::connection::{AuthState, ConnectionState};
 use crate::handlers::req::{
-    event_visible_to_reader, filter_can_match_persona_shared_kinds,
-    filter_can_match_result_gated_kinds, result_gated_count_safe_for_pushdown,
+    event_visible_to_reader, filter_can_match_result_gated_kinds,
+    filter_can_match_shared_gated_kinds, result_gated_count_safe_for_pushdown,
 };
 use crate::protocol::RelayMessage;
 use crate::state::AppState;
@@ -103,11 +103,11 @@ pub async fn handle_count(
         // fast-path count_events() cannot be used because it doesn't do
         // per-event author filtering.
         let needs_author_only_filtering = super::req::filter_can_match_author_only_kinds(filter);
-        // Determine if this filter can match kind 30175 (persona) — if so, the
-        // fast-path must be bypassed because it has no per-event shared-tag check.
-        // A fast count over 30175 would include foreign unshared persona events,
-        // leaking the existence of private agent activity.
-        let needs_persona_filtering = filter_can_match_persona_shared_kinds(filter);
+        // Determine if this filter can match a shared-gated kind (30175, 30178)
+        // — if so, the fast path must be bypassed because it has no per-event
+        // shared-tag check. A fast count over those kinds would include foreign
+        // unshared events, leaking the existence of private agent activity.
+        let needs_shared_gate_filtering = filter_can_match_shared_gated_kinds(filter);
         // Determine if this filter can match result-gated kinds (44200, 30622)
         // that require a per-event owner check. When the fast SQL path would
         // count matching rows without calling reader_authorized_for_event, a
@@ -157,10 +157,10 @@ pub async fn handle_count(
                 conn.tenant.community(),
             )
             .await;
-            // Persona visibility pushdown: pre-filter the fallback query_events
-            // candidate page before ORDER/LIMIT.
-            if needs_persona_filtering {
-                query.persona_reader = Some(pubkey_bytes.clone());
+            // Shared-gated visibility pushdown: pre-filter the fallback
+            // query_events candidate page before ORDER/LIMIT.
+            if needs_shared_gate_filtering {
+                query.shared_gated_reader = Some(pubkey_bytes.clone());
             }
             let author_is_self = filter.authors.as_ref().is_some_and(|authors| {
                 !authors.is_empty()
@@ -171,9 +171,9 @@ pub async fn handle_count(
             if super::req::filter_fully_pushable(filter)
                 && (!needs_author_only_filtering || author_is_self)
                 && !needs_result_gated_filtering
-                && !needs_persona_filtering
+                && !needs_shared_gate_filtering
             {
-                match state.db.count_events(&query).await {
+                match state.db.count_events_routed("count_req", &query).await {
                     Ok(n) => total += n as u64,
                     Err(e) => {
                         conn.send(RelayMessage::closed(&sub_id, &format!("error: {e}")));
@@ -184,7 +184,11 @@ pub async fn handle_count(
                 // Fallback: query + post-filter for non-pushable constraints.
                 let mut q = query;
                 super::req::apply_count_fallback_limit(&mut q);
-                match state.db.query_events(&q).await {
+                match state
+                    .db
+                    .query_events_routed_bounded("count_req_fallback", &q)
+                    .await
+                {
                     Ok(stored_events) => {
                         if super::req::count_fallback_exceeded(stored_events.len()) {
                             metrics::counter!("buzz_count_fallback_rejections_total").increment(1);
@@ -226,9 +230,9 @@ pub async fn handle_count(
             )
             .await;
             query.channel_ids = Some(accessible_channels.to_vec());
-            // Persona visibility pushdown for the fallback query_events path.
-            if needs_persona_filtering {
-                query.persona_reader = Some(pubkey_bytes.clone());
+            // Shared-gated visibility pushdown for the fallback query_events path.
+            if needs_shared_gate_filtering {
+                query.shared_gated_reader = Some(pubkey_bytes.clone());
             }
 
             let author_is_self = filter.authors.as_ref().is_some_and(|authors| {
@@ -240,10 +244,10 @@ pub async fn handle_count(
             if super::req::filter_fully_pushable(filter)
                 && (!needs_author_only_filtering || author_is_self)
                 && !needs_result_gated_filtering
-                && !needs_persona_filtering
+                && !needs_shared_gate_filtering
             {
                 query.limit = None; // COUNT doesn't need a row limit
-                match state.db.count_events(&query).await {
+                match state.db.count_events_routed("count_req", &query).await {
                     Ok(n) => total += n as u64,
                     Err(e) => {
                         conn.send(RelayMessage::closed(&sub_id, &format!("error: {e}")));
@@ -253,7 +257,11 @@ pub async fn handle_count(
             } else {
                 // Fallback: query a bounded candidate set + post-filter.
                 super::req::apply_count_fallback_limit(&mut query);
-                match state.db.query_events(&query).await {
+                match state
+                    .db
+                    .query_events_routed_bounded("count_req_fallback", &query)
+                    .await
+                {
                     Ok(stored_events) => {
                         if super::req::count_fallback_exceeded(stored_events.len()) {
                             metrics::counter!("buzz_count_fallback_rejections_total").increment(1);
diff --git a/crates/buzz-relay/src/handlers/event.rs b/crates/buzz-relay/src/handlers/event.rs
index 88dd5f5180..a9cdffcdec 100644
--- a/crates/buzz-relay/src/handlers/event.rs
+++ b/crates/buzz-relay/src/handlers/event.rs
@@ -7,7 +7,7 @@ use tracing::{debug, error, info, warn};
 
 use buzz_core::event::StoredEvent;
 use buzz_core::kind::{
-    event_kind_u32, is_ephemeral, is_unshared_persona_event, AUTHOR_ONLY_KINDS,
+    event_kind_u32, is_ephemeral, is_unshared_gated_event, AUTHOR_ONLY_KINDS,
     KIND_AGENT_OBSERVER_FRAME, KIND_GIFT_WRAP, KIND_PRESENCE_UPDATE,
 };
 use buzz_core::observer::{
@@ -151,10 +151,10 @@ pub async fn filter_fanout_by_access(
         matches
     };
 
-    // Persona shared-read gate (fan-out): kind 30175 events fan out to all
-    // connections only when carrying ["shared","true"]. Unshared personas
-    // are delivered only to the author's own connections, matching REQ semantics.
-    let matches = if buzz_core::kind::is_persona_shared_kind(event_kind_u32(&stored_event.event)) {
+    // Shared-read gate (fan-out): SHARED_GATED_KINDS events fan out to all
+    // connections only when carrying ["shared","true"]. Unshared ones are
+    // delivered only to the author's own connections, matching REQ semantics.
+    let matches = if buzz_core::kind::is_shared_gated_kind(event_kind_u32(&stored_event.event)) {
         let author = stored_event.event.pubkey.to_bytes();
         matches
             .into_iter()
@@ -167,7 +167,7 @@ pub async fn filter_fanout_by_access(
                     return true;
                 }
                 // Foreign connection: allowed only if the event is shared.
-                !is_unshared_persona_event(&stored_event.event, &pk)
+                !is_unshared_gated_event(&stored_event.event, &pk)
             })
             .collect()
     } else {
diff --git a/crates/buzz-relay/src/handlers/ingest.rs b/crates/buzz-relay/src/handlers/ingest.rs
index a30b0e714d..fcd0d70728 100644
--- a/crates/buzz-relay/src/handlers/ingest.rs
+++ b/crates/buzz-relay/src/handlers/ingest.rs
@@ -28,12 +28,12 @@ use buzz_core::kind::{
     KIND_NIP29_EDIT_METADATA, KIND_NIP29_JOIN_REQUEST, KIND_NIP29_LEAVE_REQUEST,
     KIND_NIP29_PUT_USER, KIND_NIP29_REMOVE_USER, KIND_NIP43_LEAVE_REQUEST,
     KIND_NIP65_RELAY_LIST_METADATA, KIND_PERSONA, KIND_PIN_LIST, KIND_PRESENCE_UPDATE,
-    KIND_PRODUCT_FEEDBACK, KIND_PROFILE, KIND_REACTION, KIND_READ_STATE, KIND_REPORT,
+    KIND_PRODUCT_FEEDBACK, KIND_PROFILE, KIND_PROJECT, KIND_REACTION, KIND_READ_STATE, KIND_REPORT,
     KIND_STREAM_MESSAGE, KIND_STREAM_MESSAGE_BOOKMARKED, KIND_STREAM_MESSAGE_DIFF,
     KIND_STREAM_MESSAGE_EDIT, KIND_STREAM_MESSAGE_PINNED, KIND_STREAM_MESSAGE_SCHEDULED,
-    KIND_STREAM_MESSAGE_V2, KIND_STREAM_REMINDER, KIND_TEAM, KIND_TEXT_NOTE, KIND_USER_STATUS,
-    KIND_WORKFLOW_DEF, KIND_WORKFLOW_TRIGGER, RELAY_ADMIN_ADD_MEMBER, RELAY_ADMIN_CHANGE_ROLE,
-    RELAY_ADMIN_REMOVE_MEMBER, RELAY_ADMIN_SET_WORKSPACE_PROFILE,
+    KIND_STREAM_MESSAGE_V2, KIND_STREAM_REMINDER, KIND_TEAM, KIND_TEAM_CATALOG, KIND_TEXT_NOTE,
+    KIND_USER_STATUS, KIND_WORKFLOW_DEF, KIND_WORKFLOW_TRIGGER, RELAY_ADMIN_ADD_MEMBER,
+    RELAY_ADMIN_CHANGE_ROLE, RELAY_ADMIN_REMOVE_MEMBER, RELAY_ADMIN_SET_WORKSPACE_PROFILE,
 };
 use buzz_core::tenant::TenantContext;
 use buzz_core::verification::verify_event;
@@ -214,7 +214,7 @@ fn required_scope_for_kind(kind: u32, event: &Event) -> Result<Scope, &'static s
         KIND_TEXT_NOTE | KIND_LONG_FORM => Ok(Scope::MessagesWrite),
         KIND_CONTACT_LIST | KIND_READ_STATE | KIND_USER_STATUS | KIND_AGENT_ENGRAM
         | KIND_EVENT_REMINDER | KIND_PERSONA | KIND_TEAM | KIND_MANAGED_AGENT
-        | super::push_lease::KIND_PUSH_LEASE => {
+        | KIND_TEAM_CATALOG | super::push_lease::KIND_PUSH_LEASE => {
             Ok(Scope::UsersWrite)
         }
         // NIP-AM: agent turn metrics are agent-authored global events (encrypted to owner).
@@ -301,6 +301,9 @@ fn required_scope_for_kind(kind: u32, event: &Event) -> Result<Scope, &'static s
         | KIND_HUDDLE_GUIDELINES => Ok(Scope::ChannelsWrite),
         // NIP-34: Git repository events
         KIND_GIT_REPO_ANNOUNCEMENT | KIND_GIT_REPO_STATE => Ok(Scope::ReposWrite),
+        // NIP-MP: a project is repository metadata — grouping repositories needs
+        // the same scope as announcing them.
+        KIND_PROJECT => Ok(Scope::ReposWrite),
         KIND_GIT_PATCH
         | KIND_GIT_PULL_REQUEST
         | KIND_GIT_PR_UPDATE
@@ -419,10 +422,12 @@ pub(crate) fn is_global_only_kind(kind: u32) -> bool {
             | KIND_AGENT_PROFILE
             // NIP-AP: persona definitions (30175): owner-authored, keyed by (pubkey, kind, d_tag).
             | KIND_PERSONA
-            // NIP-AP: team (30176) + managed-agent (30177) definitions: owner-authored,
-            // keyed by (pubkey, kind, d_tag). A stray `h` tag must not channel-scope them.
+            // NIP-AP: team (30176) + managed-agent (30177) definitions and the
+            // team-catalog projection (30178): owner-authored, keyed by
+            // (pubkey, kind, d_tag). A stray `h` tag must not channel-scope them.
             | KIND_TEAM
             | KIND_MANAGED_AGENT
+            | KIND_TEAM_CATALOG
             // NIP-34: git events use `a` tags (repo reference), not `h` tags (channel scope).
             // Parameterized replaceable kinds are keyed by (pubkey, kind, d_tag).
             | KIND_GIT_REPO_ANNOUNCEMENT
@@ -435,6 +440,10 @@ pub(crate) fn is_global_only_kind(kind: u32) -> bool {
             | KIND_GIT_STATUS_MERGED
             | KIND_GIT_STATUS_CLOSED
             | KIND_GIT_STATUS_DRAFT
+            // NIP-MP: projects are addressed by (pubkey, kind, d_tag). The
+            // `buzz-channel` tag is a metadata reference, not a routing directive,
+            // so a project's state is never channel-scoped.
+            | KIND_PROJECT
             // Community moderation commands (9040–9044): community-global
             // direct commands, same model as the NIP-43 9030-series. A stray
             // `h` tag must never channel-scope them (pinned contract —
@@ -1029,37 +1038,27 @@ fn validate_engram_envelope(event: &Event) -> Result<(), String> {
     Ok(())
 }
 
-/// Validate the envelope of a kind:30175 persona event.
-///
-/// Enforces:
-/// * exactly one `d` tag with a non-empty value matching the slug grammar
-///   `^[a-z0-9][a-z0-9_-]{0,63}$`.
-/// * at most one `shared` tag; if present, its value must be exactly `"true"`.
+/// Enforce the `shared`-tag shape shared by every kind in
+/// [`buzz_core::kind::SHARED_GATED_KINDS`]: at most one `shared` tag, and if
+/// present it must be exactly `["shared", "true"]`.
 ///
-/// Without the `d`-tag check, an empty d-tag collapses every persona into the
-/// `(pubkey, 30175, "")` slot — last-write-wins data loss.
+/// This ensures no ambiguous heads: either an event has no `shared` tag
+/// (author-only) or exactly `["shared", "true"]` (community-readable). Any
+/// other value (`"false"`, `"1"`, extra elements, duplicate tags) is rejected
+/// at ingest so read-path helpers — including the SQL-level `tags @>
+/// '[["shared","true"]]'` containment clause, which would otherwise match a
+/// three-element superset — can treat stored events as unambiguously one or the
+/// other.
 ///
-/// The `shared` tag rule ensures no ambiguous heads: either an event has no
-/// `shared` tag (author-only) or exactly `["shared", "true"]` (community-
-/// readable). Any other value (`"false"`, `"1"`, extra tags) is rejected at
-/// ingest so read-path helpers can treat stored events as unambiguously one or
-/// the other.
-fn validate_persona_envelope(event: &Event) -> Result<(), String> {
-    let mut d_tags: Vec<&str> = Vec::new();
+/// `label` names the kind in error messages (e.g. `"persona event"`).
+fn validate_shared_tag(event: &Event, label: &str) -> Result<(), String> {
     let mut shared_count = 0usize;
     for tag in event.tags.iter() {
         let parts = tag.as_slice();
-        if parts.len() >= 2 && parts[0].as_str() == "d" {
-            d_tags.push(&parts[1]);
-        }
         if !parts.is_empty() && parts[0].as_str() == "shared" {
-            // Exact shape required: ["shared", "true"] — exactly two elements,
-            // second element exactly "true". Extra elements are rejected so that
-            // a three-element tag like ["shared","true","extra"] cannot be stored
-            // and later misread as shared by the SQL-level visibility clause.
             if parts.len() != 2 || parts[1].as_str() != "true" {
                 return Err(format!(
-                    "persona event `shared` tag must be exactly [\"shared\",\"true\"] (got {:?})",
+                    "{label} `shared` tag must be exactly [\"shared\",\"true\"] (got {:?})",
                     parts.iter().map(|s| s.as_str()).collect::<Vec<_>>()
                 ));
             }
@@ -1068,39 +1067,380 @@ fn validate_persona_envelope(event: &Event) -> Result<(), String> {
     }
     if shared_count > 1 {
         return Err(format!(
-            "persona event must have at most one `shared` tag (got {shared_count})"
+            "{label} must have at most one `shared` tag (got {shared_count})"
         ));
     }
+    Ok(())
+}
+
+/// Return the event's single `d` tag value, requiring exactly one tag whose
+/// value is non-empty, at most 64 characters, and free of Unicode control
+/// characters and whitespace.
+///
+/// Without this check an empty `d` tag collapses every event of the kind into
+/// the `(pubkey, kind, "")` slot — last-write-wins data loss. The character
+/// bound keeps the value usable as a NIP-33 coordinate (`<kind>:<pubkey>:<d>`)
+/// and as a log field: an embedded newline or tab would break line-oriented
+/// consumers of both.
+///
+/// Tags are counted by their first element alone, so a valueless `["d"]`
+/// counts. Skipping it would let `["d"]` plus `["d", "team-1"]` pass the
+/// exactly-one rule, and a NIP-33 consumer that reads `["d"]` as an
+/// empty-valued first `d` tag would then address the event at `""` where this
+/// relay addresses it at `"team-1"`.
+///
+/// `label` names the kind in error messages (e.g. `"persona event"`).
+fn single_bounded_d_tag<'a>(event: &'a Event, label: &str) -> Result<&'a str, String> {
+    let d_tags: Vec<Option<&str>> = event
+        .tags
+        .iter()
+        .filter_map(|tag| {
+            let parts = tag.as_slice();
+            (parts.first().map(|name| name.as_str()) == Some("d"))
+                .then(|| parts.get(1).map(|value| value.as_str()))
+        })
+        .collect();
     if d_tags.len() != 1 {
         return Err(format!(
-            "persona event must have exactly one `d` tag (got {})",
+            "{label} must have exactly one `d` tag (got {})",
             d_tags.len()
         ));
     }
-    let d = d_tags[0];
+    let d = d_tags[0].unwrap_or_default();
     if d.is_empty() {
-        return Err("persona event `d` tag must not be empty".to_string());
+        return Err(format!("{label} `d` tag must not be empty"));
     }
-    // Slug grammar: ^[a-z0-9][a-z0-9_-]{0,63}$
-    if d.len() > 64 {
+    let char_count = d.chars().count();
+    if char_count > 64 {
         return Err(format!(
-            "persona event `d` tag too long ({} chars, max 64)",
-            d.len()
+            "{label} `d` tag too long ({char_count} chars, max 64)"
         ));
     }
+    if d.chars().any(|c| c.is_control() || c.is_whitespace()) {
+        return Err(format!(
+            "{label} `d` tag must not contain control characters or whitespace"
+        ));
+    }
+    Ok(d)
+}
+
+/// Validate the envelope of a kind:30175 persona event.
+///
+/// Enforces the shared-gated `shared`-tag shape ([`validate_shared_tag`]) plus
+/// exactly one `d` tag matching the persona slug grammar
+/// `^[a-z0-9][a-z0-9_-]{0,63}$`.
+fn validate_persona_envelope(event: &Event) -> Result<(), String> {
+    const LABEL: &str = "persona event";
+    validate_shared_tag(event, LABEL)?;
+    let d = single_bounded_d_tag(event, LABEL)?;
+    // Slug grammar: ^[a-z0-9][a-z0-9_-]{0,63}$
     let bytes = d.as_bytes();
     if !bytes[0].is_ascii_lowercase() && !bytes[0].is_ascii_digit() {
-        return Err(
-            "persona event `d` tag must start with a lowercase letter or digit".to_string(),
-        );
+        return Err(format!(
+            "{LABEL} `d` tag must start with a lowercase letter or digit"
+        ));
     }
     if !bytes[1..]
         .iter()
         .all(|&b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_' || b == b'-')
     {
-        return Err(
-            "persona event `d` tag must match [a-z0-9_-] after the first character".to_string(),
-        );
+        return Err(format!(
+            "{LABEL} `d` tag must match [a-z0-9_-] after the first character"
+        ));
+    }
+    Ok(())
+}
+
+/// Validate the envelope of a kind:30178 team-catalog event.
+///
+/// Enforces the shared-gated `shared`-tag shape ([`validate_shared_tag`]) plus
+/// exactly one non-empty, bounded `d` tag.
+///
+/// Deliberately NOT the persona slug grammar: a team's `d` tag is its stable
+/// local id, which is either a UUID or a built-in identifier such as
+/// `builtin-team:welcome` — the colon is not slug-legal, and rewriting ids to
+/// fit would break NIP-33 addressing against the team's own kind:30176 head.
+fn validate_team_catalog_envelope(event: &Event) -> Result<(), String> {
+    const LABEL: &str = "team-catalog event";
+    validate_shared_tag(event, LABEL)?;
+    single_bounded_d_tag(event, LABEL)?;
+    Ok(())
+}
+
+/// Maximum number of member `a` tags on a kind:30621 project.
+///
+/// Counted over raw tags, not distinct coordinates: a duplicate-heavy event
+/// naming one coordinate thousands of times would otherwise be bounded only by
+/// the relay frame limit (`config.rs`), so the cap must be checked before any
+/// set proportional to the tag list is built.
+const PROJECT_MEMBER_CAP: usize = 64;
+
+/// Maximum byte length of a project `name` tag value.
+const PROJECT_NAME_MAX_LEN: usize = 256;
+
+/// Maximum byte length of a project `description` tag value.
+const PROJECT_DESCRIPTION_MAX_LEN: usize = 2048;
+
+/// Maximum byte length of `buzz-channel` and `buzz-visibility` tag values.
+///
+/// Both are opaque strings at the relay layer; the bound exists only so an
+/// unbounded value cannot ride into storage on a tag ingest does not interpret.
+const PROJECT_METADATA_TAG_MAX_LEN: usize = 256;
+
+/// Metadata tags a project may carry at most once each.
+///
+/// Duplicates would make the effective value reader-dependent — one client
+/// taking the first, another the last.
+const PROJECT_SINGLETON_METADATA_TAGS: [&str; 4] =
+    ["name", "description", "buzz-channel", "buzz-visibility"];
+
+/// The kind segment every project member coordinate must carry: a project groups
+/// repository *announcements*, so a coordinate naming any other kind (notably
+/// kind:30618 repository state) is malformed.
+const PROJECT_MEMBER_KIND_SEGMENT: &str = "30617";
+const _: () = assert!(KIND_GIT_REPO_ANNOUNCEMENT == 30617);
+
+/// A validation failure from [`validate_project_envelope`] or
+/// [`parse_project_member_coordinate`].
+///
+/// Carries the stable NIP-MP rule identifier alongside the human-readable
+/// rejection message. The rule ID allows the fixture oracle and any future
+/// cross-implementation conformance test to assert *which* rule fired, not just
+/// that rejection occurred — an implementation cannot pass a reject fixture by
+/// refusing for an unrelated reason.
+///
+/// The eight IDs match the `reject_rules` strings in `NIP-MP.fixtures.json`
+/// exactly: `d-cardinality`, `d-empty`, `member-cap`, `member-tag-arity`,
+/// `member-coordinate-malformed`, `member-duplicate`, `metadata-cardinality`,
+/// `metadata-length`.
+#[derive(Debug)]
+struct ProjectRejection {
+    /// Stable rule identifier matching the fixture file's `reject_rules` set.
+    rule: &'static str,
+    /// Human-readable explanation forwarded to the client's NOTICE/OK message.
+    message: String,
+}
+
+impl std::fmt::Display for ProjectRejection {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "[{}] {}", self.rule, self.message)
+    }
+}
+
+impl ProjectRejection {
+    fn new(rule: &'static str, message: impl Into<String>) -> Self {
+        Self {
+            rule,
+            message: message.into(),
+        }
+    }
+}
+
+/// Validate the envelope of a kind:30621 NIP-MP project event.
+///
+/// Enforces the structural contract in `docs/nips/NIP-MP.md` — exactly one
+/// non-empty `d` tag, at most [`PROJECT_MEMBER_CAP`] member `a` tags each
+/// holding a canonical `30617:<lowercase-64-hex-owner>:<non-empty-d>`
+/// coordinate with no duplicates, and bounded metadata.
+///
+/// Deliberately absent: any membership authorization. The signer may reference
+/// any repository coordinate, including another owner's, because membership
+/// grants nothing — push policy reads the repository's own kind:30617
+/// (`api/git/policy.rs`) and never a project. Owner-only replacement comes free
+/// from NIP-33 addressing.
+///
+/// Duplicates are rejected rather than deduped: a relay cannot rewrite tags
+/// inside a signed event without invalidating its id and signature, so the
+/// choice is reject or force every consumer to apply a first-wins rule.
+fn validate_project_envelope(event: &Event) -> Result<(), ProjectRejection> {
+    let mut d_tags: Vec<&str> = Vec::new();
+    let mut members: Vec<&str> = Vec::new();
+    let mut name: Option<&str> = None;
+    let mut description: Option<&str> = None;
+    let mut buzz_channel: Option<&str> = None;
+    let mut buzz_visibility: Option<&str> = None;
+    let mut singleton_counts = [0usize; PROJECT_SINGLETON_METADATA_TAGS.len()];
+
+    for tag in event.tags.iter() {
+        let parts = tag.as_slice();
+        let Some(tag_name) = parts.first().map(|s| s.as_str()) else {
+            continue;
+        };
+        let value = parts.get(1).map(|s| s.as_str()).unwrap_or("");
+        match tag_name {
+            "d" => d_tags.push(value),
+            "a" => members.push(value),
+            _ => {
+                if let Some(i) = PROJECT_SINGLETON_METADATA_TAGS
+                    .iter()
+                    .position(|k| *k == tag_name)
+                {
+                    singleton_counts[i] += 1;
+                    match tag_name {
+                        "name" => name = Some(value),
+                        "description" => description = Some(value),
+                        "buzz-channel" => buzz_channel = Some(value),
+                        "buzz-visibility" => buzz_visibility = Some(value),
+                        _ => {}
+                    }
+                }
+            }
+        }
+    }
+
+    // `d-cardinality` / `d-empty`: under NIP-33 a missing `d` is treated as
+    // empty, which collapses every such project into the `(pubkey, 30621, "")`
+    // slot where unrelated projects silently overwrite each other. Several `d`
+    // tags make the address reader-dependent. Length is bounded by the generic
+    // `D_TAG_MAX_LEN` check the ingest pipeline already applies.
+    if d_tags.len() != 1 {
+        return Err(ProjectRejection::new(
+            "d-cardinality",
+            format!(
+                "project event must have exactly one `d` tag (got {})",
+                d_tags.len()
+            ),
+        ));
+    }
+    if d_tags[0].is_empty() {
+        return Err(ProjectRejection::new(
+            "d-empty",
+            "project event `d` tag must not be empty",
+        ));
+    }
+
+    // `member-cap` before `member-coordinate-malformed` and `member-duplicate`:
+    // refuse on count before doing per-tag work.
+    if members.len() > PROJECT_MEMBER_CAP {
+        return Err(ProjectRejection::new(
+            "member-cap",
+            format!(
+                "project event must have at most {PROJECT_MEMBER_CAP} member `a` tags (got {})",
+                members.len()
+            ),
+        ));
+    }
+    // `member-tag-arity`: every member `a` tag has exactly 2 or 3 elements per
+    // NIP-01's `a` tag grammar. A one-element tag names no coordinate; a fourth
+    // element has no defined meaning, and accepting it would let a writer park
+    // unbounded unvalidated data in a position no consumer reads.
+    for tag in event.tags.iter() {
+        let parts = tag.as_slice();
+        if parts.first().map(|s| s.as_str()) == Some("a") && !(2..=3).contains(&parts.len()) {
+            return Err(ProjectRejection::new(
+                "member-tag-arity",
+                format!(
+                    "project event member `a` tag must have exactly 2 or 3 elements (got {})",
+                    parts.len()
+                ),
+            ));
+        }
+    }
+    let mut seen = std::collections::HashSet::with_capacity(members.len());
+    for member in &members {
+        parse_project_member_coordinate(member)?;
+        if !seen.insert(*member) {
+            return Err(ProjectRejection::new(
+                "member-duplicate",
+                format!("project event has duplicate member coordinate {member:?}"),
+            ));
+        }
+    }
+
+    for (i, count) in singleton_counts.iter().enumerate() {
+        if *count > 1 {
+            return Err(ProjectRejection::new(
+                "metadata-cardinality",
+                format!(
+                    "project event must have at most one `{}` tag (got {count})",
+                    PROJECT_SINGLETON_METADATA_TAGS[i]
+                ),
+            ));
+        }
+    }
+    if let Some(name) = name {
+        if name.len() > PROJECT_NAME_MAX_LEN {
+            return Err(ProjectRejection::new(
+                "metadata-length",
+                format!(
+                    "project event `name` tag too long ({} bytes, max {PROJECT_NAME_MAX_LEN})",
+                    name.len()
+                ),
+            ));
+        }
+    }
+    if let Some(description) = description {
+        if description.len() > PROJECT_DESCRIPTION_MAX_LEN {
+            return Err(ProjectRejection::new(
+                "metadata-length",
+                format!(
+                    "project event `description` tag too long ({} bytes, max {PROJECT_DESCRIPTION_MAX_LEN})",
+                    description.len()
+                ),
+            ));
+        }
+    }
+    if let Some(buzz_channel) = buzz_channel {
+        if buzz_channel.len() > PROJECT_METADATA_TAG_MAX_LEN {
+            return Err(ProjectRejection::new(
+                "metadata-length",
+                format!(
+                    "project event `buzz-channel` tag too long ({} bytes, max {PROJECT_METADATA_TAG_MAX_LEN})",
+                    buzz_channel.len()
+                ),
+            ));
+        }
+    }
+    if let Some(buzz_visibility) = buzz_visibility {
+        if buzz_visibility.len() > PROJECT_METADATA_TAG_MAX_LEN {
+            return Err(ProjectRejection::new(
+                "metadata-length",
+                format!(
+                    "project event `buzz-visibility` tag too long ({} bytes, max {PROJECT_METADATA_TAG_MAX_LEN})",
+                    buzz_visibility.len()
+                ),
+            ));
+        }
+    }
+    Ok(())
+}
+
+/// Check that `coordinate` is a canonical repository-announcement address.
+///
+/// Splits on the first two colons only, matching how NIP-09 deletion handling
+/// parses coordinates (`side_effects.rs`), so a repository whose `d` tag
+/// contains a colon stays addressable and a project can never disagree with a
+/// deletion about where the `d` value begins.
+fn parse_project_member_coordinate(coordinate: &str) -> Result<(), ProjectRejection> {
+    let malformed = || {
+        ProjectRejection::new(
+            "member-coordinate-malformed",
+            format!(
+                "project event member `a` tag must be \
+                 `{PROJECT_MEMBER_KIND_SEGMENT}:<lowercase-64-hex-owner>:<repo-d>` (got {coordinate:?})"
+            ),
+        )
+    };
+    let mut segments = coordinate.splitn(3, ':');
+    let (Some(kind), Some(owner), Some(repo_d)) =
+        (segments.next(), segments.next(), segments.next())
+    else {
+        return Err(malformed());
+    };
+    if kind != PROJECT_MEMBER_KIND_SEGMENT {
+        return Err(malformed());
+    }
+    // Lowercase-only: `#a` filter matching is byte-exact, so an uppercase-owner
+    // head would be invisible to the lowercase-coordinate queries readers issue.
+    if owner.len() != 64
+        || !owner
+            .bytes()
+            .all(|b| b.is_ascii_hexdigit() && !b.is_ascii_uppercase())
+    {
+        return Err(malformed());
+    }
+    if repo_d.is_empty() {
+        return Err(malformed());
     }
     Ok(())
 }
@@ -2070,6 +2410,16 @@ async fn ingest_event_inner(
             .map_err(|e| IngestError::Rejected(format!("invalid: {e}")))?;
     }
 
+    if kind_u32 == KIND_TEAM_CATALOG {
+        validate_team_catalog_envelope(&event)
+            .map_err(|e| IngestError::Rejected(format!("invalid: {e}")))?;
+    }
+
+    if kind_u32 == KIND_PROJECT {
+        validate_project_envelope(&event)
+            .map_err(|e| IngestError::Rejected(format!("invalid: {e}")))?;
+    }
+
     // Track pre-created channel UUID for compensation on insert failure.
     let mut pre_created_channel: Option<Uuid> = None;
 
@@ -2481,7 +2831,12 @@ async fn ingest_event_inner(
             crate::handlers::side_effects::handle_side_effects(tenant, kind_u32, &event, state)
                 .await
         {
-            warn!(event_id = %event_id_hex, kind = kind_u32, "Side effect failed: {e}");
+            // error!, not warn!: the event was accepted but its side effects
+            // (channel creation, git repo seeding, …) did not run — the relay
+            // is now in a state the client believes it isn't. Production runs
+            // RUST_LOG=error, so warn! made these failures invisible during
+            // the #3527 triage.
+            error!(event_id = %event_id_hex, kind = kind_u32, "Side effect failed: {e}");
         }
     }
 
@@ -3592,6 +3947,24 @@ mod tests {
         assert!(err.contains("`d` tag"), "got: {err}");
     }
 
+    #[test]
+    fn persona_envelope_rejects_valueless_d_tag() {
+        // A lone ["d"] carries no value; it must fail as a missing value, not
+        // be skipped as though the event had no `d` tag at all.
+        let ev = make_persona(&[&["d"]]);
+        let err = validate_persona_envelope(&ev).unwrap_err();
+        assert!(err.contains("must not be empty"), "got: {err}");
+    }
+
+    #[test]
+    fn persona_envelope_rejects_valueless_plus_valued_d_tags() {
+        // Counting only tags with a value would see one `d` here and accept the
+        // event, breaking the exactly-one rule.
+        let ev = make_persona(&[&["d"], &["d", "slug-a"]]);
+        let err = validate_persona_envelope(&ev).unwrap_err();
+        assert!(err.contains("exactly one `d` tag"), "got: {err}");
+    }
+
     #[test]
     fn persona_envelope_rejects_too_long() {
         let slug = "a".repeat(65);
@@ -3718,6 +4091,552 @@ mod tests {
         );
     }
 
+    // ─── team-catalog (30178) envelope tests ─────────────────────────────────
+
+    fn make_team_catalog(tags: &[&[&str]]) -> Event {
+        make_event_with_tags(
+            KIND_TEAM_CATALOG,
+            r#"{"v":1,"name":"Team","members":[]}"#,
+            tags,
+        )
+    }
+
+    #[test]
+    fn team_catalog_envelope_accepts_uuid_d_tag() {
+        let ev = make_team_catalog(&[&["d", "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0"]]);
+        assert!(validate_team_catalog_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn team_catalog_envelope_accepts_builtin_colon_d_tag() {
+        // Built-in team ids carry a colon (`builtin-team:welcome`), which the
+        // persona slug grammar forbids. The catalog `d` tag must accept them so
+        // a built-in team can be shared under its real local id.
+        let ev = make_team_catalog(&[&["d", "builtin-team:welcome"]]);
+        assert!(validate_team_catalog_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn team_catalog_envelope_accepts_shared_true() {
+        let ev = make_team_catalog(&[&["d", "team-1"], &["shared", "true"]]);
+        assert!(validate_team_catalog_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_missing_d_tag() {
+        let ev = make_team_catalog(&[]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("exactly one `d` tag"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_empty_d_tag() {
+        // An empty d-tag collapses every team into the (pubkey, 30178, "") slot.
+        let ev = make_team_catalog(&[&["d", ""]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("must not be empty"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_duplicate_d_tags() {
+        let ev = make_team_catalog(&[&["d", "team-1"], &["d", "team-2"]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("exactly one `d` tag"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_valueless_d_tag() {
+        // A lone ["d"] carries no value; it must fail as a missing value, not
+        // be skipped as though the event had no `d` tag at all.
+        let ev = make_team_catalog(&[&["d"]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("must not be empty"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_valueless_plus_valued_d_tags() {
+        // Counting only tags with a value would see one `d` here and accept the
+        // event. A NIP-33 consumer that reads ["d"] as an empty-valued first
+        // `d` tag would then address this event at "" where we address it at
+        // "team-1".
+        let ev = make_team_catalog(&[&["d"], &["d", "team-1"]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("exactly one `d` tag"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_bounds_d_tag_by_chars_not_bytes() {
+        // 64 multi-byte characters is 192 bytes; the documented bound is
+        // characters, so this must be accepted.
+        let d = "é".repeat(64);
+        assert!(d.len() > 64, "fixture must exceed the bound in bytes");
+        let ev = make_team_catalog(&[&["d", &d]]);
+        assert!(validate_team_catalog_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_too_long_d_tag() {
+        let d = "a".repeat(65);
+        let ev = make_team_catalog(&[&["d", &d]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("too long"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_accepts_max_length_d_tag() {
+        let d = "a".repeat(64);
+        let ev = make_team_catalog(&[&["d", &d]]);
+        assert!(validate_team_catalog_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_whitespace_d_tag() {
+        // A newline in the d-tag would break the NIP-33 coordinate and any
+        // line-oriented log consumer.
+        let ev = make_team_catalog(&[&["d", "team\n1"]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("control characters"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_shared_false() {
+        let ev = make_team_catalog(&[&["d", "team-1"], &["shared", "false"]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("\"true\""), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_shared_three_elements() {
+        // Same exact-shape rule as personas: a three-element tag would match the
+        // SQL containment clause `tags @> '[["shared","true"]]'` as a superset.
+        let ev = make_team_catalog(&[&["d", "team-1"], &["shared", "true", "extra"]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("[\"shared\",\"true\"]"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_envelope_rejects_duplicate_shared_tags() {
+        let ev = make_team_catalog(&[&["d", "team-1"], &["shared", "true"], &["shared", "true"]]);
+        let err = validate_team_catalog_envelope(&ev).unwrap_err();
+        assert!(err.contains("at most one"), "got: {err}");
+    }
+
+    #[test]
+    fn team_catalog_is_in_scope_allowlist() {
+        let dummy = make_dummy_event();
+        assert_eq!(
+            required_scope_for_kind(KIND_TEAM_CATALOG, &dummy).unwrap(),
+            Scope::UsersWrite,
+        );
+    }
+
+    #[test]
+    fn team_catalog_is_global_only() {
+        assert!(is_global_only_kind(KIND_TEAM_CATALOG));
+        assert!(!requires_h_channel_scope(KIND_TEAM_CATALOG));
+    }
+
+    // ─── project (NIP-MP kind:30621) envelope tests ──────────────────────────
+
+    const OWNER_A: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+    const OWNER_B: &str = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+
+    fn make_project(tags: &[&[&str]]) -> Event {
+        make_event_with_tags(KIND_PROJECT, "", tags)
+    }
+
+    fn member_coord(owner: &str, repo_d: &str) -> String {
+        format!("30617:{owner}:{repo_d}")
+    }
+
+    #[test]
+    fn project_envelope_accepts_minimal() {
+        let ev = make_project(&[&["d", "platform"]]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn project_envelope_accepts_full_cross_owner_membership() {
+        // The motivating case: one project spanning two owners' repositories.
+        let a = member_coord(OWNER_A, "buzz");
+        let b = member_coord(OWNER_B, "buzz-infra");
+        let ev = make_project(&[
+            &["d", "platform"],
+            &["name", "Platform"],
+            &["description", "Relay, desktop, and mobile."],
+            &["a", &a],
+            &["a", &b],
+            &["buzz-channel", "3580ca9b-47b4-4af9-b22a-1068778f26c6"],
+            &["buzz-visibility", "listed"],
+        ]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn project_envelope_accepts_zero_members() {
+        // Legal at the protocol layer: the natural state after removing a final
+        // member. The create UI requires >= 1; the relay must not.
+        let ev = make_project(&[&["d", "empty"], &["name", "Empty"]]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn project_envelope_accepts_same_repo_d_under_two_owners() {
+        // The NIP-34 fork case. Identity is the whole coordinate, so these are
+        // two distinct members, not a duplicate.
+        let a = member_coord(OWNER_A, "buzz");
+        let b = member_coord(OWNER_B, "buzz");
+        let ev = make_project(&[&["d", "forks"], &["a", &a], &["a", &b]]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn project_envelope_accepts_member_repo_d_containing_colon() {
+        // Coordinates split on the first two colons only, matching NIP-09
+        // deletion parsing, so a colon-bearing repository `d` stays addressable.
+        let coord = member_coord(OWNER_A, "group:repo");
+        let ev = make_project(&[&["d", "external"], &["a", &coord]]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn project_envelope_accepts_member_cap_boundary() {
+        let coords: Vec<String> = (0..PROJECT_MEMBER_CAP)
+            .map(|i| member_coord(OWNER_A, &format!("repo-{i}")))
+            .collect();
+        let mut tags: Vec<Vec<&str>> = vec![vec!["d", "wide"]];
+        tags.extend(coords.iter().map(|c| vec!["a", c.as_str()]));
+        let tag_refs: Vec<&[&str]> = tags.iter().map(|t| t.as_slice()).collect();
+        let ev = make_project(&tag_refs);
+        assert!(
+            validate_project_envelope(&ev).is_ok(),
+            "exactly {PROJECT_MEMBER_CAP} members must be accepted"
+        );
+    }
+
+    #[test]
+    fn project_envelope_ignores_unknown_tags() {
+        // Forward compatibility: a newer writer's extra metadata must not
+        // invalidate the event for this relay.
+        let ev = make_project(&[&["d", "platform"], &["future-field", "whatever"]]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn project_envelope_rejects_missing_d_tag() {
+        let ev = make_project(&[&["name", "No Identity"]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("exactly one `d` tag"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_multiple_d_tags() {
+        let ev = make_project(&[&["d", "one"], &["d", "two"]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("exactly one `d` tag"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_empty_d_tag() {
+        // An empty `d` collapses every such project into the (pubkey, 30621, "")
+        // slot, where unrelated projects silently overwrite each other.
+        let ev = make_project(&[&["d", ""]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(err.to_string().contains("must not be empty"), "got: {err}");
+    }
+
+    #[test]
+    fn project_envelope_rejects_valueless_d_tag() {
+        // `["d"]` with no value is treated as empty, not as absent.
+        let ev = make_project(&[&["d"]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(err.to_string().contains("must not be empty"), "got: {err}");
+    }
+
+    #[test]
+    fn project_envelope_rejects_duplicate_member_coordinate() {
+        let coord = member_coord(OWNER_A, "buzz");
+        let ev = make_project(&[&["d", "platform"], &["a", &coord], &["a", &coord]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("duplicate member coordinate"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_member_cap_exceeded() {
+        let coords: Vec<String> = (0..=PROJECT_MEMBER_CAP)
+            .map(|i| member_coord(OWNER_A, &format!("repo-{i}")))
+            .collect();
+        let mut tags: Vec<Vec<&str>> = vec![vec!["d", "wide"]];
+        tags.extend(coords.iter().map(|c| vec!["a", c.as_str()]));
+        let tag_refs: Vec<&[&str]> = tags.iter().map(|t| t.as_slice()).collect();
+        let ev = make_project(&tag_refs);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(err.to_string().contains("at most 64 member"), "got: {err}");
+    }
+
+    #[test]
+    fn project_envelope_rejects_duplicate_heavy_list_on_cap_not_duplicate() {
+        // The cap counts raw `a` tags, so a duplicate-heavy list is refused on
+        // count — parse volume is never bounded only by the frame limit.
+        let coord = member_coord(OWNER_A, "buzz");
+        let mut tags: Vec<Vec<&str>> = vec![vec!["d", "wide"]];
+        for _ in 0..=PROJECT_MEMBER_CAP {
+            tags.push(vec!["a", coord.as_str()]);
+        }
+        let tag_refs: Vec<&[&str]> = tags.iter().map(|t| t.as_slice()).collect();
+        let ev = make_project(&tag_refs);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("at most 64 member"),
+            "cap must be evaluated before the duplicate set is built, got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_member_wrong_kind_prefix() {
+        // kind:30618 is repository *state*; a project groups announcements.
+        let coord = format!("30618:{OWNER_A}:buzz");
+        let ev = make_project(&[&["d", "platform"], &["a", &coord]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("member `a` tag must be"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_member_owner_not_hex() {
+        let coord = member_coord(&"z".repeat(64), "buzz");
+        let ev = make_project(&[&["d", "platform"], &["a", &coord]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("member `a` tag must be"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_member_owner_uppercase_hex() {
+        // `#a` filter matching is byte-exact: an uppercase-owner head would be
+        // invisible to the lowercase-coordinate queries every reader issues.
+        let coord = member_coord(&"A".repeat(64), "buzz");
+        let ev = make_project(&[&["d", "platform"], &["a", &coord]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("member `a` tag must be"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_member_owner_wrong_length() {
+        let coord = member_coord(&"a".repeat(63), "buzz");
+        let ev = make_project(&[&["d", "platform"], &["a", &coord]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("member `a` tag must be"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_member_empty_repo_d() {
+        let coord = member_coord(OWNER_A, "");
+        let ev = make_project(&[&["d", "platform"], &["a", &coord]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("member `a` tag must be"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_member_missing_segment() {
+        let coord = format!("30617:{OWNER_A}");
+        let ev = make_project(&[&["d", "platform"], &["a", &coord]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("member `a` tag must be"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_valueless_member_tag() {
+        // A one-element `a` tag names no coordinate — caught by the arity check
+        // (rule 4) before the coordinate parse (rule 5) even runs.
+        let ev = make_project(&[&["d", "platform"], &["a"]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("exactly 2 or 3 elements"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_rejects_duplicate_metadata_tags() {
+        // Every singleton metadata tag is bounded: a duplicate would make the
+        // effective value reader-dependent.
+        for tag_name in PROJECT_SINGLETON_METADATA_TAGS {
+            let ev = make_project(&[&["d", "platform"], &[tag_name, "x"], &[tag_name, "y"]]);
+            let err = validate_project_envelope(&ev).unwrap_err();
+            assert!(
+                err.to_string()
+                    .contains(&format!("at most one `{tag_name}` tag")),
+                "duplicate `{tag_name}` must be rejected, got: {err}"
+            );
+        }
+    }
+
+    #[test]
+    fn project_envelope_rejects_name_too_long() {
+        let name = "x".repeat(PROJECT_NAME_MAX_LEN + 1);
+        let ev = make_project(&[&["d", "platform"], &["name", &name]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("`name` tag too long"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_accepts_name_at_max_length() {
+        let name = "x".repeat(PROJECT_NAME_MAX_LEN);
+        let ev = make_project(&[&["d", "platform"], &["name", &name]]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn project_envelope_rejects_description_too_long() {
+        let description = "x".repeat(PROJECT_DESCRIPTION_MAX_LEN + 1);
+        let ev = make_project(&[&["d", "platform"], &["description", &description]]);
+        let err = validate_project_envelope(&ev).unwrap_err();
+        assert!(
+            err.to_string().contains("`description` tag too long"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn project_envelope_accepts_description_at_max_length() {
+        let description = "x".repeat(PROJECT_DESCRIPTION_MAX_LEN);
+        let ev = make_project(&[&["d", "platform"], &["description", &description]]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    /// Membership is an assertion, not a permission grant: the relay must accept
+    /// a project naming a repository the signer does not own. Cross-owner
+    /// grouping is the entire point of the kind, and it is safe precisely because
+    /// membership confers nothing.
+    #[test]
+    fn project_envelope_accepts_member_owned_by_another_pubkey() {
+        let stranger = member_coord(OWNER_B, "not-mine");
+        let ev = make_project(&[&["d", "collection"], &["a", &stranger]]);
+        assert!(validate_project_envelope(&ev).is_ok());
+    }
+
+    #[test]
+    fn project_is_in_scope_allowlist() {
+        let dummy = make_dummy_event();
+        assert_eq!(
+            required_scope_for_kind(KIND_PROJECT, &dummy).unwrap(),
+            Scope::ReposWrite,
+            "a project is repository metadata — same scope as announcing a repo"
+        );
+    }
+
+    #[test]
+    fn project_is_global_only() {
+        // `buzz-channel` is a metadata reference, not a routing directive.
+        assert!(is_global_only_kind(KIND_PROJECT));
+        assert!(!requires_h_channel_scope(KIND_PROJECT));
+    }
+
+    #[test]
+    fn project_is_parameterized_replaceable() {
+        // Owner-only editing comes free from NIP-33 addressing: replacement is
+        // keyed by (pubkey, kind, d), so one signer can never overwrite another's
+        // project. No relay-side permission check exists or is needed.
+        assert!(is_parameterized_replaceable(KIND_PROJECT));
+    }
+
+    /// Drive every case in the shared NIP-MP fixture file against
+    /// `validate_project_envelope`. All 11 accept cases must pass; all 20
+    /// reject cases must return an error whose rule is in the case's allowed
+    /// `reject_rules` set — an implementation cannot pass by rejecting for an
+    /// unrelated reason. This is the machine-readable oracle the spec promises.
+    #[test]
+    fn project_envelope_validates_all_shared_fixtures() {
+        #[derive(serde::Deserialize)]
+        struct FixtureFile {
+            cases: Vec<Case>,
+        }
+        #[derive(serde::Deserialize)]
+        struct Case {
+            name: String,
+            expect: String,
+            #[serde(default)]
+            reject_rules: Vec<String>,
+            template: Template,
+        }
+        #[derive(serde::Deserialize)]
+        struct Template {
+            content: String,
+            tags: Vec<Vec<String>>,
+        }
+
+        let raw = include_str!("../../../../docs/nips/NIP-MP.fixtures.json");
+        let file: FixtureFile = serde_json::from_str(raw).expect("fixture file must parse");
+
+        for case in &file.cases {
+            let tag_strs: Vec<Vec<&str>> = case
+                .template
+                .tags
+                .iter()
+                .map(|t| t.iter().map(|s| s.as_str()).collect())
+                .collect();
+            let tag_refs: Vec<&[&str]> = tag_strs.iter().map(|t| t.as_slice()).collect();
+            let ev = make_event_with_tags(KIND_PROJECT, &case.template.content, &tag_refs);
+            let result = validate_project_envelope(&ev);
+            match case.expect.as_str() {
+                "accept" => assert!(
+                    result.is_ok(),
+                    "fixture {:?} expected accept, got err: {:?}",
+                    case.name,
+                    result.unwrap_err()
+                ),
+                "reject" => {
+                    let rejection = match result {
+                        Err(r) => r,
+                        Ok(()) => {
+                            panic!("fixture {:?} expected reject, but was accepted", case.name)
+                        }
+                    };
+                    assert!(
+                        case.reject_rules.iter().any(|r| r == rejection.rule),
+                        "fixture {:?} fired rule {:?}, which is not in allowed set {:?}",
+                        case.name,
+                        rejection.rule,
+                        case.reject_rules,
+                    );
+                }
+                other => panic!(
+                    "unknown expect value {:?} in fixture {:?}",
+                    other, case.name
+                ),
+            }
+        }
+    }
+
     // ─── agent_turn_metric envelope tests ────────────────────────────────────
 
     /// Build an event for kind:44200 with the given tags and content.
diff --git a/crates/buzz-relay/src/handlers/relay_admin.rs b/crates/buzz-relay/src/handlers/relay_admin.rs
index 3f58a9c2aa..3782f2c516 100644
--- a/crates/buzz-relay/src/handlers/relay_admin.rs
+++ b/crates/buzz-relay/src/handlers/relay_admin.rs
@@ -10,7 +10,7 @@
 //! | 9030 | Add member      | admin or owner       |
 //! | 9031 | Remove member   | admin or owner       |
 //! | 9032 | Change role     | owner only           |
-//! | 9033 | Set workspace profile (icon) | admin or owner |
+//! | 9033 | Set workspace profile (icon) | admin or owner; on an open relay whose community has no admin/owner row at all, any authenticated sender (see [`may_set_workspace_profile`]) |
 
 use std::sync::Arc;
 
@@ -94,6 +94,35 @@ fn validate_workspace_icon(icon: &str) -> Result<(), String> {
     Ok(())
 }
 
+/// Whether `sender_role` may set the workspace profile (kind:9033).
+///
+/// Closed relays (`membership_enforced == true`) require an `admin`/`owner`
+/// row in `relay_members` — the enforced roster is the authority. Open relays
+/// don't *enforce* the roster, but the data can still exist: startup
+/// bootstraps `RELAY_OWNER_PUBKEY` as `owner` regardless of the flag
+/// (`main.rs`), as does operator provisioning. So the rule is steward-wins:
+///
+/// - a steward (any admin/owner row) exists → admin/owner only, exactly like
+///   a closed relay. An open relay with a configured owner keeps its icon
+///   owner-controlled instead of last-write-wins for every authenticated key.
+/// - genuinely rosterless (e.g. a community created by
+///   `ensure_configured_community`, which writes no owner row) → any
+///   NIP-42-authenticated sender may set the icon, mirroring how open relays
+///   gate every other write. Without this the icon is permanently unsettable:
+///   the desktop deliberately shows the icon editor on open relays (see
+///   `canEditIcon` in `EditCommunityDialog.tsx`, #2640) and defers to this
+///   relay-side check, which used to always say no.
+fn may_set_workspace_profile(
+    sender_role: &str,
+    membership_enforced: bool,
+    community_has_steward: bool,
+) -> bool {
+    if !membership_enforced && !community_has_steward {
+        return true;
+    }
+    sender_role == "admin" || sender_role == "owner"
+}
+
 /// A relay-admin command failure, carrying the *category* of the failure so
 /// the ingest seam can map it to the right NIP-01 prefix and HTTP status.
 ///
@@ -230,9 +259,33 @@ async fn execute_relay_admin_command(
     // kind:9033 — Set workspace profile (icon). Handled before p-tag
     // extraction: it targets the relay itself, not a member pubkey.
     if kind == RELAY_ADMIN_SET_WORKSPACE_PROFILE {
-        if sender_role != "admin" && sender_role != "owner" {
+        // Steward detection only matters on open relays (closed relays gate on
+        // the sender's own role either way), so skip the extra query there.
+        let community_has_steward = if state.config.require_relay_membership {
+            true
+        } else {
+            state
+                .db
+                .has_admin_or_owner(tenant.community())
+                .await
+                .map_err(|e| format!("database error: {e}"))?
+        };
+        if !may_set_workspace_profile(
+            sender_role,
+            state.config.require_relay_membership,
+            community_has_steward,
+        ) {
             return Err("actor not authorized: must be admin or owner".to_string());
         }
+        if sender_role != "admin" && sender_role != "owner" {
+            // Rosterless-open-relay admit: 9033 writes no audit row and
+            // publishes no announcement event (unlike 9030/9031), so this warn
+            // is the only durable attribution of who changed the icon.
+            warn!(
+                sender = %sender_hex,
+                "workspace profile change admitted without a roster role (open relay, no steward)"
+            );
+        }
 
         // Empty or missing icon tag clears the workspace icon.
         let icon = extract_tag_value(event, "icon").unwrap_or_default();
@@ -562,6 +615,46 @@ mod tests {
         assert!(validate_workspace_icon("").is_ok());
     }
 
+    /// Closed relay (membership enforced): only an admin/owner row in
+    /// `relay_members` may set the workspace profile — a plain member, or a
+    /// pubkey with no row at all (empty role), must be refused. The steward
+    /// flag is irrelevant when membership is enforced (call sites pass `true`,
+    /// but the rule must not depend on it).
+    #[test]
+    fn closed_relay_requires_admin_or_owner_for_workspace_profile() {
+        for steward in [true, false] {
+            assert!(may_set_workspace_profile("owner", true, steward));
+            assert!(may_set_workspace_profile("admin", true, steward));
+            assert!(!may_set_workspace_profile("member", true, steward));
+            assert!(!may_set_workspace_profile("", true, steward));
+        }
+    }
+
+    /// Open relay with a steward: startup bootstraps `RELAY_OWNER_PUBKEY` as
+    /// `owner` regardless of `require_relay_membership`, so an open relay's
+    /// community can hold admin/owner rows. When one exists, the icon stays
+    /// steward-only — the fix must not widen an owner-controlled icon to
+    /// every authenticated key.
+    #[test]
+    fn open_relay_with_steward_keeps_workspace_profile_steward_only() {
+        assert!(may_set_workspace_profile("owner", false, true));
+        assert!(may_set_workspace_profile("admin", false, true));
+        assert!(!may_set_workspace_profile("member", false, true));
+        assert!(!may_set_workspace_profile("", false, true));
+    }
+
+    /// Open relay, genuinely rosterless (no admin/owner row anywhere): any
+    /// authenticated sender may set the icon — including the roleless (empty
+    /// role) case, which is *every* sender there. This is the bug being
+    /// fixed: the desktop shows the icon editor on open relays (#2640) but
+    /// the relay refused every 9033.
+    #[test]
+    fn rosterless_open_relay_admits_any_authenticated_sender_for_workspace_profile() {
+        assert!(may_set_workspace_profile("", false, false));
+        assert!(may_set_workspace_profile("member", false, false));
+        assert!(may_set_workspace_profile("owner", false, false));
+    }
+
     #[test]
     fn workspace_icon_https_ok() {
         assert!(validate_workspace_icon("https://example.com/icon.png").is_ok());
@@ -591,4 +684,216 @@ mod tests {
         let long_data = format!("data:image/png;base64,{}", "A".repeat(98_304));
         assert!(validate_workspace_icon(&long_data).is_err());
     }
+
+    // ─── Call-site integration: the 9033 gate wired to real config + DB ────
+    //
+    // The unit tests above pin `may_set_workspace_profile`'s truth table, but
+    // not its wiring: mutation-testing showed that inverting
+    // `state.config.require_relay_membership` at the call site — an exact
+    // inversion of the security contract — survives the default suite. These
+    // tests drive `handle_relay_admin_event` with a real `AppState` against
+    // Postgres, on both relay modes, so the wiring itself is pinned. Selected
+    // explicitly in CI's Backend Integration job; requires local Postgres
+    // (and hard-fails rather than skipping when it is unreachable).
+
+    const TEST_DB_URL: &str = "postgres://buzz:buzz_dev@localhost:5432/buzz"; // sadscan:disable np.postgres.1
+
+    /// Build a real `AppState` + tenant for a fresh community on `host`, with
+    /// `require_relay_membership` set as given. Mirrors
+    /// `api::invites::tests::invite_test_state`.
+    async fn workspace_profile_test_state(
+        host: &str,
+        require_relay_membership: bool,
+    ) -> (Arc<AppState>, TenantContext) {
+        let mut config = crate::config::Config::from_env().expect("config from env");
+        let database_url = std::env::var("BUZZ_TEST_DATABASE_URL")
+            .or_else(|_| std::env::var("DATABASE_URL"))
+            .unwrap_or_else(|_| TEST_DB_URL.to_string());
+        config.database_url = database_url.clone();
+        config.redis_url = "redis://127.0.0.1:1".to_string();
+        config.relay_url = format!("wss://{host}");
+        config.require_relay_membership = require_relay_membership;
+
+        let pool = sqlx::PgPool::connect(&database_url)
+            .await
+            .expect("requires reachable Postgres");
+        let db = buzz_db::Db::from_pool(pool.clone());
+        let record = db
+            .ensure_configured_community(host)
+            .await
+            .expect("ensure community");
+        let tenant = TenantContext::resolved(record.id, host);
+
+        let redis_pool = deadpool_redis::Config::from_url(&config.redis_url)
+            .create_pool(Some(deadpool_redis::Runtime::Tokio1))
+            .expect("redis pool config");
+        let pubsub = Arc::new(
+            buzz_pubsub::PubSubManager::new(&config.redis_url, redis_pool.clone())
+                .await
+                .expect("pubsub manager"),
+        );
+        let audit = buzz_audit::AuditService::new(pool.clone());
+        let auth = buzz_auth::AuthService::new(config.auth.clone());
+        let search = buzz_search::SearchService::new(pool.clone());
+        let workflow_engine = Arc::new(buzz_workflow::WorkflowEngine::new(
+            db.clone(),
+            buzz_workflow::WorkflowConfig::default(),
+        ));
+        let media_storage = buzz_media::MediaStorage::new(&config.media).expect("media storage");
+        let (state, _audit_shutdown) = AppState::new(
+            config,
+            db,
+            redis_pool,
+            audit,
+            pubsub,
+            auth,
+            search,
+            workflow_engine,
+            Keys::generate(),
+            media_storage,
+        );
+        (Arc::new(state), tenant)
+    }
+
+    /// Sign a fresh kind:9033 with `icon` and run it through the real
+    /// admission + command path.
+    async fn submit_9033(
+        state: &Arc<AppState>,
+        tenant: &TenantContext,
+        keys: &Keys,
+        icon: &str,
+    ) -> Result<(), RelayAdminError> {
+        let event = EventBuilder::new(Kind::Custom(9033), "")
+            .tags(vec![Tag::parse(["icon", icon]).expect("icon tag")])
+            .sign_with_keys(keys)
+            .expect("sign 9033");
+        handle_relay_admin_event(tenant, state, &event).await
+    }
+
+    async fn stored_icon(state: &Arc<AppState>, tenant: &TenantContext) -> Option<String> {
+        state
+            .db
+            .get_community_icon(tenant.community())
+            .await
+            .expect("read icon")
+    }
+
+    /// Open relay (`require_relay_membership = false`): a rosterless
+    /// community admits any authenticated sender, but the moment a steward
+    /// (admin/owner row) exists the gate reverts to steward-only.
+    ///
+    /// Discriminating: fails if the call site inverts or drops
+    /// `require_relay_membership`, or stops consulting `has_admin_or_owner`.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn open_relay_9033_admits_roleless_only_until_a_steward_exists() {
+        let host = format!("icon-gate-open-{}.example", uuid::Uuid::new_v4().simple());
+        let (state, tenant) = workspace_profile_test_state(&host, false).await;
+        let roleless = Keys::generate();
+        let owner = Keys::generate();
+
+        // Rosterless: the roleless sender may set the icon.
+        submit_9033(&state, &tenant, &roleless, "https://example.com/open.png")
+            .await
+            .expect("rosterless open relay must admit an authenticated sender");
+        assert_eq!(
+            stored_icon(&state, &tenant).await.as_deref(),
+            Some("https://example.com/open.png"),
+            "icon must actually be stored"
+        );
+
+        // Seed a steward — the same roleless sender must now be refused, and
+        // the previously stored icon must survive the refused attempt.
+        state
+            .db
+            .add_relay_member(
+                tenant.community(),
+                &owner.public_key().to_hex(),
+                "owner",
+                None,
+            )
+            .await
+            .expect("seed owner");
+        let refused = submit_9033(&state, &tenant, &roleless, "https://evil.example/pwn.png").await;
+        assert_eq!(
+            refused,
+            Err(RelayAdminError::Rejected(
+                "actor not authorized: must be admin or owner".to_string()
+            )),
+            "an open relay with a steward must refuse a roleless sender"
+        );
+        assert_eq!(
+            stored_icon(&state, &tenant).await.as_deref(),
+            Some("https://example.com/open.png"),
+            "refused attempt must not mutate the icon"
+        );
+
+        // The steward still can.
+        submit_9033(&state, &tenant, &owner, "https://example.com/owner.png")
+            .await
+            .expect("the steward must retain icon control");
+        assert_eq!(
+            stored_icon(&state, &tenant).await.as_deref(),
+            Some("https://example.com/owner.png")
+        );
+    }
+
+    /// Closed relay (`require_relay_membership = true`): admin/owner only —
+    /// a plain member and a roleless key are refused even though the
+    /// community also *looks* rosterless-then-stewarded to the open-relay
+    /// branch. Together with the open-relay test this kills the inverted-flag
+    /// mutant: no assignment of the flag satisfies both.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn closed_relay_9033_still_requires_admin_or_owner() {
+        let host = format!("icon-gate-closed-{}.example", uuid::Uuid::new_v4().simple());
+        let (state, tenant) = workspace_profile_test_state(&host, true).await;
+        let roleless = Keys::generate();
+        let member = Keys::generate();
+        let admin = Keys::generate();
+        state
+            .db
+            .add_relay_member(
+                tenant.community(),
+                &member.public_key().to_hex(),
+                "member",
+                None,
+            )
+            .await
+            .expect("seed member");
+        state
+            .db
+            .add_relay_member(
+                tenant.community(),
+                &admin.public_key().to_hex(),
+                "admin",
+                None,
+            )
+            .await
+            .expect("seed admin");
+
+        for (keys, label) in [(&roleless, "roleless"), (&member, "member")] {
+            let refused = submit_9033(&state, &tenant, keys, "https://evil.example/pwn.png").await;
+            assert_eq!(
+                refused,
+                Err(RelayAdminError::Rejected(
+                    "actor not authorized: must be admin or owner".to_string()
+                )),
+                "closed relay must refuse a {label} sender"
+            );
+        }
+        assert_eq!(
+            stored_icon(&state, &tenant).await,
+            None,
+            "refused attempts must not set an icon"
+        );
+
+        submit_9033(&state, &tenant, &admin, "https://example.com/closed.png")
+            .await
+            .expect("closed-relay admin must set the icon");
+        assert_eq!(
+            stored_icon(&state, &tenant).await.as_deref(),
+            Some("https://example.com/closed.png")
+        );
+    }
 }
diff --git a/crates/buzz-relay/src/handlers/req.rs b/crates/buzz-relay/src/handlers/req.rs
index d3ddd3e5d3..2aed12cd7f 100644
--- a/crates/buzz-relay/src/handlers/req.rs
+++ b/crates/buzz-relay/src/handlers/req.rs
@@ -7,8 +7,8 @@ use tracing::{debug, warn};
 
 use buzz_core::filter::filters_match;
 use buzz_core::kind::{
-    is_unshared_persona_event, AUTHOR_ONLY_KINDS, KIND_AGENT_ENGRAM, KIND_AGENT_TURN_METRIC,
-    KIND_DM_VISIBILITY, KIND_PERSONA, P_GATED_KINDS, RESULT_GATED_KINDS,
+    is_unshared_gated_event, AUTHOR_ONLY_KINDS, KIND_AGENT_ENGRAM, KIND_AGENT_TURN_METRIC,
+    KIND_DM_VISIBILITY, P_GATED_KINDS, RESULT_GATED_KINDS, SHARED_GATED_KINDS,
 };
 use buzz_core::tenant::TenantContext;
 use buzz_db::EventQuery;
@@ -22,7 +22,6 @@ use crate::connection::{AuthState, ConnectionState};
 use crate::protocol::RelayMessage;
 use crate::state::AppState;
 
-const MAX_HISTORICAL_LIMIT: i64 = 2_000;
 const MAX_SUBSCRIPTIONS: usize = 1024;
 
 /// Maximum `query_events` calls in flight per multi-filter REQ / bridge query.
@@ -290,11 +289,11 @@ pub async fn handle_req(
             let mut params =
                 filter_to_query_params(filter, per_filter_channel, conn.tenant.community());
             apply_access_scope_to_query(&mut params, per_filter_channel, &accessible_channels);
-            // Persona visibility pushdown: set reader bytes so query_events appends
-            // the SQL visibility clause before ORDER/LIMIT, preventing newer private
-            // personas from starving older shared ones off the page.
-            if filter_can_match_persona_shared_kinds(filter) {
-                params.persona_reader = Some(pubkey_bytes.clone());
+            // Shared-gated visibility pushdown: set reader bytes so query_events
+            // appends the SQL visibility clause before ORDER/LIMIT, preventing
+            // newer private events from starving older shared ones off the page.
+            if filter_can_match_shared_gated_kinds(filter) {
+                params.shared_gated_reader = Some(pubkey_bytes.clone());
             }
             (idx, per_filter_channel, params)
         })
@@ -310,7 +309,7 @@ pub async fn handle_req(
         |(idx, per_filter_channel, params)| {
             let db = db.clone();
             async move {
-                let filter_events = db.query_events(&params).await;
+                let filter_events = db.query_events_routed("req_historical", &params).await;
                 (idx, per_filter_channel, filter_events)
             }
         },
@@ -416,10 +415,24 @@ pub async fn handle_req(
     );
 }
 
-/// Handle a NIP-50 search REQ: query Postgres FTS, fetch full events, deliver results, EOSE.
-/// Search subscriptions are one-shot — no persistent subscription is registered.
+/// FTS candidate hits fetched per page. Pages are always full regardless of
+/// the requested limit — post-filtering discards an unpredictable share of
+/// hits, so the scan fetches candidates in full pages rather than sizing
+/// pages to the request.
+const SEARCH_PAGE_SIZE: u32 = 100;
+
 /// Maximum FTS pages to fetch per filter (prevents unbounded loops).
-const MAX_SEARCH_PAGES: u32 = 10;
+///
+/// Derived from the advertised page ceiling rather than fixed: the scan
+/// budget is a resource policy — at most one advertised page ceiling's worth
+/// of candidates per filter — and deriving it keeps the budget tracking the
+/// ceiling if the ceiling ever moves. This bounds candidates *scanned*, not
+/// events *emitted*: post-filtering (NIP-01 match, channel access, reader
+/// visibility, dedup) can discard any number of candidates, so a result
+/// smaller than the requested limit remains possible and is not a NIP-11
+/// violation — `max_limit` promises a clamp on the request, not a count in
+/// the response.
+const MAX_SEARCH_PAGES: u32 = (buzz_db::DEFAULT_MAX_PAGE_LIMIT as u32).div_ceil(SEARCH_PAGE_SIZE);
 
 /// Resolve request-local channel access, repairing a stale cache-negative.
 ///
@@ -501,6 +514,8 @@ pub(crate) fn build_search_channel_scope_filter(
     })
 }
 
+/// Handle a NIP-50 search REQ: query Postgres FTS, fetch full events, deliver results, EOSE.
+/// Search subscriptions are one-shot — no persistent subscription is registered.
 #[allow(clippy::too_many_arguments)]
 async fn handle_search_req(
     sub_id: &str,
@@ -535,8 +550,8 @@ async fn handle_search_req(
 
         let limit = filter
             .limit
-            .map(|l| (l as u32).min(MAX_HISTORICAL_LIMIT as u32))
-            .unwrap_or(MAX_HISTORICAL_LIMIT as u32);
+            .map(|l| (l as u32).min(buzz_db::DEFAULT_MAX_PAGE_LIMIT as u32))
+            .unwrap_or(buzz_db::DEFAULT_MAX_PAGE_LIMIT as u32);
 
         if limit == 0 {
             continue; // NIP-01: limit 0 means "no results from this filter"
@@ -583,13 +598,11 @@ async fn handle_search_req(
         let since = filter.since.map(|s| s.as_secs() as i64);
         let until = filter.until.map(|u| u.as_secs() as i64);
 
-        // Paginate: keep fetching pages until we've emitted `limit` results
-        // or exhausted the search result set. This ensures post-filtering
-        // doesn't silently reduce the result count below the requested limit.
+        // Paginate: keep fetching pages until we've emitted `limit` results or
+        // exhausted the search result set. Post-filtering discards an unpredictable
+        // share of each page, so continuing past short yields gives the scan a
+        // chance — not a guarantee — of filling the requested limit.
         let mut emitted: u32 = 0;
-        // Always fetch full pages (100) regardless of limit — post-filtering
-        // may discard many hits, so we need headroom to fill the requested limit.
-        let per_page: u32 = 100;
 
         for page in 1..=MAX_SEARCH_PAGES {
             if emitted >= limit {
@@ -605,7 +618,7 @@ async fn handle_search_req(
                 since,
                 until,
                 page,
-                per_page,
+                per_page: SEARCH_PAGE_SIZE,
                 mode: buzz_search::SearchMode::FullText,
             };
 
@@ -617,9 +630,9 @@ async fn handle_search_req(
                 }
             };
 
-            // A short page is the last page: FTS returns up to `per_page` hits,
-            // so fewer than that means the result set is exhausted.
-            let exhausted = search_result.hits.len() < per_page as usize;
+            // A short page is the last page: FTS returns up to a full page of
+            // hits, so fewer than that means the result set is exhausted.
+            let exhausted = search_result.hits.len() < SEARCH_PAGE_SIZE as usize;
             let page_empty = search_result.hits.is_empty();
 
             let hit_ids: Vec<[u8; 32]> =
@@ -629,7 +642,7 @@ async fn handle_search_req(
                 let id_refs: Vec<&[u8]> = hit_ids.iter().map(|b| b.as_slice()).collect();
                 let events = match state
                     .db
-                    .get_events_by_ids(tenant.community(), &id_refs)
+                    .get_events_by_ids_routed("req_search_hydrate", tenant.community(), &id_refs)
                     .await
                 {
                     Ok(evs) => evs,
@@ -878,8 +891,8 @@ fn filter_to_query_params(
         .and_then(|u| chrono::DateTime::from_timestamp(u.as_secs() as i64, 0));
     let limit = filter
         .limit
-        .map(|l| (l as i64).min(MAX_HISTORICAL_LIMIT))
-        .unwrap_or(MAX_HISTORICAL_LIMIT);
+        .map(|l| (l as i64).min(buzz_db::DEFAULT_MAX_PAGE_LIMIT))
+        .unwrap_or(buzz_db::DEFAULT_MAX_PAGE_LIMIT);
 
     // Push author filter into SQL. Single-author uses the indexed `pubkey` column;
     // multi-author uses the `authors` IN-list pushdown added in the pure-nostr PR.
@@ -1137,19 +1150,20 @@ pub(crate) fn filter_can_match_author_only_kinds(filter: &Filter) -> bool {
     })
 }
 
-/// Returns `true` if the filter CAN match kind 30175 (persona) — meaning it
-/// either has no `kinds` constraint (wildcard) or explicitly includes 30175.
+/// Returns `true` if the filter CAN match any kind in [`SHARED_GATED_KINDS`] —
+/// meaning it either has no `kinds` constraint (wildcard) or explicitly includes
+/// one of them.
 ///
 /// Used by the COUNT handler to force the per-event fallback path, which calls
-/// `is_unshared_persona_event` on each row. The fast SQL `count_events()` path
+/// `is_unshared_gated_event` on each row. The fast SQL `count_events()` path
 /// has no per-event access check, so it would over-count foreign unshared
-/// persona events — leaking the existence of persona activity even without
-/// returning content.
-pub(crate) fn filter_can_match_persona_shared_kinds(filter: &Filter) -> bool {
-    filter
-        .kinds
-        .as_ref()
-        .is_none_or(|ks| ks.iter().any(|k| k.as_u16() as u32 == KIND_PERSONA))
+/// events — leaking the existence of private persona/team-catalog activity even
+/// without returning content.
+pub(crate) fn filter_can_match_shared_gated_kinds(filter: &Filter) -> bool {
+    filter.kinds.as_ref().is_none_or(|ks| {
+        ks.iter()
+            .any(|k| SHARED_GATED_KINDS.contains(&(k.as_u16() as u32)))
+    })
 }
 
 /// Returns `true` if the filter CAN match result-gated kinds — meaning it
@@ -1208,8 +1222,9 @@ pub(crate) fn is_author_only_event(event: &nostr::Event, requester_pubkey_bytes:
 ///
 /// 1. **Author-only kinds** (`AUTHOR_ONLY_KINDS`, e.g. kind 30300/30350): only
 ///    the author may read their own events.
-/// 2. **Persona shared-gate** (kind 30175 without `["shared","true"]`): the
-///    event is only visible to the author unless explicitly opted into sharing.
+/// 2. **Shared-gate** (`SHARED_GATED_KINDS`, e.g. kind 30175/30178 without
+///    `["shared","true"]`): the event is only visible to the author unless
+///    explicitly opted into sharing.
 /// 3. **Result-gated kinds** (kind 44200/30622 etc.): `reader_authorized_for_event`
 ///    carries the per-event ownership check.
 ///
@@ -1223,7 +1238,7 @@ pub(crate) fn event_visible_to_reader(event: &nostr::Event, requester_pubkey_byt
     if is_author_only_event(event, requester_pubkey_bytes) {
         return false;
     }
-    if is_unshared_persona_event(event, requester_pubkey_bytes) {
+    if is_unshared_gated_event(event, requester_pubkey_bytes) {
         return false;
     }
     let requester_pubkey_hex = hex::encode(requester_pubkey_bytes);
@@ -1416,6 +1431,83 @@ mod tests {
         )
     }
 
+    /// NIP-11 `limitation.max_limit` as this relay actually advertises it.
+    fn advertised_max_limit() -> i64 {
+        crate::nip11::RelayInfo::build(
+            None,
+            None,
+            false,
+            crate::config::DEFAULT_MAX_FRAME_BYTES,
+            None,
+        )
+        .limitation
+        .expect("limitation")
+        .max_limit
+        .expect("max_limit") as i64
+    }
+
+    #[test]
+    fn req_filter_limit_clamps_to_advertised_nip11_max_limit() {
+        let advertised = advertised_max_limit();
+
+        let community = buzz_core::tenant::CommunityId::from_uuid(uuid::Uuid::new_v4());
+
+        // A filter asking for more than the relay advertises is clamped down to
+        // exactly the advertised ceiling — the NIP-11 document is the promise,
+        // this is the enforcement.
+        let greedy = filter_to_query_params(
+            &Filter::new().limit(advertised as usize * 10),
+            None,
+            community,
+        );
+        assert_eq!(greedy.limit, Some(advertised));
+
+        // A filter with no `limit` gets the same ceiling, not something larger.
+        let unbounded = filter_to_query_params(&Filter::new(), None, community);
+        assert_eq!(unbounded.limit, Some(advertised));
+
+        // Neither sets `max_limit`, so `query_events` applies its own default
+        // clamp. That default must equal the advertised value too, or the
+        // clamp above would be undone one layer down.
+        assert_eq!(greedy.max_limit, None);
+        assert_eq!(unbounded.max_limit, None);
+        assert_eq!(buzz_db::DEFAULT_MAX_PAGE_LIMIT, advertised);
+
+        // Under-ceiling requests are honored verbatim.
+        let modest = filter_to_query_params(&Filter::new().limit(10), None, community);
+        assert_eq!(modest.limit, Some(10));
+    }
+
+    /// The NIP-50 search path clamps its emission target to the advertised
+    /// ceiling like every other REQ, but the number of candidates it will scan
+    /// is bounded a second time by the page budget. This pins the resource
+    /// policy: the budget covers exactly one advertised page ceiling's worth of
+    /// candidates — no less (a ceiling raise must not silently shrink the scan
+    /// relative to what clients may request) and no hand-tuned spare (the budget
+    /// must stay derived, not drift back into a magic number). It deliberately
+    /// does NOT claim search fills the emitted limit — post-filtering can
+    /// discard any number of candidates.
+    #[test]
+    fn search_scan_capacity_covers_advertised_nip11_max_limit() {
+        let advertised = advertised_max_limit();
+        let capacity = i64::from(MAX_SEARCH_PAGES) * i64::from(SEARCH_PAGE_SIZE);
+
+        assert!(
+            capacity >= advertised,
+            "NIP-50 scans at most {capacity} candidates ({MAX_SEARCH_PAGES} pages of \
+             {SEARCH_PAGE_SIZE}) but NIP-11 advertises {advertised} — the scan budget \
+             no longer covers the advertised ceiling"
+        );
+
+        // The budget is derived, not hand-tuned: one page under the derived
+        // count must be insufficient, or the ceiling could rise without the
+        // page count following it.
+        assert!(
+            capacity - i64::from(SEARCH_PAGE_SIZE) < advertised,
+            "scan budget has a spare page of slack — derive it from the ceiling"
+        );
+    }
+
     #[test]
     fn count_fallback_fetches_one_extra_candidate() {
         let mut query =
diff --git a/crates/buzz-relay/src/handlers/side_effects.rs b/crates/buzz-relay/src/handlers/side_effects.rs
index 65d04ef0ba..660a55fef3 100644
--- a/crates/buzz-relay/src/handlers/side_effects.rs
+++ b/crates/buzz-relay/src/handlers/side_effects.rs
@@ -2167,9 +2167,18 @@ async fn handle_a_tag_deletion(
             };
             // Safe cast: NIP-33 kinds are 30000–39999, well within i32.
             let kind_i32 = k as i32;
+            // NIP-09 scopes an a-tag deletion to versions at or before the
+            // deletion's own created_at, so a stale/replayed tombstone can never
+            // erase a newer replacement head.
             let deleted = state
                 .db
-                .soft_delete_by_coordinate(tenant.community(), kind_i32, &pubkey_bytes, d_tag)
+                .soft_delete_by_coordinate(
+                    tenant.community(),
+                    kind_i32,
+                    &pubkey_bytes,
+                    d_tag,
+                    event.created_at.as_secs() as i64,
+                )
                 .await
                 .map_err(|e| {
                     anyhow::anyhow!(
diff --git a/crates/buzz-relay/src/main.rs b/crates/buzz-relay/src/main.rs
index 3ed820d3c5..799cf9cf60 100644
--- a/crates/buzz-relay/src/main.rs
+++ b/crates/buzz-relay/src/main.rs
@@ -102,6 +102,7 @@ async fn main() -> anyhow::Result<()> {
     // spans under the correct service identity.
     let resource = telemetry::service_resource();
     let tracer_init = telemetry::try_init_tracer(resource.clone());
+    let otel_enabled = matches!(&tracer_init, telemetry::TracerInit::Enabled(_));
     let otel_layer = match &tracer_init {
         telemetry::TracerInit::Enabled(p) => {
             use opentelemetry::trace::TracerProvider as _;
@@ -109,12 +110,18 @@ async fn main() -> anyhow::Result<()> {
         }
         _ => None,
     };
+    let trace_context_lookup = telemetry::TraceContextLookup::default();
+    let trace_context_lookup_layer = otel_enabled.then(|| {
+        trace_context_lookup
+            .clone()
+            .with_filter(tracing_subscriber::filter::LevelFilter::OFF)
+    });
 
     tracing_subscriber::registry()
         .with(
             fmt::layer()
                 .json()
-                .flatten_event(true)
+                .event_format(trace_context_lookup.json_formatter(otel_enabled))
                 .with_filter(log_env_filter(std::env::var("RUST_LOG").ok().as_deref())),
         )
         .with(otel_layer.map(|layer| {
@@ -122,6 +129,7 @@ async fn main() -> anyhow::Result<()> {
                 std::env::var("BUZZ_OTEL_FILTER").ok().as_deref(),
             ))
         }))
+        .with(trace_context_lookup_layer)
         .init();
 
     // Log any exporter-build failure now that the subscriber is installed.
@@ -158,7 +166,9 @@ async fn main() -> anyhow::Result<()> {
     let db_config = DbConfig {
         database_url: config.database_url.clone(),
         read_database_url: config.read_database_url.clone(),
+        replica_read_max_age_ms: config.replica_read_max_age_ms,
         max_connections: config.db_pool_size,
+        read_max_connections: config.db_read_pool_size,
         ..DbConfig::default()
     };
     let db = Db::new(&db_config).await.map_err(|e| {
@@ -166,7 +176,11 @@ async fn main() -> anyhow::Result<()> {
         anyhow::anyhow!("DB connection failed: {e}")
     })?;
     if db.has_read_pool() {
-        info!("Postgres connected (writer + read replica)");
+        info!("Postgres connected (writer + lazy read replica pool)");
+        // Reader-down at boot must not crash or block the relay; this warn-only
+        // ping is the sole boot-time visibility that the replica is unreachable
+        // (the lazy pool with min_connections=0 dials nothing until first use).
+        db.spawn_read_pool_boot_ping();
     } else {
         info!("Postgres connected");
     }
@@ -991,6 +1005,12 @@ async fn main() -> anyhow::Result<()> {
                             metrics::gauge!("buzz_db_replica_fence_open").set(0.0);
                         }
                     }
+                    // Probe liveness, ungated by staleness: how long since
+                    // the probe last committed a heartbeat token.
+                    if let Some(age) = pool_state.db.fence().heartbeat_age() {
+                        metrics::gauge!("buzz_db_replica_heartbeat_age_seconds")
+                            .set(age.as_secs_f64());
+                    }
                 }
 
                 let rs = pool_state.redis_pool.status();
diff --git a/crates/buzz-relay/src/nip11.rs b/crates/buzz-relay/src/nip11.rs
index a8e397dd21..2575ddd7ba 100644
--- a/crates/buzz-relay/src/nip11.rs
+++ b/crates/buzz-relay/src/nip11.rs
@@ -89,6 +89,11 @@ pub struct RelayLimitation {
 
 /// Canonical `RelayLimitation` advertised by this relay.
 ///
+/// `max_limit` is [`buzz_db::DEFAULT_MAX_PAGE_LIMIT`], the same constant the
+/// REQ path clamps filter limits to, so the advertised ceiling and the
+/// enforced one cannot drift (see
+/// `handlers::req::tests::req_filter_limit_clamps_to_advertised_nip11_max_limit`).
+///
 /// `auth_required` is always `true`: the REQ, EVENT, and COUNT handlers
 /// unconditionally reject connections that are not in
 /// `AuthState::Authenticated`. This is independent of the REST API token
@@ -103,7 +108,7 @@ fn relay_limitation(max_message_length: usize) -> RelayLimitation {
         max_message_length: Some(max_message_length as u64),
         max_subscriptions: Some(1024),
         max_filters: Some(10),
-        max_limit: Some(10_000),
+        max_limit: Some(buzz_db::DEFAULT_MAX_PAGE_LIMIT as u32),
         max_subid_length: Some(256),
         min_pow_difficulty: None,
         auth_required: true,
diff --git a/crates/buzz-relay/src/state.rs b/crates/buzz-relay/src/state.rs
index 758c001b96..58a869a995 100644
--- a/crates/buzz-relay/src/state.rs
+++ b/crates/buzz-relay/src/state.rs
@@ -697,6 +697,7 @@ impl AppState {
             &config.media.s3_secret_key,
             &config.media.s3_bucket,
             &config.media.s3_region,
+            config.media.s3_addressing_style,
         )
         .expect("media storage was already constructed with this S3 config");
         let git_pack_cache = Arc::new(
diff --git a/crates/buzz-relay/src/telemetry.rs b/crates/buzz-relay/src/telemetry.rs
index 11c6d03512..91bd92f0f3 100644
--- a/crates/buzz-relay/src/telemetry.rs
+++ b/crates/buzz-relay/src/telemetry.rs
@@ -23,9 +23,157 @@
 //! - `OTEL_TRACES_SAMPLER` (default: `parentbased_always_on`)
 //! - `OTEL_TRACES_SAMPLER_ARG`
 
+use std::{
+    fmt,
+    sync::{Arc, OnceLock},
+};
+
+use opentelemetry::trace::{SpanId, TraceContextExt as _, TraceId};
 use opentelemetry_otlp::ExporterBuildError;
 use opentelemetry_sdk::{resource::EnvResourceDetector, trace::SdkTracerProvider, Resource};
-use tracing_subscriber::EnvFilter;
+use tracing::{Event, Subscriber};
+use tracing_subscriber::{
+    fmt::{
+        format::{Format, FormatEvent, FormatFields, Json, Writer},
+        FmtContext,
+    },
+    registry::LookupSpan,
+    EnvFilter, Layer,
+};
+
+/// Captures the subscriber dispatch used to resolve tracing span IDs to their
+/// OpenTelemetry contexts.
+#[derive(Clone, Default)]
+pub struct TraceContextLookup {
+    dispatch: Arc<OnceLock<tracing::dispatcher::WeakDispatch>>,
+}
+
+impl TraceContextLookup {
+    /// Build a JSON formatter backed by this subscriber dispatch lookup.
+    pub fn json_formatter(&self, enabled: bool) -> TraceContextJson {
+        TraceContextJson {
+            inner: tracing_subscriber::fmt::format().json().flatten_event(true),
+            enabled,
+            context_lookup: self.clone(),
+        }
+    }
+
+    fn nearest_otel_context(&self, span_id: &tracing::span::Id) -> Option<opentelemetry::Context> {
+        let dispatch = self.dispatch.get()?.upgrade()?;
+        let registry = dispatch.downcast_ref::<tracing_subscriber::Registry>()?;
+
+        let context = registry.span(span_id)?.scope().find_map(|span| {
+            let context = tracing_opentelemetry::get_otel_context(&span.id(), &dispatch)?;
+            context.span().span_context().is_valid().then_some(context)
+        });
+        context
+    }
+}
+
+impl<S: Subscriber> Layer<S> for TraceContextLookup {
+    fn on_register_dispatch(&self, subscriber: &tracing::Dispatch) {
+        let _ = self.dispatch.set(subscriber.downgrade());
+    }
+}
+
+/// JSON event formatter that adds the active OpenTelemetry trace context.
+///
+/// Datadog recognizes the OpenTelemetry-standard `trace_id` and `span_id`
+/// fields when they are lowercase hexadecimal strings. Events outside a valid
+/// OpenTelemetry span retain the standard `tracing-subscriber` JSON format.
+pub struct TraceContextJson {
+    inner: Format<Json>,
+    enabled: bool,
+    context_lookup: TraceContextLookup,
+}
+
+struct CorrelationWriter<'writer> {
+    inner: Writer<'writer>,
+    trace_id: TraceId,
+    span_id: SpanId,
+    injected: bool,
+}
+
+impl fmt::Write for CorrelationWriter<'_> {
+    fn write_str(&mut self, value: &str) -> fmt::Result {
+        if self.injected {
+            return self.inner.write_str(value);
+        }
+
+        let Some(object_start) = value.find('{') else {
+            return self.inner.write_str(value);
+        };
+        self.inner.write_str(&value[..=object_start])?;
+        write!(
+            self.inner,
+            "\"trace_id\":\"{}\",\"span_id\":\"{}\",",
+            self.trace_id, self.span_id
+        )?;
+        self.injected = true;
+        self.inner.write_str(&value[object_start + 1..])
+    }
+}
+
+impl<S, N> FormatEvent<S, N> for TraceContextJson
+where
+    S: Subscriber + for<'lookup> LookupSpan<'lookup>,
+    N: for<'writer> FormatFields<'writer> + 'static,
+{
+    fn format_event(
+        &self,
+        ctx: &FmtContext<'_, S, N>,
+        mut writer: Writer<'_>,
+        event: &Event<'_>,
+    ) -> fmt::Result {
+        if !self.enabled {
+            return self.inner.format_event(ctx, writer, event);
+        }
+
+        let otel_context = match event.parent() {
+            Some(span_id) => self.context_lookup.nearest_otel_context(span_id),
+            None if event.is_contextual() => Some(opentelemetry::Context::current()),
+            None => None,
+        };
+        let Some(otel_context) = otel_context else {
+            return self.inner.format_event(ctx, writer, event);
+        };
+        let otel_span = otel_context.span();
+        let span_context = otel_span.span_context();
+
+        if !span_context.is_valid() {
+            return self.inner.format_event(ctx, writer, event);
+        }
+
+        let trace_id = span_context.trace_id();
+        let span_id = span_context.span_id();
+
+        // Events may define fields with the correlation names themselves. In
+        // that uncommon case, overwrite them rather than emitting duplicate
+        // JSON keys. Preserve the allocation-free streaming path for ordinary
+        // events.
+        let fields = event.metadata().fields();
+        if fields.field("trace_id").is_some() || fields.field("span_id").is_some() {
+            let mut json = String::new();
+            self.inner
+                .format_event(ctx, Writer::new(&mut json), event)?;
+            let mut object: serde_json::Map<String, serde_json::Value> =
+                serde_json::from_str(json.trim_end()).map_err(|_| fmt::Error)?;
+            object.insert("trace_id".into(), trace_id.to_string().into());
+            object.insert("span_id".into(), span_id.to_string().into());
+            writer.write_str(&serde_json::to_string(&object).map_err(|_| fmt::Error)?)?;
+            return writeln!(writer);
+        }
+
+        let mut writer = CorrelationWriter {
+            inner: writer,
+            trace_id,
+            span_id,
+            injected: false,
+        };
+        self.inner
+            .format_event(ctx, Writer::new(&mut writer), event)
+    }
+}
 
 /// Build the filter for spans exported through OpenTelemetry.
 ///
@@ -122,8 +270,13 @@ fn classify_exporter_result(
 #[cfg(test)]
 mod tests {
     use super::*;
-    use opentelemetry::KeyValue;
-    use std::sync::Mutex;
+    use opentelemetry::{trace::TracerProvider as _, KeyValue};
+    use opentelemetry_sdk::trace::InMemorySpanExporter;
+    use std::{
+        io,
+        sync::{Arc, Mutex},
+    };
+    use tracing_subscriber::prelude::*;
 
     // Env vars are process-global — serialize tests that mutate them to prevent
     // cross-test races when the suite runs with multiple threads.
@@ -137,6 +290,209 @@ mod tests {
             .map(|(_, v)| v.to_string())
     }
 
+    #[derive(Clone)]
+    struct CapturingWriter(Arc<Mutex<Vec<u8>>>);
+
+    impl io::Write for CapturingWriter {
+        fn write(&mut self, bytes: &[u8]) -> io::Result<usize> {
+            self.0.lock().unwrap().extend_from_slice(bytes);
+            Ok(bytes.len())
+        }
+
+        fn flush(&mut self) -> io::Result<()> {
+            Ok(())
+        }
+    }
+
+    #[test]
+    fn trace_context_json_correlates_nested_span_logs() {
+        let output = Arc::new(Mutex::new(Vec::new()));
+        let output_writer = Arc::clone(&output);
+        let exporter = InMemorySpanExporter::default();
+        let provider = SdkTracerProvider::builder()
+            .with_simple_exporter(exporter.clone())
+            .build();
+        let tracer = provider.tracer("trace-context-json-test");
+        let context_lookup = TraceContextLookup::default();
+
+        let subscriber = tracing_subscriber::registry()
+            .with(
+                tracing_subscriber::fmt::layer()
+                    .json()
+                    .event_format(context_lookup.json_formatter(true))
+                    .with_writer(move || CapturingWriter(Arc::clone(&output_writer)))
+                    .with_filter(tracing_subscriber::filter::filter_fn(|metadata| {
+                        metadata.target() != "stdout_filtered"
+                    })),
+            )
+            .with(
+                tracing_opentelemetry::layer()
+                    .with_tracer(tracer)
+                    .with_filter(tracing_subscriber::filter::filter_fn(|metadata| {
+                        !matches!(metadata.target(), "filtered" | "otel_event_filtered")
+                    })),
+            )
+            .with(
+                context_lookup
+                    .clone()
+                    .with_filter(tracing_subscriber::filter::LevelFilter::OFF),
+            );
+
+        tracing::subscriber::with_default(subscriber, || {
+            let explicit = tracing::info_span!("explicit");
+            let root = tracing::info_span!("root");
+            root.in_scope(|| {
+                tracing::info!(answer = 42, "root event");
+                tracing::info!(
+                    trace_id = "event-provided-trace",
+                    span_id = "event-provided-span",
+                    "colliding-fields event"
+                );
+                tracing::info!(parent: &explicit, "explicit-parent event");
+                tracing::info!(parent: None, "explicit-root event");
+                let child = tracing::info_span!("child");
+                child.in_scope(|| tracing::info!("child event"));
+
+                let filtered_child = tracing::info_span!(target: "filtered", "filtered-child");
+                filtered_child.in_scope(|| tracing::info!("filtered-child event"));
+                tracing::info!(
+                    parent: &filtered_child,
+                    "explicit-filtered-child event"
+                );
+
+                let stdout_filtered_child =
+                    tracing::info_span!(target: "stdout_filtered", "stdout-filtered-child");
+                stdout_filtered_child.in_scope(|| tracing::info!("stdout-filtered-child event"));
+
+                tracing::info!(target: "otel_event_filtered", "otel-filtered event");
+            });
+            let filtered = tracing::info_span!(target: "filtered", "filtered");
+            filtered.in_scope(|| tracing::info!("filtered-span event"));
+            tracing::info!("unscoped event");
+        });
+
+        provider.force_flush().unwrap();
+        let spans = exporter.get_finished_spans().unwrap();
+        let root = spans.iter().find(|span| span.name == "root").unwrap();
+        let explicit = spans.iter().find(|span| span.name == "explicit").unwrap();
+        let child = spans.iter().find(|span| span.name == "child").unwrap();
+        let stdout_filtered_child = spans
+            .iter()
+            .find(|span| span.name == "stdout-filtered-child")
+            .unwrap();
+
+        let bytes = output.lock().unwrap().clone();
+        let output = String::from_utf8(bytes).unwrap();
+        let lines: Vec<&str> = output.lines().collect();
+        let logs: Vec<serde_json::Value> = lines
+            .iter()
+            .map(|line| serde_json::from_str(line).unwrap())
+            .collect();
+        assert_eq!(logs.len(), 11);
+
+        assert_eq!(logs[0]["message"], "root event");
+        assert_eq!(logs[0]["answer"], 42);
+        assert_eq!(
+            logs[0]["trace_id"],
+            root.span_context.trace_id().to_string()
+        );
+        assert_eq!(logs[0]["span_id"], root.span_context.span_id().to_string());
+        assert_eq!(logs[0]["trace_id"].as_str().unwrap().len(), 32);
+        assert_eq!(logs[0]["span_id"].as_str().unwrap().len(), 16);
+
+        assert_eq!(logs[1]["message"], "colliding-fields event");
+        assert_eq!(
+            logs[1]["trace_id"],
+            root.span_context.trace_id().to_string()
+        );
+        assert_eq!(logs[1]["span_id"], root.span_context.span_id().to_string());
+        assert_eq!(lines[1].matches("\"trace_id\":").count(), 1);
+        assert_eq!(lines[1].matches("\"span_id\":").count(), 1);
+
+        assert_eq!(logs[2]["message"], "explicit-parent event");
+        assert_eq!(
+            logs[2]["trace_id"],
+            explicit.span_context.trace_id().to_string()
+        );
+        assert_eq!(
+            logs[2]["span_id"],
+            explicit.span_context.span_id().to_string()
+        );
+
+        assert_eq!(logs[3]["message"], "explicit-root event");
+        assert!(logs[3].get("trace_id").is_none());
+        assert!(logs[3].get("span_id").is_none());
+
+        assert_eq!(logs[4]["message"], "child event");
+        assert_eq!(
+            logs[4]["trace_id"],
+            child.span_context.trace_id().to_string()
+        );
+        assert_eq!(logs[4]["span_id"], child.span_context.span_id().to_string());
+        assert_eq!(logs[0]["trace_id"], logs[4]["trace_id"]);
+
+        assert_eq!(logs[5]["message"], "filtered-child event");
+        assert_eq!(
+            logs[5]["trace_id"],
+            root.span_context.trace_id().to_string()
+        );
+        assert_eq!(logs[5]["span_id"], root.span_context.span_id().to_string());
+
+        assert_eq!(logs[6]["message"], "explicit-filtered-child event");
+        assert_eq!(
+            logs[6]["trace_id"],
+            root.span_context.trace_id().to_string()
+        );
+        assert_eq!(logs[6]["span_id"], root.span_context.span_id().to_string());
+
+        assert_eq!(logs[7]["message"], "stdout-filtered-child event");
+        assert_eq!(
+            logs[7]["trace_id"],
+            stdout_filtered_child.span_context.trace_id().to_string()
+        );
+        assert_eq!(
+            logs[7]["span_id"],
+            stdout_filtered_child.span_context.span_id().to_string()
+        );
+
+        assert_eq!(logs[8]["message"], "otel-filtered event");
+        assert_eq!(
+            logs[8]["trace_id"],
+            root.span_context.trace_id().to_string()
+        );
+        assert_eq!(logs[8]["span_id"], root.span_context.span_id().to_string());
+
+        assert_eq!(logs[9]["message"], "filtered-span event");
+        assert!(logs[9].get("trace_id").is_none());
+        assert!(logs[9].get("span_id").is_none());
+
+        assert_eq!(logs[10]["message"], "unscoped event");
+        assert!(logs[10].get("trace_id").is_none());
+        assert!(logs[10].get("span_id").is_none());
+    }
+
+    #[test]
+    fn trace_context_lookup_does_not_enable_callsites() {
+        let context_lookup = TraceContextLookup::default();
+        let subscriber = tracing_subscriber::registry().with(
+            context_lookup
+                .clone()
+                .with_filter(tracing_subscriber::filter::LevelFilter::OFF),
+        );
+
+        tracing::subscriber::with_default(subscriber, || {
+            assert!(context_lookup
+                .dispatch
+                .get()
+                .and_then(tracing::dispatcher::WeakDispatch::upgrade)
+                .is_some());
+            assert!(!tracing::enabled!(
+                target: "trace_context_lookup_filter_test",
+                tracing::Level::ERROR
+            ));
+        });
+    }
+
     #[test]
     fn test_service_resource_default_when_env_unset() {
         let _guard = ENV_LOCK.lock().unwrap();
diff --git a/crates/buzz-sdk/src/builders.rs b/crates/buzz-sdk/src/builders.rs
index 8cc9c8650a..9a139f0377 100644
--- a/crates/buzz-sdk/src/builders.rs
+++ b/crates/buzz-sdk/src/builders.rs
@@ -11,8 +11,8 @@ use buzz_core::{
         KIND_GIT_STATUS_CLOSED, KIND_GIT_STATUS_DRAFT, KIND_GIT_STATUS_MERGED,
         KIND_GIT_STATUS_OPEN, KIND_IA_ARCHIVE_REQUEST, KIND_IA_UNARCHIVE_REQUEST,
         KIND_MODERATION_BAN, KIND_MODERATION_RESOLVE_REPORT, KIND_MODERATION_TIMEOUT,
-        KIND_MODERATION_UNBAN, KIND_MODERATION_UNTIMEOUT, KIND_PRESENCE_UPDATE, KIND_USER_STATUS,
-        KIND_WORKFLOW_DEF, KIND_WORKFLOW_TRIGGER,
+        KIND_MODERATION_UNBAN, KIND_MODERATION_UNTIMEOUT, KIND_PRESENCE_UPDATE, KIND_PROJECT,
+        KIND_USER_STATUS, KIND_WORKFLOW_DEF, KIND_WORKFLOW_TRIGGER,
     },
     observer::{
         content_looks_like_nip44, OBSERVER_AGENT_TAG, OBSERVER_FRAME_CONTROL, OBSERVER_FRAME_TAG,
@@ -1499,12 +1499,7 @@ pub fn build_workflow_delete(
     author_pubkey: &str,
     workflow_id: Uuid,
 ) -> Result<EventBuilder, SdkError> {
-    let pk = check_pubkey_hex(author_pubkey, "author_pubkey")?;
-    let tags = vec![tag(&[
-        "a",
-        &format!("{}:{pk}:{workflow_id}", KIND_WORKFLOW_DEF),
-    ])?];
-    Ok(EventBuilder::new(Kind::Custom(KIND_DELETION as u16), "").tags(tags))
+    build_delete_addressable(KIND_WORKFLOW_DEF, author_pubkey, &workflow_id.to_string())
 }
 
 /// Build a workflow trigger event (kind 46020).
@@ -1838,6 +1833,364 @@ pub fn build_unarchive_identity_request(
     )
 }
 
+// ─── NIP-MP: Multi-repo projects (kind:30621) ────────────────────────────────
+//
+//  Public surface:
+//  • `validate_project_envelope` — Layer A protocol validator (8 ingest rules)
+//  • `build_project_with_tags`   — Layer A raw builder (content + tags, no canonicalization)
+//  • `ProjectMemberCoord`        — parsed member coordinate + optional relay hint
+//  • `build_project`             — Layer B writer-policy builder
+//  • `build_delete_addressable`  — generic NIP-09 kind:5 coordinate delete
+//
+//  Byte-length bounds from NIP-MP §Relay Processing:
+/// Maximum byte length of a project `d` tag value.
+pub const PROJECT_D_MAX_LEN: usize = 1024;
+/// Maximum byte length of a project `name` tag value.
+pub const PROJECT_NAME_MAX: usize = 256;
+/// Maximum byte length of a project `description` tag value.
+pub const PROJECT_DESCRIPTION_MAX: usize = 2048;
+/// Maximum byte length of a project `buzz-channel` tag value.
+pub const PROJECT_CHANNEL_MAX: usize = 256;
+/// Maximum byte length of a project `buzz-visibility` tag value.
+pub const PROJECT_VISIBILITY_MAX: usize = 256;
+/// Maximum number of `a` member tags per project event (checked before dedup).
+pub const PROJECT_MEMBER_CAP: usize = 64;
+
+/// A validated NIP-MP member `a`-tag coordinate with an optional relay hint.
+///
+/// Equality and `Hash` are by `coord` only (per spec: duplicate detection ignores hint).
+#[derive(Clone, Debug)]
+pub struct ProjectMemberCoord {
+    /// The full `30617:<owner-hex>:<repo-d>` coordinate string.
+    pub coord: String,
+    /// Optional opaque relay hint (third `a`-tag element, never validated by content).
+    pub hint: Option<String>,
+}
+
+impl PartialEq for ProjectMemberCoord {
+    fn eq(&self, other: &Self) -> bool {
+        self.coord == other.coord
+    }
+}
+
+impl Eq for ProjectMemberCoord {}
+
+impl std::hash::Hash for ProjectMemberCoord {
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        self.coord.hash(state);
+    }
+}
+
+impl ProjectMemberCoord {
+    /// Parse a full `30617:<owner-hex>:<repo-d>` coordinate string.
+    ///
+    /// Accepts an optional relay hint as the third colon-separated element
+    /// after the split, but the split is always first-two-colons: kind, owner,
+    /// everything-else-as-repo-d.
+    ///
+    /// Rules enforced:
+    /// - Exactly three segments after splitting on the first two colons
+    /// - First segment must be the literal string `"30617"`
+    /// - Second segment must be exactly 64 lowercase hex characters
+    /// - Third segment (repo-d) must be non-empty
+    /// - Uppercase owners are rejected (never normalized)
+    pub fn parse_full(coord: &str) -> Result<Self, SdkError> {
+        // Split on first two colons only: kind:owner:rest
+        let mut parts = coord.splitn(3, ':');
+        let kind_part = parts.next().unwrap_or("");
+        let owner_part = parts.next().unwrap_or("");
+        let rest = parts.next().unwrap_or("");
+
+        if kind_part != "30617" {
+            return Err(SdkError::InvalidInput(format!(
+                "member coordinate must start with '30617:' (got kind {kind_part:?})"
+            )));
+        }
+        if owner_part.len() != 64 || !owner_part.chars().all(|c| c.is_ascii_hexdigit()) {
+            return Err(SdkError::InvalidInput(format!(
+                "member owner must be a 64-character hex pubkey (got {owner_part:?})"
+            )));
+        }
+        // Reject uppercase (spec: lowercase hex required)
+        if owner_part.chars().any(|c| c.is_ascii_uppercase()) {
+            return Err(SdkError::InvalidInput(
+                "member owner hex must be lowercase".into(),
+            ));
+        }
+        if rest.is_empty() {
+            return Err(SdkError::InvalidInput(
+                "member coordinate repo-d must not be empty".into(),
+            ));
+        }
+        Ok(ProjectMemberCoord {
+            coord: format!("30617:{owner_part}:{rest}"),
+            hint: None,
+        })
+    }
+
+    /// Returns the `a`-tag element slice: `[coord]` or `[coord, hint]`.
+    pub fn to_tag_parts(&self) -> Vec<String> {
+        let mut parts = vec!["a".to_string(), self.coord.clone()];
+        if let Some(h) = &self.hint {
+            parts.push(h.clone());
+        }
+        parts
+    }
+}
+
+/// **Layer A**: Validate a complete kind:30621 envelope against the 8 NIP-MP
+/// ingest rules.  This is the single source of protocol truth used by both
+/// `build_project_with_tags` (raw path) and `build_project` (policy path).
+///
+/// Rules enforced (matches relay `buzz-db` ingest logic):
+/// 1. `d` cardinality: exactly one `d` tag.
+/// 2. `d` value: non-empty, ≤1024 bytes.
+/// 3. Member cap: raw count of every `a` tag ≤ 64 (checked **before** per-tag
+///    parsing, matching relay rule order).
+/// 4. Member tag arity: every `a` tag has 2 or 3 elements (no more, no fewer).
+/// 5. Member coordinate grammar: first-two-colons split; kind literal `"30617"`;
+///    owner lowercase 64-hex; repo-d non-empty verbatim.
+/// 6. Member deduplication: coordinate equality only (hint ignored); any
+///    coordinate that appears more than once is a duplicate.
+/// 7. Singleton metadata: each of `name`, `description`, `buzz-channel`,
+///    `buzz-visibility` appears at most once.
+/// 8. Metadata byte lengths: `name` ≤256, `description` ≤2048,
+///    `buzz-channel` ≤256, `buzz-visibility` ≤256.
+pub fn validate_project_envelope(tags: &[Tag], _content: &str) -> Result<(), SdkError> {
+    // --- Rule 1 & 2: d tag ---
+    let d_tags: Vec<&Tag> = tags.iter().filter(|t| tag_name(t) == Some("d")).collect();
+    match d_tags.len() {
+        0 => {
+            return Err(SdkError::InvalidInput(
+                "project must have exactly one 'd' tag (rule: d-cardinality)".into(),
+            ))
+        }
+        1 => {}
+        _ => {
+            return Err(SdkError::InvalidInput(
+                "project must have exactly one 'd' tag (rule: d-cardinality)".into(),
+            ))
+        }
+    }
+    let d_val = tag_value(d_tags[0]).unwrap_or("");
+    if d_val.is_empty() {
+        return Err(SdkError::InvalidInput(
+            "project 'd' tag must not be empty (rule: d-empty)".into(),
+        ));
+    }
+    if d_val.len() > PROJECT_D_MAX_LEN {
+        return Err(SdkError::InvalidInput(format!(
+            "project 'd' tag exceeds {PROJECT_D_MAX_LEN} bytes (rule: d-empty)"
+        )));
+    }
+
+    let a_tags: Vec<&Tag> = tags.iter().filter(|t| tag_name(t) == Some("a")).collect();
+
+    // --- Rule 3: member cap (checked before per-tag parsing, matching relay rule order) ---
+    if a_tags.len() > PROJECT_MEMBER_CAP {
+        return Err(SdkError::InvalidInput(format!(
+            "project exceeds member cap of {PROJECT_MEMBER_CAP} (got {}) (rule: member-cap)",
+            a_tags.len()
+        )));
+    }
+
+    // --- Rule 4: member arity ---
+    for a in &a_tags {
+        let len = a.as_slice().len() - 1; // exclude the "a" name element
+        if !(1..=2).contains(&len) {
+            return Err(SdkError::InvalidInput(format!(
+                "member 'a' tag must have 1 or 2 value elements (got {len}) (rule: member-tag-arity)"
+            )));
+        }
+    }
+
+    // --- Rules 5 & 6: coordinate grammar + deduplication ---
+    let mut seen_coords: std::collections::HashSet<String> = std::collections::HashSet::new();
+    for a in &a_tags {
+        let coord_val = tag_value(a).unwrap_or("");
+        ProjectMemberCoord::parse_full(coord_val).map_err(|e| {
+            SdkError::InvalidInput(format!("{e} (rule: member-coordinate-malformed)"))
+        })?;
+        if !seen_coords.insert(coord_val.to_string()) {
+            return Err(SdkError::InvalidInput(format!(
+                "duplicate member coordinate {coord_val:?} (rule: member-duplicate)"
+            )));
+        }
+    }
+
+    // --- Rules 7 & 8: singleton metadata + byte bounds ---
+    let singleton_fields = [
+        (
+            "name",
+            PROJECT_NAME_MAX,
+            "metadata-cardinality",
+            "metadata-length",
+        ),
+        (
+            "description",
+            PROJECT_DESCRIPTION_MAX,
+            "metadata-cardinality",
+            "metadata-length",
+        ),
+        (
+            "buzz-channel",
+            PROJECT_CHANNEL_MAX,
+            "metadata-cardinality",
+            "metadata-length",
+        ),
+        (
+            "buzz-visibility",
+            PROJECT_VISIBILITY_MAX,
+            "metadata-cardinality",
+            "metadata-length",
+        ),
+    ];
+    for (field, max_bytes, card_rule, len_rule) in singleton_fields {
+        let matches: Vec<&Tag> = tags.iter().filter(|t| tag_name(t) == Some(field)).collect();
+        if matches.len() > 1 {
+            return Err(SdkError::InvalidInput(format!(
+                "project must have at most one '{field}' tag (rule: {card_rule})"
+            )));
+        }
+        if let Some(t) = matches.first() {
+            let val = tag_value(t).unwrap_or("");
+            if val.len() > max_bytes {
+                return Err(SdkError::InvalidInput(format!(
+                    "'{field}' tag exceeds {max_bytes} bytes (rule: {len_rule})"
+                )));
+            }
+        }
+    }
+
+    Ok(())
+}
+
+/// Helper: tag name (first element).
+fn tag_name(tag: &Tag) -> Option<&str> {
+    tag.as_slice().first().map(String::as_str)
+}
+
+/// Helper: tag value (second element).
+fn tag_value(tag: &Tag) -> Option<&str> {
+    tag.as_slice().get(1).map(String::as_str)
+}
+
+/// **Layer A raw builder**: Build a kind:30621 project event from a raw
+/// `content` string and a raw `tags` slice, without any canonicalization.
+///
+/// Validates the entire envelope through `validate_project_envelope` before
+/// accepting it.  The caller is responsible for supplying the correct `d` tag.
+/// This is the path exercised by fixture conformance tests and by read-modify-
+/// write mutations in the CLI.
+pub fn build_project_with_tags(content: &str, tags: Vec<Tag>) -> Result<EventBuilder, SdkError> {
+    validate_project_envelope(&tags, content)?;
+    Ok(EventBuilder::new(Kind::Custom(KIND_PROJECT as u16), content).tags(tags))
+}
+
+/// **Layer B writer-policy builder**: Build a kind:30621 project event with
+/// enforced writer policy:
+/// - The `d` tag is constructed from `slug`; `check_project_slug` rejects
+///   an empty or over-length slug.
+/// - `channel` must be a valid UUID string.
+/// - `visibility` must be `"listed"` or `"unlisted"`.
+/// - Content is always empty.
+/// - Member coordinates are parsed through `ProjectMemberCoord::parse_full`.
+///
+/// The resulting envelope is validated through Layer A before the builder is
+/// returned.
+pub fn build_project(
+    slug: &str,
+    name: Option<&str>,
+    description: Option<&str>,
+    members: &[ProjectMemberCoord],
+    channel: Option<&str>,
+    visibility: Option<&str>,
+) -> Result<EventBuilder, SdkError> {
+    // Slug validation
+    if slug.is_empty() {
+        return Err(SdkError::InvalidInput(
+            "project slug must not be empty".into(),
+        ));
+    }
+    if slug.len() > PROJECT_D_MAX_LEN {
+        return Err(SdkError::InvalidInput(format!(
+            "project slug must not exceed {PROJECT_D_MAX_LEN} bytes (got {})",
+            slug.len()
+        )));
+    }
+
+    // Channel UUID validation
+    if let Some(ch) = channel {
+        uuid::Uuid::parse_str(ch).map_err(|_| {
+            SdkError::InvalidInput(format!("buzz-channel must be a valid UUID (got {ch:?})"))
+        })?;
+    }
+
+    // Visibility enum validation
+    if let Some(vis) = visibility {
+        if vis != "listed" && vis != "unlisted" {
+            return Err(SdkError::InvalidInput(format!(
+                "buzz-visibility must be 'listed' or 'unlisted' (got {vis:?})"
+            )));
+        }
+    }
+
+    let mut tags: Vec<Tag> = Vec::new();
+    tags.push(tag(&["d", slug])?);
+
+    if let Some(n) = name {
+        tags.push(tag(&["name", n])?);
+    }
+    if let Some(d) = description {
+        tags.push(tag(&["description", d])?);
+    }
+    for m in members {
+        let tag_parts = m.to_tag_parts();
+        let parts: Vec<&str> = tag_parts.iter().map(|s| s.as_str()).collect();
+        // Safety: to_tag_parts always produces ["a", coord, ...hint]
+        tags.push(
+            Tag::parse(parts.iter().copied()).map_err(|e| SdkError::InvalidTag(e.to_string()))?,
+        );
+    }
+    if let Some(ch) = channel {
+        tags.push(tag(&["buzz-channel", ch])?);
+    }
+    if let Some(vis) = visibility {
+        tags.push(tag(&["buzz-visibility", vis])?);
+    }
+
+    build_project_with_tags("", tags)
+}
+
+/// **Generic NIP-09 coordinate delete**: Build a kind:5 deletion event with
+/// a single `a`-tag addressing `<kind>:<pubkey>:<d>`.
+///
+/// Validates:
+/// - `kind` is an addressable kind (10000–19999 or 30000–39999).
+/// - `pubkey` is a 64-character lowercase hex string.
+/// - `d` is non-empty.
+///
+/// `build_workflow_delete` delegates to this function.
+pub fn build_delete_addressable(
+    kind: u32,
+    pubkey: &str,
+    d: &str,
+) -> Result<EventBuilder, SdkError> {
+    let is_addressable = (10000..20000).contains(&kind) || (30000..40000).contains(&kind);
+    if !is_addressable {
+        return Err(SdkError::InvalidInput(format!(
+            "kind {kind} is not an addressable kind (must be 10000–19999 or 30000–39999)"
+        )));
+    }
+    let pk = check_pubkey_hex(pubkey, "pubkey")?;
+    if d.is_empty() {
+        return Err(SdkError::InvalidInput("d must not be empty".into()));
+    }
+    let coord = format!("{kind}:{pk}:{d}");
+    let tags = vec![tag(&["a", &coord])?];
+    Ok(EventBuilder::new(Kind::Custom(KIND_DELETION as u16), "").tags(tags))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -3884,4 +4237,280 @@ mod tests {
             .iter()
             .any(|t| t.as_slice().first().map(String::as_str) == Some("replaced-by")));
     }
+
+    // ── NIP-MP cap-before-arity ordering ─────────────────────────────────────
+
+    /// When an envelope exceeds the member cap AND contains a malformed `a` tag,
+    /// the validator must fire `member-cap` (rule 3) — not `member-tag-arity`
+    /// (rule 4).  This matches the relay's ingest ordering and means a client
+    /// sending an oversized list never receives a per-tag parse error.
+    #[test]
+    fn validate_project_envelope_cap_wins_over_arity_when_both_fail() {
+        let owner = "a".repeat(64);
+        // Build 65 well-formed `a` tags — enough to trigger the cap.
+        let mut tags = vec![Tag::parse(["d", "platform"]).unwrap()];
+        for i in 0..65usize {
+            let coord = format!("30617:{owner}:repo-{i}");
+            tags.push(Tag::parse(["a", &coord]).unwrap());
+        }
+        // Also add one malformed tag (four elements) that would fire
+        // member-tag-arity if evaluated before the cap check.
+        let coord_extra = format!("30617:{owner}:repo-extra");
+        tags.push(
+            Tag::parse([
+                "a",
+                &coord_extra,
+                "wss://relay.example.com",
+                "extra-element",
+            ])
+            .unwrap(),
+        );
+
+        let err = validate_project_envelope(&tags, "").unwrap_err();
+        let msg = err.to_string();
+        assert!(
+            msg.contains("member-cap"),
+            "expected member-cap to win, got: {msg}"
+        );
+        assert!(
+            !msg.contains("member-tag-arity"),
+            "arity rule must not fire before cap rule, got: {msg}"
+        );
+    }
+
+    // ── Layer B writer-policy builder ───────────────────────────────────────
+
+    const OWNER64: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+    const VALID_UUID: &str = "3580ca9b-47b4-4af9-b22a-1068778f26c6";
+
+    fn member_coord(repo: &str) -> ProjectMemberCoord {
+        ProjectMemberCoord::parse_full(&format!("30617:{OWNER64}:{repo}")).unwrap()
+    }
+
+    #[test]
+    fn build_project_emitted_envelope_has_correct_shape() {
+        // slug, name, description, channel, visibility, and one member.
+        let m = member_coord("buzz");
+        let ev = sign(
+            build_project(
+                "my-proj",
+                Some("My Project"),
+                Some("A description"),
+                &[m],
+                Some(VALID_UUID),
+                Some("listed"),
+            )
+            .expect("Layer B must accept valid inputs"),
+        );
+
+        // Kind must be 30621.
+        assert_eq!(ev.kind.as_u16(), KIND_PROJECT as u16);
+        // Content must be empty (Layer B policy).
+        assert!(ev.content.is_empty(), "content must be empty");
+
+        let all_tags: Vec<Vec<String>> = ev.tags.iter().map(|t| t.as_slice().to_vec()).collect();
+
+        // d tag must be present exactly once.
+        let d_tags: Vec<_> = all_tags.iter().filter(|t| t[0] == "d").collect();
+        assert_eq!(d_tags.len(), 1);
+        assert_eq!(d_tags[0][1], "my-proj");
+
+        // name, description, buzz-channel, buzz-visibility present.
+        let name_tags: Vec<_> = all_tags.iter().filter(|t| t[0] == "name").collect();
+        assert_eq!(name_tags.len(), 1);
+        assert_eq!(name_tags[0][1], "My Project");
+
+        let desc_tags: Vec<_> = all_tags.iter().filter(|t| t[0] == "description").collect();
+        assert_eq!(desc_tags.len(), 1);
+        assert_eq!(desc_tags[0][1], "A description");
+
+        let ch_tags: Vec<_> = all_tags.iter().filter(|t| t[0] == "buzz-channel").collect();
+        assert_eq!(ch_tags.len(), 1);
+        assert_eq!(ch_tags[0][1], VALID_UUID);
+
+        let vis_tags: Vec<_> = all_tags
+            .iter()
+            .filter(|t| t[0] == "buzz-visibility")
+            .collect();
+        assert_eq!(vis_tags.len(), 1);
+        assert_eq!(vis_tags[0][1], "listed");
+
+        // member a tag.
+        let a_tags: Vec<_> = all_tags.iter().filter(|t| t[0] == "a").collect();
+        assert_eq!(a_tags.len(), 1);
+        assert_eq!(a_tags[0][1], format!("30617:{OWNER64}:buzz"));
+    }
+
+    #[test]
+    fn build_project_optional_fields_absent_when_not_supplied() {
+        let m = member_coord("core");
+        let ev = sign(
+            build_project("my-proj", None, None, &[m], None, None)
+                .expect("minimal build must succeed"),
+        );
+        let names: Vec<_> = ev
+            .tags
+            .iter()
+            .filter(|t| t.as_slice().first().map(|s| s.as_str()) == Some("name"))
+            .collect();
+        assert!(names.is_empty(), "name tag must not be emitted when absent");
+    }
+
+    #[test]
+    fn build_project_rejects_empty_slug() {
+        let m = member_coord("r");
+        let err = build_project("", None, None, &[m], None, None).unwrap_err();
+        assert!(
+            matches!(err, SdkError::InvalidInput(_)),
+            "empty slug must be InvalidInput, got: {err:?}"
+        );
+        assert!(err.to_string().contains("empty"));
+    }
+
+    #[test]
+    fn build_project_rejects_overlong_slug() {
+        let long_slug = "a".repeat(PROJECT_D_MAX_LEN + 1);
+        let m = member_coord("r");
+        let err = build_project(&long_slug, None, None, &[m], None, None).unwrap_err();
+        assert!(matches!(err, SdkError::InvalidInput(_)));
+    }
+
+    #[test]
+    fn build_project_rejects_invalid_channel_uuid() {
+        let m = member_coord("r");
+        let err = build_project("slug", None, None, &[m], Some("not-a-uuid"), None).unwrap_err();
+        assert!(matches!(err, SdkError::InvalidInput(_)));
+        assert!(err.to_string().contains("UUID") || err.to_string().contains("uuid"));
+    }
+
+    #[test]
+    fn build_project_rejects_invalid_visibility_token() {
+        let m = member_coord("r");
+        let err = build_project("slug", None, None, &[m], None, Some("chartreuse")).unwrap_err();
+        assert!(matches!(err, SdkError::InvalidInput(_)));
+        assert!(err.to_string().contains("listed") || err.to_string().contains("unlisted"));
+    }
+
+    #[test]
+    fn build_project_rejects_over_cap_members() {
+        let members: Vec<_> = (0..=PROJECT_MEMBER_CAP)
+            .map(|i| member_coord(&format!("repo-{i}")))
+            .collect();
+        let err = build_project("slug", None, None, &members, None, None).unwrap_err();
+        assert!(matches!(err, SdkError::InvalidInput(_)));
+        assert!(
+            err.to_string().contains("member-cap"),
+            "over-cap must report member-cap, got: {err}"
+        );
+    }
+
+    #[test]
+    fn build_project_rejects_duplicate_members() {
+        let m = member_coord("same");
+        let err = build_project("slug", None, None, &[m.clone(), m], None, None).unwrap_err();
+        assert!(matches!(err, SdkError::InvalidInput(_)));
+        assert!(
+            err.to_string().contains("dedup") || err.to_string().contains("duplicate"),
+            "duplicate member must report dedup, got: {err}"
+        );
+    }
+
+    #[test]
+    fn build_project_content_is_always_empty() {
+        // build_project forces content="" regardless; Layer A also enforces
+        // that the envelope is valid. Any non-empty content would be dropped.
+        // This test pins the Layer B content-forced-empty policy.
+        let m = member_coord("r");
+        let ev = sign(build_project("slug", None, None, &[m], None, None).unwrap());
+        assert!(
+            ev.content.is_empty(),
+            "Layer B must always emit empty content"
+        );
+    }
+
+    // ── NIP-MP conformance fixtures ──────────────────────────────────────────
+    // `build_project_with_tags` directly.  Accept cases must build; reject
+    // cases must fail with an error message containing the expected rule name.
+    // A count assertion guards against silent omissions.
+    //
+    // `include_str!` path is relative to this source file.
+    fn nip_mp_fixture_tags(json_tags: &serde_json::Value) -> Vec<Tag> {
+        json_tags
+            .as_array()
+            .unwrap()
+            .iter()
+            .map(|t| {
+                let parts: Vec<String> = t
+                    .as_array()
+                    .unwrap()
+                    .iter()
+                    .map(|v| v.as_str().unwrap().to_string())
+                    .collect();
+                let parts_ref: Vec<&str> = parts.iter().map(String::as_str).collect();
+                Tag::parse(parts_ref.iter().copied())
+                    .unwrap_or_else(|e| panic!("fixture tag parse error: {e}\n  raw: {t}"))
+            })
+            .collect()
+    }
+
+    #[test]
+    fn nip_mp_fixtures_all_31_cases_exercised() {
+        const FIXTURE_JSON: &str = include_str!("../../../docs/nips/NIP-MP.fixtures.json");
+
+        let data: serde_json::Value =
+            serde_json::from_str(FIXTURE_JSON).expect("fixture JSON must parse");
+        let cases = data["cases"].as_array().expect("cases must be array");
+
+        // Count gate: the spec says "required to test against this one file"
+        // with the exact count as-shipped.
+        assert_eq!(
+            cases.len(),
+            31,
+            "expected 31 fixture cases, got {} — was NIP-MP.fixtures.json edited?",
+            cases.len()
+        );
+
+        let mut accept_count = 0usize;
+        let mut reject_count = 0usize;
+
+        for case in cases {
+            let name = case["name"].as_str().unwrap();
+            let expect = case["expect"].as_str().unwrap();
+            let template = &case["template"];
+            let content = template["content"].as_str().unwrap_or("");
+            let tags = nip_mp_fixture_tags(&template["tags"]);
+
+            match expect {
+                "accept" => {
+                    build_project_with_tags(content, tags).unwrap_or_else(|e| {
+                        panic!("fixture '{name}' (accept) must build successfully, got: {e}")
+                    });
+                    accept_count += 1;
+                }
+                "reject" => {
+                    let reject_rules = case["reject_rules"]
+                        .as_array()
+                        .expect("reject case must have reject_rules")
+                        .iter()
+                        .map(|r| r.as_str().unwrap().to_string())
+                        .collect::<Vec<_>>();
+
+                    let err = build_project_with_tags(content, tags).unwrap_err();
+                    let err_msg = err.to_string();
+
+                    // The error must mention at least one of the expected rules.
+                    let rule_matched = reject_rules.iter().any(|r| err_msg.contains(r.as_str()));
+                    assert!(
+                        rule_matched,
+                        "fixture '{name}' rejected with wrong rule.\n  expected one of: {reject_rules:?}\n  got error: {err_msg}"
+                    );
+                    reject_count += 1;
+                }
+                other => panic!("fixture '{name}' has unknown expect value: {other:?}"),
+            }
+        }
+
+        assert_eq!(accept_count, 11, "expected 11 accept cases");
+        assert_eq!(reject_count, 20, "expected 20 reject cases");
+    }
 }
diff --git a/crates/buzz-test-client/Cargo.toml b/crates/buzz-test-client/Cargo.toml
index 40a08f3d19..e495c16300 100644
--- a/crates/buzz-test-client/Cargo.toml
+++ b/crates/buzz-test-client/Cargo.toml
@@ -36,6 +36,7 @@ sha2 = { workspace = true }
 sqlx = { workspace = true }
 chrono = { workspace = true }
 s3 = { version = "0.37", package = "rust-s3", default-features = false, features = ["tokio-rustls-tls", "fail-on-err", "tags"] }
+buzz-media = { workspace = true }
 buzz-sdk = { workspace = true }
 
 [[bin]]
diff --git a/crates/buzz-test-client/tests/e2e_git.rs b/crates/buzz-test-client/tests/e2e_git.rs
index 63281fd18f..3c82e31764 100644
--- a/crates/buzz-test-client/tests/e2e_git.rs
+++ b/crates/buzz-test-client/tests/e2e_git.rs
@@ -21,6 +21,7 @@ use std::path::{Path, PathBuf};
 use std::process::Command;
 use std::time::Duration;
 
+use buzz_media::S3AddressingStyle;
 use nostr::{EventBuilder, Keys, Kind, Tag};
 use s3::creds::Credentials;
 use s3::{Bucket, Region};
@@ -61,6 +62,27 @@ async fn post_event(event: &nostr::Event) {
     );
 }
 
+/// Create a channel (kind:9007) owned by `keys` and return its UUID.
+///
+/// The git read gate (SEC-005) authorizes against membership in the channel
+/// named by the announcement's `buzz-channel` tag, so every repo these tests
+/// announce must be bound to a channel its owner belongs to — creating the
+/// channel makes the creator its owner-member.
+async fn create_test_channel(keys: &Keys) -> String {
+    let channel_uuid = uuid::Uuid::new_v4().to_string();
+    let event = EventBuilder::new(Kind::Custom(9007), "")
+        .tags(vec![
+            Tag::parse(["h", &channel_uuid]).unwrap(),
+            Tag::parse(["name", &format!("git-e2e-{channel_uuid}")]).unwrap(),
+            Tag::parse(["channel_type", "stream"]).unwrap(),
+            Tag::parse(["visibility", "open"]).unwrap(),
+        ])
+        .sign_with_keys(keys)
+        .unwrap();
+    post_event(&event).await;
+    channel_uuid
+}
+
 /// Run `git` with the Buzz credential helper and isolated config.
 fn git_status(args: &[&str], cwd: &Path, owner_nsec: &str) -> std::process::Output {
     let helper = credential_helper();
@@ -115,29 +137,55 @@ struct PointerSnapshot {
 }
 
 impl GitS3Probe {
-    fn from_env() -> Self {
-        let endpoint = std::env::var("BUZZ_GIT_S3_ENDPOINT")
-            .or_else(|_| std::env::var("BUZZ_S3_ENDPOINT"))
-            .unwrap_or_else(|_| "http://localhost:9000".to_string());
-        let access_key = std::env::var("BUZZ_GIT_S3_ACCESS_KEY")
-            .or_else(|_| std::env::var("BUZZ_S3_ACCESS_KEY"))
-            .unwrap_or_else(|_| "buzz_dev".to_string());
-        let secret_key = std::env::var("BUZZ_GIT_S3_SECRET_KEY")
-            .or_else(|_| std::env::var("BUZZ_S3_SECRET_KEY"))
-            .unwrap_or_else(|_| "buzz_dev_secret".to_string());
-        let bucket = std::env::var("BUZZ_GIT_S3_BUCKET")
-            .or_else(|_| std::env::var("BUZZ_S3_BUCKET"))
-            .unwrap_or_else(|_| "buzz-media".to_string());
-
+    fn bucket(
+        endpoint: String,
+        access_key: &str,
+        secret_key: &str,
+        bucket_name: &str,
+        region_name: String,
+        addressing_style: S3AddressingStyle,
+    ) -> Box<Bucket> {
         let region = Region::Custom {
-            region: "us-east-1".into(),
+            region: region_name,
             endpoint,
         };
-        let creds = Credentials::new(Some(&access_key), Some(&secret_key), None, None, None)
+        let creds = Credentials::new(Some(access_key), Some(secret_key), None, None, None)
             .expect("S3 credentials");
-        let bucket = Bucket::new(&bucket, region, creds)
-            .expect("S3 bucket")
-            .with_path_style();
+        let bucket = Bucket::new(bucket_name, region, creds).expect("S3 bucket");
+        match addressing_style {
+            S3AddressingStyle::Path => bucket.with_path_style(),
+            S3AddressingStyle::Virtual => bucket,
+        }
+    }
+
+    fn from_env() -> Self {
+        // These E2E assertions inspect the relay's backing bucket directly, so
+        // they must receive the same provider connection and URL style as the
+        // relay. Unit/live MinIO probes in buzz-relay keep explicit local
+        // fixtures and do not need provider overrides.
+        let endpoint = std::env::var("BUZZ_S3_ENDPOINT")
+            .unwrap_or_else(|_| "http://localhost:9000".to_string());
+        let access_key =
+            std::env::var("BUZZ_S3_ACCESS_KEY").unwrap_or_else(|_| "buzz_dev".to_string());
+        let secret_key =
+            std::env::var("BUZZ_S3_SECRET_KEY").unwrap_or_else(|_| "buzz_dev_secret".to_string());
+        let bucket_name =
+            std::env::var("BUZZ_S3_BUCKET").unwrap_or_else(|_| "buzz-media".to_string());
+        let region_name =
+            std::env::var("BUZZ_S3_REGION").unwrap_or_else(|_| "us-east-1".to_string());
+        let addressing_style = std::env::var("BUZZ_S3_ADDRESSING_STYLE")
+            .unwrap_or_else(|_| "path".to_string())
+            .parse::<S3AddressingStyle>()
+            .expect("BUZZ_S3_ADDRESSING_STYLE must be 'path' or 'virtual'");
+
+        let bucket = Self::bucket(
+            endpoint,
+            &access_key,
+            &secret_key,
+            &bucket_name,
+            region_name,
+            addressing_style,
+        );
         Self { bucket }
     }
 
@@ -192,6 +240,31 @@ impl GitS3Probe {
     }
 }
 
+#[test]
+fn git_s3_probe_builds_both_addressing_styles() {
+    let path = GitS3Probe::bucket(
+        "https://storage.example".to_string(),
+        "access",
+        "secret",
+        "buzz-media",
+        "us-east-1".to_string(),
+        S3AddressingStyle::Path,
+    );
+    assert!(path.is_path_style());
+    assert_eq!(path.url(), "https://storage.example/buzz-media");
+
+    let virtual_hosted = GitS3Probe::bucket(
+        "https://storage.example".to_string(),
+        "access",
+        "secret",
+        "buzz-media",
+        "auto".to_string(),
+        S3AddressingStyle::Virtual,
+    );
+    assert!(virtual_hosted.is_subdomain_style());
+    assert_eq!(virtual_hosted.url(), "https://buzz-media.storage.example");
+}
+
 #[tokio::test]
 #[ignore = "requires live relay + MinIO + git"]
 async fn git_clone_push_fetch_force_roundtrip() {
@@ -204,10 +277,15 @@ async fn git_clone_push_fetch_force_roundtrip() {
     let s3 = GitS3Probe::from_env();
 
     // Announce the repo (kind:30617) so the relay creates the bare repo + hook.
+    // The `buzz-channel` binding is the repo's ACL: without it the read gate
+    // 404s even for the owner (issue #3527), so bind to a channel the owner
+    // just created (and therefore belongs to).
+    let channel = create_test_channel(&owner).await;
     let announce = EventBuilder::new(Kind::from(30617), "")
         .tags(vec![
             Tag::parse(["d", &repo]).unwrap(),
             Tag::parse(["name", "e2e git repo"]).unwrap(),
+            Tag::parse(["buzz-channel", &channel]).unwrap(),
         ])
         .sign_with_keys(&owner)
         .unwrap();
@@ -341,10 +419,12 @@ async fn git_concurrent_push_one_wins_and_repo_recovers() {
     let repo = format!("e2e-git-concurrent-{}", std::process::id());
     let s3 = GitS3Probe::from_env();
 
+    let channel = create_test_channel(&owner).await;
     let announce = EventBuilder::new(Kind::from(30617), "")
         .tags(vec![
             Tag::parse(["d", &repo]).unwrap(),
             Tag::parse(["name", "e2e concurrent git repo"]).unwrap(),
+            Tag::parse(["buzz-channel", &channel]).unwrap(),
         ])
         .sign_with_keys(&owner)
         .unwrap();
diff --git a/crates/buzz-test-client/tests/e2e_persona.rs b/crates/buzz-test-client/tests/e2e_persona.rs
index b3b1f7f6b2..4f37e22e16 100644
--- a/crates/buzz-test-client/tests/e2e_persona.rs
+++ b/crates/buzz-test-client/tests/e2e_persona.rs
@@ -1324,7 +1324,7 @@ async fn test_persona_http_query_cross_author_gate() {
 ///
 /// A foreign authenticated caller counting `{kinds:[30175],authors:[victim]}`
 /// must count only shared heads — not unshared ones — on both the fast SQL
-/// path (prevented by `needs_persona_filtering`) and the fallback path.
+/// path (prevented by `needs_shared_gate_filtering`) and the fallback path.
 #[tokio::test]
 #[ignore]
 async fn test_persona_http_count_cross_author_gate() {
@@ -1403,7 +1403,7 @@ async fn test_persona_http_count_cross_author_gate() {
 /// event is returned.
 ///
 /// Verifies at `312014d5e`: this test fails there because `query_events` did
-/// not have the `persona_reader` SQL clause and the private rows starved the
+/// not have the `shared_gated_reader` SQL clause and the private rows starved the
 /// shared one off the page.
 #[tokio::test]
 #[ignore]
diff --git a/crates/buzz-test-client/tests/e2e_project.rs b/crates/buzz-test-client/tests/e2e_project.rs
new file mode 100644
index 0000000000..c0a05e4674
--- /dev/null
+++ b/crates/buzz-test-client/tests/e2e_project.rs
@@ -0,0 +1,491 @@
+//! End-to-end tests for kind:30621 multi-repo project events (NIP-MP).
+//!
+//! The ingest unit tests in `buzz-relay` pin the envelope contract in isolation.
+//! These tests cover the three behaviors that only exist once an event reaches
+//! storage, plus proof that the envelope validator is actually wired into the
+//! live write path:
+//! - a valid cross-owner project round-trips through its NIP-33 coordinate;
+//! - replacement is keyed by `(pubkey, 30621, d)` — newer wins for one author,
+//!   and two authors sharing a `d` hold two independent projects (this is what
+//!   makes owner-only editing free rather than a relay permission check);
+//! - a NIP-09 `a`-tag tombstone removes the project coordinate and leaves every
+//!   referenced kind:30617 announcement untouched, because membership is an
+//!   assertion about repositories and never authority over them;
+//! - malformed envelopes are refused by the relay, not merely by the validator.
+//!
+//! See `docs/nips/NIP-MP.md` for the normative contract.
+//!
+//! # Running
+//!
+//! Start the relay, then run:
+//!
+//! ```text
+//! RELAY_URL=ws://localhost:3000 cargo test -p buzz-test-client --test e2e_project -- --ignored
+//! ```
+
+use std::time::Duration;
+
+use buzz_test_client::BuzzTestClient;
+use nostr::{Alphabet, EventBuilder, Filter, Keys, Kind, SingleLetterTag, Tag, Timestamp};
+
+const PROJECT_KIND: u16 = 30621;
+const REPO_ANNOUNCEMENT_KIND: u16 = 30617;
+
+fn relay_url() -> String {
+    std::env::var("RELAY_URL").unwrap_or_else(|_| "ws://localhost:3000".to_string())
+}
+
+fn sub_id(name: &str) -> String {
+    format!("e2e-project-{name}-{}", uuid::Uuid::new_v4())
+}
+
+/// A short unique suffix so concurrent runs never collide on a `d` tag.
+fn unique(prefix: &str) -> String {
+    format!("{prefix}-{}", &uuid::Uuid::new_v4().to_string()[..8])
+}
+
+fn member_coord(owner: &Keys, repo_d: &str) -> String {
+    format!(
+        "{REPO_ANNOUNCEMENT_KIND}:{}:{repo_d}",
+        owner.public_key().to_hex()
+    )
+}
+
+/// Build a project event. `members` are canonical `30617:<owner>:<d>`
+/// coordinates; `created_at` defaults to now when `None`.
+fn project_event(
+    keys: &Keys,
+    d_tag: &str,
+    name: &str,
+    members: &[String],
+    created_at: Option<u64>,
+) -> nostr::Event {
+    let mut tags = vec![
+        Tag::parse(["d", d_tag]).unwrap(),
+        Tag::parse(["name", name]).unwrap(),
+    ];
+    tags.extend(
+        members
+            .iter()
+            .map(|m| Tag::parse(["a", m.as_str()]).unwrap()),
+    );
+    let builder = EventBuilder::new(Kind::Custom(PROJECT_KIND), "").tags(tags);
+    match created_at {
+        Some(ts) => builder.custom_created_at(Timestamp::from(ts)),
+        None => builder,
+    }
+    .sign_with_keys(keys)
+    .unwrap()
+}
+
+/// Announce a repository so a project has a real coordinate to reference.
+fn repo_announcement(keys: &Keys, repo_d: &str) -> nostr::Event {
+    EventBuilder::new(Kind::Custom(REPO_ANNOUNCEMENT_KIND), "")
+        .tags(vec![
+            Tag::parse(["d", repo_d]).unwrap(),
+            Tag::parse(["name", repo_d]).unwrap(),
+        ])
+        .sign_with_keys(keys)
+        .unwrap()
+}
+
+/// A NIP-09 `a`-tag-only deletion at a NIP-33 coordinate. No `e` tag, so the
+/// relay takes the coordinate-delete path rather than the event-id path.
+/// `created_at` defaults to now when `None`.
+fn coordinate_delete(keys: &Keys, kind: u16, d_tag: &str, created_at: Option<u64>) -> nostr::Event {
+    let coord = format!("{kind}:{}:{d_tag}", keys.public_key().to_hex());
+    let builder =
+        EventBuilder::new(Kind::Custom(5), "")
+            .tags(vec![Tag::parse(["a", coord.as_str()]).unwrap()]);
+    match created_at {
+        Some(ts) => builder.custom_created_at(Timestamp::from(ts)),
+        None => builder,
+    }
+    .sign_with_keys(keys)
+    .unwrap()
+}
+
+fn addressable_filter(kind: u16, author: &Keys, d_tag: &str) -> Filter {
+    Filter::new()
+        .kind(Kind::Custom(kind))
+        .author(author.public_key())
+        .custom_tags(SingleLetterTag::lowercase(Alphabet::D), [d_tag])
+}
+
+/// Subscribe with `filter` and drain to EOSE.
+async fn query(client: &mut BuzzTestClient, name: &str, filter: Filter) -> Vec<nostr::Event> {
+    let sid = sub_id(name);
+    client
+        .subscribe(&sid, vec![filter])
+        .await
+        .expect("subscribe");
+    client
+        .collect_until_eose(&sid, Duration::from_secs(5))
+        .await
+        .expect("collect events")
+}
+
+#[tokio::test]
+#[ignore]
+async fn test_project_publish_and_query_returns_cross_owner_members() {
+    let url = relay_url();
+    let owner = Keys::generate();
+    let other = Keys::generate();
+    let d_tag = unique("project");
+
+    let members = vec![
+        member_coord(&owner, "buzz"),
+        member_coord(&other, "buzz-infra"),
+    ];
+
+    let mut client = BuzzTestClient::connect(&url, &owner)
+        .await
+        .expect("connect");
+
+    let event = project_event(&owner, &d_tag, "Platform", &members, None);
+    let ok = client.send_event(event).await.expect("send project");
+    assert!(ok.accepted, "relay rejected project event: {}", ok.message);
+
+    let events = query(
+        &mut client,
+        "query",
+        addressable_filter(PROJECT_KIND, &owner, &d_tag),
+    )
+    .await;
+
+    assert_eq!(events.len(), 1, "expected exactly one project event");
+    let stored: Vec<&str> = events[0]
+        .tags
+        .iter()
+        .filter_map(|t| {
+            let parts = t.as_slice();
+            (parts.first().map(|s| s.as_str()) == Some("a")).then(|| parts[1].as_str())
+        })
+        .collect();
+    assert_eq!(
+        stored, members,
+        "both members must survive the round trip, including the one owned by another pubkey"
+    );
+
+    client.disconnect().await.expect("disconnect");
+}
+
+#[tokio::test]
+#[ignore]
+async fn test_project_replacement_keeps_only_newest_for_same_author_and_d() {
+    let url = relay_url();
+    let owner = Keys::generate();
+    let d_tag = unique("project-replace");
+    let now = Timestamp::now().as_secs();
+
+    let mut client = BuzzTestClient::connect(&url, &owner)
+        .await
+        .expect("connect");
+
+    let first = project_event(&owner, &d_tag, "Old", &[], Some(now - 100));
+    let ok = client.send_event(first).await.expect("send old");
+    assert!(ok.accepted, "relay rejected old project: {}", ok.message);
+
+    let members = vec![member_coord(&owner, "buzz")];
+    let second = project_event(&owner, &d_tag, "New", &members, Some(now));
+    let ok = client.send_event(second).await.expect("send new");
+    assert!(ok.accepted, "relay rejected new project: {}", ok.message);
+
+    let events = query(
+        &mut client,
+        "replace",
+        addressable_filter(PROJECT_KIND, &owner, &d_tag),
+    )
+    .await;
+
+    assert_eq!(
+        events.len(),
+        1,
+        "NIP-33: only the newest head should remain"
+    );
+    let name = events[0]
+        .tags
+        .iter()
+        .find_map(|t| {
+            let parts = t.as_slice();
+            (parts.first().map(|s| s.as_str()) == Some("name")).then(|| parts[1].as_str())
+        })
+        .expect("name tag");
+    assert_eq!(name, "New", "the newer head must win");
+
+    client.disconnect().await.expect("disconnect");
+}
+
+/// Owner-only editing is a property of the addressable model, not a relay
+/// permission check: two authors publishing the same `d` occupy two coordinates,
+/// so neither can overwrite the other. This is the test that would fail if the
+/// kind were ever classified as plain-replaceable or keyed on `d` alone.
+#[tokio::test]
+#[ignore]
+async fn test_project_same_d_under_two_authors_are_independent() {
+    let url = relay_url();
+    let alice = Keys::generate();
+    let bob = Keys::generate();
+    let d_tag = unique("project-shared-d");
+
+    let mut alice_client = BuzzTestClient::connect(&url, &alice)
+        .await
+        .expect("connect");
+    let ok = alice_client
+        .send_event(project_event(&alice, &d_tag, "Alice", &[], None))
+        .await
+        .expect("send alice");
+    assert!(
+        ok.accepted,
+        "relay rejected alice's project: {}",
+        ok.message
+    );
+
+    let mut bob_client = BuzzTestClient::connect(&url, &bob).await.expect("connect");
+    let ok = bob_client
+        .send_event(project_event(&bob, &d_tag, "Bob", &[], None))
+        .await
+        .expect("send bob");
+    assert!(ok.accepted, "relay rejected bob's project: {}", ok.message);
+
+    for (label, keys, expected_name) in [("alice", &alice, "Alice"), ("bob", &bob, "Bob")] {
+        let events = query(
+            &mut alice_client,
+            label,
+            addressable_filter(PROJECT_KIND, keys, &d_tag),
+        )
+        .await;
+        assert_eq!(
+            events.len(),
+            1,
+            "{label} should still hold their own project at the shared `d`"
+        );
+        let name = events[0]
+            .tags
+            .iter()
+            .find_map(|t| {
+                let parts = t.as_slice();
+                (parts.first().map(|s| s.as_str()) == Some("name")).then(|| parts[1].as_str())
+            })
+            .expect("name tag");
+        assert_eq!(name, expected_name, "{label}'s project was overwritten");
+    }
+
+    alice_client.disconnect().await.expect("disconnect");
+    bob_client.disconnect().await.expect("disconnect");
+}
+
+/// Deleting a project must delete only the grouping. A project is metadata about
+/// repositories; if a tombstone at the project coordinate cascaded to the
+/// referenced kind:30617s, adding a repo to someone's project would become a way
+/// to destroy it.
+#[tokio::test]
+#[ignore]
+async fn test_project_tombstone_deletes_coordinate_and_spares_members() {
+    let url = relay_url();
+    let owner = Keys::generate();
+    let repo_d = unique("repo");
+    let project_d = unique("project-tombstone");
+
+    let mut client = BuzzTestClient::connect(&url, &owner)
+        .await
+        .expect("connect");
+
+    let ok = client
+        .send_event(repo_announcement(&owner, &repo_d))
+        .await
+        .expect("send announcement");
+    assert!(ok.accepted, "relay rejected announcement: {}", ok.message);
+
+    let members = vec![member_coord(&owner, &repo_d)];
+    let ok = client
+        .send_event(project_event(&owner, &project_d, "Doomed", &members, None))
+        .await
+        .expect("send project");
+    assert!(ok.accepted, "relay rejected project: {}", ok.message);
+
+    let before = query(
+        &mut client,
+        "tombstone-pre",
+        addressable_filter(PROJECT_KIND, &owner, &project_d),
+    )
+    .await;
+    assert_eq!(before.len(), 1, "project should be live before deletion");
+
+    let ok = client
+        .send_event(coordinate_delete(&owner, PROJECT_KIND, &project_d, None))
+        .await
+        .expect("send tombstone");
+    assert!(ok.accepted, "relay rejected tombstone: {}", ok.message);
+
+    let after = query(
+        &mut client,
+        "tombstone-post",
+        addressable_filter(PROJECT_KIND, &owner, &project_d),
+    )
+    .await;
+    assert!(
+        after.is_empty(),
+        "tombstone should remove the project coordinate, got {} event(s)",
+        after.len()
+    );
+
+    let repo = query(
+        &mut client,
+        "member-after",
+        addressable_filter(REPO_ANNOUNCEMENT_KIND, &owner, &repo_d),
+    )
+    .await;
+    assert_eq!(
+        repo.len(),
+        1,
+        "deleting a project must not touch the repositories it referenced"
+    );
+
+    client.disconnect().await.expect("disconnect");
+}
+
+/// NIP-09 scopes an `a`-tag deletion to versions at or before the deletion's own
+/// `created_at`. A tombstone signed between V1 and V2 — delayed in transit or
+/// replayed by a third party — must therefore retire V1 only and leave the newer
+/// V2 head live. Before the timestamp predicate landed in
+/// `soft_delete_by_coordinate`, the coordinate delete was timestamp-blind and
+/// this sequence silently destroyed V2.
+#[tokio::test]
+#[ignore]
+async fn test_stale_tombstone_between_versions_leaves_newer_project_live() {
+    let url = relay_url();
+    let owner = Keys::generate();
+    let project_d = unique("project-stale-tombstone");
+    let now = Timestamp::now().as_secs();
+
+    let mut client = BuzzTestClient::connect(&url, &owner)
+        .await
+        .expect("connect");
+
+    let ok = client
+        .send_event(project_event(
+            &owner,
+            &project_d,
+            "V1",
+            &[],
+            Some(now - 100),
+        ))
+        .await
+        .expect("send v1");
+    assert!(ok.accepted, "relay rejected V1: {}", ok.message);
+
+    let ok = client
+        .send_event(project_event(&owner, &project_d, "V2", &[], Some(now)))
+        .await
+        .expect("send v2");
+    assert!(ok.accepted, "relay rejected V2: {}", ok.message);
+
+    // Timestamped strictly between V1 and V2: valid for V1, stale for V2.
+    let ok = client
+        .send_event(coordinate_delete(
+            &owner,
+            PROJECT_KIND,
+            &project_d,
+            Some(now - 50),
+        ))
+        .await
+        .expect("send stale tombstone");
+    assert!(
+        ok.accepted,
+        "a well-formed tombstone is still an acceptable event: {}",
+        ok.message
+    );
+
+    let after = query(
+        &mut client,
+        "stale-tombstone",
+        addressable_filter(PROJECT_KIND, &owner, &project_d),
+    )
+    .await;
+
+    assert_eq!(
+        after.len(),
+        1,
+        "a tombstone older than the live head must not delete it, got {} event(s)",
+        after.len()
+    );
+    let name = after[0]
+        .tags
+        .iter()
+        .find_map(|t| {
+            let parts = t.as_slice();
+            (parts.first().map(|s| s.as_str()) == Some("name")).then(|| parts[1].as_str())
+        })
+        .expect("surviving head must carry its name tag");
+    assert_eq!(name, "V2", "the surviving head must be the newer version");
+
+    client.disconnect().await.expect("disconnect");
+}
+
+/// Proves the envelope validator is reachable from the live write path — a unit
+/// test of `validate_project_envelope` cannot show that ingest calls it.
+#[tokio::test]
+#[ignore]
+async fn test_project_malformed_envelope_rejected_by_relay() {
+    let url = relay_url();
+    let owner = Keys::generate();
+    let mut client = BuzzTestClient::connect(&url, &owner)
+        .await
+        .expect("connect");
+
+    let duplicate = member_coord(&owner, "buzz");
+    // Each case pairs a malformed event with the substring its rejection must
+    // carry, so a refusal for an unrelated reason cannot satisfy the assertion.
+    let cases: Vec<(&str, nostr::Event, &str)> = vec![
+        (
+            "duplicate member coordinate",
+            project_event(
+                &owner,
+                &unique("project-dup"),
+                "Dup",
+                &[duplicate.clone(), duplicate],
+                None,
+            ),
+            "duplicate member coordinate",
+        ),
+        (
+            "member coordinate naming the wrong kind",
+            project_event(
+                &owner,
+                &unique("project-badkind"),
+                "Bad kind",
+                &[format!("30618:{}:buzz", owner.public_key().to_hex())],
+                None,
+            ),
+            "member `a` tag must be",
+        ),
+        (
+            "member coordinate with an uppercase-hex owner",
+            project_event(
+                &owner,
+                &unique("project-upper"),
+                "Uppercase",
+                &[format!("{REPO_ANNOUNCEMENT_KIND}:{}:buzz", "A".repeat(64))],
+                None,
+            ),
+            "member `a` tag must be",
+        ),
+    ];
+
+    for (label, event, expected) in cases {
+        let ok = client.send_event(event).await.expect("send");
+        assert!(
+            !ok.accepted,
+            "relay must reject a project with a {label}, got OK: {}",
+            ok.message
+        );
+        assert!(
+            ok.message.contains(expected),
+            "rejection for {label} must name the rule that fired, got: {}",
+            ok.message
+        );
+    }
+
+    client.disconnect().await.expect("disconnect");
+}
diff --git a/crates/buzz-test-client/tests/e2e_team_catalog.rs b/crates/buzz-test-client/tests/e2e_team_catalog.rs
new file mode 100644
index 0000000000..ce313d1fe9
--- /dev/null
+++ b/crates/buzz-test-client/tests/e2e_team_catalog.rs
@@ -0,0 +1,484 @@
+//! End-to-end tests for kind:30178 team-catalog events (NIP-AP).
+//!
+//! Kind 30178 is the shareable projection of a team. It joins kind:30175 in
+//! `SHARED_GATED_KINDS`, so these tests assert the wire behaviour of that gate
+//! at every read chokepoint (REQ, `ids` lookup, COUNT, live fan-out) plus the
+//! ingest envelope rules that make the gate sound:
+//! - Exactly one non-empty, bounded `d` tag — the team's stable local id, which
+//!   may contain a colon (`builtin-team:welcome`) unlike a persona slug.
+//! - `shared`, if present, is exactly `["shared", "true"]`.
+//!
+//! # Running
+//!
+//! Start the relay, then run:
+//!
+//! ```text
+//! RELAY_URL=ws://localhost:3000 cargo test --test e2e_team_catalog -- --ignored
+//! ```
+
+use std::time::Duration;
+
+use buzz_test_client::{BuzzTestClient, RelayMessage};
+use nostr::{Alphabet, EventBuilder, Filter, Keys, Kind, SingleLetterTag, Tag, Timestamp};
+
+const TEAM_CATALOG_KIND: u16 = 30178;
+
+fn relay_url() -> String {
+    std::env::var("RELAY_URL").unwrap_or_else(|_| "ws://localhost:3000".to_string())
+}
+
+fn sub_id(name: &str) -> String {
+    format!("e2e-team-catalog-{name}-{}", uuid::Uuid::new_v4())
+}
+
+fn catalog_content(name: &str) -> String {
+    serde_json::json!({ "v": 1, "name": name, "members": [] }).to_string()
+}
+
+/// Build a kind:30178 event, optionally carrying the `["shared","true"]` opt-in.
+fn catalog_event(keys: &Keys, d_tag: &str, shared: bool) -> nostr::Event {
+    catalog_event_at(keys, d_tag, shared, Timestamp::now().as_secs())
+}
+
+/// Same as [`catalog_event`] with an explicit `created_at`, so NIP-33 head
+/// ordering is deterministic instead of resolved by event-id tie-break.
+fn catalog_event_at(keys: &Keys, d_tag: &str, shared: bool, created_at: u64) -> nostr::Event {
+    let mut tags = vec![Tag::parse(["d", d_tag]).unwrap()];
+    if shared {
+        tags.push(Tag::parse(["shared", "true"]).unwrap());
+    }
+    EventBuilder::new(
+        Kind::Custom(TEAM_CATALOG_KIND),
+        catalog_content("Test Team"),
+    )
+    .tags(tags)
+    .custom_created_at(Timestamp::from(created_at))
+    .sign_with_keys(keys)
+    .unwrap()
+}
+
+fn author_filter(author: &Keys) -> Filter {
+    Filter::new()
+        .kind(Kind::Custom(TEAM_CATALOG_KIND))
+        .author(author.public_key())
+}
+
+fn coordinate_filter(author: &Keys, d_tag: &str) -> Filter {
+    author_filter(author).custom_tags(SingleLetterTag::lowercase(Alphabet::D), [d_tag])
+}
+
+fn d_tag_of(event: &nostr::Event) -> Option<&str> {
+    event.tags.iter().find_map(|t| {
+        let parts = t.as_slice();
+        if parts.first().map(|p| p.as_str()) != Some("d") {
+            return None;
+        }
+        Some(parts.get(1)?.as_str())
+    })
+}
+
+/// The author's own unshared projection round-trips at its NIP-33 coordinate.
+///
+/// The `d` tag is a UUID, matching the desktop team id — proof the envelope does
+/// NOT apply the persona slug grammar.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_publish_and_query_own_unshared() {
+    let url = relay_url();
+    let keys = Keys::generate();
+    let d_tag = uuid::Uuid::new_v4().to_string();
+
+    let mut client = BuzzTestClient::connect(&url, &keys).await.expect("connect");
+    let event = catalog_event(&keys, &d_tag, false);
+    let event_id = event.id;
+    let ok = client.send_event(event).await.expect("send catalog");
+    assert!(ok.accepted, "relay rejected catalog event: {}", ok.message);
+
+    let sid = sub_id("own-unshared");
+    client
+        .subscribe(&sid, vec![coordinate_filter(&keys, &d_tag)])
+        .await
+        .expect("subscribe");
+    let events = client
+        .collect_until_eose(&sid, Duration::from_secs(5))
+        .await
+        .expect("collect");
+
+    assert_eq!(events.len(), 1, "author must see own unshared projection");
+    assert_eq!(events[0].id, event_id);
+
+    client.disconnect().await.expect("disconnect");
+}
+
+/// A built-in team id (`builtin-team:welcome`) is accepted as the `d` tag.
+///
+/// The colon is illegal in a persona slug; rewriting the id to fit would break
+/// NIP-33 addressing against the team's own kind:30176 head.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_accepts_builtin_colon_d_tag() {
+    let url = relay_url();
+    let keys = Keys::generate();
+    let d_tag = format!("builtin-team:{}", &uuid::Uuid::new_v4().to_string()[..8]);
+
+    let mut client = BuzzTestClient::connect(&url, &keys).await.expect("connect");
+    let ok = client
+        .send_event(catalog_event(&keys, &d_tag, true))
+        .await
+        .expect("send catalog");
+    assert!(
+        ok.accepted,
+        "relay rejected colon-bearing team id: {}",
+        ok.message
+    );
+
+    client.disconnect().await.expect("disconnect");
+}
+
+/// Ingest refuses an empty `d` tag: generic NIP-33 storage maps it to the empty
+/// coordinate, collapsing every team into one `(pubkey, 30178, "")` slot.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_rejects_empty_d_tag() {
+    let url = relay_url();
+    let keys = Keys::generate();
+
+    let mut client = BuzzTestClient::connect(&url, &keys).await.expect("connect");
+    let ok = client
+        .send_event(catalog_event(&keys, "", false))
+        .await
+        .expect("send catalog");
+    assert!(!ok.accepted, "empty d-tag must be rejected");
+    assert!(
+        ok.message.contains("invalid:"),
+        "expected an `invalid:` refusal, got: {}",
+        ok.message
+    );
+
+    client.disconnect().await.expect("disconnect");
+}
+
+/// Ingest refuses a valueless `["d"]` tag alongside a valued one. Counting only
+/// tags that carry a value would see exactly one `d` here and accept the event;
+/// a NIP-33 consumer that reads `["d"]` as an empty-valued first `d` tag would
+/// then address the event at `""` where this relay addresses it at the team id.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_rejects_valueless_plus_valued_d_tags() {
+    let url = relay_url();
+    let keys = Keys::generate();
+    let d_tag = uuid::Uuid::new_v4().to_string();
+
+    let event = EventBuilder::new(
+        Kind::Custom(TEAM_CATALOG_KIND),
+        catalog_content("Two d tags"),
+    )
+    .tags(vec![
+        Tag::parse(["d"]).unwrap(),
+        Tag::parse(["d", d_tag.as_str()]).unwrap(),
+    ])
+    .sign_with_keys(&keys)
+    .unwrap();
+
+    let mut client = BuzzTestClient::connect(&url, &keys).await.expect("connect");
+    let ok = client.send_event(event).await.expect("send catalog");
+    assert!(
+        !ok.accepted,
+        "a valueless `d` tag must count toward the exactly-one rule"
+    );
+    assert!(
+        ok.message.contains("invalid:"),
+        "expected an `invalid:` refusal, got: {}",
+        ok.message
+    );
+
+    client.disconnect().await.expect("disconnect");
+}
+
+/// Ingest refuses a malformed `shared` tag. A three-element tag would satisfy
+/// the SQL containment clause `tags @> '[["shared","true"]]'` as a superset
+/// while the in-process gate reads it as unshared — the two layers must agree,
+/// so such an event can never be stored.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_rejects_three_element_shared_tag() {
+    let url = relay_url();
+    let keys = Keys::generate();
+    let d_tag = uuid::Uuid::new_v4().to_string();
+
+    let event = EventBuilder::new(
+        Kind::Custom(TEAM_CATALOG_KIND),
+        catalog_content("Malformed"),
+    )
+    .tags(vec![
+        Tag::parse(["d", d_tag.as_str()]).unwrap(),
+        Tag::parse(["shared", "true", "extra"]).unwrap(),
+    ])
+    .sign_with_keys(&keys)
+    .unwrap();
+
+    let mut client = BuzzTestClient::connect(&url, &keys).await.expect("connect");
+    let ok = client.send_event(event).await.expect("send catalog");
+    assert!(!ok.accepted, "three-element shared tag must be rejected");
+    assert!(
+        ok.message.contains("invalid:"),
+        "expected an `invalid:` refusal, got: {}",
+        ok.message
+    );
+
+    client.disconnect().await.expect("disconnect");
+}
+
+/// REQ historical delivery: a foreign reader receives only shared projections,
+/// while the author receives both of their own.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_foreign_sees_only_shared() {
+    let url = relay_url();
+    let author_keys = Keys::generate();
+    let foreign_keys = Keys::generate();
+
+    let d_unshared = format!("priv-{}", uuid::Uuid::new_v4());
+    let d_shared = format!("pub-{}", uuid::Uuid::new_v4());
+
+    let mut author = BuzzTestClient::connect(&url, &author_keys)
+        .await
+        .expect("connect author");
+    let shared_event = catalog_event(&author_keys, &d_shared, true);
+    let shared_id = shared_event.id;
+    let ok = author
+        .send_event(catalog_event(&author_keys, &d_unshared, false))
+        .await
+        .expect("send unshared");
+    assert!(ok.accepted, "unshared ingest rejected: {}", ok.message);
+    let ok = author.send_event(shared_event).await.expect("send shared");
+    assert!(ok.accepted, "shared ingest rejected: {}", ok.message);
+
+    let mut foreign = BuzzTestClient::connect(&url, &foreign_keys)
+        .await
+        .expect("connect foreign");
+    let sid = sub_id("fg-all");
+    foreign
+        .subscribe(&sid, vec![author_filter(&author_keys)])
+        .await
+        .expect("subscribe");
+    let events = foreign
+        .collect_until_eose(&sid, Duration::from_secs(5))
+        .await
+        .expect("collect");
+
+    assert!(
+        !events
+            .iter()
+            .any(|e| d_tag_of(e) == Some(d_unshared.as_str())),
+        "foreign reader must NOT see the unshared projection"
+    );
+    assert!(
+        events.iter().any(|e| e.id == shared_id),
+        "foreign reader must see the shared projection"
+    );
+
+    let sid_author = sub_id("auth-all");
+    author
+        .subscribe(&sid_author, vec![author_filter(&author_keys)])
+        .await
+        .expect("subscribe author");
+    let author_events = author
+        .collect_until_eose(&sid_author, Duration::from_secs(5))
+        .await
+        .expect("collect author");
+    assert!(
+        author_events.len() >= 2,
+        "author must see both own projections, got {}",
+        author_events.len()
+    );
+
+    author.disconnect().await.expect("disconnect author");
+    foreign.disconnect().await.expect("disconnect foreign");
+}
+
+/// Knowing an event id does NOT grant access: `{ids:[unshared]}` returns nothing
+/// to a foreign reader.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_ids_lookup_unshared_returns_nothing_to_foreign() {
+    let url = relay_url();
+    let author_keys = Keys::generate();
+    let foreign_keys = Keys::generate();
+
+    let event = catalog_event(&author_keys, &uuid::Uuid::new_v4().to_string(), false);
+    let event_id = event.id;
+
+    let mut author = BuzzTestClient::connect(&url, &author_keys)
+        .await
+        .expect("connect author");
+    let ok = author.send_event(event).await.expect("send");
+    assert!(ok.accepted, "ingest rejected: {}", ok.message);
+    author.disconnect().await.expect("disconnect author");
+
+    let mut foreign = BuzzTestClient::connect(&url, &foreign_keys)
+        .await
+        .expect("connect foreign");
+    let sid = sub_id("ids-unshared");
+    foreign
+        .subscribe(&sid, vec![Filter::new().id(event_id)])
+        .await
+        .expect("subscribe");
+    let events = foreign
+        .collect_until_eose(&sid, Duration::from_secs(5))
+        .await
+        .expect("collect");
+
+    assert!(
+        events.is_empty(),
+        "ids-lookup of an unshared projection must return nothing, got {:?}",
+        events.iter().map(|e| e.id).collect::<Vec<_>>()
+    );
+
+    foreign.disconnect().await.expect("disconnect foreign");
+}
+
+/// COUNT must take the per-event fallback for kind:30178 so the aggregate does
+/// not leak the existence of unshared projections.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_count_excludes_foreign_unshared() {
+    let url = relay_url();
+    let author_keys = Keys::generate();
+    let foreign_keys = Keys::generate();
+
+    let mut author = BuzzTestClient::connect(&url, &author_keys)
+        .await
+        .expect("connect author");
+    let ok = author
+        .send_event(catalog_event(
+            &author_keys,
+            &uuid::Uuid::new_v4().to_string(),
+            false,
+        ))
+        .await
+        .expect("send unshared");
+    assert!(ok.accepted, "unshared rejected: {}", ok.message);
+    let ok = author
+        .send_event(catalog_event(
+            &author_keys,
+            &uuid::Uuid::new_v4().to_string(),
+            true,
+        ))
+        .await
+        .expect("send shared");
+    assert!(ok.accepted, "shared rejected: {}", ok.message);
+    author.disconnect().await.expect("disconnect author");
+
+    let mut foreign = BuzzTestClient::connect(&url, &foreign_keys)
+        .await
+        .expect("connect foreign");
+    let sid = sub_id("count");
+    let count_msg = serde_json::json!(["COUNT", sid, author_filter(&author_keys)]);
+    foreign.send_raw(&count_msg).await.expect("send COUNT");
+
+    let count = match foreign.recv_event(Duration::from_secs(5)).await {
+        Ok(RelayMessage::Count { count, .. }) => count,
+        Ok(RelayMessage::Closed { message, .. }) => panic!("COUNT closed unexpectedly: {message}"),
+        Ok(other) => panic!("unexpected relay message for COUNT: {other:?}"),
+        Err(e) => panic!("unexpected error for COUNT: {e}"),
+    };
+    assert_eq!(
+        count, 1,
+        "foreign COUNT must see only the shared projection, got {count}"
+    );
+
+    foreign.disconnect().await.expect("disconnect foreign");
+}
+
+/// Live fan-out honours the gate, and unsharing (a NIP-33 replacement that drops
+/// the `shared` tag) retracts the projection from foreign readers.
+#[tokio::test]
+#[ignore]
+async fn test_team_catalog_live_fanout_and_unshare_retracts() {
+    let url = relay_url();
+    let author_keys = Keys::generate();
+    let foreign_keys = Keys::generate();
+
+    let d_tag = uuid::Uuid::new_v4().to_string();
+    let now = Timestamp::now().as_secs();
+    let (t0, t1, t2) = (now.saturating_sub(2), now.saturating_sub(1), now);
+
+    // Subscribe BEFORE publishing, scoped to this author so parallel tests
+    // publishing their own 30178s cannot trip the leak assertion.
+    let mut foreign = BuzzTestClient::connect(&url, &foreign_keys)
+        .await
+        .expect("connect foreign");
+    let sid = sub_id("fanout");
+    foreign
+        .subscribe(&sid, vec![author_filter(&author_keys)])
+        .await
+        .expect("subscribe");
+    let _ = foreign
+        .collect_until_eose(&sid, Duration::from_secs(5))
+        .await
+        .expect("drain eose");
+
+    let mut author = BuzzTestClient::connect(&url, &author_keys)
+        .await
+        .expect("connect author");
+
+    // Unshared publish must NOT reach the foreign connection.
+    let ok = author
+        .send_event(catalog_event_at(&author_keys, &d_tag, false, t0))
+        .await
+        .expect("send unshared");
+    assert!(ok.accepted, "unshared rejected: {}", ok.message);
+    match foreign.recv_event(Duration::from_millis(750)).await {
+        Err(buzz_test_client::TestClientError::Timeout) => {}
+        Ok(RelayMessage::Event { event, .. }) if event.kind == Kind::Custom(TEAM_CATALOG_KIND) => {
+            panic!("unshared projection leaked to foreign live subscription");
+        }
+        Ok(_) => {}
+        Err(e) => panic!("unexpected error awaiting fan-out: {e}"),
+    }
+
+    // Shared replacement MUST reach it.
+    let shared_event = catalog_event_at(&author_keys, &d_tag, true, t1);
+    let shared_id = shared_event.id;
+    let ok = author.send_event(shared_event).await.expect("send shared");
+    assert!(ok.accepted, "shared rejected: {}", ok.message);
+    let delivered = loop {
+        match foreign.recv_event(Duration::from_secs(5)).await {
+            Ok(RelayMessage::Event { event, .. }) if event.id == shared_id => break true,
+            Ok(_) => continue,
+            Err(buzz_test_client::TestClientError::Timeout) => break false,
+            Err(e) => panic!("unexpected error awaiting shared fan-out: {e}"),
+        }
+    };
+    assert!(
+        delivered,
+        "shared projection must fan out to foreign readers"
+    );
+
+    // Unshare: replace at the same coordinate without the tag. Subsequent
+    // foreign REQs must return nothing.
+    let ok = author
+        .send_event(catalog_event_at(&author_keys, &d_tag, false, t2))
+        .await
+        .expect("send unshare");
+    assert!(ok.accepted, "unshare rejected: {}", ok.message);
+
+    let sid_post = sub_id("post-unshare");
+    foreign
+        .subscribe(&sid_post, vec![coordinate_filter(&author_keys, &d_tag)])
+        .await
+        .expect("subscribe post");
+    let after = foreign
+        .collect_until_eose(&sid_post, Duration::from_secs(5))
+        .await
+        .expect("collect post");
+    assert!(
+        after.is_empty(),
+        "unsharing must retract the projection from foreign readers, got {} event(s)",
+        after.len()
+    );
+
+    author.disconnect().await.expect("disconnect author");
+    foreign.disconnect().await.expect("disconnect foreign");
+}
diff --git a/crates/buzz-voice/Cargo.toml b/crates/buzz-voice/Cargo.toml
new file mode 100644
index 0000000000..beff5b4a54
--- /dev/null
+++ b/crates/buzz-voice/Cargo.toml
@@ -0,0 +1,25 @@
+[package]
+name = "buzz-voice"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "Reusable local voice primitives for Buzz"
+
+[dependencies]
+atomic-write-file = "0.3"
+hex = { workspace = true }
+ort = { version = "=2.0.0-rc.12", default-features = false, features = ["api-24", "ndarray", "std"] }
+ort-sys = { version = "=2.0.0-rc.12", features = ["disable-linking"] }
+rand = "0.10"
+sentencepiece-model = "0.1"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+sha2 = { workspace = true }
+sherpa-onnx = "1.12"
+symphonia = { version = "0.5", default-features = false, features = ["aac", "aiff", "alac", "flac", "isomp4", "mp3", "ogg", "pcm", "vorbis", "wav"] }
+tokenizers = { version = "0.22", default-features = false, features = ["fancy-regex"] }
+
+[dev-dependencies]
+tempfile = "3"
diff --git a/crates/buzz-voice/src/imported.rs b/crates/buzz-voice/src/imported.rs
new file mode 100644
index 0000000000..6f0ea71cad
--- /dev/null
+++ b/crates/buzz-voice/src/imported.rs
@@ -0,0 +1,730 @@
+//! Device-local Pocket reference voice validation, canonicalization, and storage.
+
+use std::{
+    fs,
+    io::Write,
+    path::{Path, PathBuf},
+};
+
+use atomic_write_file::AtomicWriteFile;
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use symphonia::core::{
+    audio::SampleBuffer, codecs::DecoderOptions, errors::Error as SymphoniaError,
+    formats::FormatOptions, io::MediaSourceStream, meta::MetadataOptions, probe::Hint,
+};
+
+const MAX_SOURCE_BYTES: u64 = 25 * 1024 * 1024;
+const MIN_SAMPLE_RATE: u32 = 8_000;
+const MAX_SAMPLE_RATE: u32 = 96_000;
+const MIN_DURATION_SECONDS: f64 = 2.0;
+const MAX_DURATION_SECONDS: f64 = 30.0;
+pub const CANONICAL_SAMPLE_RATE: u32 = 32_000;
+const REGISTRY_VERSION: u32 = 1;
+const REGISTRY_FILE: &str = "registry.json";
+
+#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct ImportedVoice {
+    pub key: String,
+    pub display_name: String,
+    pub content_hash: String,
+    pub file_name: String,
+}
+
+#[derive(Default, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ImportedVoiceRegistry {
+    version: u32,
+    voices: Vec<ImportedVoice>,
+}
+
+#[derive(Clone, Debug)]
+pub struct PocketVoiceLibrary {
+    root: PathBuf,
+}
+
+impl PocketVoiceLibrary {
+    pub fn new(root: impl Into<PathBuf>) -> Self {
+        Self { root: root.into() }
+    }
+
+    pub fn root(&self) -> &Path {
+        &self.root
+    }
+
+    fn registry_path(&self) -> PathBuf {
+        self.root.join(REGISTRY_FILE)
+    }
+
+    pub fn load(&self) -> Result<Vec<ImportedVoice>, String> {
+        let path = self.registry_path();
+        if !path.exists() {
+            return Ok(Vec::new());
+        }
+        let bytes =
+            fs::read(&path).map_err(|error| format!("could not read imported voices: {error}"))?;
+        let registry: ImportedVoiceRegistry = serde_json::from_slice(&bytes)
+            .map_err(|error| format!("imported voice registry is invalid: {error}"))?;
+        if registry.version > REGISTRY_VERSION {
+            return Err(format!(
+                "imported voice registry version {} is newer than this Buzz build supports",
+                registry.version
+            ));
+        }
+        Ok(registry
+            .voices
+            .into_iter()
+            .filter(valid_identity)
+            .filter(|voice| self.resolve_file(voice).is_ok())
+            .collect())
+    }
+
+    fn save(&self, voices: &[ImportedVoice]) -> Result<(), String> {
+        ensure_storage_dir(&self.root)?;
+        let payload = serde_json::to_vec_pretty(&ImportedVoiceRegistry {
+            version: REGISTRY_VERSION,
+            voices: voices.to_vec(),
+        })
+        .map_err(|error| format!("could not encode imported voice registry: {error}"))?;
+        atomic_write_restricted(&self.registry_path(), &payload)
+            .map_err(|error| format!("could not save imported voice registry: {error}"))
+    }
+
+    pub fn resolve_file(&self, voice: &ImportedVoice) -> Result<PathBuf, String> {
+        if !valid_identity(voice) {
+            return Err("Imported voice registry contains an invalid file identity".to_string());
+        }
+        let path = self.root.join(&voice.file_name);
+        if !is_regular_file_without_symlink(&path) {
+            return Err(format!("Imported voice {} is missing", voice.display_name));
+        }
+        let bytes =
+            fs::read(&path).map_err(|error| format!("could not verify imported voice: {error}"))?;
+        if hex::encode(Sha256::digest(bytes)) != voice.content_hash {
+            return Err(format!(
+                "Imported voice {} does not match its content identity",
+                voice.display_name
+            ));
+        }
+        Ok(path)
+    }
+
+    pub fn find(&self, key: &str) -> Result<Option<ImportedVoice>, String> {
+        Ok(self.load()?.into_iter().find(|voice| voice.key == key))
+    }
+
+    pub fn import_path(&self, source: &Path) -> Result<ImportedVoice, String> {
+        let metadata = fs::metadata(source)
+            .map_err(|error| format!("could not inspect selected audio: {error}"))?;
+        if metadata.len() > MAX_SOURCE_BYTES {
+            return Err("Voice audio must be 25 MB or smaller".to_string());
+        }
+        let extension = source
+            .extension()
+            .and_then(|extension| extension.to_str())
+            .map(str::to_ascii_lowercase)
+            .ok_or_else(|| "Voice audio must have a supported file extension".to_string())?;
+        let samples = if extension == "wav" {
+            let source_bytes = fs::read(source)
+                .map_err(|error| format!("could not read selected audio: {error}"))?;
+            decode_wav(&source_bytes)?
+        } else {
+            decode_media(source, &extension)?
+        };
+        let canonical_samples = resample_linear(&samples.samples, samples.sample_rate);
+        let canonical = encode_pcm16_wav(&canonical_samples, CANONICAL_SAMPLE_RATE);
+        let hash = hex::encode(Sha256::digest(&canonical));
+        let key = format!("pocket:imported:{hash}");
+        let file_name = format!("{hash}.wav");
+        let display_name = source
+            .file_stem()
+            .and_then(|name| name.to_str())
+            .map(str::trim)
+            .filter(|name| !name.is_empty())
+            .unwrap_or("Imported voice")
+            .chars()
+            .take(80)
+            .collect::<String>();
+
+        ensure_storage_dir(&self.root)?;
+        let file_path = self.root.join(&file_name);
+        let file_created = !file_path.exists();
+        if file_created {
+            atomic_write_restricted(&file_path, &canonical)
+                .map_err(|error| format!("could not save imported voice audio: {error}"))?;
+        } else {
+            if !is_regular_file_without_symlink(&file_path) {
+                return Err("Imported voice storage contains an unsafe file entry".to_string());
+            }
+            let existing = fs::read(&file_path)
+                .map_err(|error| format!("could not verify imported voice audio: {error}"))?;
+            if hex::encode(Sha256::digest(&existing)) != hash {
+                return Err("Imported voice storage contains mismatched audio data".to_string());
+            }
+        }
+
+        let mut imported = ImportedVoice {
+            key,
+            display_name,
+            content_hash: hash,
+            file_name,
+        };
+        let mut voices = self.load()?;
+        if let Some(existing) = voices
+            .iter()
+            .find(|voice| voice.content_hash == imported.content_hash)
+        {
+            imported = existing.clone();
+        } else {
+            voices.push(imported.clone());
+        }
+        if let Err(error) = self.save(&voices) {
+            if file_created {
+                let _ = fs::remove_file(&file_path);
+            }
+            return Err(error);
+        }
+        Ok(imported)
+    }
+
+    pub fn delete(&self, key: &str) -> Result<(), String> {
+        let mut voices = self.load()?;
+        let index = voices
+            .iter()
+            .position(|voice| voice.key == key)
+            .ok_or_else(|| format!("Unknown imported voice: {key}"))?;
+        let previous_voices = voices.clone();
+        let removed = voices.remove(index);
+        self.save(&voices)?;
+        let path = self.root.join(removed.file_name);
+        match fs::remove_file(path) {
+            Ok(()) => Ok(()),
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
+            Err(error) => {
+                self.save(&previous_voices).map_err(|rollback_error| {
+                    format!(
+                        "Imported voice audio could not be deleted ({error}), and its registry \
+                         entry could not be restored ({rollback_error})"
+                    )
+                })?;
+                Err(format!(
+                    "Imported voice audio could not be deleted: {error}"
+                ))
+            }
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct PcmStats {
+    pub sample_count: usize,
+    pub sample_rate: u32,
+    pub duration_seconds: f64,
+    pub peak: f32,
+    pub rms: f32,
+    pub non_silent_samples: usize,
+}
+
+impl PcmStats {
+    pub fn analyze(samples: &[f32], sample_rate: u32) -> Self {
+        let peak = samples
+            .iter()
+            .filter(|sample| sample.is_finite())
+            .fold(0.0_f32, |peak, sample| peak.max(sample.abs()));
+        let square_sum = samples
+            .iter()
+            .filter(|sample| sample.is_finite())
+            .map(|sample| sample * sample)
+            .sum::<f32>();
+        let rms = if samples.is_empty() {
+            0.0
+        } else {
+            (square_sum / samples.len() as f32).sqrt()
+        };
+        Self {
+            sample_count: samples.len(),
+            sample_rate,
+            duration_seconds: if sample_rate == 0 {
+                0.0
+            } else {
+                samples.len() as f64 / f64::from(sample_rate)
+            },
+            peak,
+            rms,
+            non_silent_samples: samples
+                .iter()
+                .filter(|sample| sample.is_finite() && sample.abs() >= 0.001)
+                .count(),
+        }
+    }
+
+    pub fn is_non_silent(self) -> bool {
+        self.peak >= 0.001 && self.rms >= 0.0001 && self.non_silent_samples > 0
+    }
+}
+
+pub fn write_pcm16_wav(path: &Path, samples: &[f32], sample_rate: u32) -> Result<(), String> {
+    let bytes = encode_pcm16_wav(samples, sample_rate);
+    fs::write(path, bytes).map_err(|error| format!("could not write PCM evidence: {error}"))
+}
+
+fn ensure_storage_dir(path: &Path) -> Result<(), String> {
+    fs::create_dir_all(path)
+        .map_err(|error| format!("could not create local voice storage: {error}"))?;
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        fs::set_permissions(path, fs::Permissions::from_mode(0o700))
+            .map_err(|error| format!("could not restrict local voice storage: {error}"))?;
+    }
+    Ok(())
+}
+
+fn atomic_write_restricted(path: &Path, payload: &[u8]) -> Result<(), String> {
+    let resolved = fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf());
+    let mut file = AtomicWriteFile::open(&resolved)
+        .map_err(|error| format!("open {} for atomic write: {error}", resolved.display()))?;
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        file.set_permissions(fs::Permissions::from_mode(0o600))
+            .map_err(|error| format!("set {} permissions: {error}", resolved.display()))?;
+    }
+    file.write_all(payload)
+        .map_err(|error| format!("write {}: {error}", resolved.display()))?;
+    file.commit()
+        .map_err(|error| format!("commit {}: {error}", resolved.display()))
+}
+
+fn valid_hash(hash: &str) -> bool {
+    hash.len() == 64 && hash.bytes().all(|byte| byte.is_ascii_hexdigit())
+}
+
+fn valid_identity(voice: &ImportedVoice) -> bool {
+    valid_hash(&voice.content_hash)
+        && voice.key == format!("pocket:imported:{}", voice.content_hash)
+        && voice.file_name == format!("{}.wav", voice.content_hash)
+}
+
+fn is_regular_file_without_symlink(path: &Path) -> bool {
+    fs::symlink_metadata(path)
+        .is_ok_and(|metadata| metadata.file_type().is_file() && !metadata.file_type().is_symlink())
+}
+
+#[derive(Debug)]
+struct DecodedAudio {
+    sample_rate: u32,
+    samples: Vec<f32>,
+}
+
+fn decode_wav(bytes: &[u8]) -> Result<DecodedAudio, String> {
+    if bytes.len() < 12 || &bytes[..4] != b"RIFF" || &bytes[8..12] != b"WAVE" {
+        return Err("Selected file is not a valid RIFF/WAVE file".to_string());
+    }
+    let mut offset = 12usize;
+    let mut format = None;
+    let mut data = None;
+    while offset.checked_add(8).is_some_and(|end| end <= bytes.len()) {
+        let id = &bytes[offset..offset + 4];
+        let size =
+            u32::from_le_bytes(bytes[offset + 4..offset + 8].try_into().unwrap_or([0; 4])) as usize;
+        let start = offset + 8;
+        let end = start.checked_add(size).ok_or("WAV chunk size overflow")?;
+        if end > bytes.len() {
+            return Err("Selected WAV contains a truncated chunk".to_string());
+        }
+        if id == b"fmt " {
+            format = Some(&bytes[start..end]);
+        } else if id == b"data" {
+            data = Some(&bytes[start..end]);
+        }
+        offset = end + (size & 1);
+    }
+    let format = format.ok_or("Selected WAV has no format chunk")?;
+    let data = data.ok_or("Selected WAV has no audio data")?;
+    if format.len() < 16 {
+        return Err("Selected WAV has an invalid format chunk".to_string());
+    }
+    let encoding = u16::from_le_bytes(format[0..2].try_into().unwrap_or([0; 2]));
+    let encoding = if encoding == 0xfffe && format.len() >= 40 {
+        u16::from_le_bytes(format[24..26].try_into().unwrap_or([0; 2]))
+    } else {
+        encoding
+    };
+    let channels = u16::from_le_bytes(format[2..4].try_into().unwrap_or([0; 2]));
+    let sample_rate = u32::from_le_bytes(format[4..8].try_into().unwrap_or([0; 4]));
+    let block_align = u16::from_le_bytes(format[12..14].try_into().unwrap_or([0; 2])) as usize;
+    let bits = u16::from_le_bytes(format[14..16].try_into().unwrap_or([0; 2]));
+    if channels == 0 || channels > 8 {
+        return Err("Voice WAV must contain between 1 and 8 channels".to_string());
+    }
+    if !(MIN_SAMPLE_RATE..=MAX_SAMPLE_RATE).contains(&sample_rate) {
+        return Err("Voice WAV sample rate must be between 8 and 96 kHz".to_string());
+    }
+    let bytes_per_sample = usize::from(bits.div_ceil(8));
+    if block_align != bytes_per_sample * usize::from(channels)
+        || block_align == 0
+        || data.len() % block_align != 0
+    {
+        return Err("Voice WAV has invalid sample alignment".to_string());
+    }
+    if !matches!((encoding, bits), (1, 8 | 16 | 24 | 32) | (3, 32)) {
+        return Err("Voice WAV must contain PCM or 32-bit float audio".to_string());
+    }
+    let frames = data.len() / block_align;
+    let duration = frames as f64 / f64::from(sample_rate);
+    if !(MIN_DURATION_SECONDS..=MAX_DURATION_SECONDS).contains(&duration) {
+        return Err("Voice WAV must be between 2 and 30 seconds long".to_string());
+    }
+
+    let mut samples = Vec::with_capacity(frames);
+    for frame in data.chunks_exact(block_align) {
+        let mut mono = 0.0_f32;
+        for chunk in frame.chunks_exact(bytes_per_sample) {
+            let sample = match (encoding, bits) {
+                (1, 8) => (f32::from(chunk[0]) - 128.0) / 128.0,
+                (1, 16) => f32::from(i16::from_le_bytes([chunk[0], chunk[1]])) / 32768.0,
+                (1, 24) => {
+                    let raw = i32::from_le_bytes([
+                        chunk[0],
+                        chunk[1],
+                        chunk[2],
+                        if chunk[2] & 0x80 == 0 { 0 } else { 0xff },
+                    ]);
+                    raw as f32 / 8_388_608.0
+                }
+                (1, 32) => {
+                    i32::from_le_bytes(chunk.try_into().map_err(|_| "invalid PCM sample")?) as f32
+                        / 2_147_483_648.0
+                }
+                (3, 32) => f32::from_le_bytes(
+                    chunk
+                        .try_into()
+                        .map_err(|_| "invalid floating-point sample")?,
+                ),
+                _ => unreachable!(),
+            };
+            if !sample.is_finite() {
+                return Err("Voice WAV contains non-finite samples".to_string());
+            }
+            mono += sample;
+        }
+        samples.push((mono / f32::from(channels)).clamp(-1.0, 1.0));
+    }
+    let stats = PcmStats::analyze(&samples, sample_rate);
+    if !stats.is_non_silent() {
+        return Err("Voice WAV is silent or too quiet to clone".to_string());
+    }
+    Ok(DecodedAudio {
+        sample_rate,
+        samples,
+    })
+}
+
+fn decode_media(source: &Path, extension: &str) -> Result<DecodedAudio, String> {
+    let supported = ["m4a", "mp3", "flac", "ogg", "oga", "aif", "aiff"];
+    if !supported.contains(&extension) {
+        return Err(format!(
+            "Unsupported voice audio format .{extension}. Choose WAV, M4A, MP3, FLAC, OGG, or AIFF"
+        ));
+    }
+
+    let file = fs::File::open(source)
+        .map_err(|error| format!("could not read selected audio: {error}"))?;
+    let media = MediaSourceStream::new(Box::new(file), Default::default());
+    let mut hint = Hint::new();
+    hint.with_extension(extension);
+    let probed = symphonia::default::get_probe()
+        .format(
+            &hint,
+            media,
+            &FormatOptions::default(),
+            &MetadataOptions::default(),
+        )
+        .map_err(|error| format!("could not recognize selected audio: {error}"))?;
+    let mut format = probed.format;
+    let track = format
+        .default_track()
+        .ok_or_else(|| "Selected audio has no decodable track".to_string())?;
+    let track_id = track.id;
+    let mut decoder = symphonia::default::get_codecs()
+        .make(&track.codec_params, &DecoderOptions::default())
+        .map_err(|error| format!("could not initialize audio decoder: {error}"))?;
+    let mut sample_rate = None;
+    let mut samples = Vec::new();
+
+    loop {
+        let packet = match format.next_packet() {
+            Ok(packet) => packet,
+            Err(SymphoniaError::ResetRequired) => {
+                return Err("Selected audio changes format mid-stream".to_string());
+            }
+            Err(SymphoniaError::IoError(error))
+                if error.kind() == std::io::ErrorKind::UnexpectedEof =>
+            {
+                break;
+            }
+            Err(error) => return Err(format!("could not read selected audio: {error}")),
+        };
+        if packet.track_id() != track_id {
+            continue;
+        }
+        let decoded = match decoder.decode(&packet) {
+            Ok(decoded) => decoded,
+            Err(SymphoniaError::DecodeError(_)) => continue,
+            Err(error) => return Err(format!("could not decode selected audio: {error}")),
+        };
+        let spec = *decoded.spec();
+        if !(MIN_SAMPLE_RATE..=MAX_SAMPLE_RATE).contains(&spec.rate) {
+            return Err("Voice audio sample rate must be between 8 and 96 kHz".to_string());
+        }
+        if sample_rate.is_some_and(|rate| rate != spec.rate) {
+            return Err("Selected audio changes sample rate mid-stream".to_string());
+        }
+        sample_rate = Some(spec.rate);
+        let channels = spec.channels.count();
+        if channels == 0 || channels > 8 {
+            return Err("Voice audio must contain between 1 and 8 channels".to_string());
+        }
+        let mut buffer = SampleBuffer::<f32>::new(decoded.capacity() as u64, spec);
+        buffer.copy_interleaved_ref(decoded);
+        for frame in buffer.samples().chunks_exact(channels) {
+            let mono = frame.iter().copied().sum::<f32>() / channels as f32;
+            if !mono.is_finite() {
+                return Err("Voice audio contains non-finite samples".to_string());
+            }
+            samples.push(mono.clamp(-1.0, 1.0));
+        }
+        if samples.len() as f64 > MAX_DURATION_SECONDS * f64::from(spec.rate) {
+            return Err("Voice audio must be between 2 and 30 seconds long".to_string());
+        }
+    }
+
+    let sample_rate =
+        sample_rate.ok_or_else(|| "Selected audio contains no samples".to_string())?;
+    validate_decoded_audio(&samples, sample_rate)?;
+    Ok(DecodedAudio {
+        sample_rate,
+        samples,
+    })
+}
+
+fn validate_decoded_audio(samples: &[f32], sample_rate: u32) -> Result<(), String> {
+    let stats = PcmStats::analyze(samples, sample_rate);
+    if !(MIN_DURATION_SECONDS..=MAX_DURATION_SECONDS).contains(&stats.duration_seconds) {
+        return Err("Voice audio must be between 2 and 30 seconds long".to_string());
+    }
+    if !stats.is_non_silent() {
+        return Err("Voice audio is silent or too quiet to clone".to_string());
+    }
+    Ok(())
+}
+
+fn resample_linear(samples: &[f32], source_rate: u32) -> Vec<f32> {
+    if source_rate == CANONICAL_SAMPLE_RATE {
+        return samples.to_vec();
+    }
+    let output_len = ((samples.len() as u64 * u64::from(CANONICAL_SAMPLE_RATE)
+        + u64::from(source_rate) / 2)
+        / u64::from(source_rate)) as usize;
+    (0..output_len)
+        .map(|index| {
+            let source = index as f64 * f64::from(source_rate) / f64::from(CANONICAL_SAMPLE_RATE);
+            let left = source.floor() as usize;
+            let fraction = (source - left as f64) as f32;
+            let a = samples[left.min(samples.len() - 1)];
+            let b = samples[(left + 1).min(samples.len() - 1)];
+            a + (b - a) * fraction
+        })
+        .collect()
+}
+
+fn encode_pcm16_wav(samples: &[f32], sample_rate: u32) -> Vec<u8> {
+    let data_len = (samples.len() * 2) as u32;
+    let mut bytes = Vec::with_capacity(44 + data_len as usize);
+    bytes.extend_from_slice(b"RIFF");
+    bytes.extend_from_slice(&(36 + data_len).to_le_bytes());
+    bytes.extend_from_slice(b"WAVEfmt ");
+    bytes.extend_from_slice(&16_u32.to_le_bytes());
+    bytes.extend_from_slice(&1_u16.to_le_bytes());
+    bytes.extend_from_slice(&1_u16.to_le_bytes());
+    bytes.extend_from_slice(&sample_rate.to_le_bytes());
+    bytes.extend_from_slice(&(sample_rate * 2).to_le_bytes());
+    bytes.extend_from_slice(&2_u16.to_le_bytes());
+    bytes.extend_from_slice(&16_u16.to_le_bytes());
+    bytes.extend_from_slice(b"data");
+    bytes.extend_from_slice(&data_len.to_le_bytes());
+    for sample in samples {
+        let value = (sample.clamp(-1.0, 1.0) * f32::from(i16::MAX)).round() as i16;
+        bytes.extend_from_slice(&value.to_le_bytes());
+    }
+    bytes
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn fixture(sample_rate: u32, seconds: usize, amplitude: f32) -> Vec<u8> {
+        let samples = (0..sample_rate as usize * seconds)
+            .map(|index| {
+                amplitude
+                    * (std::f32::consts::TAU * 220.0 * index as f32 / sample_rate as f32).sin()
+            })
+            .collect::<Vec<_>>();
+        encode_pcm16_wav(&samples, sample_rate)
+    }
+
+    fn stereo_fixture(sample_rate: u32, seconds: usize, amplitude: f32) -> Vec<u8> {
+        let mono = fixture(sample_rate, seconds, amplitude);
+        let mono_data = &mono[44..];
+        let mut stereo_data = Vec::with_capacity(mono_data.len() * 2);
+        for sample in mono_data.chunks_exact(2) {
+            stereo_data.extend_from_slice(sample);
+            stereo_data.extend_from_slice(sample);
+        }
+        let mut stereo = mono[..44].to_vec();
+        stereo[4..8].copy_from_slice(&(36 + stereo_data.len() as u32).to_le_bytes());
+        stereo[22..24].copy_from_slice(&2_u16.to_le_bytes());
+        stereo[28..32].copy_from_slice(&(sample_rate * 4).to_le_bytes());
+        stereo[32..34].copy_from_slice(&4_u16.to_le_bytes());
+        stereo[40..44].copy_from_slice(&(stereo_data.len() as u32).to_le_bytes());
+        stereo.extend_from_slice(&stereo_data);
+        stereo
+    }
+
+    #[test]
+    fn imports_persists_reloads_and_deletes_canonical_voice() {
+        let temp = tempfile::tempdir().expect("temp voice workspace");
+        let source = temp.path().join("My voice.wav");
+        fs::write(&source, fixture(44_100, 2, 0.5)).expect("write source");
+        let library = PocketVoiceLibrary::new(temp.path().join("library"));
+
+        let imported = library.import_path(&source).expect("import voice");
+        assert!(imported.key.starts_with("pocket:imported:"));
+        assert_eq!(imported.display_name, "My voice");
+
+        let relaunched = PocketVoiceLibrary::new(library.root());
+        assert_eq!(
+            relaunched.load().expect("reload registry"),
+            vec![imported.clone()]
+        );
+        let stored = relaunched
+            .resolve_file(&imported)
+            .expect("resolve stored voice");
+        let decoded = decode_wav(&fs::read(&stored).expect("read stored voice"))
+            .expect("decode canonical voice");
+        assert_eq!(decoded.sample_rate, CANONICAL_SAMPLE_RATE);
+        assert_eq!(decoded.samples.len(), CANONICAL_SAMPLE_RATE as usize * 2);
+
+        assert_eq!(
+            relaunched.import_path(&source).expect("idempotent import"),
+            imported
+        );
+        assert_eq!(relaunched.load().expect("deduplicated registry").len(), 1);
+
+        relaunched.delete(&imported.key).expect("delete voice");
+        assert!(relaunched.load().expect("empty registry").is_empty());
+        assert!(!stored.exists());
+    }
+
+    #[test]
+    fn common_stereo_audio_is_downmixed_to_canonical_mono() {
+        let temp = tempfile::tempdir().expect("temp voice workspace");
+        let source = temp.path().join("stereo.wav");
+        fs::write(&source, stereo_fixture(44_100, 2, 0.5)).expect("write stereo");
+        let library = PocketVoiceLibrary::new(temp.path().join("library"));
+
+        let imported = library.import_path(&source).expect("import stereo");
+        let stored = library
+            .resolve_file(&imported)
+            .expect("resolve stored voice");
+        let decoded = decode_wav(&fs::read(stored).expect("read stored voice"))
+            .expect("decode canonical voice");
+        assert_eq!(decoded.sample_rate, CANONICAL_SAMPLE_RATE);
+        assert_eq!(decoded.samples.len(), CANONICAL_SAMPLE_RATE as usize * 2);
+    }
+
+    #[test]
+    #[ignore = "requires BUZZ_VOICE_IMPORT_TEST_DIR with common-format fixtures"]
+    fn imports_common_audio_format_fixtures() {
+        let fixtures =
+            PathBuf::from(std::env::var("BUZZ_VOICE_IMPORT_TEST_DIR").expect("fixture directory"));
+        let temp = tempfile::tempdir().expect("temp voice workspace");
+        let library = PocketVoiceLibrary::new(temp.path().join("library"));
+
+        for file_name in [
+            "voice.wav",
+            "voice.m4a",
+            "voice.mp3",
+            "voice.flac",
+            "voice.ogg",
+            "voice.aiff",
+        ] {
+            let imported = library
+                .import_path(&fixtures.join(file_name))
+                .unwrap_or_else(|error| panic!("import {file_name}: {error}"));
+            let stored = library
+                .resolve_file(&imported)
+                .unwrap_or_else(|error| panic!("resolve {file_name}: {error}"));
+            let decoded = decode_wav(&fs::read(stored).expect("read canonical voice"))
+                .expect("decode canonical voice");
+            assert_eq!(decoded.sample_rate, CANONICAL_SAMPLE_RATE);
+            assert!(decoded.samples.len() >= CANONICAL_SAMPLE_RATE as usize * 2);
+        }
+    }
+
+    #[test]
+    fn invalid_unsupported_and_silent_files_do_not_mutate_registry() {
+        let temp = tempfile::tempdir().expect("temp voice workspace");
+        let library = PocketVoiceLibrary::new(temp.path().join("library"));
+
+        let garbage = temp.path().join("garbage.wav");
+        fs::write(&garbage, b"not a wave").expect("write garbage");
+        assert!(library
+            .import_path(&garbage)
+            .expect_err("garbage rejected")
+            .contains("RIFF/WAVE"));
+
+        let silent = temp.path().join("silent.wav");
+        fs::write(&silent, fixture(32_000, 2, 0.0)).expect("write silence");
+        assert!(library
+            .import_path(&silent)
+            .expect_err("silence rejected")
+            .contains("silent"));
+
+        let unsupported_container = temp.path().join("voice.txt");
+        fs::write(&unsupported_container, b"not audio").expect("write unsupported container");
+        assert!(library
+            .import_path(&unsupported_container)
+            .expect_err("container rejected")
+            .contains("Unsupported voice audio format"));
+
+        let mut unsupported = fixture(32_000, 2, 0.5);
+        unsupported[20..22].copy_from_slice(&6_u16.to_le_bytes());
+        let unsupported_path = temp.path().join("unsupported.wav");
+        fs::write(&unsupported_path, unsupported).expect("write unsupported");
+        assert!(library
+            .import_path(&unsupported_path)
+            .expect_err("unsupported rejected")
+            .contains("PCM or 32-bit float"));
+
+        assert!(library.load().expect("unchanged registry").is_empty());
+    }
+
+    #[test]
+    fn pcm_analysis_distinguishes_signal_from_silence() {
+        let signal = (0..24_000)
+            .map(|index| (std::f32::consts::TAU * 440.0 * index as f32 / 24_000.0).sin() * 0.5)
+            .collect::<Vec<_>>();
+        let signal_stats = PcmStats::analyze(&signal, 24_000);
+        assert!(signal_stats.is_non_silent());
+        assert_eq!(signal_stats.duration_seconds, 1.0);
+        assert!(signal_stats.peak > 0.49);
+        assert!(signal_stats.rms > 0.3);
+
+        let silence = vec![0.0; 24_000];
+        assert!(!PcmStats::analyze(&silence, 24_000).is_non_silent());
+    }
+}
diff --git a/crates/buzz-voice/src/lib.rs b/crates/buzz-voice/src/lib.rs
new file mode 100644
index 0000000000..e4b4ebfed3
--- /dev/null
+++ b/crates/buzz-voice/src/lib.rs
@@ -0,0 +1,23 @@
+//! Reusable local voice primitives for Buzz.
+
+pub mod imported;
+pub mod pocket;
+
+pub use pocket::{
+    april_model_info, load_text_to_speech, load_voice_style, PocketModelInfo, PocketTts,
+    VoiceStyle, DEFAULT_VOICE, SAMPLE_RATE, VOICE_FILE_EXT,
+};
+
+/// One immutable artifact required by the April Pocket bundle.
+///
+/// `filename` is the bundle-relative file name, `sha256` pins its contents,
+/// `size_bytes` supports download progress and validation, and `quantized`
+/// identifies the INT8 components.
+pub type PocketModelArtifact = pocket::PocketModelArtifact;
+
+/// Language bundle selected from the pinned export.
+pub const APRIL_BUNDLE_ID: &str = pocket::APRIL_BUNDLE_ID;
+/// Pinned upstream export repository.
+pub const APRIL_MODEL_ID: &str = pocket::APRIL_MODEL_ID;
+/// Pinned revision containing the April bundle.
+pub const APRIL_MODEL_REVISION: &str = pocket::APRIL_MODEL_REVISION;
diff --git a/crates/buzz-voice/src/pocket.rs b/crates/buzz-voice/src/pocket.rs
new file mode 100644
index 0000000000..0c6174a8dc
--- /dev/null
+++ b/crates/buzz-voice/src/pocket.rs
@@ -0,0 +1,167 @@
+//! April 2026 Pocket TTS engine for Buzz Desktop.
+//!
+//! The `english_2026-04` bundle uses SentencePiece tokenization, a learned
+//! voice BOS embedding, recurrent FlowLM state, and stateful Mimi decoding.
+//! Buzz selects the upstream three-graph INT8 variant while retaining the
+//! full-precision Mimi encoder and text conditioner specified by that variant.
+//!
+//! ## Attribution
+//!
+//! - Pocket TTS and Mimi: Kyutai, CC-BY-4.0.
+//! - ONNX export: KevinAHM/pocket-tts-onnx, CC-BY-4.0.
+//! - Reference voice: Kyutai's Mary preset (VCTK p333), CC-BY-4.0.
+//!
+//! `huddle::models` writes the complete attribution beside the cached bytes.
+
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+
+use sherpa_onnx::Wave;
+
+#[path = "pocket_april.rs"]
+mod pocket_april;
+#[path = "pocket_models.rs"]
+mod pocket_models;
+
+use pocket_april::{prepare_april_prompt, AprilPocketTts};
+pub use pocket_models::{
+    april_model_info, PocketModelArtifact, PocketModelInfo, APRIL_BUNDLE_ID, APRIL_MODEL_ID,
+    APRIL_MODEL_REVISION,
+};
+
+/// Pocket TTS emits 24 kHz mono PCM.
+pub const SAMPLE_RATE: u32 = 24_000;
+
+/// Bundled reference voice name without its extension.
+pub const DEFAULT_VOICE: &str = "reference_sample";
+
+/// Pocket voice files are reference WAVs.
+pub const VOICE_FILE_EXT: &str = "wav";
+
+const TTS_NUM_THREADS: usize = 1;
+
+/// Loaded reference voice samples and their original sample rate.
+#[derive(Debug, Clone)]
+pub struct VoiceStyle {
+    samples: Vec<f32>,
+    sample_rate: i32,
+}
+
+/// Load a Pocket reference voice WAV from disk.
+pub fn load_voice_style(path: &Path) -> Result<VoiceStyle, String> {
+    let path_str = path
+        .to_str()
+        .ok_or_else(|| format!("voice path is not valid UTF-8: {}", path.display()))?;
+    let wave = Wave::read(path_str)
+        .ok_or_else(|| format!("could not read voice WAV at {}", path.display()))?;
+    let samples = wave.samples().to_vec();
+    if samples.is_empty() {
+        return Err(format!("voice WAV is empty: {}", path.display()));
+    }
+    Ok(VoiceStyle {
+        samples,
+        sample_rate: wave.sample_rate(),
+    })
+}
+
+/// Resident April INT8 Pocket TTS engine.
+pub struct PocketTts {
+    inner: Mutex<AprilPocketTts>,
+}
+
+/// Load Buzz Desktop's pinned April INT8 model.
+pub fn load_text_to_speech(model_dir: &str) -> Result<PocketTts, String> {
+    let dir = PathBuf::from(model_dir);
+    for artifact in april_model_info().artifacts {
+        let path = dir.join(artifact.filename);
+        if !path.is_file() {
+            return Err(format!(
+                "incomplete Pocket TTS {} INT8 bundle: missing {}",
+                APRIL_BUNDLE_ID,
+                path.display()
+            ));
+        }
+    }
+    Ok(PocketTts {
+        inner: Mutex::new(AprilPocketTts::load(&dir, TTS_NUM_THREADS)?),
+    })
+}
+
+impl PocketTts {
+    /// Split text into synthesis units that satisfy the bundle's exact
+    /// 50-token input limit.
+    pub fn split_text_into_chunks(&self, text: &str) -> Result<Vec<String>, String> {
+        let Some(prepared) = prepare_april_prompt(text) else {
+            return Ok(Vec::new());
+        };
+        self.inner
+            .lock()
+            .map_err(|_| "Pocket TTS engine lock poisoned".to_string())?
+            .split_prompt(&prepared)
+    }
+
+    /// Synthesize text with the supplied reference voice.
+    ///
+    /// Pocket detects language from text and this model uses one synthesis
+    /// step, so `_lang` and `_steps` intentionally do not affect output.
+    pub fn synth_chunk(
+        &self,
+        text: &str,
+        _lang: &str,
+        style: &VoiceStyle,
+        _steps: usize,
+    ) -> Result<Vec<f32>, String> {
+        let Some(prepared) = prepare_april_prompt(text) else {
+            return Ok(Vec::new());
+        };
+        let mut engine = self
+            .inner
+            .lock()
+            .map_err(|_| "Pocket TTS engine lock poisoned".to_string())?;
+        let chunks = engine.split_prompt(&prepared)?;
+        let mut samples = Vec::new();
+        for chunk in chunks {
+            let prepared = prepare_april_prompt(&chunk)
+                .ok_or_else(|| "Pocket TTS prompt chunk became empty".to_string())?;
+            samples.extend(engine.synth_chunk(&prepared, style)?);
+        }
+        Ok(samples)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn desktop_model_is_april_int8_only() {
+        let info = april_model_info();
+        assert_eq!(info.max_token_per_chunk, 50);
+        assert_eq!(info.sample_rate, SAMPLE_RATE);
+        assert!(info
+            .artifacts
+            .iter()
+            .any(|artifact| artifact.filename == "flow_lm_main_int8.onnx"));
+        assert!(!info
+            .artifacts
+            .iter()
+            .any(|artifact| artifact.filename == "flow_lm_main.onnx"));
+    }
+
+    #[test]
+    #[ignore = "requires BUZZ_POCKET_TEST_MODEL_DIR"]
+    fn production_api_emits_non_silent_april_int8_pcm() {
+        let dir = std::env::var("BUZZ_POCKET_TEST_MODEL_DIR")
+            .expect("set BUZZ_POCKET_TEST_MODEL_DIR to an April INT8 model directory");
+        let engine = load_text_to_speech(&dir).expect("load April INT8 engine");
+        let style = load_voice_style(&Path::new(&dir).join("reference_sample.wav"))
+            .expect("load reference voice");
+        let samples = engine
+            .synth_chunk("Bright birds begin beside the bay.", "en", &style, 1)
+            .expect("synthesize through the production API");
+
+        assert!(!samples.is_empty());
+        assert!(samples.iter().all(|sample| sample.is_finite()));
+        assert!(samples.iter().any(|sample| sample.abs() > 1.0e-6));
+    }
+}
diff --git a/crates/buzz-voice/src/pocket_april.rs b/crates/buzz-voice/src/pocket_april.rs
new file mode 100644
index 0000000000..43826df5c9
--- /dev/null
+++ b/crates/buzz-voice/src/pocket_april.rs
@@ -0,0 +1,940 @@
+//! Native ONNX loader for Pocket TTS `english_2026-04`.
+//!
+//! The bundle uses SentencePiece, prepends a learned BOS voice embedding, and
+//! describes recurrent state tensors in `bundle.json`. This module supplies
+//! that frontend and state loop while reusing the ONNX Runtime linked by the
+//! Desktop speech stack.
+
+use std::borrow::Cow;
+use std::f32::consts::TAU;
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use ort::session::{Session, SessionInputValue};
+use ort::value::{DynValue, Tensor};
+use rand::{Rng, RngExt};
+use sentencepiece_model::SentencePieceModel;
+use serde::Deserialize;
+use sherpa_onnx::LinearResampler;
+use tokenizers::models::unigram::Unigram;
+use tokenizers::pre_tokenizers::metaspace::{Metaspace, PrependScheme};
+use tokenizers::Tokenizer;
+
+use super::VoiceStyle;
+
+const FILE_BUNDLE: &str = "bundle.json";
+const FILE_MIMI_ENCODER: &str = "mimi_encoder.onnx";
+const FILE_TEXT_CONDITIONER: &str = "text_conditioner.onnx";
+const FILE_FLOW_MAIN_INT8: &str = "flow_lm_main_int8.onnx";
+const FILE_FLOW_INT8: &str = "flow_lm_flow_int8.onnx";
+const FILE_MIMI_DECODER_INT8: &str = "mimi_decoder_int8.onnx";
+
+const MODEL_LANGUAGE: &str = "english_2026-04";
+const DEFAULT_TEMPERATURE: f32 = 0.7;
+const EOS_LOGIT_THRESHOLD: f32 = -4.0;
+const DECODER_CHUNK_FRAMES: usize = 12;
+const TOKENS_PER_SECOND_ESTIMATE: f32 = 3.0;
+const GENERATION_SECONDS_PADDING: f32 = 2.0;
+
+#[derive(Debug, Deserialize)]
+struct Bundle {
+    schema_version: u32,
+    language: String,
+    sample_rate: usize,
+    frame_rate: f32,
+    samples_per_frame: usize,
+    latent_dim: usize,
+    conditioning_dim: usize,
+    insert_bos_before_voice: bool,
+    pad_with_spaces_for_short_inputs: bool,
+    remove_semicolons: bool,
+    model_recommended_frames_after_eos: Option<usize>,
+    max_token_per_chunk: usize,
+    tokenizer_file: String,
+    bos_before_voice_file: String,
+    flow_lm_state_manifest: Vec<StateSpec>,
+    mimi_state_manifest: Vec<StateSpec>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+struct StateSpec {
+    input_name: String,
+    output_name: String,
+    dtype: StateDtype,
+    shape: Vec<i64>,
+    fill: StateFill,
+}
+
+#[derive(Debug, Clone, Copy, Deserialize)]
+#[serde(rename_all = "lowercase")]
+enum StateDtype {
+    #[serde(rename = "float32")]
+    Float32,
+    #[serde(rename = "int64")]
+    Int64,
+    Bool,
+}
+
+#[derive(Debug, Clone, Copy, Deserialize)]
+#[serde(rename_all = "lowercase")]
+enum StateFill {
+    Empty,
+    Nan,
+    Ones,
+    Zeros,
+}
+
+struct StateValue {
+    spec: StateSpec,
+    value: DynValue,
+}
+
+struct CachedVoice {
+    samples_ptr: usize,
+    samples_len: usize,
+    sample_rate: i32,
+    embeddings: Vec<f32>,
+}
+
+pub(crate) struct AprilPocketTts {
+    bundle: Bundle,
+    tokenizer: Tokenizer,
+    bos_embedding: Vec<f32>,
+    mimi_encoder: Session,
+    text_conditioner: Session,
+    flow_main: Session,
+    flow: Session,
+    mimi_decoder: Session,
+    cached_voice: Option<CachedVoice>,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct AprilPreparedPrompt {
+    pub(crate) text: String,
+    pub(crate) frames_after_eos: usize,
+}
+
+pub(crate) fn prepare_april_prompt(input: &str) -> Option<AprilPreparedPrompt> {
+    let trimmed = input.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+
+    let mut cleaned = String::with_capacity(trimmed.len());
+    let mut last_was_space = false;
+    for ch in trimmed.chars() {
+        if ch.is_whitespace() {
+            if !last_was_space {
+                cleaned.push(' ');
+            }
+            last_was_space = true;
+        } else {
+            cleaned.push(ch);
+            last_was_space = false;
+        }
+    }
+
+    let first = cleaned.chars().next().expect("cleaned non-empty above");
+    if first.is_lowercase() {
+        let upper: String = first.to_uppercase().collect();
+        let mut iter = cleaned.chars();
+        iter.next();
+        cleaned = upper + iter.as_str();
+    }
+
+    let last = cleaned
+        .chars()
+        .next_back()
+        .expect("cleaned non-empty above");
+    if last.is_alphanumeric() {
+        cleaned.push('.');
+    }
+
+    let word_count = cleaned.split_whitespace().count();
+    Some(AprilPreparedPrompt {
+        text: cleaned,
+        // Mirror the bundle's upstream heuristic: three generated frames plus
+        // two trailing frames for short prompts, one plus two otherwise.
+        frames_after_eos: if word_count <= 4 { 5 } else { 3 },
+    })
+}
+
+impl AprilPocketTts {
+    pub(crate) fn load(dir: &Path, num_threads: usize) -> Result<Self, String> {
+        if num_threads == 0 {
+            return Err("Pocket TTS num_threads must be at least 1".to_string());
+        }
+        let bundle_path = dir.join(FILE_BUNDLE);
+        let bundle: Bundle = serde_json::from_slice(
+            &fs::read(&bundle_path)
+                .map_err(|err| format!("read {}: {err}", bundle_path.display()))?,
+        )
+        .map_err(|err| format!("parse {}: {err}", bundle_path.display()))?;
+
+        if bundle.schema_version != 2 {
+            return Err(format!(
+                "unsupported Pocket TTS bundle schema {} in {}",
+                bundle.schema_version,
+                bundle_path.display()
+            ));
+        }
+        if bundle.language != MODEL_LANGUAGE {
+            return Err(format!(
+                "expected Pocket TTS language {MODEL_LANGUAGE}, got {}",
+                bundle.language
+            ));
+        }
+        if bundle.sample_rate != 24_000
+            || bundle.frame_rate != 12.5
+            || bundle.samples_per_frame != 1_920
+            || bundle.latent_dim != 32
+            || bundle.conditioning_dim != 1024
+        {
+            return Err(format!(
+                "unexpected Pocket TTS dimensions: sample_rate={}, frame_rate={}, samples_per_frame={}, latent_dim={}, conditioning_dim={}",
+                bundle.sample_rate,
+                bundle.frame_rate,
+                bundle.samples_per_frame,
+                bundle.latent_dim,
+                bundle.conditioning_dim
+            ));
+        }
+        if !bundle.insert_bos_before_voice {
+            return Err("April Pocket TTS bundle must insert BOS before voice".to_string());
+        }
+        if bundle.pad_with_spaces_for_short_inputs
+            || bundle.remove_semicolons
+            || bundle.model_recommended_frames_after_eos.is_some()
+            || bundle.max_token_per_chunk != 50
+        {
+            return Err("unsupported April Pocket TTS prompt-policy metadata".to_string());
+        }
+
+        let tokenizer_path = dir.join(&bundle.tokenizer_file);
+        let tokenizer = load_tokenizer(&tokenizer_path)?;
+        let bos_path = dir.join(&bundle.bos_before_voice_file);
+        let bos_embedding = read_npy_f32(&bos_path)?;
+        if bos_embedding.len() != bundle.conditioning_dim {
+            return Err(format!(
+                "{} has {} values; expected {}",
+                bos_path.display(),
+                bos_embedding.len(),
+                bundle.conditioning_dim
+            ));
+        }
+
+        let flow_main = FILE_FLOW_MAIN_INT8;
+        let flow = FILE_FLOW_INT8;
+        let mimi_decoder = FILE_MIMI_DECODER_INT8;
+
+        Ok(Self {
+            // The INT8 layout quantizes only the three generation graphs;
+            // voice encoding and text conditioning remain full precision.
+            mimi_encoder: load_session(dir.join(FILE_MIMI_ENCODER), num_threads)?,
+            text_conditioner: load_session(dir.join(FILE_TEXT_CONDITIONER), num_threads)?,
+            flow_main: load_session(dir.join(flow_main), num_threads)?,
+            flow: load_session(dir.join(flow), num_threads)?,
+            mimi_decoder: load_session(dir.join(mimi_decoder), num_threads)?,
+            bundle,
+            tokenizer,
+            bos_embedding,
+            cached_voice: None,
+        })
+    }
+
+    pub(crate) fn split_prompt(
+        &self,
+        prepared: &AprilPreparedPrompt,
+    ) -> Result<Vec<String>, String> {
+        if self.token_count(&prepared.text)? <= self.bundle.max_token_per_chunk {
+            return Ok(vec![prepared.text.clone()]);
+        }
+
+        let mut chunks = Vec::new();
+        let mut current = String::new();
+        for word in prepared.text.split_whitespace() {
+            let candidate = if current.is_empty() {
+                word.to_string()
+            } else {
+                format!("{current} {word}")
+            };
+            if self.prepared_token_count(&candidate)? <= self.bundle.max_token_per_chunk {
+                current = candidate;
+                continue;
+            }
+            if !current.is_empty() {
+                chunks.push(std::mem::take(&mut current));
+            }
+
+            if self.prepared_token_count(word)? <= self.bundle.max_token_per_chunk {
+                current = word.to_string();
+                continue;
+            }
+
+            let mut fragment = String::new();
+            for ch in word.chars() {
+                let candidate = format!("{fragment}{ch}");
+                if !fragment.is_empty()
+                    && self.prepared_token_count(&candidate)? > self.bundle.max_token_per_chunk
+                {
+                    chunks.push(std::mem::take(&mut fragment));
+                }
+                fragment.push(ch);
+            }
+            current = fragment;
+        }
+        if !current.is_empty() {
+            chunks.push(current);
+        }
+
+        chunks
+            .into_iter()
+            .map(|text| {
+                let chunk = prepare_april_prompt(&text)
+                    .ok_or_else(|| "Pocket TTS prompt chunk became empty".to_string())?;
+                let token_count = self.token_count(&chunk.text)?;
+                if token_count > self.bundle.max_token_per_chunk {
+                    return Err(format!(
+                        "Pocket TTS prompt chunk has {token_count} tokens; maximum is {}",
+                        self.bundle.max_token_per_chunk
+                    ));
+                }
+                Ok(chunk.text)
+            })
+            .collect()
+    }
+
+    pub(crate) fn synth_chunk(
+        &mut self,
+        prepared: &AprilPreparedPrompt,
+        style: &VoiceStyle,
+    ) -> Result<Vec<f32>, String> {
+        let voice_embeddings = self.voice_embeddings(style)?;
+        let mut flow_state = self.condition_voice(&voice_embeddings)?;
+        let token_ids = self
+            .tokenizer
+            .encode(prepared.text.as_str(), false)
+            .map_err(|err| format!("tokenize Pocket TTS prompt: {err}"))?
+            .get_ids()
+            .iter()
+            .copied()
+            .map(i64::from)
+            .collect::<Vec<_>>();
+        if token_ids.is_empty() {
+            return Ok(Vec::new());
+        }
+        if token_ids.len() > self.bundle.max_token_per_chunk {
+            return Err(format!(
+                "Pocket TTS prompt has {} tokens; split_text_into_chunks maximum is {}",
+                token_ids.len(),
+                self.bundle.max_token_per_chunk
+            ));
+        }
+
+        let token_count = token_ids.len();
+        let text_embeddings = self.text_embeddings(token_ids)?;
+        self.run_flow_main_prefix(&text_embeddings, &mut flow_state)?;
+        let max_frames = estimate_max_frames(token_count, self.bundle.frame_rate);
+        let latents =
+            self.generate_latents(max_frames, prepared.frames_after_eos, &mut flow_state)?;
+        self.decode_latents(&latents)
+    }
+
+    fn prepared_token_count(&self, text: &str) -> Result<usize, String> {
+        let prepared = prepare_april_prompt(text)
+            .ok_or_else(|| "Pocket TTS prompt chunk became empty".to_string())?;
+        self.token_count(&prepared.text)
+    }
+
+    fn token_count(&self, text: &str) -> Result<usize, String> {
+        Ok(self
+            .tokenizer
+            .encode(text, false)
+            .map_err(|err| format!("tokenize Pocket TTS prompt: {err}"))?
+            .get_ids()
+            .len())
+    }
+
+    fn voice_embeddings(&mut self, style: &VoiceStyle) -> Result<Vec<f32>, String> {
+        let key = (
+            style.samples.as_ptr() as usize,
+            style.samples.len(),
+            style.sample_rate,
+        );
+        if let Some(cached) = &self.cached_voice {
+            if (cached.samples_ptr, cached.samples_len, cached.sample_rate) == key {
+                return Ok(cached.embeddings.clone());
+            }
+        }
+
+        let samples = if style.sample_rate == self.bundle.sample_rate as i32 {
+            style.samples.clone()
+        } else {
+            LinearResampler::create(style.sample_rate, self.bundle.sample_rate as i32)
+                .ok_or_else(|| {
+                    format!(
+                        "create Pocket TTS resampler {}Hz -> {}Hz",
+                        style.sample_rate, self.bundle.sample_rate
+                    )
+                })?
+                .resample(&style.samples, true)
+        };
+        let audio = Tensor::from_array((
+            vec![1_i64, 1, samples.len() as i64],
+            samples.into_boxed_slice(),
+        ))
+        .map_err(ort_error("create voice audio tensor"))?;
+        let outputs = self
+            .mimi_encoder
+            .run(ort::inputs!["audio" => audio])
+            .map_err(ort_error("run Mimi encoder"))?;
+        let (_, encoded) = outputs[0]
+            .try_extract_tensor::<f32>()
+            .map_err(ort_error("extract Mimi encoder output"))?;
+        if !encoded.len().is_multiple_of(self.bundle.conditioning_dim) {
+            return Err(format!(
+                "Mimi encoder returned {} values, not divisible by {}",
+                encoded.len(),
+                self.bundle.conditioning_dim
+            ));
+        }
+        let mut embeddings =
+            Vec::with_capacity(self.bos_embedding.len().saturating_add(encoded.len()));
+        embeddings.extend_from_slice(&self.bos_embedding);
+        embeddings.extend_from_slice(encoded);
+        self.cached_voice = Some(CachedVoice {
+            samples_ptr: key.0,
+            samples_len: key.1,
+            sample_rate: key.2,
+            embeddings: embeddings.clone(),
+        });
+        Ok(embeddings)
+    }
+
+    fn condition_voice(&mut self, embeddings: &[f32]) -> Result<Vec<StateValue>, String> {
+        let frames = embeddings.len() / self.bundle.conditioning_dim;
+        let sequence = Tensor::<f32>::new(
+            &ort::memory::Allocator::default(),
+            [1_i64, 0, self.bundle.latent_dim as i64],
+        )
+        .map_err(ort_error("create empty voice sequence"))?;
+        let text_embeddings = Tensor::from_array((
+            vec![1_i64, frames as i64, self.bundle.conditioning_dim as i64],
+            embeddings.to_vec().into_boxed_slice(),
+        ))
+        .map_err(ort_error("create voice embedding tensor"))?;
+        let mut state = initialize_state(&self.bundle.flow_lm_state_manifest)?;
+        let mut inputs = vec![
+            (Cow::Borrowed("sequence"), SessionInputValue::from(sequence)),
+            (
+                Cow::Borrowed("text_embeddings"),
+                SessionInputValue::from(text_embeddings),
+            ),
+        ];
+        append_state_inputs(&mut inputs, &state);
+        let mut outputs = self
+            .flow_main
+            .run(inputs)
+            .map_err(ort_error("condition Pocket TTS voice"))?;
+        replace_state_from_outputs(&mut state, &mut outputs)?;
+        Ok(state)
+    }
+
+    fn text_embeddings(&mut self, token_ids: Vec<i64>) -> Result<Vec<f32>, String> {
+        let tokens = Tensor::from_array((
+            vec![1_i64, token_ids.len() as i64],
+            token_ids.into_boxed_slice(),
+        ))
+        .map_err(ort_error("create token tensor"))?;
+        let outputs = self
+            .text_conditioner
+            .run(ort::inputs!["token_ids" => tokens])
+            .map_err(ort_error("run text conditioner"))?;
+        let (_, embeddings) = outputs[0]
+            .try_extract_tensor::<f32>()
+            .map_err(ort_error("extract text embeddings"))?;
+        Ok(embeddings.to_vec())
+    }
+
+    fn run_flow_main_prefix(
+        &mut self,
+        text_embeddings: &[f32],
+        state: &mut [StateValue],
+    ) -> Result<(), String> {
+        if !text_embeddings
+            .len()
+            .is_multiple_of(self.bundle.conditioning_dim)
+        {
+            return Err(format!(
+                "text conditioner returned {} values, not divisible by {}",
+                text_embeddings.len(),
+                self.bundle.conditioning_dim
+            ));
+        }
+        let frames = text_embeddings.len() / self.bundle.conditioning_dim;
+        let sequence = Tensor::<f32>::new(
+            &ort::memory::Allocator::default(),
+            [1_i64, 0, self.bundle.latent_dim as i64],
+        )
+        .map_err(ort_error("create empty text sequence"))?;
+        let text_embeddings = Tensor::from_array((
+            vec![1_i64, frames as i64, self.bundle.conditioning_dim as i64],
+            text_embeddings.to_vec().into_boxed_slice(),
+        ))
+        .map_err(ort_error("create text embedding tensor"))?;
+        let mut inputs = vec![
+            (Cow::Borrowed("sequence"), SessionInputValue::from(sequence)),
+            (
+                Cow::Borrowed("text_embeddings"),
+                SessionInputValue::from(text_embeddings),
+            ),
+        ];
+        append_state_inputs(&mut inputs, state);
+        let mut outputs = self
+            .flow_main
+            .run(inputs)
+            .map_err(ort_error("prime Pocket TTS text state"))?;
+        replace_state_from_outputs(state, &mut outputs)
+    }
+
+    fn generate_latents(
+        &mut self,
+        max_frames: usize,
+        frames_after_eos: usize,
+        state: &mut [StateValue],
+    ) -> Result<Vec<f32>, String> {
+        let mut current = vec![f32::NAN; self.bundle.latent_dim];
+        let mut latents = Vec::with_capacity(max_frames * self.bundle.latent_dim);
+        let mut eos_step = None;
+        let mut rng = rand::rng();
+
+        for step in 0..max_frames {
+            let sequence = Tensor::from_array((
+                vec![1_i64, 1, self.bundle.latent_dim as i64],
+                current.clone().into_boxed_slice(),
+            ))
+            .map_err(ort_error("create latent input"))?;
+            let text_embeddings = Tensor::<f32>::new(
+                &ort::memory::Allocator::default(),
+                [1_i64, 0, self.bundle.conditioning_dim as i64],
+            )
+            .map_err(ort_error("create empty text input"))?;
+            let mut inputs = vec![
+                (Cow::Borrowed("sequence"), SessionInputValue::from(sequence)),
+                (
+                    Cow::Borrowed("text_embeddings"),
+                    SessionInputValue::from(text_embeddings),
+                ),
+            ];
+            append_state_inputs(&mut inputs, state);
+            let mut outputs = self
+                .flow_main
+                .run(inputs)
+                .map_err(ort_error("run Pocket TTS Flow LM"))?;
+            let conditioning = outputs[0]
+                .try_extract_tensor::<f32>()
+                .map_err(ort_error("extract Flow LM conditioning"))?
+                .1
+                .to_vec();
+            let eos_logit = outputs[1]
+                .try_extract_tensor::<f32>()
+                .map_err(ort_error("extract Flow LM EOS logit"))?
+                .1
+                .first()
+                .copied()
+                .ok_or_else(|| "Flow LM returned empty EOS logit".to_string())?;
+            replace_state_from_outputs(state, &mut outputs)?;
+
+            if eos_logit > EOS_LOGIT_THRESHOLD && eos_step.is_none() {
+                eos_step = Some(step);
+            }
+            if eos_step.is_some_and(|eos| step >= eos + frames_after_eos) {
+                break;
+            }
+
+            let mut noise =
+                normal_noise(&mut rng, self.bundle.latent_dim, DEFAULT_TEMPERATURE.sqrt());
+            let conditioning = Tensor::from_array((
+                vec![1_i64, self.bundle.conditioning_dim as i64],
+                conditioning.into_boxed_slice(),
+            ))
+            .map_err(ort_error("create flow conditioning"))?;
+            let s = Tensor::from_array((vec![1_i64, 1], vec![0.0_f32].into_boxed_slice()))
+                .map_err(ort_error("create flow start tensor"))?;
+            let t = Tensor::from_array((vec![1_i64, 1], vec![1.0_f32].into_boxed_slice()))
+                .map_err(ort_error("create flow end tensor"))?;
+            let x = Tensor::from_array((
+                vec![1_i64, self.bundle.latent_dim as i64],
+                noise.clone().into_boxed_slice(),
+            ))
+            .map_err(ort_error("create flow noise tensor"))?;
+            let outputs = self
+                .flow
+                .run(ort::inputs![
+                    "c" => conditioning,
+                    "s" => s,
+                    "t" => t,
+                    "x" => x,
+                ])
+                .map_err(ort_error("run Pocket TTS flow"))?;
+            let flow = outputs[0]
+                .try_extract_tensor::<f32>()
+                .map_err(ort_error("extract Pocket TTS flow"))?
+                .1;
+            if flow.len() != noise.len() {
+                return Err(format!(
+                    "flow returned {} values; expected {}",
+                    flow.len(),
+                    noise.len()
+                ));
+            }
+            for (sample, delta) in noise.iter_mut().zip(flow) {
+                *sample += *delta;
+            }
+            current.clone_from(&noise);
+            latents.extend_from_slice(&noise);
+        }
+        Ok(latents)
+    }
+
+    fn decode_latents(&mut self, latents: &[f32]) -> Result<Vec<f32>, String> {
+        if latents.is_empty() {
+            return Ok(Vec::new());
+        }
+        if !latents.len().is_multiple_of(self.bundle.latent_dim) {
+            return Err(format!(
+                "latent buffer has {} values, not divisible by {}",
+                latents.len(),
+                self.bundle.latent_dim
+            ));
+        }
+        let frame_count = latents.len() / self.bundle.latent_dim;
+        let mut state = initialize_state(&self.bundle.mimi_state_manifest)?;
+        let mut audio = Vec::new();
+
+        for start in (0..frame_count).step_by(DECODER_CHUNK_FRAMES) {
+            let end = (start + DECODER_CHUNK_FRAMES).min(frame_count);
+            let values =
+                latents[start * self.bundle.latent_dim..end * self.bundle.latent_dim].to_vec();
+            let latent = Tensor::from_array((
+                vec![1_i64, (end - start) as i64, self.bundle.latent_dim as i64],
+                values.into_boxed_slice(),
+            ))
+            .map_err(ort_error("create Mimi latent tensor"))?;
+            let mut inputs = vec![(Cow::Borrowed("latent"), SessionInputValue::from(latent))];
+            append_state_inputs(&mut inputs, &state);
+            let mut outputs = self
+                .mimi_decoder
+                .run(inputs)
+                .map_err(ort_error("run Mimi decoder"))?;
+            let samples = outputs[0]
+                .try_extract_tensor::<f32>()
+                .map_err(ort_error("extract Mimi audio"))?
+                .1;
+            audio.extend_from_slice(samples);
+            replace_state_from_outputs(&mut state, &mut outputs)?;
+        }
+        Ok(audio)
+    }
+}
+
+fn load_session(path: PathBuf, num_threads: usize) -> Result<Session, String> {
+    if !path.is_file() {
+        return Err(format!("missing Pocket TTS file: {}", path.display()));
+    }
+    Session::builder()
+        .map_err(ort_error("create ONNX session builder"))?
+        .with_intra_threads(num_threads)
+        .map_err(|err| format!("configure ONNX intra-op threads: {err}"))?
+        .with_inter_threads(1)
+        .map_err(|err| format!("configure ONNX inter-op threads: {err}"))?
+        .commit_from_file(&path)
+        .map_err(|err| format!("load {}: {err}", path.display()))
+}
+
+fn load_tokenizer(path: &Path) -> Result<Tokenizer, String> {
+    let sentencepiece = SentencePieceModel::from_file(path)
+        .map_err(|err| format!("load {}: {err}", path.display()))?;
+    let trainer = sentencepiece
+        .trainer()
+        .ok_or_else(|| format!("{} has no SentencePiece trainer metadata", path.display()))?;
+    let normalizer = sentencepiece.normalizer().ok_or_else(|| {
+        format!(
+            "{} has no SentencePiece normalizer metadata",
+            path.display()
+        )
+    })?;
+    if normalizer.name() != "identity" {
+        return Err(format!(
+            "{} uses unsupported SentencePiece normalizer {:?}",
+            path.display(),
+            normalizer.name()
+        ));
+    }
+
+    let vocab = sentencepiece
+        .pieces()
+        .iter()
+        .map(|piece| (piece.piece().to_owned(), f64::from(piece.score())))
+        .collect();
+    let mut tokenizer = Tokenizer::new(
+        Unigram::from(
+            vocab,
+            Some(trainer.unk_id() as usize),
+            trainer.byte_fallback(),
+        )
+        .map_err(|err| format!("construct tokenizer from {}: {err}", path.display()))?,
+    );
+    // SentencePiece's identity normalizer still escapes spaces as U+2581 and
+    // prepends one marker to the input before unigram segmentation.
+    tokenizer.with_pre_tokenizer(Some(Metaspace::new('▁', PrependScheme::Always, false)));
+    Ok(tokenizer)
+}
+
+fn initialize_state(specs: &[StateSpec]) -> Result<Vec<StateValue>, String> {
+    specs
+        .iter()
+        .cloned()
+        .map(|spec| {
+            let len = shape_len(&spec.shape)?;
+            let value = match spec.dtype {
+                StateDtype::Float32 => {
+                    let fill = match spec.fill {
+                        StateFill::Nan => f32::NAN,
+                        StateFill::Empty | StateFill::Zeros => 0.0,
+                        StateFill::Ones => 1.0,
+                    };
+                    if len == 0 {
+                        Tensor::<f32>::new(&ort::memory::Allocator::default(), spec.shape.clone())
+                            .map_err(ort_error("create empty float state tensor"))?
+                            .into_dyn()
+                    } else {
+                        Tensor::from_array((spec.shape.clone(), vec![fill; len].into_boxed_slice()))
+                            .map_err(ort_error("create float state tensor"))?
+                            .into_dyn()
+                    }
+                }
+                StateDtype::Int64 => {
+                    let fill = i64::from(matches!(spec.fill, StateFill::Ones));
+                    if len == 0 {
+                        Tensor::<i64>::new(&ort::memory::Allocator::default(), spec.shape.clone())
+                            .map_err(ort_error("create empty integer state tensor"))?
+                            .into_dyn()
+                    } else {
+                        Tensor::from_array((spec.shape.clone(), vec![fill; len].into_boxed_slice()))
+                            .map_err(ort_error("create integer state tensor"))?
+                            .into_dyn()
+                    }
+                }
+                StateDtype::Bool => {
+                    let fill = matches!(spec.fill, StateFill::Ones);
+                    if len == 0 {
+                        Tensor::<bool>::new(&ort::memory::Allocator::default(), spec.shape.clone())
+                            .map_err(ort_error("create empty bool state tensor"))?
+                            .into_dyn()
+                    } else {
+                        Tensor::from_array((spec.shape.clone(), vec![fill; len].into_boxed_slice()))
+                            .map_err(ort_error("create bool state tensor"))?
+                            .into_dyn()
+                    }
+                }
+            };
+            Ok(StateValue { spec, value })
+        })
+        .collect()
+}
+
+fn append_state_inputs<'a>(
+    inputs: &mut Vec<(Cow<'a, str>, SessionInputValue<'a>)>,
+    state: &'a [StateValue],
+) {
+    for value in state {
+        inputs.push((
+            Cow::Borrowed(value.spec.input_name.as_str()),
+            SessionInputValue::from(&value.value),
+        ));
+    }
+}
+
+fn replace_state_from_outputs(
+    state: &mut [StateValue],
+    outputs: &mut ort::session::SessionOutputs<'_>,
+) -> Result<(), String> {
+    for value in state {
+        value.value = outputs
+            .remove(&value.spec.output_name)
+            .ok_or_else(|| format!("missing state output {}", value.spec.output_name))?;
+    }
+    Ok(())
+}
+
+fn shape_len(shape: &[i64]) -> Result<usize, String> {
+    shape.iter().try_fold(1_usize, |len, &dim| {
+        let dim = usize::try_from(dim).map_err(|_| format!("negative state dimension {dim}"))?;
+        len.checked_mul(dim)
+            .ok_or_else(|| format!("state shape overflows usize: {shape:?}"))
+    })
+}
+
+fn estimate_max_frames(token_count: usize, frame_rate: f32) -> usize {
+    ((token_count as f32 / TOKENS_PER_SECOND_ESTIMATE + GENERATION_SECONDS_PADDING) * frame_rate)
+        .ceil() as usize
+}
+
+fn normal_noise(rng: &mut impl Rng, len: usize, std_dev: f32) -> Vec<f32> {
+    let mut out = Vec::with_capacity(len);
+    while out.len() < len {
+        let u1 = rng.random::<f32>().max(f32::MIN_POSITIVE);
+        let u2 = rng.random::<f32>();
+        let radius = (-2.0_f32 * u1.ln()).sqrt() * std_dev;
+        out.push(radius * (TAU * u2).cos());
+        if out.len() < len {
+            out.push(radius * (TAU * u2).sin());
+        }
+    }
+    out
+}
+
+fn read_npy_f32(path: &Path) -> Result<Vec<f32>, String> {
+    let bytes = fs::read(path).map_err(|err| format!("read {}: {err}", path.display()))?;
+    if bytes.len() < 10 || &bytes[..6] != b"\x93NUMPY" {
+        return Err(format!("{} is not a NumPy array", path.display()));
+    }
+    let major = bytes[6];
+    let header_len_bytes = match major {
+        1 => 2,
+        2 | 3 => 4,
+        _ => {
+            return Err(format!(
+                "unsupported NumPy version {major} in {}",
+                path.display()
+            ))
+        }
+    };
+    let header_start = 8 + header_len_bytes;
+    if bytes.len() < header_start {
+        return Err(format!("truncated NumPy header in {}", path.display()));
+    }
+    let header_len = if header_len_bytes == 2 {
+        u16::from_le_bytes([bytes[8], bytes[9]]) as usize
+    } else {
+        u32::from_le_bytes([bytes[8], bytes[9], bytes[10], bytes[11]]) as usize
+    };
+    let data_start = header_start
+        .checked_add(header_len)
+        .ok_or_else(|| format!("NumPy header overflow in {}", path.display()))?;
+    if data_start > bytes.len() {
+        return Err(format!("truncated NumPy data in {}", path.display()));
+    }
+    let header = std::str::from_utf8(&bytes[header_start..data_start])
+        .map_err(|err| format!("invalid NumPy header in {}: {err}", path.display()))?;
+    if !(header.contains("'descr': '<f4'") || header.contains("\"descr\": \"<f4\""))
+        || header.contains("fortran_order': True")
+        || header.contains("fortran_order\": true")
+    {
+        return Err(format!(
+            "{} must be a little-endian, C-order float32 NumPy array",
+            path.display()
+        ));
+    }
+    let data = &bytes[data_start..];
+    if data.len() % 4 != 0 {
+        return Err(format!("misaligned float32 data in {}", path.display()));
+    }
+    Ok(data
+        .chunks_exact(4)
+        .map(|chunk| f32::from_le_bytes([chunk[0], chunk[1], chunk[2], chunk[3]]))
+        .collect())
+}
+
+fn ort_error(context: &'static str) -> impl FnOnce(ort::Error) -> String {
+    move |err| format!("{context}: {err}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn shape_len_supports_empty_state_dimensions() {
+        assert_eq!(shape_len(&[1, 128, 0]).expect("shape"), 0);
+        assert_eq!(shape_len(&[2, 1, 8, 1000, 64]).expect("shape"), 1_024_000);
+    }
+
+    #[test]
+    fn normal_noise_has_requested_length() {
+        let mut rng = rand::rng();
+        assert_eq!(normal_noise(&mut rng, 1, 1.0).len(), 1);
+        assert_eq!(normal_noise(&mut rng, 32, 1.0).len(), 32);
+    }
+
+    #[test]
+    fn generation_frame_estimate_scales_with_token_count() {
+        assert_eq!(estimate_max_frames(3, 12.5), 38);
+        assert_eq!(estimate_max_frames(300, 12.5), 1_275);
+    }
+
+    #[test]
+    #[ignore = "requires BUZZ_POCKET_TEST_MODEL_DIR"]
+    fn tokenizer_matches_sentencepiece_reference_including_unknown_words() {
+        let dir = std::env::var("BUZZ_POCKET_TEST_MODEL_DIR")
+            .expect("set BUZZ_POCKET_TEST_MODEL_DIR to the verified April bundle");
+        let tokenizer =
+            load_tokenizer(&Path::new(&dir).join("tokenizer.model")).expect("load April tokenizer");
+        let cases: &[(&str, &[u32])] = &[
+            ("Yep.", &[2462, 263]),
+            ("Hello there.", &[2994, 310, 263]),
+            (
+                "quizzaciously xyzzy.",
+                &[
+                    260, 1157, 1818, 362, 1814, 323, 260, 568, 327, 1818, 327, 263,
+                ],
+            ),
+            ("I'm listening.", &[268, 264, 283, 260, 604, 273, 263]),
+        ];
+        for (text, expected) in cases {
+            let encoding = tokenizer.encode(*text, false).expect("tokenize");
+            assert_eq!(encoding.get_ids(), *expected, "{text}");
+        }
+    }
+
+    #[test]
+    #[ignore = "requires BUZZ_POCKET_TEST_MODEL_DIR"]
+    fn loader_splits_oversized_prompts_at_bundle_token_limit() {
+        let dir = std::env::var("BUZZ_POCKET_TEST_MODEL_DIR")
+            .expect("set BUZZ_POCKET_TEST_MODEL_DIR to the verified April bundle");
+        let engine = AprilPocketTts::load(Path::new(&dir), 1).expect("load April bundle");
+        let text = "This deliberately long sentence repeats ordinary English words so the exact SentencePiece token limit is exercised without relying on punctuation, and it keeps adding more material until the prompt must be divided into multiple independently safe generation chunks before the recurrent state cache can be exhausted.";
+        let prepared = prepare_april_prompt(text).expect("prepare prompt");
+        let chunks = engine.split_prompt(&prepared).expect("split prompt");
+
+        assert!(chunks.len() > 1);
+        assert!(chunks.iter().all(|chunk| {
+            engine.token_count(chunk).expect("tokenize chunk") <= engine.bundle.max_token_per_chunk
+        }));
+    }
+
+    #[test]
+    #[ignore = "requires BUZZ_POCKET_TEST_MODEL_DIR"]
+    fn gary_provost_long_sentence_respects_bundle_token_limit() {
+        let dir = std::env::var("BUZZ_POCKET_TEST_MODEL_DIR")
+            .expect("set BUZZ_POCKET_TEST_MODEL_DIR to the verified April bundle");
+        let engine = AprilPocketTts::load(Path::new(&dir), 1).expect("load April bundle");
+        let text = "And sometimes, when I am certain the reader is rested, I will engage him with a sentence of considerable length, a sentence that burns with energy and builds with all the impetus of a crescendo, the roll of the drums, the crash of the cymbals–sounds that say listen to this, it is important.";
+        let prepared = prepare_april_prompt(text).expect("prepare prompt");
+        let chunks = engine.split_prompt(&prepared).expect("split long sentence");
+        let token_counts: Vec<_> = chunks
+            .iter()
+            .map(|chunk| engine.token_count(chunk).expect("count tokens"))
+            .collect();
+
+        assert_eq!(
+            chunks,
+            [
+                "And sometimes, when I am certain the reader is rested, I will engage him with a sentence of considerable length, a sentence that burns with energy and builds with all the.",
+                "Impetus of a crescendo, the roll of the drums, the crash of the cymbals–sounds that say listen to this, it is important.",
+            ]
+        );
+        assert_eq!(token_counts, [48, 44]);
+    }
+}
diff --git a/crates/buzz-voice/src/pocket_models.rs b/crates/buzz-voice/src/pocket_models.rs
new file mode 100644
index 0000000000..ba3f92849c
--- /dev/null
+++ b/crates/buzz-voice/src/pocket_models.rs
@@ -0,0 +1,137 @@
+//! Immutable capabilities for Buzz Desktop's April Pocket TTS bundle.
+
+/// Pinned upstream export repository.
+pub const APRIL_MODEL_ID: &str = "KevinAHM/pocket-tts-onnx";
+
+/// Pinned revision containing the `english_2026-04` bundle.
+pub const APRIL_MODEL_REVISION: &str = "58a6d00cf13d239b6748cb0769f35c580a8f606c";
+
+/// Language bundle selected from the pinned export.
+pub const APRIL_BUNDLE_ID: &str = "english_2026-04";
+
+/// Maximum input size declared by the April bundle.
+pub const APRIL_MAX_TOKEN_PER_CHUNK: usize = 50;
+
+/// One immutable artifact required by the April INT8 runtime.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct PocketModelArtifact {
+    pub filename: &'static str,
+    pub sha256: &'static str,
+    pub size_bytes: u64,
+    pub quantized: bool,
+}
+
+/// Capabilities of Buzz Desktop's sole Pocket model.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct PocketModelInfo {
+    /// Language bundle selected from the pinned export.
+    pub bundle_id: &'static str,
+    /// Upstream model repository.
+    pub source_model_id: &'static str,
+    /// Pinned upstream model revision.
+    pub revision: &'static str,
+    /// PCM output sample rate.
+    pub sample_rate: u32,
+    /// Maximum input size declared by the bundle.
+    pub max_token_per_chunk: usize,
+    /// Immutable files required by the runtime.
+    pub artifacts: &'static [PocketModelArtifact],
+    /// Components quantized in the selected bundle.
+    pub quantized_components: &'static [&'static str],
+}
+
+const INT8_ARTIFACTS: [PocketModelArtifact; 8] = [
+    PocketModelArtifact {
+        filename: "bundle.json",
+        sha256: "bab643150f437f37df080a710520ff39ed9ebd9a339f8ebdc739f7eddfc28b3f",
+        size_bytes: 24_381,
+        quantized: false,
+    },
+    PocketModelArtifact {
+        filename: "bos_before_voice.npy",
+        sha256: "f46edf4f7007b7ba4ea58831f49d003e59e167b4641c44bb3addfe9231a780b1",
+        size_bytes: 4_224,
+        quantized: false,
+    },
+    PocketModelArtifact {
+        filename: "tokenizer.model",
+        sha256: "d461765ae179566678c93091c5fa6f2984c31bbe990bf1aa62d92c64d91bc3f6",
+        size_bytes: 59_339,
+        quantized: false,
+    },
+    PocketModelArtifact {
+        filename: "flow_lm_main_int8.onnx",
+        sha256: "f9bd8106b79a0192c1c43399ab938fb24900a95c1c599870d75a884e99000116",
+        size_bytes: 76_341_079,
+        quantized: true,
+    },
+    PocketModelArtifact {
+        filename: "flow_lm_flow_int8.onnx",
+        sha256: "3dd781ee5abee9e195320bf0106bebd6372a852b3b36352524ee78b40554635d",
+        size_bytes: 9_962_530,
+        quantized: true,
+    },
+    PocketModelArtifact {
+        filename: "mimi_decoder_int8.onnx",
+        sha256: "3630450a3297a101792a6ac66619ebc70ab916b265e6220c2afaef8b1673f925",
+        size_bytes: 22_684_077,
+        quantized: true,
+    },
+    PocketModelArtifact {
+        filename: "mimi_encoder.onnx",
+        sha256: "853e2ca623b8782d94c3745ec6133bfdff7ce33d9b11128bd29ea03f28d76e3d",
+        size_bytes: 39_768_446,
+        quantized: false,
+    },
+    PocketModelArtifact {
+        filename: "text_conditioner.onnx",
+        sha256: "4ecee995fb69f85c7a7493d11f7b5ee15d9950facc7ab3f5c9c49ef1e03847bb",
+        size_bytes: 16_388_344,
+        quantized: false,
+    },
+];
+
+const INT8_COMPONENTS: [&str; 3] = ["flow_lm_main", "flow_lm_flow", "mimi_decoder"];
+
+/// Return immutable metadata for Buzz Desktop's April INT8 model.
+pub const fn april_model_info() -> PocketModelInfo {
+    PocketModelInfo {
+        bundle_id: APRIL_BUNDLE_ID,
+        source_model_id: APRIL_MODEL_ID,
+        revision: APRIL_MODEL_REVISION,
+        sample_rate: 24_000,
+        max_token_per_chunk: APRIL_MAX_TOKEN_PER_CHUNK,
+        artifacts: &INT8_ARTIFACTS,
+        quantized_components: &INT8_COMPONENTS,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn metadata_matches_pinned_int8_layout() {
+        let info = april_model_info();
+        assert_eq!(info.artifacts.len(), 8);
+        assert_eq!(
+            info.quantized_components,
+            ["flow_lm_main", "flow_lm_flow", "mimi_decoder"]
+        );
+        assert_eq!(
+            info.artifacts
+                .iter()
+                .map(|artifact| artifact.size_bytes)
+                .sum::<u64>(),
+            165_232_420
+        );
+        assert!(info
+            .artifacts
+            .iter()
+            .any(|artifact| { artifact.filename == "mimi_encoder.onnx" && !artifact.quantized }));
+        assert!(!info
+            .artifacts
+            .iter()
+            .any(|artifact| artifact.filename == "mimi_encoder_int8.onnx"));
+    }
+}
diff --git a/crates/buzz-voice/tests/pocket_import_audio.rs b/crates/buzz-voice/tests/pocket_import_audio.rs
new file mode 100644
index 0000000000..8578c368d4
--- /dev/null
+++ b/crates/buzz-voice/tests/pocket_import_audio.rs
@@ -0,0 +1,133 @@
+use std::{
+    fs,
+    path::{Path, PathBuf},
+};
+
+use buzz_voice::{
+    imported::{write_pcm16_wav, PcmStats, PocketVoiceLibrary},
+    pocket::{load_text_to_speech, load_voice_style, DEFAULT_VOICE, SAMPLE_RATE, VOICE_FILE_EXT},
+};
+
+const PREVIEW_TEXT: &str = "This is an objective Pocket voice preview.";
+
+fn required_path(name: &str) -> PathBuf {
+    std::env::var_os(name)
+        .map(PathBuf::from)
+        .unwrap_or_else(|| panic!("{name} must point to the required local test path"))
+}
+
+fn checked_in_voice() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("../../desktop/src-tauri/resources/pocket-voices/eve.wav")
+}
+
+fn evidence_dir() -> PathBuf {
+    std::env::var_os("BUZZ_VOICE_EVIDENCE_DIR")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| {
+            Path::new(env!("CARGO_MANIFEST_DIR")).join("../../target/buzz-voice-evidence")
+        })
+}
+
+fn synthesize(model_dir: &Path, voice_path: &Path, text: &str) -> (Vec<f32>, PcmStats) {
+    let engine = load_text_to_speech(
+        model_dir
+            .to_str()
+            .expect("Pocket model path must be valid UTF-8"),
+    )
+    .expect("load Pocket model");
+    let style = load_voice_style(voice_path).expect("load selected voice");
+    let samples = engine
+        .synth_chunk(text, "en", &style, 1)
+        .expect("synthesize preview");
+    let stats = PcmStats::analyze(&samples, SAMPLE_RATE);
+    assert!(
+        stats.is_non_silent(),
+        "generated PCM must be non-silent: {stats:?}"
+    );
+    assert!(
+        stats.duration_seconds > 0.2,
+        "generated PCM is unexpectedly short: {stats:?}"
+    );
+    (samples, stats)
+}
+
+#[test]
+#[ignore = "requires BUZZ_POCKET_MODEL_DIR and runs the installed Pocket ONNX model"]
+fn objective_import_synthesis_delete_and_mary_fallback() {
+    let model_dir = required_path("BUZZ_POCKET_MODEL_DIR");
+    let temp = tempfile::tempdir().expect("temporary voice workspace");
+    let source = temp.path().join("Imported Eve.wav");
+    fs::copy(checked_in_voice(), &source).expect("copy checked-in voice fixture");
+
+    let library_root = temp.path().join("library");
+    let library = PocketVoiceLibrary::new(&library_root);
+    let imported = library.import_path(&source).expect("import valid WAV");
+    assert_eq!(
+        library.find(&imported.key).expect("read selection"),
+        Some(imported.clone())
+    );
+
+    drop(library);
+    let relaunched = PocketVoiceLibrary::new(&library_root);
+    let selected = relaunched
+        .find(&imported.key)
+        .expect("reload persisted selection")
+        .expect("selected imported voice survived relaunch");
+    let imported_path = relaunched
+        .resolve_file(&selected)
+        .expect("resolve persisted imported voice");
+    let (imported_pcm, imported_stats) = synthesize(&model_dir, &imported_path, PREVIEW_TEXT);
+
+    let evidence = evidence_dir();
+    fs::create_dir_all(&evidence).expect("create evidence directory");
+    let imported_wav = evidence.join("imported-preview.wav");
+    write_pcm16_wav(&imported_wav, &imported_pcm, SAMPLE_RATE)
+        .expect("write imported preview evidence");
+
+    relaunched
+        .delete(&imported.key)
+        .expect("delete imported voice");
+    assert_eq!(
+        relaunched.find(&imported.key).expect("reload after delete"),
+        None
+    );
+
+    let mary_path = model_dir.join(format!("{DEFAULT_VOICE}.{VOICE_FILE_EXT}"));
+    assert_eq!(
+        mary_path.file_name().and_then(|name| name.to_str()),
+        Some("reference_sample.wav"),
+        "fallback must remain the deterministic Mary reference"
+    );
+    let (mary_pcm, mary_stats) = synthesize(&model_dir, &mary_path, PREVIEW_TEXT);
+    let mary_wav = evidence.join("mary-fallback-preview.wav");
+    write_pcm16_wav(&mary_wav, &mary_pcm, SAMPLE_RATE)
+        .expect("write Mary fallback preview evidence");
+
+    println!(
+        "{}",
+        serde_json::json!({
+            "importedKey": imported.key,
+            "persistence": "reloaded",
+            "afterDelete": "pocket:mary",
+            "importedPreview": {
+                "path": imported_wav,
+                "samples": imported_stats.sample_count,
+                "sampleRate": imported_stats.sample_rate,
+                "durationSeconds": imported_stats.duration_seconds,
+                "peak": imported_stats.peak,
+                "rms": imported_stats.rms,
+                "nonSilentSamples": imported_stats.non_silent_samples,
+            },
+            "maryFallbackPreview": {
+                "path": mary_wav,
+                "samples": mary_stats.sample_count,
+                "sampleRate": mary_stats.sample_rate,
+                "durationSeconds": mary_stats.duration_seconds,
+                "peak": mary_stats.peak,
+                "rms": mary_stats.rms,
+                "nonSilentSamples": mary_stats.non_silent_samples,
+            }
+        })
+    );
+}
diff --git a/deploy/charts/buzz/README.md b/deploy/charts/buzz/README.md
index a7c4bcf63b..b2778df28b 100644
--- a/deploy/charts/buzz/README.md
+++ b/deploy/charts/buzz/README.md
@@ -52,6 +52,48 @@ See:
 
 The chart fails at `helm install` / `helm template` time with a clear message if any of these are missing or malformed (see `templates/_validate.tpl`).
 
+## S3 URL addressing
+
+Buzz uses one URL style for both media and Git/CAS object-store requests:
+
+| `s3.addressingStyle` | Request shape | Use for |
+|---|---|---|
+| `path` (default) | `https://endpoint/bucket/key` | Bundled MinIO and endpoints whose DNS does not resolve bucket subdomains |
+| `virtual` | `https://bucket.endpoint/key` | AWS-style providers and new Railway Storage Buckets |
+
+The chart always renders `s3.addressingStyle` as
+`BUZZ_S3_ADDRESSING_STYLE`. It renders `s3.region` as `BUZZ_S3_REGION` only
+when explicitly set, preserving the relay's existing `AWS_REGION` fallback for
+upgrades. Only `path` and `virtual` addressing styles are accepted; invalid
+values fail chart rendering and relay startup. The bundled MinIO quickstart
+deliberately keeps `path` because its Service DNS resolves one endpoint
+hostname, not arbitrary `<bucket>.<service>` names.
+
+For a Railway Storage Bucket, map its variables to chart values in the service
+or generated Helm configuration:
+
+```yaml
+s3:
+  endpoint: "${{Object Storage.ENDPOINT}}"
+  bucket: "${{Object Storage.BUCKET}}"
+  region: "${{Object Storage.REGION}}"
+  addressingStyle: virtual
+```
+
+Store `BUZZ_S3_ACCESS_KEY=${{Object Storage.ACCESS_KEY_ID}}` and
+`BUZZ_S3_SECRET_KEY=${{Object Storage.SECRET_ACCESS_KEY}}` in the Secret named by
+`secrets.existingSecret`. Railway's Credentials tab is authoritative for older
+buckets, which may still require `path`. The setting changes request routing and
+SigV4 signing, so do not put the bucket into `s3.endpoint`; pass Railway's base
+`ENDPOINT` and `BUCKET` separately.
+
+Object storage is contacted during relay startup only when
+`BUZZ_GIT_CONFORMANCE_PROBE` is enabled (the relay default). A probe failure is
+startup-fatal, so Kubernetes readiness never opens. If an operator explicitly
+disables that probe through `relay.extraEnv`, `/_readiness` does not test object
+storage; configuration is still parsed strictly, but reachability and addressing
+errors surface on the first storage operation.
+
 ## Relay Pod extensions
 
 The chart exposes narrow extension points for init containers, volumes, relay
diff --git a/deploy/charts/buzz/examples/argocd-app.yaml b/deploy/charts/buzz/examples/argocd-app.yaml
index 7e90f64bd7..a29a6919b7 100644
--- a/deploy/charts/buzz/examples/argocd-app.yaml
+++ b/deploy/charts/buzz/examples/argocd-app.yaml
@@ -16,9 +16,14 @@ metadata:
 spec:
   project: default
   source:
-    repoURL: oci://ghcr.io/block/buzz/charts
-    chart: buzz
-    targetRevision: 0.1.0
+    # Argo CD >= 3.1 native OCI sources: repoURL must be the FULL chart
+    # artifact path — with the `repoURL: …/charts` + `chart: buzz` split
+    # form, the `chart` field is ignored for oci:// URLs and the fetch
+    # fails with a 403 (`repository:block/buzz/charts:pull` denied). The
+    # spec validator still requires `path`; use "." for OCI sources.
+    repoURL: oci://ghcr.io/block/buzz/charts/buzz
+    path: .
+    targetRevision: 0.1.7
     helm:
       releaseName: buzz
       values: |
@@ -41,6 +46,8 @@ spec:
         s3:
           endpoint: "https://s3.us-east-1.amazonaws.com"
           bucket: "buzz-media"
+          region: "us-east-1"
+          addressingStyle: virtual
           # accessKey / secretKey live in buzz-secrets
 
         persistence:
diff --git a/deploy/charts/buzz/examples/flux-helmrelease.yaml b/deploy/charts/buzz/examples/flux-helmrelease.yaml
index 16754c0fcb..09a6bfeb6a 100644
--- a/deploy/charts/buzz/examples/flux-helmrelease.yaml
+++ b/deploy/charts/buzz/examples/flux-helmrelease.yaml
@@ -41,6 +41,8 @@ spec:
     s3:
       endpoint: "https://s3.us-east-1.amazonaws.com"
       bucket: "buzz-media"
+      region: "us-east-1"
+      addressingStyle: virtual
 
     persistence:
       git:
diff --git a/deploy/charts/buzz/templates/_validate.tpl b/deploy/charts/buzz/templates/_validate.tpl
index 946424f9a3..aa7f7ac13c 100644
--- a/deploy/charts/buzz/templates/_validate.tpl
+++ b/deploy/charts/buzz/templates/_validate.tpl
@@ -75,10 +75,12 @@ surface at template time regardless of which manifest helm renders first.
   {{- fail "Postgres source missing: enable postgresql.enabled=true, set externalPostgresql.url, or provide secrets.existingSecret with key DATABASE_URL." -}}
 {{- end -}}
 
-{{/* S3 / object-storage source must exist somewhere (relay hard-fails its
-     startup conformance probe without a reachable bucket). */}}
+{{/* S3 / object-storage source must exist somewhere. With the default
+     BUZZ_GIT_CONFORMANCE_PROBE behavior, an unreachable bucket is detected
+     before the relay opens its listener; operators can explicitly disable that
+     startup gate. */}}
 {{- if not (or .Values.minio.enabled .Values.s3.endpoint .Values.secrets.existingSecret) -}}
-  {{- fail "S3/object-storage source missing: enable minio.enabled=true (quickstart in-cluster), set s3.endpoint + s3.bucket + credentials, or provide secrets.existingSecret with keys BUZZ_S3_ACCESS_KEY + BUZZ_S3_SECRET_KEY. The relay runs a startup S3 conformance probe and exits if storage is unreachable." -}}
+  {{- fail "S3/object-storage source missing: enable minio.enabled=true (quickstart in-cluster), set s3.endpoint + s3.bucket + credentials, or provide secrets.existingSecret with keys BUZZ_S3_ACCESS_KEY + BUZZ_S3_SECRET_KEY. By default the relay runs a startup S3 conformance probe and exits if storage is unreachable; disabling BUZZ_GIT_CONFORMANCE_PROBE also removes that startup storage check." -}}
 {{- end -}}
 
 {{- end -}}
diff --git a/deploy/charts/buzz/templates/deployment.yaml b/deploy/charts/buzz/templates/deployment.yaml
index bf2df4c2c8..67a93138c5 100644
--- a/deploy/charts/buzz/templates/deployment.yaml
+++ b/deploy/charts/buzz/templates/deployment.yaml
@@ -170,6 +170,10 @@ spec:
             - { name: BUZZ_S3_ENDPOINT, value: {{ $s3Endpoint | quote }} }
             {{- end }}
             - { name: BUZZ_S3_BUCKET, value: {{ .Values.s3.bucket | quote }} }
+            {{- if .Values.s3.region }}
+            - { name: BUZZ_S3_REGION, value: {{ .Values.s3.region | quote }} }
+            {{- end }}
+            - { name: BUZZ_S3_ADDRESSING_STYLE, value: {{ .Values.s3.addressingStyle | quote }} }
 
             # ── Secrets (from chart-managed or existing) ─────────────
             - name: BUZZ_RELAY_PRIVATE_KEY
diff --git a/deploy/charts/buzz/tests/render_test.yaml b/deploy/charts/buzz/tests/render_test.yaml
index 3e044f5d7c..cf08210781 100644
--- a/deploy/charts/buzz/tests/render_test.yaml
+++ b/deploy/charts/buzz/tests/render_test.yaml
@@ -30,6 +30,18 @@ tests:
           path: kind
           value: Service
         template: templates/service.yaml
+      - notContains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: BUZZ_S3_REGION
+          any: true
+        template: templates/deployment.yaml
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: BUZZ_S3_ADDRESSING_STYLE
+            value: "path"
+        template: templates/deployment.yaml
       - contains:
           path: spec.template.spec.containers[0].env
           content:
@@ -47,6 +59,32 @@ tests:
             value: "true"
         template: templates/deployment.yaml
 
+  - it: renders virtual-hosted S3 addressing for providers that require it
+    set:
+      relayUrl: wss://buzz.example.com
+      ownerPubkey: "0000000000000000000000000000000000000000000000000000000000000000"
+      externalPostgresql.url: postgres://u:p@h:5432/d
+      externalRedis.url: redis://h:6379
+      s3.endpoint: https://storage.railway.app
+      s3.bucket: buzz-media-example
+      s3.region: auto
+      s3.addressingStyle: virtual
+      s3.accessKey: a
+      s3.secretKey: s
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: BUZZ_S3_REGION
+            value: "auto"
+        template: templates/deployment.yaml
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: BUZZ_S3_ADDRESSING_STYLE
+            value: "virtual"
+        template: templates/deployment.yaml
+
   - it: lets an explicit value opt out of media read auth for dev/public deployments
     set:
       relayUrl: wss://buzz.example.com
diff --git a/deploy/charts/buzz/tests/validation_test.yaml b/deploy/charts/buzz/tests/validation_test.yaml
index f0a3869795..a5a0050a86 100644
--- a/deploy/charts/buzz/tests/validation_test.yaml
+++ b/deploy/charts/buzz/tests/validation_test.yaml
@@ -58,6 +58,17 @@ tests:
       - failedTemplate:
           errorPattern: "Postgres source missing"
 
+  - it: rejects an invalid S3 addressing style
+    set:
+      relayUrl: wss://buzz.example.com
+      ownerPubkey: "0000000000000000000000000000000000000000000000000000000000000000"
+      externalPostgresql.url: postgres://u:p@h:5432/d
+      s3.endpoint: http://minio:9000
+      s3.addressingStyle: auto
+    asserts:
+      - failedTemplate:
+          errorPattern: "s3.addressingStyle: s3.addressingStyle must be one of the following:.*path.*virtual"
+
   - it: fails when S3/object-storage source is missing
     set:
       relayUrl: wss://buzz.example.com
diff --git a/deploy/charts/buzz/values.schema.json b/deploy/charts/buzz/values.schema.json
index 53bb29bb60..9cb6a02c9b 100644
--- a/deploy/charts/buzz/values.schema.json
+++ b/deploy/charts/buzz/values.schema.json
@@ -198,6 +198,15 @@
       "properties": {
         "endpoint": { "type": "string", "pattern": "^(https?://.+)?$" },
         "bucket": { "type": "string", "minLength": 1 },
+        "region": {
+          "type": "string",
+          "description": "Optional S3 region used for SigV4 signing. When empty, BUZZ_S3_REGION is omitted so the relay can use AWS_REGION or its own default."
+        },
+        "addressingStyle": {
+          "type": "string",
+          "enum": ["path", "virtual"],
+          "description": "S3 URL style shared by media and Git/CAS clients. Defaults to path for bundled MinIO compatibility."
+        },
         "accessKey": { "type": "string" },
         "secretKey": { "type": "string" }
       }
diff --git a/deploy/charts/buzz/values.yaml b/deploy/charts/buzz/values.yaml
index 8ac5086e27..810f8a9658 100644
--- a/deploy/charts/buzz/values.yaml
+++ b/deploy/charts/buzz/values.yaml
@@ -338,6 +338,12 @@ externalRedis:
 s3:
   endpoint: ""
   bucket: "buzz-media"
+  # Optional SigV4 signing region. Leave empty to preserve the relay's
+  # AWS_REGION fallback; set the provider's credential value when needed.
+  region: ""
+  # path: https://endpoint/bucket/key (bundled MinIO-compatible default)
+  # virtual: https://bucket.endpoint/key (standard S3; required by new Railway buckets)
+  addressingStyle: path
   accessKey: ""
   secretKey: ""
 
diff --git a/deploy/compose/.env.example b/deploy/compose/.env.example
index 838824c17f..f6ab4fcab9 100644
--- a/deploy/compose/.env.example
+++ b/deploy/compose/.env.example
@@ -33,6 +33,8 @@ REDIS_PASSWORD=CHANGE_ME_RANDOM_PASSWORD
 BUZZ_S3_ACCESS_KEY=CHANGE_ME_RANDOM_ACCESS_KEY
 BUZZ_S3_SECRET_KEY=CHANGE_ME_RANDOM_SECRET_KEY
 BUZZ_S3_BUCKET=buzz-media
+# Bundled MinIO uses path-style URLs; deploy/compose/compose.yml pins this.
+BUZZ_S3_ADDRESSING_STYLE=path
 
 # Optional host ports. Base compose publishes the relay directly on BUZZ_HTTP_PORT.
 BUZZ_HTTP_PORT=3000
diff --git a/deploy/compose/README.md b/deploy/compose/README.md
index 0de524fb5b..bb0e63fe15 100644
--- a/deploy/compose/README.md
+++ b/deploy/compose/README.md
@@ -38,6 +38,11 @@ keypair.
   migrations.
 - The stack uses Postgres, Redis, MinIO, and a git data volume because
   those are real Buzz dependencies today. Minimal mode can simplify this later.
+- The bundled Compose stack fixes the relay endpoint to `http://minio:9000` and
+  `BUZZ_S3_ADDRESSING_STYLE=path`: Docker DNS resolves `minio`, not
+  `<bucket>.minio`. It is not configurable for an external S3 provider through
+  `.env`; use the Helm chart or a custom Compose configuration for providers
+  such as new Railway Storage Buckets that require `virtual` addressing.
 
 Run `./run.sh backup-hint` for the backup checklist.
 
diff --git a/deploy/compose/compose.yml b/deploy/compose/compose.yml
index bc3c27501e..15337c92a2 100644
--- a/deploy/compose/compose.yml
+++ b/deploy/compose/compose.yml
@@ -12,6 +12,8 @@ services:
       DATABASE_URL: postgres://${POSTGRES_USER:-buzz}:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-buzz}
       REDIS_URL: redis://:${REDIS_PASSWORD:?set REDIS_PASSWORD}@redis:6379
       BUZZ_S3_ENDPOINT: http://minio:9000
+      # Docker DNS resolves `minio`, not arbitrary `<bucket>.minio` hosts.
+      BUZZ_S3_ADDRESSING_STYLE: path
       BUZZ_S3_ACCESS_KEY: ${BUZZ_S3_ACCESS_KEY:?set BUZZ_S3_ACCESS_KEY}
       BUZZ_S3_SECRET_KEY: ${BUZZ_S3_SECRET_KEY:?set BUZZ_S3_SECRET_KEY}
       BUZZ_S3_BUCKET: ${BUZZ_S3_BUCKET:-buzz-media}
diff --git a/desktop/package.json b/desktop/package.json
index adac095a47..e8145f5468 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -1,7 +1,7 @@
 {
   "name": "buzz",
   "private": true,
-  "version": "0.5.0",
+  "version": "0.5.3",
   "type": "module",
   "scripts": {
     "dev": "vite",
diff --git a/desktop/playwright.config.ts b/desktop/playwright.config.ts
index 459fa75743..7ce7f48389 100644
--- a/desktop/playwright.config.ts
+++ b/desktop/playwright.config.ts
@@ -34,6 +34,7 @@ export default defineConfig({
         "**/hosted-communities-settings-screenshots.spec.ts",
         "**/invites-settings-screenshots.spec.ts",
         "**/messaging.spec.ts",
+        "**/message-feedback-snapshots.spec.ts",
         "**/custom-emoji.spec.ts",
         "**/profile-custom-emoji-status.spec.ts",
         "**/custom-emoji-ui.spec.ts",
@@ -48,6 +49,7 @@ export default defineConfig({
         "**/activity-scope-label-screenshots.spec.ts",
         "**/welcome-agent-modal-screenshots.spec.ts",
         "**/local-archive-screenshots.spec.ts",
+        "**/voice-settings.spec.ts",
         "**/agent-readiness-screenshots.spec.ts",
         "**/agent-error-state-screenshots.spec.ts",
         "**/edit-agent.spec.ts",
@@ -94,6 +96,7 @@ export default defineConfig({
         "**/cold-switch-longtask.perf.ts",
         "**/timeline-no-shift.spec.ts",
         "**/human-edit-agent-content.spec.ts",
+        "**/empty-edit-delete.spec.ts",
         "**/reaction-order.spec.ts",
         "**/reaction-names.spec.ts",
         "**/inbox-reactions.spec.ts",
@@ -118,15 +121,18 @@ export default defineConfig({
         "**/nostr-bind.spec.ts",
         "**/mobile-pairing-qr.spec.ts",
         "**/profile-nsec-reveal.spec.ts",
+        "**/profile-backup-settings.spec.ts",
         "**/signout-confirmation.spec.ts",
         "**/agent-provider-dropdowns.spec.ts",
         "**/agent-lifecycle-feedback.spec.ts",
+        "**/agent-access-warning.spec.ts",
         "**/inbox-live-update.spec.ts",
         "**/mesh-compute.spec.ts",
         "**/observer-archive-policy.spec.ts",
         "**/harness-management.spec.ts",
         "**/harness-catalog-screenshots.spec.ts",
         "**/inline-custom-harness.spec.ts",
+        "**/huddle-transcription.spec.ts",
       ],
       use: {
         ...devices["Desktop Chrome"],
diff --git a/desktop/public/harness-logos/CREDITS.md b/desktop/public/harness-logos/CREDITS.md
index de4e003c3f..716c43e1ae 100644
--- a/desktop/public/harness-logos/CREDITS.md
+++ b/desktop/public/harness-logos/CREDITS.md
@@ -9,6 +9,7 @@ license permits redistribution.
 
 | File | Upstream | Commit | License | Source path | Modifications |
 |---|---|---|---|---|---|
+| `devin.svg` | [Cognition Devin documentation](https://docs.devin.ai/cli) | Retrieved 2026-07-27 | Cognition trademark; nominative use to identify the Devin harness | Official documentation `logo/favicon.svg` | Added the official black mark to a white square canvas so it remains legible in both app themes |
 | `hermes.png` | [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent) | `6ad632b` | MIT © 2025 Nous Research | `website/static/img/logo.png` | Cropped the baked-in border frame, padded to square, resized to 64×64, quantised to a 16-colour palette |
 | `openclaw.svg` | [openclaw/openclaw](https://github.com/openclaw/openclaw) | `b06f40a` | MIT © 2026 OpenClaw Foundation | `ui/public/favicon.svg` | Removed the SMIL animation elements (renders the upstream rest pose statically — verified pixel-identical to the upstream frame at t=0); minified paths |
 | `omp.svg` | [can1357/oh-my-pi](https://github.com/can1357/oh-my-pi) | `667111575ebba136dadfd6989379e7f67e0d40d9` | MIT © 2025 Mario Zechner; © 2025–2026 Can Bölük | `assets/icon.svg` | None |
diff --git a/desktop/public/harness-logos/devin.svg b/desktop/public/harness-logos/devin.svg
new file mode 100644
index 0000000000..e760797d68
--- /dev/null
+++ b/desktop/public/harness-logos/devin.svg
@@ -0,0 +1,4 @@
+<svg width="425" height="425" viewBox="0 0 425 425" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="425" height="425" fill="white"/>
+  <path d="M70 159.333V91.3471C70 88.3592 71.594 85.5983 74.1816 84.1044L133.043 50.1205C135.631 48.6265 138.819 48.6265 141.407 50.1205L200.269 84.1044C202.856 85.5983 204.45 88.3592 204.45 91.3471V126.068C204.708 137.606 210.806 148.734 221.531 154.926C232.256 161.117 244.942 160.834 255.063 155.289L285.132 137.929C287.719 136.435 290.907 136.435 293.495 137.929L352.357 171.913C354.944 173.406 356.538 176.167 356.538 179.155V247.123C356.538 250.111 354.944 252.872 352.357 254.366L293.495 288.35C290.907 289.844 287.719 289.844 285.132 288.35L255.306 271.13C245.146 265.456 232.344 265.117 221.534 271.358C210.809 277.55 204.711 288.678 204.453 300.215V334.926C204.453 337.914 202.859 340.675 200.271 342.169L141.41 376.153C138.822 377.647 135.634 377.647 133.046 376.153L74.1845 342.169C71.5969 340.675 70.0028 337.914 70.0028 334.926V266.959C70.0029 263.971 71.5969 261.21 74.1845 259.716L133.046 225.732C135.634 224.238 138.822 224.238 141.41 225.732L171.547 243.132C181.656 248.638 194.306 248.906 205.005 242.729C215.815 236.488 221.922 225.231 222.088 213.595C221.83 202.057 215.732 189.737 205.008 183.545C194.283 177.353 181.597 177.636 171.476 183.181L141.269 200.72C138.67 202.229 135.461 202.228 132.864 200.716L74.1576 166.562C71.5835 165.065 70 162.311 70 159.333Z" fill="black"/>
+</svg>
diff --git a/desktop/scripts/build-release-config.mjs b/desktop/scripts/build-release-config.mjs
index 389d18aec5..d1cd8181eb 100644
--- a/desktop/scripts/build-release-config.mjs
+++ b/desktop/scripts/build-release-config.mjs
@@ -52,6 +52,15 @@ const releaseConfig = {
   },
 };
 
+// Tauri applies --config after platform-specific config using RFC 7396.
+// Any externalBin value here would therefore replace the platform sidecar list,
+// while null would silently delete it. This delta must never own that key.
+if (Object.hasOwn(releaseConfig.bundle, "externalBin")) {
+  throw new Error(
+    "Release config must not define bundle.externalBin; sidecars are platform-specific",
+  );
+}
+
 console.log(`Updater enabled -> ${updaterEndpoint}`);
 
 writeFileSync(outputConfigPath, `${JSON.stringify(releaseConfig, null, 2)}\n`);
diff --git a/desktop/scripts/check-pubkey-truncation.mjs b/desktop/scripts/check-pubkey-truncation.mjs
index 95e56fb282..d65db13545 100644
--- a/desktop/scripts/check-pubkey-truncation.mjs
+++ b/desktop/scripts/check-pubkey-truncation.mjs
@@ -18,12 +18,10 @@ const rules = [
 // Non-display uses: array windows over pubkey lists, color/initials
 // derivation where the value is never presented as an identity.
 const overrides = new Set([
-  // ProfileAvatar fallback label — decorative glyphs inside an avatar disc.
-  "src/features/huddle/components/ParticipantList.tsx:92",
   // HexAvatar: 6-char badge + hue derivation inside a color-coded disc,
   // clearly decorative (paired with a full truncatePubkey aria-label).
-  "src/features/huddle/components/ParticipantList.tsx:143",
-  "src/features/huddle/components/ParticipantList.tsx:144",
+  "src/features/huddle/components/ParticipantList.tsx:150",
+  "src/features/huddle/components/ParticipantList.tsx:151",
   // clientId (not a pubkey) sliced in a debug log next to the real thing.
   "src/features/channels/readState/readStateManager.ts:338",
   // Array windows (first N pubkeys), not string truncation.
diff --git a/desktop/scripts/texture-card/generate-card-texture.mjs b/desktop/scripts/texture-card/generate-card-texture.mjs
index 75cc24e744..57ebc61a9b 100644
--- a/desktop/scripts/texture-card/generate-card-texture.mjs
+++ b/desktop/scripts/texture-card/generate-card-texture.mjs
@@ -12,83 +12,116 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
-const OUTPUT = path.resolve(
-  HERE,
-  "../../src/shared/ui/assets/card-texture.png",
-);
-
-// CSS-pixel source geometry. Screenshotting at DPR 2 produces a crisp asset.
-const CARD_SIZE = 640;
-const OUTSET = 96;
-const CAPTURE_SIZE = CARD_SIZE + OUTSET * 2;
+const OUTPUT_DIRECTORY = path.resolve(HERE, "../../src/shared/ui/assets");
 const DPR = 2;
 
 // Approved texture parameters, archived from the former runtime SVG filter.
-const BLUR = 66;
-const DILATE = Math.round(BLUR * 0.85);
 const THRESHOLD_BIAS = 0.302;
 const SLOPE = 8;
 const FREQUENCY = 0.999;
 const OCTAVES = 3;
 const SEED = 5315;
 
-await mkdir(path.dirname(OUTPUT), { recursive: true });
+const TEXTURES = [
+  {
+    filename: "card-texture.png",
+    color: "white",
+    cardSize: 640,
+    outset: 96,
+    blur: 66,
+    innerBand: 112,
+  },
+  {
+    filename: "card-texture-dark.png",
+    color: "#171b21",
+    cardSize: 640,
+    outset: 96,
+    blur: 66,
+    innerBand: 112,
+  },
+  {
+    filename: "card-texture-compact.png",
+    color: "white",
+    cardSize: 320,
+    outset: 24,
+    blur: 24,
+    innerBand: 44,
+  },
+  {
+    filename: "card-texture-dark-compact.png",
+    color: "#171b21",
+    cardSize: 320,
+    outset: 24,
+    blur: 24,
+    innerBand: 44,
+  },
+];
+
+await mkdir(OUTPUT_DIRECTORY, { recursive: true });
 
 const browser = await chromium.launch();
 try {
-  const page = await browser.newPage({
-    deviceScaleFactor: DPR,
-    viewport: { height: CAPTURE_SIZE, width: CAPTURE_SIZE },
-  });
+  for (const texture of TEXTURES) {
+    const captureSize = texture.cardSize + texture.outset * 2;
+    const dilate = Math.round(texture.blur * 0.85);
+    const output = path.join(OUTPUT_DIRECTORY, texture.filename);
+    const page = await browser.newPage({
+      deviceScaleFactor: DPR,
+      viewport: { height: captureSize, width: captureSize },
+    });
 
-  await page.setContent(`<!doctype html>
-    <style>
-      html, body { margin: 0; width: 100%; height: 100%; background: transparent; }
-      #stage { position: relative; width: ${CAPTURE_SIZE}px; height: ${CAPTURE_SIZE}px; }
-      #core {
-        position: absolute;
-        inset: ${OUTSET + BLUR / 2}px;
-        background: white;
-        filter: blur(${BLUR / 3}px);
-      }
-    </style>
-    <div id="stage">
-      <svg width="${CAPTURE_SIZE}" height="${CAPTURE_SIZE}" aria-hidden="true">
-        <defs>
-          <filter id="texture" x="0" y="0" width="100%" height="100%"
-                  filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
-            <feMorphology in="SourceAlpha" operator="dilate" radius="${DILATE}" result="squared" />
-            <feGaussianBlur in="squared" stdDeviation="${BLUR}" result="ramp" />
-            <feTurbulence type="fractalNoise" baseFrequency="${FREQUENCY}"
-                          numOctaves="${OCTAVES}" seed="${SEED}" result="grain" />
-            <feColorMatrix in="grain" result="grainAlpha" type="matrix"
-              values="0 0 0 0 0
-                      0 0 0 0 0
-                      0 0 0 0 0
-                      1 0 0 0 0" />
-            <feComposite in="ramp" in2="grainAlpha" operator="arithmetic"
-                         k1="0" k2="1" k3="-1" k4="${-THRESHOLD_BIAS}" result="dithered" />
-            <feComponentTransfer in="dithered" result="specks">
-              <feFuncA type="linear" slope="${SLOPE}" intercept="0" />
-            </feComponentTransfer>
-            <feFlood flood-color="white" result="white" />
-            <feComposite in="white" in2="specks" operator="in" />
-          </filter>
-        </defs>
-        <rect x="${OUTSET}" y="${OUTSET}" width="${CARD_SIZE}" height="${CARD_SIZE}"
-              fill="white" filter="url(#texture)" />
-      </svg>
-      <span id="core"></span>
-    </div>`);
+    await page.setContent(`<!doctype html>
+      <style>
+        html, body { margin: 0; width: 100%; height: 100%; background: transparent; }
+        #stage { position: relative; width: ${captureSize}px; height: ${captureSize}px; }
+        #core {
+          position: absolute;
+          inset: ${texture.outset + texture.blur / 2}px;
+          background: ${texture.color};
+          filter: blur(${texture.blur / 3}px);
+        }
+      </style>
+      <div id="stage">
+        <svg width="${captureSize}" height="${captureSize}" aria-hidden="true">
+          <defs>
+            <filter id="texture" x="0" y="0" width="100%" height="100%"
+                    filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+              <feMorphology in="SourceAlpha" operator="dilate" radius="${dilate}" result="squared" />
+              <feGaussianBlur in="squared" stdDeviation="${texture.blur}" result="ramp" />
+              <feTurbulence type="fractalNoise" baseFrequency="${FREQUENCY}"
+                            numOctaves="${OCTAVES}" seed="${SEED}" result="grain" />
+              <feColorMatrix in="grain" result="grainAlpha" type="matrix"
+                values="0 0 0 0 0
+                        0 0 0 0 0
+                        0 0 0 0 0
+                        1 0 0 0 0" />
+              <feComposite in="ramp" in2="grainAlpha" operator="arithmetic"
+                           k1="0" k2="1" k3="-1" k4="${-THRESHOLD_BIAS}" result="dithered" />
+              <feComponentTransfer in="dithered" result="specks">
+                <feFuncA type="linear" slope="${SLOPE}" intercept="0" />
+              </feComponentTransfer>
+              <feFlood flood-color="${texture.color}" result="surfaceColor" />
+              <feComposite in="surfaceColor" in2="specks" operator="in" />
+            </filter>
+          </defs>
+          <rect x="${texture.outset}" y="${texture.outset}" width="${texture.cardSize}" height="${texture.cardSize}"
+                fill="${texture.color}" filter="url(#texture)" />
+        </svg>
+        <span id="core"></span>
+      </div>`);
 
-  await page.locator("#stage").screenshot({
-    omitBackground: true,
-    path: OUTPUT,
-  });
+    await page.locator("#stage").screenshot({
+      omitBackground: true,
+      path: output,
+    });
+    await page.close();
+
+    console.log(`Generated ${output}`);
+    console.log(`Asset: ${captureSize * DPR}×${captureSize * DPR}px @${DPR}x`);
+    console.log(
+      `Runtime slice: ${(texture.outset + texture.innerBand) * DPR}px; outset: ${texture.outset}px`,
+    );
+  }
 } finally {
   await browser.close();
 }
-
-console.log(`Generated ${OUTPUT}`);
-console.log(`Asset: ${CAPTURE_SIZE * DPR}×${CAPTURE_SIZE * DPR}px @${DPR}x`);
-console.log(`Runtime slice: ${(OUTSET + 112) * DPR}px; outset: ${OUTSET}px`);
diff --git a/desktop/src-tauri/Cargo.lock b/desktop/src-tauri/Cargo.lock
index 66553ef595..9feecbee01 100644
--- a/desktop/src-tauri/Cargo.lock
+++ b/desktop/src-tauri/Cargo.lock
@@ -75,6 +75,20 @@ dependencies = [
  "subtle",
 ]
 
+[[package]]
+name = "ahash"
+version = "0.8.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
+dependencies = [
+ "cfg-if 1.0.4",
+ "getrandom 0.3.4",
+ "once_cell",
+ "serde",
+ "version_check",
+ "zerocopy",
+]
+
 [[package]]
 name = "aho-corasick"
 version = "1.1.4"
@@ -694,6 +708,12 @@ version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fd307490d624467aa6f74b0eabb77633d1f758a7b25f12bceb0b22e08d9726f6"
 
+[[package]]
+name = "base64"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e1b586273c5702936fe7b7d6896644d8be71e6314cfe09d3167c95f712589e8"
+
 [[package]]
 name = "base64"
 version = "0.21.7"
@@ -718,6 +738,12 @@ version = "0.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32637268377fc7b10a8c6d51de3e7fba1ce5dd371a96e342b34e6078db558e7f"
 
+[[package]]
+name = "beef"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a8241f3ebb85c056b509d4327ad0358fbbba6ffb340bf388f26350aeda225b1"
+
 [[package]]
 name = "bip39"
 version = "2.2.2"
@@ -1010,7 +1036,7 @@ dependencies = [
 
 [[package]]
 name = "buzz-desktop"
-version = "0.5.0"
+version = "0.5.3"
 dependencies = [
  "anyhow",
  "arboard",
@@ -1018,11 +1044,13 @@ dependencies = [
  "audioadapter-buffers",
  "axum",
  "base64 0.22.1",
+ "block2",
  "buzz-agent",
  "buzz-core",
  "buzz-media",
  "buzz-persona",
  "buzz-sdk",
+ "buzz-voice",
  "bytes",
  "bzip2 0.6.1",
  "chrono",
@@ -1032,6 +1060,7 @@ dependencies = [
  "ed25519-dalek",
  "flate2",
  "futures-util",
+ "getrandom 0.2.17",
  "hex",
  "image",
  "infer",
@@ -1047,7 +1076,9 @@ dependencies = [
  "neteq",
  "nostr",
  "notify-rust",
+ "objc2",
  "objc2-app-kit",
+ "objc2-foundation",
  "opus",
  "plist",
  "png 0.18.1",
@@ -1076,6 +1107,7 @@ dependencies = [
  "tauri-plugin-single-instance",
  "tauri-plugin-updater",
  "tauri-plugin-window-state",
+ "tauri-utils",
  "tempfile",
  "tokio",
  "tokio-tungstenite 0.29.0",
@@ -1085,6 +1117,7 @@ dependencies = [
  "url",
  "user-idle",
  "uuid",
+ "webkit2gtk",
  "window-vibrancy",
  "windows-sys 0.61.2",
  "zeroize",
@@ -1143,6 +1176,24 @@ dependencies = [
  "uuid",
 ]
 
+[[package]]
+name = "buzz-voice"
+version = "0.1.0"
+dependencies = [
+ "atomic-write-file",
+ "hex",
+ "ort",
+ "ort-sys",
+ "rand 0.10.2",
+ "sentencepiece-model",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "sherpa-onnx",
+ "symphonia",
+ "tokenizers",
+]
+
 [[package]]
 name = "by_address"
 version = "1.2.1"
@@ -1508,7 +1559,7 @@ version = "3.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "faf9468729b8cbcea668e36183cb69d317348c2e08e994829fb56ebfdfbaac34"
 dependencies = [
- "windows-sys 0.48.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -1545,6 +1596,7 @@ dependencies = [
  "itoa",
  "rustversion",
  "ryu",
+ "serde",
  "static_assertions",
 ]
 
@@ -1745,7 +1797,7 @@ dependencies = [
  "wasm-bindgen",
  "wasm-bindgen-futures",
  "web-sys",
- "windows 0.61.3",
+ "windows 0.62.2",
 ]
 
 [[package]]
@@ -1796,6 +1848,16 @@ dependencies = [
  "crossbeam-utils",
 ]
 
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5181e0de7b61eb03a81e347d6dd8797bae9da5146707b51077e2d71a54ec0ceb"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+
 [[package]]
 name = "crossbeam-epoch"
 version = "0.9.20"
@@ -2120,6 +2182,15 @@ dependencies = [
  "syn 2.0.118",
 ]
 
+[[package]]
+name = "dary_heap"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b1e3a325bc115f096c8b77bbf027a7c2592230e70be2d985be950d3d5e60ebe"
+dependencies = [
+ "serde",
+]
+
 [[package]]
 name = "dasp_sample"
 version = "0.11.0"
@@ -2149,7 +2220,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ccc2776f0c61eca1ca32528f85548abd1a4be8fb53d1b21c013e4f18da1e7090"
 dependencies = [
  "data-encoding",
- "syn 1.0.109",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -2617,6 +2688,12 @@ version = "3.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dea2df4cf52843e0452895c455a1a2cfbb842a1e7329671acf418fdc53ed4c59"
 
+[[package]]
+name = "esaxx-rs"
+version = "0.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d817e038c30374a4bcb22f94d0a8a0e216958d4c3dcde369b1439fec4bdda6e6"
+
 [[package]]
 name = "euclid"
 version = "0.22.14"
@@ -2675,6 +2752,17 @@ dependencies = [
  "regex",
 ]
 
+[[package]]
+name = "fancy-regex"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e24cb5a94bcae1e5408b0effca5cd7172ea3c5755049c5f3af4cd283a165298"
+dependencies = [
+ "bit-set 0.8.0",
+ "regex-automata",
+ "regex-syntax",
+]
+
 [[package]]
 name = "fast-srgb8"
 version = "1.0.0"
@@ -3099,8 +3187,8 @@ dependencies = [
  "libc",
  "log",
  "rustversion",
- "windows-link 0.1.3",
- "windows-result 0.3.4",
+ "windows-link 0.2.1",
+ "windows-result 0.4.1",
 ]
 
 [[package]]
@@ -3845,7 +3933,7 @@ dependencies = [
  "tokio",
  "tower-service",
  "tracing",
- "windows-registry 0.5.3",
+ "windows-registry 0.6.1",
 ]
 
 [[package]]
@@ -3860,7 +3948,7 @@ dependencies = [
  "js-sys",
  "log",
  "wasm-bindgen",
- "windows-core 0.61.2",
+ "windows-core 0.62.2",
 ]
 
 [[package]]
@@ -4746,6 +4834,39 @@ version = "0.4.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
 
+[[package]]
+name = "logos"
+version = "0.14.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7251356ef8cb7aec833ddf598c6cb24d17b689d20b993f9d11a3d764e34e6458"
+dependencies = [
+ "logos-derive",
+]
+
+[[package]]
+name = "logos-codegen"
+version = "0.14.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59f80069600c0d66734f5ff52cc42f2dabd6b29d205f333d61fd7832e9e9963f"
+dependencies = [
+ "beef",
+ "fnv",
+ "lazy_static",
+ "proc-macro2",
+ "quote",
+ "regex-syntax",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "logos-derive"
+version = "0.14.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24fb722b06a9dc12adb0963ed585f19fc61dc5413e6a9be9422ef92c091e731d"
+dependencies = [
+ "logos-codegen",
+]
+
 [[package]]
 name = "loom"
 version = "0.7.2"
@@ -4855,6 +4976,22 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "macro_rules_attribute"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b3ae8f6d608c795738406608304d30a2dfbdc8e58e44f7ba43236da5208ded3c"
+dependencies = [
+ "macro_rules_attribute-proc_macro",
+ "pastey",
+]
+
+[[package]]
+name = "macro_rules_attribute-proc_macro"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc04a4c58212d57930a24bf47d3fa87485264a3a054e9c10e042eb373573ad3c"
+
 [[package]]
 name = "markup5ever"
 version = "0.38.0"
@@ -4881,6 +5018,16 @@ version = "0.8.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3"
 
+[[package]]
+name = "matrixmultiply"
+version = "0.3.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f607c237553f086e7043417a51df26b2eb899d3caff94e6a67592ff992fedc7"
+dependencies = [
+ "autocfg",
+ "rawpointer",
+]
+
 [[package]]
 name = "maybe-async"
 version = "0.2.11"
@@ -4936,8 +5083,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-api-client"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "hex",
  "mesh-llm-client",
@@ -4946,8 +5093,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-api-server"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "mesh-llm-api-client",
@@ -4957,13 +5104,13 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-build-info"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 
 [[package]]
 name = "mesh-llm-client"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -4980,7 +5127,7 @@ dependencies = [
  "mesh-llm-types",
  "model-artifact",
  "nostr-sdk",
- "prost",
+ "prost 0.14.4",
  "rand 0.10.2",
  "rustls",
  "serde",
@@ -4994,8 +5141,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-config"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "dirs",
@@ -5010,8 +5157,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-embedded-runtime"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "mesh-llm-host-runtime",
@@ -5020,8 +5167,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-events"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "clap",
@@ -5032,8 +5179,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-gpu-bench"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "cc",
@@ -5045,8 +5192,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-guardrails"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "serde",
  "serde_json",
@@ -5054,16 +5201,16 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-hardware-profile"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "mesh-llm-native-runtime",
 ]
 
 [[package]]
 name = "mesh-llm-host-runtime"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "argon2",
@@ -5085,7 +5232,6 @@ dependencies = [
  "http",
  "http-body-util",
  "httparse",
- "if-addrs",
  "iroh",
  "json5",
  "keyring",
@@ -5119,7 +5265,7 @@ dependencies = [
  "opentelemetry",
  "opentelemetry-otlp",
  "opentelemetry_sdk",
- "prost",
+ "prost 0.14.4",
  "rand 0.10.2",
  "regex-lite",
  "reqwest 0.12.28",
@@ -5133,6 +5279,7 @@ dependencies = [
  "serde_yaml",
  "sha2 0.10.9",
  "skippy-coordinator",
+ "skippy-ffi",
  "skippy-protocol",
  "skippy-runtime",
  "skippy-server",
@@ -5155,8 +5302,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-identity"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "argon2",
  "base64 0.22.1",
@@ -5177,8 +5324,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-native-runtime"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "serde",
@@ -5188,8 +5335,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-node"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "mesh-llm-types",
@@ -5202,13 +5349,13 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-plugin"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "async-trait",
- "prost",
- "prost-build",
+ "prost 0.14.4",
+ "prost-build 0.14.4",
  "protoc-bin-vendored",
  "rmcp",
  "schemars 1.2.1",
@@ -5219,8 +5366,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-plugin-manager"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "dirs",
@@ -5230,6 +5377,7 @@ dependencies = [
  "reqwest 0.12.28",
  "serde",
  "serde_json",
+ "sha2 0.10.9",
  "tar",
  "tempfile",
  "zip 2.4.2",
@@ -5237,29 +5385,29 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-protocol"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "hex",
  "iroh",
- "prost",
+ "prost 0.14.4",
  "serde_json",
  "sha2 0.10.9",
 ]
 
 [[package]]
 name = "mesh-llm-routing"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "iroh",
 ]
 
 [[package]]
 name = "mesh-llm-runtime-install"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "dirs",
@@ -5281,8 +5429,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-sdk"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "mesh-llm-api-client",
@@ -5296,8 +5444,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-skills"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "dirs",
@@ -5307,8 +5455,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-system"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "chrono",
@@ -5330,8 +5478,8 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-types"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "hex",
  "serde",
@@ -5341,13 +5489,13 @@ dependencies = [
 
 [[package]]
 name = "mesh-llm-ui"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 
 [[package]]
 name = "mesh-mixture-of-agents"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "async-trait",
  "mesh-llm-guardrails",
@@ -5358,6 +5506,28 @@ dependencies = [
  "tracing",
 ]
 
+[[package]]
+name = "miette"
+version = "7.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5f98efec8807c63c752b5bd61f862c165c115b0a35685bdcfd9238c7aeb592b7"
+dependencies = [
+ "cfg-if 1.0.4",
+ "miette-derive",
+ "unicode-width 0.1.14",
+]
+
+[[package]]
+name = "miette-derive"
+version = "7.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db5b29714e950dbb20d5e6f74f9dcec4edbcc1067bb7f8ed198c097b8c1a818b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
 [[package]]
 name = "mime"
 version = "0.3.17"
@@ -5419,8 +5589,8 @@ dependencies = [
 
 [[package]]
 name = "model-artifact"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -5430,8 +5600,8 @@ dependencies = [
 
 [[package]]
 name = "model-hf"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -5448,8 +5618,8 @@ dependencies = [
 
 [[package]]
 name = "model-package"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "bytes",
@@ -5468,16 +5638,16 @@ dependencies = [
 
 [[package]]
 name = "model-ref"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "serde",
 ]
 
 [[package]]
 name = "model-resolver"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "model-artifact",
@@ -5503,6 +5673,28 @@ dependencies = [
  "uuid",
 ]
 
+[[package]]
+name = "monostate"
+version = "0.1.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3341a273f6c9d5bef1908f17b7267bbab0e95c9bf69a0d4dcf8e9e1b2c76ef67"
+dependencies = [
+ "monostate-impl",
+ "serde",
+ "serde_core",
+]
+
+[[package]]
+name = "monostate-impl"
+version = "0.1.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4db6d5580af57bf992f59068d4ea26fd518574ff48d7639b255a36f9de6e7e9"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
 [[package]]
 name = "more-asserts"
 version = "0.3.1"
@@ -5630,6 +5822,21 @@ dependencies = [
  "tempfile",
 ]
 
+[[package]]
+name = "ndarray"
+version = "0.17.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "520080814a7a6b4a6e9070823bb24b4531daac8c4627e08ba5de8c5ef2f2752d"
+dependencies = [
+ "matrixmultiply",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "portable-atomic",
+ "portable-atomic-util",
+ "rawpointer",
+]
+
 [[package]]
 name = "ndk"
 version = "0.9.0"
@@ -5917,9 +6124,9 @@ dependencies = [
 
 [[package]]
 name = "nostr"
-version = "0.44.6"
+version = "0.44.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e826dd648489de2c5b293920e20b92932ef820302007c1987c758d4d06eeb2cf"
+checksum = "c7d3d987ea7078dc36947cde532637c472a229426702e4331dd7667325378bd9"
 dependencies = [
  "base64 0.22.1",
  "bech32",
@@ -5961,9 +6168,9 @@ dependencies = [
 
 [[package]]
 name = "nostr-relay-pool"
-version = "0.44.1"
+version = "0.44.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "91b2c039df4f96c4bf7dae52a74fd5516ad6dda83a11c0c69dea91b5255a4f37"
+checksum = "c85c54d6ca9aae4ae2bf19a7663ba9db5f45f783f1d24aff55f006386b8b99a1"
 dependencies = [
  "async-utility",
  "async-wsocket",
@@ -6131,7 +6338,7 @@ version = "0.7.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "680998035259dcfcafe653688bf2aa6d3e2dc05e98be6ab46afb089dc84f1df8"
 dependencies = [
- "proc-macro-crate 1.3.1",
+ "proc-macro-crate 3.5.0",
  "proc-macro2",
  "quote",
  "syn 2.0.118",
@@ -6505,8 +6712,8 @@ dependencies = [
 
 [[package]]
 name = "openai-frontend"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "async-trait",
  "axum",
@@ -6611,7 +6818,7 @@ dependencies = [
  "opentelemetry-http",
  "opentelemetry-proto",
  "opentelemetry_sdk",
- "prost",
+ "prost 0.14.4",
  "reqwest 0.12.28",
  "thiserror 2.0.18",
 ]
@@ -6626,7 +6833,7 @@ dependencies = [
  "const-hex",
  "opentelemetry",
  "opentelemetry_sdk",
- "prost",
+ "prost 0.14.4",
  "serde",
  "serde_json",
  "tonic",
@@ -6692,6 +6899,24 @@ dependencies = [
  "pin-project-lite",
 ]
 
+[[package]]
+name = "ort"
+version = "2.0.0-rc.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7de3af33d24a745ffb8fab904b13478438d1cd52868e6f17735ef6e1f8bf133"
+dependencies = [
+ "ndarray",
+ "ort-sys",
+ "smallvec",
+ "tracing",
+]
+
+[[package]]
+name = "ort-sys"
+version = "2.0.0-rc.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7b497d21a8b6fbb4b5a544f8fadb77e801a09ae0add9e411d31c6f89e3c1e90"
+
 [[package]]
 name = "os_pipe"
 version = "1.2.3"
@@ -6699,7 +6924,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7d8fae84b431384b68627d0f9b3b1245fcf9f46f6c0e3dc902e9dce64edd1967"
 dependencies = [
  "libc",
- "windows-sys 0.45.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -6919,6 +7144,16 @@ dependencies = [
  "pest",
 ]
 
+[[package]]
+name = "petgraph"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3672b37090dbd86368a4145bc067582552b29c27377cad4e0a306c97f9bd7772"
+dependencies = [
+ "fixedbitset 0.5.7",
+ "indexmap 2.14.0",
+]
+
 [[package]]
 name = "petgraph"
 version = "0.8.3"
@@ -7183,6 +7418,15 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "portable-atomic-util"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a106d1259c23fac8e543272398ae0e3c0b8d33c88ed73d0cc71b0f1d902618"
+dependencies = [
+ "portable-atomic",
+]
+
 [[package]]
 name = "portmapper"
 version = "0.19.1"
@@ -7393,6 +7637,16 @@ dependencies = [
  "unarray",
 ]
 
+[[package]]
+name = "prost"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2796faa41db3ec313a31f7624d9286acf277b52de526150b7e69f3debf891ee5"
+dependencies = [
+ "bytes",
+ "prost-derive 0.13.5",
+]
+
 [[package]]
 name = "prost"
 version = "0.14.4"
@@ -7400,7 +7654,27 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "528ac67416ff8646872a3c02cad9cc4ee5dc9f9540c9b10771855c95cb2e5ae1"
 dependencies = [
  "bytes",
- "prost-derive",
+ "prost-derive 0.14.4",
+]
+
+[[package]]
+name = "prost-build"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be769465445e8c1474e9c5dac2018218498557af32d9ed057325ec9a41ae81bf"
+dependencies = [
+ "heck 0.5.0",
+ "itertools",
+ "log",
+ "multimap",
+ "once_cell",
+ "petgraph 0.7.1",
+ "prettyplease",
+ "prost 0.13.5",
+ "prost-types 0.13.5",
+ "regex",
+ "syn 2.0.118",
+ "tempfile",
 ]
 
 [[package]]
@@ -7409,19 +7683,32 @@ version = "0.14.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "03da047801ff44bb6a4d407d4860c05fd70bb81714e6b2f3812603d5b145b042"
 dependencies = [
- "heck 0.4.1",
+ "heck 0.5.0",
  "itertools",
  "log",
  "multimap",
- "petgraph",
+ "petgraph 0.8.3",
  "prettyplease",
- "prost",
- "prost-types",
+ "prost 0.14.4",
+ "prost-types 0.14.4",
  "regex",
  "syn 2.0.118",
  "tempfile",
 ]
 
+[[package]]
+name = "prost-derive"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a56d757972c98b346a9b766e3f02746cde6dd1cd1d1d563472929fdd74bec4d"
+dependencies = [
+ "anyhow",
+ "itertools",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
 [[package]]
 name = "prost-derive"
 version = "0.14.4"
@@ -7435,13 +7722,35 @@ dependencies = [
  "syn 2.0.118",
 ]
 
+[[package]]
+name = "prost-reflect"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b5edd582b62f5cde844716e66d92565d7faf7ab1445c8cebce6e00fba83ddb2"
+dependencies = [
+ "logos",
+ "miette",
+ "once_cell",
+ "prost 0.13.5",
+ "prost-types 0.13.5",
+]
+
+[[package]]
+name = "prost-types"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52c2c1bf36ddb1a1c396b3601a3cec27c2462e45f07c386894ec3ccf5332bd16"
+dependencies = [
+ "prost 0.13.5",
+]
+
 [[package]]
 name = "prost-types"
 version = "0.14.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f94967dc7688f3054c7fac87473ffae4cc4c3904800e2d9f5b857246d8963b0a"
 dependencies = [
- "prost",
+ "prost 0.14.4",
 ]
 
 [[package]]
@@ -7508,6 +7817,33 @@ version = "3.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "95067976aca6421a523e491fce939a3e65249bac4b977adee0ee9771568e8aa3"
 
+[[package]]
+name = "protox"
+version = "0.7.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6f352af331bf637b8ecc720f7c87bf903d2571fa2e14a66e9b2558846864b54a"
+dependencies = [
+ "bytes",
+ "miette",
+ "prost 0.13.5",
+ "prost-reflect",
+ "prost-types 0.13.5",
+ "protox-parse",
+ "thiserror 1.0.69",
+]
+
+[[package]]
+name = "protox-parse"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a3a462d115462c080ae000c29a47f0b3985737e5d3a995fcdbcaa5c782068dde"
+dependencies = [
+ "logos",
+ "miette",
+ "prost-types 0.13.5",
+ "thiserror 1.0.69",
+]
+
 [[package]]
 name = "pxfm"
 version = "0.1.30"
@@ -7756,7 +8092,7 @@ dependencies = [
  "thiserror 2.0.18",
  "unicode-segmentation",
  "unicode-truncate",
- "unicode-width",
+ "unicode-width 0.2.2",
 ]
 
 [[package]]
@@ -7819,7 +8155,7 @@ dependencies = [
  "strum",
  "time",
  "unicode-segmentation",
- "unicode-width",
+ "unicode-width 0.2.2",
 ]
 
 [[package]]
@@ -7828,6 +8164,43 @@ version = "0.6.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "20675572f6f24e9e76ef639bc5552774ed45f1c30e2951e1e99c59888861c539"
 
+[[package]]
+name = "rawpointer"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3"
+
+[[package]]
+name = "rayon"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+
+[[package]]
+name = "rayon-cond"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2964d0cf57a3e7a06e8183d14a8b527195c706b7983549cd5462d5aa3747438f"
+dependencies = [
+ "either",
+ "itertools",
+ "rayon",
+]
+
+[[package]]
+name = "rayon-core"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+
 [[package]]
 name = "realfft"
 version = "3.5.0"
@@ -8640,6 +9013,18 @@ version = "0.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cd0b0ec5f1c1ca621c432a25813d8d60c88abe6d3e08a3eb9cf37d97a0fe3d73"
 
+[[package]]
+name = "sentencepiece-model"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40b87bf750a8322c3236d7aa63c1f4a6862187d00d2d8b038e1dfe263bfe43ec"
+dependencies = [
+ "miette",
+ "prost 0.13.5",
+ "prost-build 0.13.5",
+ "protox",
+]
+
 [[package]]
 name = "serde"
 version = "1.0.228"
@@ -9038,8 +9423,8 @@ checksum = "8ee5873ec9cce0195efcb7a4e9507a04cd49aec9c83d0389df45b1ef7ba2e649"
 
 [[package]]
 name = "skippy-cache"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "blake3",
@@ -9048,40 +9433,40 @@ dependencies = [
 
 [[package]]
 name = "skippy-coordinator"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "thiserror 2.0.18",
 ]
 
 [[package]]
 name = "skippy-ffi"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "libloading 0.8.9",
 ]
 
 [[package]]
 name = "skippy-metrics"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 
 [[package]]
 name = "skippy-protocol"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
- "prost",
- "prost-build",
+ "prost 0.14.4",
+ "prost-build 0.14.4",
  "protoc-bin-vendored",
  "serde",
 ]
 
 [[package]]
 name = "skippy-runtime"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "anyhow",
  "libc",
@@ -9094,9 +9479,10 @@ dependencies = [
 
 [[package]]
 name = "skippy-server"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
+ "ahash",
  "anyhow",
  "async-trait",
  "axum",
@@ -9122,8 +9508,8 @@ dependencies = [
 
 [[package]]
 name = "skippy-topology"
-version = "0.73.1"
-source = "git+https://github.com/Mesh-LLM/mesh-llm.git?rev=f455d493a2ae82baf2a326e2d0fda351433b4b30#f455d493a2ae82baf2a326e2d0fda351433b4b30"
+version = "0.74.0"
+source = "git+https://github.com/Mesh-LLM/mesh-llm.git?tag=v0.74.0#e60b2fe43aa05271569fbeff2a457133aef456a1"
 dependencies = [
  "serde",
  "serde_json",
@@ -9252,6 +9638,18 @@ dependencies = [
  "der",
 ]
 
+[[package]]
+name = "spm_precompiled"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5851699c4033c63636f7ea4cf7b7c1f1bf06d0cc03cfb42e711de5a5c46cf326"
+dependencies = [
+ "base64 0.13.1",
+ "nom 7.1.3",
+ "serde",
+ "unicode-segmentation",
+]
+
 [[package]]
 name = "sse-stream"
 version = "0.2.4"
@@ -9386,6 +9784,7 @@ dependencies = [
  "symphonia-bundle-flac",
  "symphonia-bundle-mp3",
  "symphonia-codec-aac",
+ "symphonia-codec-alac",
  "symphonia-codec-pcm",
  "symphonia-codec-vorbis",
  "symphonia-core",
@@ -9430,6 +9829,16 @@ dependencies = [
  "symphonia-core",
 ]
 
+[[package]]
+name = "symphonia-codec-alac"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8413fa754942ac16a73634c9dfd1500ed5c61430956b33728567f667fdd393ab"
+dependencies = [
+ "log",
+ "symphonia-core",
+]
+
 [[package]]
 name = "symphonia-codec-pcm"
 version = "0.5.5"
@@ -9633,7 +10042,7 @@ version = "1.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fce91f2f0ec87dff7e6bcbbeb267439aa1188703003c6055193c821487400432"
 dependencies = [
- "unicode-width",
+ "unicode-width 0.2.2",
 ]
 
 [[package]]
@@ -10150,7 +10559,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
 dependencies = [
  "fastrand",
- "getrandom 0.3.4",
+ "getrandom 0.4.3",
  "once_cell",
  "rustix 1.1.4",
  "windows-sys 0.61.2",
@@ -10208,7 +10617,7 @@ dependencies = [
  "anyhow",
  "base64 0.22.1",
  "bitflags 2.13.0",
- "fancy-regex",
+ "fancy-regex 0.11.0",
  "filedescriptor",
  "finl_unicode",
  "fixedbitset 0.4.2",
@@ -10371,6 +10780,39 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
+[[package]]
+name = "tokenizers"
+version = "0.22.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b238e22d44a15349529690fb07bd645cf58149a1b1e44d6cb5bd1641ff1a6223"
+dependencies = [
+ "ahash",
+ "aho-corasick",
+ "compact_str 0.9.1",
+ "dary_heap",
+ "derive_builder",
+ "esaxx-rs",
+ "fancy-regex 0.14.0",
+ "getrandom 0.3.4",
+ "itertools",
+ "log",
+ "macro_rules_attribute",
+ "monostate",
+ "paste",
+ "rand 0.9.4",
+ "rayon",
+ "rayon-cond",
+ "regex",
+ "regex-syntax",
+ "serde",
+ "serde_json",
+ "spm_precompiled",
+ "thiserror 2.0.18",
+ "unicode-normalization-alignments",
+ "unicode-segmentation",
+ "unicode_categories",
+]
+
 [[package]]
 name = "tokio"
 version = "1.52.3"
@@ -10704,7 +11146,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "50849f68853be452acf590cde0b146665b8d507b3b8af17261df47e02c209ea0"
 dependencies = [
  "bytes",
- "prost",
+ "prost 0.14.4",
  "tonic",
 ]
 
@@ -10885,7 +11327,7 @@ checksum = "b8765b90061cba6c22b5831f675da109ae5561588290f9fa2317adab2714d5a6"
 dependencies = [
  "memchr",
  "nom 8.0.0",
- "petgraph",
+ "petgraph 0.8.3",
 ]
 
 [[package]]
@@ -11056,6 +11498,15 @@ dependencies = [
  "tinyvec",
 ]
 
+[[package]]
+name = "unicode-normalization-alignments"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43f613e4fa046e69818dd287fdc4bc78175ff20331479dab6e1b0f98d57062de"
+dependencies = [
+ "smallvec",
+]
+
 [[package]]
 name = "unicode-segmentation"
 version = "1.13.3"
@@ -11070,9 +11521,15 @@ checksum = "16b380a1238663e5f8a691f9039c73e1cdae598a30e9855f541d29b08b53e9a5"
 dependencies = [
  "itertools",
  "unicode-segmentation",
- "unicode-width",
+ "unicode-width 0.2.2",
 ]
 
+[[package]]
+name = "unicode-width"
+version = "0.1.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7dd6e30e90baa6f72411720665d41d89b9a3d039dc45b8faea1ddd07f617f6af"
+
 [[package]]
 name = "unicode-width"
 version = "0.2.2"
@@ -11085,6 +11542,12 @@ version = "0.2.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
 
+[[package]]
+name = "unicode_categories"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39ec24b3121d976906ece63c9daad25b85969647682eee313cb5779fdd69e14e"
+
 [[package]]
 name = "universal-hash"
 version = "0.5.1"
@@ -11786,7 +12249,7 @@ version = "0.1.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
 dependencies = [
- "windows-sys 0.48.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -12415,8 +12878,8 @@ dependencies = [
  "log",
  "serde",
  "thiserror 2.0.18",
- "windows 0.61.3",
- "windows-core 0.61.2",
+ "windows 0.62.2",
+ "windows-core 0.62.2",
 ]
 
 [[package]]
diff --git a/desktop/src-tauri/Cargo.toml b/desktop/src-tauri/Cargo.toml
index 324218a49d..fd58f27878 100644
--- a/desktop/src-tauri/Cargo.toml
+++ b/desktop/src-tauri/Cargo.toml
@@ -2,7 +2,7 @@
 
 [package]
 name = "buzz-desktop"
-version = "0.5.0"
+version = "0.5.3"
 description = "Buzz desktop app"
 authors = ["you"]
 edition = "2021"
@@ -40,9 +40,16 @@ keyring = { version = "3.6.3", default-features = false, features = ["sync-secre
 # connection is dropped, which the plugin does immediately. Default features
 # keep the pure-Rust zbus backend, matching the plugin (no libdbus needed).
 notify-rust = "4"
+# Enable getUserMedia in the WebKitGTK webview (see src/linux_media.rs). Pinned
+# to the exact version wry links so both resolve to one webkit2gtk-sys and we
+# don't get duplicate symbols; bump in lockstep with wry.
+webkit2gtk = { version = "=2.0.2", features = ["v2_22"] }
 
 [target.'cfg(target_os = "macos")'.dependencies]
-objc2-app-kit = { version = "0.3.2", default-features = false, features = ["NSHapticFeedback"] }
+block2 = { version = "0.6", default-features = false, features = ["std"] }
+objc2 = { version = "0.6.4", default-features = false }
+objc2-app-kit = { version = "0.3.2", default-features = false, features = ["NSEvent", "NSHapticFeedback", "NSMenu", "NSMenuItem", "NSStatusItem", "block2"] }
+objc2-foundation = { version = "0.3.2", default-features = false, features = ["NSProcessInfo", "NSString"] }
 keyring = { version = "3.6.3", default-features = false, features = ["apple-native", "vendored"], optional = true }
 security-framework = { version = "3.7.0", features = ["OSX_10_15"] }
 window-vibrancy = "0.6"
@@ -58,7 +65,7 @@ user-idle = { version = "0.6", default-features = false }
 atomic-write-file = "0.3"
 anyhow = "1"
 dirs = "6"
-tauri = { version = "2", features = ["macos-private-api"] }
+tauri = { version = "2", features = ["macos-private-api", "tray-icon"] }
 tauri-plugin-deep-link = "2"
 tauri-plugin-opener = "2"
 tauri-plugin-single-instance = { version = "2", features = ["deep-link"] }
@@ -80,7 +87,10 @@ serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 serde_yaml = "0.9"
 toml = "0.8"
-nostr = { version = "0.44", features = ["nip44"] }
+nostr = { version = "0.44", features = ["nip44", "nip49"] }
+# OS-entropy source for backup passphrase generation (already in the tree as a
+# transitive dependency; pinned here for direct use).
+getrandom = "0.2"
 zeroize = "1"
 reqwest = { version = "0.13", features = ["json", "query", "stream", "blocking"] }
 rustls = { version = "0.23", default-features = false, features = ["aws_lc_rs", "std"] }
@@ -89,15 +99,16 @@ buzz_core_pkg = { package = "buzz-core", path = "../../crates/buzz-core" }
 buzz_persona_pkg = { package = "buzz-persona", path = "../../crates/buzz-persona" }
 buzz_sdk_pkg = { package = "buzz-sdk", path = "../../crates/buzz-sdk" }
 buzz_agent_pkg = { package = "buzz-agent", path = "../../crates/buzz-agent" }
+buzz_voice_pkg = { package = "buzz-voice", path = "../../crates/buzz-voice" }
 iroh = { version = "1.0.2", optional = true }
-mesh-llm-sdk = { git = "https://github.com/Mesh-LLM/mesh-llm.git", rev = "f455d493a2ae82baf2a326e2d0fda351433b4b30", package = "mesh-llm-sdk", default-features = false, features = ["client", "serving"], optional = true }
-mesh-llm-host-runtime = { git = "https://github.com/Mesh-LLM/mesh-llm.git", rev = "f455d493a2ae82baf2a326e2d0fda351433b4b30", package = "mesh-llm-host-runtime", default-features = false, features = ["dynamic-native-runtime"], optional = true }
+mesh-llm-sdk = { git = "https://github.com/Mesh-LLM/mesh-llm.git", tag = "v0.74.0", package = "mesh-llm-sdk", default-features = false, features = ["client", "serving"], optional = true }
+mesh-llm-host-runtime = { git = "https://github.com/Mesh-LLM/mesh-llm.git", tag = "v0.74.0", package = "mesh-llm-host-runtime", default-features = false, features = ["dynamic-native-runtime"], optional = true }
 # Model catalog + hardware survey for the Share-compute model picker (same
 # diagnose pattern as mesh-console). Lib name of mesh-llm-client is mesh_client.
-mesh-llm-client = { git = "https://github.com/Mesh-LLM/mesh-llm.git", rev = "f455d493a2ae82baf2a326e2d0fda351433b4b30", package = "mesh-llm-client", optional = true }
-mesh-llm-node = { git = "https://github.com/Mesh-LLM/mesh-llm.git", rev = "f455d493a2ae82baf2a326e2d0fda351433b4b30", package = "mesh-llm-node", optional = true }
-mesh-llm-system = { git = "https://github.com/Mesh-LLM/mesh-llm.git", rev = "f455d493a2ae82baf2a326e2d0fda351433b4b30", package = "mesh-llm-system", optional = true }
-mesh-llm-events = { git = "https://github.com/Mesh-LLM/mesh-llm.git", rev = "f455d493a2ae82baf2a326e2d0fda351433b4b30", package = "mesh-llm-events", optional = true }
+mesh-llm-client = { git = "https://github.com/Mesh-LLM/mesh-llm.git", tag = "v0.74.0", package = "mesh-llm-client", optional = true }
+mesh-llm-node = { git = "https://github.com/Mesh-LLM/mesh-llm.git", tag = "v0.74.0", package = "mesh-llm-node", optional = true }
+mesh-llm-system = { git = "https://github.com/Mesh-LLM/mesh-llm.git", tag = "v0.74.0", package = "mesh-llm-system", optional = true }
+mesh-llm-events = { git = "https://github.com/Mesh-LLM/mesh-llm.git", tag = "v0.74.0", package = "mesh-llm-events", optional = true }
 base64 = "0.22"
 sha2 = "0.11"
 tar = "0.4"
@@ -128,6 +139,7 @@ strip-ansi-escapes = "0.2"
 tracing = "0.1"
 
 [dev-dependencies]
+tauri-utils = "2"
 # `test-util` enables tokio's paused-clock (`start_paused`) so the relay
 # admission gate tests can assert exact wait durations without real sleeps.
 tokio = { version = "1", features = ["test-util"] }
diff --git a/desktop/src-tauri/assets/card_template.png b/desktop/src-tauri/assets/card_template.png
new file mode 100644
index 0000000000..2225d1d442
Binary files /dev/null and b/desktop/src-tauri/assets/card_template.png differ
diff --git a/desktop/src-tauri/examples/pocket_bench.rs b/desktop/src-tauri/examples/pocket_bench.rs
deleted file mode 100644
index b4f5635a95..0000000000
--- a/desktop/src-tauri/examples/pocket_bench.rs
+++ /dev/null
@@ -1,116 +0,0 @@
-//! Cold-vs-warm latency bench for Pocket TTS.
-//!
-//! This duplicates the small config-building snippet from `huddle::pocket` so it
-//! doesn't depend on changing module visibility for a one-off dev tool.
-//! Keep in sync with `huddle::pocket::load_text_to_speech`.
-//!
-//! Run with the model files in a directory (defaults to /tmp/pocket-tts-bench):
-//!   cargo run --release --example pocket_bench
-//!   cargo run --release --example pocket_bench /path/to/pocket-tts
-
-use std::path::PathBuf;
-use std::time::Instant;
-
-use sherpa_onnx::{
-    self, GenerationConfig, OfflineTts, OfflineTtsConfig, OfflineTtsModelConfig,
-    OfflineTtsPocketModelConfig, Wave,
-};
-
-const SAMPLE_RATE: u32 = 24_000;
-const TEST_TEXT: &str =
-    "Hello, this is a test of the new Pocket TTS engine running on sherpa-onnx.";
-
-fn main() {
-    let model_dir = std::env::args()
-        .nth(1)
-        .unwrap_or_else(|| "/tmp/pocket-tts-bench".to_string());
-    println!("Model dir: {model_dir}");
-
-    let dir = PathBuf::from(&model_dir);
-    let p = |name: &str| dir.join(name).to_string_lossy().into_owned();
-
-    let t0 = Instant::now();
-    let cfg = OfflineTtsConfig {
-        model: OfflineTtsModelConfig {
-            pocket: OfflineTtsPocketModelConfig {
-                lm_main: Some(p("lm_main.int8.onnx")),
-                lm_flow: Some(p("lm_flow.int8.onnx")),
-                encoder: Some(p("encoder.onnx")),
-                decoder: Some(p("decoder.int8.onnx")),
-                text_conditioner: Some(p("text_conditioner.onnx")),
-                vocab_json: Some(p("vocab.json")),
-                token_scores_json: Some(p("token_scores.json")),
-                voice_embedding_cache_capacity: 16,
-            },
-            num_threads: 1,
-            debug: false,
-            ..Default::default()
-        },
-        ..Default::default()
-    };
-    let engine = OfflineTts::create(&cfg).expect("engine create");
-    let load_ms = t0.elapsed().as_secs_f32() * 1000.0;
-    println!("Engine load:      {load_ms:.1} ms");
-
-    let t0 = Instant::now();
-    let voice_path = dir.join("reference_sample.wav");
-    let wave = Wave::read(voice_path.to_str().unwrap()).expect("voice WAV");
-    let samples = wave.samples().to_vec();
-    let sr = wave.sample_rate();
-    let voice_ms = t0.elapsed().as_secs_f32() * 1000.0;
-    println!("Voice load:       {voice_ms:.1} ms");
-
-    let gen = || GenerationConfig {
-        speed: 1.05,
-        num_steps: 1,
-        silence_scale: 1.0, // production setting (huddle::pocket::SYNTH_SILENCE_SCALE)
-        reference_audio: Some(samples.clone()),
-        reference_sample_rate: sr,
-        ..Default::default()
-    };
-
-    let t0 = Instant::now();
-    let cold = engine
-        .generate_with_config(TEST_TEXT, &gen(), None::<fn(&[f32], f32) -> bool>)
-        .expect("cold synth");
-    let cold_ms = t0.elapsed().as_secs_f32() * 1000.0;
-    let cold_audio_ms = (cold.samples().len() as f32 / SAMPLE_RATE as f32) * 1000.0;
-    let cold_rtf_x = cold_audio_ms / cold_ms;
-    println!(
-        "Cold synth:       {cold_ms:.1} ms  → {cold_audio_ms:.1} ms audio  → {cold_rtf_x:.2}× realtime"
-    );
-
-    let t0 = Instant::now();
-    let warm = engine
-        .generate_with_config(TEST_TEXT, &gen(), None::<fn(&[f32], f32) -> bool>)
-        .expect("warm synth");
-    let warm_ms = t0.elapsed().as_secs_f32() * 1000.0;
-    let warm_audio_ms = (warm.samples().len() as f32 / SAMPLE_RATE as f32) * 1000.0;
-    let warm_rtf_x = warm_audio_ms / warm_ms;
-    println!(
-        "Warm synth:       {warm_ms:.1} ms  → {warm_audio_ms:.1} ms audio  → {warm_rtf_x:.2}× realtime"
-    );
-
-    let out_path = "/tmp/pocket_bench_out.wav";
-    let ok = sherpa_onnx::write(out_path, warm.samples(), SAMPLE_RATE as i32);
-    println!(
-        "Wrote {} ({} samples, ok={ok})",
-        out_path,
-        warm.samples().len()
-    );
-
-    let delta_ms = cold_ms - warm_ms;
-    let delta_pct = (delta_ms / warm_ms) * 100.0;
-    println!();
-    println!("Cold/warm delta:  {delta_ms:+.1} ms  ({delta_pct:+.1}%)");
-    println!(
-        "Decision: warmup {}.",
-        if delta_ms > 200.0 {
-            "RECOMMENDED — significant cold-call penalty"
-        } else if delta_ms > 50.0 {
-            "OPTIONAL — small cold-call penalty"
-        } else {
-            "UNNECESSARY — cold and warm essentially equal"
-        }
-    );
-}
diff --git a/desktop/src-tauri/examples/pocket_clip_probe.rs b/desktop/src-tauri/examples/pocket_clip_probe.rs
deleted file mode 100644
index ad8657599f..0000000000
--- a/desktop/src-tauri/examples/pocket_clip_probe.rs
+++ /dev/null
@@ -1,122 +0,0 @@
-//! Clipping probe for any fixed playback gain applied after Pocket TTS synth.
-//!
-//! Synthesises a spread of sentences (short/long, calm/energetic) and reports
-//! the raw peak of each, the post-gain peak, and the fraction of samples that
-//! would hit a ±1.0 clamp — i.e. how much a fixed gain would flat-top the
-//! waveform ("blown out" distortion).
-//!
-//! History: the production pipeline briefly shipped a fixed 9.3× gain
-//! calibrated on a single bench utterance that peaked at 0.076. This probe
-//! showed real output peaks at 0.4–0.97, so that gain clipped 13–34% of all
-//! samples (the 2026-06-12 "blown out" report). Production now applies no
-//! gain — run this probe before reintroducing one.
-//!
-//! Run with model files in ~/.buzz/models/pocket-tts (override with arg 1):
-//!   cargo run --release --example pocket_clip_probe
-
-use std::path::PathBuf;
-
-use sherpa_onnx::{
-    self, GenerationConfig, OfflineTts, OfflineTtsConfig, OfflineTtsModelConfig,
-    OfflineTtsPocketModelConfig, Wave,
-};
-
-/// Candidate gain under test (the regressed production value).
-const GAIN: f32 = 9.3;
-
-const PROMPTS: &[&str] = &[
-    "Hello, this is a test of the new Pocket TTS engine running on sherpa-onnx.",
-    "Yep, I can hear you.",
-    "Absolutely! That sounds fantastic, let's do it right now!",
-    "The quick brown fox jumps over the lazy dog near the riverbank.",
-    "I found three problems in the code: a race condition, a memory leak, and an off-by-one error in the loop bounds.",
-    "No.",
-    "Warning! The build failed because seventeen tests crashed unexpectedly!",
-    "Sure, I can walk you through the whole pipeline step by step whenever you're ready.",
-];
-
-fn main() {
-    let model_dir = std::env::args().nth(1).unwrap_or_else(|| {
-        dirs::home_dir()
-            .expect("home dir")
-            .join(".buzz/models/pocket-tts")
-            .to_string_lossy()
-            .into_owned()
-    });
-    eprintln!("Model dir: {model_dir}");
-
-    let dir = PathBuf::from(&model_dir);
-    let p = |name: &str| dir.join(name).to_string_lossy().into_owned();
-
-    let cfg = OfflineTtsConfig {
-        model: OfflineTtsModelConfig {
-            pocket: OfflineTtsPocketModelConfig {
-                lm_main: Some(p("lm_main.int8.onnx")),
-                lm_flow: Some(p("lm_flow.int8.onnx")),
-                encoder: Some(p("encoder.onnx")),
-                decoder: Some(p("decoder.int8.onnx")),
-                text_conditioner: Some(p("text_conditioner.onnx")),
-                vocab_json: Some(p("vocab.json")),
-                token_scores_json: Some(p("token_scores.json")),
-                voice_embedding_cache_capacity: 16,
-            },
-            num_threads: 1,
-            debug: false,
-            ..Default::default()
-        },
-        ..Default::default()
-    };
-    let engine = OfflineTts::create(&cfg).expect("engine create");
-
-    let voice_path = dir.join("reference_sample.wav");
-    let wave = Wave::read(voice_path.to_str().unwrap()).expect("voice WAV");
-    let voice_samples = wave.samples().to_vec();
-    let voice_sr = wave.sample_rate();
-
-    let gen = || GenerationConfig {
-        speed: 1.05,
-        num_steps: 1,
-        silence_scale: 1.0,
-        reference_audio: Some(voice_samples.clone()),
-        reference_sample_rate: voice_sr,
-        ..Default::default()
-    };
-
-    let _ = engine.generate_with_config("warmup.", &gen(), None::<fn(&[f32], f32) -> bool>);
-
-    println!(
-        "{:<46} | {:>8} | {:>9} | {:>9} | {:>10}",
-        "prompt", "raw peak", "raw RMS", "post-gain", "% clipped"
-    );
-    println!("{}", "-".repeat(95));
-
-    let mut worst_clip = 0.0f32;
-    for prompt in PROMPTS {
-        let out = engine
-            .generate_with_config(prompt, &gen(), None::<fn(&[f32], f32) -> bool>)
-            .expect("synth");
-        let samples = out.samples();
-
-        let peak = samples.iter().fold(0.0f32, |m, s| m.max(s.abs()));
-        let rms = (samples.iter().map(|s| s * s).sum::<f32>() / samples.len() as f32).sqrt();
-        let post = peak * GAIN;
-        let clipped = samples.iter().filter(|s| s.abs() * GAIN > 1.0).count();
-        let clip_pct = 100.0 * clipped as f32 / samples.len() as f32;
-        worst_clip = worst_clip.max(clip_pct);
-
-        let label: String = prompt.chars().take(44).collect();
-        println!("{label:<46} | {peak:>8.4} | {rms:>9.4} | {post:>9.3} | {clip_pct:>9.3}%");
-    }
-
-    println!();
-    println!(
-        "Verdict: worst-case clipped fraction {worst_clip:.3}% — {}",
-        if worst_clip > 0.1 {
-            "AUDIBLE DISTORTION LIKELY (gain too hot)"
-        } else if worst_clip > 0.0 {
-            "marginal — occasional transient clipping"
-        } else {
-            "no clipping at this gain"
-        }
-    );
-}
diff --git a/desktop/src-tauri/examples/pocket_onset_probe.rs b/desktop/src-tauri/examples/pocket_onset_probe.rs
deleted file mode 100644
index 05b4d0193c..0000000000
--- a/desktop/src-tauri/examples/pocket_onset_probe.rs
+++ /dev/null
@@ -1,149 +0,0 @@
-//! Onset-attenuation probe for Pocket TTS.
-//!
-//! Synthesises a handful of short sentences and dumps per-sentence onset
-//! statistics (samples[0], 1ms/5ms/20ms peak + RMS) so we can decide whether
-//! the production `apply_fades` 8 ms fade-in is masking real audio.
-//!
-//! Also writes the raw (un-faded, un-normalised) audio of each sentence to
-//! /tmp so they can be inspected in Audacity / aplay without rodio in the
-//! loop.
-//!
-//! Run with model files in /tmp/pocket-tts-bench (override with arg 1):
-//!   cargo run --release --example pocket_onset_probe
-//!   cargo run --release --example pocket_onset_probe /path/to/pocket-tts
-
-use std::path::PathBuf;
-
-use sherpa_onnx::{
-    self, GenerationConfig, OfflineTts, OfflineTtsConfig, OfflineTtsModelConfig,
-    OfflineTtsPocketModelConfig, Wave,
-};
-
-const SAMPLE_RATE: u32 = 24_000;
-
-/// Test prompts chosen to span different onsets:
-/// - palatal glide 'Y' (soft onset)
-/// - voiceless fricative 'H' (very soft onset)
-/// - labio-velar glide 'W' (medium onset)
-/// - voiceless stop 'T' (hard onset)
-const PROMPTS: &[&str] = &[
-    "Yep, I can hear you.",
-    "Hello there friend.",
-    "What can I help with?",
-    "Try this experiment now.",
-];
-
-fn main() {
-    let model_dir = std::env::args()
-        .nth(1)
-        .unwrap_or_else(|| "/tmp/pocket-tts-bench".to_string());
-    eprintln!("Model dir: {model_dir}");
-
-    let dir = PathBuf::from(&model_dir);
-    let p = |name: &str| dir.join(name).to_string_lossy().into_owned();
-
-    let cfg = OfflineTtsConfig {
-        model: OfflineTtsModelConfig {
-            pocket: OfflineTtsPocketModelConfig {
-                lm_main: Some(p("lm_main.int8.onnx")),
-                lm_flow: Some(p("lm_flow.int8.onnx")),
-                encoder: Some(p("encoder.onnx")),
-                decoder: Some(p("decoder.int8.onnx")),
-                text_conditioner: Some(p("text_conditioner.onnx")),
-                vocab_json: Some(p("vocab.json")),
-                token_scores_json: Some(p("token_scores.json")),
-                voice_embedding_cache_capacity: 16,
-            },
-            num_threads: 1,
-            debug: false,
-            ..Default::default()
-        },
-        ..Default::default()
-    };
-    let engine = OfflineTts::create(&cfg).expect("engine create");
-
-    let voice_path = dir.join("reference_sample.wav");
-    let wave = Wave::read(voice_path.to_str().unwrap()).expect("voice WAV");
-    let voice_samples = wave.samples().to_vec();
-    let voice_sr = wave.sample_rate();
-
-    // Warmup so we're not measuring cold-call jitter.
-    {
-        let cfg = GenerationConfig {
-            speed: 1.05,
-            num_steps: 1,
-            silence_scale: 1.0, // production setting (huddle::pocket::SYNTH_SILENCE_SCALE)
-            reference_audio: Some(voice_samples.clone()),
-            reference_sample_rate: voice_sr,
-            ..Default::default()
-        };
-        let _ = engine.generate_with_config("warmup.", &cfg, None::<fn(&[f32], f32) -> bool>);
-    }
-
-    println!(
-        "{:<28} | {:>10} | {:>10} {:>10} | {:>10} {:>10} | {:>10} {:>10}",
-        "prompt",
-        "samples[0]",
-        "peak@1ms",
-        "rms@1ms",
-        "peak@5ms",
-        "rms@5ms",
-        "peak@20ms",
-        "rms@20ms"
-    );
-    println!("{}", "-".repeat(120));
-
-    for prompt in PROMPTS {
-        // Mirror the production prompt-prep (capitalise + terminal punctuation).
-        // These prompts already have it, so this is just to match what
-        // sherpa-onnx sees in production.
-        let cfg = GenerationConfig {
-            speed: 1.05,
-            num_steps: 1,
-            silence_scale: 1.0, // production setting (huddle::pocket::SYNTH_SILENCE_SCALE)
-            reference_audio: Some(voice_samples.clone()),
-            reference_sample_rate: voice_sr,
-            ..Default::default()
-        };
-        let out = engine
-            .generate_with_config(prompt, &cfg, None::<fn(&[f32], f32) -> bool>)
-            .expect("synth");
-        let samples = out.samples();
-
-        let n_1ms = (SAMPLE_RATE as f32 * 0.001) as usize;
-        let n_5ms = (SAMPLE_RATE as f32 * 0.005) as usize;
-        let n_20ms = (SAMPLE_RATE as f32 * 0.020) as usize;
-
-        let stats = |range: &[f32]| -> (f32, f32) {
-            if range.is_empty() {
-                return (0.0, 0.0);
-            }
-            let peak = range.iter().fold(0.0_f32, |a, &x| a.max(x.abs()));
-            let sumsq: f32 = range.iter().map(|x| x * x).sum();
-            let rms = (sumsq / range.len() as f32).sqrt();
-            (peak, rms)
-        };
-
-        let first = samples.first().copied().unwrap_or(0.0);
-        let (p1, r1) = stats(&samples[..n_1ms.min(samples.len())]);
-        let (p5, r5) = stats(&samples[..n_5ms.min(samples.len())]);
-        let (p20, r20) = stats(&samples[..n_20ms.min(samples.len())]);
-
-        println!(
-            "{:<28} | {:>10.6} | {:>10.6} {:>10.6} | {:>10.6} {:>10.6} | {:>10.6} {:>10.6}",
-            prompt, first, p1, r1, p5, r5, p20, r20
-        );
-
-        let safe: String = prompt
-            .chars()
-            .map(|c| if c.is_ascii_alphanumeric() { c } else { '_' })
-            .collect();
-        let out_path = format!("/tmp/pocket_onset_{}.wav", &safe[..safe.len().min(24)]);
-        let _ = sherpa_onnx::write(&out_path, samples, SAMPLE_RATE as i32);
-        eprintln!(
-            "  → wrote {out_path} ({} samples = {:.3} s)",
-            samples.len(),
-            samples.len() as f32 / SAMPLE_RATE as f32
-        );
-    }
-}
diff --git a/desktop/src-tauri/examples/pocket_quality_ab.rs b/desktop/src-tauri/examples/pocket_quality_ab.rs
deleted file mode 100644
index 0c31f1c910..0000000000
--- a/desktop/src-tauri/examples/pocket_quality_ab.rs
+++ /dev/null
@@ -1,519 +0,0 @@
-//! Reproducible blind Pocket TTS quality corpus generator.
-//!
-//! Renders Buzz's production prompt preparation and post-processing across:
-//! INT8/FP32 × per-sentence/grouped generation. The generated filenames are
-//! deterministically blinded; keep `key.json` away from listeners until their
-//! scoring sheet is complete.
-//!
-//! Usage:
-//!   cargo run --release --example pocket_quality_ab -- \
-//!     <int8-model-dir> <fp32-model-dir> <output-dir> [--idle-minutes N --only ITEM]
-//!
-//! The optional idle run intentionally creates one engine per condition, warms
-//! all four, sleeps once, and then makes each clip the first generation after
-//! dormancy. It requires `--only` because only the first synthesis after an
-//! uninterrupted idle is a valid post-idle observation. Run each 5/15-minute
-//! item as a separate process.
-
-// Importing the production module also brings in runtime-only helpers that this
-// standalone corpus generator deliberately does not call.
-#![allow(dead_code)]
-
-#[path = "../src/huddle/pocket.rs"]
-mod production_pocket;
-#[path = "../src/huddle/preprocessing.rs"]
-mod production_preprocessing;
-
-use std::collections::HashMap;
-use std::fs;
-use std::path::{Path, PathBuf};
-use std::time::{Duration, Instant};
-
-use serde::Serialize;
-use sha2::{Digest, Sha256};
-use sherpa_onnx::{GenerationConfig, OfflineTts, OfflineTtsConfig, Wave};
-
-use production_pocket::{prepare_pocket_prompt, SAMPLE_RATE};
-use production_preprocessing::{preprocess_for_tts, split_sentences};
-
-const NUM_STEPS: i32 = 1;
-const SILENCE_SCALE: f32 = 1.0;
-const INTER_SENTENCE_SILENCE_SAMPLES: usize = SAMPLE_RATE as usize / 10;
-const LEAD_IN_SAMPLES: usize = SAMPLE_RATE as usize / 50;
-const FADE_OUT_SAMPLES: usize = SAMPLE_RATE as usize * 8 / 1000;
-const TARGET_RMS_DBFS: f32 = -23.0;
-const BLINDING_SEED: &str = "pocket-quality-2026-07-21-v1";
-
-const CORPUS: &[CorpusItem] = &[
-    CorpusItem { id: "short_one_word", kind: "short", text: "Yep." },
-    CorpusItem { id: "short_four_words", kind: "short", text: "Sounds good to me." },
-    CorpusItem {
-        id: "multi_relay_review",
-        kind: "multi-sentence",
-        text: "I looked at the relay code this morning. The lease logic is solid. There's one race in the worker claim path, though. I'll write it up and send you a patch.",
-    },
-    CorpusItem {
-        id: "multi_community_size",
-        kind: "multi-sentence",
-        text: "Great question. The answer is it depends on the community size. For small ones, keep it simple.",
-    },
-    CorpusItem {
-        id: "mixed_agent_message",
-        kind: "mixed",
-        text: "That's 42 open PRs right now — mostly small. I'll triage them after lunch.",
-    },
-];
-
-#[derive(Clone, Copy)]
-struct CorpusItem {
-    id: &'static str,
-    kind: &'static str,
-    text: &'static str,
-}
-
-#[derive(Clone, Copy, Debug, Serialize)]
-#[serde(rename_all = "snake_case")]
-enum Precision {
-    Int8,
-    Fp32,
-}
-
-#[derive(Clone, Copy, Debug, Serialize)]
-#[serde(rename_all = "snake_case")]
-enum Chunking {
-    PerSentence,
-    Grouped,
-}
-
-#[derive(Clone, Copy, Debug)]
-struct Condition {
-    precision: Precision,
-    chunking: Chunking,
-}
-
-const CONDITIONS: [Condition; 4] = [
-    Condition {
-        precision: Precision::Int8,
-        chunking: Chunking::PerSentence,
-    },
-    Condition {
-        precision: Precision::Int8,
-        chunking: Chunking::Grouped,
-    },
-    Condition {
-        precision: Precision::Fp32,
-        chunking: Chunking::PerSentence,
-    },
-    Condition {
-        precision: Precision::Fp32,
-        chunking: Chunking::Grouped,
-    },
-];
-
-#[derive(Serialize)]
-struct KeyFile {
-    warning: &'static str,
-    blinding_seed: &'static str,
-    target_rms_dbfs: f32,
-    items: Vec<KeyItem>,
-}
-
-#[derive(Serialize)]
-struct KeyItem {
-    id: String,
-    kind: String,
-    text: String,
-    clips: Vec<KeyClip>,
-}
-
-#[derive(Serialize)]
-struct KeyClip {
-    file: String,
-    precision: Precision,
-    chunking: Chunking,
-    cold_start: bool,
-    idle_minutes: Option<u64>,
-    synthesis_ms: u128,
-    audio_seconds: f32,
-}
-
-struct Voice {
-    samples: Vec<f32>,
-    sample_rate: i32,
-}
-
-struct Engine {
-    inner: OfflineTts,
-    voice: Voice,
-}
-
-fn main() -> Result<(), String> {
-    let mut args = std::env::args().skip(1);
-    let int8_dir = required_path(args.next(), "INT8 model directory")?;
-    let fp32_dir = required_path(args.next(), "FP32 model directory")?;
-    let output_dir = required_path(args.next(), "output directory")?;
-    let mut idle_minutes = None;
-    let mut only_item = None;
-    while let Some(arg) = args.next() {
-        match arg.as_str() {
-            "--idle-minutes" => {
-                idle_minutes = Some(
-                    args.next()
-                        .ok_or("--idle-minutes requires a value")?
-                        .parse::<u64>()
-                        .map_err(|e| format!("invalid idle minutes: {e}"))?,
-                );
-            }
-            "--only" => only_item = Some(args.next().ok_or("--only requires an item ID")?),
-            _ => return Err(format!("unknown argument: {arg}")),
-        }
-    }
-
-    if idle_minutes.is_some() && only_item.is_none() {
-        return Err("--idle-minutes requires --only so every clip is first-after-idle".into());
-    }
-    if let Some(ref requested) = only_item {
-        if !CORPUS.iter().any(|item| item.id == requested) {
-            return Err(format!("unknown corpus item for --only: {requested}"));
-        }
-    }
-
-    validate_model_dir(&int8_dir, Precision::Int8)?;
-    validate_model_dir(&fp32_dir, Precision::Fp32)?;
-    fs::create_dir_all(&output_dir).map_err(|e| e.to_string())?;
-
-    let mut engines = Vec::with_capacity(CONDITIONS.len());
-    for condition in CONDITIONS {
-        let dir = match condition.precision {
-            Precision::Int8 => &int8_dir,
-            Precision::Fp32 => &fp32_dir,
-        };
-        let engine = load_engine(dir, condition.precision)?;
-        // Production warms once before serving a real utterance. Cold cases use
-        // separate fresh engines below and deliberately skip this call.
-        synth_chunks(&engine, &["warmup".to_string()])?;
-        engines.push(engine);
-    }
-
-    if let Some(minutes) = idle_minutes {
-        eprintln!("All four warmed engines idle for {minutes} minute(s)…");
-        std::thread::sleep(Duration::from_secs(minutes * 60));
-    }
-
-    let mut key_items = Vec::new();
-    for item in CORPUS {
-        if only_item
-            .as_deref()
-            .is_some_and(|requested| requested != item.id)
-        {
-            continue;
-        }
-        let preprocessed = preprocess_for_tts(item.text);
-        let per_sentence: Vec<String> = split_sentences(&preprocessed)
-            .into_iter()
-            .filter(|s| !s.trim().is_empty())
-            .collect();
-        // These corpus texts are deliberately below the upstream ~50-token
-        // grouping target, so grouped mode is one exact generate() call.
-        let grouped = vec![per_sentence.join(" ")];
-        let item_dir = output_dir.join(item.id);
-        fs::create_dir_all(&item_dir).map_err(|e| e.to_string())?;
-        let clip_order = blinded_order(item.id);
-        let mut clips = Vec::new();
-
-        let mut rendered = Vec::new();
-        for (condition_index, engine) in engines.iter().enumerate() {
-            let condition = CONDITIONS[condition_index];
-            let chunks = match condition.chunking {
-                Chunking::PerSentence => &per_sentence,
-                Chunking::Grouped => &grouped,
-            };
-            let started = Instant::now();
-            let audio = synth_chunks(engine, chunks)?;
-            rendered.push((
-                condition_index,
-                condition,
-                audio,
-                started.elapsed().as_millis(),
-            ));
-        }
-        loudness_match_item(&mut rendered);
-        for (condition_index, condition, audio, synth_ms) in rendered {
-            let clip_number = clip_order[condition_index] + 1;
-            let file_name = format!("clip{clip_number}.wav");
-            write_wav(&item_dir.join(&file_name), &audio)?;
-            clips.push(KeyClip {
-                file: format!("{}/{file_name}", item.id),
-                precision: condition.precision,
-                chunking: condition.chunking,
-                cold_start: false,
-                idle_minutes,
-                synthesis_ms: synth_ms,
-                audio_seconds: audio.len() as f32 / SAMPLE_RATE as f32,
-            });
-        }
-        clips.sort_by(|a, b| a.file.cmp(&b.file));
-        key_items.push(KeyItem {
-            id: item.id.to_string(),
-            kind: item.kind.to_string(),
-            text: item.text.to_string(),
-            clips,
-        });
-    }
-
-    // Explicit fresh-engine cold-start clips for the two highest-signal texts.
-    // Idle runs intentionally omit them: they happen after the post-idle clips
-    // and add no valid idle observation.
-    for item in if idle_minutes.is_none() { CORPUS } else { &[] } {
-        if !matches!(item.id, "short_one_word" | "multi_relay_review") {
-            continue;
-        }
-        if only_item
-            .as_deref()
-            .is_some_and(|requested| requested != item.id)
-        {
-            continue;
-        }
-        let cold_id = format!("cold_{}", item.id);
-        let preprocessed = preprocess_for_tts(item.text);
-        let sentences: Vec<String> = split_sentences(&preprocessed)
-            .into_iter()
-            .filter(|s| !s.trim().is_empty())
-            .collect();
-        let grouped = vec![sentences.join(" ")];
-        let item_dir = output_dir.join(&cold_id);
-        fs::create_dir_all(&item_dir).map_err(|e| e.to_string())?;
-        let clip_order = blinded_order(&cold_id);
-        let mut clips = Vec::new();
-        let mut rendered = Vec::new();
-        for (condition_index, condition) in CONDITIONS.iter().copied().enumerate() {
-            let dir = match condition.precision {
-                Precision::Int8 => &int8_dir,
-                Precision::Fp32 => &fp32_dir,
-            };
-            let engine = load_engine(dir, condition.precision)?;
-            let chunks = match condition.chunking {
-                Chunking::PerSentence => &sentences,
-                Chunking::Grouped => &grouped,
-            };
-            let started = Instant::now();
-            let audio = synth_chunks(&engine, chunks)?;
-            rendered.push((
-                condition_index,
-                condition,
-                audio,
-                started.elapsed().as_millis(),
-            ));
-        }
-        loudness_match_item(&mut rendered);
-        for (condition_index, condition, audio, synth_ms) in rendered {
-            let clip_number = clip_order[condition_index] + 1;
-            let file_name = format!("clip{clip_number}.wav");
-            write_wav(&item_dir.join(&file_name), &audio)?;
-            clips.push(KeyClip {
-                file: format!("{cold_id}/{file_name}"),
-                precision: condition.precision,
-                chunking: condition.chunking,
-                cold_start: true,
-                idle_minutes: None,
-                synthesis_ms: synth_ms,
-                audio_seconds: audio.len() as f32 / SAMPLE_RATE as f32,
-            });
-        }
-        clips.sort_by(|a, b| a.file.cmp(&b.file));
-        key_items.push(KeyItem {
-            id: cold_id,
-            kind: "cold-start".to_string(),
-            text: item.text.to_string(),
-            clips,
-        });
-    }
-
-    let key = KeyFile {
-        warning: "DO NOT OPEN UNTIL LISTENING SCORES ARE FINAL",
-        blinding_seed: BLINDING_SEED,
-        target_rms_dbfs: TARGET_RMS_DBFS,
-        items: key_items,
-    };
-    fs::write(
-        output_dir.join("key.json"),
-        serde_json::to_vec_pretty(&key).map_err(|e| e.to_string())?,
-    )
-    .map_err(|e| e.to_string())?;
-    write_scoring_sheet(&output_dir, &key)?;
-    println!("Wrote blind corpus to {}", output_dir.display());
-    println!("Give listeners the WAV folders and SCORING.md; withhold key.json.");
-    Ok(())
-}
-
-fn required_path(value: Option<String>, label: &str) -> Result<PathBuf, String> {
-    value
-        .map(PathBuf::from)
-        .ok_or_else(|| format!("missing {label}"))
-}
-
-fn model_file(precision: Precision, base: &str) -> String {
-    match precision {
-        Precision::Int8 => format!("{base}.int8.onnx"),
-        Precision::Fp32 => format!("{base}.onnx"),
-    }
-}
-
-fn validate_model_dir(dir: &Path, precision: Precision) -> Result<(), String> {
-    for file in [
-        model_file(precision, "lm_main"),
-        model_file(precision, "lm_flow"),
-        "encoder.onnx".into(),
-        model_file(precision, "decoder"),
-        "text_conditioner.onnx".into(),
-        "vocab.json".into(),
-        "token_scores.json".into(),
-        "reference_sample.wav".into(),
-    ] {
-        if !dir.join(&file).is_file() {
-            return Err(format!("missing {}", dir.join(file).display()));
-        }
-    }
-    Ok(())
-}
-
-fn load_engine(dir: &Path, precision: Precision) -> Result<Engine, String> {
-    let p = |name: &str| dir.join(name).to_string_lossy().into_owned();
-    let mut cfg = OfflineTtsConfig::default();
-    cfg.model.pocket.lm_main = Some(p(&model_file(precision, "lm_main")));
-    cfg.model.pocket.lm_flow = Some(p(&model_file(precision, "lm_flow")));
-    cfg.model.pocket.encoder = Some(p("encoder.onnx"));
-    cfg.model.pocket.decoder = Some(p(&model_file(precision, "decoder")));
-    cfg.model.pocket.text_conditioner = Some(p("text_conditioner.onnx"));
-    cfg.model.pocket.vocab_json = Some(p("vocab.json"));
-    cfg.model.pocket.token_scores_json = Some(p("token_scores.json"));
-    cfg.model.pocket.voice_embedding_cache_capacity = 16;
-    cfg.model.num_threads = 1;
-    cfg.model.debug = false;
-    let inner =
-        OfflineTts::create(&cfg).ok_or_else(|| format!("failed to create {precision:?} engine"))?;
-    let wave =
-        Wave::read(&p("reference_sample.wav")).ok_or("failed to read reference_sample.wav")?;
-    Ok(Engine {
-        inner,
-        voice: Voice {
-            samples: wave.samples().to_vec(),
-            sample_rate: wave.sample_rate(),
-        },
-    })
-}
-
-fn synth_chunks(engine: &Engine, chunks: &[String]) -> Result<Vec<f32>, String> {
-    let mut out = Vec::new();
-    for chunk in chunks {
-        let prepared = prepare_pocket_prompt(chunk).ok_or("empty prepared prompt")?;
-        let extra = prepared.max_frames.map(|max_frames| {
-            HashMap::from([(
-                "max_frames".to_string(),
-                serde_json::Value::from(max_frames),
-            )])
-        });
-        let cfg = GenerationConfig {
-            num_steps: NUM_STEPS,
-            silence_scale: SILENCE_SCALE,
-            reference_audio: Some(engine.voice.samples.clone()),
-            reference_sample_rate: engine.voice.sample_rate,
-            extra,
-            ..Default::default()
-        };
-        let audio = engine
-            .inner
-            .generate_with_config(&prepared.text, &cfg, None::<fn(&[f32], f32) -> bool>)
-            .ok_or_else(|| format!("synthesis failed for {chunk:?}"))?;
-        let mut samples: Vec<f32> = audio.samples().iter().map(|s| s.clamp(-1.0, 1.0)).collect();
-        apply_fade_out(&mut samples);
-        out.extend(std::iter::repeat_n(0.0, LEAD_IN_SAMPLES));
-        out.extend(samples);
-        out.extend(std::iter::repeat_n(
-            0.0,
-            INTER_SENTENCE_SILENCE_SAMPLES - LEAD_IN_SAMPLES,
-        ));
-    }
-    Ok(out)
-}
-
-fn apply_fade_out(samples: &mut [f32]) {
-    let fade = FADE_OUT_SAMPLES.min(samples.len() / 2);
-    for i in 0..fade {
-        samples[samples.len() - 1 - i] *= i as f32 / fade as f32;
-    }
-}
-
-fn active_rms(samples: &[f32]) -> Option<f32> {
-    let (sum_squares, count) = samples
-        .iter()
-        .filter(|sample| sample.abs() > 1.0e-4)
-        .fold((0.0_f32, 0_usize), |(sum, count), sample| {
-            (sum + sample * sample, count + 1)
-        });
-    (count > 0).then(|| (sum_squares / count as f32).sqrt())
-}
-
-/// Attenuate every clip in one comparison set to the quietest active-speech RMS.
-/// This removes the louder-is-better confound without normalizing dynamics or
-/// claiming standards-compliant integrated LUFS. The dBFS value is a ceiling.
-fn loudness_match_item(rendered: &mut [(usize, Condition, Vec<f32>, u128)]) {
-    let ceiling = 10.0_f32.powf(TARGET_RMS_DBFS / 20.0);
-    let target = rendered
-        .iter()
-        .filter_map(|(_, _, samples, _)| active_rms(samples))
-        .fold(ceiling, f32::min);
-    for (_, _, samples, _) in rendered {
-        let Some(rms) = active_rms(samples) else {
-            continue;
-        };
-        let gain = (target / rms).min(1.0);
-        for sample in samples {
-            *sample *= gain;
-        }
-    }
-}
-
-fn blinded_order(item_id: &str) -> [usize; 4] {
-    let mut keyed: Vec<(usize, Vec<u8>)> = (0..4)
-        .map(|index| {
-            let digest = Sha256::digest(format!("{BLINDING_SEED}:{item_id}:{index}"));
-            (index, digest.to_vec())
-        })
-        .collect();
-    keyed.sort_by(|a, b| a.1.cmp(&b.1));
-    let mut condition_to_clip = [0; 4];
-    for (clip, (condition, _)) in keyed.into_iter().enumerate() {
-        condition_to_clip[condition] = clip;
-    }
-    condition_to_clip
-}
-
-fn write_wav(path: &Path, samples: &[f32]) -> Result<(), String> {
-    let path = path
-        .to_str()
-        .ok_or_else(|| format!("non-UTF8 path: {}", path.display()))?;
-    if sherpa_onnx::write(path, samples, SAMPLE_RATE as i32) {
-        Ok(())
-    } else {
-        Err(format!("failed to write {path}"))
-    }
-}
-
-fn write_scoring_sheet(output_dir: &Path, key: &KeyFile) -> Result<(), String> {
-    let mut sheet = String::from("# Pocket TTS blind listening sheet\n\nDo not open `key.json` until this sheet is complete. Rank best to worst; ties are allowed.\n\n");
-    for item in &key.items {
-        sheet.push_str(&format!(
-            "## {} ({})\n\n> {}\n\n",
-            item.id, item.kind, item.text
-        ));
-        sheet.push_str("Rank: `____ > ____ > ____ > ____`\n\n| Clip | seam | onset | garble | robotic | timbre | truncate | note |\n|---|---|---|---|---|---|---|---|\n");
-        for clip in 1..=4 {
-            sheet.push_str(&format!(
-                "| clip{clip} | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | |\n"
-            ));
-        }
-        sheet.push('\n');
-    }
-    fs::write(output_dir.join("SCORING.md"), sheet).map_err(|e| e.to_string())
-}
diff --git a/desktop/src-tauri/resources/pocket-voices/NOTICE.md b/desktop/src-tauri/resources/pocket-voices/NOTICE.md
new file mode 100644
index 0000000000..9cc515dea3
--- /dev/null
+++ b/desktop/src-tauri/resources/pocket-voices/NOTICE.md
@@ -0,0 +1,35 @@
+# Pocket TTS English VCTK presets
+
+Buzz exposes Kyutai's twelve official English VCTK Pocket presets. The WAV
+bytes are unchanged from `kyutai/tts-voices` revision
+`323332d33f997de8394f24a193e1a76df720e01a`; only local filenames differ.
+
+| Voice | Upstream asset | SHA-256 |
+| --- | --- | --- |
+| Anna | `vctk/p228_023_enhanced.wav` | `0a6de25cf12bf1540beb85979f306a92be81fecc051c547c5395e7e5237a3856` |
+| Vera | `vctk/p229_023_enhanced.wav` | `309cf91a895830f15842b398f69a4962cb1f7e0bfab10e25dd27838e826c204b` |
+| Fantine | `vctk/p244_023_enhanced.wav` | `5f07d4e2a3f20a15572aae885156b43ef3fc12ef3812996fd135680d9956448b` |
+| Charles | `vctk/p254_023_enhanced.wav` | `6b681a429198f16e378d53bccb08d06939da7b00144a7696111d4f8f76be7756` |
+| Paul | `vctk/p259_023_enhanced.wav` | `7aba504fe0b3b16478b69eb27ce6007e3cb42b0c1915b5f1c6a6024ae37d679b` |
+| Eponine | `vctk/p262_023_enhanced.wav` | `a13c27fb47627b05223691a0ef2974358a18c886e6c2f9d2762ff1d02c20926b` |
+| Azelma | `vctk/p303_023_enhanced.wav` | `60e3d26cdf2efdec5df712152c839928f4d5522821e6554ae11fd96c57ab1026` |
+| George | `vctk/p315_023_enhanced.wav` | `29a41f93bf5236e5b21501091d7774c255d5f3d4e62fa4f9fdf0a92a793c84ae` |
+| Mary | `vctk/p333_023_enhanced.wav` | `a35b0468382218e9f37a9a7494d1e4b74deaf18d7ced22265b4e325bb55c183f` |
+| Jane | `vctk/p339_023_enhanced.wav` | `2f12e7f155eb3118f55425394f1b049e5b1b67bdc9b3932c8ba4521420aeb84a` |
+| Michael | `vctk/p360_023_enhanced.wav` | `b6743e9195e5e3fd34fe9d1633ae93f7ffab787b249e45f6467d7d6f7a6ee6ad` |
+| Eve | `vctk/p361_023_enhanced.wav` | `396e7cbd066b0f3fb6d67fa26e7904076958239d736d4390f15b5fe88feb14cd` |
+
+Mary is already installed as the Pocket model's `reference_sample.wav`, so it
+is not duplicated in this resource directory.
+
+Source repository:
+https://huggingface.co/kyutai/tts-voices/tree/323332d33f997de8394f24a193e1a76df720e01a/vctk
+
+The original recordings are from the Voice Cloning Toolkit (VCTK) corpus,
+licensed CC BY 4.0:
+https://datashare.ed.ac.uk/handle/10283/3443
+
+The recordings were enhanced by ai-coustics:
+https://ai-coustics.com/
+
+Neither Kyutai, the VCTK speakers, nor ai-coustics endorses Buzz.
diff --git a/desktop/src-tauri/resources/pocket-voices/anna.wav b/desktop/src-tauri/resources/pocket-voices/anna.wav
new file mode 100644
index 0000000000..79d60697ff
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/anna.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/azelma.wav b/desktop/src-tauri/resources/pocket-voices/azelma.wav
new file mode 100644
index 0000000000..e9d0c00b3f
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/azelma.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/charles.wav b/desktop/src-tauri/resources/pocket-voices/charles.wav
new file mode 100644
index 0000000000..2170975545
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/charles.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/eponine.wav b/desktop/src-tauri/resources/pocket-voices/eponine.wav
new file mode 100644
index 0000000000..bded6f4f09
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/eponine.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/eve.wav b/desktop/src-tauri/resources/pocket-voices/eve.wav
new file mode 100644
index 0000000000..216665ff13
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/eve.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/fantine.wav b/desktop/src-tauri/resources/pocket-voices/fantine.wav
new file mode 100644
index 0000000000..28c2b1140d
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/fantine.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/george.wav b/desktop/src-tauri/resources/pocket-voices/george.wav
new file mode 100644
index 0000000000..739d5bc7a5
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/george.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/jane.wav b/desktop/src-tauri/resources/pocket-voices/jane.wav
new file mode 100644
index 0000000000..3c9890473b
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/jane.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/michael.wav b/desktop/src-tauri/resources/pocket-voices/michael.wav
new file mode 100644
index 0000000000..861da085c7
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/michael.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/paul.wav b/desktop/src-tauri/resources/pocket-voices/paul.wav
new file mode 100644
index 0000000000..bfde50fdd9
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/paul.wav differ
diff --git a/desktop/src-tauri/resources/pocket-voices/vera.wav b/desktop/src-tauri/resources/pocket-voices/vera.wav
new file mode 100644
index 0000000000..e4fce84ce3
Binary files /dev/null and b/desktop/src-tauri/resources/pocket-voices/vera.wav differ
diff --git a/desktop/src-tauri/src/app_state.rs b/desktop/src-tauri/src/app_state.rs
index 94d162e620..fc90e6ab14 100644
--- a/desktop/src-tauri/src/app_state.rs
+++ b/desktop/src-tauri/src/app_state.rs
@@ -2,7 +2,7 @@ use std::{
     collections::HashMap,
     io::Write,
     sync::{
-        atomic::{AtomicBool, AtomicU16},
+        atomic::{AtomicBool, AtomicU16, AtomicU8},
         Arc, Mutex,
     },
 };
@@ -13,10 +13,15 @@ use tauri::{AppHandle, Manager};
 use tokio::sync::Mutex as AsyncMutex;
 
 use crate::huddle::HuddleState;
+pub(crate) use crate::identity_storage::{IdentityStorage, RecoveryState, ResolvedIdentity};
 use crate::managed_agents::config_bridge::SessionConfigCache;
 use crate::managed_agents::{ManagedAgentPairRuntime, ManagedAgentRuntimeKey};
+
 pub struct AppState {
     pub keys: Mutex<Keys>,
+    /// Durable backend holding `keys`. Updated after the key write and before
+    /// recovery flags are cleared so `get_identity` reports a consistent state.
+    pub(crate) identity_storage: AtomicU8,
     pub http_client: reqwest::Client,
     /// A no-redirect client for authenticated relay media fetches (download,
     /// clipboard copy, snapshot, editor). Every caller pre-validates the URL
@@ -48,15 +53,13 @@ pub struct AppState {
     pub channel_templates_store_lock: Mutex<()>,
     pub managed_agent_processes: Mutex<HashMap<ManagedAgentRuntimeKey, ManagedAgentPairRuntime>>,
     pub huddle_state: Mutex<HuddleState>,
+    pub huddle_audio: crate::huddle::tts_settings::HuddleAudioSettingsState,
     /// Tauri app handle — stored after setup so huddle commands can emit
     /// `huddle-state-changed` events without needing the handle threaded
     /// through every call site.
     ///
     /// Set once during `setup()` in `lib.rs`; never cleared.
     pub app_handle: Mutex<Option<AppHandle>>,
-    /// Selected audio output device name. `None` = system default.
-    /// Used by `connect_audio_relay` and TTS pipeline when opening sinks.
-    pub audio_output_device: Mutex<Option<String>>,
     /// Port of the localhost media streaming proxy (set during setup).
     pub media_proxy_port: AtomicU16,
     /// Set when identity resolution detected a "keyring-locked" state: the
@@ -178,19 +181,20 @@ pub fn build_media_fetch_client() -> reqwest::Result<reqwest::Client> {
 pub fn build_app_state() -> AppState {
     // Env var takes precedence (dev/CI). If absent, resolve_persisted_identity()
     // in setup() will replace the ephemeral placeholder with a persisted key.
-    let keys = match identity_from_env() {
+    let (keys, identity_storage) = match identity_from_env() {
         Some(keys) => {
             eprintln!(
                 "buzz-desktop: configured identity pubkey {}",
                 keys.public_key().to_hex()
             );
-            keys
+            (keys, IdentityStorage::Environment)
         }
-        None => Keys::generate(),
+        None => (Keys::generate(), IdentityStorage::Ephemeral),
     };
 
     AppState {
         keys: Mutex::new(keys),
+        identity_storage: AtomicU8::new(identity_storage as u8),
         http_client: reqwest::Client::builder()
             .resolve("localhost", std::net::SocketAddr::from(([127, 0, 0, 1], 0)))
             .pool_idle_timeout(std::time::Duration::from_secs(10))
@@ -213,8 +217,8 @@ pub fn build_app_state() -> AppState {
         managed_agent_processes: Mutex::new(HashMap::new()),
         session_config_cache: Mutex::new(HashMap::new()),
         huddle_state: Mutex::new(HuddleState::default()),
+        huddle_audio: Default::default(),
         app_handle: Mutex::new(None),
-        audio_output_device: Mutex::new(None),
         media_proxy_port: AtomicU16::new(0),
         prevent_sleep: Arc::new(Mutex::new(
             crate::prevent_sleep::PreventSleepState::default(),
@@ -366,9 +370,13 @@ pub fn resolve_persisted_identity(app: &AppHandle, state: &AppState) -> Result<(
     std::fs::create_dir_all(&data_dir).map_err(|e| format!("create app data dir: {e}"))?;
 
     let resolved = load_or_create_identity(&data_dir)?;
-    // Write keys before setting the recovery flags (Release) so any thread
-    // that reads a flag as false with Acquire is guaranteed to see the keys.
-    *state.keys.lock().map_err(|e| e.to_string())? = resolved.keys;
+    // Write keys and storage before setting the recovery flags (Release) so
+    // any thread that reads a flag as false with Acquire sees consistent data.
+    {
+        let mut active_keys = state.keys.lock().map_err(|e| e.to_string())?;
+        *active_keys = resolved.keys;
+        state.set_identity_storage(resolved.storage);
+    }
     state.identity_lost.store(
         resolved.recovery == RecoveryState::Lost,
         std::sync::atomic::Ordering::Release,
@@ -394,26 +402,6 @@ const IDENTITY_KEY_NAME: &str = "identity";
 /// keyring is merely unreachable (the key IS in the keyring, must NOT generate).
 const MIGRATION_MARKER_NAME: &str = "identity.migrated";
 
-/// Recovery state produced by identity resolution. `None` means the app has
-/// a real, usable identity. `Lost` means the keyring was reachable-but-empty
-/// despite a prior successful migration — the key vanished externally. `KeyringLocked`
-/// means the keyring is unreachable this boot but was used in the past
-/// (marker present, no file) — the key still exists but is temporarily
-/// inaccessible. Both non-`None` variants boot with an ephemeral key; the
-/// frontend shows a different recovery screen for each.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-enum RecoveryState {
-    None,
-    Lost,
-    KeyringLocked,
-}
-
-/// The output of identity resolution.
-struct ResolvedIdentity {
-    keys: Keys,
-    recovery: RecoveryState,
-}
-
 /// The keyring operations the identity resolution flow needs. Abstracted so the
 /// corrupt-keyring recovery decision ([`recover_from_keyring`]) can be
 /// unit-tested against a fake without touching the live OS keyring.
@@ -465,6 +453,7 @@ fn load_or_create_identity(data_dir: &std::path::Path) -> Result<ResolvedIdentit
         return Ok(ResolvedIdentity {
             keys,
             recovery: RecoveryState::None,
+            storage: IdentityStorage::LocalFile,
         });
     }
 
@@ -514,7 +503,7 @@ fn resolve_identity_with_store(
                                     // fails. A transient keyring failure must not abort
                                     // boot — the file key is safe and adoption retries next
                                     // boot when the keyring is reachable again.
-                                    if let Err(e) = persist_identity_to_keyring(
+                                    let storage = if let Err(e) = persist_identity_to_keyring(
                                         store,
                                         &file_keys,
                                         legacy_path,
@@ -524,10 +513,14 @@ fn resolve_identity_with_store(
                                             "buzz-desktop: keyring adoption of identity.key \
                                              failed ({e}); using file key, will retry next boot"
                                         );
-                                    }
+                                        IdentityStorage::LocalFile
+                                    } else {
+                                        IdentityStorage::SystemKeyring
+                                    };
                                     return Ok(ResolvedIdentity {
                                         keys: file_keys,
                                         recovery: RecoveryState::None,
+                                        storage,
                                     });
                                 }
                                 // Corrupt file — keyring is authoritative. Log before
@@ -567,6 +560,7 @@ fn resolve_identity_with_store(
                         return Ok(ResolvedIdentity {
                             keys: keyring_keys,
                             recovery: RecoveryState::None,
+                            storage: IdentityStorage::SystemKeyring,
                         });
                     }
                     // The corruption is in the KEYRING, not the file. Clear the
@@ -595,6 +589,7 @@ fn resolve_identity_with_store(
                     return Ok(ResolvedIdentity {
                         keys,
                         recovery: RecoveryState::None,
+                        storage: IdentityStorage::SystemKeyring,
                     });
                 }
             } else if migration_marker_path(data_dir).exists() {
@@ -615,6 +610,7 @@ fn resolve_identity_with_store(
                 return Ok(ResolvedIdentity {
                     keys: ephemeral,
                     recovery: RecoveryState::Lost,
+                    storage: IdentityStorage::Ephemeral,
                 });
             }
         }
@@ -643,20 +639,23 @@ fn resolve_identity_with_store(
                 return Ok(ResolvedIdentity {
                     keys: ephemeral,
                     recovery: RecoveryState::KeyringLocked,
+                    storage: IdentityStorage::Ephemeral,
                 });
             }
             let keys = load_file_or_generate(legacy_path, data_dir)?;
             return Ok(ResolvedIdentity {
                 keys,
                 recovery: RecoveryState::None,
+                storage: IdentityStorage::LocalFile,
             });
         }
     }
 
-    let keys = generate_and_persist(store, legacy_path, data_dir)?;
+    let (keys, storage) = generate_and_persist(store, legacy_path, data_dir)?;
     Ok(ResolvedIdentity {
         keys,
         recovery: RecoveryState::None,
+        storage,
     })
 }
 
@@ -682,6 +681,7 @@ fn recover_from_keyring(
             return Ok(ResolvedIdentity {
                 keys,
                 recovery: RecoveryState::None,
+                storage: IdentityStorage::SystemKeyring,
             });
         }
     }
@@ -699,13 +699,15 @@ fn recover_from_keyring(
         return Ok(ResolvedIdentity {
             keys: ephemeral,
             recovery: RecoveryState::Lost,
+            storage: IdentityStorage::Ephemeral,
         });
     }
     // No marker: genuine first launch with a corrupt keyring. Generate fresh.
-    let keys = generate_and_persist(store, legacy_path, data_dir)?;
+    let (keys, storage) = generate_and_persist(store, legacy_path, data_dir)?;
     Ok(ResolvedIdentity {
         keys,
         recovery: RecoveryState::None,
+        storage,
     })
 }
 
@@ -872,15 +874,16 @@ fn persist_imported_identity_impl(
     keys: &Keys,
     legacy_path: &std::path::Path,
     data_dir: &std::path::Path,
-) -> Result<(), String> {
+) -> Result<IdentityStorage, String> {
     match persist_identity_to_keyring(store, keys, legacy_path, data_dir) {
-        Ok(()) => Ok(()),
+        Ok(()) => Ok(IdentityStorage::SystemKeyring),
         Err(e) => {
             eprintln!(
                 "buzz-desktop: keyring write failed during import ({e}), \
                  falling back to identity.key"
             );
-            save_key_file(legacy_path, keys)
+            save_key_file(legacy_path, keys)?;
+            Ok(IdentityStorage::LocalFile)
         }
     }
 }
@@ -892,7 +895,7 @@ pub(crate) fn persist_imported_identity(
     keys: &Keys,
     legacy_path: &std::path::Path,
     data_dir: &std::path::Path,
-) -> Result<(), String> {
+) -> Result<IdentityStorage, String> {
     persist_imported_identity_impl(store, keys, legacy_path, data_dir)
 }
 
@@ -920,15 +923,6 @@ fn write_migration_marker(marker_path: &std::path::Path) -> Result<(), String> {
         .map_err(|e| format!("commit migration marker: {e}"))
 }
 
-/// Which backend [`store_key_preferring_keyring`] wrote to. The caller writes
-/// the migration marker only after a keyring success — on the file-fallback arm
-/// the key is on disk and a marker would wrongly trip the next Unreachable boot
-/// into failing closed.
-enum PersistBackend {
-    Keyring,
-    File,
-}
-
 /// Generate a fresh identity, persist it through the store, return it.
 ///
 /// On a keyring-backed persist no file is written, so a later
@@ -940,9 +934,10 @@ fn generate_and_persist(
     store: &impl IdentityKeyStore,
     legacy_path: &std::path::Path,
     data_dir: &std::path::Path,
-) -> Result<Keys, String> {
+) -> Result<(Keys, IdentityStorage), String> {
     let keys = Keys::generate();
-    if let PersistBackend::Keyring = store_key_preferring_keyring(store, &keys, legacy_path)? {
+    let storage = store_key_preferring_keyring(store, &keys, legacy_path)?;
+    if storage == IdentityStorage::SystemKeyring {
         let marker_path = migration_marker_path(data_dir);
         if let Err(e) = write_migration_marker(&marker_path) {
             eprintln!(
@@ -956,7 +951,7 @@ fn generate_and_persist(
         "buzz-desktop: generated and saved identity pubkey {}",
         keys.public_key().to_hex()
     );
-    Ok(keys)
+    Ok((keys, storage))
 }
 
 /// Persist `keys` through the store, silently falling back to the `0o600` file
@@ -968,17 +963,17 @@ fn store_key_preferring_keyring(
     store: &impl IdentityKeyStore,
     keys: &Keys,
     legacy_path: &std::path::Path,
-) -> Result<PersistBackend, String> {
+) -> Result<IdentityStorage, String> {
     let nsec = keys
         .secret_key()
         .to_bech32()
         .map_err(|e| format!("encode nsec: {e}"))?;
     match store.store(IDENTITY_KEY_NAME, &nsec) {
-        Ok(()) => Ok(PersistBackend::Keyring),
+        Ok(()) => Ok(IdentityStorage::SystemKeyring),
         Err(keyring_err) => {
             eprintln!("buzz-desktop: keyring write failed ({keyring_err}), using file fallback");
             save_key_file(legacy_path, keys)?;
-            Ok(PersistBackend::File)
+            Ok(IdentityStorage::LocalFile)
         }
     }
 }
diff --git a/desktop/src-tauri/src/app_state_tests.rs b/desktop/src-tauri/src/app_state_tests.rs
index 485dfaea15..751bcf22e5 100644
--- a/desktop/src-tauri/src/app_state_tests.rs
+++ b/desktop/src-tauri/src/app_state_tests.rs
@@ -484,7 +484,7 @@ fn fresh_keyring_generate_writes_marker() {
     let resolved = resolve_identity_with_store(&store, &legacy_path, dir.path()).unwrap();
 
     // The key was stored in the keyring (not the file), and the marker marks it.
-    assert!(!legacy_path.exists());
+    assert!(!legacy_path.exists() && resolved.storage == IdentityStorage::SystemKeyring);
     assert!(migration_marker_path(dir.path()).exists());
     assert_eq!(
         store
@@ -541,7 +541,10 @@ fn fresh_generate_keyring_failure_falls_back_to_file_without_marker() {
     let from_file = load_key_file(&legacy_path).unwrap();
     assert_key_eq(&resolved.keys, &from_file);
     // No marker: the file is the authoritative store, not the keyring.
-    assert!(!migration_marker_path(dir.path()).exists());
+    assert!(
+        !migration_marker_path(dir.path()).exists()
+            && resolved.storage == IdentityStorage::LocalFile
+    );
 }
 
 // ── New tests for the three defects fixed in this PR ─────────────────────
@@ -786,10 +789,7 @@ fn persist_imported_identity_falls_back_to_file_on_keyring_failure() {
     let result = persist_imported_identity_impl(&store, &imported_keys, &legacy_path, dir.path());
 
     // The policy core handles the keyring failure — Ok, not Err.
-    assert!(
-        result.is_ok(),
-        "must not propagate keyring failure when file fallback succeeds"
-    );
+    assert_eq!(result.unwrap(), IdentityStorage::LocalFile);
 
     // Key is recoverable from the file on next boot.
     let from_file = load_key_file(&legacy_path).unwrap();
diff --git a/desktop/src-tauri/src/archive/mod.rs b/desktop/src-tauri/src/archive/mod.rs
index a65b126a4d..42c6812674 100644
--- a/desktop/src-tauri/src/archive/mod.rs
+++ b/desktop/src-tauri/src/archive/mod.rs
@@ -483,21 +483,23 @@ pub async fn list_save_subscriptions(
 /// Does NOT purge already-archived event data — retention is decoupled in v1.
 /// GC of orphaned event rows happens in P4 purge commands, not here.
 #[tauri::command]
-pub fn delete_save_subscription(
+pub async fn delete_save_subscription(
     state: State<'_, AppState>,
     scope_type: ScopeType,
     scope_value: String,
 ) -> Result<bool, String> {
     let identity_pk = identity_pubkey(&state)?;
     let relay_url = relay_ws_url_with_override(&state);
-    let conn = open_db()?;
-    store::delete_save_subscription(
-        &conn,
-        &identity_pk,
-        &relay_url,
-        scope_type.as_str(),
-        &scope_value,
-    )
+    run_archive_db_task(move |conn| {
+        store::delete_save_subscription(
+            conn,
+            &identity_pk,
+            &relay_url,
+            scope_type.as_str(),
+            &scope_value,
+        )
+    })
+    .await
 }
 
 // ── read_archived_events ─────────────────────────────────────────────────────
@@ -516,7 +518,7 @@ pub fn delete_save_subscription(
 /// newest-first order. Compound cursor `(before_created_at, before_id)` works
 /// identically to `read_archived_events`.
 #[tauri::command]
-pub fn read_archived_observer_events_for_channel(
+pub async fn read_archived_observer_events_for_channel(
     state: State<'_, AppState>,
     channel_id: String,
     before_created_at: Option<i64>,
@@ -525,16 +527,18 @@ pub fn read_archived_observer_events_for_channel(
 ) -> Result<Vec<String>, String> {
     let identity_pk = identity_pubkey(&state)?;
     let relay_url = relay_ws_url_with_override(&state);
-    let conn = open_db()?;
-    store::read_archived_observer_events_for_channel(
-        &conn,
-        &identity_pk,
-        &relay_url,
-        &channel_id,
-        before_created_at,
-        before_id.as_deref(),
-        limit.unwrap_or(DEFAULT_READ_LIMIT),
-    )
+    run_archive_db_task(move |conn| {
+        store::read_archived_observer_events_for_channel(
+            conn,
+            &identity_pk,
+            &relay_url,
+            &channel_id,
+            before_created_at,
+            before_id.as_deref(),
+            limit.unwrap_or(DEFAULT_READ_LIMIT),
+        )
+    })
+    .await
 }
 
 // ── index_observer_channel_id ─────────────────────────────────────────────────
@@ -548,24 +552,26 @@ pub fn read_archived_observer_events_for_channel(
 ///
 /// Idempotent: rows that are already indexed are left unchanged.
 #[tauri::command]
-pub fn index_observer_channel_id(
+pub async fn index_observer_channel_id(
     state: State<'_, AppState>,
     entries: Vec<ObserverChannelIndexEntry>,
 ) -> Result<(), String> {
     let identity_pk = identity_pubkey(&state)?;
     let relay_url = relay_ws_url_with_override(&state);
-    let conn = open_db()?;
-    for entry in &entries {
-        store::upsert_observer_channel_index(
-            &conn,
-            &identity_pk,
-            &relay_url,
-            &entry.event_id,
-            entry.channel_id.as_deref(),
-            entry.created_at,
-        )?;
-    }
-    Ok(())
+    run_archive_db_task(move |conn| {
+        for entry in &entries {
+            store::upsert_observer_channel_index(
+                conn,
+                &identity_pk,
+                &relay_url,
+                &entry.event_id,
+                entry.channel_id.as_deref(),
+                entry.created_at,
+            )?;
+        }
+        Ok(())
+    })
+    .await
 }
 
 /// A single (event_id, channel_id?, created_at) record used by
@@ -591,21 +597,23 @@ pub struct ObserverChannelIndexEntry {
 /// Together these constitute the one-shot idempotent backfill required by the
 /// Slice 1 acceptance criteria (Thufir Pass 4).
 #[tauri::command]
-pub fn read_unindexed_observer_rows(
+pub async fn read_unindexed_observer_rows(
     state: State<'_, AppState>,
 ) -> Result<Vec<RawObserverRow>, String> {
     let identity_pk = identity_pubkey(&state)?;
     let relay_url = relay_ws_url_with_override(&state);
-    let conn = open_db()?;
-    let rows = store::read_unindexed_observer_rows(&conn, &identity_pk, &relay_url)?;
-    Ok(rows
-        .into_iter()
-        .map(|(id, raw_json, created_at)| RawObserverRow {
-            id,
-            raw_json,
-            created_at,
-        })
-        .collect())
+    run_archive_db_task(move |conn| {
+        let rows = store::read_unindexed_observer_rows(conn, &identity_pk, &relay_url)?;
+        Ok(rows
+            .into_iter()
+            .map(|(id, raw_json, created_at)| RawObserverRow {
+                id,
+                raw_json,
+                created_at,
+            })
+            .collect())
+    })
+    .await
 }
 
 /// Wire type returned by `read_unindexed_observer_rows`.
diff --git a/desktop/src-tauri/src/assets/eff_short_wordlist_2_0.txt b/desktop/src-tauri/src/assets/eff_short_wordlist_2_0.txt
new file mode 100644
index 0000000000..9ac732fe36
--- /dev/null
+++ b/desktop/src-tauri/src/assets/eff_short_wordlist_2_0.txt
@@ -0,0 +1,1296 @@
+aardvark
+abandoned
+abbreviate
+abdomen
+abhorrence
+abiding
+abnormal
+abrasion
+absorbing
+abundant
+abyss
+academy
+accountant
+acetone
+achiness
+acid
+acoustics
+acquire
+acrobat
+actress
+acuteness
+aerosol
+aesthetic
+affidavit
+afloat
+afraid
+aftershave
+again
+agency
+aggressor
+aghast
+agitate
+agnostic
+agonizing
+agreeing
+aidless
+aimlessly
+ajar
+alarmclock
+albatross
+alchemy
+alfalfa
+algae
+aliens
+alkaline
+almanac
+alongside
+alphabet
+already
+also
+altitude
+aluminum
+always
+amazingly
+ambulance
+amendment
+amiable
+ammunition
+amnesty
+amoeba
+amplifier
+amuser
+anagram
+anchor
+android
+anesthesia
+angelfish
+animal
+anklet
+announcer
+anonymous
+answer
+antelope
+anxiety
+anyplace
+aorta
+apartment
+apnea
+apostrophe
+apple
+apricot
+aquamarine
+arachnid
+arbitrate
+ardently
+arena
+argument
+aristocrat
+armchair
+aromatic
+arrowhead
+arsonist
+artichoke
+asbestos
+ascend
+aseptic
+ashamed
+asinine
+asleep
+asocial
+asparagus
+astronaut
+asymmetric
+atlas
+atmosphere
+atom
+atrocious
+attic
+atypical
+auctioneer
+auditorium
+augmented
+auspicious
+automobile
+auxiliary
+avalanche
+avenue
+aviator
+avocado
+awareness
+awhile
+awkward
+awning
+awoke
+axially
+azalea
+babbling
+backpack
+badass
+bagpipe
+bakery
+balancing
+bamboo
+banana
+barracuda
+basket
+bathrobe
+bazooka
+blade
+blender
+blimp
+blouse
+blurred
+boatyard
+bobcat
+body
+bogusness
+bohemian
+boiler
+bonnet
+boots
+borough
+bossiness
+bottle
+bouquet
+boxlike
+breath
+briefcase
+broom
+brushes
+bubblegum
+buckle
+buddhist
+buffalo
+bullfrog
+bunny
+busboy
+buzzard
+cabin
+cactus
+cadillac
+cafeteria
+cage
+cahoots
+cajoling
+cakewalk
+calculator
+camera
+canister
+capsule
+carrot
+cashew
+cathedral
+caucasian
+caviar
+ceasefire
+cedar
+celery
+cement
+census
+ceramics
+cesspool
+chalkboard
+cheesecake
+chimney
+chlorine
+chopsticks
+chrome
+chute
+cilantro
+cinnamon
+circle
+cityscape
+civilian
+clay
+clergyman
+clipboard
+clock
+clubhouse
+coathanger
+cobweb
+coconut
+codeword
+coexistent
+coffeecake
+cognitive
+cohabitate
+collarbone
+computer
+confetti
+copier
+cornea
+cosmetics
+cotton
+couch
+coverless
+coyote
+coziness
+crawfish
+crewmember
+crib
+croissant
+crumble
+crystal
+cubical
+cucumber
+cuddly
+cufflink
+cuisine
+culprit
+cup
+curry
+cushion
+cuticle
+cybernetic
+cyclist
+cylinder
+cymbal
+cynicism
+cypress
+cytoplasm
+dachshund
+daffodil
+dagger
+dairy
+dalmatian
+dandelion
+dartboard
+dastardly
+datebook
+daughter
+dawn
+daytime
+dazzler
+dealer
+debris
+decal
+dedicate
+deepness
+defrost
+degree
+dehydrator
+deliverer
+democrat
+dentist
+deodorant
+depot
+deranged
+desktop
+detergent
+device
+dexterity
+diamond
+dibs
+dictionary
+diffuser
+digit
+dilated
+dimple
+dinnerware
+dioxide
+diploma
+directory
+dishcloth
+ditto
+dividers
+dizziness
+doctor
+dodge
+doll
+dominoes
+donut
+doorstep
+dorsal
+double
+downstairs
+dozed
+drainpipe
+dresser
+driftwood
+droppings
+drum
+dryer
+dubiously
+duckling
+duffel
+dugout
+dumpster
+duplex
+durable
+dustpan
+dutiful
+duvet
+dwarfism
+dwelling
+dwindling
+dynamite
+dyslexia
+eagerness
+earlobe
+easel
+eavesdrop
+ebook
+eccentric
+echoless
+eclipse
+ecosystem
+ecstasy
+edged
+editor
+educator
+eelworm
+eerie
+effects
+eggnog
+egomaniac
+ejection
+elastic
+elbow
+elderly
+elephant
+elfishly
+eliminator
+elk
+elliptical
+elongated
+elsewhere
+elusive
+elves
+emancipate
+embroidery
+emcee
+emerald
+emission
+emoticon
+emperor
+emulate
+enactment
+enchilada
+endorphin
+energy
+enforcer
+engine
+enhance
+enigmatic
+enjoyably
+enlarged
+enormous
+enquirer
+enrollment
+ensemble
+entryway
+enunciate
+envoy
+enzyme
+epidemic
+equipment
+erasable
+ergonomic
+erratic
+eruption
+escalator
+eskimo
+esophagus
+espresso
+essay
+estrogen
+etching
+eternal
+ethics
+etiquette
+eucalyptus
+eulogy
+euphemism
+euthanize
+evacuation
+evergreen
+evidence
+evolution
+exam
+excerpt
+exerciser
+exfoliate
+exhale
+exist
+exorcist
+explode
+exquisite
+exterior
+exuberant
+fabric
+factory
+faded
+failsafe
+falcon
+family
+fanfare
+fasten
+faucet
+favorite
+feasibly
+february
+federal
+feedback
+feigned
+feline
+femur
+fence
+ferret
+festival
+fettuccine
+feudalist
+feverish
+fiberglass
+fictitious
+fiddle
+figurine
+fillet
+finalist
+fiscally
+fixture
+flashlight
+fleshiness
+flight
+florist
+flypaper
+foamless
+focus
+foggy
+folksong
+fondue
+footpath
+fossil
+fountain
+fox
+fragment
+freeway
+fridge
+frosting
+fruit
+fryingpan
+gadget
+gainfully
+gallstone
+gamekeeper
+gangway
+garlic
+gaslight
+gathering
+gauntlet
+gearbox
+gecko
+gem
+generator
+geographer
+gerbil
+gesture
+getaway
+geyser
+ghoulishly
+gibberish
+giddiness
+giftshop
+gigabyte
+gimmick
+giraffe
+giveaway
+gizmo
+glasses
+gleeful
+glisten
+glove
+glucose
+glycerin
+gnarly
+gnomish
+goatskin
+goggles
+goldfish
+gong
+gooey
+gorgeous
+gosling
+gothic
+gourmet
+governor
+grape
+greyhound
+grill
+groundhog
+grumbling
+guacamole
+guerrilla
+guitar
+gullible
+gumdrop
+gurgling
+gusto
+gutless
+gymnast
+gynecology
+gyration
+habitat
+hacking
+haggard
+haiku
+halogen
+hamburger
+handgun
+happiness
+hardhat
+hastily
+hatchling
+haughty
+hazelnut
+headband
+hedgehog
+hefty
+heinously
+helmet
+hemoglobin
+henceforth
+herbs
+hesitation
+hexagon
+hubcap
+huddling
+huff
+hugeness
+hullabaloo
+human
+hunter
+hurricane
+hushing
+hyacinth
+hybrid
+hydrant
+hygienist
+hypnotist
+ibuprofen
+icepack
+icing
+iconic
+identical
+idiocy
+idly
+igloo
+ignition
+iguana
+illuminate
+imaging
+imbecile
+imitator
+immigrant
+imprint
+iodine
+ionosphere
+ipad
+iphone
+iridescent
+irksome
+iron
+irrigation
+island
+isotope
+issueless
+italicize
+itemizer
+itinerary
+itunes
+ivory
+jabbering
+jackrabbit
+jaguar
+jailhouse
+jalapeno
+jamboree
+janitor
+jarring
+jasmine
+jaundice
+jawbreaker
+jaywalker
+jazz
+jealous
+jeep
+jelly
+jeopardize
+jersey
+jetski
+jezebel
+jiffy
+jigsaw
+jingling
+jobholder
+jockstrap
+jogging
+john
+joinable
+jokingly
+journal
+jovial
+joystick
+jubilant
+judiciary
+juggle
+juice
+jujitsu
+jukebox
+jumpiness
+junkyard
+juror
+justifying
+juvenile
+kabob
+kamikaze
+kangaroo
+karate
+kayak
+keepsake
+kennel
+kerosene
+ketchup
+khaki
+kickstand
+kilogram
+kimono
+kingdom
+kiosk
+kissing
+kite
+kleenex
+knapsack
+kneecap
+knickers
+koala
+krypton
+laboratory
+ladder
+lakefront
+lantern
+laptop
+laryngitis
+lasagna
+latch
+laundry
+lavender
+laxative
+lazybones
+lecturer
+leftover
+leggings
+leisure
+lemon
+length
+leopard
+leprechaun
+lettuce
+leukemia
+levers
+lewdness
+liability
+library
+licorice
+lifeboat
+lightbulb
+likewise
+lilac
+limousine
+lint
+lioness
+lipstick
+liquid
+listless
+litter
+liverwurst
+lizard
+llama
+luau
+lubricant
+lucidity
+ludicrous
+luggage
+lukewarm
+lullaby
+lumberjack
+lunchbox
+luridness
+luscious
+luxurious
+lyrics
+macaroni
+maestro
+magazine
+mahogany
+maimed
+majority
+makeover
+malformed
+mammal
+mango
+mapmaker
+marbles
+massager
+matchstick
+maverick
+maximum
+mayonnaise
+moaning
+mobilize
+moccasin
+modify
+moisture
+molecule
+momentum
+monastery
+moonshine
+mortuary
+mosquito
+motorcycle
+mousetrap
+movie
+mower
+mozzarella
+muckiness
+mudflow
+mugshot
+mule
+mummy
+mundane
+muppet
+mural
+mustard
+mutation
+myriad
+myspace
+myth
+nail
+namesake
+nanosecond
+napkin
+narrator
+nastiness
+natives
+nautically
+navigate
+nearest
+nebula
+nectar
+nefarious
+negotiator
+neither
+nemesis
+neoliberal
+nephew
+nervously
+nest
+netting
+neuron
+nevermore
+nextdoor
+nicotine
+niece
+nimbleness
+nintendo
+nirvana
+nuclear
+nugget
+nuisance
+nullify
+numbing
+nuptials
+nursery
+nutcracker
+nylon
+oasis
+oat
+obediently
+obituary
+object
+obliterate
+obnoxious
+observer
+obtain
+obvious
+occupation
+oceanic
+octopus
+ocular
+office
+oftentimes
+oiliness
+ointment
+older
+olympics
+omissible
+omnivorous
+oncoming
+onion
+onlooker
+onstage
+onward
+onyx
+oomph
+opaquely
+opera
+opium
+opossum
+opponent
+optical
+opulently
+oscillator
+osmosis
+ostrich
+otherwise
+ought
+outhouse
+ovation
+oven
+owlish
+oxford
+oxidize
+oxygen
+oyster
+ozone
+pacemaker
+padlock
+pageant
+pajamas
+palm
+pamphlet
+pantyhose
+paprika
+parakeet
+passport
+patio
+pauper
+pavement
+payphone
+pebble
+peculiarly
+pedometer
+pegboard
+pelican
+penguin
+peony
+pepperoni
+peroxide
+pesticide
+petroleum
+pewter
+pharmacy
+pheasant
+phonebook
+phrasing
+physician
+plank
+pledge
+plotted
+plug
+plywood
+pneumonia
+podiatrist
+poetic
+pogo
+poison
+poking
+policeman
+poncho
+popcorn
+porcupine
+postcard
+poultry
+powerboat
+prairie
+pretzel
+princess
+propeller
+prune
+pry
+pseudo
+psychopath
+publisher
+pucker
+pueblo
+pulley
+pumpkin
+punchbowl
+puppy
+purse
+pushup
+putt
+puzzle
+pyramid
+python
+quarters
+quesadilla
+quilt
+quote
+racoon
+radish
+ragweed
+railroad
+rampantly
+rancidity
+rarity
+raspberry
+ravishing
+rearrange
+rebuilt
+receipt
+reentry
+refinery
+register
+rehydrate
+reimburse
+rejoicing
+rekindle
+relic
+remote
+renovator
+reopen
+reporter
+request
+rerun
+reservoir
+retriever
+reunion
+revolver
+rewrite
+rhapsody
+rhetoric
+rhino
+rhubarb
+rhyme
+ribbon
+riches
+ridden
+rigidness
+rimmed
+riptide
+riskily
+ritzy
+riverboat
+roamer
+robe
+rocket
+romancer
+ropelike
+rotisserie
+roundtable
+royal
+rubber
+rudderless
+rugby
+ruined
+rulebook
+rummage
+running
+rupture
+rustproof
+sabotage
+sacrifice
+saddlebag
+saffron
+sainthood
+saltshaker
+samurai
+sandworm
+sapphire
+sardine
+sassy
+satchel
+sauna
+savage
+saxophone
+scarf
+scenario
+schoolbook
+scientist
+scooter
+scrapbook
+sculpture
+scythe
+secretary
+sedative
+segregator
+seismology
+selected
+semicolon
+senator
+septum
+sequence
+serpent
+sesame
+settler
+severely
+shack
+shelf
+shirt
+shovel
+shrimp
+shuttle
+shyness
+siamese
+sibling
+siesta
+silicon
+simmering
+singles
+sisterhood
+sitcom
+sixfold
+sizable
+skateboard
+skeleton
+skies
+skulk
+skylight
+slapping
+sled
+slingshot
+sloth
+slumbering
+smartphone
+smelliness
+smitten
+smokestack
+smudge
+snapshot
+sneezing
+sniff
+snowsuit
+snugness
+speakers
+sphinx
+spider
+splashing
+sponge
+sprout
+spur
+spyglass
+squirrel
+statue
+steamboat
+stingray
+stopwatch
+strawberry
+student
+stylus
+suave
+subway
+suction
+suds
+suffocate
+sugar
+suitcase
+sulphur
+superstore
+surfer
+sushi
+swan
+sweatshirt
+swimwear
+sword
+sycamore
+syllable
+symphony
+synagogue
+syringes
+systemize
+tablespoon
+taco
+tadpole
+taekwondo
+tagalong
+takeout
+tallness
+tamale
+tanned
+tapestry
+tarantula
+tastebud
+tattoo
+tavern
+thaw
+theater
+thimble
+thorn
+throat
+thumb
+thwarting
+tiara
+tidbit
+tiebreaker
+tiger
+timid
+tinsel
+tiptoeing
+tirade
+tissue
+tractor
+tree
+tripod
+trousers
+trucks
+tryout
+tubeless
+tuesday
+tugboat
+tulip
+tumbleweed
+tupperware
+turtle
+tusk
+tutorial
+tuxedo
+tweezers
+twins
+tyrannical
+ultrasound
+umbrella
+umpire
+unarmored
+unbuttoned
+uncle
+underwear
+unevenness
+unflavored
+ungloved
+unhinge
+unicycle
+unjustly
+unknown
+unlocking
+unmarked
+unnoticed
+unopened
+unpaved
+unquenched
+unroll
+unscrewing
+untied
+unusual
+unveiled
+unwrinkled
+unyielding
+unzip
+upbeat
+upcountry
+update
+upfront
+upgrade
+upholstery
+upkeep
+upload
+uppercut
+upright
+upstairs
+uptown
+upwind
+uranium
+urban
+urchin
+urethane
+urgent
+urologist
+username
+usher
+utensil
+utility
+utmost
+utopia
+utterance
+vacuum
+vagrancy
+valuables
+vanquished
+vaporizer
+varied
+vaseline
+vegetable
+vehicle
+velcro
+vendor
+vertebrae
+vestibule
+veteran
+vexingly
+vicinity
+videogame
+viewfinder
+vigilante
+village
+vinegar
+violin
+viperfish
+virus
+visor
+vitamins
+vivacious
+vixen
+vocalist
+vogue
+voicemail
+volleyball
+voucher
+voyage
+vulnerable
+waffle
+wagon
+wakeup
+walrus
+wanderer
+wasp
+water
+waving
+wheat
+whisper
+wholesaler
+wick
+widow
+wielder
+wifeless
+wikipedia
+wildcat
+windmill
+wipeout
+wired
+wishbone
+wizardry
+wobbliness
+wolverine
+womb
+woolworker
+workbasket
+wound
+wrangle
+wreckage
+wristwatch
+wrongdoing
+xerox
+xylophone
+yacht
+yahoo
+yard
+yearbook
+yesterday
+yiddish
+yield
+yo-yo
+yodel
+yogurt
+yuppie
+zealot
+zebra
+zeppelin
+zestfully
+zigzagged
+zillion
+zipping
+zirconium
+zodiac
+zombie
+zookeeper
+zucchini
diff --git a/desktop/src-tauri/src/commands/agent_discovery.rs b/desktop/src-tauri/src/commands/agent_discovery.rs
index d6429e0454..cbbf4ce351 100644
--- a/desktop/src-tauri/src/commands/agent_discovery.rs
+++ b/desktop/src-tauri/src/commands/agent_discovery.rs
@@ -236,10 +236,12 @@ pub async fn install_acp_runtime(
     // returns (Guard impl Drop) — so Phase 2's restart path runs outside
     // the guard and cannot re-enter the mutex.
     let runtime_id_clone = runtime_id.clone();
-    let install_result =
-        tokio::task::spawn_blocking(move || install_acp_runtime_blocking(&runtime_id_clone))
-            .await
-            .map_err(|e| format!("install task panicked: {e}"))??;
+    let app_clone = app.clone();
+    let install_result = tokio::task::spawn_blocking(move || {
+        install_acp_runtime_blocking(&runtime_id_clone, &app_clone)
+    })
+    .await
+    .map_err(|e| format!("install task panicked: {e}"))??;
 
     if !install_result.success {
         return Ok(install_result);
@@ -259,12 +261,21 @@ pub async fn install_acp_runtime(
         steps: install_result.steps,
         restarted_count,
         failed_restart_count,
+        log_path: install_result.log_path,
     })
 }
 
 /// Err(_) = infrastructure failure (panic, concurrency guard).
 /// Ok({success: false}) = an install step failed (stderr captured in steps).
-fn install_acp_runtime_blocking(runtime_id: &str) -> Result<InstallRuntimeResult, String> {
+///
+/// The reporter is built here rather than by the caller so this run's log
+/// session starts only once the concurrency guard is held and the runtime id is
+/// resolved to its canonical catalog form: a rejected install must not rotate a
+/// running one's log, and the log filename is derived from that id.
+fn install_acp_runtime_blocking(
+    runtime_id: &str,
+    app: &tauri::AppHandle,
+) -> Result<InstallRuntimeResult, String> {
     // Re-fetch the login-shell PATH so a Node.js installation that happened
     // after app launch (or after a previous failed install) is visible to this
     // run and to the subsequent discover_acp_providers call.
@@ -297,6 +308,8 @@ fn install_acp_runtime_blocking(runtime_id: &str) -> Result<InstallRuntimeResult
     let runtime = crate::managed_agents::known_acp_runtime_exact(runtime_id)
         .ok_or_else(|| format!("unknown runtime: {runtime_id}"))?;
 
+    let reporter = InstallReporter::for_run(app, runtime.id);
+
     let mut steps = Vec::new();
 
     // Phase 1: Install CLI if missing and commands are available.
@@ -306,16 +319,11 @@ fn install_acp_runtime_blocking(runtime_id: &str) -> Result<InstallRuntimeResult
     if let Some(cli) = runtime.underlying_cli {
         if crate::managed_agents::resolve_command(cli).is_none() {
             for cmd in runtime.cli_install_commands_for_os() {
-                let result = run_install_command_with_retry("cli", cmd);
+                let result = run_install_command_with_retry("cli", cmd, &reporter);
                 let success = result.success;
                 steps.push(result);
                 if !success {
-                    return Ok(InstallRuntimeResult {
-                        success: false,
-                        steps,
-                        restarted_count: 0,
-                        failed_restart_count: 0,
-                    });
+                    return Ok(reporter.failed(steps));
                 }
             }
         }
@@ -340,13 +348,8 @@ fn install_acp_runtime_blocking(runtime_id: &str) -> Result<InstallRuntimeResult
             cmds.iter().any(|cmd| is_npm_global_install(cmd)) && managed_node_runtime_supported();
         if use_managed_npm {
             if let Err(step) = ensure_managed_node_runtime_blocking() {
-                steps.push(*step);
-                return Ok(InstallRuntimeResult {
-                    success: false,
-                    steps,
-                    restarted_count: 0,
-                    failed_restart_count: 0,
-                });
+                reporter.record_step(&mut steps, *step);
+                return Ok(reporter.failed(steps));
             }
         }
 
@@ -359,40 +362,31 @@ fn install_acp_runtime_blocking(runtime_id: &str) -> Result<InstallRuntimeResult
                 Ok(Some(command)) => command,
                 Ok(None) => cmd.to_string(),
                 Err(step) => {
-                    steps.push(*step);
-                    return Ok(InstallRuntimeResult {
-                        success: false,
-                        steps,
-                        restarted_count: 0,
-                        failed_restart_count: 0,
-                    });
+                    reporter.record_step(&mut steps, *step);
+                    return Ok(reporter.failed(steps));
                 }
             };
 
-            let mut result = run_install_command_with_retry("adapter", &planned);
+            let mut result = run_install_command_with_retry("adapter", &planned, &reporter);
             if !result.success && result.hint.is_none() && is_npm_global_install(cmd) {
                 result.hint = npm_eacces_hint(&result.stderr, cmd);
             }
             let success = result.success;
             steps.push(result);
             if !success {
-                return Ok(InstallRuntimeResult {
-                    success: false,
-                    steps,
-                    restarted_count: 0,
-                    failed_restart_count: 0,
-                });
+                return Ok(reporter.failed(steps));
             }
         }
     }
 
-    post_install_verification::run(runtime_id, &mut steps);
+    post_install_verification::run(runtime_id, &mut steps, &reporter);
 
     Ok(InstallRuntimeResult {
         success: steps.iter().all(|step| step.success),
         steps,
         restarted_count: 0,
         failed_restart_count: 0,
+        log_path: reporter.log_path(),
     })
 }
 
@@ -1016,8 +1010,11 @@ fn build_install_command(command: &str) -> Result<std::process::Command, String>
 }
 
 // ── install command execution ─────────────────────────────────────────────────
+mod install_capture;
 mod install_exec;
+mod install_report;
 use install_exec::run_install_command_with_retry;
+use install_report::InstallReporter;
 
 // ── managed Node/npm runtime ──────────────────────────────────────────────────
 mod managed_node;
diff --git a/desktop/src-tauri/src/commands/agent_discovery/install_capture.rs b/desktop/src-tauri/src/commands/agent_discovery/install_capture.rs
new file mode 100644
index 0000000000..903b68715a
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_discovery/install_capture.rs
@@ -0,0 +1,319 @@
+//! Bounded capture of an install command's output.
+//!
+//! One drain per stream feeds a [`Capture`], which holds two independently
+//! bounded views of the same bytes: a small one sized for an error toast and a
+//! large one sized for the install log file. Both are shared with the draining
+//! reader rather than returned by it, so whatever arrived before a stall is
+//! readable at the ceiling — exactly when the output matters most.
+
+use std::collections::VecDeque;
+use std::io::Read;
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+
+/// How much of each end a capture keeps, and how it names what was cut.
+#[derive(Clone, Copy)]
+struct Caps {
+    head: usize,
+    tail: usize,
+    marker: fn(usize) -> String,
+}
+
+/// Sized for a UI error message: enough to identify the failure, small enough
+/// to read in a toast.
+const UI_CAPS: Caps = Caps {
+    head: 512,
+    tail: 1024,
+    marker: |omitted| format!("... ({omitted} bytes omitted) ..."),
+};
+
+/// Sized for the log file, where the budget is disk rather than screen. At this
+/// cap a real install log is complete in practice; the marker names the cases
+/// where it is not, so the file never implies completeness it does not have.
+const LOG_CAPS: Caps = Caps {
+    head: 128 * 1024,
+    tail: 128 * 1024,
+    marker: |omitted| format!("... [{omitted} bytes omitted at cap] ..."),
+};
+
+/// Bounded capture of one stream: its first `head` bytes, its last `tail`
+/// bytes, and the total byte count. Output of any size costs a fixed amount of
+/// memory, so an installer that prints megabytes cannot grow the process.
+struct BoundedOutput {
+    head: Vec<u8>,
+    tail: VecDeque<u8>,
+    total: usize,
+    caps: Caps,
+}
+
+type SharedOutput = Arc<Mutex<BoundedOutput>>;
+
+impl BoundedOutput {
+    fn shared(caps: Caps) -> SharedOutput {
+        Arc::new(Mutex::new(Self {
+            head: Vec::new(),
+            tail: VecDeque::new(),
+            total: 0,
+            caps,
+        }))
+    }
+
+    /// Absorb one read. Chunk boundaries are irrelevant to the result: the head
+    /// fills first, the remainder rolls through the tail window.
+    fn push(&mut self, chunk: &[u8]) {
+        self.total += chunk.len();
+        let head_room = self
+            .caps
+            .head
+            .saturating_sub(self.head.len())
+            .min(chunk.len());
+        let (head_part, tail_part) = chunk.split_at(head_room);
+        self.head.extend_from_slice(head_part);
+        self.tail.extend(tail_part);
+        while self.tail.len() > self.caps.tail {
+            self.tail.pop_front();
+        }
+    }
+
+    fn render(&self) -> String {
+        let tail: Vec<u8> = self.tail.iter().copied().collect();
+        if self.total <= self.caps.head + self.caps.tail {
+            // Nothing was dropped, so head followed by tail is the whole stream.
+            let mut whole = self.head.clone();
+            whole.extend_from_slice(&tail);
+            return decode(&whole);
+        }
+        // Both ends are cut at arbitrary byte offsets, so trim any partial
+        // character rather than emitting replacement chars, then drop the
+        // partial *token* each cut left behind. The marker counts every dropped
+        // byte, including both trims.
+        let head = erode_head(utf8_prefix(&self.head));
+        let tail = erode_tail(utf8_suffix(&tail));
+        let omitted = self.total - head.len() - tail.len();
+        format!(
+            "{}\n{}\n{}",
+            decode(head),
+            (self.caps.marker)(omitted),
+            decode(tail)
+        )
+    }
+}
+
+/// The two bounded views of one stream, filled by a single drain.
+pub(super) struct Capture {
+    ui: SharedOutput,
+    log: SharedOutput,
+}
+
+impl Capture {
+    pub(super) fn new() -> Self {
+        Self {
+            ui: BoundedOutput::shared(UI_CAPS),
+            log: BoundedOutput::shared(LOG_CAPS),
+        }
+    }
+
+    /// What the UI shows for this stream.
+    pub(super) fn ui(&self) -> String {
+        render(&self.ui)
+    }
+
+    /// What the install log records for this stream.
+    pub(super) fn log(&self) -> String {
+        render(&self.log)
+    }
+
+    fn push(&self, chunk: &[u8]) {
+        for sink in [&self.ui, &self.log] {
+            if let Ok(mut sink) = sink.lock() {
+                sink.push(chunk);
+            }
+        }
+    }
+}
+
+/// Called with each complete line an install prints, for the live output line
+/// in the UI. Shared across both drain threads of one attempt.
+pub(super) type LineObserver = Arc<dyn Fn(&str) + Send + Sync>;
+
+/// Render a capture even if its drain thread panicked mid-write — a poisoned
+/// lock must not cost the diagnostics.
+fn render(sink: &SharedOutput) -> String {
+    sink.lock().unwrap_or_else(|p| p.into_inner()).render()
+}
+
+/// Read `pipe` to EOF, feeding fixed-size chunks into `capture` and each
+/// complete line to `observer`. Read errors end the drain — a broken pipe means
+/// the child is gone and there is nothing left to capture.
+pub(super) fn drain_into(mut pipe: impl Read, capture: &Capture, observer: Option<&LineObserver>) {
+    let mut chunk = [0u8; 8192];
+    let mut lines = LineSplitter::default();
+    loop {
+        match pipe.read(&mut chunk) {
+            Ok(0) => return,
+            Ok(n) => {
+                capture.push(&chunk[..n]);
+                if let Some(observe) = observer {
+                    lines.feed(&chunk[..n], |line| observe(line));
+                }
+            }
+            Err(e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
+            Err(_) => return,
+        }
+    }
+}
+
+/// Reassembles lines from arbitrary read chunks. A partial trailing line is
+/// held until its newline arrives, so an observer only ever sees complete
+/// lines. The buffer is capped: a program that prints megabytes without a
+/// newline must not grow it without bound.
+#[derive(Default)]
+struct LineSplitter {
+    partial: Vec<u8>,
+}
+
+impl LineSplitter {
+    /// Longest line reassembled. Beyond this the excess is dropped, since the
+    /// consumer displays a single truncated line anyway.
+    const MAX_LINE: usize = 4096;
+
+    fn feed(&mut self, chunk: &[u8], mut emit: impl FnMut(&str)) {
+        for byte in chunk {
+            if *byte == b'\n' {
+                let line = String::from_utf8_lossy(&self.partial).trim().to_string();
+                self.partial.clear();
+                if !line.is_empty() {
+                    emit(&line);
+                }
+            } else if self.partial.len() < Self::MAX_LINE {
+                self.partial.push(*byte);
+            }
+        }
+    }
+}
+
+/// Rate limiter for the live output line: at most one event per
+/// `min_interval`.
+///
+/// A line arriving inside the window is *held* rather than dropped, and the
+/// newest held line replaces any older one. Dropping was wrong at two points:
+/// the last line of an attempt — typically the failure that caused the retry —
+/// vanished if it landed inside the window, and so did a new attempt's first
+/// line when it arrived within 250ms of the previous attempt's last.
+pub(super) struct Throttle {
+    min_interval: Duration,
+    state: Mutex<ThrottleState>,
+}
+
+#[derive(Default)]
+struct ThrottleState {
+    last_emitted: Option<Instant>,
+    pending: Option<String>,
+}
+
+impl Throttle {
+    pub(super) fn new(min_interval: Duration) -> Self {
+        Self {
+            min_interval,
+            state: Mutex::new(ThrottleState::default()),
+        }
+    }
+
+    /// Offer one line. `Some` means emit it now; `None` means it is held as the
+    /// newest pending line, to be emitted by [`Throttle::take_pending`] or
+    /// replaced by a line that supersedes it.
+    pub(super) fn offer(&self, line: &str, now: Instant) -> Option<String> {
+        let Ok(mut state) = self.state.lock() else {
+            return None;
+        };
+        if state
+            .last_emitted
+            .is_some_and(|prev| now.duration_since(prev) < self.min_interval)
+        {
+            state.pending = Some(line.to_string());
+            return None;
+        }
+        state.last_emitted = Some(now);
+        // Emitting a newer line makes the held one obsolete: the display shows
+        // one line, and it must be the latest.
+        state.pending = None;
+        Some(line.to_string())
+    }
+
+    /// Take the held line, if the window closed on one.
+    pub(super) fn take_pending(&self) -> Option<String> {
+        self.state.lock().ok()?.pending.take()
+    }
+
+    /// Open the window for a new attempt, so its first line is emitted
+    /// immediately instead of waiting out the previous attempt's window.
+    pub(super) fn restart(&self) {
+        if let Ok(mut state) = self.state.lock() {
+            *state = ThrottleState::default();
+        }
+    }
+}
+
+fn decode(bytes: &[u8]) -> String {
+    String::from_utf8_lossy(bytes).into_owned()
+}
+
+/// Drop a trailing partial UTF-8 sequence, keeping mid-stream invalid bytes for
+/// the lossy decode to mark.
+fn utf8_prefix(bytes: &[u8]) -> &[u8] {
+    match std::str::from_utf8(bytes) {
+        Ok(_) => bytes,
+        Err(e) if e.error_len().is_none() => &bytes[..e.valid_up_to()],
+        Err(_) => bytes,
+    }
+}
+
+/// Drop leading UTF-8 continuation bytes — at most three can precede a
+/// character start.
+fn utf8_suffix(bytes: &[u8]) -> &[u8] {
+    let start = bytes
+        .iter()
+        .take(3)
+        .take_while(|b| *b & 0b1100_0000 == 0b1000_0000)
+        .count();
+    &bytes[start..]
+}
+
+/// How far a cut edge looks for a token boundary. Sized past any credential
+/// shape worth protecting (an `nsec1` key is 63 bytes, registry tokens are
+/// shorter) and short enough that erosion costs a token rather than a chunk of
+/// output. A cut inside a longer whitespace-free run is left alone: erasing
+/// kilobytes of a single-token stream would cost more diagnostics than the
+/// fragment could leak.
+const MAX_ERODED_TOKEN: usize = 256;
+
+/// Drop the partial token a head cut left at its end.
+///
+/// Redaction runs on the rendered text and matches whole tokens: a prefixed
+/// secret up to the next whitespace, or an exact env value. A cut through the
+/// middle of a secret leaves a fragment that matches neither and therefore
+/// survives scrubbing, so the fragment is removed here instead — at the cut,
+/// where it is still identifiable as partial. The omitted-byte marker counts
+/// what this drops.
+fn erode_head(bytes: &[u8]) -> &[u8] {
+    let window = bytes.len().saturating_sub(MAX_ERODED_TOKEN);
+    match bytes[window..].iter().rposition(u8::is_ascii_whitespace) {
+        Some(last) => &bytes[..=window + last],
+        None => bytes,
+    }
+}
+
+/// Drop the partial token a tail cut left at its start — the direction that
+/// matters most, since a fragment there has lost the `nsec1`-style prefix the
+/// scrubber keys on. See [`erode_head`].
+fn erode_tail(bytes: &[u8]) -> &[u8] {
+    let window = MAX_ERODED_TOKEN.min(bytes.len());
+    match bytes[..window].iter().position(u8::is_ascii_whitespace) {
+        Some(first) => &bytes[first..],
+        None => bytes,
+    }
+}
+
+#[cfg(test)]
+#[path = "install_capture_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/commands/agent_discovery/install_capture_tests.rs b/desktop/src-tauri/src/commands/agent_discovery/install_capture_tests.rs
new file mode 100644
index 0000000000..8830f355df
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_discovery/install_capture_tests.rs
@@ -0,0 +1,437 @@
+use super::*;
+
+/// Feed `chunks` through a capture in order.
+fn capture_of(chunks: &[&[u8]]) -> Capture {
+    let capture = Capture::new();
+    for chunk in chunks {
+        capture.push(chunk);
+    }
+    capture
+}
+
+/// Render what the UI would show for a stream of `chunks`.
+fn ui(chunks: &[&[u8]]) -> String {
+    capture_of(chunks).ui()
+}
+
+// ── bounded capture ──────────────────────────────────────────────────────────
+
+/// Output within the cap is passed through byte-for-byte — no marker, no loss.
+#[test]
+fn test_capture_leaves_short_output_untouched() {
+    let short = "a".repeat(1536);
+
+    assert_eq!(ui(&[short.as_bytes()]), short);
+}
+
+/// Over the cap, both ends survive and the middle is replaced by a marker
+/// naming the omitted byte count — the head keeps the command's opening
+/// context and the tail keeps the error that usually trails.
+#[test]
+fn test_capture_over_cap_keeps_head_and_tail_with_marker() {
+    let input = format!(
+        "{}{}{}",
+        "H".repeat(512),
+        "M".repeat(4000),
+        "T".repeat(1024)
+    );
+
+    let out = ui(&[input.as_bytes()]);
+
+    assert!(out.starts_with(&"H".repeat(512)));
+    assert!(out.ends_with(&"T".repeat(1024)));
+    assert!(
+        out.contains("... (4000 bytes omitted) ..."),
+        "marker must name the omitted byte count, got: {out}"
+    );
+}
+
+/// The rendered result depends only on the byte stream, not on how the reads
+/// happened to split it — a real drain sees arbitrary chunk sizes.
+#[test]
+fn test_capture_is_independent_of_chunk_boundaries() {
+    let input = "x".repeat(9000);
+    let one_shot = ui(&[input.as_bytes()]);
+
+    let chunked: Vec<&[u8]> = input.as_bytes().chunks(7).collect();
+
+    assert_eq!(ui(&chunked), one_shot);
+}
+
+/// Truncation must not split a multi-byte character. Both cut points land
+/// mid-codepoint here; the partial bytes are dropped rather than decoded into
+/// replacement chars.
+#[test]
+fn test_capture_does_not_split_multibyte_characters() {
+    // "é" is 2 bytes, so every candidate cut index lands mid-character.
+    let input = "é".repeat(4000);
+
+    let out = ui(&[input.as_bytes()]);
+
+    assert!(out.contains("bytes omitted"), "input must exceed the cap");
+    assert!(!out.contains('\u{fffd}'), "no replacement chars: {out}");
+}
+
+/// Memory stays flat regardless of how much the installer prints: the rendered
+/// UI result of a 4MiB stream is no larger than that of a 6KiB one.
+#[test]
+fn test_capture_of_huge_output_stays_bounded() {
+    let chunk = vec![b'z'; 8192];
+
+    let capture = Capture::new();
+    for _ in 0..512 {
+        capture.push(&chunk);
+    }
+
+    let out = capture.ui();
+    assert!(
+        out.len() < 2048,
+        "4MiB of output must render bounded, got {} bytes",
+        out.len()
+    );
+    assert!(out.contains("bytes omitted"));
+}
+
+// ── the log view is separately bounded ───────────────────────────────────────
+
+/// The log view holds output the UI view had to cut. A toast is capped for
+/// readability; the log file's budget is disk, and "Full log: {path}" has to
+/// point at more than the toast already showed.
+#[test]
+fn test_log_view_keeps_output_the_ui_view_truncates() {
+    let input = format!("start{}end", "m".repeat(64 * 1024));
+
+    let capture = capture_of(&[input.as_bytes()]);
+
+    assert!(
+        capture.ui().contains("bytes omitted"),
+        "64KiB must exceed the UI cap"
+    );
+    assert_eq!(
+        capture.log(),
+        input,
+        "the same output must be complete in the log view"
+    );
+}
+
+/// Even the log view is bounded — a runaway installer cannot fill the disk —
+/// and when it does cut, the record says so inline at the cap rather than
+/// implying completeness.
+#[test]
+fn test_log_view_is_bounded_and_marks_its_cap() {
+    let head = "H".repeat(128 * 1024);
+    let middle = "M".repeat(5000);
+    let tail = "T".repeat(128 * 1024);
+    let input = format!("{head}{middle}{tail}");
+
+    let capture = capture_of(&[input.as_bytes()]);
+
+    let out = capture.log();
+    assert!(
+        out.len() < 300 * 1024,
+        "output past the log cap must render bounded, got {} bytes",
+        out.len()
+    );
+    assert!(out.starts_with(&head), "the log head must survive intact");
+    assert!(out.ends_with(&tail), "the log tail must survive intact");
+    assert!(
+        out.contains("... [5000 bytes omitted at cap] ..."),
+        "a cut log record must name the cap inline, got the middle: {}",
+        &out[128 * 1024..(128 * 1024 + 64).min(out.len())]
+    );
+}
+
+/// The two views mark their cuts differently on purpose: the toast reads as
+/// prose, the log record reads as a machine-scannable annotation.
+#[test]
+fn test_ui_and_log_views_use_their_own_cap_markers() {
+    let input = "x".repeat(300 * 1024);
+
+    let capture = capture_of(&[input.as_bytes()]);
+
+    assert!(
+        capture.ui().contains("bytes omitted) ..."),
+        "the UI marker reads as prose: {}",
+        capture.ui()
+    );
+    assert!(capture.log().contains("bytes omitted at cap] ..."));
+}
+
+// ── line observation ─────────────────────────────────────────────────────────
+
+/// Collect the lines a drain over `chunks` reports.
+fn observed_lines(chunks: &[&[u8]]) -> Vec<String> {
+    let seen: Arc<Mutex<Vec<String>>> = Arc::new(Mutex::new(Vec::new()));
+    let observer: LineObserver = {
+        let seen = Arc::clone(&seen);
+        Arc::new(move |line: &str| seen.lock().unwrap().push(line.to_string()))
+    };
+    let bytes: Vec<u8> = chunks.concat();
+
+    drain_into(bytes.as_slice(), &Capture::new(), Some(&observer));
+
+    let observed = seen.lock().unwrap().clone();
+    observed
+}
+
+/// The observer sees complete lines, reassembled across the read boundaries
+/// that split them — a live output line must never show half a word.
+#[test]
+fn test_observer_reassembles_lines_split_across_reads() {
+    let lines = observed_lines(&[b"downloa", b"ding 40%\nunpack", b"ing\n"]);
+
+    assert_eq!(lines, vec!["downloading 40%", "unpacking"]);
+}
+
+/// A trailing line with no newline is never reported: it may still be growing,
+/// and showing a half-line as if complete is worse than showing the previous
+/// one.
+#[test]
+fn test_observer_withholds_a_line_that_has_no_newline_yet() {
+    let lines = observed_lines(&[b"complete\n", b"still-writing"]);
+
+    assert_eq!(lines, vec!["complete"]);
+}
+
+/// Blank lines carry nothing to display; progress output is full of them.
+#[test]
+fn test_observer_skips_blank_lines() {
+    let lines = observed_lines(&[b"a\n\n  \nb\n"]);
+
+    assert_eq!(lines, vec!["a", "b"]);
+}
+
+/// A pathological line with no newline must not grow the buffer without bound.
+#[test]
+fn test_observer_caps_a_pathologically_long_line() {
+    let huge = "x".repeat(100_000);
+
+    let lines = observed_lines(&[huge.as_bytes(), b"\n"]);
+
+    assert_eq!(lines.len(), 1);
+    assert!(
+        lines[0].len() <= LineSplitter::MAX_LINE,
+        "line must be capped, got {} bytes",
+        lines[0].len()
+    );
+}
+
+/// A drain with no observer still captures — the log and UI views do not
+/// depend on anyone watching.
+#[test]
+fn test_drain_captures_without_an_observer() {
+    let capture = Capture::new();
+
+    drain_into(b"hello\n".as_slice(), &capture, None);
+
+    assert_eq!(capture.ui(), "hello\n");
+}
+
+// ── throttle ─────────────────────────────────────────────────────────────────
+
+/// The first line goes out immediately, and one arriving inside the window is
+/// *held* rather than dropped: it becomes the pending line, so the newest output
+/// survives the rate limit instead of vanishing.
+#[test]
+fn test_throttle_emits_the_first_line_and_holds_the_next_in_window() {
+    let throttle = Throttle::new(Duration::from_millis(250));
+    let start = Instant::now();
+
+    assert_eq!(throttle.offer("first", start), Some("first".to_string()));
+    assert_eq!(
+        throttle.offer("second", start + Duration::from_millis(100)),
+        None
+    );
+    assert_eq!(
+        throttle.take_pending(),
+        Some("second".to_string()),
+        "the line inside the window must be retained, not dropped"
+    );
+}
+
+/// A burst inside one window collapses to its newest line: the display shows a
+/// single line, so an older held line has no value once a newer one exists.
+#[test]
+fn test_throttle_keeps_only_the_newest_held_line() {
+    let throttle = Throttle::new(Duration::from_millis(250));
+    let start = Instant::now();
+    throttle.offer("emitted", start);
+
+    throttle.offer("held-then-superseded", start + Duration::from_millis(50));
+    throttle.offer("newest", start + Duration::from_millis(100));
+
+    assert_eq!(throttle.take_pending(), Some("newest".to_string()));
+}
+
+/// Once the window passes, emission resumes and nothing is left pending — the
+/// emitted line *is* the newest, so holding it too would emit it twice.
+#[test]
+fn test_throttle_emits_again_after_the_window_and_clears_the_held_line() {
+    let throttle = Throttle::new(Duration::from_millis(250));
+    let start = Instant::now();
+    throttle.offer("first", start);
+    throttle.offer("held", start + Duration::from_millis(50));
+
+    assert_eq!(
+        throttle.offer("later", start + Duration::from_millis(300)),
+        Some("later".to_string())
+    );
+
+    assert_eq!(
+        throttle.take_pending(),
+        None,
+        "a line emitted after the window supersedes the held one"
+    );
+}
+
+/// The window is measured from the last *emitted* line, not the last offer: a
+/// stream of held lines must not extend the silence.
+#[test]
+fn test_throttle_window_runs_from_the_last_emission() {
+    let throttle = Throttle::new(Duration::from_millis(250));
+    let start = Instant::now();
+    throttle.offer("first", start);
+
+    assert_eq!(
+        throttle.offer("held", start + Duration::from_millis(200)),
+        None
+    );
+
+    assert_eq!(
+        throttle.offer("next", start + Duration::from_millis(260)),
+        Some("next".to_string()),
+        "a held line must not restart the window"
+    );
+}
+
+/// A pending line is taken once. Taking it twice would re-emit a line the
+/// display already shows.
+#[test]
+fn test_throttle_yields_a_held_line_only_once() {
+    let throttle = Throttle::new(Duration::from_millis(250));
+    let start = Instant::now();
+    throttle.offer("first", start);
+    throttle.offer("held", start + Duration::from_millis(50));
+
+    assert_eq!(throttle.take_pending(), Some("held".to_string()));
+
+    assert_eq!(throttle.take_pending(), None);
+}
+
+/// Restarting opens the window immediately, which is what lets a new attempt's
+/// first line go out even when it arrives inside the previous attempt's window.
+/// It also discards a held line: that line belongs to the attempt that just
+/// ended, and the new attempt is about to clear the display.
+#[test]
+fn test_throttle_restart_opens_the_window_and_discards_the_held_line() {
+    let throttle = Throttle::new(Duration::from_millis(250));
+    let start = Instant::now();
+    throttle.offer("previous attempt", start);
+    throttle.offer("held", start + Duration::from_millis(10));
+
+    throttle.restart();
+
+    assert_eq!(throttle.take_pending(), None);
+    assert_eq!(
+        throttle.offer("new attempt", start + Duration::from_millis(20)),
+        Some("new attempt".to_string())
+    );
+}
+
+// ── cut-edge erosion ─────────────────────────────────────────────────────────
+
+/// A secret cut in half by the head cap must not survive as a fragment.
+/// Redaction matches whole tokens — a prefixed secret up to the next whitespace
+/// — so `nsec1qqq…` cut mid-value would still be scrubbed, but the *tail* of
+/// that same value, having lost its prefix, would not be. Both cut edges drop
+/// their partial token for that reason.
+#[test]
+fn test_capture_drops_the_partial_token_at_each_cut_edge() {
+    // Positioned so the head cap lands inside the first secret and the tail cap
+    // inside the second.
+    let head_secret = "nsec1headsecretvalue";
+    let tail_secret = "nsec1tailsecretvalue";
+    let input = format!(
+        "{} {head_secret} {} {tail_secret} {}",
+        "h".repeat(500),
+        "m".repeat(4000),
+        "t".repeat(1010)
+    );
+
+    let out = ui(&[input.as_bytes()]);
+
+    assert!(out.contains("bytes omitted"), "input must exceed the cap");
+    for fragment in ["nsec1head", "secretvalue"] {
+        assert!(
+            !out.contains(fragment),
+            "a fragment of a cut token must not survive: {out}"
+        );
+    }
+}
+
+/// Erosion stops at the nearest whitespace, so it costs one partial token and
+/// not the surrounding output — the head's earlier lines and the tail's later
+/// ones are what make a truncated capture readable.
+#[test]
+fn test_capture_erosion_keeps_the_complete_tokens_around_the_cut() {
+    let input = format!(
+        "opening line
+{}
+cut-here-head{}cut-here-tail
+{}
+closing line
+",
+        "h".repeat(480),
+        "m".repeat(4000),
+        "t".repeat(980)
+    );
+
+    let out = ui(&[input.as_bytes()]);
+
+    assert!(out.starts_with("opening line\n"), "got: {out}");
+    assert!(out.ends_with("closing line\n"), "got: {out}");
+}
+
+/// A cut inside a whitespace-free run longer than the erosion window is left
+/// intact. Erosion is bounded on purpose: erasing kilobytes of a single-token
+/// stream — `npm` progress bars and base64 payloads both look like this — would
+/// cost more diagnostics than a fragment of one could leak.
+#[test]
+fn test_capture_of_one_giant_token_keeps_its_cut_edges() {
+    let input = "x".repeat(4000);
+
+    let out = ui(&[input.as_bytes()]);
+
+    assert!(out.starts_with(&"x".repeat(512)), "got: {out}");
+    assert!(out.ends_with(&"x".repeat(1024)), "got: {out}");
+}
+
+/// The marker's byte count stays honest across erosion: what it names as omitted
+/// must equal the input minus what is actually shown, or a reader cannot trust
+/// the file to say how much is missing.
+#[test]
+fn test_capture_marker_counts_the_bytes_erosion_dropped() {
+    let input = format!(
+        "{} {} {}",
+        "h".repeat(600),
+        "m".repeat(4000),
+        "t".repeat(1100)
+    );
+
+    let out = ui(&[input.as_bytes()]);
+
+    let (head, rest) = out.split_once('\n').expect("a marker line");
+    let (marker, tail) = rest.split_once('\n').expect("a marker line");
+    let omitted: usize = marker
+        .trim_start_matches("... (")
+        .split_once(' ')
+        .expect("a byte count")
+        .0
+        .parse()
+        .expect("a byte count");
+    assert_eq!(
+        head.len() + omitted + tail.len(),
+        input.len(),
+        "shown + omitted must account for every input byte"
+    );
+}
diff --git a/desktop/src-tauri/src/commands/agent_discovery/install_exec.rs b/desktop/src-tauri/src/commands/agent_discovery/install_exec.rs
index 63163ceadc..3b94f2ef8a 100644
--- a/desktop/src-tauri/src/commands/agent_discovery/install_exec.rs
+++ b/desktop/src-tauri/src/commands/agent_discovery/install_exec.rs
@@ -5,13 +5,46 @@
 //! `install_powershell_command`, `build_install_command`); this module owns
 //! only what happens once a `Command` exists.
 
-use std::io::Read;
+use std::sync::Arc;
+use std::time::{Duration, Instant};
 
+use super::install_capture::{drain_into, Capture, LineObserver};
+use super::install_report::{InstallOutcome, InstallReporter};
 use crate::managed_agents::InstallStepResult;
 
 /// Maximum number of attempts for a transient-looking install command.
 const INSTALL_MAX_ATTEMPTS: u32 = 3;
 
+/// Absolute wall-clock ceiling for a single install command.
+///
+/// This is a ceiling, not an inactivity timeout: nothing observable
+/// distinguishes a hung installer from one silently transferring a large
+/// artifact (the Goose step downloads a ~79MB release asset with no progress
+/// output, and npm at its default log level prints only at the end), so silence
+/// alone never kills an install. The previous 300s wall killed
+/// slow-but-working installs — Windows Defender scanning every file npm
+/// extracts pushes past it routinely (#2401).
+///
+/// The cost of a larger ceiling: skipping onboarding does not cancel a running
+/// install and a per-runtime guard rejects a second one, so this is also the
+/// longest a user who skipped a genuinely *hung* install waits before Install
+/// works again in Settings. User-facing cancellation is the product-level fix.
+const INSTALL_TIMEOUT: Duration = Duration::from_secs(900);
+
+/// How long the group gets to exit on SIGTERM before the ceiling escalates to
+/// SIGKILL.
+#[cfg(unix)]
+const TERM_GRACE: Duration = Duration::from_secs(1);
+
+/// How long the ceiling waits after killing the install's process group —
+/// applied separately to reaping the killed child and to the output drains
+/// finishing. The kill closes the pipe write ends, so both normally complete
+/// within microseconds; the bound covers the cases where they don't (a process
+/// that escaped the group and still holds a pipe, or a termination that failed
+/// outright). Neither may hold the install — nor the per-runtime concurrency
+/// guard behind it — open past the ceiling.
+const POST_KILL_GRACE: Duration = Duration::from_secs(2);
+
 /// Run an install command, retrying transient failures with backoff.
 ///
 /// Runtime installs pull artifacts over the network — Goose's `curl … | bash`
@@ -22,10 +55,24 @@ const INSTALL_MAX_ATTEMPTS: u32 = 3;
 /// `INSTALL_MAX_ATTEMPTS` times. Failures with no exit code — a timeout or a
 /// shell that never spawned — are not retried, since re-running them just costs
 /// the user more time without a plausible path to success.
-pub(super) fn run_install_command_with_retry(step: &str, command: &str) -> InstallStepResult {
+///
+/// Every attempt is recorded through `reporter`, so the install log holds the
+/// full retry history even though the UI only ever sees the last attempt.
+pub(super) fn run_install_command_with_retry(
+    step: &str,
+    command: &str,
+    reporter: &InstallReporter,
+) -> InstallStepResult {
     run_install_with_retry(
         INSTALL_MAX_ATTEMPTS,
-        |_attempt| run_install_command(step, command),
+        |attempt| {
+            // Before the command spawns, so the previous attempt's last line
+            // stops being displayed for the whole backoff rather than until the
+            // new attempt happens to print something.
+            reporter.start_attempt();
+            let outcome = run_install_command(step, command, reporter.line_observer());
+            reporter.record_attempt(attempt, outcome)
+        },
         std::thread::sleep,
     )
 }
@@ -92,11 +139,15 @@ fn prepare_install_command(command: &str) -> Result<std::process::Command, Strin
     Ok(cmd)
 }
 
-fn run_install_command(step: &str, command: &str) -> InstallStepResult {
+fn run_install_command(
+    step: &str,
+    command: &str,
+    observer: Option<LineObserver>,
+) -> InstallOutcome {
     let mut cmd = match prepare_install_command(command) {
         Ok(cmd) => cmd,
         Err(hint) => {
-            return InstallStepResult {
+            return InstallOutcome::synthesized(InstallStepResult {
                 step: step.to_string(),
                 command: command.to_string(),
                 success: false,
@@ -104,11 +155,11 @@ fn run_install_command(step: &str, command: &str) -> InstallStepResult {
                 stderr: "no suitable shell found for install commands".to_string(),
                 exit_code: None,
                 hint: Some(hint),
-            };
+            });
         }
     };
 
-    let mut child = match cmd
+    let child = match cmd
         .stdin(std::process::Stdio::null())
         .stdout(std::process::Stdio::piped())
         .stderr(std::process::Stdio::piped())
@@ -116,7 +167,7 @@ fn run_install_command(step: &str, command: &str) -> InstallStepResult {
     {
         Ok(child) => child,
         Err(e) => {
-            return InstallStepResult {
+            return InstallOutcome::synthesized(InstallStepResult {
                 step: step.to_string(),
                 command: command.to_string(),
                 success: false,
@@ -124,146 +175,312 @@ fn run_install_command(step: &str, command: &str) -> InstallStepResult {
                 stderr: format!("failed to spawn shell: {e}"),
                 exit_code: None,
                 hint: None,
-            };
+            });
         }
     };
 
-    // Drain stdout/stderr on background threads to prevent pipe buffer deadlock.
+    await_install_child(step, command, child, INSTALL_TIMEOUT, observer)
+}
+
+/// Drain a spawned install child's output into bounded buffers and wait for it
+/// to exit, killing it at `timeout`.
+///
+/// Split from the spawn so the timing-sensitive half is testable without a real
+/// login shell: shell startup alone can outlast a short test ceiling on a
+/// loaded machine. Production always passes [`INSTALL_TIMEOUT`].
+fn await_install_child(
+    step: &str,
+    command: &str,
+    mut child: std::process::Child,
+    timeout: Duration,
+    observer: Option<LineObserver>,
+) -> InstallOutcome {
+    // Drain stdout/stderr on background threads to prevent pipe buffer
+    // deadlock. Each drain feeds a bounded capture the main thread can read at
+    // any time, so a timeout can still surface whatever the install printed
+    // before it stalled.
+    let stdout_capture = Arc::new(Capture::new());
+    let stderr_capture = Arc::new(Capture::new());
     let stdout_pipe = child.stdout.take();
     let stderr_pipe = child.stderr.take();
 
-    let stdout_thread = std::thread::spawn(move || {
-        let mut buf = String::new();
-        if let Some(mut pipe) = stdout_pipe {
-            let _ = pipe.read_to_string(&mut buf);
+    // One event stream carries every input the ceiling waits on, so the exit
+    // and the drains are governed by the same deadline instead of the exit
+    // releasing the drains from it.
+    let (events_tx, events) = std::sync::mpsc::channel();
+
+    std::thread::spawn({
+        let (capture, done, observer) = (
+            Arc::clone(&stdout_capture),
+            events_tx.clone(),
+            observer.clone(),
+        );
+        move || {
+            if let Some(pipe) = stdout_pipe {
+                drain_into(pipe, &capture, observer.as_ref());
+            }
+            let _ = done.send(Settled::Drained);
         }
-        buf
     });
-    let stderr_thread = std::thread::spawn(move || {
-        let mut buf = String::new();
-        if let Some(mut pipe) = stderr_pipe {
-            let _ = pipe.read_to_string(&mut buf);
+    std::thread::spawn({
+        let (capture, done) = (Arc::clone(&stderr_capture), events_tx.clone());
+        move || {
+            if let Some(pipe) = stderr_pipe {
+                drain_into(pipe, &capture, observer.as_ref());
+            }
+            let _ = done.send(Settled::Drained);
         }
-        buf
     });
 
     // Save the PID before moving `child` into the wait thread so we can
     // kill the process on timeout.
     let child_pid = child.id();
 
-    let (tx, rx) = std::sync::mpsc::channel();
-    let wait_thread = std::thread::spawn(move || {
-        let status = child.wait();
-        let _ = tx.send(status);
+    std::thread::spawn(move || {
+        let _ = events_tx.send(Settled::Exited(child.wait()));
     });
 
-    // 5-minute timeout for install commands.
-    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(300);
-    loop {
-        let remaining = deadline.saturating_duration_since(std::time::Instant::now());
-        if remaining.is_zero() {
-            // Timeout: kill the child process via its PID, then join all
-            // threads so nothing leaks.
-            #[cfg(unix)]
-            unsafe {
-                libc::kill(child_pid as i32, libc::SIGTERM);
-            }
-            #[cfg(windows)]
-            {
-                let _ = crate::managed_agents::taskkill_tree(child_pid);
-            }
-            drop(rx);
-            let _ = wait_thread.join();
-            let _ = stdout_thread.join();
-            let _ = stderr_thread.join();
-            return InstallStepResult {
+    // No thread is ever joined. Each sends its one event before exiting, so a
+    // join after a complete settle would add nothing — and a join before one
+    // would reintroduce the unbounded wait this loop exists to prevent.
+    let mut settle = Settle::default();
+    let ended = settle.collect(&events, Instant::now() + timeout);
+    if ended == Collected::Deadline {
+        // Ceiling reached: kill the install's whole process group — the install
+        // shell is a session leader (`setsid` in its `pre_exec`), so signalling
+        // only the leader would leave descendants running and holding the
+        // output pipes open.
+        //
+        // Whether the leader had already exited decides the verdict. If it had,
+        // only a descendant was holding a drain open: the install genuinely
+        // finished and its real status stands. If it had not, the install itself
+        // was still running and this is a timeout — the status the kill produces
+        // moments later describes the kill, not the install, so it is discarded.
+        let install_finished = settle.status.is_some();
+        terminate_install_group(child_pid);
+        // Reaping the child and finishing the drains share one bound. Both
+        // normally complete within microseconds of the kill, which closes the
+        // pipes; when they don't — a process that escaped the group still
+        // holding a pipe, or a termination that failed outright — waiting would
+        // defeat the very ceiling that fired and keep the per-runtime install
+        // guard behind it closed. Stragglers are detached instead; the captures
+        // are read under the lock either way.
+        settle.collect(&events, Instant::now() + POST_KILL_GRACE);
+        if !install_finished {
+            return failed_with_capture(
+                step,
+                command,
+                timeout_message(timeout),
+                &stdout_capture,
+                &stderr_capture,
+            );
+        }
+    }
+
+    match settle.status {
+        Some(Ok(status)) => InstallOutcome {
+            step: InstallStepResult {
                 step: step.to_string(),
                 command: command.to_string(),
-                success: false,
-                stdout: String::new(),
-                stderr: "install command timed out after 5 minutes".to_string(),
-                exit_code: None,
+                success: status.success(),
+                stdout: stdout_capture.ui(),
+                stderr: stderr_capture.ui(),
+                exit_code: status.code(),
                 hint: None,
-            };
-        }
+            },
+            log_stdout: stdout_capture.log(),
+            log_stderr: stderr_capture.log(),
+        },
+        Some(Err(e)) => failed_with_capture(
+            step,
+            command,
+            format!("failed to check process status: {e}"),
+            &stdout_capture,
+            &stderr_capture,
+        ),
+        // Every sender is gone without an exit ever arriving.
+        None => failed_with_capture(
+            step,
+            command,
+            "internal error: install wait ended without a status".to_string(),
+            &stdout_capture,
+            &stderr_capture,
+        ),
+    }
+}
 
-        match rx.recv_timeout(std::time::Duration::from_millis(200).min(remaining)) {
-            Ok(Ok(status)) => {
-                let _ = wait_thread.join();
-                let stdout = stdout_thread.join().unwrap_or_default();
-                let stderr_raw = stderr_thread.join().unwrap_or_default();
-                return InstallStepResult {
-                    step: step.to_string(),
-                    command: command.to_string(),
-                    success: status.success(),
-                    stdout: truncate_output(stdout),
-                    stderr: truncate_output(stderr_raw),
-                    exit_code: status.code(),
-                    hint: None,
-                };
-            }
-            Ok(Err(e)) => {
-                let _ = wait_thread.join();
-                let _ = stdout_thread.join();
-                let _ = stderr_thread.join();
-                return InstallStepResult {
-                    step: step.to_string(),
-                    command: command.to_string(),
-                    success: false,
-                    stdout: String::new(),
-                    stderr: format!("failed to check process status: {e}"),
-                    exit_code: None,
-                    hint: None,
-                };
-            }
-            Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {
-                // Still running; loop and check deadline again.
-                continue;
-            }
-            Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => {
-                // wait_thread dropped sender without sending — shouldn't happen.
-                let _ = wait_thread.join();
-                let _ = stdout_thread.join();
-                let _ = stderr_thread.join();
-                return InstallStepResult {
-                    step: step.to_string(),
-                    command: command.to_string(),
-                    success: false,
-                    stdout: String::new(),
-                    stderr: "internal error: wait thread disconnected".to_string(),
-                    exit_code: None,
-                    hint: None,
-                };
+/// One input the ceiling waits on.
+enum Settled {
+    Exited(std::io::Result<std::process::ExitStatus>),
+    Drained,
+}
+
+/// How a bounded [`Settle::collect`] ended.
+#[derive(PartialEq, Debug)]
+enum Collected {
+    /// The child exited and both drains reached EOF.
+    Complete,
+    /// The deadline passed first.
+    Deadline,
+    /// Every sender is gone — a thread died without reporting.
+    Disconnected,
+}
+
+/// What the install has settled so far: the child's exit status once it is
+/// known, and how many of the two drains have reached EOF.
+///
+/// Collecting is resumable, so the ceiling can fold more events into the same
+/// state under a second, post-kill deadline.
+#[derive(Default)]
+struct Settle {
+    status: Option<std::io::Result<std::process::ExitStatus>>,
+    drained: usize,
+}
+
+impl Settle {
+    const DRAINS: usize = 2;
+
+    fn is_complete(&self) -> bool {
+        self.status.is_some() && self.drained >= Self::DRAINS
+    }
+
+    /// Fold events until the install has fully settled or `deadline` passes.
+    ///
+    /// The exit and the drains share one deadline deliberately: a shell can exit
+    /// while a descendant it left behind still holds the inherited output pipes,
+    /// and waiting on those drains outside the deadline would let such a
+    /// descendant outlast the ceiling — holding the per-runtime install guard,
+    /// which is the very failure the ceiling exists to prevent.
+    fn collect(
+        &mut self,
+        events: &std::sync::mpsc::Receiver<Settled>,
+        deadline: Instant,
+    ) -> Collected {
+        while !self.is_complete() {
+            let remaining = deadline.saturating_duration_since(Instant::now());
+            match events.recv_timeout(remaining) {
+                Ok(Settled::Exited(status)) => self.status = Some(status),
+                Ok(Settled::Drained) => self.drained += 1,
+                Err(std::sync::mpsc::RecvTimeoutError::Timeout) => return Collected::Deadline,
+                Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => {
+                    return Collected::Disconnected
+                }
             }
         }
+        Collected::Complete
     }
 }
 
-/// Cap output to head + tail to avoid flooding the UI with large error dumps,
-/// while preserving the most useful parts of the output.
-fn truncate_output(s: String) -> String {
-    const HEAD: usize = 512;
-    const TAIL: usize = 1024;
-    const LIMIT: usize = HEAD + TAIL;
-    if s.len() <= LIMIT {
-        return s;
-    }
-    let head_end = floor_char_boundary(&s, HEAD);
-    let tail_start = floor_char_boundary(&s, s.len().saturating_sub(TAIL));
-    let omitted = tail_start - head_end;
-    format!(
-        "{}\n... ({omitted} bytes omitted) ...\n{}",
-        &s[..head_end],
-        &s[tail_start..]
-    )
+/// Kill the install's process group, escalating on the *tree's* liveness.
+///
+/// The install ceiling owns this rather than reusing
+/// `managed_agents::terminate_process`, which escalates to SIGKILL only while
+/// the group *leader* is still running: a descendant that ignores SIGTERM
+/// outlives the leader, keeps the output pipes open, and never receives the
+/// group SIGKILL. The ceiling's contract is that nothing survives it, and the
+/// shared helper's escalation is load-bearing for the agent stop/restore paths,
+/// so the stricter rule lives here instead of changing it for them.
+///
+/// Nothing is returned: every outcome — including a signal that could not be
+/// delivered at all — has the same handling, the bounded waits at the call
+/// site.
+#[cfg(unix)]
+fn terminate_install_group(pid: u32) {
+    signal_install_tree(pid, libc::SIGTERM);
+    let deadline = Instant::now() + TERM_GRACE;
+    while install_tree_is_alive(pid) {
+        if Instant::now() >= deadline {
+            signal_install_tree(pid, libc::SIGKILL);
+            return;
+        }
+        std::thread::sleep(Duration::from_millis(50));
+    }
+}
+
+/// Signal every process in `pid`'s group, falling back to the leader alone when
+/// the group cannot be signalled — the leader may have changed groups, or macOS
+/// may refuse one member — since killing the install shell beats killing
+/// nothing.
+#[cfg(unix)]
+fn signal_install_tree(pid: u32, signal: i32) {
+    if unsafe { libc::kill(-(pid as i32), signal) } != 0 {
+        unsafe { libc::kill(pid as i32, signal) };
+    }
+}
+
+/// Whether anything the ceiling aimed at is still running: a member of the
+/// process group, or the leader itself.
+#[cfg(unix)]
+fn install_tree_is_alive(pid: u32) -> bool {
+    signal_reaches(-(pid as i32)) || signal_reaches(pid as i32)
+}
+
+/// `kill(target, 0)` distinguishes "nothing there" (`ESRCH`) from every other
+/// outcome. Anything ambiguous — notably `EPERM` for a member we may not
+/// signal — counts as alive, so an unclear answer escalates rather than
+/// declaring the tree dead.
+#[cfg(unix)]
+fn signal_reaches(target: i32) -> bool {
+    if unsafe { libc::kill(target, 0) } == 0 {
+        return true;
+    }
+    std::io::Error::last_os_error().raw_os_error() != Some(libc::ESRCH)
+}
+
+/// Windows has no process groups on this path: `terminate_process` runs
+/// `taskkill /T /F`, which is already tree-wide and unconditional, so there is
+/// no escalation to get wrong.
+#[cfg(not(unix))]
+fn terminate_install_group(pid: u32) {
+    let _ = crate::managed_agents::terminate_process(pid);
 }
 
-fn floor_char_boundary(s: &str, mut index: usize) -> usize {
-    index = index.min(s.len());
-    while index > 0 && !s.is_char_boundary(index) {
-        index -= 1;
+/// A failure carrying whatever the drains captured, with `reason` leading
+/// stderr so the surfaced message names the failure before the install's own
+/// output.
+fn failed_with_capture(
+    step: &str,
+    command: &str,
+    reason: String,
+    stdout: &Capture,
+    stderr: &Capture,
+) -> InstallOutcome {
+    InstallOutcome {
+        step: InstallStepResult {
+            step: step.to_string(),
+            command: command.to_string(),
+            success: false,
+            stdout: stdout.ui(),
+            stderr: lead_with_reason(&reason, stderr.ui()),
+            exit_code: None,
+            hint: None,
+        },
+        log_stdout: stdout.log(),
+        log_stderr: lead_with_reason(&reason, stderr.log()),
     }
-    index
+}
+
+/// Put `reason` ahead of the install's own stderr, so the surfaced message names
+/// the failure before the output. An empty capture leaves the reason alone,
+/// without a dangling separator.
+fn lead_with_reason(reason: &str, captured: String) -> String {
+    if captured.is_empty() {
+        reason.to_string()
+    } else {
+        format!("{reason}\n{captured}")
+    }
+}
+
+/// Name the limit that fired and its value, so a ceiling kill is
+/// distinguishable from the installer's own failure.
+fn timeout_message(timeout: Duration) -> String {
+    let secs = timeout.as_secs();
+    let limit = if secs >= 60 {
+        format!("{}-minute", secs / 60)
+    } else {
+        format!("{secs}-second")
+    };
+    format!("install command exceeded the {limit} ceiling and was terminated")
 }
 
 #[cfg(test)]
@@ -410,48 +627,304 @@ mod tests {
         assert_eq!(cmd.get_current_dir(), Some(expected.as_path()));
     }
 
-    // ── output truncation ─────────────────────────────────────────────────────
+    // ── install ceiling ───────────────────────────────────────────────────────
+
+    /// The ceiling is Will's ruling: 15 minutes, and the error names the limit
+    /// that fired so a ceiling kill is not mistaken for the installer's own
+    /// failure.
+    #[test]
+    fn test_ceiling_is_fifteen_minutes_and_error_names_it() {
+        assert_eq!(INSTALL_TIMEOUT, Duration::from_secs(900));
+        assert!(
+            timeout_message(INSTALL_TIMEOUT).contains("15-minute"),
+            "got: {}",
+            timeout_message(INSTALL_TIMEOUT)
+        );
+    }
+
+    /// Spawn `script` under `sh` as a process-group leader with piped output —
+    /// the same shape [`run_install_command`] hands to
+    /// [`await_install_child`], minus the login shell whose own startup can
+    /// outlast a short test ceiling.
+    #[cfg(unix)]
+    fn spawn_group_leader(script: &str) -> std::process::Child {
+        use std::os::unix::process::CommandExt;
+
+        let mut cmd = std::process::Command::new("/bin/sh");
+        cmd.arg("-c").arg(script);
+        unsafe {
+            cmd.pre_exec(|| {
+                libc::setsid();
+                Ok(())
+            });
+        }
+        cmd.stdin(std::process::Stdio::null())
+            .stdout(std::process::Stdio::piped())
+            .stderr(std::process::Stdio::piped())
+            .spawn()
+            .expect("sh must spawn")
+    }
+
+    /// A command killed by the ceiling must surface what it printed before
+    /// stalling — that partial output is the only evidence of where the install
+    /// got stuck — and must stay unretryable, since re-running a hang just
+    /// costs the user another ceiling.
+    #[cfg(unix)]
+    #[test]
+    fn test_ceiling_returns_captured_output_and_stays_unretryable() {
+        let child = spawn_group_leader("echo out-before-hang; echo err-before-hang >&2; sleep 60");
+
+        let started = Instant::now();
+        let outcome = await_install_child("cli", "install", child, Duration::from_secs(5), None);
+        let result = &outcome.step;
+
+        assert!(!result.success);
+        assert_eq!(result.exit_code, None, "a killed command has no exit code");
+        assert!(
+            !install_failure_is_retryable(result),
+            "a ceiling kill must not be retried"
+        );
+        assert!(
+            result.stdout.contains("out-before-hang"),
+            "stdout captured before the stall must survive, got: {:?}",
+            result.stdout
+        );
+        assert!(
+            result.stderr.contains("5-second ceiling"),
+            "stderr must name the ceiling that actually fired, got: {:?}",
+            result.stderr
+        );
+        assert!(
+            result.stderr.contains("err-before-hang"),
+            "stderr captured before the stall must survive, got: {:?}",
+            result.stderr
+        );
+        assert!(
+            started.elapsed() < Duration::from_secs(30),
+            "the ceiling must not wait on the hung command's own exit"
+        );
+        assert!(
+            outcome.log_stderr.contains("err-before-hang"),
+            "the log record of a ceiling kill must carry the output too, got: {:?}",
+            outcome.log_stderr
+        );
+    }
+
+    /// A failure whose stream captured nothing surfaces the reason alone — no
+    /// dangling separator from an empty capture.
+    #[test]
+    fn test_failure_with_no_captured_output_reports_only_the_reason() {
+        let result = failed_with_capture(
+            "cli",
+            "curl … | bash",
+            "boom".to_string(),
+            &Capture::new(),
+            &Capture::new(),
+        )
+        .step;
+
+        assert_eq!(result.stdout, "");
+        assert_eq!(result.stderr, "boom");
+    }
+
+    // ── post-kill settle bound ────────────────────────────────────────────────
+
+    /// A sender that never arrives — the shape of a failed termination, whose
+    /// child is never reaped — must not extend the wait past its deadline.
+    #[test]
+    fn test_settling_on_a_message_that_never_arrives_stops_at_the_deadline() {
+        let (_tx, events) = std::sync::mpsc::channel::<Settled>();
+
+        let started = Instant::now();
+        let ended = Settle::default().collect(&events, started + Duration::from_millis(200));
+
+        assert_eq!(ended, Collected::Deadline);
+        assert!(
+            started.elapsed() < Duration::from_secs(1),
+            "the wait must end at its deadline, took {:?}",
+            started.elapsed()
+        );
+    }
+
+    /// An exit alone is not a settle: the drains are inputs to the same wait, so
+    /// a shell that exited while a descendant holds a pipe still hits the
+    /// deadline instead of being released from it.
+    #[test]
+    fn test_exit_without_drains_still_hits_the_deadline() {
+        let (tx, events) = std::sync::mpsc::channel();
+        tx.send(Settled::Exited(Ok(exit_status_zero()))).unwrap();
+
+        let started = Instant::now();
+        let mut settle = Settle::default();
+        let ended = settle.collect(&events, started + Duration::from_millis(200));
+
+        assert_eq!(
+            ended,
+            Collected::Deadline,
+            "a leader exit must not complete the settle while a drain is outstanding"
+        );
+        assert!(settle.status.is_some(), "the exit status must be retained");
+        assert!(started.elapsed() < Duration::from_secs(1));
+    }
 
-    /// Output within the cap is passed through byte-for-byte — no marker, no loss.
+    /// The settle completes only when the exit and both drains have arrived, and
+    /// it is resumable: state folded under the first deadline carries into the
+    /// post-kill one.
     #[test]
-    fn test_truncate_output_leaves_short_output_untouched() {
-        let short = "a".repeat(1536);
+    fn test_settle_completes_on_exit_plus_both_drains_and_resumes() {
+        let (tx, events) = std::sync::mpsc::channel();
+        tx.send(Settled::Drained).unwrap();
+
+        let mut settle = Settle::default();
+        assert_eq!(
+            settle.collect(&events, Instant::now() + Duration::from_millis(50)),
+            Collected::Deadline
+        );
+
+        tx.send(Settled::Exited(Ok(exit_status_zero()))).unwrap();
+        tx.send(Settled::Drained).unwrap();
+
+        assert_eq!(
+            settle.collect(&events, Instant::now() + Duration::from_secs(5)),
+            Collected::Complete,
+            "the second collect must build on the first's state, not restart it"
+        );
+    }
 
-        assert_eq!(truncate_output(short.clone()), short);
+    /// Exit status of a trivially successful command, for driving `Settle`
+    /// without a real install.
+    fn exit_status_zero() -> std::process::ExitStatus {
+        std::process::Command::new("true")
+            .status()
+            .expect("run `true`")
     }
 
-    /// Over the cap, both ends survive and the middle is replaced by a marker
-    /// naming the omitted byte count — the head keeps the command's opening
-    /// context and the tail keeps the error that usually trails.
+    /// A shell can exit while a descendant it left behind still holds the
+    /// inherited output pipes. If the exit released the drains from the
+    /// deadline, that descendant would hold the install — and the per-runtime
+    /// concurrency guard behind it — open indefinitely, which is exactly the
+    /// failure the ceiling exists to prevent. The leader here exits in
+    /// milliseconds; only the descendant outlives the ceiling.
+    #[cfg(unix)]
     #[test]
-    fn test_truncate_output_keeps_head_and_tail_with_marker() {
-        let input = format!(
-            "{}{}{}",
-            "H".repeat(512),
-            "M".repeat(4000),
-            "T".repeat(1024)
+    fn test_promptly_exited_leader_with_a_pipe_holding_descendant_still_obeys_the_ceiling() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let pidfile = dir.path().join("lingering.pid");
+        let child = spawn_group_leader(&format!(
+            "sh -c 'echo $$ > {pid}; sleep 120' & exit 3",
+            pid = pidfile.display()
+        ));
+
+        let started = Instant::now();
+        let outcome = await_install_child("cli", "install", child, Duration::from_secs(2), None);
+
+        assert!(
+            started.elapsed() < Duration::from_secs(30),
+            "a descendant holding the pipe must not outlast the ceiling, took {:?}",
+            started.elapsed()
         );
+        assert_eq!(
+            outcome.step.exit_code,
+            Some(3),
+            "the leader's real status outranks the ceiling's verdict once it is known"
+        );
+        // The deadline must still reach the kill on this path: a leader exit that
+        // skipped termination would leave the descendant running with the pipes
+        // open, which is the defect itself rather than a detail of it.
+        let pid = recorded_pid(&pidfile);
+        assert!(
+            await_death(pid),
+            "descendant {pid} survived — a leader exit must not skip the ceiling's kill"
+        );
+    }
 
-        let out = truncate_output(input);
+    /// Wait up to 3s for `pid` to disappear.
+    #[cfg(unix)]
+    fn await_death(pid: u32) -> bool {
+        for _ in 0..30 {
+            if !crate::managed_agents::process_is_running(pid) {
+                return true;
+            }
+            std::thread::sleep(Duration::from_millis(100));
+        }
+        false
+    }
+
+    /// Read the pid a test descendant recorded for itself.
+    #[cfg(unix)]
+    fn recorded_pid(pidfile: &std::path::Path) -> u32 {
+        for _ in 0..50 {
+            if let Ok(text) = std::fs::read_to_string(pidfile) {
+                if let Ok(pid) = text.trim().parse() {
+                    return pid;
+                }
+            }
+            std::thread::sleep(Duration::from_millis(100));
+        }
+        panic!("the descendant never recorded its pid at {pidfile:?}");
+    }
+
+    /// The install shell is a process-group leader, and its descendants inherit
+    /// the output pipes. Killing only the leader leaves them running and the
+    /// drains blocked on a pipe nobody will close, so the ceiling kills the
+    /// whole group.
+    #[cfg(unix)]
+    #[test]
+    fn test_ceiling_kills_descendants_holding_the_output_pipe() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let pidfile = dir.path().join("descendant.pid");
+        let child = spawn_group_leader(&format!(
+            "sh -c 'echo $$ > {pid}; sleep 60' & echo leader-up; sleep 60",
+            pid = pidfile.display()
+        ));
+
+        let started = Instant::now();
+        let outcome = await_install_child("cli", "install", child, Duration::from_secs(5), None);
+        let result = &outcome.step;
 
-        assert!(out.starts_with(&"H".repeat(512)));
-        assert!(out.ends_with(&"T".repeat(1024)));
+        assert!(!result.success);
         assert!(
-            out.contains("... (4000 bytes omitted) ..."),
-            "marker must name the omitted byte count, got: {out}"
+            started.elapsed() < Duration::from_secs(30),
+            "the drains must not block on a descendant's inherited pipe"
+        );
+
+        let pid = recorded_pid(&pidfile);
+        assert!(
+            await_death(pid),
+            "descendant {pid} survived the ceiling kill — the group was not signalled"
         );
     }
 
-    /// Truncation must not split a multi-byte character. Cutting mid-codepoint
-    /// would panic on the slice; the boundary floor prevents it.
+    /// Escalation must key off the group, not the leader: a descendant that
+    /// ignores SIGTERM outlives the leader, and if SIGKILL is skipped because
+    /// the leader is gone it keeps running with the output pipes open — past the
+    /// ceiling, and past the concurrency guard that blocks the next install.
+    #[cfg(unix)]
     #[test]
-    fn test_truncate_output_does_not_split_multibyte_characters() {
-        // "é" is 2 bytes, so every candidate cut index lands mid-character.
-        let input = "é".repeat(4000);
+    fn test_ceiling_kills_sigterm_ignoring_descendant() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let pidfile = dir.path().join("stubborn.pid");
+        // An ignored disposition survives exec, so the descendant's own `sleep`
+        // ignores SIGTERM too — nothing in that subtree dies without SIGKILL.
+        let child = spawn_group_leader(&format!(
+            "sh -c 'trap \"\" TERM; echo $$ > {pid}; sleep 60' & echo leader-up; sleep 60",
+            pid = pidfile.display()
+        ));
+
+        let started = Instant::now();
+        let outcome = await_install_child("cli", "install", child, Duration::from_secs(5), None);
+        let result = &outcome.step;
 
-        let out = truncate_output(input);
+        assert!(!result.success);
+        assert!(
+            started.elapsed() < Duration::from_secs(30),
+            "a SIGTERM-ignoring descendant must not hold the ceiling open"
+        );
 
-        assert!(out.contains("bytes omitted"), "input must exceed the cap");
-        assert!(!out.contains('\u{fffd}'), "no replacement chars: {out}");
+        let pid = recorded_pid(&pidfile);
+        assert!(
+            await_death(pid),
+            "SIGTERM-ignoring descendant {pid} survived — escalation followed the leader, not the group"
+        );
     }
 }
diff --git a/desktop/src-tauri/src/commands/agent_discovery/install_report.rs b/desktop/src-tauri/src/commands/agent_discovery/install_report.rs
new file mode 100644
index 0000000000..24bcd3456a
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_discovery/install_report.rs
@@ -0,0 +1,595 @@
+//! Where an install's output goes: the install log file (complete history) and
+//! the live output line in the UI (current progress).
+//!
+//! Both destinations hang off the same drain seam in
+//! [`super::install_capture`], and both are best-effort: an install must never
+//! fail because a log write or an event emit did.
+//!
+//! [`InstallReporter`] owns two explicit lifecycles, because both the log and
+//! the live line are meaningless without a notion of "this run":
+//!
+//! * a **log session**, started once per run, which keeps the previous run's
+//!   file as `.1` and writes this run's header; and
+//! * a **live-event sequence**, monotonic across the whole install, which is
+//!   what lets the UI drop a superseded line. A per-command retry number
+//!   cannot do that job — it restarts at 1 for every step.
+
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::{Arc, Mutex, RwLock};
+use std::time::{Duration, Instant};
+
+use serde::Serialize;
+
+use super::install_capture::{LineObserver, Throttle};
+use crate::managed_agents::{InstallRuntimeResult, InstallStepResult};
+
+/// One install command's result: what the UI shows, and the log-scale copy of
+/// the same output for the log file.
+pub(super) struct InstallOutcome {
+    pub(super) step: InstallStepResult,
+    pub(super) log_stdout: String,
+    pub(super) log_stderr: String,
+}
+
+impl InstallOutcome {
+    /// A step Buzz synthesized rather than ran — a failed prerequisite, or the
+    /// post-install verification. Its own message is the whole record.
+    pub(super) fn synthesized(step: InstallStepResult) -> Self {
+        Self {
+            log_stdout: step.stdout.clone(),
+            log_stderr: step.stderr.clone(),
+            step,
+        }
+    }
+}
+
+/// Payload of the `acp-install-output` event.
+///
+/// `seq` is monotonic across the entire install, so the UI can drop a line a
+/// later step or attempt has already superseded. The retry number cannot serve
+/// as that key: it restarts at 1 for every step, so a step that succeeded on
+/// attempt 2 would make the next step's attempt-1 output look stale and freeze
+/// the display.
+///
+/// `line: None` is the *start signal*: an attempt is beginning and the displayed
+/// line must clear now. It is emitted unthrottled, because the point is that
+/// stale output stops being shown before the new work prints anything.
+#[derive(Serialize, Clone, Debug)]
+pub(super) struct InstallOutputEvent {
+    pub(super) runtime_id: String,
+    pub(super) seq: u64,
+    pub(super) line: Option<String>,
+}
+
+/// Emits one live output event. Boxed rather than holding an `AppHandle` so the
+/// reporter is constructible — and assertable — without a Tauri app.
+type EmitEvent = Arc<dyn Fn(InstallOutputEvent) + Send + Sync>;
+
+/// Literal secret values scrubbed out of everything this module publishes, in
+/// addition to the shapes [`crate::managed_agents::redact_secrets_with`]
+/// recognises on its own.
+type Secrets = Arc<Vec<String>>;
+
+/// At most four live-output events per second. Coalescing *holds* the newest
+/// line rather than dropping it: a burst that ends just before the window
+/// closes would otherwise leave the display showing a line the install had
+/// already moved past.
+const LIVE_LINE_INTERVAL: Duration = Duration::from_millis(250);
+
+pub(super) struct InstallReporter {
+    log: Option<InstallLog>,
+    /// `None` when nothing is listening, which is also what makes
+    /// [`InstallReporter::line_observer`] `None` — the drain then skips line
+    /// reassembly entirely instead of doing it for no one.
+    live: Option<Live>,
+    secrets: Secrets,
+}
+
+impl Drop for InstallReporter {
+    /// Serialise deactivation against in-flight publications: take the
+    /// exclusive lifecycle write lock, mark the run as inactive, and return —
+    /// all before the per-runtime concurrency guard releases.
+    ///
+    /// Every drain thread holds the shared read guard from its admission check
+    /// through its `(self.emit)(...)` call, so the write lock here blocks until
+    /// every in-flight publication has finished.  After this returns, `active`
+    /// is `false` under an exclusive write, and any thread that attempts a new
+    /// `offer` will read `false` under a read lock and return without emitting.
+    ///
+    /// The ordering guarantee: `reporter` is declared after `_guard` in
+    /// `install_acp_runtime_blocking` (line 311 vs line 306), so Rust drops
+    /// `reporter` first in reverse-declaration order — deactivation completes
+    /// before the runtime guard releases and a new install can start.
+    fn drop(&mut self) {
+        if let Some(live) = &self.live {
+            if let Ok(mut active) = live.lifecycle.write() {
+                *active = false;
+            }
+        }
+    }
+}
+
+impl InstallReporter {
+    /// The reporter a real install run uses: it starts this run's log session
+    /// and emits live output events through `app`.
+    ///
+    /// `runtime_id` must already be the canonical id from the runtime catalog —
+    /// the log path is built from it, so resolving it first is what keeps a raw
+    /// command argument out of a filename.
+    ///
+    /// A log that cannot be resolved or opened degrades to no log rather than
+    /// failing the install: a user with a broken app-data directory still needs
+    /// the install itself to work.
+    pub(super) fn for_run(app: &tauri::AppHandle, runtime_id: &str) -> Self {
+        // Read from the app's own package info rather than the frontend's
+        // `getVersion` plugin call: the header is written on the Rust side, and
+        // this cannot fail or be mocked out from under the log.
+        let app_version = app.package_info().version.to_string();
+        let log = crate::managed_agents::storage::install_log_path(app, runtime_id)
+            .ok()
+            .and_then(|path| InstallLog::start(&path, runtime_id, &app_version));
+        let app = app.clone();
+        let emit: EmitEvent = Arc::new(move |event| {
+            use tauri::Emitter;
+            let _ = app.emit("acp-install-output", event);
+        });
+        Self::new(runtime_id, log, Some(emit))
+    }
+
+    fn new(runtime_id: &str, log: Option<InstallLog>, emit: Option<EmitEvent>) -> Self {
+        // Snapshot the environment's secrets once, at construction: the install
+        // inherits this environment, so anything it echoes came from here.
+        Self::with_secrets(runtime_id, log, emit, env_secret_values())
+    }
+
+    /// The reporter over an explicit secret set, which is what makes the
+    /// scrubbing assertable: a test can name a proxy credential without
+    /// exporting a real `HTTPS_PROXY` into the process every HTTP client in the
+    /// suite would then read.
+    fn with_secrets(
+        runtime_id: &str,
+        log: Option<InstallLog>,
+        emit: Option<EmitEvent>,
+        secrets: Vec<String>,
+    ) -> Self {
+        let secrets: Secrets = Arc::new(secrets);
+        let live = emit.map(|emit| Live {
+            runtime_id: Arc::from(runtime_id),
+            emit,
+            throttle: Arc::new(Throttle::new(LIVE_LINE_INTERVAL)),
+            seq: Arc::new(AtomicU64::new(0)),
+            lifecycle: Arc::new(RwLock::new(true)),
+            secrets: Arc::clone(&secrets),
+        });
+        Self { log, live, secrets }
+    }
+
+    /// The log file to point the user at, or `None` when this run has no log —
+    /// the failure message then omits the pointer rather than naming a file
+    /// that does not exist.
+    pub(super) fn log_path(&self) -> Option<String> {
+        Some(self.log.as_ref()?.path.display().to_string())
+    }
+
+    /// A failed install carrying the steps recorded so far and the log holding
+    /// their full history. Every early return in the install shapes its result
+    /// here, so none can forget the log pointer the failure message needs.
+    pub(super) fn failed(&self, steps: Vec<InstallStepResult>) -> InstallRuntimeResult {
+        InstallRuntimeResult {
+            success: false,
+            steps,
+            restarted_count: 0,
+            failed_restart_count: 0,
+            log_path: self.log_path(),
+        }
+    }
+
+    /// Mark the start of one executed attempt: clear whatever line the previous
+    /// attempt left on screen, and start this attempt's clock.
+    ///
+    /// The clear is emitted unthrottled and reopens the rate window, so the new
+    /// attempt's first line cannot be swallowed by the previous attempt's.
+    /// Without this signal the prior attempt's last line — typically the failure
+    /// that caused the retry — sits under the spinner through the backoff and
+    /// through a silent next attempt.
+    pub(super) fn start_attempt(&self) {
+        if let Some(log) = &self.log {
+            log.mark_attempt_start();
+        }
+        if let Some(live) = &self.live {
+            live.throttle.restart();
+            live.publish(None);
+        }
+    }
+
+    /// Observer for one attempt's drains, or `None` when nothing is listening.
+    pub(super) fn line_observer(&self) -> Option<LineObserver> {
+        let live = self.live.clone()?;
+        Some(Arc::new(move |line: &str| live.offer(line)))
+    }
+
+    /// Record one executed attempt of a step, returning the step with secrets
+    /// scrubbed out of the output the UI will render.
+    ///
+    /// The scrub happens here rather than at the construction sites because
+    /// every executed step reaches the caller through this function — the
+    /// timeout path, the status-check failure, and the ordinary exit all build
+    /// their `InstallStepResult` straight from the captures.
+    pub(super) fn record_attempt(
+        &self,
+        attempt: u32,
+        outcome: InstallOutcome,
+    ) -> InstallStepResult {
+        // The drains are finished, so a line the throttle is still holding is
+        // this attempt's last and nothing is coming to replace it.
+        if let Some(live) = &self.live {
+            live.flush_pending();
+        }
+        self.write_record(Some(attempt), &outcome);
+        self.redacted_step(outcome.step)
+    }
+
+    /// Push a synthesized step onto `steps` and record it. Routing every step
+    /// through here is what keeps the log complete: a step that reaches the UI
+    /// without passing this function is invisible in the file.
+    pub(super) fn record_step(&self, steps: &mut Vec<InstallStepResult>, step: InstallStepResult) {
+        self.write_record(None, &InstallOutcome::synthesized(step.clone()));
+        steps.push(self.redacted_step(step));
+    }
+
+    /// Scrub the frontend-visible fields of a step. The failure message the UI
+    /// builds renders `stderr`/`stdout` and the hint verbatim, so they need the
+    /// same scrubbing as the log record and the live line — the log is not the
+    /// only place an install's output is read.
+    fn redacted_step(&self, mut step: InstallStepResult) -> InstallStepResult {
+        step.command = redact(&step.command, &self.secrets);
+        step.stdout = redact(&step.stdout, &self.secrets);
+        step.stderr = redact(&step.stderr, &self.secrets);
+        step.hint = step.hint.map(|hint| redact(&hint, &self.secrets));
+        step
+    }
+
+    /// Append one record. Best-effort by contract: a full disk or a revoked
+    /// permission degrades the diagnostics, it does not fail the install.
+    fn write_record(&self, attempt: Option<u32>, outcome: &InstallOutcome) {
+        let Some(log) = &self.log else {
+            return;
+        };
+        log.append(&render_record(
+            attempt,
+            log.take_attempt_elapsed(),
+            outcome,
+            &self.secrets,
+        ));
+    }
+}
+
+/// The shared half of the reporter — everything a drain thread's observer needs,
+/// owned rather than borrowed so an observer can outlive the call that made it.
+#[derive(Clone)]
+struct Live {
+    runtime_id: Arc<str>,
+    emit: EmitEvent,
+    throttle: Arc<Throttle>,
+    seq: Arc<AtomicU64>,
+    /// Lifecycle lock: `true` while the run is active, `false` once
+    /// `InstallReporter` has been dropped.
+    ///
+    /// Drain threads hold a **shared read guard** from the admission check
+    /// through the `(self.emit)(...)` call, making the admit-and-publish pair
+    /// atomic with respect to deactivation. `InstallReporter::drop` takes the
+    /// **exclusive write guard** and sets the value to `false`; this blocks
+    /// until every in-flight publication finishes, then prevents any new
+    /// publications from starting. The write lock is held only for the flag
+    /// store and is released before the per-runtime concurrency guard drops,
+    /// so its duration is bounded by the time a single `emit` call takes —
+    /// microseconds to low milliseconds for the Tauri IPC broadcast.
+    lifecycle: Arc<RwLock<bool>>,
+    secrets: Secrets,
+}
+
+impl Live {
+    /// Offer one drained line to the rate limiter, emitting it if the window is
+    /// open and holding it as the newest pending line if not.
+    ///
+    /// The read guard is held from the admission check through the emit call so
+    /// that `InstallReporter::drop`'s write lock must wait for any in-flight
+    /// publication to complete before deactivating.  This makes the
+    /// check-then-emit pair atomic with respect to shutdown.
+    fn offer(&self, line: &str) {
+        let Ok(guard) = self.lifecycle.read() else {
+            return;
+        };
+        if !*guard {
+            return;
+        }
+        if let Some(line) = self.throttle.offer(line, Instant::now()) {
+            self.publish_under_guard(line);
+        }
+        // `guard` drops here, releasing the read lock after publication.
+    }
+
+    fn flush_pending(&self) {
+        let Ok(guard) = self.lifecycle.read() else {
+            return;
+        };
+        if !*guard {
+            return;
+        }
+        if let Some(line) = self.throttle.take_pending() {
+            self.publish_under_guard(line);
+        }
+        // `guard` drops here, releasing the read lock after publication.
+    }
+
+    /// Emit `line` now, bypassing the rate window and the lifecycle lock.
+    ///
+    /// Only called from `InstallReporter` methods that run on the reporter
+    /// itself (never from detached drain threads), so no lifecycle guard is
+    /// needed — the reporter is alive by definition when its own methods run.
+    fn publish(&self, line: Option<String>) {
+        (self.emit)(InstallOutputEvent {
+            runtime_id: self.runtime_id.to_string(),
+            seq: self.seq.fetch_add(1, Ordering::Relaxed),
+            line: line.map(|line| redact(&line, &self.secrets)),
+        });
+    }
+
+    /// Publish `line` while already holding a read guard on `lifecycle`.  The
+    /// caller is responsible for checking `active` before calling this.
+    fn publish_under_guard(&self, line: String) {
+        (self.emit)(InstallOutputEvent {
+            runtime_id: self.runtime_id.to_string(),
+            seq: self.seq.fetch_add(1, Ordering::Relaxed),
+            line: Some(redact(&line, &self.secrets)),
+        });
+    }
+}
+
+/// This run's log file: one session, opened once, appended to per record.
+struct InstallLog {
+    path: PathBuf,
+    /// When the attempt currently running started, so its record can name its
+    /// own duration. A 15-minute ceiling is only diagnosable if the file says
+    /// how long each attempt actually took.
+    attempt_start: Mutex<Option<Instant>>,
+}
+
+impl InstallLog {
+    /// Start this run's session, or `None` if the file cannot be opened.
+    ///
+    /// Rotation happens here, once per run, rather than per record: a run either
+    /// gets its own file or it gets no log at all, so two runs are never
+    /// interleaved in one file.
+    ///
+    /// The header identifies the environment the run happened in, not just the
+    /// run: a Windows install failure and a macOS one on the same runtime are
+    /// different bugs, and a stale app version explains a failure that no longer
+    /// reproduces.
+    fn start(path: &Path, runtime_id: &str, app_version: &str) -> Option<Self> {
+        let mut file = crate::managed_agents::storage::start_install_log_session(path).ok()?;
+        let _ = file.write_all(
+            format!(
+                "=== install run runtime={runtime_id} app={app_version} os={} started={}\n",
+                std::env::consts::OS,
+                chrono::Utc::now().to_rfc3339()
+            )
+            .as_bytes(),
+        );
+        Some(Self {
+            path: path.to_path_buf(),
+            attempt_start: Mutex::new(None),
+        })
+    }
+
+    fn mark_attempt_start(&self) {
+        if let Ok(mut start) = self.attempt_start.lock() {
+            *start = Some(Instant::now());
+        }
+    }
+
+    /// How long the attempt being recorded ran, consumed so a later record
+    /// cannot reuse it. `None` for a synthesized step, which never ran.
+    fn take_attempt_elapsed(&self) -> Option<Duration> {
+        Some(self.attempt_start.lock().ok()?.take()?.elapsed())
+    }
+
+    fn append(&self, record: &str) {
+        if let Ok(mut file) = crate::managed_agents::storage::open_install_log_file(&self.path) {
+            let _ = file.write_all(record.as_bytes());
+        }
+    }
+}
+
+/// One self-contained record. Each is capped independently by the log-scale
+/// capture that produced it, so an early attempt that printed megabytes cannot
+/// push a later attempt — or the verification step that explains the failure —
+/// out of the file.
+fn render_record(
+    attempt: Option<u32>,
+    elapsed: Option<Duration>,
+    outcome: &InstallOutcome,
+    secrets: &Secrets,
+) -> String {
+    let step = &outcome.step;
+    let attempt = attempt.map_or_else(|| "-".to_string(), |n| n.to_string());
+    let exit = step
+        .exit_code
+        .map_or_else(|| "none".to_string(), |code| code.to_string());
+    let elapsed = elapsed.map_or_else(
+        || "-".to_string(),
+        |elapsed| format!("{:.1}s", elapsed.as_secs_f64()),
+    );
+    let mut record = format!(
+        "=== {} step={} attempt={attempt} success={} exit={exit} elapsed={elapsed}\n$ {}\n",
+        chrono::Utc::now().to_rfc3339(),
+        step.step,
+        step.success,
+        redact(&step.command, secrets),
+    );
+    for (label, text) in [
+        ("stdout", &outcome.log_stdout),
+        ("stderr", &outcome.log_stderr),
+    ] {
+        if !text.trim().is_empty() {
+            record.push_str(&format!("--- {label} ---\n{}\n", redact(text, secrets)));
+        }
+    }
+    if let Some(hint) = &step.hint {
+        record.push_str(&format!("--- hint ---\n{}\n", redact(hint, secrets)));
+    }
+    record
+}
+
+/// Scrub secrets before anything reaches disk or the UI. The log is written
+/// unattended and the live line is rendered verbatim, so scrubbing happens at
+/// the write, not at the read.
+fn redact(text: &str, secrets: &Secrets) -> String {
+    let extras: Vec<&str> = secrets.iter().map(String::as_str).collect();
+    crate::managed_agents::redact_secrets_with(text, &extras)
+}
+
+/// Values of environment variables whose *name* marks them as secret.
+///
+/// An install inherits Buzz's environment and installers echo it back — npm
+/// prints the resolved registry config on an auth failure, and a shell that
+/// traces its commands prints every expansion. Without this, only the
+/// hard-coded key shapes would be scrubbed, so a plain `NPM_TOKEN` or
+/// `ANTHROPIC_API_KEY` would land in the file in clear text.
+fn env_secret_values() -> Vec<String> {
+    secret_values_from(std::env::vars())
+}
+
+/// The secret-bearing part of each variable that carries one.
+///
+/// Split from [`env_secret_values`] so the classification is assertable without
+/// mutating the process environment — setting a real `HTTPS_PROXY` in a test
+/// would be read by every HTTP client the rest of the suite builds.
+///
+/// Three kinds of variable are recognised, because they need different
+/// treatment:
+///
+/// * **URL-valued variables**, where only the userinfo is the credential;
+/// * **exactly named credentials**, whose whole value is the secret; and
+/// * **name-marked secrets**, matched by a marker substring.
+fn secret_values_from(vars: impl IntoIterator<Item = (String, String)>) -> Vec<String> {
+    vars.into_iter()
+        .filter_map(|(name, value)| {
+            let name = name.to_ascii_uppercase();
+            if URL_CREDENTIAL_VAR_NAMES.contains(&name.as_str()) {
+                // Only the userinfo, so the endpoint itself stays named in the
+                // record: an install that fails against a proxy or a private
+                // registry is diagnosable only if the log still says which one
+                // it went through, and the host and port are not the secret.
+                // Redacting the whole value would erase that while protecting
+                // nothing more.
+                return url_userinfo(&value).map(str::to_string);
+            }
+            if SECRET_VAR_NAMES.contains(&name.as_str()) {
+                // Deliberately not subject to the 8-byte floor below: an exact
+                // name is a fact, not the guess the marker rule makes, so there
+                // is nothing for a floor to protect against. npm's one-time
+                // password is six digits and is a credential at that length —
+                // short, but still above the four-byte minimum
+                // [`crate::managed_agents::redact_secrets_with`] applies, so it
+                // survives to be scrubbed.
+                return (!value.is_empty()).then_some(value);
+            }
+            // A value under 8 bytes is more likely a flag like `true` or a
+            // version than a credential, and scrubbing those makes ordinary
+            // output unreadable.
+            (value.len() >= 8 && name_marks_secret(&name)).then_some(value)
+        })
+        .collect()
+}
+
+/// Variables whose value is a URL that may embed a credential in its userinfo.
+///
+/// npm's own `npm_config_*` aliases are here too: npm resolves them ahead of
+/// the conventional names and echoes the result from `npm config list`, and
+/// none of these names carries a marker [`name_marks_secret`] would catch.
+/// Matching is case-insensitive because the caller uppercases the name first,
+/// which is what npm's lowercase spelling needs.
+const URL_CREDENTIAL_VAR_NAMES: &[&str] = &[
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "ALL_PROXY",
+    "NPM_CONFIG_PROXY",
+    "NPM_CONFIG_HTTPS_PROXY",
+    "NPM_CONFIG_REGISTRY",
+];
+
+/// Variables whose whole value is a credential, recognised by exact name.
+///
+/// These are npm's supported credential settings, whose names carry no marker
+/// [`name_marks_secret`] would catch. They are listed exactly rather than
+/// matched on `KEY` or `AUTH` substrings: those occur throughout an ordinary
+/// environment, and scrubbing on them would delete unrelated values from the
+/// whole log.
+///
+/// * `NPM_CONFIG_KEY` — the PEM client key used to reach a registry.
+/// * `NPM_CONFIG__AUTH` — the base64 basic-auth blob (npm's own double
+///   underscore, matching the `_auth` setting).
+/// * `NPM_CONFIG_OTP` — the registry one-time password.
+const SECRET_VAR_NAMES: &[&str] = &["NPM_CONFIG_KEY", "NPM_CONFIG__AUTH", "NPM_CONFIG_OTP"];
+
+/// Whether an environment variable's name marks its value as a credential.
+///
+/// Keyed on the name because a secret's *value* has no reliable shape. The
+/// markers avoid substrings that occur in non-secret names: `AUTH` is left out
+/// because it matches `GIT_AUTHOR_NAME`, whose value is a person's name, and
+/// personal access tokens match on `_PAT` as a *suffix* rather than a substring
+/// — `contains("_PAT")` would match every `*_PATH` variable on the system and
+/// scrub directory names out of the whole log.
+fn name_marks_secret(name: &str) -> bool {
+    const SECRET_NAME_MARKERS: &[&str] = &[
+        "TOKEN",
+        "SECRET",
+        "PASSWORD",
+        "PASSWD",
+        "APIKEY",
+        "API_KEY",
+        "PRIVATE_KEY",
+        "ACCESS_KEY",
+        "CREDENTIAL",
+    ];
+    name.ends_with("_PAT")
+        || SECRET_NAME_MARKERS
+            .iter()
+            .any(|marker| name.contains(marker))
+}
+
+/// The `user:password` credential embedded in a URL, if it has one.
+///
+/// Parsed rather than pattern-matched so a URL with no credential — the common
+/// case — contributes nothing to scrub. The last `@` in the
+/// authority separates userinfo from host, so a password containing an
+/// encoded `@` still splits correctly.
+///
+/// A bare username with no password is not treated as a credential: it is not
+/// secret on its own, and scrubbing it would erase every occurrence of a word
+/// like `user` from the whole record.
+fn url_userinfo(value: &str) -> Option<&str> {
+    let authority = value
+        .split_once("://")?
+        .1
+        .split(['/', '?', '#'])
+        .next()
+        .unwrap_or_default();
+    let userinfo = authority.rsplit_once('@')?.0;
+    userinfo.contains(':').then_some(userinfo)
+}
+
+#[cfg(test)]
+#[path = "install_report_test_support.rs"]
+mod test_support;
+
+#[cfg(test)]
+#[path = "install_report_tests.rs"]
+mod tests;
+
+#[cfg(test)]
+#[path = "install_report_redaction_tests.rs"]
+mod redaction_tests;
diff --git a/desktop/src-tauri/src/commands/agent_discovery/install_report_redaction_tests.rs b/desktop/src-tauri/src/commands/agent_discovery/install_report_redaction_tests.rs
new file mode 100644
index 0000000000..ce97559616
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_discovery/install_report_redaction_tests.rs
@@ -0,0 +1,480 @@
+use super::test_support::*;
+use super::*;
+
+// ── redaction ────────────────────────────────────────────────────────────────
+
+/// Secrets that an installer echoed must not land on disk. The log is written
+/// unattended, so scrubbing happens at the write, not at the read.
+#[test]
+fn test_log_redacts_secrets_before_writing() {
+    let h = harness();
+    let leak = "npm ERR! token nsec1qqqqqqqqqqsecretvalue failed";
+
+    h.reporter.record_attempt(1, outcome("cli", false, leak));
+
+    let log = h.log_contents();
+    assert!(!log.contains("nsec1qqqqqqqqqqsecretvalue"), "got: {log}");
+    assert!(log.contains("[REDACTED]"), "got: {log}");
+}
+
+/// The environment's own secrets are scrubbed too, by *name* rather than shape.
+/// An install inherits Buzz's environment and installers echo it back — npm
+/// prints its resolved config on an auth failure — and a token with no
+/// recognizable prefix would otherwise reach the file verbatim.
+#[test]
+fn test_log_redacts_an_environment_secret_with_no_recognizable_prefix() {
+    let secret = "0e8f31c5a4b7d296e5f1a";
+    // Set before the reporter is built: the snapshot is taken at construction.
+    std::env::set_var("BUZZ_TEST_REGISTRY_TOKEN", secret);
+    let h = harness();
+    std::env::remove_var("BUZZ_TEST_REGISTRY_TOKEN");
+
+    h.reporter.record_attempt(
+        1,
+        outcome("cli", false, &format!("npm ERR! _authToken={secret}")),
+    );
+
+    let log = h.log_contents();
+    assert!(!log.contains(secret), "got: {log}");
+    assert!(log.contains("[REDACTED]"), "got: {log}");
+}
+
+/// A live line carries the same scrubbing as the log record. The line is
+/// rendered verbatim in the UI, so a leak there is as visible as one on disk.
+#[test]
+fn test_a_live_line_is_redacted_before_it_is_emitted() {
+    let h = harness();
+
+    let observer = h.reporter.line_observer().expect("an observer");
+    observer("fetching with token nsec1qqqqqqqqqqleaked");
+
+    let lines = h.lines();
+    assert_eq!(lines.len(), 1);
+    let line = lines[0].clone().expect("a line, not a clear signal");
+    assert!(!line.contains("nsec1qqqqqqqqqqleaked"), "got: {line}");
+    assert!(line.contains("[REDACTED]"), "got: {line}");
+}
+
+// ── proxy and PAT credentials ────────────────────────────────────────────────
+
+/// A proxy URL's password is a credential, but the proxy itself is diagnostic
+/// information: an install that fails behind a proxy is only debuggable if the
+/// record still says which proxy it went through. So the userinfo is scrubbed
+/// and the host is kept.
+#[test]
+fn test_proxy_userinfo_is_secret_but_the_proxy_host_is_not() {
+    let secrets = secret_values_from([(
+        "HTTPS_PROXY".to_string(),
+        "http://corpuser:hunter2pass@proxy.example:8080".to_string(),
+    )]);
+
+    assert_eq!(secrets, vec!["corpuser:hunter2pass"]);
+}
+
+/// A proxy with no credential contributes nothing — scrubbing a bare host would
+/// erase the proxy's name from every record while protecting nothing. A bare
+/// username is not a credential either, and scrubbing it would delete every
+/// occurrence of that word from the log.
+#[test]
+fn test_a_proxy_without_credentials_contributes_no_secret() {
+    let secrets = secret_values_from([
+        (
+            "HTTP_PROXY".to_string(),
+            "http://proxy.example:8080".to_string(),
+        ),
+        (
+            "ALL_PROXY".to_string(),
+            "socks5://10.0.0.1:1080".to_string(),
+        ),
+        (
+            "HTTPS_PROXY".to_string(),
+            "http://user@proxy.example:8080".to_string(),
+        ),
+    ]);
+
+    assert!(secrets.is_empty(), "got: {secrets:?}");
+}
+
+/// npm reads its own `npm_config_*` aliases in preference to the conventional
+/// proxy variables and prints the resolved value back, so a credential set only
+/// under an alias would otherwise never enter the scrub list. npm spells them
+/// in lowercase, so both cases have to classify.
+#[test]
+fn test_npm_proxy_aliases_are_classified_in_either_case() {
+    let secrets = secret_values_from([
+        (
+            "npm_config_proxy".to_string(),
+            "http://corpuser:lowerplain@proxy.example:8080".to_string(),
+        ),
+        (
+            "NPM_CONFIG_PROXY".to_string(),
+            "http://corpuser:upperplain@proxy.example:8080".to_string(),
+        ),
+        (
+            "npm_config_https_proxy".to_string(),
+            "http://corpuser:lowertls@proxy.example:8080".to_string(),
+        ),
+        (
+            "NPM_CONFIG_HTTPS_PROXY".to_string(),
+            "http://corpuser:uppertls@proxy.example:8080".to_string(),
+        ),
+    ]);
+
+    assert_eq!(
+        secrets,
+        vec![
+            "corpuser:lowerplain",
+            "corpuser:upperplain",
+            "corpuser:lowertls",
+            "corpuser:uppertls",
+        ]
+    );
+}
+
+/// The alias carries the same userinfo-only policy as the conventional names:
+/// a credential-less alias contributes nothing, so the proxy stays named in the
+/// record.
+#[test]
+fn test_an_npm_proxy_alias_without_credentials_contributes_no_secret() {
+    let secrets = secret_values_from([
+        (
+            "npm_config_proxy".to_string(),
+            "http://proxy.example:8080".to_string(),
+        ),
+        (
+            "NPM_CONFIG_HTTPS_PROXY".to_string(),
+            "http://user@proxy.example:8080".to_string(),
+        ),
+    ]);
+
+    assert!(secrets.is_empty(), "got: {secrets:?}");
+}
+
+/// The classifier and the reporter have to agree: an alias credential that
+/// classifies but never reaches the scrub list still leaks. This drives the
+/// reporter with exactly what the classifier produced for an alias, and asserts
+/// the log and the returned step both come back clean.
+#[test]
+fn test_an_npm_alias_credential_is_redacted_from_the_log_and_the_returned_step() {
+    let password = "hunter2pass";
+    let h = harness_with_secrets(secret_values_from([(
+        "npm_config_proxy".to_string(),
+        format!("http://corpuser:{password}@proxy.example:8080"),
+    )]));
+
+    let returned = h.reporter.record_attempt(
+        1,
+        InstallOutcome {
+            step: InstallStepResult {
+                stderr: format!(
+                    "npm ERR! proxy=http://corpuser:{password}@proxy.example:8080 tunneling failed"
+                ),
+                ..step("cli", false, "")
+            },
+            log_stdout: String::new(),
+            log_stderr: format!(
+                "npm config: proxy = http://corpuser:{password}@proxy.example:8080"
+            ),
+        },
+    );
+
+    let log = h.log_contents();
+    assert!(!log.contains(password), "log leaked the password: {log}");
+    assert!(
+        log.contains("proxy.example"),
+        "the proxy host is diagnostic and must survive: {log}"
+    );
+    assert!(
+        !returned.stderr.contains(password),
+        "the returned step leaked the password: {}",
+        returned.stderr
+    );
+}
+
+// ── npm's own credential settings ────────────────────────────────────────────
+
+/// npm accepts every one of its settings as an `npm_config_*` variable, so a
+/// registry client key, a basic-auth blob or a one-time password can arrive
+/// under a name that carries no marker. Their whole value is the credential —
+/// unlike a proxy, none of it is diagnostic — and npm spells them in lowercase.
+#[test]
+fn test_npm_credential_configs_are_secret_in_either_case() {
+    let secrets = secret_values_from([
+        (
+            "npm_config_key".to_string(),
+            "-----BEGIN PRIVATE KEY-----lowerkey".to_string(),
+        ),
+        (
+            "NPM_CONFIG_KEY".to_string(),
+            "-----BEGIN PRIVATE KEY-----upperkey".to_string(),
+        ),
+        ("npm_config__auth".to_string(), "bG93ZXJhdXRo".to_string()),
+        ("NPM_CONFIG__AUTH".to_string(), "dXBwZXJhdXRo".to_string()),
+        ("npm_config_otp".to_string(), "618243".to_string()),
+        ("NPM_CONFIG_OTP".to_string(), "907154".to_string()),
+    ]);
+
+    assert_eq!(
+        secrets,
+        vec![
+            "-----BEGIN PRIVATE KEY-----lowerkey",
+            "-----BEGIN PRIVATE KEY-----upperkey",
+            "bG93ZXJhdXRo",
+            "dXBwZXJhdXRo",
+            "618243",
+            "907154",
+        ]
+    );
+}
+
+/// An unset-but-exported credential is empty, and an empty needle would match
+/// everywhere. The name being exact does not make a blank value a secret.
+#[test]
+fn test_an_empty_npm_credential_config_contributes_no_secret() {
+    let secrets = secret_values_from([
+        ("NPM_CONFIG_KEY".to_string(), String::new()),
+        ("npm_config_otp".to_string(), String::new()),
+    ]);
+
+    assert!(secrets.is_empty(), "got: {secrets:?}");
+}
+
+/// A private registry's URL follows the proxy policy rather than the whole-value
+/// one: which registry an install talked to is exactly what a 401 or an ETIMEDOUT
+/// has to be read against, so only the userinfo is the secret.
+#[test]
+fn test_npm_registry_userinfo_is_secret_but_the_registry_host_is_not() {
+    let secrets = secret_values_from([(
+        "npm_config_registry".to_string(),
+        "https://builder:hunter2pass@registry.example/api/npm/".to_string(),
+    )]);
+
+    assert_eq!(secrets, vec!["builder:hunter2pass"]);
+}
+
+/// The public registry — and any private one reached with a token header rather
+/// than URL credentials — contributes nothing, so the registry stays named in
+/// the record.
+#[test]
+fn test_an_npm_registry_without_credentials_contributes_no_secret() {
+    let secrets = secret_values_from([
+        (
+            "npm_config_registry".to_string(),
+            "https://registry.npmjs.org/".to_string(),
+        ),
+        (
+            "NPM_CONFIG_REGISTRY".to_string(),
+            "https://builder@registry.example/api/npm/".to_string(),
+        ),
+    ]);
+
+    assert!(secrets.is_empty(), "got: {secrets:?}");
+}
+
+/// The credential settings are matched by exact name, never by a `KEY` or
+/// `AUTH` substring. Those occur throughout an ordinary environment on values
+/// that are paths, agent sockets and people's names, and scrubbing them would
+/// delete unrelated text from every record.
+#[test]
+fn test_key_and_auth_inside_a_variable_name_do_not_make_it_secret() {
+    let secrets = secret_values_from([
+        (
+            "SSH_AUTH_SOCK".to_string(),
+            "/tmp/ssh-agent.socket".to_string(),
+        ),
+        ("GIT_AUTHOR_NAME".to_string(), "Ada Lovelace".to_string()),
+        (
+            "KEYCHAIN".to_string(),
+            "/Users/dev/Library/login.keychain".to_string(),
+        ),
+        (
+            "NPM_CONFIG_KEYFILE".to_string(),
+            "/Users/dev/.npm/client.pem".to_string(),
+        ),
+    ]);
+
+    assert!(secrets.is_empty(), "got: {secrets:?}");
+}
+
+/// The wiring, not just the classification: npm prints its resolved config on an
+/// auth failure, so each of these has to be gone from the log and from the step
+/// the frontend renders. The one-time password is the interesting one — at six
+/// digits it is far shorter than any other secret here, and a value under four
+/// bytes is dropped by the shared redactor rather than scrubbed.
+#[test]
+fn test_npm_credential_configs_are_redacted_from_the_log_and_the_returned_step() {
+    let client_key = "-----BEGIN PRIVATE KEY-----MIIEvQIBADAN";
+    let auth = "YnVpbGRlcjpodW50ZXIycGFzcw==";
+    let otp = "618243";
+    let registry_password = "hunter2pass";
+    let h = harness_with_secrets(secret_values_from([
+        ("npm_config_key".to_string(), client_key.to_string()),
+        ("npm_config__auth".to_string(), auth.to_string()),
+        ("npm_config_otp".to_string(), otp.to_string()),
+        (
+            "npm_config_registry".to_string(),
+            format!("https://builder:{registry_password}@registry.example/api/npm/"),
+        ),
+    ]));
+
+    let returned = h.reporter.record_attempt(
+        1,
+        InstallOutcome {
+            step: InstallStepResult {
+                stderr: format!("npm ERR! 401 otp={otp} _auth={auth}"),
+                ..step("cli", false, "")
+            },
+            log_stdout: format!("npm config: key = {client_key}"),
+            log_stderr: format!(
+                "npm config: registry = https://builder:{registry_password}@registry.example/api/npm/"
+            ),
+        },
+    );
+
+    let log = h.log_contents();
+    for secret in [client_key, auth, otp, registry_password] {
+        assert!(!log.contains(secret), "log leaked {secret}: {log}");
+    }
+    assert!(
+        log.contains("registry.example"),
+        "the registry host is diagnostic and must survive: {log}"
+    );
+    assert!(
+        !returned.stderr.contains(otp) && !returned.stderr.contains(auth),
+        "the returned step leaked a credential: {}",
+        returned.stderr
+    );
+}
+
+/// `*_PATH` variables must not be mistaken for personal access tokens. A
+/// `contains("_PAT")` rule would match `PATH` itself and scrub every directory
+/// name out of the log, which is why the rule matches `_PAT` as a suffix.
+#[test]
+fn test_a_path_variable_is_not_treated_as_a_personal_access_token() {
+    let secrets = secret_values_from([
+        ("PATH".to_string(), "/usr/local/bin:/usr/bin".to_string()),
+        ("GOPATH".to_string(), "/home/user/go".to_string()),
+        (
+            "CARGO_HOME_PATH".to_string(),
+            "/home/user/.cargo".to_string(),
+        ),
+    ]);
+
+    assert!(secrets.is_empty(), "got: {secrets:?}");
+}
+
+/// Variables named as personal access tokens are secret by name, whatever shape
+/// their value has.
+#[test]
+fn test_pat_named_variables_are_secret() {
+    let secrets = secret_values_from([
+        (
+            "GITHUB_PAT".to_string(),
+            "ghp_abcdefghij0123456789".to_string(),
+        ),
+        (
+            "GH_PAT".to_string(),
+            "github_pat_abcdefghij0123".to_string(),
+        ),
+    ]);
+
+    assert_eq!(secrets.len(), 2, "got: {secrets:?}");
+}
+
+/// The whole point of the widening: a proxy password and a PAT that the
+/// installer echoed reach neither the log nor the live line.
+///
+/// Both are checked through the real reporter rather than the classifier, so
+/// this covers the wiring — a classifier that recognises a secret the reporter
+/// never consults would still leak.
+#[test]
+fn test_proxy_and_pat_credentials_are_redacted_from_the_log_and_the_live_line() {
+    let proxy_password = "hunter2pass";
+    let pat = "ghp_abcdefghij0123456789";
+    // The classifier's own tests cover recognising these under their real
+    // variable names; injecting the resulting secrets here keeps a live
+    // `HTTPS_PROXY` out of the process the rest of the suite shares.
+    let h = harness_with_secrets(vec![format!("corpuser:{proxy_password}"), pat.to_string()]);
+
+    h.reporter.record_attempt(
+        1,
+        outcome(
+            "cli",
+            false,
+            &format!(
+                "npm ERR! proxy=http://corpuser:{proxy_password}@proxy.example authToken={pat}"
+            ),
+        ),
+    );
+    let observer = h.reporter.line_observer().expect("an observer");
+    observer(&format!("cloning https://{pat}@github.com/org/repo"));
+
+    let log = h.log_contents();
+    assert!(
+        !log.contains(proxy_password),
+        "log leaked the proxy password: {log}"
+    );
+    assert!(!log.contains(pat), "log leaked the PAT: {log}");
+    assert!(
+        log.contains("proxy.example"),
+        "the proxy host is diagnostic and must survive: {log}"
+    );
+
+    let line = h.lines().into_iter().flatten().next().expect("a live line");
+    assert!(!line.contains(pat), "live line leaked the PAT: {line}");
+    assert!(line.contains("[REDACTED]"), "got: {line}");
+}
+
+/// The third surface: the step returned to the frontend. `getInstallErrorMessage`
+/// renders the failing step's stderr verbatim, so a secret that the log and the
+/// live line both scrub would still reach the user through the error dialog.
+#[test]
+fn test_a_returned_step_is_redacted_before_the_frontend_renders_it() {
+    let pat = "ghp_abcdefghij0123456789";
+    let h = harness_with_secrets(vec![pat.to_string()]);
+
+    let returned = h.reporter.record_attempt(
+        1,
+        InstallOutcome {
+            step: InstallStepResult {
+                stdout: format!("configuring remote with {pat}"),
+                stderr: format!("fatal: authentication failed for token {pat}"),
+                hint: Some(format!("check that {pat} has the repo scope")),
+                ..step("cli", false, "")
+            },
+            log_stdout: String::new(),
+            log_stderr: String::new(),
+        },
+    );
+
+    assert!(!returned.stdout.contains(pat), "got: {}", returned.stdout);
+    assert!(!returned.stderr.contains(pat), "got: {}", returned.stderr);
+    let hint = returned.hint.expect("a hint");
+    assert!(!hint.contains(pat), "got: {hint}");
+}
+
+/// A synthesized step reaches the frontend through the other funnel, and needs
+/// the same scrubbing — the managed-node prerequisite failures are built this
+/// way and carry whatever the underlying command printed.
+#[test]
+fn test_a_synthesized_step_is_redacted_before_it_reaches_the_caller() {
+    let pat = "ghp_abcdefghij0123456789";
+    let h = harness_with_secrets(vec![pat.to_string()]);
+    let mut steps = Vec::new();
+
+    h.reporter.record_step(
+        &mut steps,
+        InstallStepResult {
+            stderr: format!("npm ERR! 401 with {pat}"),
+            ..step("adapter", false, "")
+        },
+    );
+
+    assert_eq!(steps.len(), 1);
+    assert!(!steps[0].stderr.contains(pat), "got: {}", steps[0].stderr);
+    assert!(
+        steps[0].stderr.contains("[REDACTED]"),
+        "got: {}",
+        steps[0].stderr
+    );
+}
diff --git a/desktop/src-tauri/src/commands/agent_discovery/install_report_test_support.rs b/desktop/src-tauri/src/commands/agent_discovery/install_report_test_support.rs
new file mode 100644
index 0000000000..17b2789560
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_discovery/install_report_test_support.rs
@@ -0,0 +1,106 @@
+//! Shared harness for the install-report test modules.
+//!
+//! The tests are split by concern — redaction in
+//! [`super::install_report_redaction_tests`], everything else in
+//! [`super::install_report_tests`] — and both drive the reporter through the
+//! same harness, so it lives here rather than in either of them.
+
+use super::*;
+use std::sync::Mutex;
+
+/// Stands in for the real `app.package_info().version`, which needs a Tauri app.
+pub(crate) const TEST_APP_VERSION: &str = "9.9.9";
+
+/// A reporter with a started log session in a temp dir, and the emitted events
+/// captured.
+pub(crate) struct Harness {
+    /// Kept alive so the log outlives the harness; a test that reuses the
+    /// directory for a second run takes it.
+    pub(crate) _dir: tempfile::TempDir,
+    pub(crate) log: PathBuf,
+    pub(crate) reporter: InstallReporter,
+    pub(crate) events: Arc<Mutex<Vec<InstallOutputEvent>>>,
+}
+
+pub(crate) fn harness() -> Harness {
+    harness_at(None)
+}
+
+/// A harness whose log lives in `dir`, or in a fresh temp dir when `dir` is
+/// `None`. Passing a directory lets a test seed a previous run's file first.
+pub(crate) fn harness_at(dir: Option<tempfile::TempDir>) -> Harness {
+    harness_inner(dir, None)
+}
+
+/// A harness whose reporter scrubs exactly `secrets`, so a proxy or PAT
+/// credential can be asserted without exporting it into the process.
+pub(crate) fn harness_with_secrets(secrets: Vec<String>) -> Harness {
+    harness_inner(None, Some(secrets))
+}
+
+fn harness_inner(dir: Option<tempfile::TempDir>, secrets: Option<Vec<String>>) -> Harness {
+    let dir = dir.unwrap_or_else(|| tempfile::tempdir().expect("tempdir"));
+    let log = dir.path().join("install-goose.log");
+    let events: Arc<Mutex<Vec<InstallOutputEvent>>> = Arc::new(Mutex::new(Vec::new()));
+    let emit: EmitEvent = {
+        let events = Arc::clone(&events);
+        Arc::new(move |event| events.lock().unwrap().push(event))
+    };
+    let started = InstallLog::start(&log, "goose", TEST_APP_VERSION);
+    Harness {
+        reporter: match secrets {
+            Some(secrets) => InstallReporter::with_secrets("goose", started, Some(emit), secrets),
+            None => InstallReporter::new("goose", started, Some(emit)),
+        },
+        _dir: dir,
+        log,
+        events,
+    }
+}
+
+/// A reporter with no log file and nothing listening — the degraded shape.
+pub(crate) fn silent_reporter() -> InstallReporter {
+    InstallReporter::new("goose", None, None)
+}
+
+pub(crate) fn step(name: &str, success: bool, stderr: &str) -> InstallStepResult {
+    InstallStepResult {
+        step: name.to_string(),
+        command: "curl … | bash".to_string(),
+        success,
+        stdout: String::new(),
+        stderr: stderr.to_string(),
+        exit_code: Some(if success { 0 } else { 1 }),
+        hint: None,
+    }
+}
+
+/// An executed attempt whose log copy differs from the UI copy — the real shape,
+/// since the two views are capped differently.
+pub(crate) fn outcome(name: &str, success: bool, log_stdout: &str) -> InstallOutcome {
+    InstallOutcome {
+        step: step(name, success, ""),
+        log_stdout: log_stdout.to_string(),
+        log_stderr: String::new(),
+    }
+}
+
+impl Harness {
+    pub(crate) fn log_contents(&self) -> String {
+        std::fs::read_to_string(&self.log).unwrap_or_default()
+    }
+
+    /// The emitted lines in order, with a clear signal rendered as `None`.
+    pub(crate) fn lines(&self) -> Vec<Option<String>> {
+        self.events
+            .lock()
+            .unwrap()
+            .iter()
+            .map(|e| e.line.clone())
+            .collect()
+    }
+
+    pub(crate) fn events(&self) -> Vec<InstallOutputEvent> {
+        self.events.lock().unwrap().clone()
+    }
+}
diff --git a/desktop/src-tauri/src/commands/agent_discovery/install_report_tests.rs b/desktop/src-tauri/src/commands/agent_discovery/install_report_tests.rs
new file mode 100644
index 0000000000..c286b618b6
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_discovery/install_report_tests.rs
@@ -0,0 +1,564 @@
+use super::test_support::*;
+use super::*;
+use crate::commands::agent_discovery::install_capture::{drain_into, Capture};
+
+// ── the log records history the UI does not keep ─────────────────────────────
+
+/// Every attempt is recorded, not just the one the UI surfaces. Reproducing an
+/// install failure means seeing whether attempts 1 and 2 failed the same way.
+#[test]
+fn test_log_records_every_attempt_not_only_the_last() {
+    let h = harness();
+
+    h.reporter
+        .record_attempt(1, outcome("cli", false, "attempt-one-output"));
+    h.reporter
+        .record_attempt(2, outcome("cli", false, "attempt-two-output"));
+
+    let log = h.log_contents();
+    assert!(log.contains("attempt-one-output"), "got: {log}");
+    assert!(log.contains("attempt-two-output"), "got: {log}");
+    assert!(
+        log.contains("attempt=1") && log.contains("attempt=2"),
+        "got: {log}"
+    );
+}
+
+/// A first attempt that printed a huge amount must not push later records out of
+/// the file. Records are capped individually by the log-scale capture that
+/// produced them, so the run's total is bounded by steps × attempts × cap rather
+/// than by one runaway attempt.
+///
+/// The flood goes through a real [`Capture`] rather than straight into the
+/// record, so this exercises the cap that actually bounds a record.
+#[test]
+fn test_first_attempt_overflow_does_not_erase_later_records() {
+    let h = harness();
+    // Through the real drain, so the record is bounded by the cap that bounds a
+    // production record rather than by a string this test chose.
+    let capture = Capture::new();
+    drain_into(vec![b'F'; 4 * 1024 * 1024].as_slice(), &capture, None);
+
+    h.reporter
+        .record_attempt(1, outcome("cli", false, &capture.log()));
+    h.reporter
+        .record_attempt(2, outcome("cli", false, "second-attempt-detail"));
+    h.reporter.record_step(
+        &mut Vec::new(),
+        step("verify", false, "verification-detail"),
+    );
+
+    let log = h.log_contents();
+    assert!(
+        log.contains("bytes omitted at cap"),
+        "the flooded record must be marked as cut"
+    );
+    assert!(
+        log.contains("second-attempt-detail"),
+        "a later attempt must survive an earlier flood"
+    );
+    assert!(
+        log.contains("verification-detail"),
+        "the synthesized step explaining the failure must survive too"
+    );
+    assert!(
+        log.len() < 4 * 1024 * 1024,
+        "4MiB of first-attempt output must not reach the file, got {} bytes",
+        log.len()
+    );
+}
+
+/// A step Buzz synthesizes — a failed prerequisite, or post-install
+/// verification — reaches the log as well as the UI. `record_step` is the only
+/// path that guarantees this, which is why callers use it instead of
+/// `steps.push`.
+#[test]
+fn test_recording_a_synthesized_step_logs_it_and_keeps_it_for_the_ui() {
+    let h = harness();
+    let mut steps = Vec::new();
+
+    h.reporter
+        .record_step(&mut steps, step("verify", false, "still-not-usable"));
+
+    assert_eq!(steps.len(), 1, "the UI must still receive the step");
+    assert!(h.log_contents().contains("still-not-usable"));
+}
+
+// ── one file per run ─────────────────────────────────────────────────────────
+
+/// A run opens with a header naming the runtime and the environment the run
+/// happened in, so a file holding one run of several steps is identifiable as
+/// that run rather than a stream of records — and a failure report says which
+/// app version and OS produced it without a second round trip to the user.
+#[test]
+fn test_a_run_opens_with_a_header_naming_the_runtime_app_version_and_os() {
+    let h = harness();
+    let log = h.log_contents();
+
+    assert!(
+        log.starts_with(&format!(
+            "=== install run runtime=goose app={TEST_APP_VERSION} os={} started=",
+            std::env::consts::OS
+        )),
+        "got: {log}"
+    );
+}
+
+/// A new run does not append to the previous run's file: it starts a fresh one
+/// and keeps the previous as `.1`. Reading a log has to mean reading one run —
+/// records accumulated across runs are indistinguishable from retries within
+/// one.
+#[test]
+fn test_a_new_run_starts_a_fresh_file_and_keeps_the_previous_as_dot_one() {
+    let first = harness();
+    first
+        .reporter
+        .record_attempt(1, outcome("cli", false, "previous-run-output"));
+    let previous = first.log.clone();
+    let dir = first._dir;
+    drop(first.reporter);
+
+    let second = harness_at(Some(dir));
+    second
+        .reporter
+        .record_attempt(1, outcome("cli", false, "current-run-output"));
+
+    let log = second.log_contents();
+    assert!(log.contains("current-run-output"), "got: {log}");
+    assert!(
+        !log.contains("previous-run-output"),
+        "the new run's file must not carry the previous run's records: {log}"
+    );
+    let rotated = std::fs::read_to_string(previous.with_extension("log.1")).expect("read .1");
+    assert!(
+        rotated.contains("previous-run-output"),
+        "the previous run must remain readable as .1: {rotated}"
+    );
+}
+
+/// Each executed attempt records how long it ran. A 15-minute ceiling is only
+/// diagnosable if the file says which attempt consumed the time.
+#[test]
+fn test_an_executed_attempt_records_its_own_duration() {
+    let h = harness();
+
+    h.reporter.start_attempt();
+    h.reporter.record_attempt(1, outcome("cli", true, "done"));
+    h.reporter
+        .record_step(&mut Vec::new(), step("verify", true, ""));
+
+    let log = h.log_contents();
+    assert!(
+        log.contains("attempt=1") && log.contains("elapsed=0."),
+        "an executed attempt must carry its duration: {log}"
+    );
+    assert!(
+        log.contains("attempt=- ") && log.contains("elapsed=-"),
+        "a synthesized step never ran, so it has no duration: {log}"
+    );
+}
+
+// ── the log pointer ──────────────────────────────────────────────────────────
+
+/// The path is available as soon as the run's session opens, because the file
+/// exists from that moment — the header is already in it. A failure before any
+/// step ran still points the user at a real file.
+#[test]
+fn test_log_path_is_available_from_the_start_of_the_run() {
+    let h = harness();
+
+    assert_eq!(h.reporter.log_path(), Some(h.log.display().to_string()));
+}
+
+/// A reporter with no log — an unresolvable app-data directory — records
+/// nothing and reports no path, but must not panic or fail the install.
+#[test]
+fn test_reporter_without_a_log_records_nothing_and_reports_no_path() {
+    let reporter = silent_reporter();
+    let mut steps = Vec::new();
+
+    reporter.start_attempt();
+    reporter.record_attempt(1, outcome("cli", false, "output"));
+    reporter.record_step(&mut steps, step("verify", false, "detail"));
+
+    assert_eq!(reporter.log_path(), None);
+    assert_eq!(steps.len(), 1, "the UI path is unaffected by a missing log");
+}
+
+/// A log path inside a directory that no longer exists cannot open a session, so
+/// the run degrades to no log rather than failing.
+#[test]
+fn test_an_unopenable_log_degrades_to_no_log() {
+    let path = PathBuf::from("/nonexistent-dir-for-test/install-goose.log");
+
+    assert!(InstallLog::start(&path, "goose", TEST_APP_VERSION).is_none());
+}
+
+// ── live output line ─────────────────────────────────────────────────────────
+
+/// Lines carry an install-wide monotonic sequence number, so the UI can order
+/// them across steps and attempts — which a per-step retry number cannot do.
+#[test]
+fn test_emitted_lines_carry_their_runtime_and_a_monotonic_sequence() {
+    let h = harness();
+
+    let observer = h.reporter.line_observer().expect("an observer");
+    observer("downloading");
+    h.reporter.start_attempt();
+
+    let events = h.events();
+    assert_eq!(events.len(), 2);
+    assert!(events.iter().all(|e| e.runtime_id == "goose"));
+    assert_eq!(events[0].line.as_deref(), Some("downloading"));
+    assert_eq!(events[0].seq, 0);
+    assert_eq!(
+        events[1].seq, 1,
+        "the clear signal takes the next sequence number, so it cannot be \
+         mistaken for a stale event"
+    );
+}
+
+/// Starting an attempt clears the display first: the previous attempt's last
+/// line is typically the failure that caused the retry, and leaving it under the
+/// spinner through the backoff shows the user the past as if it were current.
+#[test]
+fn test_starting_an_attempt_clears_the_displayed_line() {
+    let h = harness();
+    let observer = h.reporter.line_observer().expect("an observer");
+    observer("download failed");
+
+    h.reporter.start_attempt();
+
+    assert_eq!(
+        h.lines(),
+        vec![Some("download failed".to_string()), None],
+        "the attempt boundary must emit a clear"
+    );
+}
+
+/// The clear is not rate-limited, and it reopens the window: a new attempt's
+/// first line goes out immediately even if it arrives inside the previous
+/// attempt's window. This is the case the throttle used to swallow entirely.
+#[test]
+fn test_a_new_attempts_first_line_is_emitted_even_inside_the_previous_window() {
+    let h = harness();
+    let observer = h.reporter.line_observer().expect("an observer");
+    observer("attempt one failed");
+
+    // No wait: the previous line was emitted microseconds ago, so this is well
+    // inside the 250ms window.
+    h.reporter.start_attempt();
+    observer("attempt two starting");
+
+    assert_eq!(
+        h.lines(),
+        vec![
+            Some("attempt one failed".to_string()),
+            None,
+            Some("attempt two starting".to_string()),
+        ]
+    );
+}
+
+/// A burst inside the window coalesces to one event, and the line it emits is
+/// the *newest* — the display shows current progress, not the line that happened
+/// to arrive when the window opened.
+#[test]
+fn test_a_burst_coalesces_to_the_newest_line_not_the_first() {
+    let h = harness();
+    let observer = h.reporter.line_observer().expect("an observer");
+
+    observer("one");
+    observer("two");
+    observer("three");
+    // Ends the attempt, which is when a held line is known to be the last.
+    h.reporter.record_attempt(1, outcome("cli", true, "done"));
+
+    assert_eq!(
+        h.lines(),
+        vec![Some("one".to_string()), Some("three".to_string())],
+        "the held line must be the newest, and it must not be lost"
+    );
+}
+
+/// The throttle is per install, not per stream: stdout and stderr of one attempt
+/// share one window, so an install printing on both does not double the event
+/// rate.
+#[test]
+fn test_both_streams_of_one_attempt_share_the_rate_window() {
+    let h = harness();
+    let stdout = h.reporter.line_observer().expect("an observer");
+    let stderr = h.reporter.line_observer().expect("an observer");
+
+    stdout("progress");
+    stderr("warning");
+    h.reporter.record_attempt(1, outcome("cli", true, "done"));
+
+    assert_eq!(
+        h.lines(),
+        vec![Some("progress".to_string()), Some("warning".to_string())],
+        "the second stream's line is held, not emitted immediately, and not lost"
+    );
+}
+
+/// Nothing listening means no observer at all, so the drain skips line
+/// reassembly entirely rather than doing the work and discarding it.
+#[test]
+fn test_no_observer_when_nothing_is_listening() {
+    assert!(silent_reporter().line_observer().is_none());
+}
+
+// ── late-drain deactivation ──────────────────────────────────────────────────
+
+/// After the reporter is dropped (run settled), a drain thread that still holds
+/// a cloned observer must not be able to emit. The lifecycle lock is shared by
+/// reference with every `line_observer` clone, so taking the exclusive write
+/// lock in `Drop` — which waits out any in-flight read guards — ensures no
+/// late event can reach the listener.
+///
+/// The test resets the throttle via `start_attempt` before the late emit, so
+/// the late line would be emitted unconditionally without the lifecycle lock.
+#[test]
+fn test_a_detached_observer_cannot_emit_after_the_reporter_is_dropped() {
+    let h = harness();
+
+    // Simulate a drain thread: `line_observer` clones `Live` (owned, not
+    // borrowed), so the closure outlives the reporter.
+    let observer = h.reporter.line_observer().expect("an observer");
+    observer("before-settle");
+
+    assert_eq!(
+        h.lines(),
+        vec![Some("before-settle".to_string())],
+        "a live observer must emit before the reporter drops"
+    );
+
+    // Open a fresh throttle window so the next offer would emit immediately —
+    // simulating the drain arriving after the 250ms rate window closed.
+    h.reporter.start_attempt();
+    let events = Arc::clone(&h.events);
+
+    // Drop the reporter — takes the exclusive lifecycle write lock, waits for
+    // any in-flight publications, then deactivates.
+    drop(h);
+
+    // A late offer after drop must be blocked by the deactivated lifecycle.
+    observer("late-drain-after-settle");
+
+    let lines: Vec<Option<String>> = events
+        .lock()
+        .unwrap()
+        .iter()
+        .map(|e| e.line.clone())
+        .collect();
+    assert_eq!(
+        lines,
+        // before-settle + the clear from start_attempt, no late line
+        vec![Some("before-settle".to_string()), None],
+        "a detached observer must not emit after the reporter is dropped"
+    );
+}
+
+/// Deterministic concurrency pin: proves that reporter deactivation cannot
+/// complete while a drain thread is in-flight between admission and publication.
+///
+/// The lifecycle `RwLock` enforces this: drain threads hold a shared read guard
+/// for the entire (check → emit) span, so `InstallReporter::drop`'s write lock
+/// blocks until every admitted publication finishes.
+///
+/// **How this test fails on the old atomic shape** (`dc6421ac4`): on that shape,
+/// `offer` loads `active` once as a plain atomic read and then calls `publish`
+/// independently. There is no shared lock, so `drop` (an atomic store) can
+/// complete while the thread is between the load and the emit — the test
+/// exposes this by asserting the write lock CANNOT be acquired while a reader
+/// holds a read guard. On the atomic shape the `lifecycle` field does not exist,
+/// so the entire serialisation contract is absent and the pin fails.
+#[test]
+fn test_deactivation_blocks_until_in_flight_publication_completes() {
+    // Build a reporter and grab a Live clone that represents a drain thread.
+    let h = harness();
+    let live_clone = {
+        // Extract the `Live` from a `line_observer` closure by temporarily
+        // building a second observer and using the lifecycle Arc directly.
+        h.reporter.line_observer().expect("observer");
+        // Clone the inner lifecycle from the reporter's `Live` via a
+        // white-box path: the test module is a child of install_report and
+        // can access private fields.
+        h.reporter
+            .live
+            .as_ref()
+            .expect("live exists")
+            .lifecycle
+            .clone()
+    };
+
+    // Phase 1: acquire the shared read guard (admission).
+    let guard = live_clone.read().expect("lifecycle read");
+    assert!(*guard, "lifecycle must be active at admission");
+
+    // Phase 2: while the read guard is held, a write lock must be blocked.
+    // This is the core serialisation invariant: `Drop` cannot complete until
+    // every admitted reader releases its guard.
+    assert!(
+        live_clone.try_write().is_err(),
+        "a write lock must not be acquirable while a read guard is held — \
+         Drop must block while a publication is in-flight"
+    );
+
+    // Phase 3: release the read guard (publication completed).
+    drop(guard);
+
+    // Phase 4: write lock is now available, and Drop can set active=false.
+    let mut write = live_clone.write().expect("lifecycle write");
+    *write = false;
+    drop(write);
+
+    // Phase 5: a new reader after deactivation sees active=false and returns.
+    let guard2 = live_clone.read().expect("lifecycle read");
+    assert!(
+        !*guard2,
+        "lifecycle must be inactive after deactivation — new admissions rejected"
+    );
+}
+
+/// Shared-consumer assertion: drive a potential late run-1 event AND run-2's
+/// events through the same `nextInstallOutputLine`-equivalent reducer and assert
+/// that run 2's output replaces — not revives — any stale run-1 state.
+///
+/// The frontend reduces events into a single consumer that resets to `null`
+/// when `isInstalling` goes false (i.e., when the run settles).  This test
+/// models that reset and verifies the full cross-run contract:
+///
+/// 1. Run 1 emits normally; the late drain is silenced by the lifecycle lock
+///    (no event with a high run-1 `seq` ever reaches the shared sink).
+/// 2. At run-1 settlement the consumer resets to `null`, exactly as the
+///    frontend hook does when `isInstalling` becomes false.
+/// 3. Run 2 starts, emits its `seq=0` clear and first line.  With a null-state
+///    consumer the reducer accepts both immediately — even if a late run-1
+///    event HAD arrived (it didn't), the reset would have cleared its seq.
+///
+/// **Why this test fails on the old atomic shape**: without the lifecycle lock,
+/// `obs1("late-run-one-drain")` emits a high-seq run-1 event into the shared
+/// sink.  That event arrives AFTER the consumer reset (its seq is accepted from
+/// a null state), leaving `{ seq: N, line: "late-run-one-drain" }` in the
+/// consumer.  Run 2 then emits `seq=0` and `seq=1`, both ≤ N, so they are
+/// rejected and the final state stays on run 1's output.
+#[test]
+fn test_run2_output_replaces_stale_run1_state_through_shared_consumer() {
+    // One shared event sink for all events from both runs, simulating the
+    // permanent frontend listener that receives all `acp-install-output` events.
+    let all_events: Arc<Mutex<Vec<InstallOutputEvent>>> = Arc::new(Mutex::new(Vec::new()));
+    // Track where run 1 settles so the consumer reset can be applied at the
+    // correct boundary in the fold below.
+    let run1_settle_len: Arc<Mutex<usize>> = Arc::new(Mutex::new(0));
+    let runtime_id = "goose";
+
+    // ── Run 1 ──────────────────────────────────────────────────────────────
+    let dir1 = tempfile::tempdir().expect("tempdir");
+    let log1 = dir1.path().join("install-goose.log");
+    let emit1: EmitEvent = {
+        let sink = Arc::clone(&all_events);
+        Arc::new(move |event| sink.lock().unwrap().push(event))
+    };
+    let reporter1 = InstallReporter::new(
+        runtime_id,
+        InstallLog::start(&log1, runtime_id, "1.0.0"),
+        Some(emit1),
+    );
+
+    reporter1.start_attempt();
+    let obs1 = reporter1.line_observer().expect("observer");
+    obs1("run-one-output");
+    reporter1.record_attempt(1, outcome("cli", true, "done"));
+
+    // Drop reporter1 — deactivates obs1 via the exclusive lifecycle write lock,
+    // which blocks until any in-flight read guard (publication) has released.
+    drop(reporter1);
+
+    // Record the sink length at settlement — this is the point where the
+    // frontend resets its consumer state to null (isInstalling = false).
+    *run1_settle_len.lock().unwrap() = all_events.lock().unwrap().len();
+
+    // A late drain from run 1 arrives after settlement.  With the lifecycle
+    // lock this is silenced.  Without the lock (old atomic shape) it would
+    // reach the sink with a high seq, poisoning the null-reset consumer before
+    // run 2 can emit its restarted seq=0.
+    // Reset the throttle so the offer would emit unconditionally if the lock
+    // were absent — this makes the mutation meaningful.
+    {
+        // We need a fresh throttle window.  Simulate by directly restarting
+        // via a new reporter to touch the shared Live (not possible after drop),
+        // so instead just call offer — the throttle holds the last emit time
+        // from flush_pending, which was microseconds ago.  Give the window time
+        // to expire so the offer fires immediately on the old atomic shape.
+        std::thread::sleep(Duration::from_millis(300));
+    }
+    obs1("late-run-one-drain");
+
+    // ── Run 2 ──────────────────────────────────────────────────────────────
+    let dir2 = tempfile::tempdir().expect("tempdir");
+    let log2 = dir2.path().join("install-goose.log");
+    let emit2: EmitEvent = {
+        let sink = Arc::clone(&all_events);
+        Arc::new(move |event| sink.lock().unwrap().push(event))
+    };
+    let reporter2 = InstallReporter::new(
+        runtime_id,
+        InstallLog::start(&log2, runtime_id, "1.0.0"),
+        Some(emit2),
+    );
+
+    reporter2.start_attempt();
+    let obs2 = reporter2.line_observer().expect("observer");
+    obs2("run-two-first-line");
+    reporter2.record_attempt(1, outcome("cli", true, "done"));
+
+    // ── Shared-consumer fold ────────────────────────────────────────────────
+    // Fold all emitted events through the nextInstallOutputLine reducer logic.
+    // At the run-1 settlement boundary, reset consumer to null — exactly as
+    // the frontend hook does when isInstalling becomes false.
+    struct State {
+        seq: u64,
+        line: Option<String>,
+    }
+    let settle_at = *run1_settle_len.lock().unwrap();
+    let events = all_events.lock().unwrap().clone();
+    let mut consumer: Option<State> = None;
+    for (i, event) in events.iter().enumerate() {
+        // Simulate frontend reset at run-1 settlement boundary.
+        if i == settle_at {
+            consumer = None;
+        }
+        if event.runtime_id != runtime_id {
+            continue;
+        }
+        if let Some(ref c) = consumer {
+            if event.seq <= c.seq {
+                continue; // reject stale / out-of-order
+            }
+        }
+        consumer = Some(State {
+            seq: event.seq,
+            line: event.line.clone(),
+        });
+    }
+
+    // The final consumer state must be run 2's first line.
+    //
+    // With the lifecycle lock: obs1("late-run-one-drain") emits nothing,
+    // so after the null reset only run-2 events arrive — run 2 wins cleanly.
+    //
+    // Without the lifecycle lock (old atomic shape): obs1 emits the late line
+    // with a high seq into the already-reset (null) consumer, consumer becomes
+    // { seq: N, line: "late-run-one-drain" }.  Run 2's seq=0/1 are both ≤ N
+    // and are rejected, leaving the final state on run 1's stale output.
+    let final_line = consumer
+        .as_ref()
+        .and_then(|s| s.line.as_deref())
+        .unwrap_or("<none>");
+    assert_eq!(
+        final_line, "run-two-first-line",
+        "run 2 must replace — not revive — stale run-1 state through the shared consumer; \
+         got: {final_line:?}"
+    );
+}
diff --git a/desktop/src-tauri/src/commands/agent_discovery/post_install_verification.rs b/desktop/src-tauri/src/commands/agent_discovery/post_install_verification.rs
index 3155104b56..535d4c9ecb 100644
--- a/desktop/src-tauri/src/commands/agent_discovery/post_install_verification.rs
+++ b/desktop/src-tauri/src/commands/agent_discovery/post_install_verification.rs
@@ -1,13 +1,19 @@
 use crate::managed_agents::{AcpAvailabilityStatus, InstallStepResult};
 
-pub(super) fn run(runtime_id: &str, steps: &mut Vec<InstallStepResult>) {
+use super::install_report::InstallReporter;
+
+pub(super) fn run(
+    runtime_id: &str,
+    steps: &mut Vec<InstallStepResult>,
+    reporter: &InstallReporter,
+) {
     // Observe PATH changes and binaries added after Buzz launched.
     crate::managed_agents::refresh_login_shell_path();
     crate::managed_agents::clear_resolve_cache();
 
     let availability = crate::managed_agents::discover_acp_runtime_availability(runtime_id);
     if let Some(failure) = failure(runtime_id, availability) {
-        steps.push(failure);
+        reporter.record_step(steps, failure);
     }
 }
 
diff --git a/desktop/src-tauri/src/commands/agent_models.rs b/desktop/src-tauri/src/commands/agent_models.rs
index ca1fe9bdf6..7ce03b140b 100644
--- a/desktop/src-tauri/src/commands/agent_models.rs
+++ b/desktop/src-tauri/src/commands/agent_models.rs
@@ -99,6 +99,17 @@ pub async fn get_agent_models(
     // so a build-provided provider still gets live discovery.
     let effective_provider =
         effective_discovery_provider(saved_provider.as_deref(), provider_env_var, &merged_env);
+    if let Some(models) = discover_openrouter_models(
+        &state.http_client,
+        &effective_provider,
+        &merged_env,
+        persisted_model.clone(),
+    )
+    .await?
+    {
+        return Ok(models);
+    }
+
     if let Some(models) = discover_openai_compatible_models(
         &state.http_client,
         &effective_provider,
@@ -154,69 +165,11 @@ fn model_discovery_error(pubkey: &str, error: &str) -> String {
     )
 }
 
-/// Everything `get_agent_models` needs from the record + context, resolved in
-/// one pure step so the linked-agent regression test can bind the exact values
-/// the command consumes.
-#[derive(Debug, PartialEq, Eq)]
-struct AgentModelDiscoveryConfig {
-    /// Effective harness command (descriptor-resolved), for `resolve_command`.
-    command: String,
-    /// Effective harness args (descriptor-resolved).
-    args: Vec<String>,
-    /// Model from the authoritative resolver spawn uses — linked instances
-    /// read their definition, never stale `record.model` bytes.
-    model: Option<String>,
-    /// Provider from the same authoritative resolver — never stale
-    /// `record.provider` bytes for linked instances.
-    provider: Option<String>,
-    /// The runtime's provider env var (e.g. `GOOSE_PROVIDER`), so discovery
-    /// can recover the provider from the env when the resolver yields none.
-    /// `None` for runtimes that do not take a provider, or an unknown command.
-    provider_env_var: Option<&'static str>,
-    /// The descriptor's fully layered env (definition/persona/global/agent).
-    env: BTreeMap<String, String>,
-}
-
-/// Resolve the model-discovery config for a saved agent — the descriptor-backed
-/// successor to the old `saved_agent_model_discovery_config`.
-///
-/// Command/args/env come from `resolve_effective_harness_descriptor` (the same
-/// resolver as `spawn_agent_child`); model/provider come from
-/// `resolve_effective_model_provider` (#1968's definition-authoritative
-/// contract) — linked instances read their definition, never a stale
-/// materialized `record.model`/`record.provider`, so discovery cannot query a
-/// provider this agent will not actually launch with. Definition-less
-/// instances keep their own record values, matching spawn's
-/// `resolve_definition_less` arm. When the resolver yields no provider,
-/// `effective_discovery_provider` recovers the provider the agent will
-/// actually launch with from the runtime's own provider env var, read out of
-/// the descriptor env (which already layers definition/persona/global values
-/// the same way spawn does).
-///
-/// Returns `Err("DANGLING_HARNESS_ID:<id>")` from the descriptor resolver when
-/// the harness id no longer exists; the caller routes it through
-/// `model_discovery_error`.
-fn agent_model_discovery_config(
-    record: &crate::managed_agents::ManagedAgentRecord,
-    personas: &[crate::managed_agents::AgentDefinition],
-    global: &crate::managed_agents::GlobalAgentConfig,
-) -> Result<AgentModelDiscoveryConfig, String> {
-    let descriptor =
-        crate::managed_agents::resolve_effective_harness_descriptor(record, personas, global)?;
-    let (model, provider) =
-        crate::managed_agents::resolve_effective_model_provider(record, personas, global);
-    let provider_env_var =
-        known_acp_runtime(&descriptor.command).and_then(|meta| meta.provider_env_var);
-
-    Ok(AgentModelDiscoveryConfig {
-        command: descriptor.command,
-        args: descriptor.args,
-        model,
-        provider,
-        provider_env_var,
-        env: descriptor.env,
-    })
-}
+#[path = "agent_models_discovery_config.rs"]
+mod discovery_config;
+use discovery_config::{
+    agent_model_discovery_config, draft_agent_model_discovery_env, AgentModelDiscoveryConfig,
+};
 
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
@@ -269,31 +222,12 @@ pub async fn discover_agent_models(
         .unwrap_or_else(|| agent_command.to_string());
 
     let runtime_meta = known_acp_runtime(agent_command);
-    let mut derived_env = BTreeMap::new();
-    if let Some(meta) = runtime_meta {
-        let provider = input
-            .provider
-            .as_deref()
-            .map(str::trim)
-            .filter(|value| !value.is_empty());
-        if !meta.provider_locked {
-            if let (Some(env_key), Some(provider)) = (meta.provider_env_var, provider) {
-                derived_env.insert(env_key.to_string(), provider.to_string());
-            }
-        }
-    }
-    // Layer definition_env below user env_vars so user overrides always win.
-    // Reserved keys are stripped, matching the same filter applied at spawn.
-    let mut filtered_definition_env = BTreeMap::new();
-    for (key, value) in &input.definition_env {
-        if !crate::managed_agents::is_reserved_env_key(key) {
-            filtered_definition_env.insert(key.clone(), value.clone());
-        }
-    }
-    // Merge: derived (metadata) → definition env → user env_vars.
-    let merged_with_def =
-        crate::managed_agents::merged_user_env(&derived_env, &filtered_definition_env);
-    let merged_env = crate::managed_agents::merged_user_env(&merged_with_def, &input.env_vars);
+    let merged_env = draft_agent_model_discovery_env(
+        agent_command,
+        input.provider.as_deref(),
+        &input.definition_env,
+        &input.env_vars,
+    );
     let merged_env = discovery_env_with_baked_floor(merged_env);
     // Recover a build-provided provider when the form has none, so the create
     // dialog discovers live models instead of falling through to the subprocess.
@@ -348,6 +282,13 @@ pub async fn discover_agent_models(
         return Err("Buzz shared compute is not available in this build".to_string());
     }
 
+    if let Some(models) =
+        discover_openrouter_models(&state.http_client, &effective_provider, &merged_env, None)
+            .await?
+    {
+        return Ok(models);
+    }
+
     if let Some(models) = discover_openai_compatible_models(
         &state.http_client,
         &effective_provider,
@@ -388,6 +329,15 @@ struct OpenAiModelListItem {
     created: Option<i64>,
 }
 
+#[path = "agent_models_openrouter.rs"]
+mod openrouter;
+use openrouter::discover_openrouter_models;
+#[cfg(test)]
+use openrouter::{
+    filter_openrouter_models, is_openrouter_provider, openrouter_models_url,
+    OpenRouterModelListItem, OpenRouterModelListResponse,
+};
+
 fn is_openai_compatible_provider(provider: Option<&str>) -> bool {
     matches!(
         provider
diff --git a/desktop/src-tauri/src/commands/agent_models_discovery_config.rs b/desktop/src-tauri/src/commands/agent_models_discovery_config.rs
new file mode 100644
index 0000000000..e43f09495b
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_models_discovery_config.rs
@@ -0,0 +1,112 @@
+//! Model-discovery configuration resolution for the agent-models commands.
+//!
+//! Two entry points, one per call shape: [`agent_model_discovery_config`]
+//! resolves a *saved* agent through the same descriptor/model resolvers spawn
+//! uses, and [`draft_agent_model_discovery_env`] derives the env for an unsaved
+//! form. Both are pure so the regression tests can bind the exact values the
+//! commands consume.
+//!
+//! Included from `agent_models.rs` via `#[path]`, so `super::*` resolves
+//! against that module (the `agent_models_tests.rs` convention).
+
+use std::collections::BTreeMap;
+
+use crate::managed_agents::known_acp_runtime;
+
+/// Everything `get_agent_models` needs from the record + context, resolved in
+/// one pure step so the linked-agent regression test can bind the exact values
+/// the command consumes.
+#[derive(Debug, PartialEq, Eq)]
+pub(super) struct AgentModelDiscoveryConfig {
+    /// Effective harness command (descriptor-resolved), for `resolve_command`.
+    pub(super) command: String,
+    /// Effective harness args (descriptor-resolved).
+    pub(super) args: Vec<String>,
+    /// Model from the authoritative resolver spawn uses — linked instances
+    /// read their definition, never stale `record.model` bytes.
+    pub(super) model: Option<String>,
+    /// Provider from the same authoritative resolver — never stale
+    /// `record.provider` bytes for linked instances.
+    pub(super) provider: Option<String>,
+    /// The runtime's provider env var (e.g. `GOOSE_PROVIDER`), so discovery
+    /// can recover the provider from the env when the resolver yields none.
+    /// `None` for runtimes that do not take a provider, or an unknown command.
+    pub(super) provider_env_var: Option<&'static str>,
+    /// The descriptor's fully layered env (definition/persona/global/agent).
+    pub(super) env: BTreeMap<String, String>,
+}
+
+/// Resolve the model-discovery config for a saved agent — the descriptor-backed
+/// successor to the old `saved_agent_model_discovery_config`.
+///
+/// Command/args/env come from `resolve_effective_harness_descriptor` (the same
+/// resolver as `spawn_agent_child`); model/provider come from
+/// `resolve_effective_model_provider` (#1968's definition-authoritative
+/// contract) — linked instances read their definition, never a stale
+/// materialized `record.model`/`record.provider`, so discovery cannot query a
+/// provider this agent will not actually launch with. Definition-less
+/// instances keep their own record values, matching spawn's
+/// `resolve_definition_less` arm. When the resolver yields no provider,
+/// `effective_discovery_provider` recovers the provider the agent will
+/// actually launch with from the runtime's own provider env var, read out of
+/// the descriptor env (which already layers definition/persona/global values
+/// the same way spawn does).
+///
+/// Returns `Err("DANGLING_HARNESS_ID:<id>")` from the descriptor resolver when
+/// the harness id no longer exists; the caller routes it through
+/// `model_discovery_error`.
+pub(super) fn agent_model_discovery_config(
+    record: &crate::managed_agents::ManagedAgentRecord,
+    personas: &[crate::managed_agents::AgentDefinition],
+    global: &crate::managed_agents::GlobalAgentConfig,
+) -> Result<AgentModelDiscoveryConfig, String> {
+    let descriptor =
+        crate::managed_agents::resolve_effective_harness_descriptor(record, personas, global)?;
+    let (model, provider) =
+        crate::managed_agents::resolve_effective_model_provider(record, personas, global);
+    let provider_env_var =
+        known_acp_runtime(&descriptor.command).and_then(|meta| meta.provider_env_var);
+
+    Ok(AgentModelDiscoveryConfig {
+        command: descriptor.command,
+        args: descriptor.args,
+        model,
+        provider,
+        provider_env_var,
+        env: descriptor.env,
+    })
+}
+
+/// Derive the discovery env for an unsaved ("draft") agent configuration.
+///
+/// Mirrors the layering `agent_model_discovery_config` takes from the harness
+/// descriptor, but sources the provider from form input: runtime-derived
+/// provider env var → definition env → user env vars, so user overrides always
+/// win. Extracted so the draft path has the same tested seam as the saved one.
+pub(super) fn draft_agent_model_discovery_env(
+    agent_command: &str,
+    provider: Option<&str>,
+    definition_env: &BTreeMap<String, String>,
+    env_vars: &BTreeMap<String, String>,
+) -> BTreeMap<String, String> {
+    let mut derived_env = BTreeMap::new();
+    if let Some(meta) = known_acp_runtime(agent_command) {
+        let provider = provider.map(str::trim).filter(|value| !value.is_empty());
+        if !meta.provider_locked {
+            if let (Some(env_key), Some(provider)) = (meta.provider_env_var, provider) {
+                derived_env.insert(env_key.to_string(), provider.to_string());
+            }
+        }
+    }
+    // Reserved keys are stripped from definition env, matching the same filter
+    // applied at spawn.
+    let mut filtered_definition_env = BTreeMap::new();
+    for (key, value) in definition_env {
+        if !crate::managed_agents::is_reserved_env_key(key) {
+            filtered_definition_env.insert(key.clone(), value.clone());
+        }
+    }
+    let merged_with_def =
+        crate::managed_agents::merged_user_env(&derived_env, &filtered_definition_env);
+    crate::managed_agents::merged_user_env(&merged_with_def, env_vars)
+}
diff --git a/desktop/src-tauri/src/commands/agent_models_openrouter.rs b/desktop/src-tauri/src/commands/agent_models_openrouter.rs
new file mode 100644
index 0000000000..be6dd2cf26
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_models_openrouter.rs
@@ -0,0 +1,112 @@
+use std::collections::BTreeMap;
+
+use serde::Deserialize;
+
+use crate::managed_agents::{AgentModelInfo, AgentModelsResponse};
+
+#[cfg(test)]
+use super::env_value;
+use super::{env_or_process_value, redaction_env_with_value, DiscoveryProvider};
+
+#[derive(Debug, Deserialize)]
+#[cfg_attr(test, derive(Clone))]
+pub(super) struct OpenRouterModelListResponse {
+    pub data: Vec<OpenRouterModelListItem>,
+}
+
+#[derive(Debug, Deserialize)]
+#[cfg_attr(test, derive(Clone))]
+pub(super) struct OpenRouterModelListItem {
+    pub id: String,
+    #[serde(default)]
+    pub supported_parameters: Vec<String>,
+}
+
+pub(super) fn is_openrouter_provider(provider: Option<&str>) -> bool {
+    matches!(
+        provider
+            .map(str::trim)
+            .map(str::to_ascii_lowercase)
+            .as_deref(),
+        Some("openrouter")
+    )
+}
+
+#[cfg(test)]
+pub(super) fn openrouter_models_url(env: &BTreeMap<String, String>) -> String {
+    let base_url = env_value(env, "OPENROUTER_BASE_URL")
+        .unwrap_or_else(|| "https://openrouter.ai/api/v1".to_string());
+    format!("{}/models", base_url.trim_end_matches('/'))
+}
+
+fn openrouter_models_url_for_discovery(env: &BTreeMap<String, String>) -> String {
+    let base_url = env_or_process_value(env, "OPENROUTER_BASE_URL")
+        .unwrap_or_else(|| "https://openrouter.ai/api/v1".to_string());
+    format!("{}/models", base_url.trim_end_matches('/'))
+}
+
+pub(super) async fn discover_openrouter_models(
+    client: &reqwest::Client,
+    provider: &DiscoveryProvider,
+    env: &BTreeMap<String, String>,
+    selected_model: Option<String>,
+) -> Result<Option<AgentModelsResponse>, String> {
+    if !is_openrouter_provider(provider.as_deref()) {
+        return Ok(None);
+    }
+
+    let api_key = match provider.required_env(env, "OPENROUTER_API_KEY")? {
+        Some(api_key) => api_key,
+        None => return Ok(None),
+    };
+    let redaction_env = redaction_env_with_value(env, "OPENROUTER_API_KEY", &api_key);
+    let url = openrouter_models_url_for_discovery(env);
+    let response = client
+        .get(&url)
+        .bearer_auth(&api_key)
+        .send()
+        .await
+        .map_err(|error| format!("OpenRouter model discovery request failed: {error}"))?;
+    let status = response.status();
+    if !status.is_success() {
+        let body = response.text().await.unwrap_or_default();
+        let body = crate::managed_agents::redact_env_values_in(&body, &redaction_env);
+        return Err(format!("OpenRouter model discovery HTTP {status}: {body}"));
+    }
+
+    let response = response
+        .json::<OpenRouterModelListResponse>()
+        .await
+        .map_err(|error| format!("OpenRouter model discovery response parse failed: {error}"))?;
+
+    filter_openrouter_models(response, selected_model)
+}
+
+pub(super) fn filter_openrouter_models(
+    response: OpenRouterModelListResponse,
+    selected_model: Option<String>,
+) -> Result<Option<AgentModelsResponse>, String> {
+    let models: Vec<AgentModelInfo> = response
+        .data
+        .into_iter()
+        .filter(|m| m.supported_parameters.iter().any(|p| p == "tools"))
+        .map(|m| AgentModelInfo {
+            id: m.id.clone(),
+            name: Some(m.id),
+            description: None,
+        })
+        .collect();
+
+    if models.is_empty() {
+        return Err("OpenRouter model discovery returned no tools-capable models".to_string());
+    }
+
+    Ok(Some(AgentModelsResponse {
+        agent_name: "openrouter".to_string(),
+        agent_version: "models-api".to_string(),
+        models,
+        agent_default_model: None,
+        selected_model,
+        supports_switching: true,
+    }))
+}
diff --git a/desktop/src-tauri/src/commands/agent_models_tests.rs b/desktop/src-tauri/src/commands/agent_models_tests.rs
index b65f240900..14c981d730 100644
--- a/desktop/src-tauri/src/commands/agent_models_tests.rs
+++ b/desktop/src-tauri/src/commands/agent_models_tests.rs
@@ -590,3 +590,294 @@ fn model_discovery_error_converts_dangling_sentinel_to_sentence() {
     let plain = model_discovery_error("agent-pk", "plain failure");
     assert_eq!(plain, "cannot discover models for agent-pk: plain failure");
 }
+
+// ---------------------------------------------------------------------------
+// OpenRouter provider
+// ---------------------------------------------------------------------------
+
+#[test]
+fn is_openrouter_provider_matches() {
+    assert!(is_openrouter_provider(Some("openrouter")));
+    assert!(is_openrouter_provider(Some("  OpenRouter  ")));
+    assert!(!is_openrouter_provider(Some("openai")));
+    assert!(!is_openrouter_provider(Some("anthropic")));
+    assert!(!is_openrouter_provider(None));
+}
+
+#[test]
+fn openrouter_models_url_uses_default_base_url() {
+    assert_eq!(
+        openrouter_models_url(&BTreeMap::new()),
+        "https://openrouter.ai/api/v1/models"
+    );
+}
+
+#[test]
+fn openrouter_models_url_respects_custom_base_url() {
+    let env = BTreeMap::from([(
+        "OPENROUTER_BASE_URL".to_string(),
+        "https://eu.openrouter.ai/api/v1".to_string(),
+    )]);
+    assert_eq!(
+        openrouter_models_url(&env),
+        "https://eu.openrouter.ai/api/v1/models"
+    );
+}
+
+#[test]
+fn openrouter_models_url_strips_trailing_slash() {
+    let env = BTreeMap::from([(
+        "OPENROUTER_BASE_URL".to_string(),
+        "https://proxy.example.com/api/v1/".to_string(),
+    )]);
+    assert_eq!(
+        openrouter_models_url(&env),
+        "https://proxy.example.com/api/v1/models"
+    );
+}
+
+#[test]
+fn openrouter_filter_keeps_tools_capable_models() {
+    let response = OpenRouterModelListResponse {
+        data: vec![
+            OpenRouterModelListItem {
+                id: "anthropic/claude-opus-4-7".to_string(),
+                supported_parameters: vec!["tools".to_string(), "reasoning".to_string()],
+            },
+            OpenRouterModelListItem {
+                id: "openai/gpt-5.5-pro".to_string(),
+                supported_parameters: vec!["tools".to_string()],
+            },
+            OpenRouterModelListItem {
+                id: "meta-llama/llama-no-tools".to_string(),
+                supported_parameters: vec!["temperature".to_string()],
+            },
+        ],
+    };
+    let result = filter_openrouter_models(response, None).unwrap().unwrap();
+    let ids: Vec<_> = result.models.iter().map(|m| m.id.as_str()).collect();
+    assert_eq!(ids, vec!["anthropic/claude-opus-4-7", "openai/gpt-5.5-pro"]);
+}
+
+#[test]
+fn openrouter_filter_excludes_absent_supported_parameters() {
+    let response: OpenRouterModelListResponse =
+        serde_json::from_str(r#"{"data": [{"id": "model-no-params"}]}"#).unwrap();
+    assert!(
+        response.data[0].supported_parameters.is_empty(),
+        "absent supported_parameters must default to empty vec"
+    );
+    let result = filter_openrouter_models(response, None);
+    assert!(
+        result.is_err(),
+        "models with no supported_parameters must be excluded"
+    );
+    assert!(
+        result.unwrap_err().contains("no tools-capable models"),
+        "error must indicate no tools-capable models"
+    );
+}
+
+#[test]
+fn openrouter_filter_excludes_empty_supported_parameters() {
+    let response = OpenRouterModelListResponse {
+        data: vec![OpenRouterModelListItem {
+            id: "model-empty-params".to_string(),
+            supported_parameters: Vec::new(),
+        }],
+    };
+    let result = filter_openrouter_models(response, None);
+    assert!(result.is_err());
+    assert!(result.unwrap_err().contains("no tools-capable models"));
+}
+
+#[test]
+fn openrouter_filter_empty_result_returns_error() {
+    let response = OpenRouterModelListResponse { data: Vec::new() };
+    let result = filter_openrouter_models(response, None);
+    assert!(result.is_err());
+    assert!(result.unwrap_err().contains("no tools-capable models"));
+}
+
+#[test]
+fn openrouter_filter_preserves_selected_model() {
+    let response = OpenRouterModelListResponse {
+        data: vec![OpenRouterModelListItem {
+            id: "openai/gpt-5.5-pro".to_string(),
+            supported_parameters: vec!["tools".to_string()],
+        }],
+    };
+    let result = filter_openrouter_models(response, Some("openai/gpt-5.5-pro".to_string()))
+        .unwrap()
+        .unwrap();
+    assert_eq!(result.selected_model.as_deref(), Some("openai/gpt-5.5-pro"));
+}
+
+#[test]
+fn openrouter_credential_redaction_env_records_key() {
+    let env = BTreeMap::from([(
+        "OPENROUTER_API_KEY".to_string(),
+        "sk-or-v1-secret-key-12345".to_string(),
+    )]);
+    let redaction =
+        redaction_env_with_value(&env, "OPENROUTER_API_KEY", "sk-or-v1-secret-key-12345");
+    assert_eq!(
+        redaction.get("OPENROUTER_API_KEY").map(String::as_str),
+        Some("sk-or-v1-secret-key-12345"),
+        "redaction env must record the API key for error body redaction"
+    );
+}
+
+#[test]
+fn openrouter_saved_agent_model_discovery_resolves_provider() {
+    let record: crate::managed_agents::ManagedAgentRecord = serde_json::from_str(
+        r#"{
+            "pubkey": "abcd1234",
+            "name": "test-agent",
+            "private_key_nsec": "nsec1fake",
+            "relay_url": "wss://localhost:3000",
+            "acp_command": "buzz-acp",
+            "agent_command": "buzz-agent",
+            "agent_command_override": "buzz-agent",
+            "agent_args": [],
+            "mcp_command": "",
+            "turn_timeout_seconds": 320,
+            "system_prompt": null,
+            "model": "anthropic/claude-sonnet-4",
+            "provider": "openrouter",
+            "env_vars": {
+                "OPENROUTER_API_KEY": "sk-or-test-key",
+                "BUZZ_PRIVATE_KEY": "must-not-leak"
+            },
+            "created_at": "2026-01-01T00:00:00Z",
+            "updated_at": "2026-01-01T00:00:00Z",
+            "last_started_at": null,
+            "last_stopped_at": null,
+            "last_exit_code": null,
+            "last_error": null
+        }"#,
+    )
+    .expect("sample openrouter managed agent record");
+
+    let discovery = agent_model_discovery_config(
+        &record,
+        &[],
+        &crate::managed_agents::GlobalAgentConfig::default(),
+    )
+    .expect("discovery config should resolve for an openrouter record");
+    assert_eq!(discovery.provider.as_deref(), Some("openrouter"));
+    assert_eq!(
+        discovery.model.as_deref(),
+        Some("anthropic/claude-sonnet-4")
+    );
+    assert_eq!(
+        discovery.env.get("OPENROUTER_API_KEY").map(String::as_str),
+        Some("sk-or-test-key")
+    );
+    assert!(!discovery.env.contains_key("BUZZ_PRIVATE_KEY"));
+}
+
+/// B5/T4: unsaved-agent ("draft") discovery mirrors the saved-agent path —
+/// `draft_agent_model_discovery_env` must derive the provider env var from
+/// form input the same way `agent_model_discovery_config` derives it from a
+/// persisted record's harness descriptor, and preserve caller-supplied env
+/// (including the OpenRouter API key) unmodified.
+#[test]
+fn openrouter_draft_agent_model_discovery_derives_provider_env() {
+    let env_vars = BTreeMap::from([(
+        "OPENROUTER_API_KEY".to_string(),
+        "sk-or-draft-key".to_string(),
+    )]);
+
+    let merged = draft_agent_model_discovery_env(
+        "buzz-agent",
+        Some("openrouter"),
+        &BTreeMap::new(),
+        &env_vars,
+    );
+
+    assert_eq!(
+        merged.get("BUZZ_AGENT_PROVIDER").map(String::as_str),
+        Some("openrouter"),
+        "provider env var must be derived from form input for a known ACP runtime"
+    );
+    assert_eq!(
+        merged.get("OPENROUTER_API_KEY").map(String::as_str),
+        Some("sk-or-draft-key"),
+        "caller-supplied env vars must survive the merge"
+    );
+}
+
+#[test]
+fn draft_agent_model_discovery_env_omits_provider_when_absent() {
+    let merged =
+        draft_agent_model_discovery_env("buzz-agent", None, &BTreeMap::new(), &BTreeMap::new());
+    assert!(
+        !merged.contains_key("BUZZ_AGENT_PROVIDER"),
+        "no provider must be derived when the caller supplies none"
+    );
+}
+
+/// The three-tier precedence this merge exists to preserve: main's inline
+/// `derived → definition_env → env_vars` layering was folded into
+/// `draft_agent_model_discovery_env`, so pin the order at every collision
+/// boundary rather than trusting the two single-tier tests above.
+///
+/// `SHARED` collides across all three tiers, so the user value proves the
+/// full chain; the pairwise keys prove each adjacent boundary independently
+/// (a merge that dropped only the middle tier would still satisfy `SHARED`).
+/// `BUZZ_PRIVATE_KEY` proves a reserved key cannot ride in on a harness
+/// definition, which is the tier a user never types.
+#[test]
+fn draft_agent_model_discovery_env_layers_all_three_tiers_in_order() {
+    // Tier 2 (middle): harness definition env — overlays the runtime-derived
+    // floor, loses to user env.
+    let definition_env = BTreeMap::from([
+        ("SHARED".to_string(), "from-definition".to_string()),
+        // Collides with tier 1: `buzz-agent`'s own provider env var, which the
+        // `provider` argument derives below.
+        ("BUZZ_AGENT_PROVIDER".to_string(), "openai".to_string()),
+        ("USER_OVER_DEF".to_string(), "from-definition".to_string()),
+        ("DEFINITION_ONLY".to_string(), "from-definition".to_string()),
+        // Reserved: must never reach the child, even from a definition.
+        ("BUZZ_PRIVATE_KEY".to_string(), "must-not-leak".to_string()),
+    ]);
+    // Tier 3 (top): user-entered env — wins over everything.
+    let env_vars = BTreeMap::from([
+        ("SHARED".to_string(), "from-user".to_string()),
+        ("USER_OVER_DEF".to_string(), "from-user".to_string()),
+        ("USER_ONLY".to_string(), "from-user".to_string()),
+    ]);
+
+    // Tier 1 (floor): `Some("openrouter")` derives BUZZ_AGENT_PROVIDER.
+    let merged = draft_agent_model_discovery_env(
+        "buzz-agent",
+        Some("openrouter"),
+        &definition_env,
+        &env_vars,
+    );
+
+    let expected: &[(&str, Option<&str>)] = &[
+        // Collides in all three tiers — the top tier wins.
+        ("SHARED", Some("from-user")),
+        // Tier 2 over tier 1: the definition's value survives, proving the
+        // derived provider is the floor and not layered on top.
+        ("BUZZ_AGENT_PROVIDER", Some("openai")),
+        // Tier 3 over tier 2.
+        ("USER_OVER_DEF", Some("from-user")),
+        // Single-tier keys pass through untouched.
+        ("DEFINITION_ONLY", Some("from-definition")),
+        ("USER_ONLY", Some("from-user")),
+        // Reserved keys never survive the definition tier. Doubly enforced —
+        // the explicit `is_reserved_env_key` filter here and `merged_user_env`'s
+        // own `retain` — so this pins the contract, not either mechanism.
+        ("BUZZ_PRIVATE_KEY", None),
+    ];
+    for (key, want) in expected {
+        assert_eq!(
+            merged.get(*key).map(String::as_str),
+            *want,
+            "env key `{key}` must resolve to {want:?} after three-tier layering"
+        );
+    }
+}
diff --git a/desktop/src-tauri/src/commands/agents.rs b/desktop/src-tauri/src/commands/agents.rs
index 0758fc3aac..3b114b0474 100644
--- a/desktop/src-tauri/src/commands/agents.rs
+++ b/desktop/src-tauri/src/commands/agents.rs
@@ -1362,7 +1362,7 @@ use deploy::build_deploy_payload;
 #[cfg(test)]
 use deploy::deploy_payload_json;
 #[cfg(test)]
-pub(crate) use deploy::resolve_deploy_model_provider;
+use deploy::{ensure_remote_provider_supported, resolve_deploy_model_provider};
 
 #[path = "agents_profile.rs"]
 mod profile;
diff --git a/desktop/src-tauri/src/commands/agents_deploy.rs b/desktop/src-tauri/src/commands/agents_deploy.rs
index af785711d5..9bb0f6230d 100644
--- a/desktop/src-tauri/src/commands/agents_deploy.rs
+++ b/desktop/src-tauri/src/commands/agents_deploy.rs
@@ -1,6 +1,8 @@
 //! Provider deploy payload construction, split from `agents.rs` (file-size
-//! guard). `build_deploy_payload` gathers live state; `deploy_payload_json`
-//! is the pure serialization half so payload completeness stays testable.
+//! guard). The launch block is derived from the same effective descriptor and
+//! policy helpers as local spawn so remote execution does not reimplement them.
+
+use std::collections::BTreeMap;
 
 use tauri::AppHandle;
 
@@ -13,17 +15,6 @@ use crate::{
 };
 
 /// Resolve the deploy-specific structured model/provider for a managed agent.
-///
-/// Delegates to the single effective-config resolver which enforces
-/// definition-authoritative semantics for linked instances:
-///   - **Linked:** definition → global. Stale record bytes are never consulted.
-///   - **Definition-less:** instance → global.
-///   - **Orphaned:** returns `(None, None)` — spawn is blocked elsewhere.
-///
-/// Both local spawn and deploy now use the same resolver, so they can never
-/// disagree on what model/provider an agent runs with.
-///
-/// Exported `pub(crate)` for unit testing.
 #[cfg(test)]
 pub(crate) fn resolve_deploy_model_provider(
     record: &ManagedAgentRecord,
@@ -36,58 +27,116 @@ pub(crate) fn resolve_deploy_model_provider(
     .unwrap_or((None, None))
 }
 
-/// Build the standard agent JSON payload for provider deploy calls.
-///
-/// Like local spawn, provider deploy re-reads live persona env vars and
-/// structured model/provider so remote agents receive current credentials
-/// and the same authoritative values that local spawn derives from
-/// `runtime_metadata_env_vars`. The only field still pinned is
-/// `agent_command`/`agent_args` — those were captured at create time.
-/// The only read-time resolution is `relay_url`: a blank pin resolves to
-/// the active workspace relay here, matching the create-path contract.
+/// Serialize the portable launch contract shared with provider-backed agents.
 ///
-/// Fails closed when the private key is unavailable (keyring outage leaves
-/// it empty after hydration): without this guard a provider deploy would
-/// serialize `"private_key_nsec": ""` and launch the agent with no
-/// identity — the same hazard the local spawn path refuses via
-/// `spawn_key_refusal`.
+/// `descriptor.env` is the authoritative six-layer environment. Policy values
+/// are deliberately separate because providers apply them below that layered
+/// environment, preserving the local spawn's power-user override semantics.
+pub(super) fn build_launch_block(
+    record: &ManagedAgentRecord,
+    descriptor: &crate::managed_agents::readiness::EffectiveHarnessDescriptor,
+    teams: &[crate::managed_agents::TeamRecord],
+    effective_prompt: Option<&str>,
+    effective_model: Option<&str>,
+    owner_pubkey: &str,
+) -> serde_json::Value {
+    use crate::managed_agents::{known_acp_runtime, resolve_session_title, SESSION_TITLE_ENV_VAR};
+
+    let runtime = known_acp_runtime(&descriptor.command);
+    let mut policy_env = BTreeMap::new();
+
+    if let Some(runtime) = runtime {
+        policy_env.extend(
+            runtime
+                .default_env
+                .iter()
+                .map(|(key, value)| ((*key).to_string(), (*value).to_string())),
+        );
+        if runtime.mcp_hooks {
+            policy_env.insert("MCP_HOOK_SERVERS".into(), "*".into());
+        }
+    }
+    policy_env.insert("BUZZ_ACP_RELAY_OBSERVER".into(), "true".into());
+    policy_env.insert("BUZZ_ACP_LAZY_POOL".into(), "true".into());
+    policy_env.insert("BUZZ_ACP_AGENTS".into(), record.parallelism.to_string());
+
+    if let Some(value) = effective_prompt {
+        policy_env.insert("BUZZ_ACP_SYSTEM_PROMPT".into(), value.to_string());
+    }
+    if let Some(value) = effective_model {
+        policy_env.insert("BUZZ_ACP_MODEL".into(), value.to_string());
+    }
+    if let Some(value) = record.idle_timeout_seconds {
+        policy_env.insert("BUZZ_ACP_IDLE_TIMEOUT".into(), value.to_string());
+    }
+    if let Some(value) = record.max_turn_duration_seconds {
+        policy_env.insert("BUZZ_ACP_MAX_TURN_DURATION".into(), value.to_string());
+    }
+    if let Some(value) = resolve_session_title(record.display_name.as_deref(), &record.name) {
+        policy_env.insert(SESSION_TITLE_ENV_VAR.into(), value);
+    }
+    if let Some(value) =
+        crate::managed_agents::spawn_hash::effective_team_instructions(record, teams)
+    {
+        policy_env.insert("BUZZ_ACP_TEAM_INSTRUCTIONS".into(), value);
+    }
+
+    serde_json::json!({
+        "command": descriptor.command,
+        "args": descriptor.args,
+        "env": descriptor.env,
+        "policy_env": policy_env,
+        "owner_pubkey": owner_pubkey,
+    })
+}
+
+pub(super) fn ensure_remote_provider_supported(provider: Option<&str>) -> Result<(), String> {
+    if provider.map(str::trim) == Some(crate::managed_agents::RELAY_MESH_PROVIDER_ID) {
+        return Err(
+            "shared-compute agents cannot be deployed remotely because the mesh endpoint is local to the desktop"
+                .to_string(),
+        );
+    }
+    Ok(())
+}
+
+/// Build the standard agent JSON payload for provider deploy calls.
 pub(super) fn build_deploy_payload(
     app: &AppHandle,
     state: &AppState,
     record: &ManagedAgentRecord,
 ) -> Result<serde_json::Value, String> {
-    // Fails closed when the private key is unavailable — same guard as local
-    // spawn. Without this, a keyring outage would serialize `"private_key_nsec": ""`
-    // and launch the agent with no identity.
     if let Some(err) = crate::managed_agents::spawn_key_refusal(record) {
         return Err(err);
     }
 
-    // Merge global + persona + agent env_vars for provider deploy — the same
-    // live-persona-under-overrides semantics as local spawn. Global env vars
-    // are the lowest user-settable layer: global < persona < agent (last-wins
-    // on key collision). Without this, provider-backed agents wouldn't receive
-    // credentials saved on the persona or the agent itself.
-    let global_config = crate::managed_agents::load_global_agent_config(app).unwrap_or_default();
-    let global_env = global_config.env_vars.clone();
-    let persona_env =
-        crate::managed_agents::resolve_persona_env(app, record.persona_id.as_deref())?;
-    // Merge: global < persona (persona wins over global).
-    let global_persona_merged = crate::managed_agents::merged_user_env(&global_env, &persona_env);
-    // Merge: global+persona < agent (agent wins over everything).
-    let merged_env =
-        crate::managed_agents::merged_user_env(&global_persona_merged, &record.env_vars);
-
+    let global = crate::managed_agents::load_global_agent_config(app).unwrap_or_default();
     let personas = load_personas(app).unwrap_or_default();
-    let cfg = crate::managed_agents::effective_config::resolve_effective_config(
-        record,
-        &personas,
-        &global_config,
+    let teams = crate::managed_agents::load_teams(app).unwrap_or_default();
+    let persona_env =
+        crate::managed_agents::live_persona_env(&personas, record.persona_id.as_deref());
+    let global_persona_env = crate::managed_agents::merged_user_env(&global.env_vars, &persona_env);
+    let merged_user_env =
+        crate::managed_agents::merged_user_env(&global_persona_env, &record.env_vars);
+    let effective = crate::managed_agents::effective_config::resolve_effective_config(
+        record, &personas, &global,
     )
     .require_resolved()?;
-    let effective_model = cfg.model.value;
-    let effective_provider = cfg.provider.value;
-    let effective_prompt = cfg.system_prompt.value;
+
+    ensure_remote_provider_supported(effective.provider.value.as_deref())?;
+
+    let descriptor =
+        crate::managed_agents::resolve_effective_harness_descriptor(record, &personas, &global)
+            .map_err(|error| crate::managed_agents::user_facing_harness_error(&error))?;
+    let owner_pubkey = super::workspace_owner_hex(state)?;
+    let launch = build_launch_block(
+        record,
+        &descriptor,
+        &teams,
+        effective.system_prompt.value.as_deref(),
+        effective.model.value.as_deref(),
+        &owner_pubkey,
+    );
 
     Ok(deploy_payload_json(
         record,
@@ -95,23 +144,24 @@ pub(super) fn build_deploy_payload(
             &record.relay_url,
             &relay_ws_url_with_override(state),
         ),
-        effective_model,
-        effective_provider,
-        effective_prompt,
-        merged_env,
+        effective.model.value,
+        effective.provider.value,
+        effective.system_prompt.value,
+        merged_user_env,
+        launch,
     ))
 }
 
-/// Pure serialization half of [`build_deploy_payload`] — every field the
-/// provider harness receives is deliberately listed here, so payload
-/// completeness is testable without an `AppHandle`.
+/// Pure serialization half of [`build_deploy_payload`]. Legacy top-level fields
+/// remain for display/bookkeeping; providers execute the resolved `launch` block.
 pub(super) fn deploy_payload_json(
     record: &ManagedAgentRecord,
     relay_url: String,
     effective_model: Option<String>,
     effective_provider: Option<String>,
     effective_prompt: Option<String>,
-    merged_env: std::collections::BTreeMap<String, String>,
+    merged_env: BTreeMap<String, String>,
+    launch: serde_json::Value,
 ) -> serde_json::Value {
     serde_json::json!({
         "name": &record.name,
@@ -130,5 +180,81 @@ pub(super) fn deploy_payload_json(
         "respond_to": record.respond_to,
         "respond_to_allowlist": &record.respond_to_allowlist,
         "env_vars": merged_env,
+        "launch": launch,
     })
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::managed_agents::{readiness::EffectiveHarnessDescriptor, RespondTo, TeamRecord};
+
+    fn record() -> ManagedAgentRecord {
+        serde_json::from_value(serde_json::json!({
+            "pubkey": "abcd1234",
+            "name": "agent-handle",
+            "display_name": "Agent\u{0000} Name",
+            "private_key_nsec": "nsec1fake",
+            "relay_url": "wss://relay.example",
+            "acp_command": "buzz-acp",
+            "agent_command": "goose",
+            "agent_args": [],
+            "mcp_command": "",
+            "turn_timeout_seconds": 320,
+            "idle_timeout_seconds": 17,
+            "max_turn_duration_seconds": 23,
+            "parallelism": 4,
+            "respond_to": RespondTo::OwnerOnly,
+            "respond_to_allowlist": [],
+            "team_id": "team-1",
+            "created_at": "2026-01-01T00:00:00Z",
+            "updated_at": "2026-01-01T00:00:00Z"
+        }))
+        .unwrap()
+    }
+
+    #[test]
+    fn launch_block_preserves_descriptor_and_spawn_policy() {
+        let record = record();
+        let descriptor = EffectiveHarnessDescriptor {
+            command: "goose".into(),
+            args: vec!["acp".into()],
+            env: BTreeMap::from([
+                ("GOOSE_MODE".into(), "custom".into()),
+                ("SECRET_FROM_PERSONA".into(), "secret".into()),
+            ]),
+        };
+        let teams: Vec<TeamRecord> = serde_json::from_value(serde_json::json!([{
+            "id": "team-1", "name": "Team", "instructions": "Coordinate", "persona_ids": [], "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"
+        }])).unwrap();
+
+        let launch = build_launch_block(
+            &record,
+            &descriptor,
+            &teams,
+            Some("prompt"),
+            Some("model"),
+            "owner-hex",
+        );
+
+        assert_eq!(launch["command"], "goose");
+        assert_eq!(launch["args"], serde_json::json!(["acp"]));
+        assert_eq!(launch["env"]["GOOSE_MODE"], "custom");
+        // policy_env is applied first, so this default remains separate from
+        // the descriptor value that wins in launch.env.
+        assert_eq!(launch["policy_env"]["GOOSE_MODE"], "auto");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_LAZY_POOL"], "true");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_RELAY_OBSERVER"], "true");
+        assert_eq!(
+            launch["policy_env"]["BUZZ_ACP_TEAM_INSTRUCTIONS"],
+            "Coordinate"
+        );
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_SESSION_TITLE"], "Agent Name");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_SYSTEM_PROMPT"], "prompt");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_MODEL"], "model");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_IDLE_TIMEOUT"], "17");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_MAX_TURN_DURATION"], "23");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_AGENTS"], "4");
+        assert_eq!(launch["owner_pubkey"], "owner-hex");
+    }
+}
diff --git a/desktop/src-tauri/src/commands/agents_tests.rs b/desktop/src-tauri/src/commands/agents_tests.rs
index 03389d1d18..df135298c4 100644
--- a/desktop/src-tauri/src/commands/agents_tests.rs
+++ b/desktop/src-tauri/src/commands/agents_tests.rs
@@ -263,6 +263,19 @@ fn normalize_relay_mesh_trims_and_preserves_valid_config() {
     );
 }
 
+#[test]
+fn deploy_refuses_resolved_relay_mesh_provider_with_padding() {
+    let record = bare_agent_record(Some("p1"), None, None);
+    let personas = vec![persona_record("p1", None, Some("  relay-mesh  "))];
+    let global = crate::managed_agents::GlobalAgentConfig::default();
+
+    let (_, provider) = resolve_deploy_model_provider(&record, &personas, &global);
+    let error = ensure_remote_provider_supported(provider.as_deref())
+        .expect_err("resolved shared-compute provider must not deploy remotely");
+
+    assert!(error.contains("cannot be deployed remotely"), "{error}");
+}
+
 #[test]
 fn created_avatar_prefers_explicit_input() {
     let resolved = resolve_created_avatar_url(
@@ -398,50 +411,93 @@ fn legacy_avatar_empty_when_nothing_resolves() {
 
 // ── Provider deploy payload completeness ─────────────────────────────────────
 
-/// Regression (PR #1667 review, Thufir): the provider deploy payload must
-/// carry every behavioral field the local spawn path applies — a field
-/// missing here silently strips it from provider-backed agents.
+/// The shared provider fixture is the contract arbiter: it must be the exact
+/// richest deploy request produced by the real desktop serializers.
 #[test]
-fn deploy_payload_carries_the_full_behavioral_quad() {
-    let allow = "a".repeat(64);
-    let record: ManagedAgentRecord = serde_json::from_str(&format!(
-        r#"{{
-            "pubkey": "abcd1234",
-            "name": "test-agent",
-            "private_key_nsec": "nsec1fake",
-            "relay_url": "wss://localhost:3000",
-            "acp_command": "buzz-acp",
-            "agent_command": "goose",
-            "agent_args": [],
-            "mcp_command": "",
-            "turn_timeout_seconds": 320,
-            "system_prompt": null,
-            "parallelism": 4,
-            "respond_to": "allowlist",
-            "respond_to_allowlist": ["{allow}"],
-            "created_at": "2026-01-01T00:00:00Z",
-            "updated_at": "2026-01-01T00:00:00Z",
-            "last_started_at": null,
-            "last_stopped_at": null,
-            "last_exit_code": null,
-            "last_error": null
-        }}"#
-    ))
-    .expect("sample record");
-
-    let payload = deploy_payload_json(
+fn deploy_payload_matches_the_shared_full_launch_fixture() {
+    let fixture_path = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join(
+        "../../crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-full-launch.request.json",
+    );
+    let fixture: serde_json::Value = serde_json::from_str(
+        &std::fs::read_to_string(&fixture_path)
+            .unwrap_or_else(|error| panic!("read {}: {error}", fixture_path.display())),
+    )
+    .expect("parse shared provider fixture");
+    let record: ManagedAgentRecord = serde_json::from_value(serde_json::json!({
+        "pubkey": "abcd1234",
+        "name": "worker",
+        "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+        "relay_url": "wss://localhost:3000",
+        "auth_tag": "tag-1",
+        "acp_command": "buzz-acp",
+        "agent_command": "goose",
+        "runtime": "goose",
+        "model": "gpt-5",
+        "provider": "openai",
+        "env_vars": {"USER_KEY": "user-value"},
+        "agent_args": [],
+        "mcp_command": "",
+        "turn_timeout_seconds": 300,
+        "system_prompt": null,
+        "idle_timeout_seconds": null,
+        "max_turn_duration_seconds": null,
+        "parallelism": 10,
+        "respond_to": "allowlist",
+        "respond_to_allowlist": ["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"],
+        "created_at": "2026-01-01T00:00:00Z",
+        "updated_at": "2026-01-01T00:00:00Z"
+    }))
+    .expect("fixture source record");
+    let descriptor = crate::managed_agents::resolve_effective_harness_descriptor(
+        &record,
+        &[],
+        &crate::managed_agents::GlobalAgentConfig::default(),
+    )
+    .expect("resolve fixture source record descriptor");
+    let launch = super::deploy::build_launch_block(
         &record,
-        "wss://relay.example".to_string(),
-        Some("gpt-x".to_string()),
-        Some("openai".to_string()),
+        &descriptor,
+        &[],
         None,
-        std::collections::BTreeMap::new(),
+        Some("gpt-5"),
+        "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    );
+    let agent = deploy_payload_json(
+        &record,
+        "wss://relay.example".into(),
+        Some("gpt-5".into()),
+        Some("openai".into()),
+        None,
+        std::collections::BTreeMap::from([("USER_KEY".into(), "user-value".into())]),
+        launch,
     );
 
-    assert_eq!(payload["parallelism"], 4);
-    assert_eq!(payload["respond_to"], "allowlist");
-    assert_eq!(payload["respond_to_allowlist"][0], "a".repeat(64));
-    assert_eq!(payload["model"], "gpt-x");
-    assert_eq!(payload["provider"], "openai");
-    assert_eq!(payload["relay_url"], "wss://relay.example");
+    assert_eq!(
+        agent, fixture["agent"],
+        "desktop payload drifted from the shared provider fixture"
+    );
+}
+
+#[test]
+fn tauri_platform_configs_bundle_kubernetes_only_on_supported_hosts() {
+    use tauri_utils::{config::parse::read_from, platform::Target};
+
+    let config_root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+    for (target, expected) in [
+        (Target::MacOS, true),
+        (Target::Linux, true),
+        (Target::Windows, false),
+    ] {
+        let (config, paths) = read_from(target, config_root).expect("read Tauri config");
+        let external_bins = config["bundle"]["externalBin"]
+            .as_array()
+            .expect("bundle.externalBin array");
+        let has_kubernetes = external_bins
+            .iter()
+            .any(|value| value == "binaries/buzz-backend-kubernetes");
+        assert_eq!(
+            has_kubernetes, expected,
+            "unexpected Kubernetes externalBin for {target}; merged {paths:?}"
+        );
+    }
 }
diff --git a/desktop/src-tauri/src/commands/export_util.rs b/desktop/src-tauri/src/commands/export_util.rs
index 806f58d739..ded14679c1 100644
--- a/desktop/src-tauri/src/commands/export_util.rs
+++ b/desktop/src-tauri/src/commands/export_util.rs
@@ -1,16 +1,14 @@
 use tauri::AppHandle;
 use tauri_plugin_dialog::DialogExt;
 
-/// Show a save-file dialog with a custom filter and write `data` to the chosen
-/// path. Returns `Ok(true)` when the file was written, `Ok(false)` when the
-/// user cancelled the dialog.
-pub async fn save_bytes_with_dialog(
+/// Show a save-file dialog with a custom filter and return the chosen path,
+/// or `None` when the user cancelled. Selection only — no write.
+pub async fn pick_save_path(
     app: &AppHandle,
     suggested_filename: &str,
     filter_name: &str,
     extensions: &[&str],
-    data: &[u8],
-) -> Result<bool, String> {
+) -> Result<Option<std::path::PathBuf>, String> {
     let (tx, rx) = tokio::sync::oneshot::channel();
     app.dialog()
         .file()
@@ -23,12 +21,34 @@ pub async fn save_bytes_with_dialog(
     let selected = rx.await.map_err(|_| "dialog cancelled".to_string())?;
     let file_path = match selected {
         Some(p) => p,
-        None => return Ok(false),
+        None => return Ok(None),
     };
 
     let dest = file_path
         .as_path()
         .ok_or_else(|| "Save dialog returned an invalid path".to_string())?;
+    Ok(Some(dest.to_path_buf()))
+}
+
+/// Show a save-file dialog with a custom filter and write `data` to the chosen
+/// path. Returns `Ok(true)` when the file was written, `Ok(false)` when the
+/// user cancelled the dialog.
+///
+/// NOT for secrets: the write is plain `std::fs::write` (no atomic commit, no
+/// 0o600). Secret exports go through `pick_save_path` +
+/// `key_backup::write_backup_file`.
+pub async fn save_bytes_with_dialog(
+    app: &AppHandle,
+    suggested_filename: &str,
+    filter_name: &str,
+    extensions: &[&str],
+    data: &[u8],
+) -> Result<bool, String> {
+    let dest = match pick_save_path(app, suggested_filename, filter_name, extensions).await? {
+        Some(p) => p,
+        None => return Ok(false),
+    };
+
     std::fs::write(dest, data).map_err(|e| format!("Failed to write file: {e}"))?;
 
     Ok(true)
diff --git a/desktop/src-tauri/src/commands/identity.rs b/desktop/src-tauri/src/commands/identity.rs
index 33783c05a5..33ecf3cfca 100644
--- a/desktop/src-tauri/src/commands/identity.rs
+++ b/desktop/src-tauri/src/commands/identity.rs
@@ -43,6 +43,7 @@ pub fn get_identity(state: State<'_, AppState>) -> Result<IdentityInfo, String>
     Ok(IdentityInfo {
         pubkey: pubkey_hex,
         display_name,
+        storage: state.identity_storage().as_str().to_string(),
         lost,
         locked,
         reset_failed,
@@ -135,23 +136,29 @@ pub async fn sign_event(
 }
 
 #[tauri::command]
-pub fn decrypt_observer_event(
+pub async fn decrypt_observer_event(
     event_json: String,
     state: State<'_, AppState>,
 ) -> Result<serde_json::Value, String> {
     let keys = state.signing_keys()?;
-    let event = Event::from_json(event_json).map_err(|error| format!("invalid event: {error}"))?;
 
-    // Defense-in-depth: verify event ID and signature before decrypting.
-    if !event.verify_id() {
-        return Err("observer event has invalid ID".into());
-    }
-    if !event.verify_signature() {
-        return Err("observer event has invalid signature".into());
-    }
+    tauri::async_runtime::spawn_blocking(move || {
+        let event =
+            Event::from_json(event_json).map_err(|error| format!("invalid event: {error}"))?;
+
+        // Defense-in-depth: verify event ID and signature before decrypting.
+        if !event.verify_id() {
+            return Err("observer event has invalid ID".into());
+        }
+        if !event.verify_signature() {
+            return Err("observer event has invalid signature".into());
+        }
 
-    buzz_core_pkg::observer::decrypt_observer_payload(&keys, &event)
-        .map_err(|error| format!("decrypt observer event failed: {error}"))
+        buzz_core_pkg::observer::decrypt_observer_payload(&keys, &event)
+            .map_err(|error| format!("decrypt observer event failed: {error}"))
+    })
+    .await
+    .map_err(|e| format!("spawn_blocking failed: {e}"))?
 }
 
 #[tauri::command]
@@ -188,14 +195,157 @@ pub fn get_nsec(state: State<'_, AppState>) -> Result<String, String> {
         .map_err(|error| format!("encode nsec: {error}"))
 }
 
+/// Generate a passphrase for a new encrypted backup (EFF short wordlist, OS
+/// entropy). `words` is clamped to the range allowed by `key_backup`;
+/// `separator` joins the words (defaults to a space).
+#[tauri::command]
+pub fn generate_backup_passphrase(
+    words: Option<u32>,
+    separator: Option<String>,
+) -> Result<String, String> {
+    crate::key_backup::generate_passphrase(
+        words.map_or(crate::key_backup::DEFAULT_PASSPHRASE_WORDS, |w| w as usize),
+        separator.as_deref().unwrap_or(" "),
+    )
+}
+
+/// Core of [`create_ncryptsec_backup`], factored so tests can drive it with a
+/// bare `AppState` + temp dir (and a fast scrypt tier) without an `AppHandle`.
+pub(crate) fn create_backup_with_log_n(
+    state: &AppState,
+    password: &str,
+    log_n: u8,
+) -> Result<String, String> {
+    if password.chars().count() < crate::key_backup::MIN_PASSPHRASE_LEN {
+        return Err(format!(
+            "passphrase must be at least {} characters",
+            crate::key_backup::MIN_PASSPHRASE_LEN
+        ));
+    }
+
+    // Serialize against import_identity/persist_current_identity: the blob
+    // must be derived from — and persisted for — one stable identity. Also
+    // caps KDF concurrency at one.
+    let _mutation_guard = state.identity_mutation.lock().map_err(|e| e.to_string())?;
+
+    // Recovery mode (lost/locked) → Err, same gate as signing.
+    let keys = state.signing_keys()?;
+
+    crate::key_backup::create_backup_blob(&keys, password, log_n)
+}
+
+/// Create a NIP-49 backup of the live identity in memory.
+///
+/// Encrypts under `password`, decrypt-verifies the fresh blob against the live
+/// pubkey, and returns the `ncryptsec1…` string for the native save flow. The
+/// body runs under `identity_mutation`, so identity changes cannot race the KDF.
+#[tauri::command]
+pub async fn create_ncryptsec_backup(
+    password: String,
+    app_handle: tauri::AppHandle,
+) -> Result<String, String> {
+    tokio::task::spawn_blocking(move || {
+        let password = zeroize::Zeroizing::new(password);
+        let state = app_handle.state::<AppState>();
+        create_backup_with_log_n(&state, &password, crate::key_backup::BACKUP_LOG_N)
+    })
+    .await
+    .map_err(|e| format!("spawn_blocking failed: {e}"))?
+}
+
+#[derive(Debug, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BackupVerification {
+    pub pubkey: String,
+    pub npub: String,
+    pub matches_current_identity: bool,
+}
+
+fn verify_ncryptsec_backup_inner(
+    state: &AppState,
+    ncryptsec: &str,
+    password: &str,
+) -> Result<BackupVerification, String> {
+    let keys = crate::key_backup::decrypt_ncryptsec(ncryptsec, password)?;
+    let pubkey = keys.public_key();
+    let current = state.signing_keys()?.public_key();
+    Ok(BackupVerification {
+        pubkey: pubkey.to_hex(),
+        npub: pubkey
+            .to_bech32()
+            .map_err(|e| format!("encode backup identity: {e}"))?,
+        matches_current_identity: pubkey == current,
+    })
+}
+
+/// Decrypt and validate a NIP-49 backup without exposing its secret key.
+#[tauri::command]
+pub async fn verify_ncryptsec_backup(
+    ncryptsec: String,
+    password: String,
+    app_handle: tauri::AppHandle,
+) -> Result<BackupVerification, String> {
+    tokio::task::spawn_blocking(move || {
+        let password = zeroize::Zeroizing::new(password);
+        let state = app_handle.state::<AppState>();
+        verify_ncryptsec_backup_inner(&state, &ncryptsec, &password)
+    })
+    .await
+    .map_err(|e| format!("spawn_blocking failed: {e}"))?
+}
+
+/// Save a portable copy of an `ncryptsec1…` backup to a user-chosen path.
+///
+/// The input must parse as a structurally valid NIP-49 payload. The dialog is
+/// selection-only; the write uses secret-file semantics (atomic + 0o600).
+/// Never mutates canonical app state. Returns the chosen path, or `None` when
+/// the user cancelled.
+#[tauri::command]
+pub async fn save_ncryptsec_copy(
+    ncryptsec: String,
+    app_handle: tauri::AppHandle,
+) -> Result<Option<String>, String> {
+    // Reject anything that is not a valid encrypted-key blob — this command
+    // must not become a generic file writer.
+    crate::key_backup::parse_ncryptsec(&ncryptsec)?;
+    let normalized = ncryptsec.trim().to_string();
+
+    let dest = match crate::commands::export_util::pick_save_path(
+        &app_handle,
+        crate::key_backup::BACKUP_FILE_NAME,
+        "Password-protected key backup",
+        &["ncryptsec"],
+    )
+    .await?
+    {
+        Some(p) => p,
+        None => return Ok(None),
+    };
+
+    let dest_for_write = dest.clone();
+    tokio::task::spawn_blocking(move || {
+        crate::key_backup::write_backup_file(&dest_for_write, &normalized)
+    })
+    .await
+    .map_err(|e| format!("spawn_blocking failed: {e}"))??;
+
+    Ok(Some(dest.display().to_string()))
+}
+
 #[tauri::command]
 pub async fn import_identity(
     nsec: String,
+    password: Option<String>,
     app_handle: tauri::AppHandle,
 ) -> Result<IdentityInfo, String> {
     tokio::task::spawn_blocking(move || {
-        let trimmed = nsec.trim();
-        let keys = Keys::parse(trimmed).map_err(|e| format!("Invalid private key: {e}"))?;
+        // NIP-49 backups require a passphrase and decrypt entirely in Rust.
+        // Raw nsec/hex input follows the existing parser path unchanged.
+        let password = password.map(zeroize::Zeroizing::new);
+        let keys = crate::key_backup::recover_keys_from_input(
+            &nsec,
+            password.as_ref().map(|value| value.as_str()),
+        )?;
 
         // Serialize against persist_current_identity: hold this guard for the
         // full function body so a concurrent stale persist can't overwrite
@@ -210,30 +360,14 @@ pub async fn import_identity(
         std::fs::create_dir_all(&data_dir).map_err(|e| format!("create app data dir: {e}"))?;
         let key_path = data_dir.join("identity.key");
 
-        // Persist into the OS keyring first (store → read-back verify → marker →
-        // delete file). Falls back to the 0o600 file when the keyring is
-        // unavailable; returns Err only when both backends fail.
-        let store = crate::secret_store::SecretStore::shared(crate::app_state::keyring_service());
-        crate::app_state::persist_imported_identity(store, &keys, &key_path, &data_dir)?;
-
-        // Update in-memory keys BEFORE clearing recovery flags. The Release
-        // stores below pair with Acquire loads in get_identity: a reader
-        // observing false is guaranteed to see the updated keys.
-        let pubkey = keys.public_key();
-        *state.keys.lock().map_err(|e| e.to_string())? = keys;
-
-        // Clear both recovery flags — an import is valid in either lost or
-        // keyring-locked state and resolves both. In the locked case the
-        // keyring is unreachable, so persist_imported_identity already fell
-        // back to identity.key; on the next Unreachable boot the file is
-        // loaded directly and when the keyring returns the adoption path
-        // picks it up.
-        state
-            .identity_lost
-            .store(false, std::sync::atomic::Ordering::Release);
-        state
-            .keyring_locked
-            .store(false, std::sync::atomic::Ordering::Release);
+        let (pubkey, storage) = commit_imported_identity(&state, &data_dir, keys, |keys| {
+            // Persist into the OS keyring first (store → read-back verify →
+            // marker → delete file). Falls back to the 0o600 file when the
+            // keyring is unavailable; returns Err only when both backends fail.
+            let store =
+                crate::secret_store::SecretStore::shared(crate::app_state::keyring_service());
+            crate::app_state::persist_imported_identity(store, keys, &key_path, &data_dir)
+        })?;
 
         let pubkey_hex = pubkey.to_hex();
         let display_name = truncated_display_name(&pubkey)?;
@@ -243,6 +377,7 @@ pub async fn import_identity(
         Ok(IdentityInfo {
             pubkey: pubkey_hex,
             display_name,
+            storage: storage.as_str().to_string(),
             lost: false,
             locked: false,
             reset_failed: false,
@@ -252,6 +387,69 @@ pub async fn import_identity(
     .map_err(|e| format!("spawn_blocking failed: {e}"))?
 }
 
+/// Commit an imported identity: durably persist, swap in-memory keys, clear
+/// recovery flags, then remove the previous identity's stale app-managed
+/// backup. Caller must hold `state.identity_mutation`.
+///
+/// Ordering is the contract:
+///
+/// 1. `persist` runs FIRST. If it fails (`Err` from both keyring and file
+///    fallback), nothing has changed — the previous identity stays live in
+///    memory AND its valid canonical `identity.ncryptsec` stays on disk.
+/// 2. Only after durable persistence do we swap `state.keys` and clear the
+///    recovery flags.
+/// 3. Stale-backup cleanup runs LAST and is deliberately best-effort: at that
+///    point the import is durably committed, so reporting a cleanup failure
+///    as a command `Err` would claim a half-applied import that actually
+///    succeeded. The leftover blob is still passphrase-encrypted and is
+///    replaced by the next backup creation; we log and move on.
+fn commit_imported_identity(
+    state: &AppState,
+    data_dir: &std::path::Path,
+    keys: nostr::Keys,
+    persist: impl FnOnce(&nostr::Keys) -> Result<crate::app_state::IdentityStorage, String>,
+) -> Result<(nostr::PublicKey, crate::app_state::IdentityStorage), String> {
+    // Capture the previous pubkey up front for post-commit cleanup.
+    let previous_pubkey = state.keys.lock().map_err(|e| e.to_string())?.public_key();
+
+    let storage = persist(&keys)?;
+
+    // Update in-memory keys BEFORE clearing recovery flags. The Release
+    // stores below pair with Acquire loads in get_identity: a reader
+    // observing false is guaranteed to see the updated keys.
+    let pubkey = keys.public_key();
+    {
+        let mut active_keys = state.keys.lock().map_err(|e| e.to_string())?;
+        *active_keys = keys;
+        state.set_identity_storage(storage);
+    }
+
+    // Clear both recovery flags — an import is valid in either lost or
+    // keyring-locked state and resolves both. In the locked case the
+    // keyring is unreachable, so the persist step already fell back to
+    // identity.key; on the next Unreachable boot the file is loaded
+    // directly and when the keyring returns the adoption path picks it up.
+    state
+        .identity_lost
+        .store(false, std::sync::atomic::Ordering::Release);
+    state
+        .keyring_locked
+        .store(false, std::sync::atomic::Ordering::Release);
+
+    // Importing a different identity invalidates the app-managed backup: it
+    // encrypts the previous key and must not linger mislabeled. Best-effort
+    // per the ordering contract above.
+    if let Err(e) = crate::key_backup::cleanup_stale_backup(&previous_pubkey, &pubkey, data_dir) {
+        eprintln!(
+            "buzz-desktop: import committed, but stale key backup cleanup failed: {e}; \
+             the leftover identity.ncryptsec encrypts the PREVIOUS key and will be \
+             replaced by the next backup creation"
+        );
+    }
+
+    Ok((pubkey, storage))
+}
+
 /// Make the current ephemeral identity durable by persisting it to the OS
 /// keyring (or falling back to identity.key). This is called when the user
 /// chooses to start a new identity instead of re-importing their previous one
@@ -295,11 +493,12 @@ pub async fn persist_current_identity(
         let key_path = data_dir.join("identity.key");
 
         let store = crate::secret_store::SecretStore::shared(crate::app_state::keyring_service());
-        crate::app_state::persist_imported_identity(store, &keys, &key_path, &data_dir)?;
+        let storage =
+            crate::app_state::persist_imported_identity(store, &keys, &key_path, &data_dir)?;
 
-        // Keys are already the live identity — only clear identity_lost.
-        // Release pairs with Acquire in get_identity so readers see
-        // consistent state.
+        // Keys are already the live identity. Record where the durable write
+        // landed before clearing identity_lost.
+        state.set_identity_storage(storage);
         state
             .identity_lost
             .store(false, std::sync::atomic::Ordering::Release);
@@ -311,6 +510,7 @@ pub async fn persist_current_identity(
         Ok(IdentityInfo {
             pubkey: pubkey_hex,
             display_name,
+            storage: storage.as_str().to_string(),
             lost: false,
             locked: false,
             reset_failed: false,
@@ -583,3 +783,7 @@ mod nostr_identity_binding_tests {
         assert_eq!(error, "expires_at is expired");
     }
 }
+
+#[cfg(test)]
+#[path = "identity_key_backup_tests.rs"]
+mod identity_key_backup_tests;
diff --git a/desktop/src-tauri/src/commands/identity_key_backup_tests.rs b/desktop/src-tauri/src/commands/identity_key_backup_tests.rs
new file mode 100644
index 0000000000..c36af66879
--- /dev/null
+++ b/desktop/src-tauri/src/commands/identity_key_backup_tests.rs
@@ -0,0 +1,139 @@
+use super::{create_backup_with_log_n, verify_ncryptsec_backup_inner};
+use crate::app_state::build_app_state;
+use nostr::{Keys, ToBech32};
+
+/// Fast scrypt tier for tests; production uses BACKUP_LOG_N (18), covered
+/// once in key_backup_tests::round_trip_at_production_cost.
+const FAST_LOG_N: u8 = 16;
+const PASSWORD: &str = "correct horse battery";
+
+#[test]
+fn verification_returns_only_public_identity_and_match_status() {
+    let state = build_app_state();
+    let backup = create_backup_with_log_n(&state, PASSWORD, FAST_LOG_N).unwrap();
+    let result = verify_ncryptsec_backup_inner(&state, &backup, PASSWORD).unwrap();
+    assert_eq!(
+        result.pubkey,
+        state.keys.lock().unwrap().public_key().to_hex()
+    );
+    assert!(result.npub.starts_with("npub1"));
+    assert!(result.matches_current_identity);
+}
+
+#[test]
+fn verification_reports_valid_backup_for_a_different_identity() {
+    let state = build_app_state();
+    let other = Keys::generate();
+    let backup = crate::key_backup::create_backup_blob(&other, PASSWORD, FAST_LOG_N).unwrap();
+    let result = verify_ncryptsec_backup_inner(&state, &backup, PASSWORD).unwrap();
+    assert_eq!(result.pubkey, other.public_key().to_hex());
+    assert!(!result.matches_current_identity);
+}
+
+#[test]
+fn verification_rejects_wrong_password() {
+    let state = build_app_state();
+    let backup =
+        crate::key_backup::create_backup_blob(&Keys::generate(), PASSWORD, FAST_LOG_N).unwrap();
+    assert_eq!(
+        verify_ncryptsec_backup_inner(&state, &backup, "wrong password").unwrap_err(),
+        "wrong backup password or damaged key backup"
+    );
+}
+
+#[test]
+fn verification_accepts_maximum_supported_kdf_cost() {
+    let state = build_app_state();
+    let backup = crate::key_backup::create_backup_blob(
+        &Keys::generate(),
+        PASSWORD,
+        crate::key_backup::MAX_VERIFY_LOG_N,
+    )
+    .unwrap();
+    verify_ncryptsec_backup_inner(&state, &backup, PASSWORD).unwrap();
+}
+
+#[test]
+fn verification_rejects_unsupported_kdf_cost_before_decryption() {
+    let state = build_app_state();
+    let supported =
+        crate::key_backup::create_backup_blob(&Keys::generate(), PASSWORD, FAST_LOG_N).unwrap();
+    let encrypted = crate::key_backup::parse_ncryptsec(&supported).unwrap();
+    let mut payload = encrypted.as_vec();
+    payload[1] = crate::key_backup::MAX_VERIFY_LOG_N + 1;
+    let unsupported = nostr::nips::nip49::EncryptedSecretKey::from_slice(&payload)
+        .unwrap()
+        .to_bech32()
+        .unwrap();
+
+    let err = verify_ncryptsec_backup_inner(&state, &unsupported, PASSWORD).unwrap_err();
+    assert_eq!(
+        err,
+        format!(
+            "unsupported backup KDF cost: log_n {} exceeds maximum {}",
+            crate::key_backup::MAX_VERIFY_LOG_N + 1,
+            crate::key_backup::MAX_VERIFY_LOG_N
+        )
+    );
+}
+
+#[test]
+fn rejects_short_passphrase() {
+    let state = build_app_state();
+    let err = create_backup_with_log_n(&state, "short", FAST_LOG_N).unwrap_err();
+    assert!(err.contains("at least"), "{err}");
+}
+
+#[test]
+fn recovery_mode_blocks_backup_creation() {
+    let state = build_app_state();
+
+    state
+        .identity_lost
+        .store(true, std::sync::atomic::Ordering::Release);
+    assert!(
+        create_backup_with_log_n(&state, PASSWORD, FAST_LOG_N).is_err(),
+        "lost identity must not be backed up"
+    );
+    state
+        .identity_lost
+        .store(false, std::sync::atomic::Ordering::Release);
+
+    state
+        .keyring_locked
+        .store(true, std::sync::atomic::Ordering::Release);
+    assert!(
+        create_backup_with_log_n(&state, PASSWORD, FAST_LOG_N).is_err(),
+        "locked keyring must not be backed up"
+    );
+}
+
+/// Concurrent identity changes serialize with backup creation.
+#[test]
+fn concurrent_identity_swap_vs_backup_is_serialized() {
+    let state = std::sync::Arc::new(build_app_state());
+    let key_a = state.keys.lock().unwrap().clone();
+    let key_b = Keys::generate();
+
+    let swapper = {
+        let state = state.clone();
+        let key_b = key_b.clone();
+        std::thread::spawn(move || {
+            // Mirrors import_identity's locking: mutation guard held
+            // across the key swap.
+            let _guard = state.identity_mutation.lock().unwrap();
+            *state.keys.lock().unwrap() = key_b;
+        })
+    };
+
+    let backup = create_backup_with_log_n(&state, PASSWORD, FAST_LOG_N).unwrap();
+    swapper.join().unwrap();
+
+    let recovered = crate::key_backup::decrypt_ncryptsec(&backup, PASSWORD)
+        .unwrap()
+        .public_key();
+    assert!(
+        recovered == key_a.public_key() || recovered == key_b.public_key(),
+        "backup must match one coherent identity"
+    );
+}
diff --git a/desktop/src-tauri/src/commands/media.rs b/desktop/src-tauri/src/commands/media.rs
index bf8692ff70..ed3b340238 100644
--- a/desktop/src-tauri/src/commands/media.rs
+++ b/desktop/src-tauri/src/commands/media.rs
@@ -411,7 +411,7 @@ fn should_retry_legacy_upload(status: reqwest::StatusCode) -> bool {
 }
 
 async fn send_upload_attempt(
-    state: &State<'_, AppState>,
+    state: &AppState,
     url: String,
     auth_header: &str,
     mime: &str,
@@ -455,10 +455,22 @@ async fn send_upload_attempt(
     response.map_err(|error| classify_request_error(&error))
 }
 
+pub(crate) async fn upload_image_bytes(
+    body: Vec<u8>,
+    state: &AppState,
+) -> Result<BlobDescriptor, String> {
+    let mime = detect_and_validate_mime(&body)?;
+    if !mime.starts_with("image/") {
+        return Err("profile avatar must be an image".to_string());
+    }
+    let body = sanitize_image_for_upload(body, &mime)?;
+    do_upload(body, &mime, state, None).await
+}
+
 async fn do_upload(
     body: Vec<u8>,
     mime: &str,
-    state: &State<'_, AppState>,
+    state: &AppState,
     progress: Option<(tauri::AppHandle, String)>,
 ) -> Result<BlobDescriptor, String> {
     let sha256 = hex::encode(Sha256::digest(&body));
@@ -559,7 +571,7 @@ pub async fn upload_media(
 /// files from ever leaving the client on image-only surfaces.
 async fn process_picked_path(
     path: std::path::PathBuf,
-    state: &State<'_, AppState>,
+    state: &AppState,
     images_only: bool,
 ) -> Result<BlobDescriptor, String> {
     // Pin the inode by opening the fd BEFORE spawn_blocking. This prevents a
diff --git a/desktop/src-tauri/src/commands/media_download.rs b/desktop/src-tauri/src/commands/media_download.rs
index d3b1a9499d..7bc94da25d 100644
--- a/desktop/src-tauri/src/commands/media_download.rs
+++ b/desktop/src-tauri/src/commands/media_download.rs
@@ -8,7 +8,8 @@ use crate::commands::export_util::save_bytes_with_dialog;
 use crate::commands::media::{detect_and_validate_mime, mint_media_get_auth, sanitize_filename};
 use crate::commands::{
     personas::{
-        decode_snapshot_from_bytes, MAX_SNAPSHOT_JSON_BYTES, MAX_SNAPSHOT_PNG_BYTES, PNG_MAGIC,
+        parse_snapshot_payload_from_bytes, MAX_SNAPSHOT_JSON_BYTES, MAX_SNAPSHOT_PNG_BYTES,
+        PNG_MAGIC,
     },
     team_snapshot::{
         decode_team_snapshot_from_bytes, MAX_TEAM_SNAPSHOT_JSON_BYTES, MAX_TEAM_SNAPSHOT_PNG_BYTES,
@@ -505,10 +506,12 @@ pub async fn fetch_snapshot_bytes(
 
     // 4. Bytes must parse as the snapshot type selected by the filename.
     //    Team parsing rejects retired flat JSON and persona-pack ZIP inputs
-    //    before anything reaches the frontend.
+    //    before anything reaches the frontend. Agent kinds accept both plain
+    //    manifests and structurally valid locked (encrypted) card envelopes —
+    //    transit validation never decrypts; unlock happens at import time.
     match kind {
         SnapshotFileKind::AgentJson | SnapshotFileKind::AgentPng => {
-            decode_snapshot_from_bytes(&bytes)
+            parse_snapshot_payload_from_bytes(&bytes)
                 .map_err(|e| format!("invalid agent snapshot: {e}"))?;
         }
         SnapshotFileKind::TeamJson | SnapshotFileKind::TeamPng => {
diff --git a/desktop/src-tauri/src/commands/media_snapshot_png.rs b/desktop/src-tauri/src/commands/media_snapshot_png.rs
index 734d8f5dc8..bcaec6a592 100644
--- a/desktop/src-tauri/src/commands/media_snapshot_png.rs
+++ b/desktop/src-tauri/src/commands/media_snapshot_png.rs
@@ -204,6 +204,7 @@ mod tests {
             s3_secret_key: String::new(),
             s3_bucket: String::new(),
             s3_region: "us-east-1".to_string(),
+            s3_addressing_style: buzz_media_pkg::S3AddressingStyle::Path,
             max_image_bytes: 50 * 1024 * 1024,
             max_gif_bytes: 10 * 1024 * 1024,
             max_video_bytes: 524_288_000,
diff --git a/desktop/src-tauri/src/commands/mesh_llm.rs b/desktop/src-tauri/src/commands/mesh_llm.rs
index 305c54a203..528ca38767 100644
--- a/desktop/src-tauri/src/commands/mesh_llm.rs
+++ b/desktop/src-tauri/src/commands/mesh_llm.rs
@@ -5,12 +5,35 @@ use tauri::{AppHandle, Manager, State};
 
 use crate::{app_state::AppState, mesh_llm, relay};
 
-#[derive(Debug, serde::Deserialize, serde::Serialize)]
+#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
 #[serde(rename_all = "camelCase")]
 struct MeshSharingConfig {
     enabled: bool,
+    /// A fresh Share Compute request that must cross a process boundary before
+    /// it can start. Consumed before startup so an interrupted download is not
+    /// resumed on a later launch.
+    #[serde(default)]
+    start_on_next_launch: bool,
     model_id: String,
     max_vram_gb: Option<u64>,
+    /// Community relay where Share Compute was explicitly enabled. Older
+    /// configs predate community binding and restore against the active relay.
+    #[serde(default)]
+    relay_url: Option<String>,
+}
+
+fn pending_new_start_checkpoint(config: &MeshSharingConfig) -> MeshSharingConfig {
+    let mut checkpoint = config.clone();
+    checkpoint.enabled = false;
+    checkpoint.start_on_next_launch = false;
+    checkpoint
+}
+
+fn one_shot_restart_checkpoint(config: &MeshSharingConfig) -> MeshSharingConfig {
+    let mut checkpoint = config.clone();
+    checkpoint.enabled = false;
+    checkpoint.start_on_next_launch = true;
+    checkpoint
 }
 
 fn mesh_sharing_config_path(app: &AppHandle) -> Result<PathBuf, String> {
@@ -89,8 +112,10 @@ fn sharing_config_from_request(
         .ok_or_else(|| "modelId is required for serve mode".to_string())?;
     Ok(MeshSharingConfig {
         enabled: true,
+        start_on_next_launch: false,
         model_id: model_id.to_string(),
         max_vram_gb: request.max_vram_gb,
+        relay_url: request.relay_url.clone(),
     })
 }
 
@@ -117,7 +142,7 @@ fn restart_to_share(
     app: &AppHandle,
     config: &MeshSharingConfig,
 ) -> CmdResult<mesh_llm::MeshNodeStatus> {
-    save_mesh_sharing_config(app, config)?;
+    save_mesh_sharing_config(app, &one_shot_restart_checkpoint(config))?;
     let status = restarting_share_status(config);
     app.request_restart();
     Ok(status)
@@ -133,7 +158,7 @@ fn buzz_mesh_name_for_relay(relay_url: &str) -> String {
     format!("buzz-community-{}", &digest[..32])
 }
 
-fn buzz_mesh_name(state: &AppState) -> String {
+pub(super) fn buzz_mesh_name(state: &AppState) -> String {
     buzz_mesh_name_for_relay(&relay::relay_ws_url_with_override(state))
 }
 
@@ -150,8 +175,13 @@ fn advance_mesh_status_cursor(
     Ok(cursor)
 }
 
-async fn query_mesh_discovery_events(state: &AppState) -> Result<Vec<nostr::Event>, String> {
-    let mut events = relay::query_relay(state, &[mesh_llm::relay_membership_filter()]).await?;
+async fn query_mesh_discovery_events_at(
+    state: &AppState,
+    relay_url: &str,
+) -> Result<Vec<nostr::Event>, String> {
+    let api_base_url = relay::relay_http_base_url(relay_url);
+    let mut events =
+        relay::query_relay_at(state, &api_base_url, &[mesh_llm::relay_membership_filter()]).await?;
     let member_pubkeys = mesh_llm::current_member_pubkeys(&events);
     if member_pubkeys.is_empty() {
         // Distinguish "relay returned a membership snapshot listing zero
@@ -172,7 +202,7 @@ async fn query_mesh_discovery_events(state: &AppState) -> Result<Vec<nostr::Even
     let mut previous_cursor: Option<(u64, String)> = None;
 
     loop {
-        let page = relay::query_relay(state, &[status_filter.clone()]).await?;
+        let page = relay::query_relay_at(state, &api_base_url, &[status_filter.clone()]).await?;
         let done = page.len() < mesh_llm::MESH_STATUS_PAGE_SIZE;
         if !done {
             let cursor = advance_mesh_status_cursor(&mut status_filter, &page)?;
@@ -188,6 +218,10 @@ async fn query_mesh_discovery_events(state: &AppState) -> Result<Vec<nostr::Even
     }
 }
 
+async fn query_mesh_discovery_events(state: &AppState) -> Result<Vec<nostr::Event>, String> {
+    query_mesh_discovery_events_at(state, &relay::relay_ws_url_with_override(state)).await
+}
+
 /// Resolve the admission roster by intersecting member-signed mesh status
 /// reporters with the current NIP-43 direct-member list.
 ///
@@ -201,6 +235,14 @@ pub(crate) async fn resolve_trusted_owner_ids(state: &AppState) -> Result<Vec<St
     Ok(mesh_llm::owner_ids_from_events(&events))
 }
 
+pub(crate) async fn resolve_trusted_owner_ids_at(
+    state: &AppState,
+    relay_url: &str,
+) -> Result<Vec<String>, String> {
+    let events = query_mesh_discovery_events_at(state, relay_url).await?;
+    Ok(mesh_llm::owner_ids_from_events(&events))
+}
+
 /// Resolve the roster for an initial node *start*, failing closed to self-only
 /// (an empty roster) when the relay query fails. This is safe only at start:
 /// there is no established allowlist to preserve yet. The periodic
@@ -244,10 +286,11 @@ fn buzz_mesh_join_targets(
 /// Resolve the validated member endpoint this runtime should join to enter the
 /// existing Buzz community mesh. `Ok(None)` means this machine is the first
 /// live serving member (or is itself the shared bootstrap contact).
-pub(crate) async fn resolve_buzz_mesh_join_targets(
+pub(crate) async fn resolve_buzz_mesh_join_targets_at(
     state: &AppState,
+    relay_url: &str,
 ) -> Result<Vec<mesh_llm::MeshServeTarget>, String> {
-    let events = query_mesh_discovery_events(state).await?;
+    let events = query_mesh_discovery_events_at(state, relay_url).await?;
     let self_owner_id = mesh_llm::ensure_owner_identity()
         .map_err(|error| format!("failed to load mesh owner identity: {error}"))?
         .owner_id;
@@ -261,8 +304,11 @@ pub(crate) async fn resolve_buzz_mesh_join_targets(
 /// snapshot. A node start used to repeat the full membership + status query
 /// for each value, making Share Compute startup both slower and more exposed
 /// to inconsistent snapshots.
-async fn resolve_buzz_mesh_startup(state: &AppState) -> (Vec<String>, Option<String>) {
-    match query_mesh_discovery_events(state).await {
+async fn resolve_buzz_mesh_startup_at(
+    state: &AppState,
+    relay_url: &str,
+) -> (Vec<String>, Option<String>) {
+    match query_mesh_discovery_events_at(state, relay_url).await {
         Ok(events) => {
             let trusted_owner_ids = mesh_llm::owner_ids_from_events(&events);
             let join_token = mesh_llm::ensure_owner_identity()
@@ -291,33 +337,66 @@ async fn resolve_buzz_mesh_startup(state: &AppState) -> (Vec<String>, Option<Str
 }
 
 pub(crate) async fn restore_mesh_sharing(app: &AppHandle, state: &AppState) -> CmdResult<()> {
-    let Some(config) = load_mesh_sharing_config(app)? else {
+    let Some(mut config) = load_mesh_sharing_config(app)? else {
         return Ok(());
     };
-    if !config.enabled || config.model_id.trim().is_empty() {
+    if (!config.enabled && !config.start_on_next_launch) || config.model_id.trim().is_empty() {
         return Ok(());
     }
+    config.model_id = mesh_llm::canonical_curated_model_id(&config.model_id).to_string();
     if state.mesh_llm_runtime.lock().await.is_some() {
         return Ok(());
     }
-    let (trusted_owner_ids, join_token) = resolve_buzz_mesh_startup(state).await;
+    let relay_url = config
+        .relay_url
+        .clone()
+        .unwrap_or_else(|| relay::relay_ws_url_with_override(state));
+    let (trusted_owner_ids, join_token) = resolve_buzz_mesh_startup_at(state, &relay_url).await;
     let mut runtime = state.mesh_llm_runtime.lock().await;
     if runtime.is_some() {
         return Ok(());
     }
+    if config.start_on_next_launch {
+        // Consume a role-switch request before doing any potentially long model
+        // work. If Buzz exits during that work, the next launch stays stopped.
+        config = pending_new_start_checkpoint(&config);
+        save_mesh_sharing_config(app, &config)?;
+    }
+    // This is restoration of a previously inference-ready serving node. Keep
+    // the enabled checkpoint armed while restoring so a transient startup
+    // failure does not silently turn Share Compute off.
     let request = mesh_llm::StartMeshNodeRequest {
         mode: mesh_llm::MeshNodeMode::Serve,
-        model_id: Some(config.model_id),
+        model_id: Some(config.model_id.clone()),
         max_vram_gb: config.max_vram_gb,
         join_token,
-        mesh_name: Some(buzz_mesh_name(state)),
+        mesh_name: Some(buzz_mesh_name_for_relay(&relay_url)),
+        relay_url: Some(relay_url),
         trusted_owner_ids: Some(trusted_owner_ids),
     };
     let started = mesh_llm::DesktopMeshRuntime::start(request)
         .await
         .map_err(|error| format!("failed to restore Share Compute: {error:#}"))?;
+    // Install the restored runtime immediately: it is tracked by AppState from
+    // here on, so it can never be orphaned. Restoring a previously
+    // inference-ready node still has to load ~tens of GB of weights and may
+    // download package layers after the ports bind, and the readiness probe
+    // itself serializes behind any first inference. None of that is a failed
+    // restore — stopping the node and reporting failure (the old behaviour)
+    // tore down a node that was simply still warming up. The checkpoint stays
+    // armed (`enabled`), so a genuinely broken restore is retried next launch
+    // rather than silently turning Share Compute off.
     *runtime = Some(started);
+    config.enabled = true;
+    config.start_on_next_launch = false;
+    save_mesh_sharing_config(app, &config)?;
     drop(runtime);
+    if let Err(error) = wait_for_mesh_inference(&config.model_id).await {
+        eprintln!(
+            "buzz-mesh: restored node is not inference-ready yet ({error}); \
+             leaving it to warm up without tearing it down"
+        );
+    }
     mesh_llm::publish_current_status_once(app, "restore").await;
     Ok(())
 }
@@ -328,6 +407,11 @@ pub async fn mesh_start_node(
     state: State<'_, AppState>,
     mut request: mesh_llm::StartMeshNodeRequest,
 ) -> CmdResult<mesh_llm::MeshNodeStatus> {
+    let relay_url = relay::relay_ws_url_with_override(&state);
+    request.relay_url = Some(relay_url.clone());
+    if let Some(model_id) = request.model_id.as_mut() {
+        *model_id = mesh_llm::canonical_curated_model_id(model_id).to_string();
+    }
     let sharing_config = if request.mode == mesh_llm::MeshNodeMode::Serve {
         Some(sharing_config_from_request(&request)?)
     } else {
@@ -362,13 +446,14 @@ pub async fn mesh_start_node(
     // Frontend requests never carry a roster. Resolve it and the bootstrap
     // endpoint from one snapshot so UI startup does not repeat relay probes.
     if request.trusted_owner_ids.is_none() || request.join_token.is_none() {
-        let (trusted_owner_ids, join_token) = resolve_buzz_mesh_startup(&state).await;
+        let (trusted_owner_ids, join_token) =
+            resolve_buzz_mesh_startup_at(&state, &relay_url).await;
         request.trusted_owner_ids.get_or_insert(trusted_owner_ids);
         if request.join_token.is_none() {
             request.join_token = join_token;
         }
     }
-    request.mesh_name = Some(buzz_mesh_name(&state));
+    request.mesh_name = Some(buzz_mesh_name_for_relay(&relay_url));
     let mut runtime = state.mesh_llm_runtime.lock().await;
 
     let plan = match runtime.as_ref() {
@@ -386,6 +471,15 @@ pub async fn mesh_start_node(
         return Err("mesh node is already running".to_string());
     }
 
+    if let Some(config) = sharing_config.as_ref() {
+        // Persist a DISARMED checkpoint to cover the window of the potentially
+        // long `start()` below: if Buzz exits before the runtime is installed
+        // and tracked, the next launch stays stopped rather than trying to
+        // restore a node that never came up. The enabled config is armed right
+        // after install succeeds.
+        save_mesh_sharing_config(&app, &pending_new_start_checkpoint(config))?;
+    }
+
     let started = mesh_llm::DesktopMeshRuntime::start(request)
         .await
         .map_err(|error| format!("{error:#}"))?;
@@ -409,10 +503,28 @@ pub async fn mesh_start_node(
             ));
         }
     };
+    // Install (track) the runtime BEFORE probing readiness so it can never be
+    // orphaned. A readiness timeout is not death: mesh binds its ports before
+    // weights finish loading / layers finish downloading, and serializes all
+    // ingress HTTP (this probe included) behind any in-flight turn — a cold
+    // start can take minutes. The old code stopped the node and restarted the
+    // app on that timeout, turning startup latency into a restart loop.
     *runtime = Some(started);
     drop(runtime);
     if let Some(config) = sharing_config.as_ref() {
+        // Installed + tracked == Share Compute is on, so persist the enabled
+        // config now (mirroring restore), not gated on the probe. Gating it
+        // meant a slow first start served fine but came back OFF next launch.
+        // Safe: neither the watchdog (evicts only a closed port) nor restore
+        // (leaves a warming node alone) can loop a slow-but-alive node, and an
+        // unstartable config fails earlier in `start()`. Probe is informational.
         save_mesh_sharing_config(&app, config)?;
+        if let Err(error) = wait_for_mesh_inference(&config.model_id).await {
+            eprintln!(
+                "buzz-mesh: node started but inference is not ready yet ({error}); \
+                 leaving it to warm up (Share Compute stays armed for next launch)"
+            );
+        }
     }
     mesh_llm::publish_current_status_once(&app, "start").await;
     Ok(status)
@@ -612,6 +724,7 @@ pub(crate) async fn ensure_client_node_for_model(
         max_vram_gb: None,
         join_token: Some(join_token.clone()),
         mesh_name: Some(buzz_mesh_name(state)),
+        relay_url: Some(relay::relay_ws_url_with_override(state)),
         trusted_owner_ids: Some(resolve_trusted_owner_ids_or_self_only(state).await),
     };
     let mut runtime = state.mesh_llm_runtime.lock().await;
@@ -753,6 +866,18 @@ pub(crate) async fn ensure_relay_mesh_for_record(
             }
         }
     }
+
+    // A persisted Share Compute configuration is authoritative about this
+    // machine's role. If no runtime is currently tracked (for example after a
+    // clean process restart), restore the serving node instead of treating an
+    // agent request as permission to replace it with a client node.
+    if load_mesh_sharing_config(app)?
+        .is_some_and(|config| config.enabled && !config.model_id.trim().is_empty())
+    {
+        restore_mesh_sharing(app, &state).await?;
+        return wait_for_mesh_inference(model_id).await;
+    }
+
     let target = match resolve_mesh_bootstrap_target(&state, model_id).await {
         Ok(Some(target)) => target,
         Ok(None) => {
@@ -768,15 +893,9 @@ pub(crate) async fn ensure_relay_mesh_for_record(
         }
     };
 
-    // Serve→Client re-arm transition (micspiral review #3, intentional-by-design):
-    // if the dead ingress belonged to a *serve* node with running consumer
-    // agents, this re-arms it as a Client (`MeshNodeMode::Client`). That is the
-    // correct/safe recovery here — config-backed serve restoration is
-    // `restore_mesh_sharing`'s job (`MeshNodeMode::Serve`), and
-    // `ensure_client_node_for_model` reuses any live runtime of *either* mode
-    // (the router resolves per-request), so it only cold-starts a Client when
-    // there is genuinely no runtime. Falling back to Client if a serve node
-    // crashed under local pressure is a desirable fail-safe, not a regression.
+    // No serving configuration exists, so this is a genuine consumer-only
+    // start. A configured serving machine is restored above and never reaches
+    // this client fallback.
     ensure_client_node_for_model(&state, model_id, Some(target.endpoint_addr)).await?;
     wait_for_mesh_inference(model_id).await
 }
@@ -792,14 +911,17 @@ pub async fn mesh_stop_node(
     // role under the lock and, when it's a consume session, leave it running
     // and return its live status unchanged. The frontend also guards this, but
     // status can be stale between polls, so the backend is authoritative.
-    let taken = {
+    let (taken, bound_relay_url) = {
         let mut guard = state.mesh_llm_runtime.lock().await;
         if let Some(runtime) = guard.as_ref() {
             if !share_stop_should_teardown(runtime.mode()) {
                 return runtime.status().await.map_err(|error| error.to_string());
             }
         }
-        guard.take()
+        let bound_relay_url = guard
+            .as_ref()
+            .and_then(|runtime| runtime.start_request().relay_url.clone());
+        (guard.take(), bound_relay_url)
     };
     if let Some(runtime) = taken {
         runtime.stop().await.map_err(|error| error.to_string())?;
@@ -808,11 +930,13 @@ pub async fn mesh_stop_node(
         &app,
         &MeshSharingConfig {
             enabled: false,
+            start_on_next_launch: false,
             model_id: String::new(),
             max_vram_gb: None,
+            relay_url: None,
         },
     )?;
-    mesh_llm::publish_stopped_status_once(&app, "stop").await;
+    mesh_llm::publish_stopped_status_once_at(&app, bound_relay_url.as_deref(), "stop").await;
     Ok(mesh_llm::stopped_status())
 }
 
diff --git a/desktop/src-tauri/src/commands/mesh_llm_tests.rs b/desktop/src-tauri/src/commands/mesh_llm_tests.rs
index ccc5287d62..26eb1f5fba 100644
--- a/desktop/src-tauri/src/commands/mesh_llm_tests.rs
+++ b/desktop/src-tauri/src/commands/mesh_llm_tests.rs
@@ -110,6 +110,74 @@ fn buzz_mesh_name_is_stable_and_does_not_expose_the_relay() {
     assert!(!first.contains("example"));
 }
 
+#[test]
+fn sharing_config_keeps_the_community_where_sharing_was_enabled() {
+    let request = mesh_llm::StartMeshNodeRequest {
+        mode: mesh_llm::MeshNodeMode::Serve,
+        model_id: Some("test-model".to_string()),
+        max_vram_gb: Some(24),
+        join_token: None,
+        mesh_name: Some("buzz-community-test".to_string()),
+        relay_url: Some("wss://community.example".to_string()),
+        trusted_owner_ids: Some(Vec::new()),
+    };
+
+    let config = sharing_config_from_request(&request).expect("valid sharing config");
+    assert_eq!(config.relay_url.as_deref(), Some("wss://community.example"));
+}
+
+#[test]
+fn legacy_sharing_config_without_community_binding_still_loads() {
+    let config: MeshSharingConfig = serde_json::from_value(serde_json::json!({
+        "enabled": true,
+        "modelId": "test-model",
+        "maxVramGb": null
+    }))
+    .expect("legacy sharing config");
+
+    assert_eq!(config.relay_url, None);
+    assert!(!config.start_on_next_launch);
+}
+
+#[test]
+fn new_start_checkpoint_prevents_incomplete_download_restore() {
+    let config = MeshSharingConfig {
+        enabled: true,
+        start_on_next_launch: false,
+        model_id: "test-model".to_string(),
+        max_vram_gb: Some(24),
+        relay_url: Some("wss://community.example".to_string()),
+    };
+
+    let checkpoint = pending_new_start_checkpoint(&config);
+    assert!(!checkpoint.enabled);
+    assert!(!checkpoint.start_on_next_launch);
+    assert_eq!(checkpoint.model_id, config.model_id);
+    assert_eq!(checkpoint.max_vram_gb, config.max_vram_gb);
+    assert_eq!(checkpoint.relay_url, config.relay_url);
+}
+
+#[test]
+fn role_switch_checkpoint_starts_exactly_once_after_restart() {
+    let config = MeshSharingConfig {
+        enabled: true,
+        start_on_next_launch: false,
+        model_id: "test-model".to_string(),
+        max_vram_gb: Some(24),
+        relay_url: Some("wss://community.example".to_string()),
+    };
+
+    let restart = one_shot_restart_checkpoint(&config);
+    assert!(!restart.enabled);
+    assert!(restart.start_on_next_launch);
+
+    let consumed = pending_new_start_checkpoint(&restart);
+    assert!(!consumed.enabled);
+    assert!(!consumed.start_on_next_launch);
+    assert_eq!(consumed.model_id, config.model_id);
+    assert_eq!(consumed.relay_url, config.relay_url);
+}
+
 #[test]
 fn readiness_failure_is_catalog_sync_when_model_never_visible() {
     assert_eq!(
@@ -345,6 +413,7 @@ fn ensure_serve_runtime_serves_other_model() {
                         max_vram_gb: None,
                         join_token: None,
                         mesh_name: None,
+                        relay_url: None,
                         trusted_owner_ids: None,
                     })
                     .await
diff --git a/desktop/src-tauri/src/commands/mod.rs b/desktop/src-tauri/src/commands/mod.rs
index 1c89ee4f77..66ef7ef17b 100644
--- a/desktop/src-tauri/src/commands/mod.rs
+++ b/desktop/src-tauri/src/commands/mod.rs
@@ -44,6 +44,7 @@ mod project_git;
 mod project_git_branches;
 mod project_git_diff;
 mod project_git_exec;
+mod project_git_merge_error;
 mod project_git_push;
 mod project_git_workflow;
 mod project_repo_paths;
diff --git a/desktop/src-tauri/src/commands/personas/card.rs b/desktop/src-tauri/src/commands/personas/card.rs
new file mode 100644
index 0000000000..c516db1736
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/card.rs
@@ -0,0 +1,972 @@
+//! `mint_agent_card` / `save_agent_card` Tauri commands — Agent Trading Cards.
+//!
+//! Mints a collectible trading-card PNG for an agent via one OpenAI Responses
+//! API call (designer model + native `image_generation` tool), then embeds the
+//! agent's `buzz_agent_snapshot` manifest through the existing snapshot
+//! encoder so the card IS an importable `.agent.png`.
+//!
+//! Boundary rules (agreed with Wren, buzz-agent-trading-cards thread):
+//! - Snapshot construction/injection reuses `agent_snapshot.rs` — cards
+//!   inherit manifest-v1 behavior, exclusions, and size checks. No card-only
+//!   wire format exists.
+//! - Memory inclusion is opt-in and shares the export flow's semantics: the
+//!   same three levels (`none`/`core`/`everything`), the same owner-gated
+//!   `get_agent_memory` fetch, and a memory source DERIVED from the resolved
+//!   instance (never caller-supplied), so cross-agent memory pairing is
+//!   structurally impossible. The default is `none`; the encoder still
+//!   rejects `none` + entries.
+//! - The 10 MiB `.agent.png` ceiling is enforced on the FINAL bytes (after
+//!   resize + chunk injection) via `validate_snapshot_encode_size`.
+//! - Round-trip verification decodes the final bytes and compares the logical
+//!   manifest before anything is returned to the frontend.
+//! - The API key is resolved through the same env layering the agent runtime
+//!   uses (global config < persona < agent record) and never leaves Rust.
+//!   It is never logged.
+
+use base64::{engine::general_purpose::STANDARD, Engine as _};
+use serde::{Deserialize, Serialize};
+use tauri::{AppHandle, State};
+
+use super::super::export_util::save_bytes_with_dialog;
+use super::snapshot::{
+    memory_entries_from_listing, parse_memory_level, resolve_from_lists,
+    validate_snapshot_encode_size,
+};
+use crate::{
+    app_state::AppState,
+    commands::engrams::get_agent_memory,
+    managed_agents::{
+        agent_snapshot::{
+            build_snapshot, decode_avatar_data_url, decode_snapshot_png, encode_snapshot_png,
+            extract_chunk_payload_png, MemoryLevel,
+        },
+        agent_snapshot_envelope::{
+            decrypt_envelope, encode_locked_snapshot_png, parse_chunk_payload, ChunkPayload,
+        },
+        load_agent_definitions, load_global_agent_config, load_managed_agents, load_personas,
+        save_global_agent_config, validate_global_config,
+    },
+};
+
+/// The Buzz card frame template — Tyler's gold-honeycomb base. Generation
+/// input only: it never participates in the snapshot manifest, PNG chunk,
+/// import decoder, or attachment validation. Embedded at compile time for
+/// deterministic packaging (see `card_template_decodes` test).
+const CARD_TEMPLATE_PNG: &[u8] = include_bytes!("../../../assets/card_template.png");
+
+/// Designer model driving copy + art direction.
+const DESIGNER_MODEL: &str = "gpt-5.6-sol";
+/// Image model invoked natively via the Responses `image_generation` tool.
+const IMAGE_MODEL: &str = "gpt-image-2";
+/// Final card width in pixels (2:3 portrait → 1500x2250).
+const CARD_WIDTH: u32 = 1500;
+/// Longest edge for the real avatar inlined into an unlocked card's manifest.
+/// Kind:0 pictures render small; 512px keeps the doubly-base64-encoded
+/// manifest chunk modest next to the 1500-wide card body.
+const MANIFEST_AVATAR_MAX_DIM: u32 = 512;
+/// Upper bound for a fetched avatar (pre-resize input to the model).
+const MAX_AVATAR_FETCH_BYTES: usize = 10 * 1024 * 1024;
+/// One mint is a single long API call (~2–3 minutes observed).
+const MINT_TIMEOUT_SECS: u64 = 600;
+
+/// Error prefix the frontend matches to route the user to provider settings
+/// instead of showing a raw failure.
+pub(crate) const NO_KEY_ERROR_PREFIX: &str = "NO_OPENAI_KEY:";
+
+/// Wire shape returned by `mint_agent_card`.
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MintedCard {
+    /// Final `.agent.png` bytes (chunk-injected, round-trip verified),
+    /// base64-encoded for the IPC boundary.
+    pub card_png_base64: String,
+    /// Suggested filename, e.g. `eva.agent.png`.
+    pub file_name: String,
+    /// Designer commentary emitted alongside the image (may be empty).
+    pub designer_notes: String,
+    /// True when the embedded snapshot is NIP-44-encrypted to the
+    /// (owner, agent) pair — only their nsecs can import this card.
+    pub locked: bool,
+    /// How much memory is embedded in the card's snapshot ("none"/"core"/
+    /// "everything"). The viewer's import disclosure depends on this.
+    pub memory_level: MemoryLevel,
+}
+
+// ── Card archive ──────────────────────────────────────────────────────────────
+
+/// Sidecar metadata for one archived card PNG. Stored as `<stem>.json` next
+/// to `<stem>.agent.png` in the cards dir — two plain files per mint, no
+/// shared index to corrupt. Listing scans sidecars; a card whose PNG is
+/// missing is skipped rather than failing the whole list.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ArchivedCardMeta {
+    /// Unique on-disk PNG file name within the cards dir.
+    pub stored_file_name: String,
+    /// Suggested save-as name, e.g. `eva.agent.png`.
+    pub file_name: String,
+    /// The id the card was minted for (instance pubkey or definition slug).
+    pub agent_id: String,
+    pub agent_name: String,
+    pub designer_notes: String,
+    pub locked: bool,
+    /// Memory embedded in this card's snapshot. Defaults to `None` when the
+    /// sidecar predates the field — every pre-field mint was minted with
+    /// `MemoryLevel::None` (it was structural), so the default is honest.
+    #[serde(default)]
+    pub memory_level: MemoryLevel,
+    /// ISO-8601 mint timestamp.
+    pub minted_at: String,
+    /// Small JPEG preview for gallery grids, base64. Populated by
+    /// `list_agent_cards` from the sidecar thumb file — never stored in the
+    /// JSON sidecar itself.
+    #[serde(default, skip_deserializing)]
+    pub thumb_jpeg_base64: Option<String>,
+}
+
+fn cards_dir(app: &AppHandle) -> Result<std::path::PathBuf, String> {
+    let dir = crate::managed_agents::managed_agents_base_dir(app)?.join("cards");
+    std::fs::create_dir_all(&dir).map_err(|e| format!("failed to create cards dir: {e}"))?;
+    Ok(dir)
+}
+
+/// Persist a freshly minted card to the archive. Failures are surfaced to the
+/// caller (which logs and continues) — an archive write must never fail a
+/// mint the user already paid for.
+fn archive_minted_card(
+    app: &AppHandle,
+    agent_id: &str,
+    agent_name: &str,
+    card: &MintedCard,
+    bytes: &[u8],
+) -> Result<ArchivedCardMeta, String> {
+    let dir = cards_dir(app)?;
+    let stem = format!(
+        "{}-{}",
+        crate::util::slugify(agent_name, "agent", 50),
+        uuid::Uuid::new_v4()
+    );
+    let stored_file_name = format!("{stem}.agent.png");
+    let meta = ArchivedCardMeta {
+        stored_file_name: stored_file_name.clone(),
+        file_name: card.file_name.clone(),
+        agent_id: agent_id.to_string(),
+        agent_name: agent_name.to_string(),
+        designer_notes: card.designer_notes.clone(),
+        locked: card.locked,
+        memory_level: card.memory_level,
+        minted_at: crate::util::now_iso(),
+        thumb_jpeg_base64: None,
+    };
+    // PNG first, sidecar second: a crash between the two leaves an orphaned
+    // PNG (invisible to the list), never a sidecar pointing at nothing.
+    std::fs::write(dir.join(&stored_file_name), bytes)
+        .map_err(|e| format!("failed to write archived card: {e}"))?;
+    let meta_json = serde_json::to_string_pretty(&meta)
+        .map_err(|e| format!("failed to serialize card metadata: {e}"))?;
+    std::fs::write(dir.join(format!("{stem}.json")), meta_json)
+        .map_err(|e| format!("failed to write card metadata: {e}"))?;
+    // Thumb last and best-effort: the gallery grid falls back to lazy
+    // full-card loading for a card whose thumb is missing.
+    if let Ok(thumb) = encode_card_thumb(bytes) {
+        let _ = std::fs::write(dir.join(format!("{stem}.thumb.jpg")), thumb);
+    }
+    Ok(meta)
+}
+
+/// Downscale card PNG bytes to a small JPEG for gallery grids. The full card
+/// is ~1500x2250 PNG (megabytes); shipping that per card over IPC just to
+/// draw a grid tile is waste.
+fn encode_card_thumb(bytes: &[u8]) -> Result<Vec<u8>, String> {
+    const THUMB_WIDTH: u32 = 300;
+    let img = image::load_from_memory(bytes).map_err(|e| format!("thumb decode: {e}"))?;
+    let scale = THUMB_WIDTH as f64 / img.width() as f64;
+    let thumb = img.resize(
+        THUMB_WIDTH,
+        (img.height() as f64 * scale).round().max(1.0) as u32,
+        image::imageops::FilterType::Triangle,
+    );
+    let mut out = Vec::new();
+    // JPEG has no alpha; cards are opaque, so flatten unconditionally.
+    let rgb = image::DynamicImage::ImageRgb8(thumb.to_rgb8());
+    rgb.write_to(
+        &mut std::io::Cursor::new(&mut out),
+        image::ImageFormat::Jpeg,
+    )
+    .map_err(|e| format!("thumb encode: {e}"))?;
+    Ok(out)
+}
+
+/// Reject any archive file name that could escape the cards dir or name a
+/// non-archive file. Archive names are generated by `archive_minted_card`
+/// (slug + UUID), so a strict shape check loses nothing legitimate.
+fn validate_archive_file_name(stored_file_name: &str) -> Result<(), String> {
+    let valid = stored_file_name.ends_with(".agent.png")
+        && !stored_file_name.contains(['/', '\\'])
+        && !stored_file_name.contains("..");
+    if !valid {
+        return Err("Invalid archived card file name.".to_string());
+    }
+    Ok(())
+}
+
+/// List all archived cards, newest first.
+#[tauri::command]
+pub fn list_agent_cards(app: AppHandle) -> Result<Vec<ArchivedCardMeta>, String> {
+    let dir = cards_dir(&app)?;
+    let entries = std::fs::read_dir(&dir).map_err(|e| format!("failed to read cards dir: {e}"))?;
+    let mut cards = Vec::new();
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if path.extension().and_then(|e| e.to_str()) != Some("json") {
+            continue;
+        }
+        let Ok(content) = std::fs::read_to_string(&path) else {
+            continue;
+        };
+        let Ok(meta) = serde_json::from_str::<ArchivedCardMeta>(&content) else {
+            // A malformed sidecar hides one card, never the archive.
+            eprintln!(
+                "buzz-desktop: card-archive: skipping malformed sidecar {}",
+                path.display()
+            );
+            continue;
+        };
+        let mut meta = meta;
+        if validate_archive_file_name(&meta.stored_file_name).is_ok()
+            && dir.join(&meta.stored_file_name).is_file()
+        {
+            // Attach the pre-rendered grid thumb when present (best-effort).
+            if let Some(stem) = path.file_stem().and_then(|s| s.to_str()) {
+                meta.thumb_jpeg_base64 = std::fs::read(dir.join(format!("{stem}.thumb.jpg")))
+                    .ok()
+                    .map(|b| STANDARD.encode(&b));
+            }
+            cards.push(meta);
+        }
+    }
+    // ISO-8601 sorts lexicographically; newest first.
+    cards.sort_by(|a, b| b.minted_at.cmp(&a.minted_at));
+    Ok(cards)
+}
+
+/// Load one archived card's PNG bytes as base64, keyed by its stored file
+/// name (as returned by `list_agent_cards`).
+#[tauri::command]
+pub fn load_agent_card(stored_file_name: String, app: AppHandle) -> Result<String, String> {
+    validate_archive_file_name(&stored_file_name)?;
+    let bytes = std::fs::read(cards_dir(&app)?.join(&stored_file_name))
+        .map_err(|e| format!("failed to read archived card: {e}"))?;
+    Ok(STANDARD.encode(&bytes))
+}
+
+// ── Key resolution ────────────────────────────────────────────────────────────
+
+/// Pure layering: global env < persona env < agent record env, then the
+/// process environment as a development fallback. Returns the first
+/// non-empty value for `key`.
+pub(crate) fn resolve_env_from_layers(
+    key: &str,
+    global_env: &std::collections::BTreeMap<String, String>,
+    persona_env: &std::collections::BTreeMap<String, String>,
+    record_env: &std::collections::BTreeMap<String, String>,
+    process_value: Option<String>,
+) -> Option<String> {
+    for layer in [record_env, persona_env, global_env] {
+        if let Some(v) = layer.get(key) {
+            let v = v.trim();
+            if !v.is_empty() {
+                return Some(v.to_string());
+            }
+        }
+    }
+    process_value.filter(|k| !k.trim().is_empty())
+}
+
+/// The Responses endpoint to post mints to. `OPENAI_BASE_URL` (same env
+/// layering as the key) overrides the default host, supporting endpoints and
+/// proxies that speak the OpenAI Responses shape with Bearer auth. Azure
+/// OpenAI is NOT covered by this override alone — it uses its own URL scheme
+/// and `api-key` auth header, which would need a real driver.
+pub(crate) fn responses_url(base_url: Option<String>) -> String {
+    let base = base_url.unwrap_or_else(|| "https://api.openai.com/v1".to_string());
+    format!("{}/responses", base.trim_end_matches('/'))
+}
+
+// ── Prompt construction ───────────────────────────────────────────────────────
+
+/// Build the designer instructions. Pure so tests can pin the contract:
+/// style-match-the-avatar is DEFAULT behavior; owner directions (art AND
+/// card text) take primacy over those style defaults, but never over the
+/// fixed contract (frame identity, geometry, text fidelity).
+pub(crate) fn build_card_instructions(
+    agent_name: &str,
+    persona_notes: &str,
+    style_notes: &str,
+) -> String {
+    let owner_directions = if style_notes.trim().is_empty() {
+        String::new()
+    } else {
+        format!(
+            "\nOWNER'S DIRECTIONS — these override the default art-style and copy guidance \
+             below wherever they conflict (they cannot change the frame, layout, or \
+             text-fidelity requirements). The owner may direct the art, the card text \
+             (type line, ability, flavor), or both:\n{style_notes}\n"
+        )
+    };
+    format!(
+        r#"You are designing one premium collectible trading card for the Buzz agent "{agent_name}".
+
+Input image 1 is the official Buzz card frame template (gold honeycomb border, dark interior, name banner top, hex badge top-right, text box lower third). Input image 2 is the agent's avatar — study its exact art style: medium, pixel grid if any, palette, shading, background motifs.
+
+Persona notes for the card copy:
+{persona_notes}
+{owner_directions}
+First, write professional trading-card copy at Magic: The Gathering editorial quality:
+- a type line (e.g. "Legendary Agent — Team Lead"),
+- ONE keyworded ability: short bolded ability name + one sentence of crisp rules text written like real MTG rules (present tense, precise, no fluff),
+- ONE italic flavor-text line, evocative and short, the kind that gets quoted.
+Where the owner's directions specify card text, use their wording within the 220-character text-box limit below (edited only for spelling; if their text exceeds the limit, condense it minimally while keeping their words and intent); invent copy only for the parts they left open.
+Keep total text-box copy under 220 characters so it renders cleanly.
+
+Then generate the finished card with the image tool, exactly 1024x1536 portrait:
+- The frame must follow input image 1 faithfully: same gold honeycomb border, same layout, honey drip detail.
+- Default art style: match input image 2's art style EXACTLY — same medium, same pixel density if pixel art, same palette, same background honeycomb-lattice sky. It must look like the same artist drew a larger scene: the character in a confident pose, conjuring glowing golden hexagons. The owner's directions above override any of this default styling where they conflict.
+- Name banner: "{agent_name}" plus the type line beneath it in smaller type.
+- Text box: the ability name in bold, rules text in regular, then the flavor line in italics, cleanly typeset like a real MTG card — professional kerning, no misspellings, hyphenate nothing.
+- Top-right hex badge: one small emblem of your choice, no text.
+Render all text with perfect fidelity."#
+    )
+}
+
+/// Encode raw image bytes as a `data:image/png;base64,` URL, downscaling to
+/// `max_dim` on the longest edge so request payloads stay small.
+fn image_data_url(bytes: &[u8], max_dim: u32) -> Result<String, String> {
+    Ok(format!(
+        "data:image/png;base64,{}",
+        STANDARD.encode(png_bytes_resized(bytes, max_dim)?)
+    ))
+}
+
+/// Re-encode an image as PNG, downscaling so neither side exceeds `max_dim`.
+fn png_bytes_resized(bytes: &[u8], max_dim: u32) -> Result<Vec<u8>, String> {
+    let img = image::load_from_memory(bytes).map_err(|e| format!("Failed to decode image: {e}"))?;
+    let img = if img.width().max(img.height()) > max_dim {
+        img.resize(max_dim, max_dim, image::imageops::FilterType::Lanczos3)
+    } else {
+        img
+    };
+    let mut png = Vec::new();
+    img.write_to(&mut std::io::Cursor::new(&mut png), image::ImageFormat::Png)
+        .map_err(|e| format!("Failed to encode image: {e}"))?;
+    Ok(png)
+}
+
+// ── Response parsing ──────────────────────────────────────────────────────────
+
+/// Extract the generated image (base64) and any designer text from a
+/// Responses API payload. Pure for testability.
+pub(crate) fn extract_card_output(resp: &serde_json::Value) -> Result<(String, String), String> {
+    let output = resp
+        .get("output")
+        .and_then(|o| o.as_array())
+        .ok_or_else(|| "Responses payload has no output array".to_string())?;
+
+    let mut image_b64 = None;
+    let mut notes = Vec::new();
+    for item in output {
+        match item.get("type").and_then(|t| t.as_str()) {
+            Some("image_generation_call") => {
+                if let Some(result) = item.get("result").and_then(|r| r.as_str()) {
+                    image_b64 = Some(result.to_string());
+                }
+            }
+            Some("message") => {
+                if let Some(content) = item.get("content").and_then(|c| c.as_array()) {
+                    for c in content {
+                        if c.get("type").and_then(|t| t.as_str()) == Some("output_text") {
+                            if let Some(text) = c.get("text").and_then(|t| t.as_str()) {
+                                notes.push(text.to_string());
+                            }
+                        }
+                    }
+                }
+            }
+            _ => {}
+        }
+    }
+
+    let image_b64 = image_b64.ok_or_else(|| {
+        let types: Vec<&str> = output
+            .iter()
+            .filter_map(|i| i.get("type").and_then(|t| t.as_str()))
+            .collect();
+        format!("No image in Responses output (item types: {types:?})")
+    })?;
+    Ok((image_b64, notes.join("\n")))
+}
+
+// ── Commands ──────────────────────────────────────────────────────────────────
+
+/// Save an `OPENAI_API_KEY` into the global Agent Defaults env for card
+/// minting — a narrow seam with deliberately different semantics from the
+/// general `set_global_agent_config`:
+///
+/// - **No agent restarts.** The general command stops/restarts every running
+///   local agent whose effective env changes, because agent env is baked at
+///   spawn time. The mint command re-reads the config from disk on every
+///   mint, so minting needs no restart — and a card setup must never disrupt
+///   running agents as a side effect. Agents pick the key up naturally on
+///   their next (re)start.
+/// - **Read-modify-write of the latest on-disk config.** The config is
+///   re-read immediately before the single-key insert + write (under the
+///   managed-agents store lock, which serializes it against the other card
+///   and agent-store commands), so a settings save that landed after this
+///   dialog opened is not clobbered with a stale dialog-open snapshot.
+///   (The general settings editor performs its own whole-config write; as
+///   today, the last writer wins between the two surfaces.)
+///
+/// Standard global-config validation still applies (POSIX key shape,
+/// reserved-key reject, size caps) — this is not a validation bypass.
+#[tauri::command]
+pub fn card_mint_save_openai_key(
+    key: String,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let key = key.trim().to_string();
+    if key.is_empty() {
+        return Err("API key cannot be empty.".to_string());
+    }
+
+    let _store_guard = state
+        .managed_agents_store_lock
+        .lock()
+        .map_err(|e| e.to_string())?;
+
+    let mut config = load_global_agent_config(&app)?;
+    config.env_vars.insert("OPENAI_API_KEY".to_string(), key);
+    validate_global_config(&config)?;
+    save_global_agent_config(&app, &config)
+}
+
+/// Report whether an OpenAI key would resolve for a card mint of agent `id`,
+/// using exactly the same env layering as `mint_agent_card`. Lets the mint
+/// dialog offer inline key setup BEFORE the user commits to a mint, instead
+/// of failing after the fact. Never returns the key itself.
+#[tauri::command]
+pub fn card_mint_key_status(
+    id: String,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<bool, String> {
+    let _store_guard = state
+        .managed_agents_store_lock
+        .lock()
+        .map_err(|e| e.to_string())?;
+
+    let instances = load_managed_agents(&app)?;
+    let definitions = load_agent_definitions(&app)?;
+    let (record, _) = resolve_from_lists(&id, &instances, &definitions)?;
+
+    let global = load_global_agent_config(&app).unwrap_or_default();
+    let personas = load_personas(&app).unwrap_or_default();
+    let persona_env = record
+        .persona_id
+        .as_deref()
+        .and_then(|pid| personas.iter().find(|p| p.id == pid))
+        .map(|p| p.env_vars.clone())
+        .unwrap_or_default();
+
+    Ok(resolve_env_from_layers(
+        "OPENAI_API_KEY",
+        &global.env_vars,
+        &persona_env,
+        &record.env_vars,
+        std::env::var("OPENAI_API_KEY").ok(),
+    )
+    .is_some())
+}
+
+/// Mint a trading card for the agent identified by `id` (instance pubkey,
+/// instance slug, or definition slug — same resolution as snapshot export).
+///
+/// When `lock` is true the embedded manifest is NIP-44-encrypted to the
+/// (owner, agent) pair per the locked-envelope contract — this requires a
+/// linked agent instance (the second key endpoint); bare definitions cannot
+/// be locked.
+///
+/// When `memory_level` is `"core"` or `"everything"`, the owner's decrypted
+/// memory for the agent is embedded in the manifest — same levels and fetch
+/// as snapshot export. The memory source is always the resolved instance
+/// itself (derived, never caller-supplied), so it requires a linked instance;
+/// bare definitions can only mint `"none"` (the default).
+///
+/// Returns the final, chunk-injected, round-trip-verified `.agent.png` bytes.
+/// Reroll = call again; the command holds no session state.
+#[tauri::command]
+pub async fn mint_agent_card(
+    id: String,
+    style_notes: Option<String>,
+    lock: Option<bool>,
+    memory_level: Option<String>,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<MintedCard, String> {
+    let lock = lock.unwrap_or(false);
+    let memory_level = parse_memory_level(memory_level.as_deref().unwrap_or(""))?;
+    // ── Resolve the record + API key under lock ──────────────────────────────
+    let (mut record, is_definition, api_key, base_url) = {
+        let _store_guard = state
+            .managed_agents_store_lock
+            .lock()
+            .map_err(|e| e.to_string())?;
+
+        let instances = load_managed_agents(&app)?;
+        let definitions = load_agent_definitions(&app)?;
+        let (record, is_definition) =
+            resolve_from_lists(&id, &instances, &definitions).map(|(r, d)| (r.clone(), d))?;
+
+        let global = load_global_agent_config(&app).unwrap_or_default();
+        let personas = load_personas(&app).unwrap_or_default();
+        let persona_env = record
+            .persona_id
+            .as_deref()
+            .and_then(|pid| personas.iter().find(|p| p.id == pid))
+            .map(|p| p.env_vars.clone())
+            .unwrap_or_default();
+
+        let api_key = resolve_env_from_layers(
+            "OPENAI_API_KEY",
+            &global.env_vars,
+            &persona_env,
+            &record.env_vars,
+            std::env::var("OPENAI_API_KEY").ok(),
+        )
+        .ok_or_else(|| {
+            format!(
+                "{NO_KEY_ERROR_PREFIX} No OPENAI_API_KEY found. Add one in the agent's \
+                 environment variables or global agent settings to mint cards."
+            )
+        })?;
+        let base_url = resolve_env_from_layers(
+            "OPENAI_BASE_URL",
+            &global.env_vars,
+            &persona_env,
+            &record.env_vars,
+            std::env::var("OPENAI_BASE_URL").ok(),
+        );
+
+        (record, is_definition, api_key, base_url)
+    };
+
+    // ── Locking needs its two exact key endpoints up front, BEFORE the
+    //    API spend: the owner identity secret and the agent instance pubkey.
+    let lock_keys = if lock {
+        if is_definition {
+            return Err(
+                "Locked cards need a linked agent instance — this persona has never been \
+                 started, so there is no agent key to lock to."
+                    .to_string(),
+            );
+        }
+        let owner_keys = state.signing_keys()?;
+        // Same canonical check the envelope decoder enforces (incl. curve
+        // validation) — a non-point record pubkey must fail BEFORE the API
+        // spend, not at post-mint encryption.
+        let agent_pubkey = crate::managed_agents::agent_snapshot_envelope::parse_canonical_pubkey(
+            "agentPubkey",
+            &record.pubkey,
+        )
+        .map_err(|_| {
+            "Agent record has an invalid pubkey (not a canonical x-only key).".to_string()
+        })?;
+        if owner_keys.public_key() == agent_pubkey {
+            return Err("Cannot lock a card to itself: owner and agent keys match.".to_string());
+        }
+        Some((owner_keys, agent_pubkey))
+    } else {
+        None
+    };
+
+    // ── Memory needs a keyed instance, resolved up front BEFORE the API
+    //    spend — the memory source is always the resolved instance itself
+    //    (derived, never caller-supplied), so cross-agent pairing cannot be
+    //    expressed. A failed fetch fails the mint here, not after payment.
+    let memory_entries = if memory_level == MemoryLevel::None {
+        Vec::new()
+    } else {
+        if is_definition {
+            return Err(
+                "Cards with memory need a linked agent instance — this persona has never \
+                 been started, so there is no agent memory to include."
+                    .to_string(),
+            );
+        }
+        let listing = get_agent_memory(record.pubkey.clone(), app.clone(), state.clone()).await?;
+        memory_entries_from_listing(listing, memory_level)
+    };
+
+    let display_name = record
+        .display_name
+        .clone()
+        .unwrap_or_else(|| record.name.clone());
+
+    // ── Prefer the agent's own kind:0 profile picture ────────────────────────
+    // The record's `avatar_url` is a stale presentation snapshot: with
+    // agent-managed profiles the agent updates its own kind:0 `picture` and
+    // desktop reconciliation is disabled (`agent_settings.rs`), so the relay
+    // profile — not the local record — is the live source of truth for how the
+    // agent looks. Definitions have no keypair and thus no kind:0; they keep
+    // the record's avatar. A relay error fails the mint here, BEFORE the API
+    // spend (same fail-early rule as the key/memory guards above) — minting
+    // with the wrong face wastes the spend it was supposed to protect.
+    if !is_definition {
+        let relay_url = crate::relay::effective_agent_relay_url(
+            &record.relay_url,
+            &crate::relay::relay_ws_url_with_override(&state),
+        );
+        let profile = crate::relay::query_agent_profile(&state, &relay_url, &record.pubkey)
+            .await
+            .map_err(|e| format!("Could not read the agent's profile for its avatar: {e}"))?;
+        record.avatar_url = preferred_avatar_url(
+            profile.and_then(|info| info.picture),
+            record.avatar_url.take(),
+        );
+    }
+
+    // ── Resolve avatar bytes (data URL, else fetch) ──────────────────────────
+    let avatar_bytes = match record.avatar_url.as_deref() {
+        Some(url) if url.starts_with("data:") => decode_avatar_data_url(url)
+            .ok_or_else(|| "Agent avatar data URL could not be decoded.".to_string())?,
+        Some(url) if url.starts_with("http://") || url.starts_with("https://") => {
+            // Relay-hosted avatars (kind:0 pictures under the relay's /media/)
+            // may require Blossom get-auth (`require_media_get_auth`). Mint the
+            // header ONLY for same-origin URLs so the token never leaves the
+            // relay (same contract as `media_download.rs`).
+            let relay_base = crate::relay::relay_api_base_url_with_override(&state);
+            let auth = is_same_origin(url, &relay_base)
+                .then(|| crate::commands::media::mint_media_get_auth(&state, &relay_base))
+                .flatten();
+            fetch_avatar(url, auth.as_deref()).await?
+        }
+        _ => {
+            return Err(
+                "Agent has no avatar image. Set an avatar before minting a card.".to_string(),
+            )
+        }
+    };
+
+    // ── Build the manifest now (with any requested memory) so a broken agent
+    //    fails before we spend minutes on the API call. ───────────────────────
+    let manifest_avatar = manifest_avatar_bytes(
+        lock_keys.is_some(),
+        &avatar_bytes,
+        record.avatar_url.as_deref(),
+    )?;
+    let snapshot = build_snapshot(
+        &record,
+        memory_level,
+        memory_entries,
+        manifest_avatar.as_deref(),
+    );
+
+    // ── One Responses API call ───────────────────────────────────────────────
+    // For locked mints, prove the manifest (including any embedded memory)
+    // fits the NIP-44 plaintext cap BEFORE spending minutes on the API call
+    // (same fail-early rule as the memory guard above).
+    if lock_keys.is_some() {
+        let json_len =
+            crate::managed_agents::agent_snapshot::encode_snapshot_json(&snapshot)?.len();
+        if json_len > buzz_core_pkg::engram::NIP44_PLAINTEXT_MAX {
+            let hint = if memory_level == MemoryLevel::None {
+                "Reduce the avatar size or mint an unlocked card."
+            } else {
+                "Include less memory, reduce the avatar size, or mint an unlocked card."
+            };
+            return Err(format!(
+                "Agent manifest is too large to lock ({json_len} bytes; the encrypted \
+                 format caps at {}). {hint}",
+                buzz_core_pkg::engram::NIP44_PLAINTEXT_MAX
+            ));
+        }
+    }
+    let instructions = build_card_instructions(
+        &display_name,
+        snapshot.definition.system_prompt.as_deref().unwrap_or(""),
+        style_notes.as_deref().unwrap_or(""),
+    );
+    let body = serde_json::json!({
+        "model": DESIGNER_MODEL,
+        "reasoning": {"effort": "high"},
+        "instructions": "You are a senior TCG card designer and MTG rules editor.",
+        "input": [{
+            "role": "user",
+            "content": [
+                {"type": "input_text", "text": instructions},
+                {"type": "input_image", "image_url": image_data_url(CARD_TEMPLATE_PNG, 1024)?},
+                {"type": "input_image", "image_url": image_data_url(&avatar_bytes, 1024)?},
+            ],
+        }],
+        "tools": [{
+            "type": "image_generation",
+            "model": IMAGE_MODEL,
+            "quality": "high",
+            "size": "1024x1536",
+            "output_format": "png",
+        }],
+        "tool_choice": "required",
+    });
+
+    let client = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(MINT_TIMEOUT_SECS))
+        .build()
+        .map_err(|e| format!("Failed to build HTTP client: {e}"))?;
+    let resp = client
+        .post(responses_url(base_url))
+        .bearer_auth(&api_key)
+        .json(&body)
+        .send()
+        .await
+        .map_err(|e| format!("Card mint request failed: {e}"))?;
+
+    let status = resp.status();
+    let payload: serde_json::Value = resp
+        .json()
+        .await
+        .map_err(|e| format!("Card mint response was not JSON: {e}"))?;
+    if !status.is_success() {
+        // Never echo the request (it embeds nothing secret, but keep the
+        // failure surface small); the OpenAI error body is safe to surface.
+        let detail = payload
+            .get("error")
+            .and_then(|e| e.get("message"))
+            .and_then(|m| m.as_str())
+            .unwrap_or("unknown error");
+        return Err(format!("Card mint failed (HTTP {status}): {detail}"));
+    }
+
+    let (image_b64, designer_notes) = extract_card_output(&payload)?;
+    let raw_card = STANDARD
+        .decode(image_b64.as_bytes())
+        .map_err(|e| format!("Generated image was not valid base64: {e}"))?;
+
+    // ── Resize to 1500-wide, inject chunk via the existing encoder ──────────
+    let card_img = image::load_from_memory(&raw_card)
+        .map_err(|e| format!("Generated image could not be decoded: {e}"))?;
+    let scale = CARD_WIDTH as f64 / card_img.width() as f64;
+    let card_img = card_img.resize(
+        CARD_WIDTH,
+        (card_img.height() as f64 * scale).round() as u32,
+        image::imageops::FilterType::Lanczos3,
+    );
+    let mut card_png = Vec::new();
+    card_img
+        .write_to(
+            &mut std::io::Cursor::new(&mut card_png),
+            image::ImageFormat::Png,
+        )
+        .map_err(|e| format!("Failed to encode card PNG: {e}"))?;
+
+    let final_bytes = match &lock_keys {
+        None => encode_snapshot_png(&snapshot, Some(&card_png))
+            .map_err(|e| format!("Failed to embed agent snapshot in card: {e}"))?,
+        Some((owner_keys, agent_pubkey)) => {
+            encode_locked_snapshot_png(&snapshot, owner_keys, agent_pubkey, Some(&card_png))
+                .map_err(|e| format!("Failed to embed locked agent snapshot in card: {e}"))?
+        }
+    };
+
+    // ── Verify: size ceiling + round-trip on the FINAL bytes ────────────────
+    // Locked cards: extract the actual chunk, parse the envelope, decrypt
+    // with the owner key, then compare the logical manifest (ciphertext is
+    // nondeterministic — never compare bytes).
+    validate_snapshot_encode_size(final_bytes.len(), true)?;
+    let decoded = match &lock_keys {
+        None => decode_snapshot_png(&final_bytes)
+            .map_err(|e| format!("Card failed round-trip verification: {e}"))?,
+        Some((owner_keys, _)) => {
+            let payload = extract_chunk_payload_png(&final_bytes)
+                .map_err(|e| format!("Card failed round-trip verification: {e}"))?;
+            match parse_chunk_payload(&payload)
+                .map_err(|e| format!("Card failed round-trip verification: {e}"))?
+            {
+                ChunkPayload::Locked(envelope) => {
+                    decrypt_envelope(&envelope, owner_keys.secret_key())
+                        .map_err(|e| format!("Card failed round-trip verification: {e}"))?
+                }
+                ChunkPayload::Plain(_) => {
+                    return Err(
+                        "Card round-trip verification failed: expected a locked envelope."
+                            .to_string(),
+                    )
+                }
+            }
+        }
+    };
+    if decoded != snapshot {
+        return Err("Card round-trip verification failed: manifest mismatch.".to_string());
+    }
+
+    let slug = crate::util::slugify(&display_name, "agent", 50);
+    let minted = MintedCard {
+        card_png_base64: STANDARD.encode(&final_bytes),
+        file_name: format!("{slug}.agent.png"),
+        designer_notes,
+        locked: lock_keys.is_some(),
+        memory_level,
+    };
+
+    // Archive best-effort: the mint is already paid for and verified, so a
+    // failed archive write logs and continues — it never fails the mint.
+    if let Err(e) = archive_minted_card(&app, &id, &display_name, &minted, &final_bytes) {
+        eprintln!("buzz-desktop: card-archive: failed to archive minted card: {e}");
+    }
+
+    Ok(minted)
+}
+
+/// The avatar the mint should use: the agent's kind:0 `picture` when one is
+/// published and non-blank, else the local record's `avatar_url`.
+///
+/// Pure so the precedence is unit-testable without a relay: a blank or
+/// whitespace-only `picture` must NOT shadow a real record avatar.
+fn preferred_avatar_url(
+    kind0_picture: Option<String>,
+    record_avatar_url: Option<String>,
+) -> Option<String> {
+    kind0_picture
+        .filter(|p| !p.trim().is_empty())
+        .or(record_avatar_url)
+}
+
+/// The avatar bytes the card manifest should inline.
+///
+/// Unlocked cards must carry the agent's REAL avatar inline: the PNG body is
+/// the generated card artwork, and the importer only adopts the body as the
+/// avatar when the manifest carries no inline bytes (`import.rs`) — without
+/// these bytes an imported agent would wear the card as its face. Downscaled
+/// to [`MANIFEST_AVATAR_MAX_DIM`] so the manifest tEXt chunk stays small.
+///
+/// Locked cards keep the data-URL-only behavior: the whole manifest must fit
+/// the NIP-44 plaintext cap (65 KB), which cannot carry inline pixels, and a
+/// locked envelope never reaches the import body override anyway.
+fn manifest_avatar_bytes(
+    locked: bool,
+    avatar_bytes: &[u8],
+    record_avatar_url: Option<&str>,
+) -> Result<Option<Vec<u8>>, String> {
+    if locked {
+        return Ok(decode_avatar_data_url(record_avatar_url.unwrap_or("")));
+    }
+    png_bytes_resized(avatar_bytes, MANIFEST_AVATAR_MAX_DIM)
+        .map(Some)
+        .map_err(|e| format!("Failed to inline the agent avatar into the card manifest: {e}"))
+}
+
+/// True when `url` shares an origin (scheme, host, port) with `relay_base`.
+///
+/// Gate for attaching the minted media get-auth header — the token must never
+/// be sent to a non-relay origin (same contract as `validate_download_url` in
+/// `media_download.rs`, but non-fatal: a foreign origin just fetches
+/// unauthenticated instead of failing the mint).
+fn is_same_origin(url: &str, relay_base: &str) -> bool {
+    match (url::Url::parse(url), url::Url::parse(relay_base)) {
+        (Ok(u), Ok(b)) => u.origin() == b.origin(),
+        _ => false,
+    }
+}
+
+/// Fetch an avatar over HTTP with a hard size cap.
+///
+/// `auth` is an optional pre-minted Blossom get-auth header value, attached
+/// verbatim — the caller is responsible for only supplying it for
+/// relay-origin URLs. Redirects are not followed when auth is present
+/// (redirect-hop guard, same rule as `media_download.rs`).
+///
+/// The cap bounds network and memory, not just the final buffer: the
+/// Content-Length header is checked before any body bytes are read, and the
+/// body is streamed with a running count so a missing or dishonest header
+/// still cannot exceed the cap (same contract as `media_download.rs`).
+async fn fetch_avatar(url: &str, auth: Option<&str>) -> Result<Vec<u8>, String> {
+    use futures_util::StreamExt;
+
+    let mut builder = reqwest::Client::builder().timeout(std::time::Duration::from_secs(30));
+    if auth.is_some() {
+        // Never let a relay 3xx forward the auth header across origins.
+        builder = builder.redirect(reqwest::redirect::Policy::none());
+    }
+    let client = builder
+        .build()
+        .map_err(|e| format!("Failed to build HTTP client: {e}"))?;
+    let mut req = client.get(url);
+    if let Some(auth) = auth {
+        req = req.header("authorization", auth);
+    }
+    let resp = req
+        .send()
+        .await
+        .map_err(|e| format!("Failed to fetch agent avatar: {e}"))?;
+    if !resp.status().is_success() {
+        return Err(format!("Avatar fetch failed: HTTP {}", resp.status()));
+    }
+
+    if let Some(content_length) = resp.content_length() {
+        if content_length > MAX_AVATAR_FETCH_BYTES as u64 {
+            return Err("Agent avatar is too large to use as card input.".to_string());
+        }
+    }
+
+    let mut bytes = Vec::new();
+    let mut stream = resp.bytes_stream();
+    while let Some(chunk) = stream.next().await {
+        let chunk = chunk.map_err(|e| format!("Failed to read avatar bytes: {e}"))?;
+        append_within_avatar_cap(&mut bytes, &chunk)?;
+    }
+    Ok(bytes)
+}
+
+/// Append a body chunk to the avatar buffer, rejecting before the append if
+/// the total would cross `MAX_AVATAR_FETCH_BYTES`. Split out so the cap
+/// boundary is unit-testable without an HTTP server.
+fn append_within_avatar_cap(buf: &mut Vec<u8>, chunk: &[u8]) -> Result<(), String> {
+    if buf.len() + chunk.len() > MAX_AVATAR_FETCH_BYTES {
+        return Err("Agent avatar is too large to use as card input.".to_string());
+    }
+    buf.extend_from_slice(chunk);
+    Ok(())
+}
+
+/// Save previously minted card bytes to disk via the OS save dialog.
+///
+/// Re-validates the bytes (chunk parses as a plain manifest or a
+/// structurally valid locked envelope, size within the import ceiling) so a
+/// corrupted preview can never be written as a `.agent.png`. No decryption
+/// happens here — the mint already round-trip-verified with the real key.
+#[tauri::command]
+pub async fn save_agent_card(
+    card_png_base64: String,
+    file_name: String,
+    app: AppHandle,
+) -> Result<bool, String> {
+    let bytes = STANDARD
+        .decode(card_png_base64.as_bytes())
+        .map_err(|e| format!("Card bytes were not valid base64: {e}"))?;
+    validate_snapshot_encode_size(bytes.len(), true)?;
+    let payload = extract_chunk_payload_png(&bytes)
+        .map_err(|e| format!("Refusing to save: card failed snapshot validation: {e}"))?;
+    parse_chunk_payload(&payload)
+        .map_err(|e| format!("Refusing to save: card failed snapshot validation: {e}"))?;
+
+    let safe_name = if file_name.ends_with(".agent.png") && !file_name.contains(['/', '\\']) {
+        file_name
+    } else {
+        "card.agent.png".to_string()
+    };
+    save_bytes_with_dialog(&app, &safe_name, "Agent card", &["png"], &bytes).await
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests;
diff --git a/desktop/src-tauri/src/commands/personas/card/tests.rs b/desktop/src-tauri/src/commands/personas/card/tests.rs
new file mode 100644
index 0000000000..ca69c43866
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/card/tests.rs
@@ -0,0 +1,324 @@
+//! Unit tests for `card.rs` — split into a child module file so the parent
+//! stays under the 1000-line gate (same layout as `snapshot/tests.rs`).
+
+use super::*;
+use std::collections::BTreeMap;
+
+#[test]
+fn archive_file_name_validation_rejects_escapes() {
+    assert!(validate_archive_file_name("eva-1234.agent.png").is_ok());
+    for bad in [
+        "../escape.agent.png",
+        "sub/dir.agent.png",
+        "sub\\dir.agent.png",
+        "not-a-card.png",
+        "plain.json",
+        "",
+    ] {
+        assert!(
+            validate_archive_file_name(bad).is_err(),
+            "expected rejection: {bad:?}"
+        );
+    }
+}
+
+#[test]
+fn card_template_decodes_with_expected_shape() {
+    // The embedded template is generation input only, but a corrupt or
+    // accidentally swapped asset should fail the build's test gate, not a
+    // user's first mint.
+    let img = image::load_from_memory(CARD_TEMPLATE_PNG).expect("template must decode");
+    // 2:3-ish portrait frame.
+    assert!(img.height() > img.width(), "template must be portrait");
+    assert!(img.width() >= 512, "template unexpectedly small");
+}
+
+#[test]
+fn key_resolution_layering_record_wins() {
+    let mut global = BTreeMap::new();
+    global.insert("OPENAI_API_KEY".to_string(), "global".to_string());
+    let mut persona = BTreeMap::new();
+    persona.insert("OPENAI_API_KEY".to_string(), "persona".to_string());
+    let mut record = BTreeMap::new();
+    record.insert("OPENAI_API_KEY".to_string(), "record".to_string());
+
+    assert_eq!(
+        resolve_env_from_layers("OPENAI_API_KEY", &global, &persona, &record, None).as_deref(),
+        Some("record")
+    );
+    record.clear();
+    assert_eq!(
+        resolve_env_from_layers("OPENAI_API_KEY", &global, &persona, &record, None).as_deref(),
+        Some("persona")
+    );
+    persona.clear();
+    assert_eq!(
+        resolve_env_from_layers("OPENAI_API_KEY", &global, &persona, &record, None).as_deref(),
+        Some("global")
+    );
+    global.clear();
+    assert_eq!(
+        resolve_env_from_layers(
+            "OPENAI_API_KEY",
+            &global,
+            &persona,
+            &record,
+            Some("process".to_string())
+        )
+        .as_deref(),
+        Some("process")
+    );
+    assert!(resolve_env_from_layers("OPENAI_API_KEY", &global, &persona, &record, None).is_none());
+}
+
+#[test]
+fn key_resolution_skips_blank_values() {
+    let mut record = BTreeMap::new();
+    record.insert("OPENAI_API_KEY".to_string(), "   ".to_string());
+    let mut persona = BTreeMap::new();
+    persona.insert("OPENAI_API_KEY".to_string(), "persona".to_string());
+    assert_eq!(
+        resolve_env_from_layers("OPENAI_API_KEY", &BTreeMap::new(), &persona, &record, None)
+            .as_deref(),
+        Some("persona")
+    );
+}
+
+#[test]
+fn responses_url_default_and_override() {
+    assert_eq!(responses_url(None), "https://api.openai.com/v1/responses");
+    // Trailing slashes must not produce a double-slash path.
+    assert_eq!(
+        responses_url(Some("https://proxy.example/v1/".to_string())),
+        "https://proxy.example/v1/responses"
+    );
+    assert_eq!(
+        responses_url(Some("https://proxy.example/v1".to_string())),
+        "https://proxy.example/v1/responses"
+    );
+}
+
+#[test]
+fn instructions_pin_style_match_default_and_owner_primacy() {
+    let base = build_card_instructions("Eva", "leads the team", "");
+    assert!(base.contains("match input image 2's art style EXACTLY"));
+    assert!(base.contains("\"Eva\""));
+    assert!(!base.contains("OWNER'S DIRECTIONS"));
+
+    let directed = build_card_instructions("Eva", "leads the team", "make it stormy");
+    // Owner directions take primacy over style defaults...
+    assert!(directed.contains("OWNER'S DIRECTIONS"));
+    assert!(directed.contains("make it stormy"));
+    assert!(directed.contains("override the default art-style and copy guidance"));
+    // ...but the fixed contract survives: frame, style anchor (as an
+    // overridable default), and text-fidelity requirements stay present.
+    assert!(directed.contains("match input image 2's art style EXACTLY"));
+    assert!(directed.contains("cannot change the frame, layout, or"));
+    assert!(directed.contains("Render all text with perfect fidelity"));
+    // Card-text direction is an explicitly named capability, and the
+    // owner-wording rule acknowledges the fixed 220-char text-box limit
+    // (no mutually impossible "verbatim" vs "under 220 chars" pair).
+    assert!(directed.contains("card text"));
+    assert!(directed.contains("use their wording within the 220-character text-box limit"));
+}
+
+#[test]
+fn extract_card_output_happy_path_and_missing_image() {
+    let ok = serde_json::json!({
+        "output": [
+            {"type": "reasoning"},
+            {"type": "image_generation_call", "result": "aW1n"},
+            {"type": "message", "content": [
+                {"type": "output_text", "text": "notes here"}
+            ]}
+        ]
+    });
+    let (img, notes) = extract_card_output(&ok).unwrap();
+    assert_eq!(img, "aW1n");
+    assert_eq!(notes, "notes here");
+
+    let missing = serde_json::json!({"output": [{"type": "message", "content": []}]});
+    let err = extract_card_output(&missing).unwrap_err();
+    assert!(err.contains("No image"), "{err}");
+
+    let no_output = serde_json::json!({});
+    assert!(extract_card_output(&no_output).is_err());
+}
+
+#[test]
+fn kind0_picture_wins_over_record_avatar_unless_blank() {
+    let some = |s: &str| Some(s.to_string());
+    // Published picture wins.
+    assert_eq!(
+        preferred_avatar_url(some("https://relay/media/k0.png"), some("data:image/png;x")),
+        some("https://relay/media/k0.png")
+    );
+    // No profile / no picture: record avatar survives.
+    assert_eq!(
+        preferred_avatar_url(None, some("data:image/png;x")),
+        some("data:image/png;x")
+    );
+    // Blank or whitespace picture must not shadow a real avatar.
+    assert_eq!(
+        preferred_avatar_url(some(""), some("data:image/png;x")),
+        some("data:image/png;x")
+    );
+    assert_eq!(
+        preferred_avatar_url(some("  "), some("data:image/png;x")),
+        some("data:image/png;x")
+    );
+    // Nothing anywhere: None (caller surfaces the "no avatar" error).
+    assert_eq!(preferred_avatar_url(None, None), None);
+}
+
+#[test]
+fn unlocked_manifest_inlines_real_avatar_bytes_downscaled() {
+    // 700px source (over MANIFEST_AVATAR_MAX_DIM) in a solid color.
+    let avatar = image::DynamicImage::ImageRgba8(image::RgbaImage::from_pixel(
+        700,
+        700,
+        image::Rgba([9, 120, 33, 255]),
+    ));
+    let mut avatar_png = std::io::Cursor::new(Vec::new());
+    avatar
+        .write_to(&mut avatar_png, image::ImageFormat::Png)
+        .unwrap();
+
+    let inlined = manifest_avatar_bytes(false, avatar_png.get_ref(), None)
+        .unwrap()
+        .expect("unlocked mints must inline the real avatar");
+    let img = image::load_from_memory(&inlined).unwrap();
+    assert_eq!(
+        (img.width(), img.height()),
+        (MANIFEST_AVATAR_MAX_DIM, MANIFEST_AVATAR_MAX_DIM)
+    );
+    assert_eq!(img.to_rgba8().get_pixel(0, 0).0, [9, 120, 33, 255]);
+
+    // Undecodable avatar bytes fail the mint (pre-spend), never silently
+    // produce a card whose import would wear the artwork as a face.
+    assert!(manifest_avatar_bytes(false, b"not a png", None).is_err());
+}
+
+#[test]
+fn locked_manifest_keeps_data_url_only_avatar() {
+    // Locked mints must not inline fetched bytes (NIP-44 cap): only a record
+    // data URL carries over, exactly as before.
+    let unused = [0u8; 4];
+    assert_eq!(
+        manifest_avatar_bytes(true, &unused, Some("data:image/png;base64,aGk="))
+            .unwrap()
+            .as_deref(),
+        Some(b"hi".as_slice())
+    );
+    assert_eq!(
+        manifest_avatar_bytes(true, &unused, Some("https://relay/media/a.png")).unwrap(),
+        None
+    );
+    assert_eq!(manifest_avatar_bytes(true, &unused, None).unwrap(), None);
+}
+
+#[test]
+fn media_get_auth_gate_is_same_origin_only() {
+    // The minted Blossom get-auth header may only travel to the relay's own
+    // origin — scheme, host, and port all count (same contract as
+    // `validate_download_url` in `media_download.rs`).
+    let relay = "https://relay.example.com";
+    assert!(is_same_origin(
+        "https://relay.example.com/media/abc.png",
+        relay
+    ));
+    // Different host, scheme, or port: no auth.
+    assert!(!is_same_origin(
+        "https://evil.example.com/media/abc.png",
+        relay
+    ));
+    assert!(!is_same_origin(
+        "http://relay.example.com/media/abc.png",
+        relay
+    ));
+    assert!(!is_same_origin(
+        "https://relay.example.com:8443/media/abc.png",
+        relay
+    ));
+    // Unparseable inputs fail closed.
+    assert!(!is_same_origin("not a url", relay));
+    assert!(!is_same_origin(
+        "https://relay.example.com/x",
+        "also not a url"
+    ));
+    // Explicit port on both sides matches.
+    assert!(is_same_origin(
+        "http://localhost:3100/media/abc.png",
+        "http://localhost:3100"
+    ));
+}
+
+#[test]
+fn avatar_cap_rejects_before_appending_crossing_chunk() {
+    // The streaming accumulator must reject a chunk that would cross the
+    // cap BEFORE buffering it — this is what bounds memory when
+    // Content-Length is missing or dishonest.
+    let mut buf = vec![0u8; MAX_AVATAR_FETCH_BYTES - 1];
+    assert!(append_within_avatar_cap(&mut buf, &[0u8]).is_ok());
+    assert_eq!(buf.len(), MAX_AVATAR_FETCH_BYTES);
+    // Exactly at the cap: one more byte must fail and not grow the buffer.
+    assert!(append_within_avatar_cap(&mut buf, &[0u8]).is_err());
+    assert_eq!(buf.len(), MAX_AVATAR_FETCH_BYTES);
+
+    // A single oversized chunk is rejected outright.
+    let mut fresh = Vec::new();
+    let oversized = vec![0u8; MAX_AVATAR_FETCH_BYTES + 1];
+    assert!(append_within_avatar_cap(&mut fresh, &oversized).is_err());
+    assert!(fresh.is_empty());
+}
+
+#[test]
+fn save_rejects_plain_png_without_snapshot_chunk() {
+    // A plain PNG (no buzz_agent_snapshot chunk) must not be saveable as
+    // a card. Exercise the same validation the command runs.
+    let img = image::DynamicImage::new_rgba8(4, 4);
+    let mut png = Vec::new();
+    img.write_to(&mut std::io::Cursor::new(&mut png), image::ImageFormat::Png)
+        .unwrap();
+    assert!(decode_snapshot_png(&png).is_err());
+}
+
+#[test]
+fn archived_sidecar_without_memory_level_defaults_to_none() {
+    // Every mint before the memory option existed embedded MemoryLevel::None
+    // structurally, so old sidecars (no memoryLevel field) must deserialize
+    // to None — the gallery's disclosure depends on this being honest.
+    let legacy = r#"{
+        "storedFileName": "eva-1234.agent.png",
+        "fileName": "eva.agent.png",
+        "agentId": "abc",
+        "agentName": "Eva",
+        "designerNotes": "",
+        "locked": false,
+        "mintedAt": "2026-07-28T00:00:00Z"
+    }"#;
+    let meta: ArchivedCardMeta = serde_json::from_str(legacy).unwrap();
+    assert_eq!(meta.memory_level, MemoryLevel::None);
+
+    let with_level = legacy.replace(
+        "\"locked\": false,",
+        "\"locked\": false, \"memoryLevel\": \"everything\",",
+    );
+    let meta: ArchivedCardMeta = serde_json::from_str(&with_level).unwrap();
+    assert_eq!(meta.memory_level, MemoryLevel::Everything);
+}
+
+#[test]
+fn minted_card_serializes_memory_level_snake_case_value() {
+    // The TS layer narrows on the exact wire strings "none"/"core"/
+    // "everything" — pin the serde representation the frontend will see.
+    let minted = MintedCard {
+        card_png_base64: String::new(),
+        file_name: "eva.agent.png".to_string(),
+        designer_notes: String::new(),
+        locked: false,
+        memory_level: MemoryLevel::Core,
+    };
+    let json = serde_json::to_value(&minted).unwrap();
+    assert_eq!(json["memoryLevel"], "core");
+}
diff --git a/desktop/src-tauri/src/commands/personas/mod.rs b/desktop/src-tauri/src/commands/personas/mod.rs
index 66f7296a25..0cd7ad0324 100644
--- a/desktop/src-tauri/src/commands/personas/mod.rs
+++ b/desktop/src-tauri/src/commands/personas/mod.rs
@@ -306,11 +306,14 @@ pub async fn set_persona_active(
 }
 
 pub(crate) const PNG_MAGIC: [u8; 4] = [0x89, 0x50, 0x4E, 0x47];
+mod card;
 mod snapshot;
-pub use snapshot::encode_agent_snapshot_for_send;
-pub use snapshot::export_agent_snapshot;
+pub use card::*;
+#[cfg(test)]
+pub(crate) use snapshot::import::decode_snapshot_from_bytes;
 pub(crate) use snapshot::import::{
-    decode_snapshot_from_bytes, resolve_snapshot_import_behavior, MAX_SNAPSHOT_JSON_BYTES,
+    parse_snapshot_payload_from_bytes, resolve_snapshot_import_behavior, MAX_SNAPSHOT_JSON_BYTES,
     MAX_SNAPSHOT_PNG_BYTES,
 };
 pub use snapshot::{confirm_agent_snapshot_import, preview_agent_snapshot_import};
+pub use snapshot::{encode_agent_snapshot_for_send, export_agent_snapshot};
diff --git a/desktop/src-tauri/src/commands/personas/pending.rs b/desktop/src-tauri/src/commands/personas/pending.rs
index a4003329bc..cab5fababc 100644
--- a/desktop/src-tauri/src/commands/personas/pending.rs
+++ b/desktop/src-tauri/src/commands/personas/pending.rs
@@ -75,11 +75,11 @@ pub(super) fn prepare_persona_publication(
 }
 
 fn retained_persona_is_shared(row: Option<&RetainedEvent>) -> bool {
-    use buzz_core_pkg::kind::persona_event_is_shared;
+    use buzz_core_pkg::kind::event_is_shared;
     use nostr::JsonUtil;
 
     row.and_then(|retained| nostr::Event::from_json(&retained.raw_event).ok())
-        .is_some_and(|event| persona_event_is_shared(&event))
+        .is_some_and(|event| event_is_shared(&event))
 }
 
 /// Project each persona's catalog visibility from the active relay+owner
diff --git a/desktop/src-tauri/src/commands/personas/snapshot.rs b/desktop/src-tauri/src/commands/personas/snapshot.rs
index a3ba731875..e7bd1597e6 100644
--- a/desktop/src-tauri/src/commands/personas/snapshot.rs
+++ b/desktop/src-tauri/src/commands/personas/snapshot.rs
@@ -142,7 +142,7 @@ pub(crate) fn validate_snapshot_encode_size(bytes_len: usize, is_png: bool) -> R
 }
 
 /// Parse a `memory_level` string to `MemoryLevel`.
-fn parse_memory_level(s: &str) -> Result<MemoryLevel, String> {
+pub(crate) fn parse_memory_level(s: &str) -> Result<MemoryLevel, String> {
     match s {
         "none" | "" => Ok(MemoryLevel::None),
         "core" => Ok(MemoryLevel::Core),
@@ -153,6 +153,32 @@ fn parse_memory_level(s: &str) -> Result<MemoryLevel, String> {
     }
 }
 
+/// Flatten an owner-decrypted memory listing into manifest entries for
+/// `memory_level`: `Core` takes the core entry only; `Everything` appends all
+/// `mem/*` entries after it. Pure so both the export and card-mint paths share
+/// (and tests can pin) the level → entries selection.
+pub(crate) fn memory_entries_from_listing(
+    listing: crate::commands::engrams::AgentMemoryListing,
+    memory_level: MemoryLevel,
+) -> Vec<AgentSnapshotMemoryEntry> {
+    let mut entries = Vec::new();
+    if let Some(core) = listing.core {
+        entries.push(AgentSnapshotMemoryEntry {
+            slug: core.slug,
+            body: core.body,
+        });
+    }
+    if memory_level == MemoryLevel::Everything {
+        for mem in listing.memories {
+            entries.push(AgentSnapshotMemoryEntry {
+                slug: mem.slug,
+                body: mem.body,
+            });
+        }
+    }
+    entries
+}
+
 /// Parse a `format` string to a PNG flag.
 fn parse_format_is_png(s: &str) -> Result<bool, String> {
     match s {
@@ -164,6 +190,33 @@ fn parse_format_is_png(s: &str) -> Result<bool, String> {
     }
 }
 
+fn materialize_portable_runtime_defaults(
+    record: &mut ManagedAgentRecord,
+    global: &crate::managed_agents::GlobalAgentConfig,
+) {
+    if record
+        .model
+        .as_deref()
+        .is_none_or(|value| value.trim().is_empty())
+    {
+        record.model = global.model.clone();
+    }
+    if record
+        .provider
+        .as_deref()
+        .is_none_or(|value| value.trim().is_empty())
+    {
+        record.provider = global.provider.clone();
+    }
+    if record
+        .runtime
+        .as_deref()
+        .is_none_or(|value| value.trim().is_empty())
+    {
+        record.runtime = global.preferred_runtime.clone();
+    }
+}
+
 /// Shared production encoding path.
 ///
 /// Resolves the agent definition, validates inputs, fetches optional memory,
@@ -196,6 +249,13 @@ pub(crate) async fn materialize_snapshot_bytes(
         let definitions = load_agent_definitions(&app)?;
         let (def_record, is_definition) = resolve_from_lists(&id, &instances, &definitions)
             .map(|(r, is_def)| (r.clone(), is_def))?;
+        let mut def_record = def_record;
+        // A snapshot is a verbatim portable copy of the effective runtime,
+        // provider, and model configuration, not a pointer to the sender's
+        // machine-wide defaults. This does not translate or substitute values
+        // for a different recipient setup.
+        let global = crate::managed_agents::load_global_agent_config(&app).unwrap_or_default();
+        materialize_portable_runtime_defaults(&mut def_record, &global);
 
         let memory_pubkey = if memory_level != MemoryLevel::None {
             let mpk = memory_source_pubkey.as_deref().unwrap_or("");
@@ -233,22 +293,7 @@ pub(crate) async fn materialize_snapshot_bytes(
     // ── Fetch memory ─────────────────────────────────────────────────────────
     let memory_entries: Vec<AgentSnapshotMemoryEntry> = if let Some(pubkey) = memory_pubkey {
         let listing = get_agent_memory(pubkey, app.clone(), state).await?;
-        let mut entries = Vec::new();
-        if let Some(core) = listing.core {
-            entries.push(AgentSnapshotMemoryEntry {
-                slug: core.slug,
-                body: core.body,
-            });
-        }
-        if memory_level == MemoryLevel::Everything {
-            for mem in listing.memories {
-                entries.push(AgentSnapshotMemoryEntry {
-                    slug: mem.slug,
-                    body: mem.body,
-                });
-            }
-        }
-        entries
+        memory_entries_from_listing(listing, memory_level)
     } else {
         Vec::new()
     };
@@ -400,6 +445,8 @@ pub async fn encode_agent_snapshot_for_send(
     })
 }
 
+#[cfg(test)]
+mod fidelity_tests;
 #[cfg(test)]
 mod tests;
 
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/fidelity_tests.rs b/desktop/src-tauri/src/commands/personas/snapshot/fidelity_tests.rs
new file mode 100644
index 0000000000..b769d74d7b
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/snapshot/fidelity_tests.rs
@@ -0,0 +1,271 @@
+use super::import::decode_snapshot_from_bytes;
+use super::*;
+use crate::managed_agents::{
+    agent_snapshot::{
+        AgentSnapshot, AgentSnapshotDefinition, AgentSnapshotMemory, AgentSnapshotProfile,
+        FORMAT_DISCRIMINATOR, FORMAT_VERSION,
+    },
+    BackendKind, ManagedAgentRecord, RespondTo,
+};
+use std::collections::BTreeMap;
+
+fn make_definition(slug: &str) -> ManagedAgentRecord {
+    ManagedAgentRecord {
+        pubkey: String::new(),
+        slug: Some(slug.to_string()),
+        name: slug.to_string(),
+        display_name: None,
+        persona_id: None,
+        private_key_nsec: String::new(),
+        auth_tag: None,
+        relay_url: String::new(),
+        avatar_url: None,
+        acp_command: String::new(),
+        agent_command: String::new(),
+        agent_command_override: None,
+        agent_args: vec![],
+        mcp_command: String::new(),
+        turn_timeout_seconds: 0,
+        idle_timeout_seconds: None,
+        max_turn_duration_seconds: None,
+        parallelism: 1,
+        system_prompt: None,
+        model: None,
+        provider: None,
+        persona_source_version: None,
+        env_vars: BTreeMap::new(),
+        start_on_app_launch: false,
+        auto_restart_on_config_change: false,
+        runtime_pid: None,
+        backend: BackendKind::Local,
+        backend_agent_id: None,
+        provider_binary_path: None,
+        team_id: None,
+        persona_team_dir: None,
+        persona_name_in_team: None,
+        created_at: String::new(),
+        updated_at: String::new(),
+        last_started_at: None,
+        last_stopped_at: None,
+        last_exit_code: None,
+        last_error: None,
+        last_error_code: None,
+        respond_to: RespondTo::default(),
+        respond_to_allowlist: vec![],
+        runtime: None,
+        name_pool: vec![],
+        is_builtin: false,
+        is_active: false,
+        shared: false,
+        source_team: None,
+        source_team_persona_slug: None,
+        catalog_source: None,
+        definition_respond_to: None,
+        definition_respond_to_allowlist: vec![],
+        definition_parallelism: None,
+        relay_mesh: None,
+    }
+}
+
+/// Build a minimal valid AgentSnapshot for import tests.
+fn make_snapshot(
+    memory_level: MemoryLevel,
+    entries: Vec<AgentSnapshotMemoryEntry>,
+) -> AgentSnapshot {
+    AgentSnapshot {
+        format: FORMAT_DISCRIMINATOR.to_string(),
+        version: FORMAT_VERSION,
+        definition: AgentSnapshotDefinition {
+            name: "Test Agent".to_string(),
+            source_is_builtin: false,
+            system_prompt: Some("You are helpful.".to_string()),
+            runtime: None,
+            model: None,
+            provider: None,
+            parallelism: None,
+            respond_to: None,
+            respond_to_allowlist: vec![],
+            name_pool: vec![],
+            idle_timeout_seconds: None,
+            max_turn_duration_seconds: None,
+        },
+        profile: AgentSnapshotProfile {
+            display_name: "Test Agent".to_string(),
+            about: None,
+            avatar_data_url: None,
+            avatar_url: None,
+        },
+        memory: AgentSnapshotMemory {
+            level: memory_level,
+            entries,
+        },
+    }
+}
+
+// ── Portable effective configuration ─────────────────────────────────────
+
+#[test]
+fn inherited_runtime_provider_and_model_are_materialized_for_export() {
+    let mut record = make_definition("wren");
+    let global = crate::managed_agents::GlobalAgentConfig {
+        preferred_runtime: Some("goose".to_string()),
+        provider: Some("databricks_v2".to_string()),
+        model: Some("databricks-gpt-5-6-sol".to_string()),
+        ..Default::default()
+    };
+
+    materialize_portable_runtime_defaults(&mut record, &global);
+
+    assert_eq!(record.runtime.as_deref(), Some("goose"));
+    assert_eq!(record.provider.as_deref(), Some("databricks_v2"));
+    assert_eq!(record.model.as_deref(), Some("databricks-gpt-5-6-sol"));
+}
+
+#[test]
+fn explicit_runtime_provider_and_model_win_over_global_defaults() {
+    let mut record = make_definition("wren");
+    record.runtime = Some("claude".to_string());
+    record.provider = Some("anthropic".to_string());
+    record.model = Some("claude-opus-5".to_string());
+    let global = crate::managed_agents::GlobalAgentConfig {
+        preferred_runtime: Some("goose".to_string()),
+        provider: Some("databricks_v2".to_string()),
+        model: Some("databricks-gpt-5-6-sol".to_string()),
+        ..Default::default()
+    };
+
+    materialize_portable_runtime_defaults(&mut record, &global);
+
+    assert_eq!(record.runtime.as_deref(), Some("claude"));
+    assert_eq!(record.provider.as_deref(), Some("anthropic"));
+    assert_eq!(record.model.as_deref(), Some("claude-opus-5"));
+}
+
+/// PNG image-body avatar overrides manifest avatar fields and all definition
+/// config survives the exact production decoder.
+#[test]
+fn import_png_body_avatar_and_full_model_round_trip() {
+    use crate::managed_agents::agent_snapshot::{decode_avatar_data_url, encode_snapshot_png};
+
+    let mut snapshot = make_snapshot(MemoryLevel::None, vec![]);
+    snapshot.definition.runtime = Some("goose".to_string());
+    snapshot.definition.model = Some("databricks-gpt-5-6-sol".to_string());
+    snapshot.definition.provider = Some("databricks_v2".to_string());
+    snapshot.profile.avatar_data_url = None;
+    snapshot.profile.avatar_url = Some("https://sender.invalid/avatar.png".to_string());
+
+    let avatar = image::DynamicImage::ImageRgba8(image::RgbaImage::from_pixel(
+        4,
+        3,
+        image::Rgba([23, 91, 177, 255]),
+    ));
+    let mut avatar_png = std::io::Cursor::new(Vec::new());
+    avatar
+        .write_to(&mut avatar_png, image::ImageFormat::Png)
+        .unwrap();
+    let png_bytes = encode_snapshot_png(&snapshot, Some(avatar_png.get_ref())).unwrap();
+
+    let decoded = decode_snapshot_from_bytes(&png_bytes).unwrap();
+    assert_eq!(decoded.definition.runtime.as_deref(), Some("goose"));
+    assert_eq!(
+        decoded.definition.model.as_deref(),
+        Some("databricks-gpt-5-6-sol")
+    );
+    assert_eq!(
+        decoded.definition.provider.as_deref(),
+        Some("databricks_v2")
+    );
+    assert_eq!(
+        decoded.profile.avatar_url.as_deref(),
+        Some("https://sender.invalid/avatar.png")
+    );
+
+    let avatar_data_url = decoded
+        .profile
+        .avatar_data_url
+        .as_deref()
+        .expect("PNG image body must become the effective portable avatar");
+    let avatar_bytes = decode_avatar_data_url(avatar_data_url).unwrap();
+    let imported_avatar = image::load_from_memory(&avatar_bytes).unwrap();
+    assert_eq!((imported_avatar.width(), imported_avatar.height()), (4, 3));
+    assert_eq!(
+        imported_avatar.to_rgba8().get_pixel(0, 0).0,
+        [23, 91, 177, 255]
+    );
+}
+
+/// The transparent 1×1 no-avatar card must not override a manifest fallback.
+#[test]
+fn import_png_placeholder_keeps_manifest_avatar_fallback() {
+    use crate::managed_agents::agent_snapshot::encode_snapshot_png;
+
+    let mut snapshot = make_snapshot(MemoryLevel::None, vec![]);
+    snapshot.profile.avatar_data_url = None;
+    snapshot.profile.avatar_url = Some("https://example.com/avatar.png".to_string());
+    let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
+
+    let decoded = decode_snapshot_from_bytes(&png_bytes).unwrap();
+    assert!(decoded.profile.avatar_data_url.is_none());
+    assert_eq!(decoded.profile.avatar_url, snapshot.profile.avatar_url);
+}
+
+/// An unlocked trading card imports the agent's REAL avatar, never the card.
+///
+/// Mint-shaped input: the PNG body is the generated card artwork, while the
+/// manifest inlines the source avatar (`manifest_avatar_bytes` in `card.rs`).
+/// The #3578 body-wins override must not fire when the manifest already
+/// carries inline avatar bytes — otherwise the imported agent publishes the
+/// 1500-wide card as its kind:0 picture.
+#[test]
+fn import_unlocked_card_uses_manifest_avatar_not_card_artwork() {
+    use crate::managed_agents::agent_snapshot::{decode_avatar_data_url, encode_snapshot_png};
+    use base64::{engine::general_purpose::STANDARD, Engine as _};
+
+    // The real avatar: 4×3 solid blue, inlined in the manifest at mint time.
+    let real_avatar = image::DynamicImage::ImageRgba8(image::RgbaImage::from_pixel(
+        4,
+        3,
+        image::Rgba([23, 91, 177, 255]),
+    ));
+    let mut real_avatar_png = std::io::Cursor::new(Vec::new());
+    real_avatar
+        .write_to(&mut real_avatar_png, image::ImageFormat::Png)
+        .unwrap();
+
+    let mut snapshot = make_snapshot(MemoryLevel::None, vec![]);
+    snapshot.profile.avatar_data_url = Some(format!(
+        "data:image/png;base64,{}",
+        STANDARD.encode(real_avatar_png.get_ref())
+    ));
+    snapshot.profile.avatar_url = Some("https://relay.example/media/live-kind0.png".to_string());
+
+    // The card artwork: a distinct 1500×2250 solid red "trading card" as the
+    // PNG body — the exact dimensions the minter encodes for unlocked cards.
+    // Size matters: 2250px exceeds `snapshot_avatar`'s 2048px decode limit,
+    // so reaching the body override here wouldn't just import the wrong
+    // face — it would fail the import outright.
+    let card_art = image::DynamicImage::ImageRgba8(image::RgbaImage::from_pixel(
+        1500,
+        2250,
+        image::Rgba([200, 16, 16, 255]),
+    ));
+    let mut card_png = std::io::Cursor::new(Vec::new());
+    card_art
+        .write_to(&mut card_png, image::ImageFormat::Png)
+        .unwrap();
+    let file_bytes = encode_snapshot_png(&snapshot, Some(card_png.get_ref())).unwrap();
+
+    // Production import decode: the effective avatar must be the real one.
+    let decoded = decode_snapshot_from_bytes(&file_bytes).unwrap();
+    let avatar_bytes =
+        decode_avatar_data_url(decoded.profile.avatar_data_url.as_deref().unwrap()).unwrap();
+    let imported = image::load_from_memory(&avatar_bytes).unwrap();
+    assert_eq!(
+        (imported.width(), imported.height()),
+        (4, 3),
+        "imported avatar must be the source avatar, not the card artwork"
+    );
+    assert_eq!(imported.to_rgba8().get_pixel(0, 0).0, [23, 91, 177, 255]);
+    // The live kind:0 URL fallback survives untouched.
+    assert_eq!(decoded.profile.avatar_url, snapshot.profile.avatar_url);
+}
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/import.rs b/desktop/src-tauri/src/commands/personas/snapshot/import.rs
index 9d7d238918..d7f0323304 100644
--- a/desktop/src-tauri/src/commands/personas/snapshot/import.rs
+++ b/desktop/src-tauri/src/commands/personas/snapshot/import.rs
@@ -13,7 +13,11 @@ use tauri::{AppHandle, Emitter, State};
 use crate::{
     app_state::AppState,
     managed_agents::{
-        agent_snapshot::{decode_snapshot_json, decode_snapshot_png, AgentSnapshot, MemoryLevel},
+        agent_snapshot::{extract_chunk_payload_png, AgentSnapshot, MemoryLevel},
+        agent_snapshot_envelope::{
+            decrypt_envelope, parse_chunk_payload, resolve_unlock_secret, ChunkPayload,
+            LOCKED_CARD_REFUSAL,
+        },
         load_managed_agents, load_personas, save_managed_agents, save_personas, AgentDefinition,
         ManagedAgentRecord, RespondTo,
     },
@@ -72,6 +76,16 @@ pub struct AgentSnapshotImportPreview {
     pub has_source_allowlist: bool,
     /// Number of source allowlist entries.
     pub source_allowlist_count: usize,
+    /// Full source allowlist entries, surfaced before import so hidden access
+    /// configuration is never reduced to a count.
+    pub source_allowlist: Vec<String>,
+    /// Pretty-printed, validated manifest exactly as decoded from the file.
+    /// The UI makes this available before confirmation for full payload review.
+    pub manifest_json: String,
+    /// True when the snapshot came from a locked (encrypted) card that this
+    /// machine successfully unlocked. Cards that cannot be unlocked never
+    /// reach a preview — they fail closed with the locked-card refusal.
+    pub locked: bool,
 }
 
 /// The confirmation request sent from the UI after the user reviews the preview.
@@ -210,42 +224,130 @@ const PNG_MAGIC: [u8; 4] = [0x89, 0x50, 0x4e, 0x47];
 ///
 /// **Size cap:** PNG inputs over 10 MiB and JSON inputs over 5 MiB are rejected
 /// before allocation to avoid avoidable large-input work.
-pub(crate) fn decode_snapshot_from_bytes(
-    file_bytes: &[u8],
-) -> Result<crate::managed_agents::agent_snapshot::AgentSnapshot, String> {
-    if file_bytes.len() >= 4 && file_bytes[..4] == PNG_MAGIC {
+///
+/// **Locked cards:** a structurally valid locked envelope parses successfully
+/// as `ChunkPayload::Locked` — no decryption happens here. Callers that can
+/// unlock go through [`decode_snapshot_for_import`]; callers that only need
+/// transit validation (e.g. `fetch_snapshot_bytes`) accept `Locked` as-is.
+pub(crate) fn parse_snapshot_payload_from_bytes(file_bytes: &[u8]) -> Result<ChunkPayload, String> {
+    let payload: ChunkPayload = if file_bytes.len() >= 4 && file_bytes[..4] == PNG_MAGIC {
         if file_bytes.len() > MAX_SNAPSHOT_PNG_BYTES {
             return Err(format!(
                 "Snapshot file is too large ({} MiB). PNG snapshots must be under 10 MiB.",
                 file_bytes.len() / (1024 * 1024)
             ));
         }
-        let snapshot = decode_snapshot_png(file_bytes)?;
-        if snapshot.memory.level == MemoryLevel::None && !snapshot.memory.entries.is_empty() {
-            return Err(
-                "Snapshot is malformed: memory.level is 'none' but entries are present."
-                    .to_string(),
-            );
+        let chunk_json = extract_chunk_payload_png(file_bytes)?;
+        let mut payload = parse_chunk_payload(&chunk_json)?;
+        // The PNG image body is the portable avatar. It deliberately wins over
+        // a manifest avatar *URL*, which may only be reachable by the sender.
+        // A 1×1 export placeholder leaves the manifest fallback intact.
+        // Inline manifest avatar *bytes* are authoritative and never
+        // overridden: trading cards supply the generated card artwork as the
+        // PNG body and carry the agent's real avatar inline — adopting the
+        // body there would import the card as the agent's face.
+        // Locked envelopes stay opaque here — there is no manifest to override
+        // until the unlock path decrypts one.
+        if let ChunkPayload::Plain(snapshot) = &mut payload {
+            if snapshot.profile.avatar_data_url.is_none() {
+                if let Some(avatar_data_url) =
+                    crate::managed_agents::snapshot_avatar::snapshot_png_avatar_data_url(
+                        file_bytes,
+                    )?
+                {
+                    snapshot.profile.avatar_data_url = Some(avatar_data_url);
+                }
+            }
         }
-        return Ok(snapshot);
-    }
-    // JSON path — apply size cap before serde allocation.
-    if file_bytes.len() > MAX_SNAPSHOT_JSON_BYTES {
-        return Err(format!(
-            "Snapshot file is too large ({} MiB). JSON snapshots must be under 5 MiB.",
-            file_bytes.len() / (1024 * 1024)
-        ));
-    }
-    let snapshot = decode_snapshot_json(file_bytes)?;
+        payload
+    } else {
+        // JSON path — apply size cap before serde allocation.
+        if file_bytes.len() > MAX_SNAPSHOT_JSON_BYTES {
+            return Err(format!(
+                "Snapshot file is too large ({} MiB). JSON snapshots must be under 5 MiB.",
+                file_bytes.len() / (1024 * 1024)
+            ));
+        }
+        parse_chunk_payload(file_bytes)?
+    };
     // Consistency check: none + non-empty entries is always malformed,
-    // regardless of format.  Mirrors the PNG path above so the rule is
-    // enforced at decode time for both formats.
-    if !snapshot.memory.entries.is_empty() && snapshot.memory.level == MemoryLevel::None {
+    // regardless of enclosing format. Enforced at decode time for plain
+    // payloads here, and after decryption for locked ones (see
+    // `enforce_memory_consistency` callers).
+    if let ChunkPayload::Plain(snapshot) = &payload {
+        enforce_memory_consistency(snapshot)?;
+    }
+    Ok(payload)
+}
+
+/// The shared malformed-memory guard: `memory.level == none` with non-empty
+/// entries is always rejected before any write.
+fn enforce_memory_consistency(
+    snapshot: &crate::managed_agents::agent_snapshot::AgentSnapshot,
+) -> Result<(), String> {
+    if snapshot.memory.level == MemoryLevel::None && !snapshot.memory.entries.is_empty() {
         return Err(
             "Snapshot is malformed: memory.level is 'none' but entries are present.".to_string(),
         );
     }
-    Ok(snapshot)
+    Ok(())
+}
+
+/// Decode a plain snapshot from raw bytes, refusing locked cards.
+///
+/// Test-only convenience: production call sites either unlock through
+/// [`decode_snapshot_for_import`] or validate structurally through
+/// [`parse_snapshot_payload_from_bytes`].
+#[cfg(test)]
+pub(crate) fn decode_snapshot_from_bytes(
+    file_bytes: &[u8],
+) -> Result<crate::managed_agents::agent_snapshot::AgentSnapshot, String> {
+    match parse_snapshot_payload_from_bytes(file_bytes)? {
+        ChunkPayload::Plain(snapshot) => Ok(*snapshot),
+        ChunkPayload::Locked(_) => Err(LOCKED_CARD_REFUSAL.to_string()),
+    }
+}
+
+/// Decode a snapshot for import, unlocking locked cards when — and only
+/// when — this machine holds one of the envelope's two exact key endpoints
+/// (the owner identity or the named local agent record).
+///
+/// Returns the decoded manifest and whether it came from a locked envelope.
+/// When neither endpoint exists, fails closed with the locked-card refusal —
+/// never partial plaintext, never crypto details.
+pub(crate) fn decode_snapshot_for_import(
+    file_bytes: &[u8],
+    owner_keys: Option<&nostr::Keys>,
+    records: &[ManagedAgentRecord],
+) -> Result<(crate::managed_agents::agent_snapshot::AgentSnapshot, bool), String> {
+    match parse_snapshot_payload_from_bytes(file_bytes)? {
+        ChunkPayload::Plain(snapshot) => Ok((*snapshot, false)),
+        ChunkPayload::Locked(envelope) => {
+            let secret = resolve_unlock_secret(&envelope, owner_keys, records)
+                .ok_or_else(|| LOCKED_CARD_REFUSAL.to_string())?;
+            let snapshot = decrypt_envelope(&envelope, &secret)?;
+            enforce_memory_consistency(&snapshot)?;
+            Ok((snapshot, true))
+        }
+    }
+}
+
+async fn materialize_import_avatar<F, Fut>(
+    avatar_data_url: Option<&str>,
+    avatar_url: Option<&str>,
+    upload: F,
+) -> Result<Option<String>, String>
+where
+    F: FnOnce(Vec<u8>) -> Fut,
+    Fut: std::future::Future<Output = Result<String, String>>,
+{
+    let Some(avatar_data_url) = avatar_data_url else {
+        return Ok(avatar_url.map(str::to_string));
+    };
+    let avatar_bytes =
+        crate::managed_agents::agent_snapshot::decode_avatar_data_url(avatar_data_url)
+            .ok_or_else(|| "Snapshot avatar data is malformed.".to_string())?;
+    upload(avatar_bytes).await.map(Some)
 }
 
 // ── `preview_agent_snapshot_import` ──────────────────────────────────────────
@@ -257,19 +359,38 @@ pub(crate) fn decode_snapshot_from_bytes(
 /// `.agent.png` file. The format is sniffed from the content, not the
 /// extension, so an incorrectly-named file is handled correctly.
 ///
+/// Locked cards are unlocked here when this machine holds one of the
+/// envelope's two exact key endpoints; a card that cannot be unlocked fails
+/// with the locked-card refusal (shown directly to the user), never a
+/// partial preview. Identity-recovery mode is tolerated: owner keys are
+/// simply unavailable, so only the agent-record endpoint can unlock.
+///
 /// Returns an `AgentSnapshotImportPreview` or a descriptive error. Errors
-/// represent irrecoverable failures (corrupt / unsupported file) and are
-/// shown directly to the user.
+/// represent irrecoverable failures (corrupt / unsupported / locked-to-
+/// someone-else file) and are shown directly to the user.
 #[tauri::command]
 pub async fn preview_agent_snapshot_import(
     file_bytes: Vec<u8>,
     file_name: String,
+    app: AppHandle,
+    state: State<'_, AppState>,
 ) -> Result<AgentSnapshotImportPreview, String> {
+    // Key material + records are gathered up front (cheap, lock-scoped) so
+    // the blocking decode below owns plain data.
+    let owner_keys = state.signing_keys().ok();
+    let records = {
+        let _store_guard = state
+            .managed_agents_store_lock
+            .lock()
+            .map_err(|e| e.to_string())?;
+        load_managed_agents(&app)?
+    };
     tokio::task::spawn_blocking(move || {
         reject_legacy_persona_filename(&file_name)?;
-        let snapshot = decode_snapshot_from_bytes(&file_bytes)?;
+        let (snapshot, locked) =
+            decode_snapshot_for_import(&file_bytes, owner_keys.as_ref(), &records)?;
 
-        Ok(build_agent_snapshot_import_preview(&snapshot))
+        build_agent_snapshot_import_preview(&snapshot, locked)
     })
     .await
     .map_err(|e| format!("spawn_blocking failed: {e}"))?
@@ -277,7 +398,8 @@ pub async fn preview_agent_snapshot_import(
 
 pub(crate) fn build_agent_snapshot_import_preview(
     snapshot: &AgentSnapshot,
-) -> AgentSnapshotImportPreview {
+    locked: bool,
+) -> Result<AgentSnapshotImportPreview, String> {
     let memory_level = match snapshot.memory.level {
         MemoryLevel::None => "none",
         MemoryLevel::Core => "core",
@@ -285,7 +407,11 @@ pub(crate) fn build_agent_snapshot_import_preview(
     }
     .to_string();
 
-    AgentSnapshotImportPreview {
+    let manifest_json = serde_json::to_string_pretty(snapshot)
+        .map_err(|e| format!("failed to render snapshot manifest: {e}"))?;
+    let source_allowlist = snapshot.definition.respond_to_allowlist.clone();
+
+    Ok(AgentSnapshotImportPreview {
         display_name: snapshot.profile.display_name.clone(),
         is_builtin: snapshot.definition.source_is_builtin,
         model: snapshot.definition.model.clone(),
@@ -299,9 +425,12 @@ pub(crate) fn build_agent_snapshot_import_preview(
             .or_else(|| snapshot.profile.avatar_url.clone()),
         memory_level,
         memory_entry_count: snapshot.memory.entries.len(),
-        source_allowlist_count: snapshot.definition.respond_to_allowlist.len(),
-        has_source_allowlist: !snapshot.definition.respond_to_allowlist.is_empty(),
-    }
+        source_allowlist_count: source_allowlist.len(),
+        has_source_allowlist: !source_allowlist.is_empty(),
+        source_allowlist,
+        manifest_json,
+        locked,
+    })
 }
 
 // ── `confirm_agent_snapshot_import` ──────────────────────────────────────────
@@ -329,8 +458,20 @@ pub async fn confirm_agent_snapshot_import(
     app: AppHandle,
     state: State<'_, AppState>,
 ) -> Result<AgentSnapshotImportResult, String> {
-    // ── Phase 1: validate (no I/O) ───────────────────────────────────────────
-    let snapshot = decode_snapshot_from_bytes(&input.file_bytes)?;
+    // ── Phase 1: validate (no writes) ────────────────────────────────────────
+    // Locked cards unlock only via this machine's exact key endpoints;
+    // anything else fails closed here, before key generation.
+    let snapshot = {
+        let owner_keys = state.signing_keys().ok();
+        let records = {
+            let _store_guard = state
+                .managed_agents_store_lock
+                .lock()
+                .map_err(|e| e.to_string())?;
+            load_managed_agents(&app)?
+        };
+        decode_snapshot_for_import(&input.file_bytes, owner_keys.as_ref(), &records)?.0
+    };
 
     let display_name = snapshot.profile.display_name.trim().to_string();
     if display_name.is_empty() {
@@ -346,12 +487,21 @@ pub async fn confirm_agent_snapshot_import(
     )?;
     let minted_parallelism = minted.parallelism;
 
-    // Effective avatar: data URL wins; URL fallback when data URL is absent.
-    let effective_avatar: Option<String> = snapshot
-        .profile
-        .avatar_data_url
-        .clone()
-        .or_else(|| snapshot.profile.avatar_url.clone());
+    // Profile metadata must contain a hosted URL. Inline avatar data can be far
+    // larger than the relay's kind:0 content limit, so upload imported pixels
+    // before minting or persisting the new agent. Failing here keeps import
+    // atomic instead of creating an agent whose profile can never publish.
+    let effective_avatar = materialize_import_avatar(
+        snapshot.profile.avatar_data_url.as_deref(),
+        snapshot.profile.avatar_url.as_deref(),
+        |avatar_bytes| async {
+            crate::commands::media::upload_image_bytes(avatar_bytes, &state)
+                .await
+                .map(|descriptor| descriptor.url)
+                .map_err(|error| format!("Could not upload the imported avatar: {error}"))
+        },
+    )
+    .await?;
 
     // Wire-format string for the persona definition's respond_to field.
     // Omit when it is the default (owner-only) to keep definitions clean.
@@ -650,7 +800,7 @@ fn retain_agent_pending(app: &AppHandle, state: &AppState, record: &ManagedAgent
 
 /// POST a pre-built signed engram event to the relay, authenticating as the
 /// new agent.
-async fn submit_engram_event(
+pub(crate) async fn submit_engram_event(
     state: &AppState,
     agent_keys: &nostr::Keys,
     event_json: &[u8],
@@ -660,6 +810,8 @@ async fn submit_engram_event(
     use crate::relay::build_nip98_auth_header_for_keys;
     use reqwest::Method;
 
+    crate::egress_guard::assert_no_key_backup_bytes(event_json, "persona snapshot engram submit")?;
+
     // Wait before signing: the relay enforces NIP-98 freshness (±60s) and the
     // gate may hold for up to MAX_HINT_SECONDS (300s). Building auth before the
     // wait produces a stale `created_at` that the relay will reject.
@@ -703,3 +855,143 @@ async fn submit_engram_event(
     }
     Ok(())
 }
+
+// ── NIP-49 egress guard: boundary 7 (persona snapshot engram submit) ─────────
+
+#[cfg(test)]
+mod egress_guard_tests {
+    use super::submit_engram_event;
+
+    const NCRYPTSEC: &str = "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+
+    /// An engram body carrying an ncryptsec must be rejected by the guard
+    /// before any network I/O (the target port is a discard address; a guard
+    /// error — not a connection error — proves the abort ordering).
+    #[tokio::test]
+    async fn blocks_ncryptsec_before_network() {
+        let state = crate::app_state::build_app_state();
+        let keys = nostr::Keys::generate();
+        let body = format!("{{\"content\":\"{NCRYPTSEC}\"}}");
+        let err = submit_engram_event(
+            &state,
+            &keys,
+            body.as_bytes(),
+            "http://127.0.0.1:9/events",
+            None,
+        )
+        .await
+        .unwrap_err();
+        assert!(err.contains("key-backup material"), "{err}");
+    }
+}
+
+#[cfg(test)]
+mod import_avatar_tests {
+    use super::materialize_import_avatar;
+    use std::cell::Cell;
+
+    #[tokio::test]
+    async fn inline_avatar_is_uploaded_and_replaced_with_hosted_url() {
+        let uploaded = Cell::new(false);
+        let result = materialize_import_avatar(
+            Some("data:image/png;base64,iVBORw0KGgo="),
+            Some("https://sender.invalid/avatar.png"),
+            |bytes| {
+                uploaded.set(true);
+                async move {
+                    assert_eq!(bytes, b"\x89PNG\r\n\x1a\n");
+                    Ok("https://relay.example/media/avatar.png".to_string())
+                }
+            },
+        )
+        .await
+        .unwrap();
+
+        assert!(uploaded.get());
+        assert_eq!(
+            result.as_deref(),
+            Some("https://relay.example/media/avatar.png")
+        );
+    }
+
+    #[tokio::test]
+    async fn hosted_avatar_skips_upload() {
+        let result =
+            materialize_import_avatar(None, Some("https://sender.example/avatar.png"), |_| async {
+                panic!("hosted avatars must not be uploaded")
+            })
+            .await
+            .unwrap();
+
+        assert_eq!(result.as_deref(), Some("https://sender.example/avatar.png"));
+    }
+
+    #[tokio::test]
+    async fn relay_sized_inline_avatar_becomes_bounded_signed_profile() {
+        use base64::{engine::general_purpose::STANDARD, Engine};
+        use image::ImageEncoder;
+        use nostr::JsonUtil;
+
+        let mut pixels = vec![0_u8; 512 * 512 * 4];
+        let mut seed = 0x1234_5678_u32;
+        for byte in &mut pixels {
+            seed ^= seed << 13;
+            seed ^= seed >> 17;
+            seed ^= seed << 5;
+            *byte = seed as u8;
+        }
+        let mut source = Vec::new();
+        image::codecs::png::PngEncoder::new(&mut source)
+            .write_image(&pixels, 512, 512, image::ExtendedColorType::Rgba8)
+            .unwrap();
+        assert!(source.len() > 256 * 1024);
+        let data_url = format!("data:image/png;base64,{}", STANDARD.encode(&source));
+        assert!(data_url.len() > 256 * 1024);
+
+        let avatar = materialize_import_avatar(Some(&data_url), None, |bytes| async move {
+            let mime = crate::commands::media::detect_and_validate_mime(&bytes)?;
+            assert_eq!(mime, "image/png");
+            let sanitized = crate::commands::media::sanitize_image_for_upload(bytes, &mime)?;
+            image::load_from_memory(&sanitized).map_err(|error| error.to_string())?;
+            Ok("https://relay.example/media/avatar.png".to_string())
+        })
+        .await
+        .unwrap()
+        .unwrap();
+
+        let event =
+            crate::events::build_profile(Some("Imported agent"), None, Some(&avatar), None, None)
+                .unwrap()
+                .sign_with_keys(&nostr::Keys::generate())
+                .unwrap();
+        assert!(event.content.len() < 64 * 1024);
+        assert!(!event.content.contains("data:image/"));
+        assert!(event
+            .content
+            .contains("https://relay.example/media/avatar.png"));
+        assert!(event.as_json().len() < 256 * 1024);
+    }
+
+    #[tokio::test]
+    async fn upload_failure_aborts_avatar_materialization() {
+        let result = materialize_import_avatar(
+            Some("data:image/png;base64,iVBORw0KGgo="),
+            None,
+            |_| async { Err("relay upload failed".to_string()) },
+        )
+        .await;
+
+        assert_eq!(result.unwrap_err(), "relay upload failed");
+    }
+
+    #[tokio::test]
+    async fn malformed_inline_avatar_fails_before_upload() {
+        let result =
+            materialize_import_avatar(Some("data:image/png;base64,not-base64!"), None, |_| async {
+                panic!("malformed avatars must not be uploaded")
+            })
+            .await;
+
+        assert_eq!(result.unwrap_err(), "Snapshot avatar data is malformed.");
+    }
+}
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/tests.rs b/desktop/src-tauri/src/commands/personas/snapshot/tests.rs
index 4289310280..c453b09a9d 100644
--- a/desktop/src-tauri/src/commands/personas/snapshot/tests.rs
+++ b/desktop/src-tauri/src/commands/personas/snapshot/tests.rs
@@ -564,7 +564,7 @@ fn import_preview_includes_exported_definition_metadata() {
     let bytes = crate::managed_agents::agent_snapshot::encode_snapshot_json(&snapshot).unwrap();
     let decoded = decode_snapshot_from_bytes(&bytes).unwrap();
 
-    let preview = build_agent_snapshot_import_preview(&decoded);
+    let preview = build_agent_snapshot_import_preview(&decoded, false).unwrap();
 
     assert!(preview.is_builtin);
     assert_eq!(preview.model.as_deref(), Some("claude-opus-4-5"));
@@ -949,51 +949,14 @@ fn test_parse_format_is_png_invalid_returns_error() {
 }
 
 // ── Export: validate_snapshot_encode_size ────────────────────────────────────
-//
-// Tests call `validate_snapshot_encode_size` directly so they prove the exact
-// production guard — not a manual reconstruction.  Removing or reversing the
-// check in production code will cause these tests to fail.
 
-/// JSON: boundary-1 passes, boundary is the last legal byte count.
-#[test]
-fn validate_encode_size_json_at_boundary_minus_1_passes() {
-    assert!(super::validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES - 1, false).is_ok());
-}
+#[path = "tests_memory_entries.rs"]
+mod memory_entries;
 
-/// JSON: exactly at the boundary is the last accepted size.
-#[test]
-fn validate_encode_size_json_at_boundary_passes() {
-    assert!(super::validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES, false).is_ok());
-}
+#[path = "tests_encode_size.rs"]
+mod encode_size;
 
-/// JSON: boundary+1 is rejected.
-#[test]
-fn validate_encode_size_json_over_boundary_is_rejected() {
-    let err = super::validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES + 1, false).unwrap_err();
-    assert!(
-        err.contains("size limit"),
-        "error must mention size limit, got: {err}"
-    );
-}
+// ── Import: decode_snapshot_for_import (locked cards) ─────────────────────
 
-/// PNG: boundary-1 passes.
-#[test]
-fn validate_encode_size_png_at_boundary_minus_1_passes() {
-    assert!(super::validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES - 1, true).is_ok());
-}
-
-/// PNG: exactly at the boundary passes.
-#[test]
-fn validate_encode_size_png_at_boundary_passes() {
-    assert!(super::validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES, true).is_ok());
-}
-
-/// PNG: boundary+1 is rejected.
-#[test]
-fn validate_encode_size_png_over_boundary_is_rejected() {
-    let err = super::validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES + 1, true).unwrap_err();
-    assert!(
-        err.contains("size limit"),
-        "error must mention size limit, got: {err}"
-    );
-}
+#[path = "tests_locked.rs"]
+mod locked_import;
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/tests_encode_size.rs b/desktop/src-tauri/src/commands/personas/snapshot/tests_encode_size.rs
new file mode 100644
index 0000000000..36eaa99716
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/snapshot/tests_encode_size.rs
@@ -0,0 +1,55 @@
+//! Export-size guard tests for `validate_snapshot_encode_size`.
+//!
+//! Kept in a sibling file so `snapshot/tests.rs` stays under the
+//! 1000-line gate; `#[path]`-included from there as a child module,
+//! so `super::*` still resolves to the shared test imports.
+//!
+//! Tests call `validate_snapshot_encode_size` directly so they prove the
+//! exact production guard — not a manual reconstruction.  Removing or
+//! reversing the check in production code will cause these tests to fail.
+
+use super::*;
+
+/// JSON: boundary-1 passes, boundary is the last legal byte count.
+#[test]
+fn validate_encode_size_json_at_boundary_minus_1_passes() {
+    assert!(validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES - 1, false).is_ok());
+}
+
+/// JSON: exactly at the boundary is the last accepted size.
+#[test]
+fn validate_encode_size_json_at_boundary_passes() {
+    assert!(validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES, false).is_ok());
+}
+
+/// JSON: boundary+1 is rejected.
+#[test]
+fn validate_encode_size_json_over_boundary_is_rejected() {
+    let err = validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES + 1, false).unwrap_err();
+    assert!(
+        err.contains("size limit"),
+        "error must mention size limit, got: {err}"
+    );
+}
+
+/// PNG: boundary-1 passes.
+#[test]
+fn validate_encode_size_png_at_boundary_minus_1_passes() {
+    assert!(validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES - 1, true).is_ok());
+}
+
+/// PNG: exactly at the boundary passes.
+#[test]
+fn validate_encode_size_png_at_boundary_passes() {
+    assert!(validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES, true).is_ok());
+}
+
+/// PNG: boundary+1 is rejected.
+#[test]
+fn validate_encode_size_png_over_boundary_is_rejected() {
+    let err = validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES + 1, true).unwrap_err();
+    assert!(
+        err.contains("size limit"),
+        "error must mention size limit, got: {err}"
+    );
+}
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/tests_locked.rs b/desktop/src-tauri/src/commands/personas/snapshot/tests_locked.rs
new file mode 100644
index 0000000000..296444f78d
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/snapshot/tests_locked.rs
@@ -0,0 +1,129 @@
+//! Locked-card import tests for `decode_snapshot_for_import`.
+//!
+//! Kept in a sibling file so `snapshot/tests.rs` stays under the
+//! 1000-line gate; `#[path]`-included from there as a child module,
+//! so `super::*` still resolves to the shared test helpers.
+
+use super::*;
+use crate::commands::personas::snapshot::import::{
+    decode_snapshot_for_import, parse_snapshot_payload_from_bytes,
+};
+use crate::managed_agents::agent_snapshot_envelope::{
+    encode_locked_snapshot_png, encrypt_snapshot_envelope, ChunkPayload, LOCKED_CARD_REFUSAL,
+};
+
+/// Build a keyed instance record holding real key material, so the
+/// agent-endpoint unlock path resolves exactly as production does.
+fn record_for(agent: &nostr::Keys) -> ManagedAgentRecord {
+    ManagedAgentRecord {
+        pubkey: agent.public_key().to_hex(),
+        slug: None,
+        persona_id: Some("locked-test".to_string()),
+        private_key_nsec: nostr::ToBech32::to_bech32(agent.secret_key()).unwrap(),
+        ..make_definition("")
+    }
+}
+
+fn locked_png(owner: &nostr::Keys, agent: &nostr::Keys) -> (AgentSnapshot, Vec<u8>) {
+    let snapshot = make_snapshot(MemoryLevel::None, vec![]);
+    let png = encode_locked_snapshot_png(&snapshot, owner, &agent.public_key(), None).unwrap();
+    (snapshot, png)
+}
+
+/// Owner identity key unlocks a locked card; `locked` is reported true.
+#[test]
+fn owner_endpoint_unlocks_locked_png() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let (snapshot, png) = locked_png(&owner, &agent);
+    let (decoded, locked) = decode_snapshot_for_import(&png, Some(&owner), &[]).unwrap();
+    assert_eq!(decoded, snapshot);
+    assert!(locked);
+}
+
+/// A local managed-agent record holding the agent nsec unlocks the card
+/// even when the owner identity does not match (e.g. re-import on the
+/// agent's own machine under a different owner identity).
+#[test]
+fn agent_record_endpoint_unlocks_locked_png() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let (snapshot, png) = locked_png(&owner, &agent);
+    let other_identity = nostr::Keys::generate();
+    let records = vec![record_for(&agent)];
+    let (decoded, locked) =
+        decode_snapshot_for_import(&png, Some(&other_identity), &records).unwrap();
+    assert_eq!(decoded, snapshot);
+    assert!(locked);
+}
+
+/// No matching endpoint → only the locked-card refusal, nothing else.
+#[test]
+fn stranger_fails_closed_with_refusal_only() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let (_snapshot, png) = locked_png(&owner, &agent);
+    let stranger = nostr::Keys::generate();
+    let unrelated_record = record_for(&nostr::Keys::generate());
+    let err = decode_snapshot_for_import(&png, Some(&stranger), &[unrelated_record]).unwrap_err();
+    assert_eq!(err, LOCKED_CARD_REFUSAL);
+    // And with no key material at all.
+    let err = decode_snapshot_for_import(&png, None, &[]).unwrap_err();
+    assert_eq!(err, LOCKED_CARD_REFUSAL);
+}
+
+/// Plain snapshots pass through unchanged with `locked == false`, with or
+/// without key material in scope.
+#[test]
+fn plain_snapshot_passes_through_unlocked() {
+    use crate::managed_agents::agent_snapshot::encode_snapshot_png;
+    let snapshot = make_snapshot(MemoryLevel::None, vec![]);
+    let png = encode_snapshot_png(&snapshot, None).unwrap();
+    let owner = nostr::Keys::generate();
+    let (decoded, locked) = decode_snapshot_for_import(&png, Some(&owner), &[]).unwrap();
+    assert_eq!(decoded, snapshot);
+    assert!(!locked);
+    let (decoded, locked) = decode_snapshot_for_import(&png, None, &[]).unwrap();
+    assert_eq!(decoded, snapshot);
+    assert!(!locked);
+}
+
+/// The memory-consistency guard fires AFTER decryption too: a locked
+/// envelope whose plaintext declares level none + non-empty entries is
+/// rejected even for a legitimate endpoint.
+#[test]
+fn decrypted_manifest_memory_consistency_enforced() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let malformed = make_snapshot(
+        MemoryLevel::None,
+        vec![AgentSnapshotMemoryEntry {
+            slug: "core".to_string(),
+            body: "leaked".to_string(),
+        }],
+    );
+    // encrypt_snapshot_envelope does not guard memory consistency (the
+    // PNG encoder does), so this constructs the malicious payload.
+    let envelope = encrypt_snapshot_envelope(&malformed, &owner, &agent.public_key()).unwrap();
+    let json = serde_json::to_vec(&envelope).unwrap();
+    let err = decode_snapshot_for_import(&json, Some(&owner), &[]).unwrap_err();
+    assert!(
+        err.contains("'none' but entries are present"),
+        "post-decrypt consistency guard must fire, got: {err}"
+    );
+}
+
+/// Transit validation (`fetch_snapshot_bytes` path) accepts a locked PNG
+/// without any key material — structural validation only, no decryption.
+#[test]
+fn transit_validation_accepts_locked_png_without_keys() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let (_snapshot, png) = locked_png(&owner, &agent);
+    let payload = parse_snapshot_payload_from_bytes(&png).unwrap();
+    assert!(matches!(payload, ChunkPayload::Locked(_)));
+}
+
+/// The keyless plain decoder refuses locked cards with the refusal.
+#[test]
+fn plain_decoder_refuses_locked_cards() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let (_snapshot, png) = locked_png(&owner, &agent);
+    let err = decode_snapshot_from_bytes(&png).unwrap_err();
+    assert_eq!(err, LOCKED_CARD_REFUSAL);
+}
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/tests_memory_entries.rs b/desktop/src-tauri/src/commands/personas/snapshot/tests_memory_entries.rs
new file mode 100644
index 0000000000..b17efa1ad1
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/snapshot/tests_memory_entries.rs
@@ -0,0 +1,55 @@
+//! Tests for `memory_entries_from_listing` — the shared level → entries
+//! selection used by both snapshot export and card minting. Split from
+//! `tests.rs` to keep that file under the 1000-line gate; `#[path]`-included
+//! from there as a child module, so `super::*` resolves to `tests`'s parent
+//! scope re-exports.
+
+use super::*;
+
+fn listing_fixture() -> crate::commands::engrams::AgentMemoryListing {
+    let entry = |slug: &str, body: &str| crate::commands::engrams::EngramEntry {
+        slug: slug.to_string(),
+        body: body.to_string(),
+        event_id: "e".repeat(64),
+        created_at: 1,
+        outgoing_refs: vec![],
+    };
+    crate::commands::engrams::AgentMemoryListing {
+        core: Some(entry("core", "core body")),
+        memories: vec![entry("mem/a", "a body"), entry("mem/b", "b body")],
+        truncated: false,
+        fetched_at: 1,
+    }
+}
+
+#[test]
+fn memory_entries_core_takes_core_only() {
+    let entries = memory_entries_from_listing(listing_fixture(), MemoryLevel::Core);
+    assert_eq!(entries.len(), 1);
+    assert_eq!(entries[0].slug, "core");
+    assert_eq!(entries[0].body, "core body");
+}
+
+#[test]
+fn memory_entries_everything_appends_mem_entries_after_core() {
+    let entries = memory_entries_from_listing(listing_fixture(), MemoryLevel::Everything);
+    assert_eq!(
+        entries.iter().map(|e| e.slug.as_str()).collect::<Vec<_>>(),
+        vec!["core", "mem/a", "mem/b"]
+    );
+}
+
+#[test]
+fn memory_entries_missing_core_still_yields_mem_entries_for_everything() {
+    let mut listing = listing_fixture();
+    listing.core = None;
+    let entries = memory_entries_from_listing(listing, MemoryLevel::Everything);
+    assert_eq!(
+        entries.iter().map(|e| e.slug.as_str()).collect::<Vec<_>>(),
+        vec!["mem/a", "mem/b"]
+    );
+
+    let mut core_only = listing_fixture();
+    core_only.core = None;
+    assert!(memory_entries_from_listing(core_only, MemoryLevel::Core).is_empty());
+}
diff --git a/desktop/src-tauri/src/commands/project_git_merge_error.rs b/desktop/src-tauri/src/commands/project_git_merge_error.rs
new file mode 100644
index 0000000000..460ce83fa3
--- /dev/null
+++ b/desktop/src-tauri/src/commands/project_git_merge_error.rs
@@ -0,0 +1,152 @@
+//! Structured pull-request merge failures returned across the Tauri boundary.
+
+use serde::Serialize;
+
+/// Machine-readable recovery metadata for a failed pull-request merge.
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ProjectPullRequestMergeRecovery {
+    action: String,
+    target_branch: String,
+    source_branch: String,
+}
+
+/// Structured pull-request merge failure returned across the Tauri boundary.
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ProjectPullRequestMergeError {
+    code: String,
+    message: String,
+    recovery: Option<ProjectPullRequestMergeRecovery>,
+}
+
+impl ProjectPullRequestMergeError {
+    pub(crate) fn new(code: &str, message: impl Into<String>) -> Self {
+        Self {
+            code: code.to_string(),
+            message: message.into(),
+            recovery: None,
+        }
+    }
+
+    fn conflict(target_branch: String, source_branch: String) -> Self {
+        Self {
+            code: "merge_conflict".to_string(),
+            message: "Pull request has merge conflicts.".to_string(),
+            recovery: Some(ProjectPullRequestMergeRecovery {
+                action: "open_terminal".to_string(),
+                target_branch,
+                source_branch,
+            }),
+        }
+    }
+}
+
+impl From<String> for ProjectPullRequestMergeError {
+    fn from(message: String) -> Self {
+        // Relay push-policy denial for a repo with no `buzz-channel` binding.
+        // The stable token is declared in `buzz-core::git_perms`
+        // (GIT_NO_CHANNEL_BINDING_TOKEN); the relay guarantees the denial body
+        // starts with it. Push failures reach this conversion as raw
+        // stderr/`remote:` text, so match the token anywhere in the message.
+        if message.contains(buzz_core_pkg::git_perms::GIT_NO_CHANNEL_BINDING_TOKEN) {
+            return Self::new(
+                buzz_core_pkg::git_perms::GIT_NO_CHANNEL_BINDING_TOKEN,
+                "This repository is not bound to a channel, so the relay cannot \
+                 authorize pushes. Bind it with: buzz repos bind --id <repo> \
+                 --channel <channel-uuid>",
+            );
+        }
+        Self::new("merge_failed", message)
+    }
+}
+
+pub(crate) fn classify_merge_error(
+    message: String,
+    has_conflicts: bool,
+    target_branch: &str,
+    source_branch: &str,
+) -> ProjectPullRequestMergeError {
+    if has_conflicts {
+        ProjectPullRequestMergeError::conflict(target_branch.to_string(), source_branch.to_string())
+    } else {
+        ProjectPullRequestMergeError::new(
+            "merge_failed",
+            format!("Pull request merge failed: {message}"),
+        )
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{classify_merge_error, ProjectPullRequestMergeError};
+
+    #[test]
+    fn merge_conflict_error_has_stable_recovery_metadata() {
+        let error =
+            ProjectPullRequestMergeError::conflict("main".to_string(), "feature/demo".to_string());
+
+        assert_eq!(error.code, "merge_conflict");
+        assert_eq!(error.message, "Pull request has merge conflicts.");
+        let recovery = error.recovery.expect("conflict recovery");
+        assert_eq!(recovery.action, "open_terminal");
+        assert_eq!(recovery.target_branch, "main");
+        assert_eq!(recovery.source_branch, "feature/demo");
+    }
+
+    #[test]
+    fn merge_conflict_error_serializes_for_tauri_clients() {
+        let error =
+            ProjectPullRequestMergeError::conflict("main".to_string(), "feature/demo".to_string());
+        let value = serde_json::to_value(error).expect("serialize merge conflict");
+
+        assert_eq!(value["code"], "merge_conflict");
+        assert_eq!(value["recovery"]["targetBranch"], "main");
+        assert_eq!(value["recovery"]["sourceBranch"], "feature/demo");
+    }
+
+    #[test]
+    fn merge_error_classification_only_recovers_conflicts() {
+        let conflict = classify_merge_error(
+            "CONFLICT (content): Merge conflict in src/main.rs".to_string(),
+            true,
+            "main",
+            "feature/demo",
+        );
+        assert_eq!(conflict.code, "merge_conflict");
+        assert!(conflict.recovery.is_some());
+
+        let other = classify_merge_error(
+            "fatal: refusing to merge unrelated histories".to_string(),
+            false,
+            "main",
+            "feature/demo",
+        );
+        assert_eq!(other.code, "merge_failed");
+        assert!(other.recovery.is_none());
+    }
+
+    #[test]
+    fn no_channel_binding_denial_converts_to_structured_code() {
+        // The relay's push-policy denial arrives as raw git stderr with
+        // `remote:` framing; the stable token must be recognized wherever it
+        // sits in the message.
+        let remote_stderr = format!(
+            "remote: {}\nerror: failed to push some refs",
+            buzz_core_pkg::git_perms::GIT_NO_CHANNEL_BINDING_BODY
+        );
+        let error = ProjectPullRequestMergeError::from(remote_stderr);
+
+        assert_eq!(
+            error.code,
+            buzz_core_pkg::git_perms::GIT_NO_CHANNEL_BINDING_TOKEN
+        );
+        assert!(error.message.contains("buzz repos bind"));
+        assert!(error.recovery.is_none());
+
+        // Unrelated push failures keep the generic code and original text.
+        let generic = ProjectPullRequestMergeError::from("connection reset".to_string());
+        assert_eq!(generic.code, "merge_failed");
+        assert_eq!(generic.message, "connection reset");
+    }
+}
diff --git a/desktop/src-tauri/src/commands/project_git_workflow.rs b/desktop/src-tauri/src/commands/project_git_workflow.rs
index 39832feb10..624bbf4dfc 100644
--- a/desktop/src-tauri/src/commands/project_git_workflow.rs
+++ b/desktop/src-tauri/src/commands/project_git_workflow.rs
@@ -32,67 +32,10 @@ pub struct ProjectRepoMergeResult {
     pub status_publication_error: Option<String>,
 }
 
-/// Machine-readable recovery metadata for a failed pull-request merge.
-#[derive(Debug, Serialize)]
-#[serde(rename_all = "camelCase")]
-pub struct ProjectPullRequestMergeRecovery {
-    action: String,
-    target_branch: String,
-    source_branch: String,
-}
-
-/// Structured pull-request merge failure returned across the Tauri boundary.
-#[derive(Debug, Serialize)]
-#[serde(rename_all = "camelCase")]
-pub struct ProjectPullRequestMergeError {
-    code: String,
-    message: String,
-    recovery: Option<ProjectPullRequestMergeRecovery>,
-}
-
-impl ProjectPullRequestMergeError {
-    fn new(code: &str, message: impl Into<String>) -> Self {
-        Self {
-            code: code.to_string(),
-            message: message.into(),
-            recovery: None,
-        }
-    }
-
-    fn conflict(target_branch: String, source_branch: String) -> Self {
-        Self {
-            code: "merge_conflict".to_string(),
-            message: "Pull request has merge conflicts.".to_string(),
-            recovery: Some(ProjectPullRequestMergeRecovery {
-                action: "open_terminal".to_string(),
-                target_branch,
-                source_branch,
-            }),
-        }
-    }
-}
-
-impl From<String> for ProjectPullRequestMergeError {
-    fn from(message: String) -> Self {
-        Self::new("merge_failed", message)
-    }
-}
-
-fn classify_merge_error(
-    message: String,
-    has_conflicts: bool,
-    target_branch: &str,
-    source_branch: &str,
-) -> ProjectPullRequestMergeError {
-    if has_conflicts {
-        ProjectPullRequestMergeError::conflict(target_branch.to_string(), source_branch.to_string())
-    } else {
-        ProjectPullRequestMergeError::new(
-            "merge_failed",
-            format!("Pull request merge failed: {message}"),
-        )
-    }
-}
+/// Machine-readable pull-request merge failure types live in
+/// [`super::project_git_merge_error`]; re-imported here for the merge
+/// workflow below.
+use super::project_git_merge_error::{classify_merge_error, ProjectPullRequestMergeError};
 
 struct ProjectRepoMergeGitResult {
     message: String,
@@ -739,8 +682,8 @@ pub async fn merge_project_pull_request(
 mod tests {
     use super::{
         align_unborn_head_branch, build_merged_status_event, build_pull_request_status_event,
-        build_review_request_event, classify_merge_error, normalize_commit, same_repository,
-        validate_merge_status_metadata, ProjectPullRequestMergeError,
+        build_review_request_event, normalize_commit, same_repository,
+        validate_merge_status_metadata,
     };
     use crate::commands::project_git_exec::{build_test_git_auth_config, run_git};
     use nostr::{Event, JsonUtil, Keys, Timestamp};
@@ -785,51 +728,6 @@ mod tests {
         ));
     }
 
-    #[test]
-    fn merge_conflict_error_has_stable_recovery_metadata() {
-        let error =
-            ProjectPullRequestMergeError::conflict("main".to_string(), "feature/demo".to_string());
-
-        assert_eq!(error.code, "merge_conflict");
-        assert_eq!(error.message, "Pull request has merge conflicts.");
-        let recovery = error.recovery.expect("conflict recovery");
-        assert_eq!(recovery.action, "open_terminal");
-        assert_eq!(recovery.target_branch, "main");
-        assert_eq!(recovery.source_branch, "feature/demo");
-    }
-
-    #[test]
-    fn merge_conflict_error_serializes_for_tauri_clients() {
-        let error =
-            ProjectPullRequestMergeError::conflict("main".to_string(), "feature/demo".to_string());
-        let value = serde_json::to_value(error).expect("serialize merge conflict");
-
-        assert_eq!(value["code"], "merge_conflict");
-        assert_eq!(value["recovery"]["targetBranch"], "main");
-        assert_eq!(value["recovery"]["sourceBranch"], "feature/demo");
-    }
-
-    #[test]
-    fn merge_error_classification_only_recovers_conflicts() {
-        let conflict = classify_merge_error(
-            "CONFLICT (content): Merge conflict in src/main.rs".to_string(),
-            true,
-            "main",
-            "feature/demo",
-        );
-        assert_eq!(conflict.code, "merge_conflict");
-        assert!(conflict.recovery.is_some());
-
-        let other = classify_merge_error(
-            "fatal: refusing to merge unrelated histories".to_string(),
-            false,
-            "main",
-            "feature/demo",
-        );
-        assert_eq!(other.code, "merge_failed");
-        assert!(other.recovery.is_none());
-    }
-
     #[test]
     fn merged_status_is_signed_by_repository_owner() {
         let keys = Keys::generate();
diff --git a/desktop/src-tauri/src/commands/team_snapshot.rs b/desktop/src-tauri/src/commands/team_snapshot.rs
index 91a0126f58..97cd11933d 100644
--- a/desktop/src-tauri/src/commands/team_snapshot.rs
+++ b/desktop/src-tauri/src/commands/team_snapshot.rs
@@ -895,7 +895,7 @@ fn retain_agent_pending(app: &AppHandle, state: &AppState, record: &ManagedAgent
 
 /// POST a pre-built signed engram event to the relay, authenticating as the
 /// new agent. Mirrors the same helper in `snapshot::import`.
-async fn submit_engram_event(
+pub(crate) async fn submit_engram_event(
     state: &AppState,
     agent_keys: &nostr::Keys,
     event_json: &[u8],
@@ -905,6 +905,8 @@ async fn submit_engram_event(
     use crate::relay::build_nip98_auth_header_for_keys;
     use reqwest::Method;
 
+    crate::egress_guard::assert_no_key_backup_bytes(event_json, "team snapshot engram submit")?;
+
     // Wait before signing: the relay enforces NIP-98 freshness (±60s) and the
     // gate may hold for up to MAX_HINT_SECONDS (300s). Building auth before the
     // wait produces a stale `created_at` that the relay will reject.
diff --git a/desktop/src-tauri/src/commands/team_snapshot/tests.rs b/desktop/src-tauri/src/commands/team_snapshot/tests.rs
index 0616411307..c9a6d8812a 100644
--- a/desktop/src-tauri/src/commands/team_snapshot/tests.rs
+++ b/desktop/src-tauri/src/commands/team_snapshot/tests.rs
@@ -733,3 +733,31 @@ fn full_rollback_at_teams_boundary_absent_agents_store() {
     assert!(!teams_path.exists());
     assert_eq!(errors.len(), 1, "only the teams-write error");
 }
+
+// ── NIP-49 egress guard: boundary 6 (team snapshot engram submit) ────────────
+
+mod egress_guard_boundary {
+    use super::super::submit_engram_event;
+
+    const NCRYPTSEC: &str = "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+
+    /// An engram body carrying an ncryptsec must be rejected by the guard
+    /// before any network I/O (the target port is a discard address; a guard
+    /// error — not a connection error — proves the abort ordering).
+    #[tokio::test]
+    async fn blocks_ncryptsec_before_network() {
+        let state = crate::app_state::build_app_state();
+        let keys = nostr::Keys::generate();
+        let body = format!("{{\"content\":\"{NCRYPTSEC}\"}}");
+        let err = submit_engram_event(
+            &state,
+            &keys,
+            body.as_bytes(),
+            "http://127.0.0.1:9/events",
+            None,
+        )
+        .await
+        .unwrap_err();
+        assert!(err.contains("key-backup material"), "{err}");
+    }
+}
diff --git a/desktop/src-tauri/src/egress_guard.rs b/desktop/src-tauri/src/egress_guard.rs
new file mode 100644
index 0000000000..db58ddafa0
--- /dev/null
+++ b/desktop/src-tauri/src/egress_guard.rs
@@ -0,0 +1,58 @@
+//! Relay egress guard for NIP-49 key-backup material.
+//!
+//! The local `ncryptsec` backup (see [`crate::key_backup`]) must NEVER be
+//! transmitted to a relay. This module enforces that contract at runtime,
+//! fail-closed, at every relay-bound egress boundary:
+//!
+//! | # | Boundary | Site |
+//! |---|----------|------|
+//! | 1 | `submit_signed_event_at_with_keys` (funnel for `submit_event*`) | `relay/submit.rs` |
+//! | 2 | `sync_managed_agent_profile` | `relay.rs` |
+//! | 3 | pre-signed path into the boundary-1 funnel | `relay/submit.rs` |
+//! | 4 | `submit_signed_event_with_keys` | `relay.rs` |
+//! | 5 | huddle STT publisher | `huddle/pipeline.rs` |
+//! | 6 | `submit_engram_event` (team snapshot) | `commands/team_snapshot.rs` |
+//! | 7 | `submit_engram_event` (persona import) | `commands/personas/snapshot/import.rs` |
+//! | 8 | native websocket send loop (all webview relay WS) | `native_websocket.rs` |
+//!
+//! The inventory-completeness test in `egress_guard_tests.rs` asserts that
+//! every `/events` URL-construction site in the tree calls this guard, so a
+//! new submission path fails the build until it is wired.
+//!
+//! Scope: `ncryptsec1` only. The raw `nsec` intentionally transits the
+//! NIP-44-encrypted pairing session (NIP-AB payload_type "nsec"); guarding it
+//! here would break pairing. Raw-key DLP is separate policy work.
+
+/// Bech32 HRP of NIP-49 encrypted secret keys.
+const NCRYPTSEC_PREFIX: &str = "ncryptsec1";
+/// Bech32 also permits an ALL-UPPERCASE encoding of the same payload
+/// (BIP-173); an uppercased valid backup decodes identically, so the guard
+/// must reject it too. Mixed case is invalid bech32 and cannot decode — a
+/// substring matching either all-lower or all-upper prefix covers every
+/// decodable form.
+const NCRYPTSEC_PREFIX_UPPER: &str = "NCRYPTSEC1";
+
+/// Reject `text` if it contains NIP-49 key-backup material.
+///
+/// Returns `Err` when an `ncryptsec1…` (or uppercase `NCRYPTSEC1…`)
+/// substring is present. Callers MUST abort the network operation on `Err` —
+/// this is a fail-closed guard, not a warning.
+pub fn assert_no_key_backup(text: &str, context: &'static str) -> Result<(), String> {
+    if text.contains(NCRYPTSEC_PREFIX) || text.contains(NCRYPTSEC_PREFIX_UPPER) {
+        return Err(format!(
+            "blocked {context}: payload contains NIP-49 key-backup material \
+             (ncryptsec); the local key backup must never be transmitted to a relay"
+        ));
+    }
+    Ok(())
+}
+
+/// Byte-slice variant for callers that hold serialized bodies.
+pub fn assert_no_key_backup_bytes(body: &[u8], context: &'static str) -> Result<(), String> {
+    // ncryptsec is ASCII bech32; a UTF-8-lossy view preserves any occurrence.
+    assert_no_key_backup(&String::from_utf8_lossy(body), context)
+}
+
+#[cfg(test)]
+#[path = "egress_guard_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/egress_guard_tests.rs b/desktop/src-tauri/src/egress_guard_tests.rs
new file mode 100644
index 0000000000..f487c8ce16
--- /dev/null
+++ b/desktop/src-tauri/src/egress_guard_tests.rs
@@ -0,0 +1,446 @@
+use super::*;
+
+/// NIP-49 spec vector — a real ncryptsec blob for injection payloads.
+const NCRYPTSEC: &str = "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+
+fn assert_guard_error(err: &str) {
+    assert!(
+        err.contains("key-backup material"),
+        "expected the egress-guard error, got: {err}"
+    );
+}
+
+// ── Guard unit behavior ───────────────────────────────────────────────────────
+
+#[test]
+fn rejects_ncryptsec_anywhere_in_text() {
+    assert_guard_error(&assert_no_key_backup(NCRYPTSEC, "test").unwrap_err());
+    assert_guard_error(
+        &assert_no_key_backup(
+            &format!("{{\"content\":\"my backup: {NCRYPTSEC}\"}}"),
+            "test",
+        )
+        .unwrap_err(),
+    );
+}
+
+/// Bech32 permits an all-uppercase encoding of the same payload — an
+/// uppercased valid backup must not bypass the guard (text and bytes).
+/// Mixed case is invalid bech32 (cannot decode) and is deliberately not
+/// blocked.
+#[test]
+fn rejects_uppercase_ncryptsec() {
+    let upper = NCRYPTSEC.to_ascii_uppercase();
+    assert_guard_error(&assert_no_key_backup(&upper, "test").unwrap_err());
+    assert_guard_error(&assert_no_key_backup_bytes(upper.as_bytes(), "test").unwrap_err());
+    // Mixed case cannot decode; not blocked.
+    assert!(assert_no_key_backup("nCrYpTsEc1qgg9947r", "test").is_ok());
+}
+
+#[test]
+fn passes_clean_payloads_including_raw_nsec() {
+    assert!(assert_no_key_backup("hello world", "test").is_ok());
+    assert!(assert_no_key_backup("", "test").is_ok());
+    // Scope is ncryptsec1 ONLY: raw nsec intentionally transits the encrypted
+    // pairing session and must NOT be blocked (plan D4 / pairing.rs).
+    let nsec = nostr::ToBech32::to_bech32(nostr::Keys::generate().secret_key()).unwrap();
+    assert!(assert_no_key_backup(&nsec, "test").is_ok());
+    // Near-miss prefixes are not blocked.
+    assert!(assert_no_key_backup("ncryptsec", "test").is_ok());
+}
+
+#[test]
+fn byte_variant_matches_text_variant() {
+    assert_guard_error(&assert_no_key_backup_bytes(NCRYPTSEC.as_bytes(), "test").unwrap_err());
+    assert!(assert_no_key_backup_bytes(b"clean body", "test").is_ok());
+    // Invalid UTF-8 around an intact ncryptsec substring must still trip the
+    // guard (from_utf8_lossy preserves the ASCII run).
+    let mut body = vec![0xff, 0xfe];
+    body.extend_from_slice(NCRYPTSEC.as_bytes());
+    body.push(0xff);
+    assert_guard_error(&assert_no_key_backup_bytes(&body, "test").unwrap_err());
+}
+
+#[test]
+fn error_names_the_boundary_context() {
+    let err = assert_no_key_backup(NCRYPTSEC, "huddle STT publish").unwrap_err();
+    assert!(err.contains("huddle STT publish"), "{err}");
+}
+
+// ── Runtime injection per boundary ────────────────────────────────────────────
+//
+// Each test drives the real production function with an ncryptsec-bearing
+// payload and asserts the guard aborts the operation before any network I/O
+// (no listener exists at the target address; a distinctive guard error — not
+// a connection error — proves the abort happened first).
+//
+// Boundaries 6 and 7 (`submit_engram_event` twins) are module-private inside
+// `commands`; their injection tests live next to them:
+//   - commands/team_snapshot/tests.rs::egress_guard_boundary
+//   - commands/personas/snapshot/import.rs::egress_guard_tests
+
+/// Boundary 1: `relay/submit.rs` `submit_event_at_with_keys` (the funnel for
+/// all `submit_event*` variants).
+#[tokio::test]
+async fn boundary_submit_event_at_with_keys_blocks_ncryptsec() {
+    let state = crate::app_state::build_app_state();
+    let keys = nostr::Keys::generate();
+    let builder = nostr::EventBuilder::new(nostr::Kind::Custom(9), NCRYPTSEC);
+    let err = crate::relay::submit_event_at_with_keys(
+        builder,
+        &state,
+        "http://127.0.0.1:9", // discard port — must never be reached
+        &keys,
+    )
+    .await
+    .unwrap_err();
+    assert_guard_error(&err);
+}
+
+/// Boundary 2: `relay.rs` `sync_managed_agent_profile` (agent kind:0 profile).
+#[tokio::test]
+async fn boundary_sync_managed_agent_profile_blocks_ncryptsec() {
+    let state = crate::app_state::build_app_state();
+    let keys = nostr::Keys::generate();
+    let err = crate::relay::sync_managed_agent_profile(
+        &state,
+        "ws://127.0.0.1:9",
+        &keys,
+        &format!("agent {NCRYPTSEC}"),
+        None,
+        None,
+    )
+    .await
+    .unwrap_err();
+    assert_guard_error(&err);
+}
+
+/// Boundary 3: `relay/submit.rs` `submit_signed_event_at_with_keys` — the
+/// pre-signed entry into the boundary-1 funnel (main's submit refactor
+/// replaced `relay.rs` `submit_signed_event` with this scoped form).
+#[tokio::test]
+async fn boundary_submit_signed_event_at_with_keys_blocks_ncryptsec() {
+    let state = crate::app_state::build_app_state();
+    let keys = nostr::Keys::generate();
+    let event = nostr::EventBuilder::new(nostr::Kind::Custom(9), NCRYPTSEC)
+        .sign_with_keys(&keys)
+        .unwrap();
+    let err = crate::relay::submit_signed_event_at_with_keys(
+        &event,
+        &state,
+        "http://127.0.0.1:9", // discard port — must never be reached
+        &keys,
+    )
+    .await
+    .unwrap_err();
+    assert_guard_error(&err);
+}
+
+/// Boundary 4: `relay.rs` `submit_signed_event_with_keys`.
+#[tokio::test]
+async fn boundary_submit_signed_event_with_keys_blocks_ncryptsec() {
+    let state = crate::app_state::build_app_state();
+    *state.relay_url_override.lock().unwrap() = Some("ws://127.0.0.1:9".to_string());
+    let keys = nostr::Keys::generate();
+    let event = nostr::EventBuilder::new(nostr::Kind::Custom(9), NCRYPTSEC)
+        .sign_with_keys(&keys)
+        .unwrap();
+    let err = crate::relay::submit_signed_event_with_keys(&event, &state, &keys, None)
+        .await
+        .unwrap_err();
+    assert_guard_error(&err);
+}
+
+/// Boundary 5: huddle STT publisher (`huddle/pipeline.rs`).
+#[test]
+fn boundary_huddle_stt_blocks_ncryptsec() {
+    let keys = nostr::Keys::generate();
+    let channel = uuid::Uuid::new_v4();
+    let builder =
+        crate::events::build_message(channel, NCRYPTSEC, None, &[], &[], &[], &[]).unwrap();
+    let err = crate::huddle::pipeline::sign_and_guard_stt_body(builder, &keys).unwrap_err();
+    assert_guard_error(&err);
+
+    // Clean transcripts pass through the same seam.
+    let builder =
+        crate::events::build_message(channel, "hello huddle", None, &[], &[], &[], &[]).unwrap();
+    assert!(crate::huddle::pipeline::sign_and_guard_stt_body(builder, &keys).is_ok());
+}
+
+/// Boundary 8: native websocket send loop — the single choke point for all
+/// webview-originated relay websocket frames.
+#[tokio::test]
+async fn boundary_native_websocket_blocks_ncryptsec() {
+    let manager = crate::native_websocket::WebSocketManager::default();
+    // Text frame: guard fires before the connection lookup, so no connection
+    // is needed — and the error must be the guard's, not "not found".
+    let err = crate::native_websocket::send_message(
+        &manager,
+        1,
+        crate::native_websocket::WebSocketMessage::Text(format!(
+            "[\"EVENT\",{{\"content\":\"{NCRYPTSEC}\"}}]"
+        )),
+    )
+    .await
+    .unwrap_err();
+    assert_guard_error(&err);
+
+    // Binary frame variant.
+    let err = crate::native_websocket::send_message(
+        &manager,
+        1,
+        crate::native_websocket::WebSocketMessage::Binary(NCRYPTSEC.as_bytes().to_vec()),
+    )
+    .await
+    .unwrap_err();
+    assert_guard_error(&err);
+
+    // Clean frames fall through to normal handling ("connection not found"
+    // here — the guard did not reject them).
+    let err = crate::native_websocket::send_message(
+        &manager,
+        1,
+        crate::native_websocket::WebSocketMessage::Text("[\"REQ\",\"sub\",{}]".to_string()),
+    )
+    .await
+    .unwrap_err();
+    assert!(err.contains("not found"), "{err}");
+}
+
+// ── Structural tripwires ──────────────────────────────────────────────────────
+
+fn src_rust_files() -> Vec<std::path::PathBuf> {
+    fn walk(dir: &std::path::Path, out: &mut Vec<std::path::PathBuf>) {
+        for entry in std::fs::read_dir(dir).unwrap() {
+            let path = entry.unwrap().path();
+            if path.is_dir() {
+                walk(&path, out);
+            } else if path.extension().and_then(|e| e.to_str()) == Some("rs") {
+                out.push(path);
+            }
+        }
+    }
+    let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
+    let mut out = Vec::new();
+    walk(&root, &mut out);
+    out
+}
+
+/// Site-granular `/events` inventory: `(file suffix, expected non-comment
+/// `/events` occurrences, expected guard call sites — full-path calls into
+/// the egress-guard module)`.
+///
+/// Every entry pairs the URL-construction count with the guard-call count for
+/// that file, so BOTH of these fail the scan (not just a brand-new file):
+///   - adding an unguarded ninth `/events` site inside an already-listed file
+///     (count goes up without a matching table update), and
+///   - removing/refactoring away a guard call while its egress site remains.
+///
+/// Updating a row here is the deliberate act that must accompany wiring the
+/// guard + adding an injection test for the new site.
+const EVENTS_INVENTORY: &[(&str, usize, usize)] = &[
+    // Production egress boundaries (see egress_guard.rs table):
+    ("src/relay.rs", 2, 2),                             // boundaries 2, 4
+    ("src/relay/submit.rs", 1, 1),                      // boundaries 1 + 3 (shared funnel)
+    ("src/huddle/pipeline.rs", 1, 1),                   // boundary 5
+    ("src/commands/team_snapshot.rs", 1, 1),            // boundary 6
+    ("src/commands/personas/snapshot/import.rs", 2, 1), // boundary 7 + its in-file injection-test fixture URL
+    ("src/native_websocket.rs", 0, 2),                  // boundary 8 (WS frames; no events URL)
+    // Test-only fixtures — no production egress, no guard:
+    ("src/relay_admission.rs", 1, 0),
+    ("src/archive/mod_tests.rs", 1, 0),
+    ("src/managed_agents/persona_events/tests.rs", 1, 0),
+    ("src/commands/team_snapshot/tests.rs", 1, 0),
+    // Mock-relay route in its in-file tests; production publish goes through
+    // the guarded boundary-1 funnel (`submit_signed_event_at_with_keys`).
+    ("src/commands/personas/sharing.rs", 1, 0),
+];
+
+// Needles are assembled at runtime so this scan file itself contains no
+// contiguous match and needs no self-referential inventory row.
+fn events_needle() -> String {
+    ["/ev", "ents"].concat()
+}
+fn guard_needle() -> String {
+    ["egress_guard::", "assert_no_key_backup"].concat()
+}
+
+/// Pure scan core over `(relative path, content)` pairs. Returns violations;
+/// empty means every file matches its inventory row exactly (files absent
+/// from the table are expected to have zero `/events` sites and zero guard
+/// calls).
+fn events_inventory_violations(files: &[(String, String)]) -> Vec<String> {
+    let events = events_needle();
+    let guard = guard_needle();
+    let mut violations = Vec::new();
+
+    for (rel, content) in files {
+        let expected = EVENTS_INVENTORY
+            .iter()
+            .find(|(suffix, _, _)| rel.ends_with(suffix))
+            .map(|&(_, e, g)| (e, g))
+            .unwrap_or((0, 0));
+
+        let mut event_sites = Vec::new();
+        for (i, line) in content.lines().enumerate() {
+            if line.trim_start().starts_with("//") {
+                continue; // doc/comment mentions
+            }
+            if line.contains(&events) {
+                event_sites.push(format!("  {rel}:{}: {}", i + 1, line.trim()));
+            }
+        }
+        let guard_count = content.matches(&guard).count();
+
+        if (event_sites.len(), guard_count) != expected {
+            violations.push(format!(
+                "{rel}: found {} events-URL site(s) + {} guard call(s), inventory \
+                 expects {} + {}. Sites found:\n{}",
+                event_sites.len(),
+                guard_count,
+                expected.0,
+                expected.1,
+                if event_sites.is_empty() {
+                    "  (none)".to_string()
+                } else {
+                    event_sites.join("\n")
+                },
+            ));
+        }
+    }
+    violations
+}
+
+fn read_src_files() -> Vec<(String, String)> {
+    let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+    src_rust_files()
+        .into_iter()
+        .map(|path| {
+            let rel = path
+                .strip_prefix(root)
+                .unwrap()
+                .to_string_lossy()
+                .replace('\\', "/");
+            let content = std::fs::read_to_string(&path).unwrap();
+            (rel, content)
+        })
+        .collect()
+}
+
+/// Inventory completeness: every `/events` URL-construction site in
+/// `desktop/src-tauri/src` must match the site-granular inventory above. A
+/// future ninth submission path — in a NEW file or an ALREADY-LISTED one —
+/// fails this test until its guard is wired, its injection test exists, and
+/// its inventory row is updated.
+#[test]
+fn events_url_inventory_is_fully_guarded() {
+    let violations = events_inventory_violations(&read_src_files());
+    assert!(
+        violations.is_empty(),
+        "events-URL egress inventory drift — wire crate::egress_guard, add an \
+         injection test, then update EVENTS_INVENTORY:\n{}",
+        violations.join("\n")
+    );
+}
+
+/// Mutation-style proof of the tripwire's guarantee: an unguarded ninth
+/// `/events` site added to an already-inventoried file (relay.rs) is caught.
+#[test]
+fn inventory_scan_catches_new_site_in_allowlisted_file() {
+    let mut files = read_src_files();
+    let relay = files
+        .iter_mut()
+        .find(|(rel, _)| rel.ends_with("src/relay.rs"))
+        .expect("relay.rs must be in the scan set");
+    relay.1.push_str(&format!(
+        "\nfn sneaky_ninth_site(base: &str) -> String {{ format!(\"{{base}}{}\") }}\n",
+        events_needle()
+    ));
+    let violations = events_inventory_violations(&files);
+    assert!(
+        violations.iter().any(|v| v.contains("src/relay.rs")),
+        "an unguarded ninth events-URL site in relay.rs must trip the scan: {violations:?}"
+    );
+}
+
+/// The pairing also fires in reverse: a guard call deleted while its egress
+/// site remains is caught.
+#[test]
+fn inventory_scan_catches_removed_guard_call() {
+    let mut files = read_src_files();
+    let relay = files
+        .iter_mut()
+        .find(|(rel, _)| rel.ends_with("src/relay.rs"))
+        .expect("relay.rs must be in the scan set");
+    relay.1 = relay.1.replacen(&guard_needle(), "removed_guard", 1);
+    let violations = events_inventory_violations(&files);
+    assert!(
+        violations.iter().any(|v| v.contains("src/relay.rs")),
+        "a removed guard call in relay.rs must trip the scan: {violations:?}"
+    );
+}
+
+/// A brand-new file with an `/events` site (no inventory row) is caught.
+#[test]
+fn inventory_scan_catches_new_unlisted_file() {
+    let mut files = read_src_files();
+    files.push((
+        "src/brand_new_egress.rs".to_string(),
+        format!("let url = format!(\"{{}}{}\", base);", events_needle()),
+    ));
+    let violations = events_inventory_violations(&files);
+    assert!(
+        violations
+            .iter()
+            .any(|v| v.contains("src/brand_new_egress.rs")),
+        "{violations:?}"
+    );
+}
+
+/// Source allowlist: NIP-49 material handling is confined to the identity /
+/// backup / import / guard files. Anything else touching ncryptsec or the
+/// nip49 codec is structural drift.
+#[test]
+fn ncryptsec_handling_is_confined_to_allowlisted_files() {
+    let allowlist: &[&str] = &[
+        "src/key_backup.rs",
+        "src/key_backup_tests.rs",
+        "src/egress_guard.rs",
+        "src/egress_guard_tests.rs",
+        "src/commands/identity.rs",
+        "src/commands/identity_key_backup_tests.rs",
+        "src/lib.rs", // module registration + invoke handler
+        // boundary wiring (guard call sites name the module, not the codec):
+        "src/relay.rs",
+        "src/relay/submit.rs",
+        "src/huddle/pipeline.rs",
+        "src/commands/team_snapshot.rs",
+        "src/commands/team_snapshot/tests.rs",
+        "src/commands/personas/snapshot/import.rs",
+        "src/native_websocket.rs",
+    ];
+
+    let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+    let mut violations = Vec::new();
+    for path in src_rust_files() {
+        let rel = path
+            .strip_prefix(root)
+            .unwrap()
+            .to_string_lossy()
+            .replace('\\', "/");
+        if allowlist.iter().any(|a| rel.ends_with(a)) {
+            continue;
+        }
+        let content = std::fs::read_to_string(&path).unwrap();
+        for needle in ["ncryptsec", "EncryptedSecretKey", "nip49"] {
+            if content.contains(needle) {
+                violations.push(format!("{rel}: contains {needle:?}"));
+            }
+        }
+    }
+    assert!(
+        violations.is_empty(),
+        "NIP-49 material outside allowlisted files:\n{}",
+        violations.join("\n")
+    );
+}
diff --git a/desktop/src-tauri/src/event_sync.rs b/desktop/src-tauri/src/event_sync.rs
index d9fe6acdb9..ee8e0d8b10 100644
--- a/desktop/src-tauri/src/event_sync.rs
+++ b/desktop/src-tauri/src/event_sync.rs
@@ -165,7 +165,7 @@ fn migrate_personas_in_dir_at(
         scoped_record.shared = existing
             .as_ref()
             .and_then(|row| nostr::Event::from_json(&row.raw_event).ok())
-            .is_some_and(|event| buzz_core_pkg::kind::persona_event_is_shared(&event));
+            .is_some_and(|event| buzz_core_pkg::kind::event_is_shared(&event));
         let event = build_persona_event(&scoped_record)
             .map_err(|e| format!("failed to build event for '{}': {e}", record.display_name))?
             .custom_created_at(monotonic_created_at(
diff --git a/desktop/src-tauri/src/huddle/agent_tts_routing.rs b/desktop/src-tauri/src/huddle/agent_tts_routing.rs
new file mode 100644
index 0000000000..2ee3ec0d41
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/agent_tts_routing.rs
@@ -0,0 +1,56 @@
+use super::HuddlePhase;
+
+#[derive(Debug, PartialEq, Eq)]
+pub(super) enum AgentTtsRuntimeGate {
+    Disabled,
+    Inactive,
+    NeedsPipeline,
+    Ready,
+}
+
+pub(super) fn classify_agent_tts_runtime(
+    enabled: bool,
+    phase: &HuddlePhase,
+    has_pipeline: bool,
+) -> AgentTtsRuntimeGate {
+    if !enabled {
+        AgentTtsRuntimeGate::Disabled
+    } else if !matches!(phase, HuddlePhase::Connected | HuddlePhase::Active) {
+        AgentTtsRuntimeGate::Inactive
+    } else if has_pipeline {
+        AgentTtsRuntimeGate::Ready
+    } else {
+        AgentTtsRuntimeGate::NeedsPipeline
+    }
+}
+
+/// Maximum text length accepted for TTS synthesis.
+/// ~2000 chars is 1–2 minutes of speech. Longer messages are truncated.
+pub(super) const MAX_TTS_TEXT_LEN: usize = 2000;
+
+pub(super) fn normalize_agent_tts_text(text: String) -> String {
+    if text.chars().count() > MAX_TTS_TEXT_LEN {
+        let mut truncated: String = text.chars().take(MAX_TTS_TEXT_LEN).collect();
+        truncated.push_str("... message truncated.");
+        truncated
+    } else {
+        text
+    }
+}
+
+pub(super) async fn enqueue_agent_tts_text<F>(
+    route_id: u64,
+    text: String,
+    enqueue: F,
+) -> Result<(), String>
+where
+    F: FnOnce(u64, String) -> Result<(), String> + Send + 'static,
+{
+    tokio::task::spawn_blocking(move || enqueue(route_id, text))
+        .await
+        .map_err(|error| format!("TTS enqueue task failed: {error}"))?
+}
+
+#[cfg(test)]
+#[path = "agent_tts_routing_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/huddle/agent_tts_routing_tests.rs b/desktop/src-tauri/src/huddle/agent_tts_routing_tests.rs
new file mode 100644
index 0000000000..cb550d7005
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/agent_tts_routing_tests.rs
@@ -0,0 +1,57 @@
+use super::{
+    classify_agent_tts_runtime, enqueue_agent_tts_text, normalize_agent_tts_text,
+    AgentTtsRuntimeGate, MAX_TTS_TEXT_LEN,
+};
+use crate::huddle::HuddlePhase;
+
+#[tokio::test]
+async fn assistant_plain_text_routes_unchanged_into_voice_pipeline_boundary() {
+    let (sender, receiver) = std::sync::mpsc::channel();
+    let text = "A newly submitted assistant reply.".to_string();
+    let route_id = 42;
+
+    enqueue_agent_tts_text(route_id, text.clone(), move |route_id, queued| {
+        sender
+            .send((route_id, queued))
+            .map_err(|error| error.to_string())
+    })
+    .await
+    .expect("route assistant text");
+
+    assert_eq!(
+        receiver.recv().expect("queued text"),
+        (route_id, text),
+        "route correlation must survive the native queue boundary"
+    );
+}
+
+#[test]
+fn disabled_is_the_only_intentional_runtime_no_op() {
+    assert_eq!(
+        classify_agent_tts_runtime(false, &HuddlePhase::Connected, false),
+        AgentTtsRuntimeGate::Disabled
+    );
+    assert_eq!(
+        classify_agent_tts_runtime(true, &HuddlePhase::Idle, false),
+        AgentTtsRuntimeGate::Inactive
+    );
+    assert_eq!(
+        classify_agent_tts_runtime(true, &HuddlePhase::Connected, false),
+        AgentTtsRuntimeGate::NeedsPipeline
+    );
+    assert_eq!(
+        classify_agent_tts_runtime(true, &HuddlePhase::Connected, true),
+        AgentTtsRuntimeGate::Ready
+    );
+}
+
+#[test]
+fn assistant_text_truncation_is_unicode_safe_before_voice_routing() {
+    let input = "🦀".repeat(MAX_TTS_TEXT_LEN + 1);
+    let output = normalize_agent_tts_text(input);
+    assert_eq!(
+        output.chars().count(),
+        MAX_TTS_TEXT_LEN + "... message truncated.".chars().count()
+    );
+    assert!(output.ends_with("... message truncated."));
+}
diff --git a/desktop/src-tauri/src/huddle/agents.rs b/desktop/src-tauri/src/huddle/agents.rs
index 02c4045410..2de22f99d8 100644
--- a/desktop/src-tauri/src/huddle/agents.rs
+++ b/desktop/src-tauri/src/huddle/agents.rs
@@ -2,7 +2,8 @@
 //!
 //! Mental model:
 //!   add_agent_to_huddle → kind:9000 to ephemeral channel
-//!                       → kind:9000 to parent channel (best-effort)
+//!                       → preserve existing parent membership, or
+//!                         kind:9000 to parent channel (best-effort)
 //!
 //! ACP spawning is NOT needed here: the running agent process auto-subscribes
 //! when it receives the kind:9000 membership notification. Huddle-specific
@@ -11,7 +12,10 @@
 use serde::Serialize;
 use uuid::Uuid;
 
-use crate::{app_state::AppState, events, relay::submit_event};
+use crate::{
+    app_state::AppState, events, huddle::relay_api::fetch_channel_members_with_roles,
+    relay::submit_event,
+};
 
 // ── Constants ─────────────────────────────────────────────────────────────────
 
@@ -61,8 +65,9 @@ with the next one.
 /// The field exists for forward compatibility with future batch-add operations
 /// where partial success may be meaningful.
 ///
-/// `parent_added` reflects whether the parent-channel add succeeded;
-/// `parent_error` carries the error string when it didn't.
+/// `parent_added` reflects whether the parent already contained the agent or
+/// the parent-channel add succeeded; `parent_error` carries the error string
+/// when neither condition could be confirmed.
 #[derive(Debug, Serialize)]
 pub struct AgentAddResult {
     /// Always `true` — invariant guaranteed by [`add_agent_to_huddle`].
@@ -91,17 +96,33 @@ pub async fn add_agent_to_huddle(
     let add_eph = events::build_add_member(ephemeral_channel_id, agent_pubkey, Some("bot"))?;
     submit_event(add_eph, state).await?;
 
-    // 2. Add agent to parent channel — so agent has full context.
-    //    Best-effort: capture the error but don't propagate it.
-    let (parent_added, parent_error) = {
+    // 2. Preserve any active parent membership, regardless of role. Rewriting
+    //    an existing DM member as `bot` is both unnecessary and forbidden for
+    //    non-admins. Otherwise add the agent so it has full context.
+    //    Best-effort: capture a real error but don't propagate it.
+    let parent_channel_id_string = parent_channel_id.to_string();
+    let parent_already_contains_agent =
+        fetch_channel_members_with_roles(&parent_channel_id_string, state)
+            .await
+            .is_ok_and(|members| contains_member(&members, agent_pubkey));
+
+    let (parent_added, parent_error) = if parent_already_contains_agent {
+        (true, None)
+    } else {
         let add_parent = events::build_add_member(parent_channel_id, agent_pubkey, Some("bot"))?;
         match submit_event(add_parent, state).await {
             Ok(_) => (true, None),
             Err(e) => {
-                eprintln!(
-                    "buzz-desktop: add agent to parent channel failed (may already be member): {e}"
-                );
-                (false, Some(e))
+                let active_after_error =
+                    fetch_channel_members_with_roles(&parent_channel_id_string, state)
+                        .await
+                        .is_ok_and(|members| contains_member(&members, agent_pubkey));
+                if active_after_error {
+                    (true, None)
+                } else {
+                    eprintln!("buzz-desktop: add agent to parent channel failed: {e}");
+                    (false, Some(e))
+                }
             }
         }
     };
@@ -112,3 +133,26 @@ pub async fn add_agent_to_huddle(
         parent_error,
     })
 }
+
+fn contains_member(members: &[(String, Option<String>)], pubkey: &str) -> bool {
+    members
+        .iter()
+        .any(|(member_pubkey, _)| member_pubkey.eq_ignore_ascii_case(pubkey))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::contains_member;
+
+    #[test]
+    fn existing_parent_membership_is_preserved_regardless_of_role() {
+        let members = vec![
+            ("agent-member".to_owned(), Some("member".to_owned())),
+            ("agent-bot".to_owned(), Some("bot".to_owned())),
+        ];
+
+        assert!(contains_member(&members, "AGENT-MEMBER"));
+        assert!(contains_member(&members, "agent-bot"));
+        assert!(!contains_member(&members, "missing"));
+    }
+}
diff --git a/desktop/src-tauri/src/huddle/audio_output.rs b/desktop/src-tauri/src/huddle/audio_output.rs
index dbd09353db..34dec53094 100644
--- a/desktop/src-tauri/src/huddle/audio_output.rs
+++ b/desktop/src-tauri/src/huddle/audio_output.rs
@@ -39,7 +39,8 @@ fn list_audio_output_devices_blocking() -> Result<Vec<AudioOutputDevice>, String
 #[tauri::command]
 pub fn set_audio_output_device(name: String, state: State<'_, AppState>) -> Result<(), String> {
     let mut guard = state
-        .audio_output_device
+        .huddle_audio
+        .output_device
         .lock()
         .map_err(|e| e.to_string())?;
     *guard = if name.is_empty() { None } else { Some(name) };
@@ -50,7 +51,8 @@ pub fn set_audio_output_device(name: String, state: State<'_, AppState>) -> Resu
 #[tauri::command]
 pub fn get_audio_output_device(state: State<'_, AppState>) -> Result<String, String> {
     let guard = state
-        .audio_output_device
+        .huddle_audio
+        .output_device
         .lock()
         .map_err(|e| e.to_string())?;
     Ok(guard.clone().unwrap_or_default())
diff --git a/desktop/src-tauri/src/huddle/mod.rs b/desktop/src-tauri/src/huddle/mod.rs
index a815bf2d06..03264f80f4 100644
--- a/desktop/src-tauri/src/huddle/mod.rs
+++ b/desktop/src-tauri/src/huddle/mod.rs
@@ -23,6 +23,7 @@
 //!    takes `stt_pipeline`/`tts_pipeline` out of the lock, then calls `shutdown()`
 //!    and drops them outside the lock (thread joins can block ~200ms).
 
+mod agent_tts_routing;
 pub mod agents;
 pub mod audio_output;
 pub mod jitter;
@@ -37,6 +38,9 @@ pub mod state;
 pub mod stt;
 pub mod transcription;
 pub mod tts;
+pub mod tts_settings;
+mod tts_voice_import;
+mod tts_voice_registry;
 pub mod wire;
 
 // ── Shared utilities ──────────────────────────────────────────────────────────
@@ -63,16 +67,25 @@ pub(super) fn drain_until_shutdown<T>(
 
 pub use state::{HuddleJoinInfo, HuddlePhase, HuddleState, VoiceInputMode};
 pub use transcription::{set_huddle_transcription_enabled, start_stt_pipeline};
+pub use tts_settings::set_tts_enabled;
 
 // ── Imports ───────────────────────────────────────────────────────────────────
 
-use std::sync::{atomic::Ordering, Arc};
+use std::sync::atomic::Ordering;
 use tauri::State;
 use uuid::Uuid;
 
 use crate::{app_state::AppState, events, relay::submit_event};
 
-use pipeline::{maybe_start_stt_pipeline, maybe_start_tts_pipeline, post_connect_setup};
+use agent_tts_routing::{
+    classify_agent_tts_runtime, enqueue_agent_tts_text, normalize_agent_tts_text,
+    AgentTtsRuntimeGate,
+};
+pub use pipeline::check_pipeline_hotstart;
+use pipeline::{
+    await_inflight_tts_start, maybe_start_stt_pipeline, maybe_start_tts_pipeline,
+    post_connect_setup, start_auto_enabled_transcription, PostConnectOutcome,
+};
 use relay_api::{
     count_human_members, fetch_channel_members, parse_channel_uuid, validate_pubkey_hex,
     MAX_HUDDLE_AGENTS,
@@ -186,7 +199,7 @@ pub async fn start_huddle(
     };
 
     // Transition to Creating.
-    {
+    let huddle_generation = {
         let mut hs = state.huddle()?;
         if hs.phase != HuddlePhase::Idle {
             return Err(format!(
@@ -194,9 +207,11 @@ pub async fn start_huddle(
                 hs.phase
             ));
         }
+        let generation = hs.begin_huddle_lifetime();
         hs.phase = HuddlePhase::Creating;
         hs.parent_channel_id = Some(parent_channel_id.clone());
-    }
+        generation
+    };
 
     let ephemeral_uuid = Uuid::new_v4();
     let ephemeral_channel_id = ephemeral_uuid.to_string();
@@ -259,27 +274,33 @@ pub async fn start_huddle(
     match result {
         Ok(successful_agents) => {
             // 5. Store active state.
-            {
+            let committed = {
                 let mut hs = state.huddle()?;
-                hs.phase = HuddlePhase::Connected;
-                hs.is_creator = true;
-                hs.ephemeral_channel_id = Some(ephemeral_channel_id.clone());
-                // Only store agents that were successfully enrolled.
-                *hs.agent_pubkeys.lock().unwrap_or_else(|e| e.into_inner()) =
-                    successful_agents.clone();
-                // Include the current user + successfully enrolled agents as participants.
-                // Use successful_agents (not member_pubkeys) so failed enrollments
-                // are not reflected in the participant list.
-                let own_pubkey = state
-                    .keys
-                    .lock()
-                    .map(|k| k.public_key().to_hex())
-                    .unwrap_or_default();
-                let mut participants = successful_agents.clone();
-                if !own_pubkey.is_empty() && !participants.contains(&own_pubkey) {
-                    participants.insert(0, own_pubkey);
+                if !hs.owns_huddle_lifetime(huddle_generation, HuddlePhase::Creating) {
+                    false
+                } else {
+                    hs.phase = HuddlePhase::Connected;
+                    hs.is_creator = true;
+                    hs.ephemeral_channel_id = Some(ephemeral_channel_id.clone());
+                    *hs.agent_pubkeys.lock().unwrap_or_else(|e| e.into_inner()) =
+                        successful_agents.clone();
+                    hs.maybe_auto_enable_transcription_for_agents();
+                    let own_pubkey = state
+                        .keys
+                        .lock()
+                        .map(|k| k.public_key().to_hex())
+                        .unwrap_or_default();
+                    let mut participants = successful_agents.clone();
+                    if !own_pubkey.is_empty() && !participants.contains(&own_pubkey) {
+                        participants.insert(0, own_pubkey);
+                    }
+                    hs.participants = participants;
+                    true
                 }
-                hs.participants = participants;
+            };
+            if !committed {
+                emit_end_and_archive(&parent_channel_id, &ephemeral_channel_id, &state).await;
+                return Err("huddle start was superseded".to_owned());
             }
 
             // 6. Notify frontend of state change.
@@ -287,16 +308,30 @@ pub async fn start_huddle(
 
             // 7. Hydrate members, download models, start pipelines (incl. audio relay).
             // Audio relay failure is fatal — no point in a huddle without audio.
-            if let Err(e) = post_connect_setup(&state, &ephemeral_channel_id).await {
-                // Rollback: audio relay failed after state was committed.
-                // Publish the terminal lifecycle event before archiving so
-                // other clients do not reconstruct a phantom active huddle.
-                emit_end_and_archive(&parent_channel_id, &ephemeral_channel_id, &state).await;
-                if let Ok(mut hs) = state.huddle_state.lock() {
-                    hs.reset_preserving_generation();
+            match post_connect_setup(&state, &ephemeral_channel_id, huddle_generation).await {
+                Ok(PostConnectOutcome::Ready) => {}
+                Ok(PostConnectOutcome::Stale) => {
+                    return Err("huddle start was superseded".to_owned());
+                }
+                Err(e) => {
+                    // Roll back only if this failed setup still owns the active
+                    // huddle. A stale failure must not tear down its replacement.
+                    let still_current = state
+                        .huddle()
+                        .map(|hs| hs.is_current_huddle(&ephemeral_channel_id, huddle_generation))
+                        .unwrap_or(false);
+                    if still_current {
+                        emit_end_and_archive(&parent_channel_id, &ephemeral_channel_id, &state)
+                            .await;
+                        if let Ok(mut hs) = state.huddle_state.lock() {
+                            if hs.is_current_huddle(&ephemeral_channel_id, huddle_generation) {
+                                hs.reset_preserving_generation();
+                            }
+                        }
+                        state.emit_huddle_state_changed();
+                    }
+                    return Err(e);
                 }
-                state.emit_huddle_state_changed();
-                return Err(e);
             }
 
             Ok(HuddleJoinInfo {
@@ -314,11 +349,11 @@ pub async fn start_huddle(
                     }
                 }
             }
-            // Reset state to Idle so the user can retry.
-            // Preserve session_generation so in-flight transcription tasks
-            // from a prior session still see a stale generation and exit.
+            // Reset only if this failed attempt still owns the Creating state.
             if let Ok(mut hs) = state.huddle_state.lock() {
-                hs.reset_preserving_generation();
+                if hs.owns_huddle_lifetime(huddle_generation, HuddlePhase::Creating) {
+                    hs.reset_preserving_generation();
+                }
             }
             Err(e)
         }
@@ -340,7 +375,7 @@ pub async fn join_huddle(
     state: State<'_, AppState>,
 ) -> Result<HuddleJoinInfo, String> {
     // Transition to Connecting.
-    {
+    let huddle_generation = {
         let mut hs = state.huddle()?;
         if hs.phase != HuddlePhase::Idle {
             return Err(format!(
@@ -348,10 +383,12 @@ pub async fn join_huddle(
                 hs.phase
             ));
         }
+        let generation = hs.begin_huddle_lifetime();
         hs.phase = HuddlePhase::Connecting;
         hs.parent_channel_id = Some(parent_channel_id.clone());
         hs.ephemeral_channel_id = Some(ephemeral_channel_id.clone());
-    }
+        generation
+    };
 
     // Seed participant list with own pubkey as a fallback until relay responds.
     let own_pubkey = state
@@ -360,12 +397,20 @@ pub async fn join_huddle(
         .map(|k| k.public_key().to_hex())
         .unwrap_or_default();
 
-    {
+    let committed = {
         let mut hs = state.huddle()?;
-        hs.phase = HuddlePhase::Connected;
-        if !own_pubkey.is_empty() {
-            hs.participants = vec![own_pubkey];
+        if !hs.owns_huddle_lifetime(huddle_generation, HuddlePhase::Connecting) {
+            false
+        } else {
+            hs.phase = HuddlePhase::Connected;
+            if !own_pubkey.is_empty() {
+                hs.participants = vec![own_pubkey];
+            }
+            true
         }
+    };
+    if !committed {
+        return Err("huddle join was superseded".to_owned());
     }
 
     // Notify frontend of state change.
@@ -373,15 +418,25 @@ pub async fn join_huddle(
 
     // Hydrate members, download models, start pipelines (incl. audio relay).
     // Audio relay failure is fatal — no point in a huddle without audio.
-    if let Err(e) = post_connect_setup(&state, &ephemeral_channel_id).await {
-        // Rollback: audio relay failed after state was committed.
-        // Reset state to Idle so the user can retry. The ephemeral channel
-        // has a TTL and will expire — no manual archive needed for joiners.
-        if let Ok(mut hs) = state.huddle_state.lock() {
-            hs.reset_preserving_generation();
+    match post_connect_setup(&state, &ephemeral_channel_id, huddle_generation).await {
+        Ok(PostConnectOutcome::Ready) => {}
+        Ok(PostConnectOutcome::Stale) => {
+            return Err("huddle join was superseded".to_owned());
+        }
+        Err(e) => {
+            // Reset only the huddle lifetime that failed.
+            let mut did_reset = false;
+            if let Ok(mut hs) = state.huddle_state.lock() {
+                if hs.is_current_huddle(&ephemeral_channel_id, huddle_generation) {
+                    hs.reset_preserving_generation();
+                    did_reset = true;
+                }
+            }
+            if did_reset {
+                state.emit_huddle_state_changed();
+            }
+            return Err(e);
         }
-        state.emit_huddle_state_changed();
-        return Err(e);
     }
 
     Ok(HuddleJoinInfo {
@@ -675,123 +730,6 @@ pub fn push_audio_pcm(
     }
 }
 
-/// Hot-start: check if voice models just finished downloading during an active
-/// huddle and start the corresponding pipelines.
-///
-/// Called by the frontend on a timer or after model status changes. No-op if
-/// the huddle is not active or pipelines are already running.
-#[tauri::command]
-pub async fn check_pipeline_hotstart(state: State<'_, AppState>) -> Result<(), String> {
-    let (is_active, ephemeral_channel_id) = {
-        let hs = state.huddle()?;
-        (
-            matches!(hs.phase, HuddlePhase::Connected | HuddlePhase::Active),
-            hs.ephemeral_channel_id.clone(),
-        )
-    };
-
-    if !is_active {
-        return Ok(());
-    }
-
-    // Detect dead pipelines: if the worker thread has exited (init failure or crash),
-    // clear the pipeline handle so hot-start can retry on the next cycle.
-    {
-        let mut hs = state.huddle()?;
-        if let Some(ref p) = hs.stt_pipeline {
-            if p.is_finished() {
-                hs.stt_pipeline = None;
-            }
-        }
-        if let Some(ref p) = hs.tts_pipeline {
-            if p.is_finished() {
-                hs.tts_pipeline = None;
-            }
-        }
-    }
-    // Re-read after potential cleanup.
-    let (has_stt, has_tts, transcription_enabled) = {
-        let hs = state.huddle()?;
-        (
-            hs.stt_pipeline.is_some(),
-            hs.tts_pipeline.is_some(),
-            hs.transcription_enabled,
-        )
-    };
-
-    // Check if models just became ready (one-shot flags).
-    let stt_ready = models::global_model_manager()
-        .map(|m| m.take_stt_ready())
-        .unwrap_or(false);
-    let tts_ready = models::global_model_manager()
-        .map(|m| m.take_tts_ready())
-        .unwrap_or(false);
-
-    // Start TTS first (so STT can capture tts_cancel).
-    if !has_tts && (tts_ready || models::is_tts_ready()) {
-        if let Err(e) = maybe_start_tts_pipeline(&state).await {
-            eprintln!("buzz-desktop: TTS hotstart failed: {e}");
-        }
-    }
-
-    if transcription_enabled && !has_stt && (stt_ready || models::is_stt_ready()) {
-        if let Some(eph_id) = &ephemeral_channel_id {
-            if let Err(e) = maybe_start_stt_pipeline(&state, eph_id).await {
-                eprintln!("buzz-desktop: STT hotstart failed: {e}");
-            }
-        }
-    }
-
-    // Periodically refresh agent_pubkeys from relay membership.
-    // This catches mid-huddle agent additions/removals by other participants,
-    // keeping STT p-tags authoritative throughout the session.
-    // Throttled to every 15 s (not on every 5 s hotstart poll).
-    //
-    // NOTE: The frontend ALSO polls agent membership independently (every 10 s
-    // via get_huddle_agent_pubkeys). This is intentional — the two polls have
-    // different failure semantics:
-    //   - Rust (here): preserves stale list on failure (STT p-tags should not
-    //     disappear on a transient network blip).
-    //   - React (HuddleContext.tsx): clears list on failure (TTS authorization
-    //     must fail-closed — never speak from a stale agent list).
-    //
-    // On Ok: always replace (even with empty — agents may have been removed).
-    // On Err: preserve the existing list (transient failure shouldn't zero it).
-    if let Some(eph_id) = &ephemeral_channel_id {
-        let should_refresh = {
-            let hs = state.huddle()?;
-            match hs.last_agent_refresh {
-                None => true,
-                Some(t) => t.elapsed() >= std::time::Duration::from_secs(15),
-            }
-        };
-        if should_refresh {
-            // Fetch agents (for STT p-tags) and all members (for participant list).
-            // Sequential — tokio::join! requires the `macros` feature.
-            // Only update the throttle timestamp when at least one fetch succeeds,
-            // so transient failures retry immediately on the next poll cycle.
-            // Fetch both lists before acquiring the lock — no lock held across await.
-            let fresh_agents = fetch_channel_members(eph_id, Some("bot"), &state)
-                .await
-                .ok();
-            let fresh_members = fetch_channel_members(eph_id, None, &state).await.ok();
-
-            if fresh_agents.is_some() || fresh_members.is_some() {
-                let mut hs = state.huddle()?;
-                if let Some(agents) = fresh_agents {
-                    *hs.agent_pubkeys.lock().unwrap_or_else(|e| e.into_inner()) = agents;
-                }
-                if let Some(members) = fresh_members {
-                    hs.participants = members;
-                }
-                hs.last_agent_refresh = Some(std::time::Instant::now());
-            }
-        }
-    }
-
-    Ok(())
-}
-
 /// Trigger a background download of voice models (Parakeet STT + Pocket TTS).
 ///
 /// Returns immediately — downloads run in tokio background tasks.
@@ -817,91 +755,90 @@ pub fn get_model_status(_state: State<'_, AppState>) -> Result<models::VoiceMode
     })
 }
 
-/// Enable or disable TTS output.
-///
-/// When disabled, the TTS pipeline is shut down and audio output stops.
-/// When re-enabled, the pipeline is restarted if TTS models are available.
-///
-/// Takes the pipeline handle out of the lock before calling shutdown() — the
-/// thread join in Drop can block for ~200 ms (ONNX inference) and we don't
-/// want to hold the HuddleState mutex during that time.
-#[tauri::command]
-pub async fn set_tts_enabled(enabled: bool, state: State<'_, AppState>) -> Result<(), String> {
-    let old_pipeline = {
-        let mut hs = state.huddle()?;
-        hs.tts_enabled = enabled;
-        if !enabled {
-            hs.tts_pipeline.take() // Take out of lock.
-        } else {
-            None
-        }
-    };
-    // Shut down outside the lock — thread join happens here.
-    if let Some(ref pipeline) = old_pipeline {
-        pipeline.shutdown();
-    }
-    drop(old_pipeline);
-
-    if enabled {
-        // Re-start TTS pipeline if models are available and huddle is active.
-        let phase = {
-            let hs = state.huddle()?;
-            hs.phase.clone()
-        };
-        if matches!(phase, HuddlePhase::Connected | HuddlePhase::Active) {
-            if let Err(e) = maybe_start_tts_pipeline(&state).await {
-                eprintln!("buzz-desktop: TTS pipeline restart failed: {e}");
-            }
-        }
-    }
-
-    Ok(())
-}
-
 /// Speak an agent message via TTS.
 ///
-/// Maximum text length accepted for TTS synthesis.
-/// ~2000 chars ≈ 1–2 minutes of speech. Longer messages are truncated.
-const MAX_TTS_TEXT_LEN: usize = 2000;
-
-/// Called by the WebView when it receives an incoming agent kind:9 message.
+/// Called by the WebView when it receives an eligible live agent message.
 /// Lazily starts the TTS pipeline if models are ready but the pipeline hasn't
 /// been created yet (e.g. models finished downloading after huddle started).
 ///
-/// No-op if TTS is disabled or models aren't ready.
+/// Disabled is the only intentional no-op. Enabled-but-unavailable speech
+/// returns an error so the caller cannot mistake a dropped message for success.
 #[tauri::command]
-pub async fn speak_agent_message(text: String, state: State<'_, AppState>) -> Result<(), String> {
+pub async fn speak_agent_message(
+    text: String,
+    route_id: u64,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    eprintln!("buzz-desktop: tts stage=invoke status=started route_id={route_id}");
     // Truncate oversized messages — agents shouldn't monologue in a voice huddle.
     // Use char count (not byte length) to avoid panicking on multi-byte UTF-8.
-    let text = if text.chars().count() > MAX_TTS_TEXT_LEN {
-        let mut truncated: String = text.chars().take(MAX_TTS_TEXT_LEN).collect();
-        truncated.push_str("... message truncated.");
-        truncated
-    } else {
-        text
-    };
+    let text = normalize_agent_tts_text(text);
 
     let needs_pipeline = {
-        let hs = state.huddle()?;
-        hs.tts_enabled
-            && hs.tts_pipeline.is_none()
-            && matches!(hs.phase, HuddlePhase::Connected | HuddlePhase::Active)
+        let mut hs = state.huddle()?;
+        if hs
+            .tts_pipeline
+            .as_ref()
+            .is_some_and(|pipeline| pipeline.is_finished())
+        {
+            hs.tts_pipeline = None;
+        }
+        match classify_agent_tts_runtime(hs.tts_enabled, &hs.phase, hs.tts_pipeline.is_some()) {
+            AgentTtsRuntimeGate::Disabled => {
+                eprintln!(
+                    "buzz-desktop: tts stage=invoke status=no_op reason=disabled route_id={route_id}"
+                );
+                return Ok(());
+            }
+            AgentTtsRuntimeGate::Inactive => {
+                eprintln!(
+                    "buzz-desktop: tts stage=invoke status=failed reason=inactive_huddle route_id={route_id}"
+                );
+                return Err(
+                    "Agent text to speech is unavailable outside an active huddle".to_string(),
+                );
+            }
+            AgentTtsRuntimeGate::NeedsPipeline => true,
+            AgentTtsRuntimeGate::Ready => false,
+        }
     };
 
     // Lazy-start: models may have finished downloading after the huddle began.
     if needs_pipeline {
-        if let Err(e) = maybe_start_tts_pipeline(&state).await {
-            eprintln!("buzz-desktop: TTS lazy-start failed: {e}");
-        }
+        maybe_start_tts_pipeline(&state).await.inspect_err(|_| {
+            eprintln!(
+                "buzz-desktop: tts stage=invoke status=failed reason=startup_failed route_id={route_id}"
+            );
+        })?;
+        await_inflight_tts_start(&state).await.inspect_err(|_| {
+            eprintln!(
+                "buzz-desktop: tts stage=invoke status=failed reason=startup_timeout route_id={route_id}"
+            );
+        })?;
     }
 
-    let hs = state.huddle()?;
-    if hs.tts_enabled {
-        if let Some(ref pipeline) = hs.tts_pipeline {
-            pipeline.speak(text)?;
-        }
-    }
-    Ok(())
+    let sender = {
+        let hs = state.huddle()?;
+        hs.tts_pipeline
+            .as_ref()
+            .map(|pipeline| pipeline.text_sender())
+    };
+    let Some(sender) = sender else {
+        eprintln!(
+            "buzz-desktop: tts stage=invoke status=failed reason=unavailable route_id={route_id}"
+        );
+        return Err("Agent text to speech is enabled but its audio pipeline is unavailable".into());
+    };
+    enqueue_agent_tts_text(route_id, text, move |route_id, text| {
+        sender
+            .send(route_id, text)
+            .map_err(|error| format!("TTS queue closed while waiting to enqueue: {error}"))
+    })
+    .await
+    .inspect(|_| eprintln!("buzz-desktop: tts stage=queue status=accepted route_id={route_id}"))
+    .inspect_err(|_| {
+        eprintln!("buzz-desktop: tts stage=queue status=failed reason=closed route_id={route_id}")
+    })
 }
 
 /// Add an agent to the active huddle.
@@ -924,7 +861,7 @@ pub async fn add_agent_to_huddle(
 ) -> Result<agents::AgentAddResult, String> {
     validate_pubkey_hex(&agent_pubkey)?;
 
-    let (eph_id, parent_id) = {
+    let (eph_id, parent_id, huddle_generation) = {
         let hs = state.huddle()?;
         if !matches!(hs.phase, HuddlePhase::Connected | HuddlePhase::Active) {
             return Err("no active huddle".to_string());
@@ -948,7 +885,7 @@ pub async fn add_agent_to_huddle(
             .clone()
             .ok_or("no ephemeral channel")?;
         let parent = hs.parent_channel_id.clone().ok_or("no parent channel")?;
-        (eph, parent)
+        (eph, parent, hs.huddle_generation)
     };
 
     let eph_uuid = Uuid::parse_str(&eph_id).map_err(|e| e.to_string())?;
@@ -957,29 +894,30 @@ pub async fn add_agent_to_huddle(
     // Returns Err only if the ephemeral add fails — parent failure is in the result.
     let result = agents::add_agent_to_huddle(eph_uuid, parent_uuid, &agent_pubkey, &state).await?;
 
-    // Ephemeral add succeeded — safe to register for p-tagging.
-    // Clone the Arc first so we can drop the outer HuddleState lock before
-    // acquiring the inner pubkeys lock (avoids the E0597 borrow-checker error).
-    {
-        let agent_pubkeys_arc = {
-            let hs = state.huddle()?;
-            Arc::clone(&hs.agent_pubkeys)
-        };
-        let mut pubkeys = agent_pubkeys_arc.lock().unwrap_or_else(|e| e.into_inner());
+    // Ephemeral add succeeded — register it only if this is still the huddle
+    // that initiated the relay operation.
+    let transcription_auto_enabled = {
+        let mut hs = state.huddle()?;
+        if !hs.is_current_huddle(&eph_id, huddle_generation) {
+            return Ok(result);
+        }
+        let mut pubkeys = hs.agent_pubkeys.lock().unwrap_or_else(|e| e.into_inner());
         if !pubkeys.contains(&agent_pubkey) {
             pubkeys.push(agent_pubkey.clone());
         }
-    }
+        drop(pubkeys);
+        if !hs.participants.contains(&agent_pubkey) {
+            hs.participants.push(agent_pubkey.clone());
+        }
+        hs.maybe_auto_enable_transcription_for_agents()
+    };
 
     // No guidelines re-post needed — the agent sees the original kind:48106
     // guidelines via EOSE replay when it subscribes to the ephemeral channel.
-
-    // Also add the agent to the visible participants list.
-    {
-        let mut hs = state.huddle()?;
-        if !hs.participants.contains(&agent_pubkey) {
-            hs.participants.push(agent_pubkey);
-        }
+    if transcription_auto_enabled {
+        start_auto_enabled_transcription(&state, &eph_id).await;
+    } else {
+        state.emit_huddle_state_changed();
     }
 
     Ok(result)
diff --git a/desktop/src-tauri/src/huddle/models.rs b/desktop/src-tauri/src/huddle/models.rs
index 169ddf66c0..f9f7065769 100644
--- a/desktop/src-tauri/src/huddle/models.rs
+++ b/desktop/src-tauri/src/huddle/models.rs
@@ -24,6 +24,14 @@ use std::sync::{Arc, Mutex, OnceLock};
 use serde::{Deserialize, Serialize};
 use sha2::{Digest, Sha256};
 
+use super::pocket::{
+    april_model_info, PocketModelArtifact, APRIL_BUNDLE_ID, APRIL_MODEL_ID, APRIL_MODEL_REVISION,
+};
+use super::tts_voice_registry::POCKET_VOICES;
+
+#[path = "models_voice_upgrade.rs"]
+mod voice_upgrade;
+
 // ── Integrity verification ────────────────────────────────────────────────────
 //
 // All model artifacts are verified against pinned SHA-256 hashes before
@@ -38,19 +46,15 @@ use sha2::{Digest, Sha256};
 /// Computed from a known-good download. Update when upgrading model versions.
 const STT_ARCHIVE_SHA256: &str = "17f945007b52ccd8b7200ffc7c5652e9e8e961dfdf479cefcabd06cf5703630b";
 
-/// HuggingFace base URL for the sherpa-onnx Pocket TTS fp32 repackage.
-///
-/// Pinned to commit 96d1e53ce3311ca6c2c6a35e2062d36b4cec6fa3
-/// (2026-02-10) for reproducible downloads.
-///
-/// fp32 (not int8): a direct same-runtime A/B (k2-fsa/sherpa-onnx#3172)
-/// found the ONNX int8 quantization audibly degraded Pocket TTS output and
-/// that fp32 "significantly improved quality even at 1 step". The runtime
-/// bundle grows from ~189 MB to ~473 MB; encoder, text conditioner, both
-/// JSON tables, and LICENSE are byte-identical between the two repos — only
-/// the three quantized sessions (lm_main, lm_flow, decoder) change.
-const POCKET_HF_BASE: &str =
-    "https://huggingface.co/csukuangfj2/sherpa-onnx-pocket-tts-2026-01-26/resolve/96d1e53ce3311ca6c2c6a35e2062d36b4cec6fa3";
+fn pocket_artifact_url(filename: &str) -> String {
+    format!(
+        "https://huggingface.co/{APRIL_MODEL_ID}/resolve/{APRIL_MODEL_REVISION}/onnx/{APRIL_BUNDLE_ID}/{filename}"
+    )
+}
+
+fn pocket_license_url() -> String {
+    format!("https://huggingface.co/{APRIL_MODEL_ID}/resolve/{APRIL_MODEL_REVISION}/onnx/LICENSE")
+}
 
 /// Reference voice WAV: "Mary (f, conversation)" from the Kyutai TTS demo
 /// voice set — VCTK speaker p333, ai-coustics-enhanced. Pinned to
@@ -64,20 +68,19 @@ const POCKET_HF_BASE: &str =
 const POCKET_REFERENCE_WAV_URL: &str =
     "https://huggingface.co/kyutai/tts-voices/resolve/323332d33f997de8394f24a193e1a76df720e01a/vctk/p333_023_enhanced.wav";
 
-/// SHA-256 hashes for individual Pocket TTS model files.
-/// Computed from known-good pinned downloads. Update when upgrading model versions.
-#[rustfmt::skip]
-const TTS_FILE_HASHES: &[(&str, &str)] = &[
-    ("decoder.onnx",          "f267880fde6c58b17b0a8f3647eaf8dcfad321f833f32d583ebc2fb2d1a15f10"),
-    ("encoder.onnx",          "e8f2f6d301ffb96e398b138a7dc6d3038622d236044636b73d920bab85890260"),
-    ("lm_flow.onnx",          "79c013a554a54e63319c33c0cc8830cbbedc9b7e448ae7e26f7923ae11f9873e"),
-    ("lm_main.onnx",          "255d1a9263c5abdf36034abfc19c11d21cc5f40f0f87d8361288e972cbd5c578"),
-    ("text_conditioner.onnx", "0b84e837d7bfaf2c896627b03e3f080320309f37f4fc7df7698c644f7ba5e6b1"),
-    ("vocab.json",            "6fb646346cf931016f70c4921aab0900ce7a304b893cb02135c74e294abfea01"),
-    ("token_scores.json",     "5be2f278caf9b9800741f0fd82bff677f4943ec764c356f907213434b622d958"),
-    ("LICENSE",               "fe7b4ce83b8381cc5b216bbb4af73c570688d1b819c73bbaed8ca401f4677cd6"),
-    ("reference_sample.wav",  "a35b0468382218e9f37a9a7494d1e4b74deaf18d7ced22265b4e325bb55c183f"),
-];
+const TTS_LICENSE_ARTIFACT: PocketModelArtifact = PocketModelArtifact {
+    filename: "LICENSE",
+    sha256: "fe7b4ce83b8381cc5b216bbb4af73c570688d1b819c73bbaed8ca401f4677cd6",
+    size_bytes: 18_655,
+    quantized: false,
+};
+
+const TTS_REFERENCE_ARTIFACT: PocketModelArtifact = PocketModelArtifact {
+    filename: "reference_sample.wav",
+    sha256: "a35b0468382218e9f37a9a7494d1e4b74deaf18d7ced22265b4e325bb55c183f",
+    size_bytes: 639_084,
+    quantized: false,
+};
 
 // ── Model versioning ──────────────────────────────────────────────────────────
 //
@@ -92,15 +95,8 @@ const TTS_FILE_HASHES: &[(&str, &str)] = &[
 /// honest (each version tag identifies one specific set of model bytes).
 const STT_MODEL_VERSION: &str = "2";
 
-/// Model manifest version for Pocket TTS. Increment when upgrading model files.
-/// Bumped "1" → "2" when the bundled reference voice changed from KevinAHM's
-/// anonymous 16 kHz sample to Mary (VCTK p333, 32 kHz, ai-coustics-enhanced)
-/// from kyutai/tts-voices. The hash mismatch on `reference_sample.wav` would
-/// fail readiness on its own, but the manifest bump makes the re-download
-/// reason explicit and skips the failing-then-re-fetching transient state.
-/// Bumped "2" → "3" for the int8 → fp32 model swap (see `POCKET_HF_BASE`):
-/// existing int8 installs must re-download the suffixless fp32 sessions.
-const TTS_MODEL_VERSION: &str = "3";
+/// Identifies the April INT8 asset set plus the official VCTK presets.
+const TTS_MODEL_VERSION: &str = "5";
 
 /// Filename for the version manifest written alongside model files.
 const MANIFEST_FILENAME: &str = ".buzz-model-manifest";
@@ -110,9 +106,9 @@ const MANIFEST_FILENAME: &str = ".buzz-model-manifest";
 /// Maximum expected STT archive size (200 MB — actual is ~100 MB).
 const MAX_STT_DOWNLOAD_BYTES: u64 = 200 * 1024 * 1024;
 
-/// Maximum expected Pocket TTS file size (400 MB per file — largest is
-/// `lm_main.onnx` at ~303 MB fp32).
-const MAX_TTS_FILE_BYTES: u64 = 400 * 1024 * 1024;
+/// Maximum expected Pocket TTS file size. The largest pinned INT8 artifact is
+/// `flow_lm_main_int8.onnx` at 76,341,079 bytes.
+const MAX_TTS_FILE_BYTES: u64 = 100 * 1024 * 1024;
 
 /// NVIDIA Parakeet TDT-CTC 110M (English, int8) — packaged for sherpa-onnx by
 /// k2-fsa. Single ONNX file (CTC head) + tokens.txt. Avg WER ~7.5% across
@@ -168,50 +164,29 @@ const TTS_MODEL_DIR_NAME: &str = "pocket-tts";
 /// Attribution sidecar written next to the Pocket TTS model files.
 const TTS_LICENSE_FILE_NAME: &str = "MODEL_LICENSE.txt";
 
-/// CC-BY-4.0 §3(a)(1) attribution block for Pocket TTS, its ONNX packaging,
-/// and the bundled reference voice WAV.
-const TTS_LICENSE_TEXT: &str = "\
-Pocket TTS
-© Kyutai.
-
-Licensed under the Creative Commons Attribution 4.0 International License
-(CC-BY-4.0). License text: https://creativecommons.org/licenses/by/4.0/
-
-Original model by Kyutai: https://huggingface.co/kyutai/pocket-tts
-Paper: Charles, Roebel, et al., Pocket TTS (arXiv:2509.06926).
-Mimi neural codec by Kyutai is bundled as part of the model.
-
-ONNX export by KevinAHM: https://huggingface.co/KevinAHM/pocket-tts-onnx
-Sherpa-onnx repackage by csukuangfj / k2-fsa:
-https://huggingface.co/csukuangfj2/sherpa-onnx-pocket-tts-2026-01-26
-
-Bundled reference voice (reference_sample.wav):
-\"Mary (f, conversation)\" preset from the Kyutai TTS demo voice catalogue
-(https://kyutai.org/tts), distributed via
-https://huggingface.co/kyutai/tts-voices as `vctk/p333_023_enhanced.wav`.
-Original recording from the Voice Cloning Toolkit (VCTK) corpus, speaker p333:
-https://datashare.ed.ac.uk/handle/10283/3443 (CC-BY-4.0).
-Recording enhancement (denoise/dereverb) by ai-coustics:
-https://ai-coustics.com/
-
-Buzz ships all ONNX/model artifacts and the reference voice WAV unmodified,
-renamed only by placement in the local model directory.
-
-Provided \"AS IS\", without warranty of any kind, express or implied. See the
-license text for full warranty disclaimer.
-";
-
 /// All files that must be present for Pocket TTS to be considered ready.
 const TTS_EXPECTED_FILES: &[&str] = &[
-    "decoder.onnx",
-    "encoder.onnx",
-    "lm_flow.onnx",
-    "lm_main.onnx",
+    "bundle.json",
+    "bos_before_voice.npy",
+    "flow_lm_main_int8.onnx",
+    "flow_lm_flow_int8.onnx",
+    "mimi_decoder_int8.onnx",
+    "mimi_encoder.onnx",
     "text_conditioner.onnx",
-    "vocab.json",
-    "token_scores.json",
+    "tokenizer.model",
     "LICENSE",
     "reference_sample.wav",
+    "anna.wav",
+    "vera.wav",
+    "fantine.wav",
+    "charles.wav",
+    "paul.wav",
+    "eponine.wav",
+    "azelma.wav",
+    "george.wav",
+    "jane.wav",
+    "michael.wav",
+    "eve.wav",
     TTS_LICENSE_FILE_NAME,
 ];
 
@@ -404,6 +379,7 @@ struct ModelSlot {
     dir_name: &'static str,                  // subdir under ~/.buzz/models/
     expected_files: &'static [&'static str], // files required for "ready"
     version: &'static str,                   // manifest version; increment to force re-download
+    expected_size: fn(&str) -> Option<u64>,
     status: Arc<Mutex<ModelStatus>>,
     just_ready: Arc<AtomicBool>, // fires once when download completes
 }
@@ -418,11 +394,17 @@ impl ModelSlot {
             dir_name,
             expected_files,
             version,
+            expected_size: |_| None,
             status: Arc::new(Mutex::new(ModelStatus::NotDownloaded)),
             just_ready: Arc::new(AtomicBool::new(false)),
         }
     }
 
+    fn with_expected_sizes(mut self, expected_size: fn(&str) -> Option<u64>) -> Self {
+        self.expected_size = expected_size;
+        self
+    }
+
     fn model_dir(&self, models_dir: &Path) -> PathBuf {
         models_dir.join(self.dir_name)
     }
@@ -432,7 +414,17 @@ impl ModelSlot {
         std::fs::read_to_string(dir.join(MANIFEST_FILENAME))
             .map(|v| v.trim() == self.version)
             .unwrap_or(false)
-            && self.expected_files.iter().all(|f| dir.join(f).is_file())
+            && self.expected_files.iter().all(|filename| {
+                let path = dir.join(filename);
+                path.is_file()
+                    && (self.expected_size)(filename)
+                        .map(|expected| {
+                            path.metadata()
+                                .map(|metadata| metadata.len() == expected)
+                                .unwrap_or(false)
+                        })
+                        .unwrap_or(true)
+            })
     }
 
     fn dir_if_ready(&self, models_dir: &Path) -> Option<PathBuf> {
@@ -453,6 +445,39 @@ impl ModelSlot {
         self.just_ready.swap(false, Ordering::AcqRel)
     }
 
+    /// Recover or clean up the backup left by an interrupted atomic install.
+    fn recover_interrupted_install(&self, models_dir: &Path) {
+        let final_dir = self.model_dir(models_dir);
+        let backup_dir = final_dir.with_extension("old");
+        if !backup_dir.exists() {
+            return;
+        }
+        if self.is_ready(models_dir) {
+            if let Err(error) = std::fs::remove_dir_all(&backup_dir) {
+                eprintln!(
+                    "buzz-desktop: could not remove stale {} backup: {error}",
+                    self.dir_name
+                );
+            }
+            return;
+        }
+        if final_dir.exists() {
+            if let Err(error) = std::fs::remove_dir_all(&final_dir) {
+                eprintln!(
+                    "buzz-desktop: could not remove incomplete {} install: {error}",
+                    self.dir_name
+                );
+                return;
+            }
+        }
+        if let Err(error) = std::fs::rename(&backup_dir, &final_dir) {
+            eprintln!(
+                "buzz-desktop: could not restore interrupted {} install: {error}",
+                self.dir_name
+            );
+        }
+    }
+
     /// Spawn a background download task if not already ready or downloading.
     fn start_download<F, Fut>(
         &self,
@@ -511,6 +536,9 @@ impl ModelSlot {
             ));
         }
 
+        std::fs::write(source_dir.join(MANIFEST_FILENAME), self.version)
+            .map_err(|e| format!("write model manifest: {e}"))?;
+
         let final_dir = self.model_dir(models_dir);
         let backup_dir = final_dir.with_extension("old");
 
@@ -529,8 +557,6 @@ impl ModelSlot {
             return Err(format!("install new model: {e}"));
         }
 
-        std::fs::write(final_dir.join(MANIFEST_FILENAME), self.version)
-            .map_err(|e| format!("write model manifest: {e}"))?;
         let _ = tokio::fs::remove_dir_all(&backup_dir).await;
         if let Some(extra) = temp_cleanup {
             let _ = tokio::fs::remove_dir_all(extra).await;
@@ -542,6 +568,25 @@ impl ModelSlot {
     }
 }
 
+fn tts_expected_size(filename: &str) -> Option<u64> {
+    april_model_info()
+        .artifacts
+        .iter()
+        .find(|artifact| artifact.filename == filename)
+        .map(|artifact| artifact.size_bytes)
+        .or_else(|| {
+            [TTS_LICENSE_ARTIFACT, TTS_REFERENCE_ARTIFACT]
+                .iter()
+                .find(|artifact| artifact.filename == filename)
+                .map(|artifact| artifact.size_bytes)
+        })
+}
+
+fn tts_model_slot() -> ModelSlot {
+    ModelSlot::new(TTS_MODEL_DIR_NAME, TTS_EXPECTED_FILES, TTS_MODEL_VERSION)
+        .with_expected_sizes(tts_expected_size)
+}
+
 // ── ModelManager ──────────────────────────────────────────────────────────────
 
 /// Manages download and location of STT/TTS model files.
@@ -561,11 +606,13 @@ impl ModelManager {
     /// Returns `None` if the home directory cannot be resolved.
     pub fn new() -> Option<Self> {
         let models_dir = dirs::home_dir()?.join(".buzz").join("models");
-        Some(Self {
+        let manager = Self {
             models_dir,
             stt: ModelSlot::new(STT_MODEL_DIR_NAME, STT_EXPECTED_FILES, STT_MODEL_VERSION),
-            tts: ModelSlot::new(TTS_MODEL_DIR_NAME, TTS_EXPECTED_FILES, TTS_MODEL_VERSION),
-        })
+            tts: tts_model_slot(),
+        };
+        manager.tts.recover_interrupted_install(&manager.models_dir);
+        Some(manager)
     }
 
     // ── STT accessors ────────────────────────────────────────────────────────
@@ -638,8 +685,11 @@ impl ModelManager {
         }
     }
 
-    /// Start a background Pocket TTS download (~189 MB). No-op if already ready or downloading.
+    /// Start a background Pocket TTS download. No-op if already ready or downloading.
     pub fn start_tts_download(&self, http_client: reqwest::Client) {
+        if let Err(error) = voice_upgrade::install_vctk_presets_into_v4_model(&self.models_dir) {
+            eprintln!("buzz-desktop: could not upgrade existing Pocket voices in place: {error}");
+        }
         let manager = self.clone();
         self.tts.start_download(
             &self.models_dir,
@@ -754,10 +804,10 @@ impl ModelManager {
     /// Download and verify the Pocket TTS model files from HuggingFace.
     ///
     /// Downloads files into `~/.buzz/models/pocket-tts/`:
-    ///   - five ONNX sessions (Pocket TTS + Mimi codec)
-    ///   - `vocab.json` / `token_scores.json` for sherpa-onnx text conditioning
+    ///   - five ONNX sessions selected by the April INT8 bundle
+    ///   - bundle metadata, SentencePiece tokenizer, and learned voice BOS
     ///   - upstream `LICENSE` plus Buzz's `MODEL_LICENSE.txt` attribution sidecar
-    ///   - `reference_sample.wav` as the bundled default voice
+    ///   - `reference_sample.wav` plus the embedded official VCTK presets
     ///
     /// Files are written to a temp directory first, then moved atomically.
     async fn download_tts_model(&self, http_client: reqwest::Client) -> Result<(), String> {
@@ -768,24 +818,18 @@ impl ModelManager {
         let temp_dir = self.models_dir.join("pocket-tts.tmp");
         fresh_temp_dir(&temp_dir).await?;
 
-        let model_files = [
-            "decoder.onnx",
-            "encoder.onnx",
-            "lm_flow.onnx",
-            "lm_main.onnx",
-            "text_conditioner.onnx",
-            "vocab.json",
-            "token_scores.json",
-            "LICENSE",
-        ];
-        let mut downloads: Vec<(String, &'static str)> = model_files
+        let mut downloads: Vec<(String, PocketModelArtifact)> = april_model_info()
+            .artifacts
             .iter()
-            .map(|filename| (format!("{POCKET_HF_BASE}/{filename}"), *filename))
+            .copied()
+            .map(|artifact| (pocket_artifact_url(artifact.filename), artifact))
             .collect();
-        downloads.push((POCKET_REFERENCE_WAV_URL.to_string(), "reference_sample.wav"));
+        downloads.push((pocket_license_url(), TTS_LICENSE_ARTIFACT));
+        downloads.push((POCKET_REFERENCE_WAV_URL.to_string(), TTS_REFERENCE_ARTIFACT));
         let total_files = downloads.len() as u32;
 
-        for (i, (url, filename)) in downloads.iter().enumerate() {
+        for (i, (url, artifact)) in downloads.iter().enumerate() {
+            let filename = artifact.filename;
             eprintln!("buzz-desktop: downloading Pocket TTS {filename} from {url}");
 
             let response = fetch_url(&http_client, url, filename)
@@ -822,16 +866,19 @@ impl ModelManager {
             })?;
             eprintln!("buzz-desktop: downloaded {bytes} bytes ({filename}), wrote to disk");
 
-            let expected = TTS_FILE_HASHES
-                .iter()
-                .find(|(n, _)| *n == *filename)
-                .map(|(_, hash)| *hash)
-                .ok_or_else(|| format!("missing expected hash for Pocket TTS file: {filename}"))?;
+            if bytes != artifact.size_bytes {
+                let _ = tokio::fs::remove_dir_all(&temp_dir).await;
+                return Err(format!(
+                    "Pocket TTS {filename} size check failed: expected {} bytes, got {bytes}",
+                    artifact.size_bytes
+                ));
+            }
             let actual = sha256_file(&dest).await?;
-            if actual != expected {
+            if actual != artifact.sha256 {
                 let _ = tokio::fs::remove_dir_all(&temp_dir).await;
                 return Err(format!(
-                    "Pocket TTS {filename} integrity check failed: expected {expected}, got {actual}"
+                    "Pocket TTS {filename} integrity check failed: expected {}, got {actual}",
+                    artifact.sha256
                 ));
             }
 
@@ -842,9 +889,20 @@ impl ModelManager {
             });
         }
 
-        tokio::fs::write(temp_dir.join(TTS_LICENSE_FILE_NAME), TTS_LICENSE_TEXT)
-            .await
-            .map_err(|e| format!("write TTS model license sidecar: {e}"))?;
+        tokio::fs::write(
+            temp_dir.join(TTS_LICENSE_FILE_NAME),
+            voice_upgrade::TTS_LICENSE_TEXT,
+        )
+        .await
+        .map_err(|e| format!("write TTS model license sidecar: {e}"))?;
+        for voice in POCKET_VOICES {
+            let Some(bytes) = voice.bytes else {
+                continue;
+            };
+            tokio::fs::write(temp_dir.join(voice.reference_file), bytes)
+                .await
+                .map_err(|e| format!("install bundled {} voice: {e}", voice.display_name))?;
+        }
 
         self.tts.set_status(ModelStatus::Downloading {
             progress_percent: 90,
@@ -931,24 +989,5 @@ pub fn is_tts_ready() -> bool {
 }
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn tts_readiness_requires_license_sidecar() {
-        let temp = tempfile::tempdir().expect("tempdir");
-        let slot = ModelSlot::new(TTS_MODEL_DIR_NAME, TTS_EXPECTED_FILES, TTS_MODEL_VERSION);
-        let model_dir = temp.path().join(TTS_MODEL_DIR_NAME);
-        std::fs::create_dir_all(&model_dir).expect("create model dir");
-
-        for file in TTS_EXPECTED_FILES {
-            std::fs::write(model_dir.join(file), b"test").expect("write expected file");
-        }
-        std::fs::write(model_dir.join(MANIFEST_FILENAME), TTS_MODEL_VERSION).expect("manifest");
-
-        assert!(slot.is_ready(temp.path()));
-
-        std::fs::remove_file(model_dir.join(TTS_LICENSE_FILE_NAME)).expect("remove sidecar");
-        assert!(!slot.is_ready(temp.path()));
-    }
-}
+#[path = "models_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/huddle/models_tests.rs b/desktop/src-tauri/src/huddle/models_tests.rs
new file mode 100644
index 0000000000..699ffbe459
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/models_tests.rs
@@ -0,0 +1,146 @@
+use super::*;
+
+fn create_ready_model_dir(root: &Path) -> PathBuf {
+    let model_dir = root.join(TTS_MODEL_DIR_NAME);
+    std::fs::create_dir_all(&model_dir).expect("create model dir");
+    for file in TTS_EXPECTED_FILES {
+        let path = model_dir.join(file);
+        let handle = std::fs::File::create(path).expect("create expected file");
+        if let Some(size) = tts_expected_size(file) {
+            handle.set_len(size).expect("size expected file");
+        } else {
+            std::fs::write(model_dir.join(file), b"test").expect("write expected file");
+        }
+    }
+    std::fs::write(model_dir.join(MANIFEST_FILENAME), TTS_MODEL_VERSION).expect("manifest");
+    model_dir
+}
+
+#[test]
+fn expected_files_match_april_int8_metadata() {
+    let mut expected = april_model_info()
+        .artifacts
+        .iter()
+        .map(|artifact| artifact.filename)
+        .chain([TTS_LICENSE_ARTIFACT.filename, TTS_LICENSE_FILE_NAME])
+        .chain(POCKET_VOICES.iter().map(|voice| voice.reference_file))
+        .collect::<Vec<_>>();
+    expected.sort_unstable();
+    let mut actual = TTS_EXPECTED_FILES.to_vec();
+    actual.sort_unstable();
+
+    assert_eq!(actual, expected);
+    assert!(!actual.contains(&"flow_lm_main.onnx"));
+    assert!(!actual.contains(&"flow_lm_flow.onnx"));
+    assert!(!actual.contains(&"mimi_decoder.onnx"));
+    assert!(!actual.contains(&"marius.wav"));
+}
+
+#[test]
+fn tts_readiness_requires_license_sidecar() {
+    let temp = tempfile::tempdir().expect("tempdir");
+    let slot = tts_model_slot();
+    let model_dir = create_ready_model_dir(temp.path());
+
+    assert!(slot.is_ready(temp.path()));
+
+    std::fs::remove_file(model_dir.join(TTS_LICENSE_FILE_NAME)).expect("remove sidecar");
+    assert!(!slot.is_ready(temp.path()));
+}
+
+#[test]
+fn tts_readiness_rejects_truncated_pinned_artifact() {
+    let temp = tempfile::tempdir().expect("tempdir");
+    let slot = tts_model_slot();
+    let model_dir = create_ready_model_dir(temp.path());
+    let artifact = april_model_info().artifacts[0];
+
+    std::fs::OpenOptions::new()
+        .write(true)
+        .open(model_dir.join(artifact.filename))
+        .expect("open artifact")
+        .set_len(artifact.size_bytes - 1)
+        .expect("truncate artifact");
+
+    assert!(!slot.is_ready(temp.path()));
+}
+
+#[test]
+fn january_cache_is_not_ready_for_april_int8() {
+    let temp = tempfile::tempdir().expect("tempdir");
+    let slot = tts_model_slot();
+    let model_dir = temp.path().join(TTS_MODEL_DIR_NAME);
+    std::fs::create_dir_all(&model_dir).expect("create model dir");
+    for file in [
+        "decoder.onnx",
+        "encoder.onnx",
+        "lm_flow.onnx",
+        "lm_main.onnx",
+        "text_conditioner.onnx",
+        "vocab.json",
+        "token_scores.json",
+        "LICENSE",
+        "reference_sample.wav",
+        TTS_LICENSE_FILE_NAME,
+    ] {
+        std::fs::write(model_dir.join(file), b"january").expect("write January file");
+    }
+    std::fs::write(model_dir.join(MANIFEST_FILENAME), "3").expect("manifest");
+
+    assert!(!slot.is_ready(temp.path()));
+}
+
+#[test]
+fn interrupted_install_restores_backup_when_destination_is_missing() {
+    let temp = tempfile::tempdir().expect("tempdir");
+    let slot = tts_model_slot();
+    let backup_dir = temp.path().join("pocket-tts.old");
+    std::fs::create_dir_all(&backup_dir).expect("create backup");
+    std::fs::write(backup_dir.join("sentinel"), b"previous").expect("write sentinel");
+
+    slot.recover_interrupted_install(temp.path());
+
+    assert_eq!(
+        std::fs::read(temp.path().join(TTS_MODEL_DIR_NAME).join("sentinel"))
+            .expect("restored sentinel"),
+        b"previous"
+    );
+    assert!(!backup_dir.exists());
+}
+
+#[test]
+fn interrupted_install_replaces_incomplete_destination_with_backup() {
+    let temp = tempfile::tempdir().expect("tempdir");
+    let slot = tts_model_slot();
+    let model_dir = temp.path().join(TTS_MODEL_DIR_NAME);
+    let backup_dir = temp.path().join("pocket-tts.old");
+    std::fs::create_dir_all(&model_dir).expect("create incomplete destination");
+    std::fs::write(model_dir.join("incomplete"), b"april").expect("write incomplete file");
+    std::fs::create_dir_all(&backup_dir).expect("create backup");
+    std::fs::write(backup_dir.join("sentinel"), b"previous").expect("write sentinel");
+
+    slot.recover_interrupted_install(temp.path());
+
+    assert_eq!(
+        std::fs::read(model_dir.join("sentinel")).expect("restored sentinel"),
+        b"previous"
+    );
+    assert!(!model_dir.join("incomplete").exists());
+    assert!(!backup_dir.exists());
+}
+
+#[test]
+fn ready_destination_removes_stale_backup() {
+    let temp = tempfile::tempdir().expect("tempdir");
+    let slot = tts_model_slot();
+    let model_dir = create_ready_model_dir(temp.path());
+    let backup_dir = temp.path().join("pocket-tts.old");
+    std::fs::create_dir_all(&backup_dir).expect("create backup");
+    std::fs::write(backup_dir.join("sentinel"), b"previous").expect("write sentinel");
+
+    slot.recover_interrupted_install(temp.path());
+
+    assert!(slot.is_ready(temp.path()));
+    assert!(model_dir.exists());
+    assert!(!backup_dir.exists());
+}
diff --git a/desktop/src-tauri/src/huddle/models_voice_upgrade.rs b/desktop/src-tauri/src/huddle/models_voice_upgrade.rs
new file mode 100644
index 0000000000..5233e02615
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/models_voice_upgrade.rs
@@ -0,0 +1,128 @@
+use super::*;
+use crate::huddle::tts_voice_registry::POCKET_VOICES;
+
+const PRESET_VOICE_TTS_MODEL_VERSION: &str = "4";
+
+/// Attribution written beside every installed Pocket model and voice asset.
+pub(super) const TTS_LICENSE_TEXT: &str = "\
+Pocket TTS
+© Kyutai.
+
+Licensed under the Creative Commons Attribution 4.0 International License
+(CC-BY-4.0). License text: https://creativecommons.org/licenses/by/4.0/
+
+Original model by Kyutai: https://huggingface.co/kyutai/pocket-tts
+Paper: Charles, Roebel, et al., Pocket TTS (arXiv:2509.06926).
+Mimi neural codec by Kyutai is bundled as part of the model.
+
+April 2026 ONNX export by KevinAHM:
+https://huggingface.co/KevinAHM/pocket-tts-onnx
+Pinned revision: 58a6d00cf13d239b6748cb0769f35c580a8f606c
+
+Bundled English VCTK presets: Anna (p228), Vera (p229), Fantine (p244),
+Charles (p254), Paul (p259), Eponine (p262), Azelma (p303), George (p315),
+Mary (p333), Jane (p339), Michael (p360), and Eve (p361). These exact,
+ai-coustics-enhanced WAVs come from Kyutai's tts-voices repository at revision
+323332d33f997de8394f24a193e1a76df720e01a.
+Source: https://huggingface.co/kyutai/tts-voices/tree/323332d33f997de8394f24a193e1a76df720e01a/vctk
+Original recordings: Voice Cloning Toolkit (VCTK) corpus,
+https://datashare.ed.ac.uk/handle/10283/3443 (CC-BY-4.0).
+Enhancement (denoise/dereverb): ai-coustics, https://ai-coustics.com/
+
+Buzz ships the ONNX/model artifacts and voice WAVs unmodified, renamed only
+by placement in the local model directory.
+
+Provided \"AS IS\", without warranty of any kind, express or implied. See the
+license text for full warranty disclaimer.
+";
+
+fn is_embedded_voice_file(filename: &str) -> bool {
+    POCKET_VOICES
+        .iter()
+        .any(|voice| voice.bytes.is_some() && voice.reference_file == filename)
+}
+
+/// Add the official VCTK presets to an otherwise-ready v4 install.
+///
+/// Model artifacts and Mary already exist in v4. The manifest is written last,
+/// so interruption leaves v4 intact and the next launch retries.
+pub(super) fn install_vctk_presets_into_v4_model(models_dir: &Path) -> Result<(), String> {
+    let model_dir = models_dir.join(TTS_MODEL_DIR_NAME);
+    let manifest_path = model_dir.join(MANIFEST_FILENAME);
+    let version = match std::fs::read_to_string(&manifest_path) {
+        Ok(version) => version,
+        Err(_) => return Ok(()),
+    };
+    if version.trim() != PRESET_VOICE_TTS_MODEL_VERSION {
+        return Ok(());
+    }
+    if !TTS_EXPECTED_FILES
+        .iter()
+        .filter(|filename| !is_embedded_voice_file(filename))
+        .all(|filename| model_dir.join(filename).is_file())
+    {
+        return Ok(());
+    }
+
+    for voice in POCKET_VOICES {
+        let Some(bytes) = voice.bytes else {
+            continue;
+        };
+        std::fs::write(model_dir.join(voice.reference_file), bytes)
+            .map_err(|error| format!("write bundled {} voice: {error}", voice.display_name))?;
+    }
+    let retired_marius = model_dir.join("marius.wav");
+    if retired_marius.is_file() {
+        std::fs::remove_file(retired_marius)
+            .map_err(|error| format!("remove retired Marius voice: {error}"))?;
+    }
+    std::fs::write(model_dir.join(TTS_LICENSE_FILE_NAME), TTS_LICENSE_TEXT)
+        .map_err(|error| format!("update Pocket voice notice: {error}"))?;
+    std::fs::write(manifest_path, TTS_MODEL_VERSION)
+        .map_err(|error| format!("update Pocket model manifest: {error}"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn v4_install_adds_presets_without_redownloading_models() {
+        let temp = tempfile::tempdir().expect("tempdir");
+        let model_dir = temp.path().join(TTS_MODEL_DIR_NAME);
+        std::fs::create_dir_all(&model_dir).expect("create model dir");
+        for file in TTS_EXPECTED_FILES
+            .iter()
+            .filter(|filename| !is_embedded_voice_file(filename))
+        {
+            std::fs::write(model_dir.join(file), b"existing").expect("write prior file");
+        }
+        std::fs::write(
+            model_dir.join(MANIFEST_FILENAME),
+            PRESET_VOICE_TTS_MODEL_VERSION,
+        )
+        .expect("write prior manifest");
+        std::fs::write(model_dir.join("marius.wav"), b"retired").expect("write retired voice");
+
+        install_vctk_presets_into_v4_model(temp.path()).expect("in-place upgrade");
+
+        for voice in POCKET_VOICES {
+            if let Some(bytes) = voice.bytes {
+                assert_eq!(
+                    std::fs::read(model_dir.join(voice.reference_file))
+                        .expect("bundled voice installed"),
+                    bytes
+                );
+            }
+        }
+        assert_eq!(
+            std::fs::read_to_string(model_dir.join(MANIFEST_FILENAME)).expect("updated manifest"),
+            TTS_MODEL_VERSION
+        );
+        assert!(!model_dir.join("marius.wav").exists());
+        assert!(
+            ModelSlot::new(TTS_MODEL_DIR_NAME, TTS_EXPECTED_FILES, TTS_MODEL_VERSION)
+                .is_ready(temp.path())
+        );
+    }
+}
diff --git a/desktop/src-tauri/src/huddle/pipeline.rs b/desktop/src-tauri/src/huddle/pipeline.rs
index ceccedd8b6..fba5464a69 100644
--- a/desktop/src-tauri/src/huddle/pipeline.rs
+++ b/desktop/src-tauri/src/huddle/pipeline.rs
@@ -3,12 +3,16 @@
 //! Handles starting, hot-starting, and spawning transcription tasks for
 //! the voice pipelines. Extracted from mod.rs to keep the command layer thin.
 
-use std::sync::{
-    atomic::{AtomicU64, Ordering},
-    Arc, Mutex,
+use std::{
+    sync::{
+        atomic::{AtomicU64, Ordering},
+        Arc, Mutex,
+    },
+    time::Duration,
 };
 
 use nostr::JsonUtil;
+use tauri::State;
 use uuid::Uuid;
 
 use crate::app_state::AppState;
@@ -16,59 +20,228 @@ use crate::events;
 
 use super::models;
 use super::relay_api::{self, fetch_channel_members, parse_channel_uuid};
-use super::state::{HuddlePhase, VoiceInputMode};
+use super::state::{HuddlePhase, HuddleState, VoiceInputMode};
 use super::stt;
 use super::tts;
 
+pub(crate) enum PostConnectOutcome {
+    Ready,
+    Stale,
+}
+
+/// Hot-start: check if voice models just finished downloading during an active
+/// huddle and start the corresponding pipelines.
+///
+/// Called by the frontend on a timer or after model status changes. No-op if
+/// the huddle is not active or pipelines are already running.
+#[tauri::command]
+pub async fn check_pipeline_hotstart(state: State<'_, AppState>) -> Result<(), String> {
+    let (is_active, ephemeral_channel_id, huddle_generation) = {
+        let hs = state.huddle()?;
+        (
+            matches!(hs.phase, HuddlePhase::Connected | HuddlePhase::Active),
+            hs.ephemeral_channel_id.clone(),
+            hs.huddle_generation,
+        )
+    };
+
+    if !is_active {
+        return Ok(());
+    }
+
+    // Detect dead pipelines: if the worker thread has exited (init failure or crash),
+    // clear the pipeline handle so hot-start can retry on the next cycle.
+    {
+        let mut hs = state.huddle()?;
+        if let Some(ref p) = hs.stt_pipeline {
+            if p.is_finished() {
+                hs.stt_pipeline = None;
+            }
+        }
+        if let Some(ref p) = hs.tts_pipeline {
+            if p.is_finished() {
+                hs.tts_pipeline = None;
+            }
+        }
+    }
+    // Re-read after potential cleanup.
+    let (has_stt, has_tts, transcription_enabled) = {
+        let hs = state.huddle()?;
+        (
+            hs.stt_pipeline.is_some(),
+            hs.tts_pipeline.is_some(),
+            hs.transcription_enabled,
+        )
+    };
+
+    // Check if models just became ready (one-shot flags).
+    let stt_ready = models::global_model_manager()
+        .map(|m| m.take_stt_ready())
+        .unwrap_or(false);
+    let tts_ready = models::global_model_manager()
+        .map(|m| m.take_tts_ready())
+        .unwrap_or(false);
+
+    // Start TTS first (so STT can capture tts_cancel).
+    if !has_tts && (tts_ready || models::is_tts_ready()) {
+        if let Err(e) = maybe_start_tts_pipeline(&state).await {
+            eprintln!("buzz-desktop: TTS hotstart failed: {e}");
+        }
+    }
+    if transcription_enabled && !has_stt && (stt_ready || models::is_stt_ready()) {
+        if let Some(eph_id) = &ephemeral_channel_id {
+            if let Err(e) = maybe_start_stt_pipeline(&state, eph_id).await {
+                eprintln!("buzz-desktop: STT hotstart failed: {e}");
+            }
+        }
+    }
+
+    // Periodically refresh agent membership from the relay.
+    // This catches mid-huddle additions/removals by other participants, keeps
+    // STT p-tags authoritative, and auto-enables transcription when the first
+    // agent appears unless the user has already chosen a transcription state.
+    // Throttled independently from the more frequent hotstart poll.
+    //
+    // NOTE: The frontend ALSO polls agent membership independently via
+    // get_huddle_agent_pubkeys. This is intentional — the two polls have
+    // different failure semantics:
+    //   - Rust (here): preserves stale list on failure (STT p-tags should not
+    //     disappear on a transient network blip).
+    //   - React (HuddleContext.tsx): clears list on failure (TTS authorization
+    //     must fail-closed — never speak from a stale agent list).
+    //
+    // On Ok: always replace (even with empty — agents may have been removed).
+    // On Err: preserve the existing list (transient failure shouldn't zero it).
+    if let Some(eph_id) = &ephemeral_channel_id {
+        let should_refresh = {
+            let hs = state.huddle()?;
+            match hs.last_agent_refresh {
+                None => true,
+                Some(t) => t.elapsed() >= std::time::Duration::from_secs(15),
+            }
+        };
+        if should_refresh {
+            // Fetch agents (for STT p-tags) before all members (for participant
+            // list) so relay membership queries remain ordered.
+            // Only update the throttle timestamp when at least one fetch succeeds,
+            // so transient failures retry immediately on the next poll cycle.
+            // Fetch both lists before acquiring the lock — no lock held across await.
+            let fresh_agents = fetch_channel_members(eph_id, Some("bot"), &state)
+                .await
+                .ok();
+            let fresh_members = fetch_channel_members(eph_id, None, &state).await.ok();
+            let transcription_auto_enabled = if fresh_agents.is_some() || fresh_members.is_some() {
+                let mut hs = state.huddle()?;
+                if !hs.is_current_huddle(eph_id, huddle_generation) {
+                    return Ok(());
+                }
+                if let Some(agents) = fresh_agents {
+                    *hs.agent_pubkeys.lock().unwrap_or_else(|e| e.into_inner()) = agents;
+                }
+                if let Some(members) = fresh_members {
+                    hs.participants = members;
+                }
+                hs.last_agent_refresh = Some(std::time::Instant::now());
+                hs.maybe_auto_enable_transcription_for_agents()
+            } else {
+                false
+            };
+            if transcription_auto_enabled {
+                start_auto_enabled_transcription(&state, eph_id).await;
+            }
+        }
+    }
+
+    Ok(())
+}
+
 pub(crate) async fn post_connect_setup(
     state: &AppState,
     ephemeral_channel_id: &str,
-) -> Result<(), String> {
+    huddle_generation: u64,
+) -> Result<PostConnectOutcome, String> {
+    {
+        let hs = state.huddle()?;
+        if !hs.is_current_huddle(ephemeral_channel_id, huddle_generation) {
+            return Ok(PostConnectOutcome::Stale);
+        }
+    }
+
     // Hydrate agent pubkeys and participants from relay in parallel
     // (authoritative — overrides local guesses).
     let (agents_result, all_members_result) = tokio::join!(
         fetch_channel_members(ephemeral_channel_id, Some("bot"), state),
         fetch_channel_members(ephemeral_channel_id, None, state),
     );
-    if let Ok(agents) = agents_result {
-        let hs = state.huddle()?;
-        *hs.agent_pubkeys.lock().unwrap_or_else(|e| e.into_inner()) = agents;
-    }
-
-    if let Ok(all_members) = all_members_result {
-        if !all_members.is_empty() {
-            let mut hs = state.huddle()?;
-            hs.participants = all_members;
+    let transcription_auto_enabled = {
+        let mut hs = state.huddle()?;
+        if !hs.is_current_huddle(ephemeral_channel_id, huddle_generation) {
+            return Ok(PostConnectOutcome::Stale);
+        }
+        if let Ok(agents) = agents_result {
+            *hs.agent_pubkeys.lock().unwrap_or_else(|e| e.into_inner()) = agents;
+        }
+        if let Ok(all_members) = all_members_result {
+            if !all_members.is_empty() {
+                hs.participants = all_members;
+            }
         }
+        hs.maybe_auto_enable_transcription_for_agents()
+    };
+
+    if transcription_auto_enabled {
+        state.emit_huddle_state_changed();
     }
 
-    // Prepare TTS for agent voice. STT is transcript-specific and starts only
-    // when transcription is explicitly enabled.
+    // Prepare voice models. Agent presence may have auto-enabled transcription;
+    // explicit user choices remain authoritative.
     if let Some(mgr) = models::global_model_manager() {
         mgr.start_tts_download(state.http_client.clone());
+        if state.huddle()?.transcription_enabled {
+            mgr.start_stt_download(state.http_client.clone());
+        }
     }
 
     // Connect audio relay WebSocket (Opus encode/decode pipeline).
     // This is the core audio path — failure is fatal for the huddle.
     let parent_id = {
         let hs = state.huddle()?;
+        if !hs.is_current_huddle(ephemeral_channel_id, huddle_generation) {
+            return Ok(PostConnectOutcome::Stale);
+        }
         hs.parent_channel_id.clone()
     };
-    let (cancel, pcm_tx) =
-        relay_api::connect_audio_relay(ephemeral_channel_id, parent_id.as_deref(), state).await?;
+    let audio_result =
+        relay_api::connect_audio_relay(ephemeral_channel_id, parent_id.as_deref(), state).await;
     {
         let mut hs = state.huddle()?;
+        if !hs.is_current_huddle(ephemeral_channel_id, huddle_generation) {
+            if let Ok((cancel, _)) = audio_result {
+                cancel.cancel();
+            }
+            return Ok(PostConnectOutcome::Stale);
+        }
+        let (cancel, pcm_tx) = audio_result?;
         hs.audio_ws_cancel = Some(cancel);
         hs.audio_relay_pcm_tx = Some(pcm_tx);
     }
 
-    // Start TTS immediately. STT/transcript posting is opt-in and starts only
-    // after the user explicitly enables transcription.
+    // Start TTS immediately, then STT when transcription is enabled either by
+    // the user or by authoritative agent membership.
+    if !state
+        .huddle()?
+        .is_current_huddle(ephemeral_channel_id, huddle_generation)
+    {
+        return Ok(PostConnectOutcome::Stale);
+    }
     if let Err(e) = maybe_start_tts_pipeline(state).await {
         eprintln!("buzz-desktop: TTS pipeline failed to start: {e}");
     }
+    if let Err(e) = maybe_start_stt_pipeline(state, ephemeral_channel_id).await {
+        eprintln!("buzz-desktop: STT pipeline failed to start: {e}");
+    }
 
-    Ok(())
+    Ok(PostConnectOutcome::Ready)
 }
 
 /// Attempt to start the STT pipeline if models are present.
@@ -83,12 +256,16 @@ pub(crate) async fn maybe_start_stt_pipeline(
     state: &AppState,
     ephemeral_channel_id: &str,
 ) -> Result<bool, String> {
-    {
+    let huddle_generation = {
         let hs = state.huddle()?;
-        if !hs.transcription_enabled {
+        if !hs.transcription_enabled
+            || !matches!(hs.phase, HuddlePhase::Connected | HuddlePhase::Active)
+            || hs.ephemeral_channel_id.as_deref() != Some(ephemeral_channel_id)
+        {
             return Ok(false);
         }
-    }
+        hs.huddle_generation
+    };
 
     if !models::is_stt_ready() {
         return Ok(false); // Models not downloaded yet — voice-only mode.
@@ -97,21 +274,29 @@ pub(crate) async fn maybe_start_stt_pipeline(
 
     let channel_uuid = parse_channel_uuid(ephemeral_channel_id)?;
 
-    // Atomically claim the construction slot (mirrors tts_starting pattern).
-    {
-        let hs = state.huddle()?;
-        if hs.stt_starting.swap(true, Ordering::AcqRel) {
-            return Ok(false); // Another caller is already constructing.
-        }
-    }
-
-    // Grab shared flags, agent pubkeys, and session generation from HuddleState.
+    // Atomically claim construction and grab shared state under one lock.
     // If replacing an existing pipeline, bump generation first so the old
     // transcription task's next POST sees a stale generation and exits.
     // Take the old pipeline OUT of the lock before dropping — Drop joins
     // the worker thread (~200ms) and must not block under the mutex.
-    let (tts_active, tts_cancel, agent_pubkeys_arc, session_gen, ptt_active_for_stt, old_stt) = {
+    let (
+        tts_active,
+        tts_cancel,
+        agent_pubkeys_arc,
+        session_gen,
+        expected_generation,
+        stt_starting,
+        ptt_active_for_stt,
+        old_stt,
+    ) = {
         let mut hs = state.huddle()?;
+        if !hs.is_current_huddle(ephemeral_channel_id, huddle_generation) {
+            return Ok(false);
+        }
+        if hs.stt_starting.swap(true, Ordering::AcqRel) {
+            return Ok(false);
+        }
+        let stt_starting = Arc::clone(&hs.stt_starting);
         // Invalidate any existing transcription task before replacing the pipeline.
         if hs.stt_pipeline.is_some() {
             hs.session_generation.fetch_add(1, Ordering::Release);
@@ -130,6 +315,8 @@ pub(crate) async fn maybe_start_stt_pipeline(
             Some(Arc::clone(&hs.tts_cancel)),
             Arc::clone(&hs.agent_pubkeys),
             Arc::clone(&hs.session_generation),
+            hs.session_generation.load(Ordering::Acquire),
+            stt_starting,
             ptt,
             old,
         )
@@ -144,13 +331,11 @@ pub(crate) async fn maybe_start_stt_pipeline(
     let (pipeline, text_rx) = match constructed {
         Ok(Ok(p)) => p,
         Ok(Err(e)) => {
-            let hs = state.huddle()?;
-            hs.stt_starting.store(false, Ordering::Release);
+            stt_starting.store(false, Ordering::Release);
             return Err(e);
         }
         Err(e) => {
-            let hs = state.huddle()?;
-            hs.stt_starting.store(false, Ordering::Release);
+            stt_starting.store(false, Ordering::Release);
             return Err(format!("spawn_blocking failed: {e}"));
         }
     };
@@ -158,10 +343,14 @@ pub(crate) async fn maybe_start_stt_pipeline(
 
     {
         let mut hs = state.huddle()?;
-        hs.stt_starting.store(false, Ordering::Release);
+        stt_starting.store(false, Ordering::Release);
         // Phase check: huddle may have been torn down during construction.
         if !hs.transcription_enabled
-            || !matches!(hs.phase, HuddlePhase::Connected | HuddlePhase::Active)
+            || !hs.is_current_transcription_generation(
+                ephemeral_channel_id,
+                huddle_generation,
+                expected_generation,
+            )
         {
             return Ok(false);
         }
@@ -172,6 +361,17 @@ pub(crate) async fn maybe_start_stt_pipeline(
     Ok(true)
 }
 
+/// Start STT after agent presence automatically enables transcription.
+pub(crate) async fn start_auto_enabled_transcription(state: &AppState, ephemeral_channel_id: &str) {
+    if let Some(manager) = models::global_model_manager() {
+        manager.start_stt_download(state.http_client.clone());
+    }
+    if let Err(error) = maybe_start_stt_pipeline(state, ephemeral_channel_id).await {
+        eprintln!("buzz-desktop: auto-enabled STT failed to start: {error}");
+    }
+    state.emit_huddle_state_changed();
+}
+
 /// Attempt to start the TTS pipeline if TTS models are present and TTS is enabled.
 ///
 /// Returns `Ok(true)` if the pipeline was started, `Ok(false)` if preconditions
@@ -192,10 +392,44 @@ pub(crate) async fn maybe_start_tts_pipeline(state: &AppState) -> Result<bool, S
         None => return Ok(false),
     };
 
+    // Avoid resolving and hashing imported voice files on every hot-start poll
+    // when TTS is already disabled or running. The guarded claim below repeats
+    // these checks after the fallible work to close the race.
+    {
+        let huddle = state.huddle()?;
+        if huddle.tts_pipeline.is_some() || !huddle.tts_enabled {
+            return Ok(false);
+        }
+    }
+
+    // Resolve all fallible construction inputs before claiming the sentinel so
+    // an unreadable optional voice registry cannot wedge future start attempts.
+    let output_device = state
+        .huddle_audio
+        .output_device
+        .lock()
+        .unwrap_or_else(|e| e.into_inner())
+        .clone();
+    let app = state
+        .app_handle
+        .lock()
+        .map_err(|error| format!("app handle lock poisoned: {error}"))?
+        .clone();
+    let voice_preferences = state
+        .huddle_audio
+        .tts
+        .lock()
+        .map_err(|error| format!("text-to-speech settings lock poisoned: {error}"))
+        .map(|settings| settings.voice_preferences.clone())?;
+    let initial_voice = match app {
+        Some(app) => super::tts_settings::pocket_voice_reference(&app, &voice_preferences)?,
+        None => super::tts_settings::bundled_pocket_voice_reference(&voice_preferences),
+    };
+
     // Atomically check preconditions and claim the construction slot.
     // The sentinel prevents a second caller from starting construction
     // while we're building outside the lock.
-    let (tts_active, tts_cancel) = {
+    let (tts_active, tts_cancel, tts_starting) = {
         let hs = state.huddle()?;
         if hs.tts_pipeline.is_some() {
             return Ok(false);
@@ -206,18 +440,25 @@ pub(crate) async fn maybe_start_tts_pipeline(state: &AppState) -> Result<bool, S
         if hs.tts_starting.swap(true, Ordering::AcqRel) {
             return Ok(false); // Another caller is already constructing.
         }
-        (Arc::clone(&hs.tts_active), Arc::clone(&hs.tts_cancel))
+        (
+            Arc::clone(&hs.tts_active),
+            Arc::clone(&hs.tts_cancel),
+            Arc::clone(&hs.tts_starting),
+        )
     };
+    let _starting_guard = TtsStartingGuard(tts_starting);
 
     // Construct outside the lock — this spawns the TTS worker thread and
     // loads ONNX sessions (~200ms). If this fails, clear the sentinel.
-    let output_device = state
-        .audio_output_device
-        .lock()
-        .unwrap_or_else(|e| e.into_inner())
-        .clone();
+    let constructed_voice = initial_voice.clone();
     let constructed = tokio::task::spawn_blocking(move || {
-        tts::TtsPipeline::new(model_dir, tts_active, tts_cancel, output_device)
+        tts::TtsPipeline::new_with_voice(
+            model_dir,
+            tts_active,
+            tts_cancel,
+            &initial_voice,
+            output_device,
+        )
     })
     .await;
     let pipeline = match constructed {
@@ -234,23 +475,104 @@ pub(crate) async fn maybe_start_tts_pipeline(state: &AppState) -> Result<bool, S
         }
     };
 
-    {
-        let mut hs = state.huddle()?;
-        hs.tts_starting.store(false, Ordering::Release);
-        // Phase check: huddle may have been torn down during construction.
-        if !matches!(hs.phase, HuddlePhase::Connected | HuddlePhase::Active) {
-            return Ok(false);
+    finalize_tts_pipeline_start(state, move |voice, huddle| {
+        if should_reselect_constructed_voice(&constructed_voice, voice) {
+            pipeline.select_voice_before_publish(voice);
         }
-        // Final check: another path may have created a pipeline while we were constructing.
-        if hs.tts_pipeline.is_some() {
-            return Ok(false);
+        huddle.tts_pipeline = Some(pipeline);
+    })
+}
+
+/// Wait for a concurrent TTS constructor to publish or fail.
+///
+/// `maybe_start_tts_pipeline` deliberately lets only one caller construct the
+/// engine. A live message that loses that race must wait for the owner instead
+/// of observing the temporary empty slot and being dropped.
+pub(crate) async fn await_inflight_tts_start(state: &AppState) -> Result<(), String> {
+    let starting = {
+        let huddle = state.huddle()?;
+        Arc::clone(&huddle.tts_starting)
+    };
+    tokio::time::timeout(Duration::from_secs(15), async {
+        while starting.load(Ordering::Acquire) {
+            tokio::time::sleep(Duration::from_millis(10)).await;
         }
-        hs.tts_pipeline = Some(pipeline);
+    })
+    .await
+    .map_err(|_| "TTS pipeline startup did not finish before timeout".to_string())?;
+    // The owner clears the sentinel while holding the huddle lock, before it
+    // publishes. Reacquiring that lock ensures publication is visible before
+    // the losing caller looks up the sender.
+    drop(state.huddle()?);
+    Ok(())
+}
+
+struct TtsStartingGuard(Arc<std::sync::atomic::AtomicBool>);
+
+impl Drop for TtsStartingGuard {
+    fn drop(&mut self) {
+        self.0.store(false, Ordering::Release);
     }
+}
 
+/// Publish a constructed TTS pipeline against the latest settings.
+///
+/// Construction happens outside locks and can overlap a voice change or OFF
+/// transition. Holding the huddle lock while re-reading settings gives either
+/// transition a safe ordering: it updates the installed pipeline afterward,
+/// or this finalizer observes the new setting before publishing.
+fn finalize_tts_pipeline_start(
+    state: &AppState,
+    publish: impl FnOnce(&str, &mut HuddleState),
+) -> Result<bool, String> {
+    let mut huddle = state.huddle()?;
+    huddle.tts_starting.store(false, Ordering::Release);
+    if !huddle.tts_enabled
+        || !matches!(huddle.phase, HuddlePhase::Connected | HuddlePhase::Active)
+        || huddle.tts_pipeline.is_some()
+    {
+        return Ok(false);
+    }
+    let app = state
+        .app_handle
+        .lock()
+        .map_err(|error| format!("app handle lock poisoned: {error}"))?
+        .clone();
+    let preferences = state
+        .huddle_audio
+        .tts
+        .lock()
+        .map_err(|error| format!("text-to-speech settings lock poisoned: {error}"))
+        .map(|settings| settings.voice_preferences.clone())?;
+    let voice = match app {
+        Some(app) => super::tts_settings::pocket_voice_reference(&app, &preferences)?,
+        None => super::tts_settings::bundled_pocket_voice_reference(&preferences),
+    };
+    publish(&voice, &mut huddle);
     Ok(true)
 }
 
+fn should_reselect_constructed_voice(constructed_voice: &str, latest_voice: &str) -> bool {
+    constructed_voice != latest_voice
+}
+
+/// Sign an STT transcript event and produce the guarded POST body.
+///
+/// Factored out of the transcription loop so egress boundary 5 (huddle STT)
+/// has a directly testable seam: the NIP-49 egress guard runs here, before
+/// any bytes can reach the network.
+pub(crate) fn sign_and_guard_stt_body(
+    builder: nostr::EventBuilder,
+    keys: &nostr::Keys,
+) -> Result<Vec<u8>, String> {
+    let event = builder
+        .sign_with_keys(keys)
+        .map_err(|e| format!("sign event: {e}"))?;
+    let body_bytes = event.as_json().into_bytes();
+    crate::egress_guard::assert_no_key_backup_bytes(&body_bytes, "huddle STT publish")?;
+    Ok(body_bytes)
+}
+
 /// Spawn a tokio task that reads text_rx and posts kind:9 events.
 ///
 /// Fix 1: `agent_pubkeys_arc` is an `Arc<Mutex<Vec<String>>>` cloned from
@@ -310,14 +632,13 @@ pub(crate) fn spawn_transcription_task(
             // the kind event and build NIP-98 auth after the wait so both
             // timestamps are fresh — single clean order: wait → sign → auth → send.
             crate::relay_admission::wait_for_rate_limit().await;
-            let event = match builder.sign_with_keys(&keys) {
-                Ok(e) => e,
+            let body_bytes = match sign_and_guard_stt_body(builder, &keys) {
+                Ok(b) => b,
                 Err(e) => {
-                    eprintln!("buzz-desktop: STT sign event: {e}");
+                    eprintln!("buzz-desktop: STT publish: {e}");
                     continue;
                 }
             };
-            let body_bytes = event.as_json().into_bytes();
             let url = format!("{relay_base_url}/events");
             let auth_header = match crate::relay::build_nip98_auth_header_for_keys(
                 &keys,
@@ -357,3 +678,148 @@ pub(crate) fn spawn_transcription_task(
         }
     });
 }
+
+#[cfg(test)]
+mod tts_start_race_tests {
+    use std::sync::{
+        atomic::{AtomicBool, Ordering},
+        Arc, Barrier, Mutex,
+    };
+    use std::time::Duration;
+
+    use crate::app_state::build_app_state;
+
+    use super::{
+        await_inflight_tts_start, finalize_tts_pipeline_start, should_reselect_constructed_voice,
+        HuddlePhase,
+    };
+
+    #[tokio::test]
+    async fn a_losing_starter_observes_publication_before_resuming() {
+        let state = Arc::new(build_app_state());
+        {
+            let mut huddle = state.huddle().expect("huddle state");
+            huddle.phase = HuddlePhase::Active;
+            huddle.tts_enabled = true;
+            huddle.tts_starting.store(true, Ordering::Release);
+        }
+        let published = Arc::new(AtomicBool::new(false));
+        let owner_state = Arc::clone(&state);
+        let owner_published = Arc::clone(&published);
+        let owner = std::thread::spawn(move || {
+            std::thread::sleep(Duration::from_millis(20));
+            finalize_tts_pipeline_start(&owner_state, |_, _| {
+                owner_published.store(true, Ordering::Release);
+            })
+        });
+
+        await_inflight_tts_start(&state)
+            .await
+            .expect("wait for pipeline owner");
+        assert!(published.load(Ordering::Acquire));
+        assert!(owner.join().expect("pipeline owner").expect("finalize"));
+    }
+
+    #[test]
+    fn constructor_fallback_survives_unchanged_preference_at_publication() {
+        let selected_voice = Mutex::new(super::super::pocket::DEFAULT_VOICE.to_string());
+        let constructed_voice = "eve";
+        let latest_voice = "eve";
+
+        if should_reselect_constructed_voice(constructed_voice, latest_voice) {
+            *selected_voice.lock().expect("selected voice") = latest_voice.to_string();
+        }
+
+        assert_eq!(
+            selected_voice.lock().expect("selected voice").as_str(),
+            super::super::pocket::DEFAULT_VOICE
+        );
+    }
+
+    #[test]
+    fn construction_reconciles_a_voice_selected_while_starting() {
+        let state = Arc::new(build_app_state());
+        {
+            let mut huddle = state.huddle().expect("huddle state");
+            huddle.phase = HuddlePhase::Active;
+            huddle.tts_enabled = true;
+            huddle.tts_starting.store(true, Ordering::Release);
+        }
+
+        let constructed = Arc::new(Barrier::new(2));
+        let publish = Arc::new(Barrier::new(2));
+        let selected_voice = Arc::new(Mutex::new(None));
+        let worker_state = Arc::clone(&state);
+        let worker_constructed = Arc::clone(&constructed);
+        let worker_publish = Arc::clone(&publish);
+        let worker_voice = Arc::clone(&selected_voice);
+        let worker = std::thread::spawn(move || {
+            worker_constructed.wait();
+            worker_publish.wait();
+            finalize_tts_pipeline_start(&worker_state, |voice, _| {
+                *worker_voice.lock().expect("selected voice") = Some(voice.to_string());
+            })
+        });
+
+        constructed.wait();
+        assert!(state
+            .huddle()
+            .expect("huddle state")
+            .tts_starting
+            .load(Ordering::Acquire));
+        state
+            .huddle_audio
+            .tts
+            .lock()
+            .expect("text-to-speech settings")
+            .voice_preferences = vec!["pocket:eve".to_string()];
+        publish.wait();
+
+        assert!(worker.join().expect("starter thread").expect("finalize"));
+        assert_eq!(
+            *selected_voice.lock().expect("selected voice"),
+            Some("eve".to_string())
+        );
+    }
+
+    #[test]
+    fn construction_is_discarded_when_disabled_while_starting() {
+        let state = Arc::new(build_app_state());
+        {
+            let mut huddle = state.huddle().expect("huddle state");
+            huddle.phase = HuddlePhase::Active;
+            huddle.tts_enabled = true;
+            huddle.tts_starting.store(true, Ordering::Release);
+        }
+
+        let constructed = Arc::new(Barrier::new(2));
+        let publish = Arc::new(Barrier::new(2));
+        let did_publish = Arc::new(Mutex::new(false));
+        let worker_state = Arc::clone(&state);
+        let worker_constructed = Arc::clone(&constructed);
+        let worker_publish = Arc::clone(&publish);
+        let worker_did_publish = Arc::clone(&did_publish);
+        let worker = std::thread::spawn(move || {
+            worker_constructed.wait();
+            worker_publish.wait();
+            finalize_tts_pipeline_start(&worker_state, |_, _| {
+                *worker_did_publish.lock().expect("publish flag") = true;
+            })
+        });
+
+        constructed.wait();
+        {
+            let mut huddle = state.huddle().expect("huddle state");
+            huddle.tts_enabled = false;
+        }
+        publish.wait();
+
+        assert!(!worker.join().expect("starter thread").expect("finalize"));
+        assert!(!*did_publish.lock().expect("publish flag"));
+        assert!(!state
+            .huddle()
+            .expect("huddle state")
+            .tts_starting
+            .load(Ordering::Acquire));
+    }
+}
diff --git a/desktop/src-tauri/src/huddle/pocket.rs b/desktop/src-tauri/src/huddle/pocket.rs
index ee1faf928a..fd407103d1 100644
--- a/desktop/src-tauri/src/huddle/pocket.rs
+++ b/desktop/src-tauri/src/huddle/pocket.rs
@@ -1,654 +1,4 @@
-//! Pocket TTS engine wrapper around sherpa-onnx's `OfflineTts`.
-//!
-//! Pocket TTS is a small (~473 MB fp32 ONNX) zero-shot voice-cloning TTS
-//! model from Kyutai. It runs quickly on CPU via sherpa-onnx, replacing the
-//! previous Kokoro-82M engine that also required an espeak-free but
-//! lexicon-heavy G2P pipeline (Misaki + CMUdict).
-//!
-//! Full-precision fp32 sessions, not the ~189 MB int8 quantization we
-//! originally shipped: a direct same-runtime A/B (k2-fsa/sherpa-onnx#3172)
-//! found the int8 ONNX export audibly degraded output quality, and fp32
-//! "significantly improved quality even at 1 step".
-//!
-//! ## Attribution
-//!
-//! - **Model**: Kyutai *Pocket TTS* — Charles, Roebel, et al., 2026.
-//!   arXiv:2509.06926. Original repository: <https://huggingface.co/kyutai/pocket-tts>.
-//!   Licensed CC-BY-4.0.
-//! - **Mimi neural codec**: Kyutai, bundled in the same release. CC-BY-4.0.
-//! - **ONNX export**: KevinAHM —
-//!   <https://huggingface.co/KevinAHM/pocket-tts-onnx>. CC-BY-4.0.
-//! - **sherpa-onnx repackage**: csukuangfj / k2-fsa —
-//!   <https://huggingface.co/csukuangfj2/sherpa-onnx-pocket-tts-2026-01-26>.
-//!   Repackages KevinAHM's export with the file layout sherpa-onnx's
-//!   `OfflineTtsPocketModelConfig` expects. CC-BY-4.0.
-//! - **Reference voice WAV** (`reference_sample.wav`): the "Mary
-//!   (f, conversation)" preset from the Kyutai TTS demo
-//!   (<https://kyutai.org/tts>), which maps to `vctk/p333_023_enhanced.wav`
-//!   in <https://huggingface.co/kyutai/tts-voices>. CC-BY-4.0, base recording
-//!   from the VCTK corpus, enhanced by ai-coustics.
-//!
-//! Buzz ships these files unmodified; see the on-disk `MODEL_LICENSE.txt`
-//! sidecar written by `huddle::models` during install for the canonical
-//! CC-BY-4.0 §3(a)(1) attribution block.
-//!
-//! ## Engine-module contract (see `huddle::tts`)
-//!
-//! `pocket.rs` exposes a fixed surface used by `tts.rs`. Mirroring this
-//! contract is what lets the TTS pipeline stay engine-agnostic:
-//!
-//! - `SAMPLE_RATE: u32`             — engine output sample rate in Hz.
-//! - `DEFAULT_VOICE: &str`          — default voice name (without extension).
-//! - `VOICE_FILE_EXT: &str`         — extension for per-voice files on disk.
-//! - `load_text_to_speech(model_dir)`              → `Result<Engine, String>`
-//! - `load_voice_style(path)`                      → `Result<VoiceStyle, String>`
-//! - `Engine::synth_chunk(&self, text, lang, &VoiceStyle, steps)`
-//!   → `Result<Vec<f32>, String>`
-//!
-//! `lang` and `steps` are accepted for API compatibility with the previous
-//! Kokoro engine but are unused — Pocket TTS does its own language ID from
-//! the input text and is not a diffusion model (consistency LM, one step).
-//! There is no speed knob: sherpa-onnx's `GenerationConfig.speed` is only
-//! read by some model families (vits), never by the Pocket impl
-//! (`offline-tts-pocket-impl.h` — zero references), and upstream pocket-tts
-//! has no speed parameter either.
-
-use std::collections::HashMap;
-use std::path::{Path, PathBuf};
-
-use sherpa_onnx::{GenerationConfig, OfflineTts, OfflineTtsConfig, Wave};
-
-// ── Engine-module contract: public consts ─────────────────────────────────────
-
-/// Pocket TTS emits 24 kHz mono PCM. Matches the previous Kokoro output rate,
-/// so the rodio sink and inter-sentence silence buffer in `tts.rs` remain valid.
-pub const SAMPLE_RATE: u32 = 24_000;
-
-/// Name (without extension) of the bundled reference voice. The model directory
-/// is expected to contain `<DEFAULT_VOICE>.<VOICE_FILE_EXT>` after install.
-pub const DEFAULT_VOICE: &str = "reference_sample";
-
-/// Voice files for Pocket TTS are reference audio (WAV). Distinct from the
-/// Kokoro `.bin` style vectors — the model conditions on raw waveform samples,
-/// not a precomputed embedding, so the extension change is honest.
-pub const VOICE_FILE_EXT: &str = "wav";
-
-// ── Tuning ────────────────────────────────────────────────────────────────────
-
-/// Single-threaded ONNX execution for predictable CPU contention with the STT
-/// pipeline. Matches `STT_NUM_THREADS` in `stt.rs`; raise only if a benchmark
-/// argues for it.
-const TTS_NUM_THREADS: i32 = 1;
-
-/// LRU cache size for cloned voice embeddings inside the sherpa-onnx engine.
-/// We bind to one voice per pipeline today, but the upstream example uses 16
-/// and the cost is negligible — keep room for future multi-voice support.
-const VOICE_EMBEDDING_CACHE_CAPACITY: i32 = 16;
-
-/// Pocket TTS is a consistency-based LM. Generation quality saturates at one
-/// denoising step — the upstream `GenerationConfig` default of 5 multiplies
-/// synthesis time by ~5× with no audible benefit on this model.
-const SYNTH_NUM_STEPS: i32 = 1;
-
-/// Leave the generated audio's silences untouched (1.0 is the identity).
-///
-/// sherpa-onnx's `ScaleSilence` (`offline-tts.cc`) is *not* pre/post padding
-/// control: it finds every interior silence run ≥ 0.2 s (|s| ≤ 0.01) and
-/// multiplies its length by this factor. The previous value of 0.0 — set
-/// under the mistaken belief it disabled lead-in/lead-out padding — deleted
-/// every natural pause inside an utterance: clause breaks, breaths, the gap
-/// after a comma. Words slammed together and endings cut abruptly. The
-/// reference Pocket TTS pipeline does not post-process silence at all;
-/// 1.0 restores parity.
-const SYNTH_SILENCE_SCALE: f32 = 1.0;
-
-/// sherpa-onnx upstream default for `max_frames` (LM steps), in
-/// `offline-tts-pocket-impl.h:Generate`. 500 steps ≈ 40 s of audio at the
-/// Mimi 12.5 Hz frame rate. Referenced only by the regression test below;
-/// production code path never raises (or even reads) this value — we just
-/// leave sherpa-onnx's own default in place by not setting the override.
-#[cfg(test)]
-const SHERPA_ONNX_MAX_FRAMES_DEFAULT: i32 = 500;
-
-/// Tight `max_frames` we ask for on short, padded prompts to bound the
-/// original "monster breathing" runaway. 100 LM steps ≈ 8 s of audio —
-/// roomy for any one-to-four-word utterance the user is likely to elicit
-/// while still well short of the 40 s upstream default. Chosen with slack so
-/// we never *truncate* a legitimate short reply.
-const SHORT_PROMPT_MAX_FRAMES: i32 = 100;
-
-/// Word-count threshold (inclusive) below which we pad the prompt with
-/// leading spaces and cap `max_frames` tighter than the upstream default.
-/// Matches upstream `pocket_tts.models.tts_model.prepare_text_prompt`. Above
-/// this threshold we leave sherpa-onnx's own defaults in place — overriding
-/// them caused the "first 'yep' is just static" regression seen on
-/// 2026-05-18, where dropping `frames_after_eos` below the upstream default
-/// of 3 clipped the leading audio of multi-clause sentences.
-const SHORT_PROMPT_WORD_THRESHOLD: usize = 4;
-
-/// Number of leading spaces prepended to short prompts. The upstream Python
-/// uses exactly 8 — keep parity rather than tuning blindly.
-///
-/// This is upstream's *only* mitigation for the FlowLM cold-start smear on
-/// short utterances (kyutai-labs/pocket-tts #91, #70): the autoregressive
-/// generation has a 2–3 step "settle" period where the first phoneme can be
-/// smeared. A previous revision added a sacrificial `". . "` prefix plus an
-/// amplitude-threshold trim to strip the rendered prefix from the output —
-/// but the trim's absolute threshold (0.02 against raw peaks of ~0.076) sat
-/// in soft-onset territory and could eat real word starts, and its tuning
-/// was calibrated against `silence_scale = 0.0` audio. Deleted in favour of
-/// upstream parity: accept the occasional smeared first syllable rather
-/// than risk trimming real speech.
-const SHORT_PROMPT_PAD_SPACES: usize = 8;
-
-/// sherpa-onnx's documented `frames_after_eos` default. We deliberately do
-/// *not* override this knob — the previous attempt to bump it for short
-/// inputs and lower it for long inputs lowered it below the upstream default
-/// of 3, which clipped the leading audio of multi-clause sentences (the
-/// "first 'yep' is static" regression). The constant exists only for the
-/// regression test below. Source: `offline-tts-pocket-impl.h:Generate`.
-#[cfg(test)]
-const SHERPA_ONNX_FRAMES_AFTER_EOS_DEFAULT: i32 = 3;
-
-// ── ONNX file names (five Pocket TTS sessions plus two JSON tables) ───────────
-
-const FILE_LM_MAIN: &str = "lm_main.onnx";
-const FILE_LM_FLOW: &str = "lm_flow.onnx";
-const FILE_ENCODER: &str = "encoder.onnx";
-const FILE_DECODER: &str = "decoder.onnx";
-const FILE_TEXT_COND: &str = "text_conditioner.onnx";
-const FILE_VOCAB: &str = "vocab.json";
-const FILE_TOKEN_SCORES: &str = "token_scores.json";
-
-// ── Voice style ───────────────────────────────────────────────────────────────
-
-/// Loaded reference voice — normalised f32 PCM samples plus their sample rate.
-///
-/// Pocket TTS takes a reference waveform per generation call (not a
-/// precomputed style embedding), so we keep the samples in memory and clone
-/// the small `Vec` into each `GenerationConfig` rather than re-reading the
-/// WAV from disk on every sentence.
-#[derive(Debug, Clone)]
-pub struct VoiceStyle {
-    samples: Vec<f32>,
-    sample_rate: i32,
-}
-
-/// Load a reference voice WAV from disk.
-///
-/// Accepts any sample rate sherpa-onnx's `Wave::read` can decode — Pocket TTS
-/// resamples internally using `reference_sample_rate`. The bundled
-/// `reference_sample.wav` ("Mary" — VCTK p333, enhanced) is 32 kHz mono.
-pub fn load_voice_style(path: &Path) -> Result<VoiceStyle, String> {
-    let path_str = path
-        .to_str()
-        .ok_or_else(|| format!("voice path is not valid UTF-8: {}", path.display()))?;
-    let wave = Wave::read(path_str)
-        .ok_or_else(|| format!("could not read voice WAV at {}", path.display()))?;
-    let samples = wave.samples().to_vec();
-    if samples.is_empty() {
-        return Err(format!("voice WAV is empty: {}", path.display()));
-    }
-    Ok(VoiceStyle {
-        samples,
-        sample_rate: wave.sample_rate(),
-    })
-}
-
-// ── Engine ────────────────────────────────────────────────────────────────────
-
-/// Pocket TTS engine handle. Cheap to construct (one `OfflineTts::create`
-/// call). Owned by the TTS worker thread for the lifetime of a huddle session.
-///
-/// `OfflineTts` does not implement `Debug`, so we don't derive it here — the
-/// pipeline only needs to move the engine into the worker thread and call
-/// `synth_chunk` on it, never to print it.
-pub struct PocketTts {
-    inner: OfflineTts,
-}
-
-/// Build the Pocket TTS engine from the model directory installed by
-/// `huddle::models`. Returns `Err` if any expected ONNX or JSON file is
-/// missing — readiness is normally enforced by `is_tts_ready` upstream, but
-/// the check is repeated here so a manually-modified model dir produces a
-/// clear error string instead of an opaque sherpa-onnx `None`.
-pub fn load_text_to_speech(model_dir: &str) -> Result<PocketTts, String> {
-    let dir = PathBuf::from(model_dir);
-    for name in [
-        FILE_LM_MAIN,
-        FILE_LM_FLOW,
-        FILE_ENCODER,
-        FILE_DECODER,
-        FILE_TEXT_COND,
-        FILE_VOCAB,
-        FILE_TOKEN_SCORES,
-    ] {
-        let p = dir.join(name);
-        if !p.is_file() {
-            return Err(format!("missing Pocket TTS file: {}", p.display()));
-        }
-    }
-
-    let to_str = |name: &str| -> String { dir.join(name).to_string_lossy().into_owned() };
-
-    // Build the config by mutating defaults — mirrors `stt.rs` and stays
-    // resilient if sherpa-onnx adds unrelated model-family fields.
-    let mut cfg = OfflineTtsConfig::default();
-    cfg.model.pocket.lm_main = Some(to_str(FILE_LM_MAIN));
-    cfg.model.pocket.lm_flow = Some(to_str(FILE_LM_FLOW));
-    cfg.model.pocket.encoder = Some(to_str(FILE_ENCODER));
-    cfg.model.pocket.decoder = Some(to_str(FILE_DECODER));
-    cfg.model.pocket.text_conditioner = Some(to_str(FILE_TEXT_COND));
-    cfg.model.pocket.vocab_json = Some(to_str(FILE_VOCAB));
-    cfg.model.pocket.token_scores_json = Some(to_str(FILE_TOKEN_SCORES));
-    cfg.model.pocket.voice_embedding_cache_capacity = VOICE_EMBEDDING_CACHE_CAPACITY;
-    cfg.model.num_threads = TTS_NUM_THREADS;
-    // Explicit — defaults are not part of the API contract, and noisy debug
-    // logging in release builds would be expensive on every synthesized chunk.
-    cfg.model.debug = false;
-
-    let inner = OfflineTts::create(&cfg)
-        .ok_or_else(|| "OfflineTts::create returned None for Pocket TTS".to_string())?;
-    Ok(PocketTts { inner })
-}
-
-// ── Prompt preparation ────────────────────────────────────────────────────────
-
-/// Result of [`prepare_pocket_prompt`]: a synthesizer-ready prompt plus the
-/// per-call generation overrides derived from the original text.
-///
-/// `None` for either override means "leave sherpa-onnx's documented default
-/// in place". The pipeline only sets `max_frames` (and only for short
-/// padded inputs) so it can bound the original "monster breathing" runaway
-/// without disturbing the rest of the LM sampling envelope.
-#[derive(Debug, Clone, PartialEq)]
-pub(crate) struct PreparedPrompt {
-    /// Text to hand to `OfflineTts::generate_with_config`. Capitalized,
-    /// punctuation-terminated, and (for short inputs) left-padded with
-    /// spaces — upstream's mitigation for the FlowLM cold-start smear.
-    pub text: String,
-    /// Value to pass via `GenerationConfig.extra["max_frames"]`, or `None` to
-    /// keep the upstream default of 500 LM steps. We only override on short
-    /// padded prompts where we have a tight expectation on output length.
-    pub max_frames: Option<i32>,
-}
-
-/// Mirror of the *text-preparation* half of upstream
-/// `pocket_tts.models.tts_model.prepare_text_prompt`. Sherpa-onnx's C++
-/// Pocket TTS impl does not run these preparation steps, so short /
-/// unpunctuated / lowercase inputs can trigger up to 40 s of runaway
-/// generation when the EOS logit never crosses its threshold. We replicate
-/// the upstream Python recipe here:
-///
-/// 1. Collapse interior whitespace (already done by `preprocess_for_tts`, but
-///    cheap to re-check after sentence splitting).
-/// 2. Capitalize the first letter.
-/// 3. Append `.` if the text doesn't end in punctuation.
-/// 4. If fewer than five words, prepend `SHORT_PROMPT_PAD_SPACES` spaces
-///    (upstream's cold-start mitigation — see the constant's docstring) and
-///    return a tight [`SHORT_PROMPT_MAX_FRAMES`] cap so the LM can't run
-///    away if EOS still doesn't fire.
-///
-/// We do **not** override `frames_after_eos` — sherpa-onnx's default of 3
-/// is what we want. An earlier version set it to 1 on long inputs, which
-/// clipped the leading audio of multi-clause sentences ("first 'yep' is
-/// just static" regression). Tests `prepare_prompt_never_lowers_frames_…`
-/// lock this in.
-///
-/// Returns `None` only if the input is empty after trimming — caller should
-/// skip synthesis in that case.
-pub(crate) fn prepare_pocket_prompt(input: &str) -> Option<PreparedPrompt> {
-    let trimmed = input.trim();
-    if trimmed.is_empty() {
-        return None;
-    }
-
-    // Collapse stray double-spaces / embedded newlines that may slip past
-    // `preprocess_for_tts` when sentences are spliced back together.
-    let mut cleaned = String::with_capacity(trimmed.len());
-    let mut last_was_space = false;
-    for ch in trimmed.chars() {
-        let is_ws = ch.is_whitespace();
-        if is_ws {
-            if !last_was_space {
-                cleaned.push(' ');
-            }
-            last_was_space = true;
-        } else {
-            cleaned.push(ch);
-            last_was_space = false;
-        }
-    }
-
-    // Capitalize first character. Uses `to_uppercase` (multi-codepoint safe).
-    let first = cleaned.chars().next().expect("cleaned non-empty above");
-    if first.is_lowercase() {
-        let upper: String = first.to_uppercase().collect();
-        let mut iter = cleaned.chars();
-        iter.next();
-        cleaned = upper + iter.as_str();
-    }
-
-    // Ensure terminal punctuation. Anything not in `.!?;:,` gets a period.
-    // The upstream Python only checks `isalnum` → period, but for our agent
-    // text we already may end in `!` `?` `.` etc. — treat any of those as OK.
-    let last = cleaned
-        .chars()
-        .next_back()
-        .expect("cleaned non-empty above");
-    if !matches!(last, '.' | '!' | '?' | ';' | ':' | ',') {
-        cleaned.push('.');
-    }
-
-    // Word count of the *cleaned but not padded* text — padding is whitespace
-    // only and would just lie to the threshold check below.
-    let word_count = cleaned.split_whitespace().count();
-
-    let (final_text, max_frames) = if word_count <= SHORT_PROMPT_WORD_THRESHOLD {
-        let mut padded = String::with_capacity(cleaned.len() + SHORT_PROMPT_PAD_SPACES);
-        for _ in 0..SHORT_PROMPT_PAD_SPACES {
-            padded.push(' ');
-        }
-        padded.push_str(&cleaned);
-        (padded, Some(SHORT_PROMPT_MAX_FRAMES))
-    } else {
-        // For everything ≥5 words, fall back to upstream defaults. Overriding
-        // these is what caused the "first 'yep' is static" regression — the
-        // upstream LM has been tuned for `frames_after_eos = 3` and
-        // `max_frames = 500`, and there's no clear win in second-guessing.
-        (cleaned, None)
-    };
-
-    Some(PreparedPrompt {
-        text: final_text,
-        max_frames,
-    })
-}
-
-/// Build the `GenerationConfig.extra` HashMap from a [`PreparedPrompt`].
-///
-/// Centralised so the regression test below can assert that we **never**
-/// emit a `frames_after_eos` override — the previous attempt to override
-/// that knob (setting it to 1 for ≥5-word inputs) clipped the leading
-/// audio of multi-clause sentences (the "first 'yep' is static" bug on
-/// 2026-05-18). The upstream sherpa-onnx default of 3 is what we want, and
-/// the right way to keep it is to not set it at all.
-fn build_generation_extra(prepared: &PreparedPrompt) -> Option<HashMap<String, serde_json::Value>> {
-    prepared.max_frames.map(|mf| {
-        let mut h: HashMap<String, serde_json::Value> = HashMap::with_capacity(1);
-        h.insert("max_frames".to_string(), serde_json::Value::from(mf));
-        h
-    })
-}
-
-impl PocketTts {
-    /// Synthesise `text` with the given reference voice.
-    ///
-    /// `_lang` and `_steps` are accepted for API compatibility with the
-    /// previous Kokoro engine. Pocket TTS infers language from the input text
-    /// directly and is a one-step consistency model. Returns an empty buffer
-    /// for whitespace-only input.
-    pub fn synth_chunk(
-        &self,
-        text: &str,
-        _lang: &str,
-        style: &VoiceStyle,
-        _steps: usize,
-    ) -> Result<Vec<f32>, String> {
-        // Mirror upstream pocket-tts prompt prep — without this short or
-        // unpunctuated inputs can cause the LM's EOS logit to never trip,
-        // producing up to 40 s of "monster breathing" garbage on the first
-        // utterance. See `prepare_pocket_prompt` for the full recipe.
-        let prepared = match prepare_pocket_prompt(text) {
-            Some(p) => p,
-            None => return Ok(Vec::new()),
-        };
-
-        // Per-call generation hints sherpa-onnx forwards to
-        // `offline-tts-pocket-impl.h`. We only override `max_frames`, and
-        // only for short padded prompts where we have a tight expectation
-        // on output length — that bounds the original runaway without
-        // disturbing the rest of the LM sampling envelope. See
-        // `prepare_pocket_prompt` docs for the regression history.
-        let extra = build_generation_extra(&prepared);
-
-        let cfg = GenerationConfig {
-            num_steps: SYNTH_NUM_STEPS,
-            silence_scale: SYNTH_SILENCE_SCALE,
-            reference_audio: Some(style.samples.clone()),
-            reference_sample_rate: style.sample_rate,
-            extra,
-            // `speed` stays at its default: the Pocket impl never reads it
-            // (see the engine-contract note in the module docs).
-            ..Default::default()
-        };
-
-        // No progress callback — synthesis is fast enough that returning the
-        // whole buffer at once keeps the lookahead pipelining in `tts.rs`
-        // simple. `None::<fn(...) -> bool>` pins the callback type for the
-        // `generate_with_config` generic parameter.
-        let audio = self
-            .inner
-            .generate_with_config(&prepared.text, &cfg, None::<fn(&[f32], f32) -> bool>)
-            .ok_or_else(|| {
-                format!(
-                    "Pocket TTS synthesis failed for text ({} chars)",
-                    prepared.text.len()
-                )
-            })?;
-
-        let sample_rate = audio.sample_rate();
-        if sample_rate != SAMPLE_RATE as i32 {
-            eprintln!(
-                "buzz-desktop: Pocket TTS returned unexpected sample rate {sample_rate}Hz \
-                 (expected {SAMPLE_RATE}Hz); playback speed may be wrong"
-            );
-        }
-
-        Ok(audio.samples().to_vec())
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    // ── prepare_pocket_prompt ────────────────────────────────────────────────
-
-    #[test]
-    fn prepare_prompt_returns_none_for_empty_input() {
-        assert!(prepare_pocket_prompt("").is_none());
-        assert!(prepare_pocket_prompt("   ").is_none());
-        assert!(prepare_pocket_prompt("\n\t  ").is_none());
-    }
-
-    /// Helper: the exact leading sequence prepended to every short prompt —
-    /// 8 spaces of padding (upstream's cold-start mitigation).
-    /// Centralising this keeps the assertions readable.
-    fn short_prefix() -> String {
-        " ".repeat(SHORT_PROMPT_PAD_SPACES)
-    }
-
-    #[test]
-    fn prepare_prompt_pads_and_capitalizes_one_word() {
-        // The "yep" case Tyler hit in production — bare lowercase one-word
-        // utterance with no punctuation. Must be padded with the short-prompt
-        // space pad, capitalized, terminated, with a tight `max_frames` cap
-        // to bound runaway gen.
-        let out = prepare_pocket_prompt("yep").expect("non-empty");
-        assert_eq!(out.text, format!("{}Yep.", short_prefix()));
-        assert_eq!(out.max_frames, Some(SHORT_PROMPT_MAX_FRAMES));
-        const {
-            assert!(
-                SHORT_PROMPT_MAX_FRAMES < SHERPA_ONNX_MAX_FRAMES_DEFAULT,
-                "short cap must be tighter than the upstream default"
-            );
-        }
-    }
-
-    #[test]
-    fn prepare_prompt_preserves_existing_punctuation() {
-        let out = prepare_pocket_prompt("yes!").expect("non-empty");
-        assert_eq!(out.text, format!("{}Yes!", short_prefix())); // exclamation kept
-        let out = prepare_pocket_prompt("really?").expect("non-empty");
-        assert_eq!(out.text, format!("{}Really?", short_prefix()));
-    }
-
-    #[test]
-    fn prepare_prompt_threshold_is_inclusive_at_four_words() {
-        // 4 words = short (padded + tight max_frames); 5 words = long
-        // (no padding, no overrides — upstream defaults stand).
-        let four = prepare_pocket_prompt("one two three four").expect("non-empty");
-        assert_eq!(
-            four.text,
-            format!("{}One two three four.", short_prefix()),
-            "four-word input should get exactly the space pad"
-        );
-        assert_eq!(four.max_frames, Some(SHORT_PROMPT_MAX_FRAMES));
-
-        let five = prepare_pocket_prompt("one two three four five").expect("non-empty");
-        assert!(
-            !five.text.starts_with(' '),
-            "five-word input should NOT be padded"
-        );
-        assert_eq!(
-            five.max_frames, None,
-            "long inputs must leave sherpa-onnx's max_frames default in place"
-        );
-    }
-
-    #[test]
-    fn prepare_prompt_does_not_pad_long_text() {
-        let long = "This is a longer sentence that the model should handle just fine.";
-        let out = prepare_pocket_prompt(long).expect("non-empty");
-        assert!(!out.text.starts_with(' '));
-        assert_eq!(out.max_frames, None);
-        assert!(out.text.ends_with('.'));
-    }
-
-    #[test]
-    fn prepare_prompt_collapses_whitespace() {
-        let out = prepare_pocket_prompt("Hello    world\n\nfriend").expect("non-empty");
-        // 3 words → short → padded. Interior whitespace collapsed.
-        assert_eq!(out.text, format!("{}Hello world friend.", short_prefix()));
-    }
-
-    #[test]
-    fn prepare_prompt_does_not_double_capitalize_already_uppercase() {
-        let out = prepare_pocket_prompt("HELLO there").expect("non-empty");
-        assert_eq!(out.text, format!("{}HELLO there.", short_prefix()));
-    }
-
-    #[test]
-    fn prepare_prompt_handles_non_ascii_first_letter() {
-        // Cyrillic lowercase 'д' → uppercase 'Д'. Must not panic / produce
-        // mojibake.
-        let out = prepare_pocket_prompt("дa").expect("non-empty");
-        assert!(out.text.contains("Дa."));
-    }
-
-    /// REGRESSION GUARD: short prompts must receive *only* whitespace
-    /// padding — no sacrificial text. A previous revision prepended a
-    /// `". . "` cold-start absorber and trimmed the rendered audio back out
-    /// with an amplitude threshold that could eat soft word onsets. If
-    /// non-whitespace ever reappears in the pad, the synth output will
-    /// contain audio for text the user never wrote.
-    #[test]
-    fn prepare_prompt_pad_is_whitespace_only() {
-        let out = prepare_pocket_prompt("I'm happy.").expect("non-empty");
-        let pad_len = out.text.len() - "I'm happy.".len();
-        assert!(
-            out.text[..pad_len].chars().all(|c| c == ' '),
-            "short-prompt pad must be spaces only, got {:?}",
-            &out.text[..pad_len]
-        );
-        assert_eq!(out.text, format!("{}I'm happy.", short_prefix()));
-    }
-
-    // ── build_generation_extra ───────────────────────────────────────────────
-    //
-    // These tests pin down a behaviour we've now regressed twice on:
-    //   1) Not padding/punctuating short inputs → 40 s of "monster breathing"
-    //      (pre-773a2a1).
-    //   2) Setting `frames_after_eos = 1` on long inputs → clipped leading
-    //      audio of multi-clause sentences, e.g. "Yep, I can hear you. …"
-    //      came out as a static burst (the 773a2a1 regression Tyler hit on
-    //      2026-05-18 ~14:30 UTC).
-    //
-    // The contract we enforce going forward: we **only** override
-    // `max_frames`, and only for ≤4-word inputs. Every other knob is left
-    // at sherpa-onnx's documented default (notably `frames_after_eos = 3`).
-
-    #[test]
-    fn build_extra_short_prompt_sets_only_max_frames() {
-        let prepared = prepare_pocket_prompt("yep").expect("non-empty");
-        let extra = build_generation_extra(&prepared).expect("short prompts get extra");
-        // Exactly one key — `max_frames` — and nothing else.
-        assert_eq!(extra.len(), 1, "extra has unexpected keys: {extra:?}");
-        assert_eq!(
-            extra.get("max_frames"),
-            Some(&serde_json::Value::from(SHORT_PROMPT_MAX_FRAMES))
-        );
-        assert!(
-            !extra.contains_key("frames_after_eos"),
-            "frames_after_eos must never be set — upstream default of {SHERPA_ONNX_FRAMES_AFTER_EOS_DEFAULT} is what we want"
-        );
-    }
-
-    #[test]
-    fn build_extra_long_prompt_is_none() {
-        // ≥5 words: no extras at all. This is the key fix for the "first
-        // 'yep' in 'Yep, I can hear you. …' is static" regression — we
-        // were previously forcing `frames_after_eos = 1` on this path.
-        let prepared = prepare_pocket_prompt("Yep, I can hear you.").expect("non-empty");
-        assert_eq!(
-            build_generation_extra(&prepared),
-            None,
-            "long prompts must not override any LM knob"
-        );
-    }
-
-    #[test]
-    fn build_extra_never_lowers_frames_after_eos_for_any_word_count() {
-        // Sweep a range of prompt lengths and assert the `extra` map (when
-        // present) never carries a `frames_after_eos` override that's lower
-        // than the upstream sherpa-onnx default. Implemented as a structural
-        // check — we just never set the key — but worth a property test in
-        // case someone reintroduces the override in the future.
-        let prompts: &[&str] = &[
-            "hi",
-            "hi there",
-            "yes please",
-            "one two three four",
-            "one two three four five",
-            "a slightly longer reply, hopefully fine",
-            "This is a multi-clause sentence. It has two parts.",
-            "really really really really really long prompt with lots of words just to be sure",
-        ];
-        for &p in prompts {
-            let prepared = prepare_pocket_prompt(p).expect("non-empty");
-            if let Some(extra) = build_generation_extra(&prepared) {
-                if let Some(v) = extra.get("frames_after_eos") {
-                    let n = v.as_i64().expect("frames_after_eos should be int");
-                    assert!(
-                        n >= SHERPA_ONNX_FRAMES_AFTER_EOS_DEFAULT as i64,
-                        "prompt {p:?} set frames_after_eos={n}, below upstream default of {SHERPA_ONNX_FRAMES_AFTER_EOS_DEFAULT}"
-                    );
-                }
-            }
-        }
-    }
-
-    #[test]
-    fn short_prompt_max_frames_is_below_upstream_default() {
-        // Sanity: the override only ever *lowers* the cap, never raises it.
-        const {
-            assert!(SHORT_PROMPT_MAX_FRAMES < SHERPA_ONNX_MAX_FRAMES_DEFAULT);
-        }
-        // …and is still large enough for a one-to-four-word reply. At Mimi's
-        // 12.5 Hz frame rate, 100 frames = 8 s, which is roomy.
-        const {
-            assert!(SHORT_PROMPT_MAX_FRAMES >= 50, "would risk truncation");
-        }
-    }
-}
+pub use buzz_voice_pkg::pocket::*;
+pub(crate) use buzz_voice_pkg::{
+    april_model_info, PocketModelArtifact, APRIL_BUNDLE_ID, APRIL_MODEL_ID, APRIL_MODEL_REVISION,
+};
diff --git a/desktop/src-tauri/src/huddle/relay_api.rs b/desktop/src-tauri/src/huddle/relay_api.rs
index eb3fea92d5..3f2aa76a56 100644
--- a/desktop/src-tauri/src/huddle/relay_api.rs
+++ b/desktop/src-tauri/src/huddle/relay_api.rs
@@ -164,7 +164,8 @@ pub(crate) async fn connect_audio_relay(
     let cancel_clone = cancel.clone();
     let (pcm_tx, pcm_rx) = tokio::sync::mpsc::channel::<Vec<u8>>(50);
     let output_device_name = state
-        .audio_output_device
+        .huddle_audio
+        .output_device
         .lock()
         .unwrap_or_else(|e| e.into_inner())
         .clone();
diff --git a/desktop/src-tauri/src/huddle/state.rs b/desktop/src-tauri/src/huddle/state.rs
index 876c2d688b..37eb3533f6 100644
--- a/desktop/src-tauri/src/huddle/state.rs
+++ b/desktop/src-tauri/src/huddle/state.rs
@@ -5,7 +5,7 @@
 
 use serde::{Deserialize, Serialize};
 use std::sync::{
-    atomic::{AtomicBool, AtomicU64},
+    atomic::{AtomicBool, AtomicU64, Ordering},
     Arc, Mutex,
 };
 
@@ -80,6 +80,15 @@ pub struct HuddleState {
     pub tts_enabled: bool,
     /// Whether STT transcript posting is enabled for this huddle.
     pub transcription_enabled: bool,
+    /// Whether the user has explicitly used the transcription control in this
+    /// huddle. Agent presence may auto-enable transcription only while this is
+    /// false, so membership refreshes never undo an explicit user choice.
+    ///
+    /// This is backend-only session state: keeping it in `HuddleState` makes it
+    /// survive frontend remounts and audio reconnects, while huddle teardown
+    /// resets it for the next session.
+    #[serde(skip)]
+    pub transcription_user_controlled: bool,
     /// Shared flag: true while TTS is playing audio.
     /// Shared with the STT pipeline for barge-in / echo gating.
     #[serde(skip)]
@@ -103,6 +112,10 @@ pub struct HuddleState {
     /// Used to throttle the refresh in check_pipeline_hotstart to every 15 s.
     #[serde(skip)]
     pub last_agent_refresh: Option<std::time::Instant>,
+    /// Monotonic identity for a local huddle lifetime. Unlike transcript
+    /// generation, this changes only when a new start/join attempt begins.
+    #[serde(skip)]
+    pub huddle_generation: u64,
     /// Session generation — incremented on every teardown. The transcription
     /// task captures this at spawn time and checks before each POST. If the
     /// generation has changed, the task silently drops the transcript.
@@ -157,11 +170,13 @@ impl Clone for HuddleState {
             is_creator: self.is_creator,
             tts_enabled: self.tts_enabled,
             transcription_enabled: self.transcription_enabled,
+            transcription_user_controlled: self.transcription_user_controlled,
             tts_active: Arc::clone(&self.tts_active),
             tts_cancel: Arc::clone(&self.tts_cancel),
             tts_starting: Arc::clone(&self.tts_starting),
             stt_starting: Arc::clone(&self.stt_starting),
             last_agent_refresh: self.last_agent_refresh,
+            huddle_generation: self.huddle_generation,
             session_generation: Arc::clone(&self.session_generation),
             voice_input_mode: self.voice_input_mode.clone(),
             ptt_active: Arc::clone(&self.ptt_active),
@@ -184,11 +199,13 @@ impl Default for HuddleState {
             is_creator: false,
             tts_enabled: true,
             transcription_enabled: false,
+            transcription_user_controlled: false,
             tts_active: Arc::new(AtomicBool::new(false)),
             tts_cancel: Arc::new(AtomicBool::new(false)),
             tts_starting: Arc::new(AtomicBool::new(false)),
             stt_starting: Arc::new(AtomicBool::new(false)),
             last_agent_refresh: None,
+            huddle_generation: 0,
             session_generation: Arc::new(AtomicU64::new(0)),
             voice_input_mode: VoiceInputMode::default(),
             ptt_active: Arc::new(AtomicBool::new(false)),
@@ -197,13 +214,247 @@ impl Default for HuddleState {
 }
 
 impl HuddleState {
+    /// Begin a new local huddle lifetime and return its identity.
+    pub(crate) fn begin_huddle_lifetime(&mut self) -> u64 {
+        self.huddle_generation = self.huddle_generation.wrapping_add(1);
+        self.huddle_generation
+    }
+
+    pub(crate) fn owns_huddle_lifetime(&self, huddle_generation: u64, phase: HuddlePhase) -> bool {
+        self.huddle_generation == huddle_generation && self.phase == phase
+    }
+
+    /// Whether an async result still belongs to the active huddle that
+    /// initiated it. The channel id is the huddle-session identity; transcript
+    /// generation changes within the same huddle must not invalidate it.
+    pub(crate) fn is_current_huddle(
+        &self,
+        ephemeral_channel_id: &str,
+        huddle_generation: u64,
+    ) -> bool {
+        matches!(self.phase, HuddlePhase::Connected | HuddlePhase::Active)
+            && self.ephemeral_channel_id.as_deref() == Some(ephemeral_channel_id)
+            && self.huddle_generation == huddle_generation
+    }
+
+    /// Whether an STT construction still belongs to the current transcript
+    /// generation within the active huddle.
+    pub(crate) fn is_current_transcription_generation(
+        &self,
+        ephemeral_channel_id: &str,
+        huddle_generation: u64,
+        session_generation: u64,
+    ) -> bool {
+        self.is_current_huddle(ephemeral_channel_id, huddle_generation)
+            && self.session_generation.load(Ordering::Acquire) == session_generation
+    }
+
+    /// Invalidate in-flight transcription work and give the next constructor a
+    /// fresh sentinel that stale constructors cannot clear.
+    pub(crate) fn invalidate_transcription_pipeline(&mut self) {
+        self.session_generation.fetch_add(1, Ordering::Release);
+        self.stt_starting = Arc::new(AtomicBool::new(false));
+    }
+
+    /// Record an explicit transcription choice made through the existing user
+    /// control. Later agent membership refreshes must preserve this choice.
+    pub(crate) fn set_transcription_enabled_by_user(&mut self, enabled: bool) {
+        self.transcription_enabled = enabled;
+        self.transcription_user_controlled = true;
+    }
+
+    /// Enable transcription when an agent is present and the user has not
+    /// explicitly chosen a transcription state for this huddle.
+    ///
+    /// Returns true only for the transition from disabled to enabled, allowing
+    /// callers to start models/pipelines and emit state exactly once. Removing
+    /// the last agent deliberately leaves the current state unchanged.
+    pub(crate) fn maybe_auto_enable_transcription_for_agents(&mut self) -> bool {
+        let has_agent = !self
+            .agent_pubkeys
+            .lock()
+            .unwrap_or_else(|e| e.into_inner())
+            .is_empty();
+        if has_agent && !self.transcription_user_controlled && !self.transcription_enabled {
+            self.transcription_enabled = true;
+            return true;
+        }
+        false
+    }
+
     /// Reset to default state while preserving the session generation counter.
     /// Used by start_huddle rollback, join_huddle rollback, and teardown_huddle
     /// to invalidate in-flight transcription tasks without losing the generation.
     pub(crate) fn reset_preserving_generation(&mut self) {
         let gen = Arc::clone(&self.session_generation);
+        let huddle_generation = self.huddle_generation;
+        let tts_enabled = self.tts_enabled;
         *self = Self::default();
         self.session_generation = gen;
+        self.huddle_generation = huddle_generation;
+        self.tts_enabled = tts_enabled;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::atomic::Ordering;
+
+    use super::HuddleState;
+
+    fn set_agents(state: &HuddleState, agents: &[&str]) {
+        *state
+            .agent_pubkeys
+            .lock()
+            .unwrap_or_else(|error| error.into_inner()) =
+            agents.iter().map(|agent| (*agent).to_owned()).collect();
+    }
+
+    #[test]
+    fn first_agent_auto_enables_transcription_once() {
+        let mut state = HuddleState::default();
+        set_agents(&state, &["agent"]);
+
+        assert!(state.maybe_auto_enable_transcription_for_agents());
+        assert!(state.transcription_enabled);
+        assert!(!state.maybe_auto_enable_transcription_for_agents());
+    }
+
+    #[test]
+    fn explicit_user_disable_is_not_undone_by_agent_presence() {
+        let mut state = HuddleState::default();
+        set_agents(&state, &["agent"]);
+        assert!(state.maybe_auto_enable_transcription_for_agents());
+
+        state.set_transcription_enabled_by_user(false);
+
+        assert!(!state.maybe_auto_enable_transcription_for_agents());
+        assert!(!state.transcription_enabled);
+    }
+
+    #[test]
+    fn last_agent_leaving_preserves_current_transcription_state() {
+        let mut state = HuddleState::default();
+        set_agents(&state, &["agent"]);
+        assert!(state.maybe_auto_enable_transcription_for_agents());
+
+        set_agents(&state, &[]);
+
+        assert!(!state.maybe_auto_enable_transcription_for_agents());
+        assert!(state.transcription_enabled);
+    }
+
+    #[test]
+    fn clone_preserves_user_control_across_frontend_state_reads() {
+        let mut state = HuddleState::default();
+        state.set_transcription_enabled_by_user(false);
+
+        let mut clone = state.clone();
+        set_agents(&clone, &["agent"]);
+
+        assert!(clone.transcription_user_controlled);
+        assert!(!clone.maybe_auto_enable_transcription_for_agents());
+    }
+
+    #[test]
+    fn stale_huddle_identity_is_rejected_after_replacement() {
+        let mut state = HuddleState {
+            phase: super::HuddlePhase::Active,
+            ephemeral_channel_id: Some("huddle-a".to_owned()),
+            ..HuddleState::default()
+        };
+        let huddle_generation = state.begin_huddle_lifetime();
+        let generation = state.session_generation.load(Ordering::Acquire);
+        assert!(state.is_current_huddle("huddle-a", huddle_generation));
+        assert!(state.is_current_transcription_generation(
+            "huddle-a",
+            huddle_generation,
+            generation
+        ));
+
+        state.session_generation.fetch_add(1, Ordering::Release);
+        assert!(state.is_current_huddle("huddle-a", huddle_generation));
+        assert!(!state.is_current_transcription_generation(
+            "huddle-a",
+            huddle_generation,
+            generation
+        ));
+
+        state.ephemeral_channel_id = Some("huddle-b".to_owned());
+
+        assert!(!state.is_current_huddle("huddle-a", huddle_generation));
+    }
+
+    #[test]
+    fn same_channel_rejoin_gets_a_new_huddle_lifetime() {
+        let mut state = HuddleState {
+            phase: super::HuddlePhase::Active,
+            ephemeral_channel_id: Some("huddle".to_owned()),
+            ..HuddleState::default()
+        };
+        let first_generation = state.begin_huddle_lifetime();
+        state.reset_preserving_generation();
+        state.phase = super::HuddlePhase::Active;
+        state.ephemeral_channel_id = Some("huddle".to_owned());
+        let second_generation = state.begin_huddle_lifetime();
+
+        assert_ne!(first_generation, second_generation);
+        assert!(!state.is_current_huddle("huddle", first_generation));
+        assert!(state.is_current_huddle("huddle", second_generation));
+    }
+
+    #[test]
+    fn superseded_create_cannot_commit_or_reset_replacement_lifetime() {
+        let mut state = HuddleState::default();
+        let first_generation = state.begin_huddle_lifetime();
+        state.phase = super::HuddlePhase::Creating;
+        assert!(state.owns_huddle_lifetime(first_generation, super::HuddlePhase::Creating));
+
+        state.reset_preserving_generation();
+        let replacement_generation = state.begin_huddle_lifetime();
+        state.phase = super::HuddlePhase::Creating;
+
+        assert!(!state.owns_huddle_lifetime(first_generation, super::HuddlePhase::Creating));
+        assert!(state.owns_huddle_lifetime(replacement_generation, super::HuddlePhase::Creating));
+    }
+
+    #[test]
+    fn superseded_join_cannot_commit_replacement_lifetime() {
+        let mut state = HuddleState::default();
+        let first_generation = state.begin_huddle_lifetime();
+        state.phase = super::HuddlePhase::Connecting;
+
+        state.reset_preserving_generation();
+        let replacement_generation = state.begin_huddle_lifetime();
+        state.phase = super::HuddlePhase::Connecting;
+
+        assert!(!state.owns_huddle_lifetime(first_generation, super::HuddlePhase::Connecting));
+        assert!(state.owns_huddle_lifetime(replacement_generation, super::HuddlePhase::Connecting));
+    }
+
+    #[test]
+    fn teardown_preserves_installation_global_tts_preference() {
+        let mut state = HuddleState {
+            tts_enabled: false,
+            phase: super::HuddlePhase::Active,
+            ..HuddleState::default()
+        };
+        state.reset_preserving_generation();
+        assert!(!state.tts_enabled);
+        assert_eq!(state.phase, super::HuddlePhase::Idle);
+    }
+
+    #[test]
+    fn stale_constructor_cannot_clear_replacement_sentinel() {
+        let mut state = HuddleState::default();
+        let stale_sentinel = std::sync::Arc::clone(&state.stt_starting);
+        stale_sentinel.store(true, Ordering::Release);
+
+        state.invalidate_transcription_pipeline();
+        state.stt_starting.store(true, Ordering::Release);
+        stale_sentinel.store(false, Ordering::Release);
+
+        assert!(state.stt_starting.load(Ordering::Acquire));
     }
 }
 
diff --git a/desktop/src-tauri/src/huddle/transcription.rs b/desktop/src-tauri/src/huddle/transcription.rs
index 0d752c1de7..5962f57cf4 100644
--- a/desktop/src-tauri/src/huddle/transcription.rs
+++ b/desktop/src-tauri/src/huddle/transcription.rs
@@ -1,5 +1,3 @@
-use std::sync::atomic::Ordering;
-
 use tauri::State;
 
 use crate::app_state::AppState;
@@ -15,10 +13,12 @@ use super::{models, pipeline::maybe_start_stt_pipeline};
 pub async fn start_stt_pipeline(state: State<'_, AppState>) -> Result<(), String> {
     let ephemeral_channel_id = {
         let mut hs = state.huddle()?;
-        hs.transcription_enabled = true;
-        hs.ephemeral_channel_id
+        let ephemeral_channel_id = hs
+            .ephemeral_channel_id
             .clone()
-            .ok_or("no active huddle — start or join a huddle first")?
+            .ok_or("no active huddle — start or join a huddle first")?;
+        hs.set_transcription_enabled_by_user(true);
+        ephemeral_channel_id
     };
 
     match maybe_start_stt_pipeline(&state, &ephemeral_channel_id).await {
@@ -41,14 +41,17 @@ pub async fn set_huddle_transcription_enabled(
 ) -> Result<(), String> {
     let (ephemeral_channel_id, old_stt) = {
         let mut hs = state.huddle()?;
-        hs.transcription_enabled = enabled;
+        let ephemeral_channel_id = hs
+            .ephemeral_channel_id
+            .clone()
+            .ok_or("no active huddle — start or join a huddle first")?;
+        hs.set_transcription_enabled_by_user(enabled);
 
         if enabled {
-            (hs.ephemeral_channel_id.clone(), None)
+            (ephemeral_channel_id, None)
         } else {
-            hs.session_generation.fetch_add(1, Ordering::Release);
-            hs.stt_starting.store(false, Ordering::Release);
-            (hs.ephemeral_channel_id.clone(), hs.stt_pipeline.take())
+            hs.invalidate_transcription_pipeline();
+            (ephemeral_channel_id, hs.stt_pipeline.take())
         }
     };
 
@@ -58,12 +61,10 @@ pub async fn set_huddle_transcription_enabled(
     drop(old_stt);
 
     if enabled {
-        let eph_id =
-            ephemeral_channel_id.ok_or("no active huddle — start or join a huddle first")?;
         if let Some(manager) = models::global_model_manager() {
             manager.start_stt_download(state.http_client.clone());
         }
-        if let Err(e) = maybe_start_stt_pipeline(&state, &eph_id).await {
+        if let Err(e) = maybe_start_stt_pipeline(&state, &ephemeral_channel_id).await {
             eprintln!("buzz-desktop: STT transcript start failed: {e}");
         }
     }
diff --git a/desktop/src-tauri/src/huddle/tts.rs b/desktop/src-tauri/src/huddle/tts.rs
index 63a435cd8e..c03589f9fe 100644
--- a/desktop/src-tauri/src/huddle/tts.rs
+++ b/desktop/src-tauri/src/huddle/tts.rs
@@ -35,10 +35,11 @@
 //! can gate microphone input while the agent is speaking.
 
 use std::{
+    collections::VecDeque,
     num::NonZero,
     path::PathBuf,
     sync::{
-        atomic::{AtomicBool, Ordering},
+        atomic::{AtomicBool, AtomicU64, Ordering},
         mpsc::{self, SyncSender},
         Arc, Mutex, MutexGuard, PoisonError,
     },
@@ -46,9 +47,21 @@ use std::{
     time::Duration,
 };
 
-use super::pocket::{load_text_to_speech, load_voice_style, SAMPLE_RATE, VOICE_FILE_EXT};
+use super::pocket::{
+    load_text_to_speech, load_voice_style, DEFAULT_VOICE, SAMPLE_RATE, VOICE_FILE_EXT,
+};
 use super::preprocessing::{preprocess_for_tts, split_sentences};
 
+#[path = "tts_voice_transition.rs"]
+mod voice_transition;
+use voice_transition::*;
+#[path = "tts_startup.rs"]
+mod startup;
+use startup::await_worker_startup;
+#[path = "tts_audio.rs"]
+mod audio;
+use audio::*;
+
 // ── Constants ─────────────────────────────────────────────────────────────────
 
 /// Maximum number of queued text items.
@@ -56,15 +69,15 @@ use super::preprocessing::{preprocess_for_tts, split_sentences};
 /// TTS can play it. Excess items are dropped with a warning.
 const TEXT_QUEUE_DEPTH: usize = 8;
 
-/// How long the worker waits on the text channel before checking the shutdown flag.
+/// How long the worker waits before checking the shutdown flag.
 const RECV_TIMEOUT: Duration = Duration::from_millis(100);
-
 /// Poll interval of the barge-in monitor thread. Bounds flag-to-silence
 /// latency: a cancel is noticed within one tick, and rodio's internal
 /// `periodic_access` wrapper stops the in-flight source within a further
 /// ~5 ms — so playing audio dies ~15 ms after the flag is set, even while
 /// the worker is blocked inside `synth_chunk`.
 const MONITOR_TICK: Duration = Duration::from_millis(10);
+const AUDIO_PRIME_TIMEOUT: Duration = Duration::from_secs(2);
 
 /// Pocket TTS is a one-step consistency model, not diffusion. Kept for API compat.
 const SYNTH_STEPS: usize = 1;
@@ -73,9 +86,8 @@ const SYNTH_STEPS: usize = 1;
 ///
 /// Applied only at the *end* of each synthesised sentence to eliminate the
 /// click that would otherwise occur when a non-zero waveform terminates
-/// abruptly. **No fade-in is applied** — see `apply_fade_out` for the
-/// rationale and `examples/pocket_onset_probe.rs` for the measurement that
-/// motivated removing the leading fade.
+/// abruptly. **No fade-in is applied** — see `apply_fade_out` for why preserving
+/// the leading waveform is important.
 const FADE_OUT_SAMPLES: usize = (SAMPLE_RATE as f64 * 0.008) as usize;
 
 /// Length of the zero-sample cushion prepended before each synthesized
@@ -101,19 +113,17 @@ const SENTENCE_LEAD_IN_SAMPLES: usize = (SAMPLE_RATE as f64 * 0.020) as usize;
 /// names chunk stitching as the reliability lever). Our previous
 /// sentence-per-call path created ~2–4× more seams than upstream.
 ///
-/// We don't ship the SentencePiece tokenizer, so 50 tokens is approximated
-/// with a character budget. The bundled 4k-entry vocab averages ~4 chars per
-/// token, but usage-weighted English text leans on short common tokens, so
-/// the effective ratio is ~2–4 chars/token and 200 chars ≈ 60–100 tokens —
-/// modestly above upstream's 50, deliberately: erring large means fewer
-/// seams, and even ~100 tokens is far below the model's 500-LM-step (~40 s)
-/// ceiling. Do not shrink this budget to chase an exact 50-token match.
+/// This character budget performs only coarse sentence packing. The April
+/// engine applies its SentencePiece tokenizer afterward and refines every
+/// result at the bundle's exact 50-token boundary.
 const MAX_CHUNK_CHARS: usize = 200;
 
 /// Silence inserted between sentences by the TTS pipeline (seconds).
 /// Injected as a silent buffer between each synthesized sentence chunk.
 const INTER_SENTENCE_SILENCE: f32 = 0.1;
 
+type WorkerControlState = (Arc<AtomicBool>, Arc<AtomicBool>, WorkerCancelSignals);
+
 // ── Public pipeline handle ────────────────────────────────────────────────────
 
 /// Handle to the running TTS pipeline.
@@ -122,7 +132,7 @@ const INTER_SENTENCE_SILENCE: f32 = 0.1;
 #[derive(Debug)]
 pub struct TtsPipeline {
     /// Send preprocessed text into the pipeline.
-    text_tx: SyncSender<String>,
+    text_tx: SyncSender<QueuedText>,
     /// `true` while the agent is speaking. Shared with the STT pipeline for gating.
     #[allow(dead_code)]
     pub tts_active: Arc<AtomicBool>,
@@ -132,38 +142,25 @@ pub struct TtsPipeline {
     /// Kept alive here so the Arc isn't dropped — the worker holds a clone.
     #[allow(dead_code)]
     cancel: Arc<AtomicBool>,
-    /// Voice name (e.g. "reference_sample"). Stored for future voice-switching support.
-    #[allow(dead_code)]
-    voice: String,
+    /// Internal cancellation used only for voice changes. Kept separate so a
+    /// concurrent human barge-in always clears every queued message.
+    voice_cancel: Arc<AtomicBool>,
+    /// Selected manifest voice. The worker reloads only the lightweight style
+    /// when this changes; the warmed Pocket engine and audio player stay alive.
+    voice: Arc<Mutex<String>>,
+    /// Tags messages so a voice change drops only pre-change queue entries.
+    voice_generation: Arc<AtomicU64>,
+    /// Completed after the worker drains pre-change text and installs the new style.
+    voice_change_ack: VoiceChangeAck,
     /// Worker thread handle — taken on drop to join cleanly.
     thread: Option<thread::JoinHandle<()>>,
 }
 
 impl TtsPipeline {
-    /// Spawn the TTS pipeline thread using the default voice.
-    ///
-    /// `model_dir` must contain the Pocket TTS files declared by `huddle::models`
-    /// (the five ONNX sessions, the two JSON tables, and `<voice>.wav`).
-    ///
-    /// `tts_active` is set to `true` while audio is playing and `false` when idle.
-    /// Pass the same `Arc` to the STT pipeline to gate microphone input.
+    /// Spawn the TTS pipeline thread with a manifest-backed voice name.
     ///
-    /// `cancel` is the shared barge-in flag from `HuddleState.tts_cancel`. Pass the
-    /// same `Arc` to the STT pipeline so both sides reference the same flag for the
-    /// entire huddle session — no stale references after pipeline restarts.
-    pub fn new(
-        model_dir: PathBuf,
-        tts_active: Arc<AtomicBool>,
-        cancel: Arc<AtomicBool>,
-        output_device: Option<String>,
-    ) -> Result<Self, String> {
-        use super::pocket::DEFAULT_VOICE;
-        Self::new_with_voice(model_dir, tts_active, cancel, DEFAULT_VOICE, output_device)
-    }
-
-    /// Spawn the TTS pipeline thread with a specific voice name. Today only the
-    /// bundled default voice (see `pocket::DEFAULT_VOICE`) is shipped; other
-    /// names will surface a clear error from `load_voice_style`.
+    /// `cancel` is shared with STT for barge-in. The same handle survives voice
+    /// changes so the warmed Pocket engine is retained.
     pub fn new_with_voice(
         model_dir: PathBuf,
         tts_active: Arc<AtomicBool>,
@@ -171,37 +168,56 @@ impl TtsPipeline {
         voice: &str,
         output_device: Option<String>,
     ) -> Result<Self, String> {
-        let (text_tx, text_rx) = mpsc::sync_channel::<String>(TEXT_QUEUE_DEPTH);
+        let (text_tx, text_rx) = mpsc::sync_channel::<QueuedText>(TEXT_QUEUE_DEPTH);
         let shutdown = Arc::new(AtomicBool::new(false));
         // cancel is passed in from HuddleState.tts_cancel — shared with STT for barge-in.
 
         let shutdown_worker = Arc::clone(&shutdown);
         let cancel_worker = Arc::clone(&cancel);
+        let voice_cancel = Arc::new(AtomicBool::new(false));
+        let worker_voice_cancel = Arc::clone(&voice_cancel);
         let tts_active_worker = Arc::clone(&tts_active);
-        let voice_name = voice.to_string();
+        let voice = Arc::new(Mutex::new(voice.to_string()));
+        let voice_worker = Arc::clone(&voice);
+        let voice_generation = Arc::new(AtomicU64::new(1));
+        let worker_voice_generation = Arc::clone(&voice_generation);
+        let voice_change_ack = Arc::new(Mutex::new(None));
+        let worker_voice_change_ack = Arc::clone(&voice_change_ack);
         let model_dir_worker = model_dir.clone();
+        let (startup_tx, startup_rx) = mpsc::sync_channel(1);
 
         let handle = thread::Builder::new()
             .name("tts-worker".into())
             .spawn(move || {
                 tts_worker(
                     model_dir_worker,
-                    voice_name,
+                    (
+                        voice_worker,
+                        worker_voice_generation,
+                        worker_voice_change_ack,
+                    ),
                     text_rx,
-                    tts_active_worker,
-                    shutdown_worker,
-                    cancel_worker,
+                    (
+                        tts_active_worker,
+                        shutdown_worker,
+                        (cancel_worker, worker_voice_cancel),
+                    ),
                     output_device,
+                    startup_tx,
                 )
             })
             .map_err(|e| format!("failed to spawn tts-worker thread: {e}"))?;
+        let handle = await_worker_startup(handle, startup_rx)?;
 
         Ok(Self {
             text_tx,
             tts_active,
             shutdown,
             cancel,
-            voice: voice.to_string(),
+            voice_cancel,
+            voice,
+            voice_generation,
+            voice_change_ack,
             thread: Some(handle),
         })
     }
@@ -211,14 +227,59 @@ impl TtsPipeline {
     /// Non-blocking. Returns `Err` if the queue is full (bounded at
     /// `TEXT_QUEUE_DEPTH`) — caller may log and discard.
     pub fn speak(&self, text: String) -> Result<(), String> {
-        self.text_tx.try_send(text).map_err(|e| {
-            eprintln!("buzz-desktop: TTS queue saturated, dropping message: {e}");
-            format!("TTS queue full, dropping: {e}")
-        })
+        self.text_tx
+            .try_send(QueuedText {
+                generation: self.voice_generation.load(Ordering::Acquire),
+                route_id: 0,
+                text,
+            })
+            .map_err(|e| {
+                eprintln!("buzz-desktop: TTS queue saturated, dropping message: {e}");
+                format!("TTS queue full, dropping: {e}")
+            })
+    }
+
+    /// Clone the bounded queue sender so callers can apply backpressure without
+    /// holding the huddle mutex. Disabling TTS drops the receiver and unblocks
+    /// any waiting sender while the shared cancellation flag stops playback.
+    pub(crate) fn text_sender(&self) -> TtsTextSender {
+        TtsTextSender {
+            text_tx: self.text_tx.clone(),
+            generation: self.voice_generation.load(Ordering::Acquire),
+        }
+    }
+
+    /// Select a bundled Pocket voice for subsequent speech.
+    ///
+    /// Current playback and queued text are cancelled immediately so content
+    /// cannot continue in the old voice. The worker keeps its warmed inference
+    /// engine and reloads only the reference style before the next utterance.
+    pub fn select_voice(&self, voice: &str) -> Option<tokio::sync::oneshot::Receiver<()>> {
+        let acknowledged = begin_voice_change(
+            &self.voice,
+            &self.voice_generation,
+            &self.voice_cancel,
+            &self.voice_change_ack,
+            voice,
+        );
+        if acknowledged.is_some() {
+            eprintln!("buzz-desktop: tts stage=cancellation reason=voice_switch route_id=0");
+        }
+        acknowledged
+    }
+
+    /// Reconcile the voice of a pipeline that has not been published yet.
+    ///
+    /// No caller can enqueue text before publication, so raising the shared
+    /// cancellation flag here would create a race that could discard the first
+    /// message queued immediately after installation.
+    pub(crate) fn select_voice_before_publish(&self, voice: &str) {
+        *self.voice.lock().unwrap_or_else(|error| error.into_inner()) = voice.to_string();
     }
 
     /// Signal the worker thread to stop.
     pub fn shutdown(&self) {
+        eprintln!("buzz-desktop: tts stage=cancellation reason=shutdown route_id=0");
         self.shutdown.store(true, Ordering::Release);
     }
 
@@ -244,40 +305,52 @@ impl Drop for TtsPipeline {
 
 fn tts_worker(
     model_dir: PathBuf,
-    voice_name: String,
-    text_rx: mpsc::Receiver<String>,
-    tts_active: Arc<AtomicBool>,
-    shutdown: Arc<AtomicBool>,
-    cancel: Arc<AtomicBool>,
+    voice_state: WorkerVoiceState,
+    text_rx: mpsc::Receiver<QueuedText>,
+    control_state: WorkerControlState,
     output_device: Option<String>,
+    startup_tx: mpsc::SyncSender<Result<(), String>>,
 ) {
+    let (selected_voice, voice_generation, voice_change_ack) = voice_state;
+    let (tts_active, shutdown, cancel_signals) = control_state;
+    let (cancel, voice_cancel) = cancel_signals;
     // ── 1. Initialise TTS engine ──────────────────────────────────────────────
     let model_dir_str = model_dir.to_string_lossy().to_string();
 
     let engine = match load_text_to_speech(&model_dir_str) {
         Ok(e) => e,
         Err(e) => {
-            eprintln!(
-                "buzz-desktop: TTS engine init failed (model_dir={}): {e}. TTS disabled.",
-                model_dir.display()
-            );
-            drain_until_shutdown(text_rx, &shutdown);
+            let error = format!("TTS engine initialization failed: {e}");
+            eprintln!("buzz-desktop: tts stage=startup status=failed reason=engine_load");
+            let _ = startup_tx.send(Err(error));
             return;
         }
     };
 
     // ── 2. Load voice style ───────────────────────────────────────────────────
-    let voice_path = model_dir.join(format!("{voice_name}.{VOICE_FILE_EXT}"));
-    let style = match load_voice_style(&voice_path) {
+    let requested_voice = selected_voice
+        .lock()
+        .unwrap_or_else(|error| error.into_inner())
+        .clone();
+    let mut voice_name = DEFAULT_VOICE.to_string();
+    let fallback_path = model_dir.join(format!("{DEFAULT_VOICE}.{VOICE_FILE_EXT}"));
+    let mut style = match load_voice_style(&fallback_path) {
         Ok(s) => s,
         Err(e) => {
-            eprintln!(
-                "buzz-desktop: TTS voice style load failed ({voice_name}): {e}. TTS disabled."
-            );
-            drain_until_shutdown(text_rx, &shutdown);
+            let error = format!("TTS voice style initialization failed: {e}");
+            eprintln!("buzz-desktop: tts stage=startup status=failed reason=fallback_voice_style");
+            let _ = startup_tx.send(Err(error));
             return;
         }
     };
+    if requested_voice != DEFAULT_VOICE
+        && !reconcile_selected_voice(&model_dir, &selected_voice, &mut voice_name, &mut style)
+    {
+        let _ = startup_tx.send(Err(
+            "TTS selected voice and Mary fallback are unavailable".to_string()
+        ));
+        return;
+    }
 
     // ── 2b. Warmup inference ─────────────────────────────────────────────────
     // The first ONNX inference on any session is significantly slower than
@@ -285,15 +358,10 @@ fn tts_worker(
     // pool allocation, and graph-specific caches. Run a short dummy synthesis
     // and discard the output so the first real utterance runs at warm-session speed.
     {
-        let t = std::time::Instant::now();
         match engine.synth_chunk("warmup", "en", &style, SYNTH_STEPS) {
-            Ok(_) => eprintln!(
-                "buzz-desktop: TTS warmup completed in {:.0}ms",
-                t.elapsed().as_millis()
-            ),
-            Err(e) => eprintln!(
-                "buzz-desktop: TTS warmup failed after {:.0}ms: {e} — first utterance may be slow",
-                t.elapsed().as_millis()
+            Ok(_) => eprintln!("buzz-desktop: tts stage=warmup status=ready"),
+            Err(_) => eprintln!(
+                "buzz-desktop: tts stage=warmup status=failed reason=inference first_utterance_may_be_slow=true"
             ),
         }
     }
@@ -306,8 +374,9 @@ fn tts_worker(
     {
         Ok(h) => h,
         Err(e) => {
-            eprintln!("buzz-desktop: TTS audio output failed: {e}. TTS disabled.");
-            drain_until_shutdown(text_rx, &shutdown);
+            let error = format!("TTS audio output initialization failed: {e}");
+            eprintln!("buzz-desktop: tts stage=startup status=failed reason=output_open");
+            let _ = startup_tx.send(Err(error));
             return;
         }
     };
@@ -315,14 +384,14 @@ fn tts_worker(
     let channels = match NonZero::new(1u16) {
         Some(c) => c,
         None => {
-            eprintln!("buzz-desktop: TTS channel count invariant violated");
+            let _ = startup_tx.send(Err("TTS channel count invariant violated".to_string()));
             return;
         }
     };
     let rate = match NonZero::new(SAMPLE_RATE) {
         Some(r) => r,
         None => {
-            eprintln!("buzz-desktop: TTS sample rate invariant violated");
+            let _ = startup_tx.send(Err("TTS sample rate invariant violated".to_string()));
             return;
         }
     };
@@ -346,10 +415,22 @@ fn tts_worker(
         player.append(SamplesBuffer::new(channels, rate, silence));
         // Wait for the silent buffer to drain — this ensures the output stream
         // is fully initialized before the first real utterance.
+        let deadline = std::time::Instant::now() + AUDIO_PRIME_TIMEOUT;
         while !player.empty() {
+            if std::time::Instant::now() >= deadline {
+                eprintln!("buzz-desktop: tts stage=startup status=failed reason=output_prime");
+                let _ = startup_tx.send(Err(
+                    "TTS audio output did not become ready before timeout".to_string(),
+                ));
+                return;
+            }
             thread::sleep(Duration::from_millis(10));
         }
     }
+    if startup_tx.send(Ok(())).is_err() {
+        return;
+    }
+    eprintln!("buzz-desktop: tts stage=startup status=ready");
 
     // ── 3b. Barge-in monitor thread ───────────────────────────────────────────
     //
@@ -377,6 +458,7 @@ fn tts_worker(
     let monitor = {
         let player = Arc::clone(&player);
         let cancel = Arc::clone(&cancel);
+        let voice_cancel = Arc::clone(&voice_cancel);
         let tts_active = Arc::clone(&tts_active);
         let stop = Arc::clone(&monitor_stop);
         let player_ops = Arc::clone(&player_ops);
@@ -384,12 +466,12 @@ fn tts_worker(
             .name("tts-barge-in-monitor".into())
             .spawn(move || {
                 while !stop.load(Ordering::Acquire) {
-                    if cancel.load(Ordering::Acquire) {
+                    if cancel.load(Ordering::Acquire) || voice_cancel.load(Ordering::Acquire) {
                         let _ops = lock_player_ops(&player_ops);
                         // Re-check under the lock: the worker may have
                         // consumed this cancel (and appended fresh audio)
                         // between the load above and the lock acquisition.
-                        if cancel.load(Ordering::Acquire) {
+                        if cancel.load(Ordering::Acquire) || voice_cancel.load(Ordering::Acquire) {
                             // clear() pauses the persistent player; play()
                             // un-pauses (see handle_cancel_or_shutdown).
                             // Idempotent — safe to repeat every tick until
@@ -423,13 +505,45 @@ fn tts_worker(
     // idle branch below uses it to decide when to drop `tts_active` and to
     // arm a fresh lead-in cushion for the next utterance.
     let mut first_append = true;
+    let mut last_route_id = 0;
+    let mut deferred_text = VecDeque::new();
+    let append_audio = |prepared: PreparedModelAudio, route_id: u64| {
+        let _ops = lock_player_ops(&player_ops);
+        if cancel.load(Ordering::Acquire)
+            || voice_cancel.load(Ordering::Acquire)
+            || shutdown.load(Ordering::Acquire)
+        {
+            let reason = if shutdown.load(Ordering::Acquire) {
+                "shutdown"
+            } else if cancel.load(Ordering::Acquire) {
+                "barge_in"
+            } else {
+                "voice_switch"
+            };
+            eprintln!(
+                "buzz-desktop: tts stage=synthesis status=cancelled reason={reason} route_id={route_id}"
+            );
+            return false;
+        }
+        player.append(SamplesBuffer::new(channels, rate, prepared.buffer));
+        eprintln!(
+            "buzz-desktop: tts stage=player status=append_accepted route_id={route_id} chunk_index={} sample_count={}",
+            prepared.chunk_index, prepared.sample_count
+        );
+        // Set this only after append so STT remains open during synthesis.
+        tts_active.store(true, Ordering::Release);
+        true
+    };
 
     loop {
+        let mut no_current_text = None;
         if handle_cancel_or_shutdown(
-            &cancel,
+            (&cancel, &voice_cancel),
             &shutdown,
             &tts_active,
-            &text_rx,
+            (&text_rx, &mut deferred_text, &mut no_current_text),
+            &voice_change_ack,
+            None,
             Some((&player, &player_ops)),
         ) {
             if shutdown.load(Ordering::Acquire) {
@@ -441,28 +555,47 @@ fn tts_worker(
             continue;
         }
 
-        let raw_text = match text_rx.recv_timeout(RECV_TIMEOUT) {
-            Ok(t) => t,
-            Err(mpsc::RecvTimeoutError::Timeout) => {
-                // Nothing queued. If playback has also finished, the agent
-                // has gone quiet — release the mic gate and reset the
-                // lead-in so the next utterance gets a fresh cushion.
-                if player.empty() && !first_append {
-                    tts_active.store(false, Ordering::Release);
-                    first_append = true;
+        // Voice changes cancel the old utterance/queue and are observed here,
+        // before receiving subsequent text. A bad bundled asset falls back to
+        // Mary without discarding the already-warmed Pocket engine.
+        let voice_ready =
+            reconcile_selected_voice(&model_dir, &selected_voice, &mut voice_name, &mut style);
+        acknowledge_voice_change(&voice_change_ack, &voice_cancel);
+        if !voice_ready {
+            continue;
+        }
+
+        let mut queued_text = Some(match deferred_text.pop_front() {
+            Some(text) => text,
+            None => match text_rx.recv_timeout(RECV_TIMEOUT) {
+                Ok(text) => text,
+                Err(mpsc::RecvTimeoutError::Timeout) => {
+                    // Nothing queued. If playback has also finished, the agent
+                    // has gone quiet — release the mic gate and reset the
+                    // lead-in so the next utterance gets a fresh cushion.
+                    if player.empty() && !first_append {
+                        tts_active.store(false, Ordering::Release);
+                        eprintln!(
+                            "buzz-desktop: tts stage=player status=drained route_id={last_route_id}"
+                        );
+                        first_append = true;
+                    }
+                    continue;
                 }
-                continue;
-            }
-            Err(mpsc::RecvTimeoutError::Disconnected) => break,
-        };
+                Err(mpsc::RecvTimeoutError::Disconnected) => break,
+            },
+        });
 
         // Check cancel again after unblocking — a cancel may have arrived
         // while we were waiting.
+        let pending_route_id = queued_text.as_ref().map(|queued| queued.route_id);
         if handle_cancel_or_shutdown(
-            &cancel,
+            (&cancel, &voice_cancel),
             &shutdown,
             &tts_active,
-            &text_rx,
+            (&text_rx, &mut deferred_text, &mut queued_text),
+            &voice_change_ack,
+            pending_route_id,
             Some((&player, &player_ops)),
         ) {
             if shutdown.load(Ordering::Acquire) {
@@ -471,6 +604,30 @@ fn tts_worker(
             first_append = true;
             continue;
         }
+        let Some(queued_text) = queued_text else {
+            continue;
+        };
+        if queued_text.generation < voice_generation.load(Ordering::Acquire) {
+            eprintln!(
+                "buzz-desktop: tts stage=queue status=dropped reason=voice_switch route_id={}",
+                queued_text.route_id
+            );
+            continue;
+        }
+        let raw_text = queued_text.text;
+        let route_id = queued_text.route_id;
+        eprintln!("buzz-desktop: tts stage=synthesis status=started route_id={route_id}");
+
+        // The selected voice can change while this worker is blocked in
+        // recv_timeout. Reconcile again after receipt so the first message
+        // queued after an unpublished pipeline is installed cannot use the
+        // voice captured when construction began.
+        if !reconcile_selected_voice(&model_dir, &selected_voice, &mut voice_name, &mut style) {
+            eprintln!(
+                "buzz-desktop: tts stage=synthesis status=failed reason=voice_unavailable route_id={route_id}"
+            );
+            continue;
+        }
 
         // If playback already drained while we were waiting for this item,
         // the agent is silent — release the mic gate BEFORE preprocessing/
@@ -482,37 +639,53 @@ fn tts_worker(
         // stays set across items.)
         if player.empty() && !first_append {
             tts_active.store(false, Ordering::Release);
+            eprintln!("buzz-desktop: tts stage=player status=drained route_id={last_route_id}");
             first_append = true;
         }
 
         // Preprocess text.
         let text = preprocess_for_tts(&raw_text);
         if text.is_empty() {
+            eprintln!(
+                "buzz-desktop: tts stage=synthesis status=empty reason=preprocess route_id={route_id}"
+            );
             continue;
         }
 
         // Split into sentences, then group into synthesis chunks: the first
         // sentence stays alone (fast time-to-first-audio), the rest pack
-        // greedily up to MAX_CHUNK_CHARS. Each chunk is one `generate()`
-        // call; playback of chunk N overlaps synthesis of chunk N+1
-        // (lookahead pipelining). Grouping matches upstream's ~50-token
-        // chunking and halves the exposed prosody seams on multi-sentence
-        // replies — see MAX_CHUNK_CHARS.
+        // greedily up to MAX_CHUNK_CHARS. Playback of each model unit overlaps
+        // synthesis of the next one. The Pocket engine applies its exact
+        // 50-token split; keeping those units within one playback chunk avoids
+        // adding fades and pauses at token-only boundaries.
         let sentences: Vec<String> = split_sentences(&text)
             .into_iter()
             .filter(|s| !s.trim().is_empty())
             .collect();
         let chunks = group_sentences_into_chunks(&sentences, MAX_CHUNK_CHARS);
+        if chunks.is_empty() {
+            eprintln!(
+                "buzz-desktop: tts stage=synthesis status=empty reason=no_chunks route_id={route_id}"
+            );
+            continue;
+        }
 
-        for chunk in &chunks {
+        let mut synthesis_outcome = "completed";
+        let mut appended_audio = false;
+        let mut model_unit_index = 0_usize;
+        'playback_chunks: for chunk in &chunks {
+            let mut no_current_text = None;
             if handle_cancel_or_shutdown(
-                &cancel,
+                (&cancel, &voice_cancel),
                 &shutdown,
                 &tts_active,
-                &text_rx,
+                (&text_rx, &mut deferred_text, &mut no_current_text),
+                &voice_change_ack,
+                Some(route_id),
                 Some((&player, &player_ops)),
             ) {
                 first_append = true;
+                synthesis_outcome = "cancelled";
                 break;
             }
 
@@ -521,53 +694,113 @@ fn tts_worker(
                 continue;
             }
 
-            match engine.synth_chunk(text, "en", &style, SYNTH_STEPS) {
-                Ok(samples) if !samples.is_empty() => {
-                    let mut audio = clamp_to_full_scale(samples);
-                    // Fade-out only — fading-in would attenuate the consonant
-                    // onset (see `apply_fade_out` docstring + the
-                    // 2026-05-18 "first little sound is missing" regression).
-                    apply_fade_out(&mut audio);
-
-                    // Build one contiguous buffer per synthesized sentence:
-                    // lead-in cushion + audio + trailing gap. Keeping this as
-                    // a single rodio source preserves the original queue/drain
-                    // semantics (one append per sentence) while still giving
-                    // every chunk a quiet device warm-up window.
-                    let buf =
-                        build_sentence_append_buffer(&mut first_append, audio, silence_buf_len);
-
-                    // Check-and-append under `player_ops`, serialized with
-                    // the monitor: a barge-in may have arrived during
-                    // synthesis (the blocking window the monitor thread
-                    // exists for). Don't append the now-stale sentence — the
-                    // human interrupted; speaking it anyway would talk over
-                    // them. Holding the lock for the check + append means the
-                    // monitor can never clear between our check passing and
-                    // the buffer landing. The flag is deliberately NOT
-                    // consumed here: the loop-top handle_cancel_or_shutdown
-                    // does the full consume (drain queue, reset lead-in) on
-                    // the next iteration.
-                    let _ops = lock_player_ops(&player_ops);
-                    if cancel.load(Ordering::Acquire) {
-                        // Nothing appended; the loop-top consume re-arms
-                        // `first_append` (the flag is still set — the worker
-                        // is its only consumer).
+            let model_chunks = match engine.split_text_into_chunks(text) {
+                Ok(model_chunks) => model_chunks,
+                Err(_) => {
+                    eprintln!(
+                        "buzz-desktop: tts stage=synthesis status=failed reason=chunking route_id={route_id}"
+                    );
+                    synthesis_outcome = "failed";
+                    break 'playback_chunks;
+                }
+            };
+            if model_chunks.is_empty() {
+                eprintln!(
+                    "buzz-desktop: tts stage=synthesis status=empty reason=no_chunks route_id={route_id}"
+                );
+                continue;
+            }
+            let mut playback_audio = PlaybackChunkAudio::new();
+            for model_chunk in &model_chunks {
+                let chunk_index = model_unit_index;
+                model_unit_index += 1;
+                let mut no_current_text = None;
+                if handle_cancel_or_shutdown(
+                    (&cancel, &voice_cancel),
+                    &shutdown,
+                    &tts_active,
+                    (&text_rx, &mut deferred_text, &mut no_current_text),
+                    &voice_change_ack,
+                    Some(route_id),
+                    Some((&player, &player_ops)),
+                ) {
+                    first_append = true;
+                    synthesis_outcome = "cancelled";
+                    break 'playback_chunks;
+                }
+
+                let synthesis = engine.synth_chunk(model_chunk, "en", &style, SYNTH_STEPS);
+                if cancel.load(Ordering::Acquire)
+                    || voice_cancel.load(Ordering::Acquire)
+                    || shutdown.load(Ordering::Acquire)
+                {
+                    let reason = if shutdown.load(Ordering::Acquire) {
+                        "shutdown"
+                    } else if cancel.load(Ordering::Acquire) {
+                        "barge_in"
+                    } else {
+                        "voice_switch"
+                    };
+                    eprintln!(
+                        "buzz-desktop: tts stage=synthesis status=cancelled reason={reason} route_id={route_id}"
+                    );
+                    // The monitor already stopped any queued playback. Discard
+                    // synthesis that completed after cancellation so stale audio
+                    // never reaches the player, while keeping buzz-voice's
+                    // extracted April engine API unchanged.
+                    first_append = true;
+                    synthesis_outcome = "cancelled";
+                    break 'playback_chunks;
+                }
+                match synthesis {
+                    Ok(samples) if !samples.is_empty() => {
+                        if let Some(prepared) = playback_audio.push(
+                            samples,
+                            chunk_index,
+                            &mut first_append,
+                            silence_buf_len,
+                            player.empty(),
+                        ) {
+                            if !append_audio(prepared, route_id) {
+                                first_append = true;
+                                synthesis_outcome = "cancelled";
+                                break 'playback_chunks;
+                            }
+                            appended_audio = true;
+                            last_route_id = route_id;
+                        }
+                    }
+                    Ok(_) => {
+                        eprintln!(
+                            "buzz-desktop: tts stage=synthesis status=empty route_id={route_id} chunk_index={chunk_index}"
+                        );
+                    }
+                    Err(_) => {
+                        eprintln!(
+                            "buzz-desktop: tts stage=synthesis status=failed reason=inference route_id={route_id} chunk_index={chunk_index}"
+                        );
+                        synthesis_outcome = "failed";
                         break;
                     }
-                    player.append(SamplesBuffer::new(channels, rate, buf));
-                    // NOTE: tts_active is set AFTER player.append(), not
-                    // before. Setting it before synthesis would cause STT to
-                    // discard user speech during the synthesis window as
-                    // "echo" even though no audio is actually playing yet.
-                    // See crossfire review C3.
-                    tts_active.store(true, Ordering::Release);
                 }
-                Ok(_) => {}
-                Err(e) => {
-                    eprintln!("buzz-desktop: TTS synth failed: {e}");
+            }
+            if let Some(prepared) =
+                playback_audio.finish(&mut first_append, silence_buf_len, player.empty())
+            {
+                if !append_audio(prepared, route_id) {
+                    first_append = true;
+                    synthesis_outcome = "cancelled";
+                    break 'playback_chunks;
                 }
+                appended_audio = true;
+                last_route_id = route_id;
             }
+            if synthesis_outcome == "failed" {
+                break 'playback_chunks;
+            }
+        }
+        if synthesis_outcome == "completed" && appended_audio {
+            eprintln!("buzz-desktop: tts stage=synthesis status=completed route_id={route_id}");
         }
 
         if shutdown.load(Ordering::Acquire) {
@@ -582,6 +815,7 @@ fn tts_worker(
         let _ = handle.join();
     }
 
+    finish_voice_change_ack(&voice_change_ack);
     tts_active.store(false, Ordering::Release);
 }
 
@@ -595,13 +829,21 @@ fn tts_worker(
 /// it is serialized with the monitor's stale-branch re-check (see the monitor
 /// block in `tts_worker`).
 fn handle_cancel_or_shutdown(
-    cancel: &AtomicBool,
+    cancel_signals: CancelSignals<'_>,
     shutdown: &AtomicBool,
     tts_active: &AtomicBool,
-    text_rx: &mpsc::Receiver<String>,
+    text_state: CancelTextState<'_>,
+    voice_change_ack: &VoiceChangeAck,
+    active_route_id: Option<u64>,
     player: Option<(&rodio::Player, &Mutex<()>)>,
 ) -> bool {
+    let (cancel, voice_cancel) = cancel_signals;
+    let (text_rx, deferred_text, current_text) = text_state;
     if shutdown.load(Ordering::Acquire) {
+        eprintln!(
+            "buzz-desktop: tts stage=cancellation reason=shutdown route_id={}",
+            active_route_id.unwrap_or(0)
+        );
         if let Some((p, ops)) = player {
             let _ops = lock_player_ops(ops);
             p.clear();
@@ -609,7 +851,29 @@ fn handle_cancel_or_shutdown(
         tts_active.store(false, Ordering::Release);
         return true;
     }
-    if cancel.load(Ordering::Acquire) {
+    if cancel.load(Ordering::Acquire) || voice_cancel.load(Ordering::Acquire) {
+        // Serialize with begin_voice_change so the generation boundary and
+        // cancel consumption are observed as one transition.
+        let pending_voice_change = voice_change_ack
+            .lock()
+            .unwrap_or_else(|error| error.into_inner());
+        // Consume at the serialization point. A later barge-in remains true
+        // for the next pass instead of being overwritten after queue cleanup.
+        let barge_in = cancel.swap(false, Ordering::AcqRel);
+        voice_cancel.store(false, Ordering::Release);
+        eprintln!(
+            "buzz-desktop: tts stage=cancellation reason={} route_id={}",
+            if barge_in { "barge_in" } else { "voice_switch" },
+            active_route_id.unwrap_or(0)
+        );
+        let preserve_generation = (!barge_in)
+            .then(|| {
+                pending_voice_change
+                    .as_ref()
+                    .map(|pending| pending.generation)
+            })
+            .flatten();
+        retain_cancelled_text(deferred_text, current_text, text_rx, preserve_generation);
         if let Some((p, ops)) = player {
             let _ops = lock_player_ops(ops);
             // `Player::clear()` removes queued sources AND pauses the player
@@ -622,11 +886,6 @@ fn handle_cancel_or_shutdown(
             // Consume the flag under the lock: once released with
             // `cancel == false`, the monitor's stale branch no-ops instead
             // of clearing the fresh post-cancel utterance.
-            while text_rx.try_recv().is_ok() {}
-            cancel.store(false, Ordering::Release);
-        } else {
-            while text_rx.try_recv().is_ok() {}
-            cancel.store(false, Ordering::Release);
         }
         tts_active.store(false, Ordering::Release);
         return true;
@@ -644,135 +903,11 @@ fn lock_player_ops(ops: &Mutex<()>) -> MutexGuard<'_, ()> {
     ops.lock().unwrap_or_else(PoisonError::into_inner)
 }
 
-/// Hard-clamp samples to ±1.0 full scale.
-///
-/// No gain is applied: Pocket TTS already emits speech-level audio
-/// (peaks 0.4–0.97, RMS ≈ −20 dBFS across varied sentences — measured by
-/// `examples/pocket_clip_probe`), matching the kyutai reference pipeline,
-/// which applies no output scaling. Two earlier gain stages were both
-/// regressions against that baseline: per-sentence peak normalization caused
-/// level pumping between sentences, and the fixed 9.3× gain that replaced it
-/// was calibrated on a single anomalously-quiet bench utterance (peak 0.076)
-/// and clipped 13–34% of samples on real speech ("blown out", 2026-06-12).
-/// The clamp alone remains as the safety net against outlier transients.
-fn clamp_to_full_scale(samples: Vec<f32>) -> Vec<f32> {
-    samples.into_iter().map(|s| s.clamp(-1.0, 1.0)).collect()
-}
-
-/// Apply a short linear fade-out at the *end* of `samples`.
-///
-/// Uses `FADE_OUT_SAMPLES` (8 ms) or half the buffer length, whichever is
-/// smaller. Eliminates the click that occurs when a non-zero waveform
-/// terminates abruptly at a sentence boundary.
-///
-/// # Why no fade-in
-///
-/// An earlier revision (pre 2026-05) symmetrically faded *in* over the same
-/// 8 ms window. That swallowed the leading consonant attack on every
-/// sentence — Pocket TTS produces real audio energy inside the first
-/// millisecond (RMS ≈ 0.02, peak ≈ 0.03 measured across four prompts in
-/// `examples/pocket_onset_probe.rs`), and a linear 0→1 ramp over 192 samples
-/// scales those onset samples by ≤50 % for the first ~4 ms. The result was
-/// the "first little sound or two is missing" regression heard on
-/// 2026-05-18.
-///
-/// The first sample of Pocket output measures ≈ 0.0018 (≈ −54 dBFS) — well
-/// below the threshold at which a DC-jump would be audible as a click — so
-/// no fade-in is needed. The OS audio device gets its quiet ramp-up window
-/// from `SENTENCE_LEAD_IN_SAMPLES` instead, inserted as pure silence before
-/// each sentence buffer.
-fn apply_fade_out(samples: &mut [f32]) {
-    let len = samples.len();
-    let fade = FADE_OUT_SAMPLES.min(len / 2);
-    for i in 0..fade {
-        samples[len - 1 - i] *= i as f32 / fade as f32;
-    }
-}
-
-/// Build the single buffer appended to the rodio `Player` for one synthesised
-/// sentence.
-///
-/// Every sentence chunk gets a short lead-in pad immediately before its audio.
-/// This matters for chunks that start with soft first phonemes (`I'm`, `I've`):
-/// the synthesized buffer can begin with speech within the first millisecond,
-/// so the playback layer must provide the device/mixer cushion.
-/// To keep the audible gap unchanged, the trailing silence after this chunk is
-/// shortened by the same amount (`silence_buf_len - SENTENCE_LEAD_IN_SAMPLES`):
-/// sentence N contributes 80 ms of post-speech silence and sentence N+1
-/// contributes the remaining 20 ms of pre-speech cushion.
-///
-/// The lead-in, audio, and trailing silence are concatenated into one
-/// `SamplesBuffer` before appending. This keeps rodio's queue shape at one
-/// tracked source per synthesized sentence, avoiding source-boundary/drain
-/// regressions from enqueueing the lead-in, audio, and tail as separate sounds.
-///
-/// `first_append` is flipped on the first call after the player goes idle.
-/// The worker uses it in the idle branch of the main loop to distinguish
-/// "never queued anything since last drain" from "drained after speaking",
-/// which controls when `tts_active` is released and the lead-in re-armed.
-fn build_sentence_append_buffer(
-    first_append: &mut bool,
-    audio: Vec<f32>,
-    silence_buf_len: usize,
-) -> Vec<f32> {
-    if *first_append {
-        *first_append = false;
-    }
-
-    let trailing_silence_len = silence_buf_len.saturating_sub(SENTENCE_LEAD_IN_SAMPLES);
-    let mut buf = Vec::with_capacity(SENTENCE_LEAD_IN_SAMPLES + audio.len() + trailing_silence_len);
-    buf.extend(std::iter::repeat_n(0.0_f32, SENTENCE_LEAD_IN_SAMPLES));
-    buf.extend(audio);
-    buf.extend(std::iter::repeat_n(0.0_f32, trailing_silence_len));
-    buf
-}
-
-/// Group sentences into synthesis chunks.
-///
-/// The first sentence always stands alone — it is what the listener hears
-/// first, and synthesizing it by itself keeps time-to-first-audio at the
-/// single-sentence cost. Subsequent sentences pack greedily: a sentence
-/// joins the current chunk while the combined length stays within
-/// `max_chars`; otherwise it starts a new chunk. A single sentence longer
-/// than `max_chars` becomes its own chunk unsplit — Pocket TTS handles long
-/// single sentences fine (the ceiling is the 500-LM-step default), it's the
-/// *seams* we're minimizing.
-///
-/// Sentences within a chunk are joined with a single space; sentence-ending
-/// punctuation is preserved by `split_sentences`, so the model sees natural
-/// multi-sentence prose — the same shape upstream's ~50-token chunker feeds it.
-fn group_sentences_into_chunks(sentences: &[String], max_chars: usize) -> Vec<String> {
-    let mut chunks: Vec<String> = Vec::new();
-    for (i, sentence) in sentences.iter().enumerate() {
-        let sentence = sentence.trim();
-        if sentence.is_empty() {
-            continue;
-        }
-        if i == 0 || chunks.is_empty() {
-            chunks.push(sentence.to_string());
-            continue;
-        }
-        // Never merge into the first chunk — it's the latency-critical one.
-        let can_merge = chunks.len() > 1
-            && chunks
-                .last()
-                .is_some_and(|c| c.len() + 1 + sentence.len() <= max_chars);
-        if can_merge {
-            let last = chunks.last_mut().expect("non-empty checked above");
-            last.push(' ');
-            last.push_str(sentence);
-        } else {
-            chunks.push(sentence.to_string());
-        }
-    }
-    chunks
-}
-
-// drain_until_shutdown lives in super (huddle/mod.rs) — shared with stt.rs.
-use super::drain_until_shutdown;
-
 // ── Tests ─────────────────────────────────────────────────────────────────────
 
 #[cfg(test)]
 #[path = "tts_tests.rs"]
 mod tests;
+#[cfg(test)]
+#[path = "tts_voice_selection_tests.rs"]
+mod voice_selection_tests;
diff --git a/desktop/src-tauri/src/huddle/tts_audio.rs b/desktop/src-tauri/src/huddle/tts_audio.rs
new file mode 100644
index 0000000000..58300b7497
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_audio.rs
@@ -0,0 +1,235 @@
+use super::{FADE_OUT_SAMPLES, SENTENCE_LEAD_IN_SAMPLES};
+
+pub(super) struct PreparedModelAudio {
+    pub(super) buffer: Vec<f32>,
+    pub(super) sample_count: usize,
+    pub(super) chunk_index: usize,
+}
+
+/// Holds one synthesized model unit so playback-boundary decoration is based
+/// on the first and last unit that actually produced audio.
+pub(super) struct PlaybackChunkAudio {
+    pending: Option<(Vec<f32>, usize)>,
+    appended: bool,
+}
+
+impl PlaybackChunkAudio {
+    pub(super) fn new() -> Self {
+        Self {
+            pending: None,
+            appended: false,
+        }
+    }
+
+    pub(super) fn push(
+        &mut self,
+        samples: Vec<f32>,
+        chunk_index: usize,
+        first_append: &mut bool,
+        silence_buf_len: usize,
+        playback_idle: bool,
+    ) -> Option<PreparedModelAudio> {
+        if samples.is_empty() {
+            return None;
+        }
+        let previous = self.pending.replace((samples, chunk_index))?;
+        let prepared = prepare_model_audio(
+            previous,
+            first_append,
+            silence_buf_len,
+            !self.appended || playback_idle,
+            false,
+        );
+        self.appended = true;
+        Some(prepared)
+    }
+
+    pub(super) fn finish(
+        &mut self,
+        first_append: &mut bool,
+        silence_buf_len: usize,
+        playback_idle: bool,
+    ) -> Option<PreparedModelAudio> {
+        let pending = self.pending.take()?;
+        Some(prepare_model_audio(
+            pending,
+            first_append,
+            silence_buf_len,
+            !self.appended || playback_idle,
+            true,
+        ))
+    }
+}
+
+fn prepare_model_audio(
+    (samples, chunk_index): (Vec<f32>, usize),
+    first_append: &mut bool,
+    silence_buf_len: usize,
+    starts_playback_chunk: bool,
+    ends_playback_chunk: bool,
+) -> PreparedModelAudio {
+    let sample_count = samples.len();
+    let mut audio = clamp_to_full_scale(samples);
+    if ends_playback_chunk {
+        apply_fade_out(&mut audio);
+    }
+    PreparedModelAudio {
+        buffer: build_sentence_append_buffer(
+            first_append,
+            audio,
+            silence_buf_len,
+            starts_playback_chunk,
+            ends_playback_chunk,
+        ),
+        sample_count,
+        chunk_index,
+    }
+}
+
+/// Hard-clamp samples to ±1.0 full scale.
+pub(super) fn clamp_to_full_scale(samples: Vec<f32>) -> Vec<f32> {
+    samples.into_iter().map(|s| s.clamp(-1.0, 1.0)).collect()
+}
+
+/// Apply a short linear fade-out to avoid a discontinuity at playback boundaries.
+pub(super) fn apply_fade_out(samples: &mut [f32]) {
+    let len = samples.len();
+    let fade = FADE_OUT_SAMPLES.min(len / 2);
+    for i in 0..fade {
+        samples[len - 1 - i] *= i as f32 / fade as f32;
+    }
+}
+
+pub(super) fn build_sentence_append_buffer(
+    first_append: &mut bool,
+    audio: Vec<f32>,
+    silence_buf_len: usize,
+    starts_playback_chunk: bool,
+    ends_playback_chunk: bool,
+) -> Vec<f32> {
+    if *first_append {
+        *first_append = false;
+    }
+
+    let lead_in_len = if starts_playback_chunk {
+        SENTENCE_LEAD_IN_SAMPLES
+    } else {
+        0
+    };
+    let trailing_silence_len = if ends_playback_chunk {
+        silence_buf_len.saturating_sub(SENTENCE_LEAD_IN_SAMPLES)
+    } else {
+        0
+    };
+    let mut buffer = Vec::with_capacity(lead_in_len + audio.len() + trailing_silence_len);
+    buffer.extend(std::iter::repeat_n(0.0_f32, lead_in_len));
+    buffer.extend(audio);
+    buffer.extend(std::iter::repeat_n(0.0_f32, trailing_silence_len));
+    buffer
+}
+
+pub(super) fn group_sentences_into_chunks(sentences: &[String], max_chars: usize) -> Vec<String> {
+    let mut chunks: Vec<String> = Vec::new();
+    for (index, sentence) in sentences.iter().enumerate() {
+        let sentence = sentence.trim();
+        if sentence.is_empty() {
+            continue;
+        }
+        if index == 0 || chunks.is_empty() {
+            chunks.push(sentence.to_string());
+            continue;
+        }
+        let can_merge = chunks.len() > 1
+            && chunks
+                .last()
+                .is_some_and(|chunk| chunk.len() + 1 + sentence.len() <= max_chars);
+        if can_merge {
+            if let Some(last) = chunks.last_mut() {
+                last.push(' ');
+                last.push_str(sentence);
+            }
+        } else {
+            chunks.push(sentence.to_string());
+        }
+    }
+    chunks
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn multi_unit_audio_decorates_only_outer_playback_boundaries() {
+        let mut chunk = PlaybackChunkAudio::new();
+        let mut first_append = true;
+        let silence = SENTENCE_LEAD_IN_SAMPLES + 100;
+
+        assert!(chunk
+            .push(vec![0.4; 16], 0, &mut first_append, silence, false)
+            .is_none());
+        let first = chunk
+            .push(vec![0.5; 16], 1, &mut first_append, silence, false)
+            .expect("first ready model unit");
+        assert_eq!(first.buffer.len(), SENTENCE_LEAD_IN_SAMPLES + 16);
+        assert!(first.buffer[..SENTENCE_LEAD_IN_SAMPLES]
+            .iter()
+            .all(|sample| *sample == 0.0));
+        assert_eq!(first.buffer[SENTENCE_LEAD_IN_SAMPLES], 0.4);
+
+        let last = chunk
+            .finish(&mut first_append, silence, false)
+            .expect("last ready model unit");
+        assert_eq!(last.buffer.len(), 16 + 100);
+        assert_eq!(last.buffer.last(), Some(&0.0));
+    }
+
+    #[test]
+    fn empty_edge_units_do_not_steal_lead_in_or_trailing_boundary() {
+        let mut chunk = PlaybackChunkAudio::new();
+        let mut first_append = true;
+        let silence = SENTENCE_LEAD_IN_SAMPLES + 100;
+
+        assert!(chunk
+            .push(Vec::new(), 0, &mut first_append, silence, false)
+            .is_none());
+        assert!(chunk
+            .push(vec![0.5; 16], 1, &mut first_append, silence, false)
+            .is_none());
+        assert!(chunk
+            .push(Vec::new(), 2, &mut first_append, silence, false)
+            .is_none());
+
+        let only = chunk
+            .finish(&mut first_append, silence, false)
+            .expect("only audible model unit");
+        assert_eq!(only.buffer.len(), SENTENCE_LEAD_IN_SAMPLES + 16 + 100);
+        assert!(only.buffer[..SENTENCE_LEAD_IN_SAMPLES]
+            .iter()
+            .all(|sample| *sample == 0.0));
+        assert_eq!(only.buffer.last(), Some(&0.0));
+    }
+
+    #[test]
+    fn playback_underrun_rearms_the_onset_cushion() {
+        let mut chunk = PlaybackChunkAudio::new();
+        let mut first_append = true;
+        let silence = SENTENCE_LEAD_IN_SAMPLES + 100;
+
+        assert!(chunk
+            .push(vec![0.4; 16], 0, &mut first_append, silence, false)
+            .is_none());
+        let first = chunk
+            .push(vec![0.5; 16], 1, &mut first_append, silence, false)
+            .expect("first model unit");
+        assert_eq!(first.buffer.len(), SENTENCE_LEAD_IN_SAMPLES + 16);
+
+        let after_underrun = chunk
+            .push(vec![0.6; 16], 2, &mut first_append, silence, true)
+            .expect("model unit after underrun");
+        assert_eq!(after_underrun.buffer.len(), SENTENCE_LEAD_IN_SAMPLES + 16);
+        assert!(after_underrun.buffer[..SENTENCE_LEAD_IN_SAMPLES]
+            .iter()
+            .all(|sample| *sample == 0.0));
+    }
+}
diff --git a/desktop/src-tauri/src/huddle/tts_settings.rs b/desktop/src-tauri/src/huddle/tts_settings.rs
new file mode 100644
index 0000000000..1b378af823
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_settings.rs
@@ -0,0 +1,971 @@
+//! Installation-global text-to-speech preferences and the local voice registry.
+//!
+//! Voice keys are backend-qualified (`pocket:mary`, `siri:aaron`) and
+//! preferences are ordered. A client resolves the first compatible entry for
+//! its one active playback backend. The same [`VoicePreferences`] value can be
+//! embedded in installation-global settings or future agent identity without a
+//! schema change. Availability is intentionally client-local.
+
+use std::{
+    path::{Path, PathBuf},
+    sync::{Arc, Mutex},
+    time::Duration,
+};
+
+use serde::{Deserialize, Serialize};
+use tauri::{AppHandle, Manager, State};
+
+use crate::{app_state::AppState, managed_agents::storage::atomic_write_json_restricted};
+
+use super::{
+    models,
+    pocket::DEFAULT_VOICE,
+    tts_voice_registry::{source_url, MARY_VOICE_KEY, POCKET_VOICES},
+    HuddlePhase, HuddleState,
+};
+
+const SETTINGS_FILE: &str = "tts-settings.json";
+const CURRENT_VERSION: u32 = 1;
+const VOICE_CHANGE_ACK_TIMEOUT: Duration = Duration::from_secs(5);
+pub const POCKET_BACKEND_ID: &str = "pocket";
+
+type VoiceChangeWait = (
+    Arc<super::tts::TtsPipeline>,
+    tokio::sync::oneshot::Receiver<()>,
+);
+
+const VOICE_AVAILABILITY_BUNDLED: &str = "bundled";
+const VOICE_AVAILABILITY_INSTALLED: &str = "installed";
+
+/// Installation-global huddle audio and speech preferences.
+#[derive(Default)]
+pub struct HuddleAudioSettingsState {
+    pub tts: Mutex<TtsSettings>,
+    pub tts_load_error: Mutex<Option<String>>,
+    pub tts_transition: tokio::sync::Mutex<()>,
+    /// Selected huddle output device. `None` uses the system default.
+    pub output_device: Mutex<Option<String>>,
+}
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct VoiceRegistryEntry {
+    /// Stable identity, never derived from or merged by the display name.
+    ///
+    /// Built-ins use `backend:slug`. Future imports use
+    /// `pocket:imported:<audio-content-sha256>` so two clips with the same
+    /// editable label remain distinct.
+    pub key: String,
+    pub display_name: String,
+    pub backend: String,
+    pub backend_name: String,
+    /// Client-local state: bundled, installed, downloadable, or unavailable.
+    pub availability: String,
+    pub fallback_key: Option<String>,
+    pub reference_file: Option<String>,
+    pub provenance: VoiceProvenance,
+}
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct VoiceProvenance {
+    pub source: String,
+    pub content_hash: Option<String>,
+    pub license: Option<String>,
+    pub source_url: Option<String>,
+}
+
+/// Ordered, backend-qualified preferences shared by global and agent settings.
+///
+/// Unknown but well-formed keys remain persisted because a different client
+/// may have that backend installed. Resolution is always local.
+pub type VoicePreferences = Vec<String>;
+
+/// Bundled Pocket voices available without local imports.
+pub fn bundled_voice_registry() -> Vec<VoiceRegistryEntry> {
+    POCKET_VOICES
+        .iter()
+        .map(|voice| VoiceRegistryEntry {
+            key: voice.key.to_string(),
+            display_name: voice.display_name.to_string(),
+            backend: POCKET_BACKEND_ID.to_string(),
+            backend_name: "Pocket TTS".to_string(),
+            availability: VOICE_AVAILABILITY_BUNDLED.to_string(),
+            fallback_key: (voice.key != MARY_VOICE_KEY).then(|| MARY_VOICE_KEY.to_string()),
+            reference_file: Some(voice.reference_file.to_string()),
+            provenance: VoiceProvenance {
+                source: "bundled".to_string(),
+                content_hash: Some(voice.sha256.to_string()),
+                license: Some("CC-BY-4.0".to_string()),
+                source_url: Some(source_url(voice)),
+            },
+        })
+        .collect()
+}
+
+/// Cross-backend registry of bundled and locally installed voices.
+pub fn voice_registry(app: &AppHandle) -> Vec<VoiceRegistryEntry> {
+    let mut registry = bundled_voice_registry();
+    match super::tts_voice_import::load_registry(app) {
+        Ok(imported) => registry.extend(imported.into_iter().map(|voice| VoiceRegistryEntry {
+            key: voice.key,
+            display_name: voice.display_name,
+            backend: POCKET_BACKEND_ID.to_string(),
+            backend_name: "Pocket TTS".to_string(),
+            availability: VOICE_AVAILABILITY_INSTALLED.to_string(),
+            fallback_key: Some(MARY_VOICE_KEY.to_string()),
+            reference_file: Some(voice.file_name),
+            provenance: VoiceProvenance {
+                source: "local import".to_string(),
+                content_hash: Some(voice.content_hash),
+                license: None,
+                source_url: None,
+            },
+        })),
+        Err(error) => {
+            eprintln!(
+                "buzz-desktop: {error}; imported Pocket voices are unavailable for this session"
+            );
+        }
+    }
+    registry
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct TtsSettings {
+    pub version: u32,
+    pub agent_text_to_speech: bool,
+    pub voice_preferences: VoicePreferences,
+}
+
+impl Default for TtsSettings {
+    fn default() -> Self {
+        Self {
+            version: CURRENT_VERSION,
+            agent_text_to_speech: true,
+            voice_preferences: vec![MARY_VOICE_KEY.to_string()],
+        }
+    }
+}
+
+pub fn voice_by_key(app: &AppHandle, key: &str) -> Option<VoiceRegistryEntry> {
+    voice_registry(app)
+        .into_iter()
+        .find(|voice| voice.key == key)
+}
+
+fn is_qualified_voice_key(key: &str) -> bool {
+    key.split_once(':')
+        .is_some_and(|(backend, voice)| !backend.is_empty() && !voice.is_empty())
+}
+
+fn is_locally_available(availability: &str) -> bool {
+    matches!(
+        availability,
+        VOICE_AVAILABILITY_BUNDLED | VOICE_AVAILABILITY_INSTALLED
+    )
+}
+
+#[cfg(test)]
+pub fn resolve_voice_for_backend(
+    preferences: &[String],
+    backend: &str,
+) -> Result<VoiceRegistryEntry, String> {
+    resolve_voice_for_backend_in_registry(preferences, backend, &bundled_voice_registry())
+}
+
+fn resolve_voice_for_backend_in_registry(
+    preferences: &[String],
+    backend: &str,
+    registry: &[VoiceRegistryEntry],
+) -> Result<VoiceRegistryEntry, String> {
+    preferences
+        .iter()
+        .filter_map(|key| registry.iter().find(|voice| voice.key == *key))
+        .find(|voice| voice.backend == backend && is_locally_available(voice.availability.as_str()))
+        .or_else(|| {
+            registry.iter().find(|voice| {
+                voice.backend == backend
+                    && voice.fallback_key.is_none()
+                    && is_locally_available(voice.availability.as_str())
+            })
+        })
+        .cloned()
+        .ok_or_else(|| format!("No locally available fallback voice for backend {backend}"))
+}
+
+pub fn bundled_pocket_voice_reference(preferences: &[String]) -> String {
+    resolve_voice_for_backend_in_registry(preferences, POCKET_BACKEND_ID, &bundled_voice_registry())
+        .ok()
+        .and_then(|voice| voice.reference_file)
+        .and_then(|file| file.strip_suffix(".wav").map(str::to_string))
+        .unwrap_or_else(|| DEFAULT_VOICE.to_string())
+}
+
+pub fn pocket_voice_reference(app: &AppHandle, preferences: &[String]) -> Result<String, String> {
+    let registry = voice_registry(app);
+    let voice = resolve_voice_for_backend_in_registry(preferences, POCKET_BACKEND_ID, &registry)?;
+    if voice.key.starts_with("pocket:imported:") {
+        let imported = super::tts_voice_import::load_registry(app)?
+            .into_iter()
+            .find(|candidate| candidate.key == voice.key)
+            .ok_or_else(|| format!("Imported voice {} is unavailable", voice.display_name))?;
+        return super::tts_voice_import::resolve_file(app, &imported)
+            .map(|path| path.to_string_lossy().into_owned());
+    }
+    Ok(voice
+        .reference_file
+        .and_then(|file| file.strip_suffix(".wav").map(str::to_string))
+        .unwrap_or_else(|| DEFAULT_VOICE.to_string()))
+}
+
+pub(crate) fn settings_path(app: &AppHandle) -> Result<PathBuf, String> {
+    app.path()
+        .app_data_dir()
+        .map(|dir| dir.join(SETTINGS_FILE))
+        .map_err(|error| format!("could not locate Buzz settings storage: {error}"))
+}
+
+pub(crate) fn load_from_path(path: &Path) -> Result<TtsSettings, String> {
+    if !path.exists() {
+        return Ok(TtsSettings::default());
+    }
+    let bytes = std::fs::read(path)
+        .map_err(|error| format!("could not read text-to-speech settings: {error}"))?;
+    let value: serde_json::Value = serde_json::from_slice(&bytes)
+        .map_err(|error| format!("text-to-speech settings are not valid JSON: {error}"))?;
+
+    // Unversioned settings are incompatible with the V1 schema. Use
+    // deterministic V1 defaults rather than interpreting ambiguous fields.
+    if value.get("version").is_none() {
+        return Ok(TtsSettings::default());
+    }
+
+    let version = value
+        .get("version")
+        .and_then(serde_json::Value::as_u64)
+        .ok_or("text-to-speech settings version is invalid")?;
+    if version > u64::from(CURRENT_VERSION) {
+        return Err(format!(
+            "text-to-speech settings version {version} is newer than this Buzz build supports"
+        ));
+    }
+
+    // Legacy V1 settings may contain one bare Pocket `voiceId`. Preserve the
+    // toggle and qualify it into the ordered cross-backend preference schema.
+    if value.get("voicePreferences").is_none() {
+        let legacy_voice = value
+            .get("voiceId")
+            .or_else(|| value.get("voice_id"))
+            .and_then(serde_json::Value::as_str)
+            .unwrap_or("mary");
+        let voice_key = if is_qualified_voice_key(legacy_voice) {
+            legacy_voice.to_string()
+        } else {
+            format!("{POCKET_BACKEND_ID}:{legacy_voice}")
+        };
+        return Ok(TtsSettings {
+            version: CURRENT_VERSION,
+            agent_text_to_speech: value
+                .get("agentTextToSpeech")
+                .and_then(serde_json::Value::as_bool)
+                .unwrap_or(true),
+            voice_preferences: vec![voice_key],
+        });
+    }
+
+    let mut settings: TtsSettings = serde_json::from_value(value)
+        .map_err(|error| format!("text-to-speech settings are invalid: {error}"))?;
+    settings.version = CURRENT_VERSION;
+    if settings.voice_preferences.is_empty()
+        || settings
+            .voice_preferences
+            .iter()
+            .any(|key| !is_qualified_voice_key(key))
+    {
+        settings.voice_preferences = TtsSettings::default().voice_preferences;
+    }
+    Ok(settings)
+}
+
+pub(crate) fn save_to_path(path: &Path, settings: &TtsSettings) -> Result<(), String> {
+    if settings.voice_preferences.is_empty() {
+        return Err("At least one voice preference is required".to_string());
+    }
+    if let Some(key) = settings
+        .voice_preferences
+        .iter()
+        .find(|key| !is_qualified_voice_key(key))
+    {
+        return Err(format!(
+            "Voice preference keys must be backend-qualified: {key}"
+        ));
+    }
+    let payload = serde_json::to_vec_pretty(settings)
+        .map_err(|error| format!("could not encode text-to-speech settings: {error}"))?;
+    atomic_write_json_restricted(path, &payload)
+        .map_err(|error| format!("could not save text-to-speech settings: {error}"))
+}
+
+pub fn load_for_app(app: &AppHandle) -> (TtsSettings, Option<String>) {
+    let result = settings_path(app).and_then(|path| load_from_path(&path));
+    match result {
+        Ok(settings) => (settings, None),
+        Err(error) => {
+            eprintln!("buzz-desktop: {error}; preserving the file and using Mary for this session");
+            (TtsSettings::default(), Some(error))
+        }
+    }
+}
+
+#[tauri::command]
+pub fn get_tts_settings(state: State<'_, AppState>) -> Result<TtsSettings, String> {
+    if let Some(error) = state
+        .huddle_audio
+        .tts_load_error
+        .lock()
+        .map_err(|lock_error| format!("text-to-speech settings lock poisoned: {lock_error}"))?
+        .clone()
+    {
+        return Err(format!(
+            "Voice settings could not be loaded and were left unchanged: {error}"
+        ));
+    }
+    state
+        .huddle_audio
+        .tts
+        .lock()
+        .map(|settings| settings.clone())
+        .map_err(|error| format!("text-to-speech settings lock poisoned: {error}"))
+}
+
+#[tauri::command]
+pub fn list_voice_registry(app: AppHandle) -> Vec<VoiceRegistryEntry> {
+    voice_registry(&app)
+}
+
+fn ensure_settings_writable(state: &AppState) -> Result<(), String> {
+    if let Some(error) = state
+        .huddle_audio
+        .tts_load_error
+        .lock()
+        .map_err(|lock_error| format!("text-to-speech settings lock poisoned: {lock_error}"))?
+        .as_ref()
+    {
+        return Err(format!(
+            "Voice settings were not saved because the existing file could not be loaded: {error}"
+        ));
+    }
+    Ok(())
+}
+
+fn cancel_huddle_speech(
+    huddle: &mut super::HuddleState,
+) -> Option<std::sync::Arc<super::tts::TtsPipeline>> {
+    huddle.tts_enabled = false;
+    huddle
+        .tts_cancel
+        .store(true, std::sync::atomic::Ordering::Release);
+    huddle.tts_pipeline.take()
+}
+
+fn disable_tts_runtime(state: &AppState) -> Result<(), String> {
+    let old_pipeline = {
+        let mut huddle = state.huddle()?;
+        cancel_huddle_speech(&mut huddle)
+    };
+    if let Some(ref pipeline) = old_pipeline {
+        pipeline.shutdown();
+    }
+    drop(old_pipeline);
+    state.emit_huddle_state_changed();
+    Ok(())
+}
+
+fn commit_effective_off(state: &AppState) -> Result<(), String> {
+    state
+        .huddle_audio
+        .tts
+        .lock()
+        .map_err(|error| format!("text-to-speech settings lock poisoned: {error}"))?
+        .agent_text_to_speech = false;
+    Ok(())
+}
+
+fn enable_tts_runtime(huddle: &mut HuddleState, voice: &str) -> Option<VoiceChangeWait> {
+    huddle.tts_enabled = true;
+    // OFF removes the pipeline. Clear a prior cancellation only when enabling
+    // a fresh pipeline; an idempotent ON write must not erase a voice
+    // transition that the existing worker still needs to drain.
+    prepare_enable_cancel(&huddle.tts_cancel, huddle.tts_pipeline.is_some());
+    huddle.tts_pipeline.as_ref().and_then(|pipeline| {
+        pipeline
+            .select_voice(voice)
+            .map(|acknowledged| (Arc::clone(pipeline), acknowledged))
+    })
+}
+
+fn prepare_enable_cancel(cancel: &std::sync::atomic::AtomicBool, has_pipeline: bool) {
+    if !has_pipeline {
+        cancel.store(false, std::sync::atomic::Ordering::Release);
+    }
+}
+
+async fn apply_tts_settings(
+    settings: TtsSettings,
+    app: &AppHandle,
+    state: &AppState,
+) -> Result<Option<VoiceChangeWait>, String> {
+    if settings.version != CURRENT_VERSION {
+        return Err(format!(
+            "Unsupported text-to-speech settings version: {}",
+            settings.version
+        ));
+    }
+
+    // OFF is safety-sensitive: stop current and queued speech before any disk
+    // I/O, and never resume it merely because persistence fails.
+    if !settings.agent_text_to_speech {
+        disable_tts_runtime(state)?;
+        commit_effective_off(state)?;
+    }
+
+    ensure_settings_writable(state)?;
+    save_to_path(&settings_path(app)?, &settings)?;
+
+    *state
+        .huddle_audio
+        .tts
+        .lock()
+        .map_err(|error| format!("text-to-speech settings lock poisoned: {error}"))? =
+        settings.clone();
+
+    let mut voice_change_wait = None;
+    if settings.agent_text_to_speech {
+        let (active, voice_change_ack) = {
+            let mut huddle = state.huddle()?;
+            let voice_reference = pocket_voice_reference(app, &settings.voice_preferences)?;
+            let voice_change_ack = enable_tts_runtime(&mut huddle, &voice_reference);
+            (
+                matches!(huddle.phase, HuddlePhase::Connected | HuddlePhase::Active),
+                voice_change_ack,
+            )
+        };
+        voice_change_wait = voice_change_ack;
+        if active {
+            if let Err(error) = super::pipeline::maybe_start_tts_pipeline(state).await {
+                eprintln!("buzz-desktop: could not hot-start text to speech: {error}");
+            }
+        }
+        state.emit_huddle_state_changed();
+    }
+    Ok(voice_change_wait)
+}
+
+fn current_settings(state: &AppState) -> Result<TtsSettings, String> {
+    state
+        .huddle_audio
+        .tts
+        .lock()
+        .map_err(|error| format!("text-to-speech settings lock poisoned: {error}"))
+        .map(|settings| settings.clone())
+}
+
+async fn finish_voice_change(voice_change: Option<VoiceChangeWait>) -> Result<(), String> {
+    let Some((pipeline, acknowledged)) = voice_change else {
+        return Ok(());
+    };
+    wait_for_voice_change_ack(acknowledged, VOICE_CHANGE_ACK_TIMEOUT, || {
+        pipeline.is_finished()
+    })
+    .await
+}
+
+async fn finish_durable_voice_change(voice_change: Option<VoiceChangeWait>) {
+    if let Err(error) = finish_voice_change(voice_change).await {
+        eprintln!(
+            "buzz-desktop: tts stage=voice_switch status=delayed reason=ack_timeout error={error}"
+        );
+    }
+}
+
+async fn wait_for_voice_change_ack(
+    mut acknowledged: tokio::sync::oneshot::Receiver<()>,
+    timeout: Duration,
+    mut worker_is_finished: impl FnMut() -> bool,
+) -> Result<(), String> {
+    let deadline = tokio::time::sleep(timeout);
+    tokio::pin!(deadline);
+    loop {
+        tokio::select! {
+            _ = &mut acknowledged => return Ok(()),
+            _ = &mut deadline => {
+                return Err(
+                    "Pocket TTS is still finishing the previous voice. Turn Agent text to speech off and try again."
+                        .to_string(),
+                );
+            }
+            _ = tokio::time::sleep(Duration::from_millis(25)) => {
+                if worker_is_finished() {
+                    return Ok(());
+                }
+            }
+        }
+    }
+}
+
+/// Compatibility command for the huddle speaker button. It updates the same
+/// installation-global preference as Settings; there is no per-huddle override.
+#[tauri::command]
+pub async fn set_tts_enabled(
+    enabled: bool,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<TtsSettings, String> {
+    let transition = state.huddle_audio.tts_transition.lock().await;
+    let mut settings = state
+        .huddle_audio
+        .tts
+        .lock()
+        .map_err(|error| format!("text-to-speech settings lock poisoned: {error}"))?
+        .clone();
+    settings.agent_text_to_speech = enabled;
+    let voice_change = apply_tts_settings(settings, &app, &state).await?;
+    drop(transition);
+    finish_voice_change(voice_change).await?;
+    current_settings(&state)
+}
+
+fn settings_with_pocket_voice(
+    settings: TtsSettings,
+    voice_key: &str,
+    app: &AppHandle,
+) -> Result<TtsSettings, String> {
+    settings_with_pocket_voice_from_registry(settings, voice_key, &voice_registry(app))
+}
+
+fn settings_with_pocket_voice_from_registry(
+    mut settings: TtsSettings,
+    voice_key: &str,
+    registry: &[VoiceRegistryEntry],
+) -> Result<TtsSettings, String> {
+    let voice = registry
+        .iter()
+        .find(|voice| voice.key == voice_key)
+        .ok_or_else(|| format!("Unknown voice: {voice_key}"))?;
+    if voice.backend != POCKET_BACKEND_ID || !is_locally_available(&voice.availability) {
+        return Err("The selected Pocket voice is not available on this device".to_string());
+    }
+    let first_pocket_index = settings
+        .voice_preferences
+        .iter()
+        .position(|key| key.starts_with("pocket:"));
+    settings
+        .voice_preferences
+        .retain(|key| !key.starts_with("pocket:"));
+    let insert_at = first_pocket_index
+        .unwrap_or(settings.voice_preferences.len())
+        .min(settings.voice_preferences.len());
+    settings
+        .voice_preferences
+        .insert(insert_at, voice_key.to_string());
+    Ok(settings)
+}
+
+#[tauri::command]
+pub async fn set_pocket_voice(
+    voice_key: String,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<TtsSettings, String> {
+    let transition = state.huddle_audio.tts_transition.lock().await;
+    let settings = state
+        .huddle_audio
+        .tts
+        .lock()
+        .map_err(|error| format!("text-to-speech settings lock poisoned: {error}"))?
+        .clone();
+    let settings = settings_with_pocket_voice(settings, &voice_key, &app)?;
+    let voice_change = apply_tts_settings(settings, &app, &state).await?;
+    drop(transition);
+    finish_durable_voice_change(voice_change).await;
+    current_settings(&state)
+}
+
+#[tauri::command]
+pub async fn preview_pocket_voice(
+    voice_key: String,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let voice =
+        voice_by_key(&app, &voice_key).ok_or_else(|| format!("Unknown voice: {voice_key}"))?;
+    if voice.backend != POCKET_BACKEND_ID {
+        return Err("Only Pocket voices can be previewed in this build".to_string());
+    }
+    if !models::is_tts_ready() {
+        return Err("Voice files are still downloading. Try preview again shortly.".to_string());
+    }
+    let model_dir = models::tts_model_dir().ok_or("Pocket voice files are unavailable")?;
+    let output_device = state
+        .huddle_audio
+        .output_device
+        .lock()
+        .unwrap_or_else(|error| error.into_inner())
+        .clone();
+    let voice_name = pocket_voice_reference(&app, std::slice::from_ref(&voice_key))?;
+    tokio::task::spawn_blocking(move || {
+        let active = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+        let cancel = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+        let pipeline = super::tts::TtsPipeline::new_with_voice(
+            model_dir,
+            active.clone(),
+            cancel,
+            &voice_name,
+            output_device,
+        )?;
+        pipeline.speak("Hello! This is how I’ll read agent responses.".to_string())?;
+        let started = std::time::Instant::now();
+        let mut heard_audio = false;
+        while started.elapsed() < std::time::Duration::from_secs(30) {
+            let is_active = active.load(std::sync::atomic::Ordering::Acquire);
+            heard_audio |= is_active;
+            if heard_audio && !is_active {
+                return Ok(());
+            }
+            std::thread::sleep(std::time::Duration::from_millis(25));
+        }
+        Err("Voice preview timed out. Check your audio output and try again.".to_string())
+    })
+    .await
+    .map_err(|error| format!("Voice preview task failed: {error}"))?
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TtsVoiceMutation {
+    pub settings: TtsSettings,
+    pub registry: Vec<VoiceRegistryEntry>,
+}
+
+#[tauri::command]
+pub async fn import_pocket_voice(
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<Option<TtsVoiceMutation>, String> {
+    let Some(imported) = super::tts_voice_import::pick_and_import(&app).await? else {
+        return Ok(None);
+    };
+    let transition = state.huddle_audio.tts_transition.lock().await;
+    let settings = current_settings(&state)?;
+    let settings = settings_with_pocket_voice(settings, &imported.key, &app)?;
+    let voice_change = apply_tts_settings(settings, &app, &state).await?;
+    drop(transition);
+    finish_durable_voice_change(voice_change).await;
+    Ok(Some(TtsVoiceMutation {
+        settings: current_settings(&state)?,
+        registry: voice_registry(&app),
+    }))
+}
+
+#[tauri::command]
+pub async fn delete_pocket_voice(
+    voice_key: String,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<TtsVoiceMutation, String> {
+    if !voice_key.starts_with("pocket:imported:") {
+        return Err("Bundled voices cannot be deleted".to_string());
+    }
+    if voice_by_key(&app, &voice_key).is_none() {
+        return Err(format!("Unknown imported voice: {voice_key}"));
+    }
+
+    let transition = state.huddle_audio.tts_transition.lock().await;
+    let current = current_settings(&state)?;
+    let selected = resolve_voice_for_backend_in_registry(
+        &current.voice_preferences,
+        POCKET_BACKEND_ID,
+        &voice_registry(&app),
+    )
+    .is_ok_and(|voice| voice.key == voice_key);
+    let voice_change = if selected {
+        let fallback = settings_with_pocket_voice(current, MARY_VOICE_KEY, &app)?;
+        apply_tts_settings(fallback, &app, &state).await?
+    } else {
+        None
+    };
+    drop(transition);
+    finish_durable_voice_change(voice_change).await;
+    super::tts_voice_import::delete(&app, &voice_key)?;
+    Ok(TtsVoiceMutation {
+        settings: current_settings(&state)?,
+        registry: voice_registry(&app),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    const EVE_VOICE_KEY: &str = "pocket:eve";
+
+    #[tokio::test]
+    async fn stalled_voice_change_returns_an_actionable_error() {
+        let (_keep_pending, acknowledged) = tokio::sync::oneshot::channel();
+
+        let error = wait_for_voice_change_ack(acknowledged, Duration::from_millis(1), || false)
+            .await
+            .expect_err("stalled worker should time out");
+
+        assert!(error.contains("Turn Agent text to speech off"));
+    }
+
+    #[test]
+    fn idempotent_enable_preserves_an_existing_pipeline_cancel() {
+        let cancel = std::sync::atomic::AtomicBool::new(true);
+        prepare_enable_cancel(&cancel, true);
+        assert!(cancel.load(std::sync::atomic::Ordering::Acquire));
+        prepare_enable_cancel(&cancel, false);
+        assert!(!cancel.load(std::sync::atomic::Ordering::Acquire));
+    }
+
+    #[test]
+    fn defaults_are_backwards_compatible_and_use_mary() {
+        assert_eq!(
+            TtsSettings::default(),
+            TtsSettings {
+                version: 1,
+                agent_text_to_speech: true,
+                voice_preferences: vec!["pocket:mary".to_string()],
+            }
+        );
+    }
+
+    #[test]
+    fn registry_has_all_official_english_vctk_presets() {
+        assert_eq!(
+            bundled_voice_registry()
+                .iter()
+                .map(|voice| {
+                    (
+                        voice.key.as_str(),
+                        voice.display_name.as_str(),
+                        voice.reference_file.as_deref(),
+                    )
+                })
+                .collect::<Vec<_>>(),
+            vec![
+                ("pocket:anna", "Anna", Some("anna.wav")),
+                ("pocket:vera", "Vera", Some("vera.wav")),
+                ("pocket:fantine", "Fantine", Some("fantine.wav")),
+                ("pocket:charles", "Charles", Some("charles.wav")),
+                ("pocket:paul", "Paul", Some("paul.wav")),
+                ("pocket:eponine", "Eponine", Some("eponine.wav")),
+                ("pocket:azelma", "Azelma", Some("azelma.wav")),
+                ("pocket:george", "George", Some("george.wav")),
+                ("pocket:mary", "Mary", Some("reference_sample.wav")),
+                ("pocket:jane", "Jane", Some("jane.wav")),
+                ("pocket:michael", "Michael", Some("michael.wav")),
+                ("pocket:eve", "Eve", Some("eve.wav")),
+            ]
+        );
+    }
+
+    #[test]
+    fn local_backend_resolution_uses_first_compatible_preference() {
+        let preferences = vec![
+            "siri:aaron".to_string(),
+            EVE_VOICE_KEY.to_string(),
+            MARY_VOICE_KEY.to_string(),
+            "kokoro:af_heart".to_string(),
+        ];
+        assert_eq!(
+            resolve_voice_for_backend(&preferences, POCKET_BACKEND_ID)
+                .expect("Pocket fallback")
+                .key,
+            EVE_VOICE_KEY
+        );
+    }
+
+    #[test]
+    fn unsupported_or_missing_preferences_fall_back_to_backend_default() {
+        let preferences = vec![
+            "siri:aaron".to_string(),
+            "pocket:imported:deadbeef".to_string(),
+        ];
+        assert_eq!(
+            resolve_voice_for_backend(&preferences, POCKET_BACKEND_ID)
+                .expect("Pocket fallback")
+                .key,
+            MARY_VOICE_KEY
+        );
+    }
+
+    #[test]
+    fn identity_is_qualified_key_not_display_label() {
+        assert!(is_qualified_voice_key("pocket:imported:audio-content-hash"));
+        assert_ne!(MARY_VOICE_KEY, EVE_VOICE_KEY);
+        let mut registry = bundled_voice_registry();
+        registry[0].display_name = "Jim".to_string();
+        registry[1].display_name = "Jim".to_string();
+        assert_eq!(registry[0].display_name, registry[1].display_name);
+        assert_ne!(registry[0].key, registry[1].key);
+        assert_eq!(
+            registry
+                .iter()
+                .map(|voice| voice.key.as_str())
+                .collect::<std::collections::HashSet<_>>()
+                .len(),
+            registry.len()
+        );
+    }
+
+    #[test]
+    fn bundled_vctk_assets_match_the_registry_manifest() {
+        for voice in POCKET_VOICES {
+            let Some(bytes) = voice.bytes else {
+                continue;
+            };
+            assert_eq!(&bytes[0..4], b"RIFF", "{}", voice.display_name);
+            assert_eq!(&bytes[8..12], b"WAVE", "{}", voice.display_name);
+            assert_eq!(
+                hex::encode(<sha2::Sha256 as sha2::Digest>::digest(bytes)),
+                voice.sha256,
+                "{}",
+                voice.display_name
+            );
+        }
+    }
+
+    #[test]
+    fn migrates_unversioned_experiment_settings_to_v1_defaults() {
+        let dir = tempfile::tempdir().expect("temp dir");
+        let path = dir.path().join(SETTINGS_FILE);
+        std::fs::write(&path, r#"{"voice":"legacy-experiment"}"#).expect("fixture write");
+        assert_eq!(
+            load_from_path(&path).expect("migration"),
+            TtsSettings::default()
+        );
+    }
+
+    #[test]
+    fn migrates_bare_pocket_voice_id_to_qualified_preferences() {
+        let dir = tempfile::tempdir().expect("temp dir");
+        let path = dir.path().join(SETTINGS_FILE);
+        std::fs::write(
+            &path,
+            r#"{"version":1,"agentTextToSpeech":false,"voiceId":"eve"}"#,
+        )
+        .expect("fixture write");
+        assert_eq!(
+            load_from_path(&path).expect("migration"),
+            TtsSettings {
+                version: 1,
+                agent_text_to_speech: false,
+                voice_preferences: vec![EVE_VOICE_KEY.to_string()],
+            }
+        );
+    }
+
+    #[test]
+    fn unknown_qualified_preferences_are_preserved_for_other_clients() {
+        let dir = tempfile::tempdir().expect("temp dir");
+        let path = dir.path().join(SETTINGS_FILE);
+        std::fs::write(
+            &path,
+            r#"{"version":1,"agentTextToSpeech":false,"voicePreferences":["siri:aaron","pocket:imported:abc123"]}"#,
+        )
+        .expect("fixture write");
+        let settings = load_from_path(&path).expect("load");
+        assert!(!settings.agent_text_to_speech);
+        assert_eq!(
+            settings.voice_preferences,
+            vec!["siri:aaron", "pocket:imported:abc123"]
+        );
+    }
+
+    #[test]
+    fn rejects_future_schema_versions_clearly() {
+        let dir = tempfile::tempdir().expect("temp dir");
+        let path = dir.path().join(SETTINGS_FILE);
+        std::fs::write(
+            &path,
+            r#"{"version":99,"agentTextToSpeech":true,"voicePreferences":["pocket:mary"]}"#,
+        )
+        .expect("fixture write");
+        assert!(load_from_path(&path)
+            .expect_err("future version should fail")
+            .contains("newer than this Buzz build supports"));
+    }
+
+    #[test]
+    fn disabling_cancels_runtime_before_persistence_can_fail() {
+        let mut huddle = super::super::HuddleState {
+            tts_enabled: true,
+            ..super::super::HuddleState::default()
+        };
+        assert!(!huddle.tts_cancel.load(std::sync::atomic::Ordering::Acquire));
+        assert!(cancel_huddle_speech(&mut huddle).is_none());
+        assert!(!huddle.tts_enabled);
+        assert!(huddle.tts_cancel.load(std::sync::atomic::Ordering::Acquire));
+    }
+
+    #[test]
+    fn pocket_voice_update_preserves_the_latest_toggle_and_other_backends() {
+        let current = TtsSettings {
+            agent_text_to_speech: false,
+            voice_preferences: vec!["siri:aaron".to_string(), MARY_VOICE_KEY.to_string()],
+            ..TtsSettings::default()
+        };
+        let updated = settings_with_pocket_voice_from_registry(
+            current,
+            EVE_VOICE_KEY,
+            &bundled_voice_registry(),
+        )
+        .expect("available voice");
+        assert!(!updated.agent_text_to_speech);
+        assert_eq!(updated.voice_preferences, vec!["siri:aaron", EVE_VOICE_KEY]);
+    }
+
+    #[test]
+    fn failed_off_persistence_cannot_be_undone_by_a_later_voice_update() {
+        let state = crate::app_state::build_app_state();
+        commit_effective_off(&state).expect("commit effective OFF state");
+
+        // This models the next command after the OFF save fails: it must merge
+        // from effective memory state, not the stale last-persisted ON value.
+        let current = state.huddle_audio.tts.lock().expect("settings").clone();
+        let voice_update = settings_with_pocket_voice_from_registry(
+            current,
+            EVE_VOICE_KEY,
+            &bundled_voice_registry(),
+        )
+        .expect("available voice");
+        assert!(!voice_update.agent_text_to_speech);
+    }
+
+    #[test]
+    fn failed_disabled_voice_save_does_not_change_the_remembered_voice() {
+        let state = crate::app_state::build_app_state();
+        state
+            .huddle_audio
+            .tts
+            .lock()
+            .expect("settings")
+            .agent_text_to_speech = false;
+        let current = state.huddle_audio.tts.lock().expect("settings").clone();
+        let unsaved = settings_with_pocket_voice_from_registry(
+            current,
+            EVE_VOICE_KEY,
+            &bundled_voice_registry(),
+        )
+        .expect("available voice");
+
+        // This is the only pre-persistence mutation for an OFF candidate.
+        commit_effective_off(&state).expect("commit effective OFF state");
+        let remembered = state.huddle_audio.tts.lock().expect("settings").clone();
+        assert_eq!(remembered.voice_preferences, vec![MARY_VOICE_KEY]);
+        assert_eq!(unsaved.voice_preferences, vec![EVE_VOICE_KEY]);
+    }
+}
diff --git a/desktop/src-tauri/src/huddle/tts_startup.rs b/desktop/src-tauri/src/huddle/tts_startup.rs
new file mode 100644
index 0000000000..2cb50401a9
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_startup.rs
@@ -0,0 +1,24 @@
+use std::{sync::mpsc, thread};
+
+pub(super) fn await_worker_startup(
+    handle: thread::JoinHandle<()>,
+    startup_rx: mpsc::Receiver<Result<(), String>>,
+) -> Result<thread::JoinHandle<()>, String> {
+    match startup_rx.recv() {
+        Ok(Ok(())) => Ok(handle),
+        Ok(Err(error)) => {
+            let _ = handle.join();
+            Err(error)
+        }
+        Err(error) => {
+            let _ = handle.join();
+            Err(format!(
+                "TTS worker exited before reporting readiness: {error}"
+            ))
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "tts_startup_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/huddle/tts_startup_tests.rs b/desktop/src-tauri/src/huddle/tts_startup_tests.rs
new file mode 100644
index 0000000000..cf688c2db8
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_startup_tests.rs
@@ -0,0 +1,44 @@
+use super::*;
+use std::sync::{
+    atomic::{AtomicBool, Ordering},
+    Arc,
+};
+
+#[test]
+fn startup_failure_is_returned_after_worker_exit() {
+    let (tx, rx) = mpsc::sync_channel(1);
+    let exited = Arc::new(AtomicBool::new(false));
+    let exited_worker = Arc::clone(&exited);
+    let handle = std::thread::spawn(move || {
+        tx.send(Err("output unavailable".to_string()))
+            .expect("startup receiver");
+        exited_worker.store(true, Ordering::Release);
+    });
+
+    assert_eq!(
+        await_worker_startup(handle, rx).expect_err("startup must fail"),
+        "output unavailable"
+    );
+    assert!(exited.load(Ordering::Acquire));
+}
+
+#[test]
+fn worker_exit_before_readiness_is_a_startup_error() {
+    let (tx, rx) = mpsc::sync_channel::<Result<(), String>>(1);
+    let handle = std::thread::spawn(move || drop(tx));
+
+    assert!(await_worker_startup(handle, rx)
+        .expect_err("closed startup channel must fail")
+        .contains("before reporting readiness"));
+}
+
+#[test]
+fn ready_ack_precedes_pipeline_publication_boundary() {
+    let (tx, rx) = mpsc::sync_channel(1);
+    let handle = std::thread::spawn(move || {
+        tx.send(Ok(())).expect("startup receiver");
+    });
+
+    let handle = await_worker_startup(handle, rx).expect("ready worker");
+    handle.join().expect("worker exits");
+}
diff --git a/desktop/src-tauri/src/huddle/tts_tests.rs b/desktop/src-tauri/src/huddle/tts_tests.rs
index 7887f8bbdb..1908b096b1 100644
--- a/desktop/src-tauri/src/huddle/tts_tests.rs
+++ b/desktop/src-tauri/src/huddle/tts_tests.rs
@@ -9,6 +9,9 @@ use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::mpsc;
 use std::sync::{Arc, Mutex};
 
+#[path = "tts_tests/token_split.rs"]
+mod token_split;
+
 // ── Remote interrupt tracker ──────────────────────────────────────────────
 //
 // Models the per-peer frame counting logic in the recv task of
@@ -785,16 +788,6 @@ fn apply_fade_out_single_sample() {
     assert_eq!(samples[0], 1.0);
 }
 
-/// Sanity-check the per-sentence cushion length: 20 ms at 24 kHz must
-/// land at exactly 480 samples. This is a const computation, so the
-/// real value of this test is documenting *why* 20 ms was chosen — it
-/// covers a typical CoreAudio buffer turnover (256–1024 samples)
-/// without being audible as user-facing latency.
-#[test]
-fn sentence_lead_in_is_sane() {
-    assert_eq!(SENTENCE_LEAD_IN_SAMPLES, 480, "20 ms × 24 kHz");
-}
-
 // ── build_sentence_append_buffer tests ───────────────────────────────────
 
 /// REGRESSION: every chunk needs an onset cushion; synthesized chunks
@@ -812,6 +805,8 @@ fn lead_in_pad_is_present_for_every_sentence_chunk() {
             &mut first,
             vec![0.5_f32; SENTENCE_AUDIO_LEN],
             SILENCE_BUF_LEN,
+            true,
+            true,
         );
 
         assert_eq!(buf.len(), SENTENCE_AUDIO_LEN + SILENCE_BUF_LEN);
@@ -840,11 +835,11 @@ fn lead_in_pad_is_present_for_every_sentence_chunk() {
 #[test]
 fn build_sentence_append_buffer_flips_first_append() {
     let mut first = true;
-    let _ = build_sentence_append_buffer(&mut first, vec![0.5; 100], 2400);
+    let _ = build_sentence_append_buffer(&mut first, vec![0.5; 100], 2400, true, true);
     assert!(!first, "first call must flip the flag");
 
     // Subsequent call: still has a per-sentence lead-in, flag stays false.
-    let buf = build_sentence_append_buffer(&mut first, vec![0.5; 100], 2400);
+    let buf = build_sentence_append_buffer(&mut first, vec![0.5; 100], 2400, true, true);
     assert!(buf[..SENTENCE_LEAD_IN_SAMPLES].iter().all(|&s| s == 0.0));
     assert!(!first);
 }
@@ -853,7 +848,7 @@ fn build_sentence_append_buffer_flips_first_append() {
 #[test]
 fn first_sentence_leading_silence_is_exactly_lead_in() {
     let mut first = true;
-    let buf = build_sentence_append_buffer(&mut first, vec![0.5; 100], 2400);
+    let buf = build_sentence_append_buffer(&mut first, vec![0.5; 100], 2400, true, true);
     assert!(buf[..SENTENCE_LEAD_IN_SAMPLES].iter().all(|&s| s == 0.0));
     assert_eq!(buf[SENTENCE_LEAD_IN_SAMPLES], 0.5);
 }
@@ -863,8 +858,10 @@ fn first_sentence_leading_silence_is_exactly_lead_in() {
 fn sentence_gap_budget_is_preserved() {
     let mut first = true;
     let silence_buf_len = 2400;
-    let first_buf = build_sentence_append_buffer(&mut first, vec![0.5; 100], silence_buf_len);
-    let second_buf = build_sentence_append_buffer(&mut first, vec![0.5; 100], silence_buf_len);
+    let first_buf =
+        build_sentence_append_buffer(&mut first, vec![0.5; 100], silence_buf_len, true, true);
+    let second_buf =
+        build_sentence_append_buffer(&mut first, vec![0.5; 100], silence_buf_len, true, true);
 
     let first_tail = &first_buf[SENTENCE_LEAD_IN_SAMPLES + 100..];
     let second_lead = &second_buf[..SENTENCE_LEAD_IN_SAMPLES];
@@ -877,7 +874,7 @@ fn sentence_gap_budget_is_preserved() {
 #[test]
 fn sentence_append_buffer_is_one_contiguous_source() {
     let mut first = true;
-    let buf = build_sentence_append_buffer(&mut first, vec![0.5; 100], 2400);
+    let buf = build_sentence_append_buffer(&mut first, vec![0.5; 100], 2400, true, true);
 
     assert_eq!(buf.len(), 2400 + 100);
     assert!(buf[..SENTENCE_LEAD_IN_SAMPLES].iter().all(|&s| s == 0.0));
@@ -949,9 +946,8 @@ fn chunk_grouping_packs_up_to_budget_then_spills() {
     assert_eq!(chunks[2], d);
 }
 
-/// A single sentence longer than the budget is passed through unsplit —
-/// long single sentences are fine (the LM cap bounds runaway); only seams
-/// are being minimized.
+/// A single sentence longer than the coarse budget is passed through here;
+/// the loaded April engine subsequently enforces its exact 50-token limit.
 #[test]
 fn chunk_grouping_oversized_sentence_passes_through() {
     let long = "word ".repeat(60).trim_end().to_string() + ".";
diff --git a/desktop/src-tauri/src/huddle/tts_tests/token_split.rs b/desktop/src-tauri/src/huddle/tts_tests/token_split.rs
new file mode 100644
index 0000000000..b9249c9afc
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_tests/token_split.rs
@@ -0,0 +1,24 @@
+use super::*;
+
+/// The onset cushion covers 20 ms at the production sample rate.
+#[test]
+fn sentence_lead_in_is_sane() {
+    assert_eq!(SENTENCE_LEAD_IN_SAMPLES, 480, "20 ms × 24 kHz");
+}
+
+/// Model-token splits remain contiguous: only the playback chunk as a whole
+/// receives its onset cushion and trailing sentence gap.
+#[test]
+fn token_split_units_do_not_add_sentence_boundary_padding() {
+    let mut first = true;
+    let silence_buf_len = 2400;
+    let first_unit =
+        build_sentence_append_buffer(&mut first, vec![0.5; 100], silence_buf_len, true, false);
+    let last_unit =
+        build_sentence_append_buffer(&mut first, vec![0.25; 100], silence_buf_len, false, true);
+
+    assert_eq!(first_unit.len(), SENTENCE_LEAD_IN_SAMPLES + 100);
+    assert_eq!(first_unit.last(), Some(&0.5));
+    assert_eq!(last_unit.first(), Some(&0.25));
+    assert_eq!(first_unit.len() + last_unit.len(), 200 + silence_buf_len);
+}
diff --git a/desktop/src-tauri/src/huddle/tts_voice_import.rs b/desktop/src-tauri/src/huddle/tts_voice_import.rs
new file mode 100644
index 0000000000..cdcc7761e2
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_voice_import.rs
@@ -0,0 +1,59 @@
+//! Tauri native-picker adapter for the reusable local Pocket voice library.
+
+use std::path::PathBuf;
+
+use buzz_voice_pkg::imported::{ImportedVoice, PocketVoiceLibrary};
+use tauri::{AppHandle, Manager};
+
+pub fn voices_dir(app: &AppHandle) -> Result<PathBuf, String> {
+    app.path()
+        .app_data_dir()
+        .map(|path| path.join("tts").join("pocket-voices"))
+        .map_err(|error| format!("could not locate local voice storage: {error}"))
+}
+
+fn library(app: &AppHandle) -> Result<PocketVoiceLibrary, String> {
+    voices_dir(app).map(PocketVoiceLibrary::new)
+}
+
+pub fn load_registry(app: &AppHandle) -> Result<Vec<ImportedVoice>, String> {
+    library(app)?.load()
+}
+
+pub fn resolve_file(app: &AppHandle, voice: &ImportedVoice) -> Result<PathBuf, String> {
+    library(app)?.resolve_file(voice)
+}
+
+pub async fn pick_and_import(app: &AppHandle) -> Result<Option<ImportedVoice>, String> {
+    use tauri_plugin_dialog::DialogExt;
+
+    let (sender, receiver) = tokio::sync::oneshot::channel();
+    app.dialog()
+        .file()
+        .add_filter(
+            "Audio",
+            &["wav", "m4a", "mp3", "flac", "ogg", "oga", "aif", "aiff"],
+        )
+        .pick_file(move |path| {
+            let _ = sender.send(path);
+        });
+    let Some(file_path) = receiver
+        .await
+        .map_err(|_| "voice picker closed unexpectedly".to_string())?
+    else {
+        return Ok(None);
+    };
+    let path = file_path
+        .as_path()
+        .ok_or("the selected voice path is invalid")?
+        .to_path_buf();
+    let voice_library = library(app)?;
+    tokio::task::spawn_blocking(move || voice_library.import_path(&path))
+        .await
+        .map_err(|error| format!("voice import task failed: {error}"))?
+        .map(Some)
+}
+
+pub fn delete(app: &AppHandle, key: &str) -> Result<(), String> {
+    library(app)?.delete(key)
+}
diff --git a/desktop/src-tauri/src/huddle/tts_voice_registry.rs b/desktop/src-tauri/src/huddle/tts_voice_registry.rs
new file mode 100644
index 0000000000..bdfbd7677b
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_voice_registry.rs
@@ -0,0 +1,129 @@
+//! Built-in Pocket voice identities and immutable asset metadata.
+//!
+//! Stable keys identify audio, not display labels. Future imported voices use
+//! `pocket:imported:<audio-content-sha256>` and may share editable labels.
+
+pub(super) const MARY_VOICE_KEY: &str = "pocket:mary";
+pub(super) const VCTK_REVISION: &str = "323332d33f997de8394f24a193e1a76df720e01a";
+
+pub(super) struct PocketVoiceSpec {
+    pub key: &'static str,
+    pub display_name: &'static str,
+    pub reference_file: &'static str,
+    pub upstream_file: &'static str,
+    pub sha256: &'static str,
+    pub bytes: Option<&'static [u8]>,
+}
+
+macro_rules! bundled_voice {
+    ($key:literal, $name:literal, $file:literal, $upstream:literal, $hash:literal) => {
+        PocketVoiceSpec {
+            key: $key,
+            display_name: $name,
+            reference_file: concat!($file, ".wav"),
+            upstream_file: concat!("vctk/", $upstream),
+            sha256: $hash,
+            bytes: Some(include_bytes!(concat!(
+                "../../resources/pocket-voices/",
+                $file,
+                ".wav"
+            ))),
+        }
+    };
+}
+
+/// Official English Pocket presets, in the order published by Kyutai.
+pub(super) static POCKET_VOICES: &[PocketVoiceSpec] = &[
+    bundled_voice!(
+        "pocket:anna",
+        "Anna",
+        "anna",
+        "p228_023_enhanced.wav",
+        "0a6de25cf12bf1540beb85979f306a92be81fecc051c547c5395e7e5237a3856"
+    ),
+    bundled_voice!(
+        "pocket:vera",
+        "Vera",
+        "vera",
+        "p229_023_enhanced.wav",
+        "309cf91a895830f15842b398f69a4962cb1f7e0bfab10e25dd27838e826c204b"
+    ),
+    bundled_voice!(
+        "pocket:fantine",
+        "Fantine",
+        "fantine",
+        "p244_023_enhanced.wav",
+        "5f07d4e2a3f20a15572aae885156b43ef3fc12ef3812996fd135680d9956448b"
+    ),
+    bundled_voice!(
+        "pocket:charles",
+        "Charles",
+        "charles",
+        "p254_023_enhanced.wav",
+        "6b681a429198f16e378d53bccb08d06939da7b00144a7696111d4f8f76be7756"
+    ),
+    bundled_voice!(
+        "pocket:paul",
+        "Paul",
+        "paul",
+        "p259_023_enhanced.wav",
+        "7aba504fe0b3b16478b69eb27ce6007e3cb42b0c1915b5f1c6a6024ae37d679b"
+    ),
+    bundled_voice!(
+        "pocket:eponine",
+        "Eponine",
+        "eponine",
+        "p262_023_enhanced.wav",
+        "a13c27fb47627b05223691a0ef2974358a18c886e6c2f9d2762ff1d02c20926b"
+    ),
+    bundled_voice!(
+        "pocket:azelma",
+        "Azelma",
+        "azelma",
+        "p303_023_enhanced.wav",
+        "60e3d26cdf2efdec5df712152c839928f4d5522821e6554ae11fd96c57ab1026"
+    ),
+    bundled_voice!(
+        "pocket:george",
+        "George",
+        "george",
+        "p315_023_enhanced.wav",
+        "29a41f93bf5236e5b21501091d7774c255d5f3d4e62fa4f9fdf0a92a793c84ae"
+    ),
+    PocketVoiceSpec {
+        key: MARY_VOICE_KEY,
+        display_name: "Mary",
+        reference_file: "reference_sample.wav",
+        upstream_file: "vctk/p333_023_enhanced.wav",
+        sha256: "a35b0468382218e9f37a9a7494d1e4b74deaf18d7ced22265b4e325bb55c183f",
+        bytes: None,
+    },
+    bundled_voice!(
+        "pocket:jane",
+        "Jane",
+        "jane",
+        "p339_023_enhanced.wav",
+        "2f12e7f155eb3118f55425394f1b049e5b1b67bdc9b3932c8ba4521420aeb84a"
+    ),
+    bundled_voice!(
+        "pocket:michael",
+        "Michael",
+        "michael",
+        "p360_023_enhanced.wav",
+        "b6743e9195e5e3fd34fe9d1633ae93f7ffab787b249e45f6467d7d6f7a6ee6ad"
+    ),
+    bundled_voice!(
+        "pocket:eve",
+        "Eve",
+        "eve",
+        "p361_023_enhanced.wav",
+        "396e7cbd066b0f3fb6d67fa26e7904076958239d736d4390f15b5fe88feb14cd"
+    ),
+];
+
+pub(super) fn source_url(voice: &PocketVoiceSpec) -> String {
+    format!(
+        "https://huggingface.co/kyutai/tts-voices/blob/{VCTK_REVISION}/{}",
+        voice.upstream_file
+    )
+}
diff --git a/desktop/src-tauri/src/huddle/tts_voice_selection_tests.rs b/desktop/src-tauri/src/huddle/tts_voice_selection_tests.rs
new file mode 100644
index 0000000000..45662c9921
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_voice_selection_tests.rs
@@ -0,0 +1,385 @@
+use super::*;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+fn inert_pipeline(cancel: Arc<AtomicBool>) -> TtsPipeline {
+    let (text_tx, text_rx) = std::sync::mpsc::sync_channel(TEXT_QUEUE_DEPTH);
+    let shutdown = Arc::new(AtomicBool::new(false));
+    let worker_shutdown = Arc::clone(&shutdown);
+    let thread = std::thread::spawn(move || {
+        while !worker_shutdown.load(Ordering::Acquire) {
+            let _ = text_rx.recv_timeout(RECV_TIMEOUT);
+        }
+    });
+    TtsPipeline {
+        text_tx,
+        tts_active: Arc::new(AtomicBool::new(false)),
+        shutdown,
+        cancel,
+        voice_cancel: Arc::new(AtomicBool::new(false)),
+        voice: Arc::new(std::sync::Mutex::new("reference_sample".to_string())),
+        voice_generation: Arc::new(AtomicU64::new(1)),
+        voice_change_ack: Arc::new(std::sync::Mutex::new(None)),
+        thread: Some(thread),
+    }
+}
+
+#[test]
+fn selecting_a_voice_raises_only_the_internal_cancel_and_retains_the_engine_handle() {
+    let cancel = Arc::new(AtomicBool::new(false));
+    let pipeline = inert_pipeline(Arc::clone(&cancel));
+
+    let _acknowledged = pipeline.select_voice("eve");
+
+    assert!(!cancel.load(Ordering::Acquire));
+    assert!(pipeline.voice_cancel.load(Ordering::Acquire));
+    assert_eq!(
+        pipeline
+            .voice
+            .lock()
+            .unwrap_or_else(|error| error.into_inner())
+            .as_str(),
+        "eve"
+    );
+}
+
+#[test]
+fn reconciling_an_unpublished_pipeline_does_not_cancel_its_first_message() {
+    let cancel = Arc::new(AtomicBool::new(false));
+    let pipeline = inert_pipeline(Arc::clone(&cancel));
+
+    pipeline.select_voice_before_publish("eve");
+
+    assert!(!cancel.load(Ordering::Acquire));
+    assert_eq!(
+        pipeline
+            .voice
+            .lock()
+            .unwrap_or_else(|error| error.into_inner())
+            .as_str(),
+        "eve"
+    );
+}
+
+#[test]
+fn received_text_reconciles_a_voice_changed_while_the_worker_was_waiting() {
+    let model_dir = tempfile::tempdir().expect("temp model dir");
+    let bundled_voice =
+        std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("resources/pocket-voices/eve.wav");
+    std::fs::copy(
+        &bundled_voice,
+        model_dir.path().join("reference_sample.wav"),
+    )
+    .expect("Mary test voice");
+    std::fs::copy(&bundled_voice, model_dir.path().join("eve.wav")).expect("Eve test voice");
+
+    let selected_voice = Arc::new(std::sync::Mutex::new("reference_sample".to_string()));
+    let mut style =
+        load_voice_style(&model_dir.path().join("reference_sample.wav")).expect("initial style");
+    let waiting = Arc::new(std::sync::Barrier::new(2));
+    let (text_tx, text_rx) = std::sync::mpsc::channel();
+    let worker_voice = Arc::clone(&selected_voice);
+    let worker_waiting = Arc::clone(&waiting);
+    let worker_model_dir = model_dir.path().to_path_buf();
+    let worker = std::thread::spawn(move || {
+        let mut voice_name = "reference_sample".to_string();
+        worker_waiting.wait();
+        let text = text_rx.recv().expect("first queued text");
+        assert!(reconcile_selected_voice(
+            &worker_model_dir,
+            &worker_voice,
+            &mut voice_name,
+            &mut style,
+        ));
+        (text, voice_name)
+    });
+
+    waiting.wait();
+    *selected_voice.lock().expect("selected voice") = "eve".to_string();
+    text_tx
+        .send("first message".to_string())
+        .expect("queue first message");
+
+    assert_eq!(
+        worker.join().expect("worker"),
+        ("first message".to_string(), "eve".to_string())
+    );
+}
+
+#[test]
+fn corrupt_selected_voice_falls_back_to_mary() {
+    let model_dir = tempfile::tempdir().expect("temp model dir");
+    let bundled_voice =
+        std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("resources/pocket-voices/eve.wav");
+    std::fs::copy(bundled_voice, model_dir.path().join("reference_sample.wav"))
+        .expect("Mary test voice");
+    std::fs::write(model_dir.path().join("eve.wav"), b"not a wave")
+        .expect("corrupt selected voice");
+
+    let selected_voice = std::sync::Mutex::new("eve".to_string());
+    let mut voice_name = "reference_sample".to_string();
+    let mut style =
+        load_voice_style(&model_dir.path().join("reference_sample.wav")).expect("Mary style");
+
+    assert!(reconcile_selected_voice(
+        model_dir.path(),
+        &selected_voice,
+        &mut voice_name,
+        &mut style,
+    ));
+    assert_eq!(voice_name, DEFAULT_VOICE);
+    assert_eq!(
+        selected_voice
+            .lock()
+            .unwrap_or_else(|error| error.into_inner())
+            .as_str(),
+        DEFAULT_VOICE
+    );
+}
+
+#[test]
+fn an_in_hand_post_change_message_survives_cancellation() {
+    let selected_voice = Arc::new(std::sync::Mutex::new("reference_sample".to_string()));
+    let voice_generation = AtomicU64::new(1);
+    let barge_in = AtomicBool::new(false);
+    let voice_cancel = Arc::new(AtomicBool::new(false));
+    let voice_change_ack = Arc::new(std::sync::Mutex::new(None));
+    let (text_tx, text_rx) = std::sync::mpsc::sync_channel(1);
+    let mut acknowledged = begin_voice_change(
+        &selected_voice,
+        &voice_generation,
+        &voice_cancel,
+        &voice_change_ack,
+        "eve",
+    )
+    .expect("voice changed");
+    assert!(voice_cancel.load(Ordering::Acquire));
+    assert!(matches!(
+        acknowledged.try_recv(),
+        Err(tokio::sync::oneshot::error::TryRecvError::Empty)
+    ));
+    acknowledge_voice_change(&voice_change_ack, &voice_cancel);
+    assert!(matches!(
+        acknowledged.try_recv(),
+        Err(tokio::sync::oneshot::error::TryRecvError::Empty)
+    ));
+    text_tx
+        .send(QueuedText {
+            generation: voice_generation.load(Ordering::Acquire),
+            route_id: 1,
+            text: "new message".to_string(),
+        })
+        .expect("new message");
+    let mut current_text = Some(text_rx.recv().expect("in-hand new message"));
+
+    let shutdown = AtomicBool::new(false);
+    let active = AtomicBool::new(true);
+    let mut deferred_text = VecDeque::from([
+        QueuedText {
+            generation: 1,
+            route_id: 2,
+            text: "old message".to_string(),
+        },
+        QueuedText {
+            generation: voice_generation.load(Ordering::Acquire),
+            route_id: 3,
+            text: "later new message".to_string(),
+        },
+    ]);
+    assert!(handle_cancel_or_shutdown(
+        (&barge_in, &voice_cancel),
+        &shutdown,
+        &active,
+        (&text_rx, &mut deferred_text, &mut current_text),
+        &voice_change_ack,
+        None,
+        None,
+    ));
+    acknowledge_voice_change(&voice_change_ack, &voice_cancel);
+    acknowledged.blocking_recv().expect("voice change ack");
+
+    assert_eq!(
+        deferred_text
+            .pop_front()
+            .expect("preserved post-change message")
+            .text,
+        "new message"
+    );
+    assert_eq!(
+        deferred_text
+            .pop_front()
+            .expect("later post-change message")
+            .text,
+        "later new message"
+    );
+    assert!(text_rx.try_recv().is_err());
+}
+
+#[test]
+fn superseding_voice_change_removes_earlier_deferred_messages() {
+    let selected_voice = std::sync::Mutex::new("reference_sample".to_string());
+    let voice_generation = AtomicU64::new(1);
+    let barge_in = AtomicBool::new(false);
+    let voice_cancel = AtomicBool::new(false);
+    let voice_change_ack = Arc::new(std::sync::Mutex::new(None));
+    let (_text_tx, text_rx) = std::sync::mpsc::channel();
+    let shutdown = AtomicBool::new(false);
+    let active = AtomicBool::new(true);
+    let mut deferred_text = VecDeque::new();
+    let mut current_text = None;
+
+    let first = begin_voice_change(
+        &selected_voice,
+        &voice_generation,
+        &voice_cancel,
+        &voice_change_ack,
+        "eve",
+    )
+    .expect("first voice change");
+    deferred_text.push_back(QueuedText {
+        generation: voice_generation.load(Ordering::Acquire),
+        route_id: 4,
+        text: "message for Eve".to_string(),
+    });
+    assert!(handle_cancel_or_shutdown(
+        (&barge_in, &voice_cancel),
+        &shutdown,
+        &active,
+        (&text_rx, &mut deferred_text, &mut current_text),
+        &voice_change_ack,
+        None,
+        None,
+    ));
+    acknowledge_voice_change(&voice_change_ack, &voice_cancel);
+    first.blocking_recv().expect("first acknowledgement");
+
+    let _second = begin_voice_change(
+        &selected_voice,
+        &voice_generation,
+        &voice_cancel,
+        &voice_change_ack,
+        "reference_sample",
+    )
+    .expect("second voice change");
+    assert!(handle_cancel_or_shutdown(
+        (&barge_in, &voice_cancel),
+        &shutdown,
+        &active,
+        (&text_rx, &mut deferred_text, &mut current_text),
+        &voice_change_ack,
+        None,
+        None,
+    ));
+
+    assert!(deferred_text.is_empty());
+}
+
+#[test]
+fn barge_in_clears_deferred_voice_change_messages() {
+    let barge_in = AtomicBool::new(true);
+    let voice_cancel = AtomicBool::new(false);
+    let shutdown = AtomicBool::new(false);
+    let active = AtomicBool::new(true);
+    let voice_change_ack = Arc::new(std::sync::Mutex::new(None));
+    let (_text_tx, text_rx) = std::sync::mpsc::channel();
+    let mut deferred_text = VecDeque::from([QueuedText {
+        generation: 2,
+        route_id: 5,
+        text: "deferred message".to_string(),
+    }]);
+    let mut current_text = None;
+
+    assert!(handle_cancel_or_shutdown(
+        (&barge_in, &voice_cancel),
+        &shutdown,
+        &active,
+        (&text_rx, &mut deferred_text, &mut current_text),
+        &voice_change_ack,
+        None,
+        None,
+    ));
+
+    assert!(deferred_text.is_empty());
+}
+
+#[test]
+fn barge_in_during_a_voice_change_clears_post_change_messages() {
+    let selected_voice = std::sync::Mutex::new("reference_sample".to_string());
+    let voice_generation = AtomicU64::new(1);
+    let barge_in = AtomicBool::new(false);
+    let voice_cancel = AtomicBool::new(false);
+    let voice_change_ack = Arc::new(std::sync::Mutex::new(None));
+    let (_text_tx, text_rx) = std::sync::mpsc::channel();
+    let shutdown = AtomicBool::new(false);
+    let active = AtomicBool::new(true);
+    let mut deferred_text = VecDeque::new();
+    let mut current_text = None;
+
+    let _acknowledged = begin_voice_change(
+        &selected_voice,
+        &voice_generation,
+        &voice_cancel,
+        &voice_change_ack,
+        "eve",
+    )
+    .expect("voice change");
+    deferred_text.push_back(QueuedText {
+        generation: voice_generation.load(Ordering::Acquire),
+        route_id: 6,
+        text: "post-change message".to_string(),
+    });
+    barge_in.store(true, Ordering::Release);
+
+    assert!(handle_cancel_or_shutdown(
+        (&barge_in, &voice_cancel),
+        &shutdown,
+        &active,
+        (&text_rx, &mut deferred_text, &mut current_text),
+        &voice_change_ack,
+        None,
+        None,
+    ));
+    assert!(deferred_text.is_empty());
+}
+
+#[test]
+fn a_sender_captured_before_voice_change_is_stale_even_if_it_sends_after_drain() {
+    let selected_voice = std::sync::Mutex::new("reference_sample".to_string());
+    let voice_generation = Arc::new(AtomicU64::new(1));
+    let barge_in = AtomicBool::new(false);
+    let voice_cancel = AtomicBool::new(false);
+    let voice_change_ack = Arc::new(std::sync::Mutex::new(None));
+    let (text_tx, text_rx) = std::sync::mpsc::sync_channel(1);
+    let old_sender = TtsTextSender {
+        text_tx,
+        generation: voice_generation.load(Ordering::Acquire),
+    };
+    let shutdown = AtomicBool::new(false);
+    let active = AtomicBool::new(true);
+    let mut deferred_text = VecDeque::new();
+    let mut current_text = None;
+
+    let _acknowledged = begin_voice_change(
+        &selected_voice,
+        &voice_generation,
+        &voice_cancel,
+        &voice_change_ack,
+        "eve",
+    )
+    .expect("voice change");
+    assert!(handle_cancel_or_shutdown(
+        (&barge_in, &voice_cancel),
+        &shutdown,
+        &active,
+        (&text_rx, &mut deferred_text, &mut current_text),
+        &voice_change_ack,
+        None,
+        None,
+    ));
+    old_sender
+        .send(7, "late old message".to_string())
+        .expect("late send");
+    let late = text_rx.recv().expect("late queued text");
+
+    assert!(late.generation < voice_generation.load(Ordering::Acquire));
+}
diff --git a/desktop/src-tauri/src/huddle/tts_voice_transition.rs b/desktop/src-tauri/src/huddle/tts_voice_transition.rs
new file mode 100644
index 0000000000..81b33672d3
--- /dev/null
+++ b/desktop/src-tauri/src/huddle/tts_voice_transition.rs
@@ -0,0 +1,206 @@
+use std::{
+    collections::VecDeque,
+    path::Path,
+    sync::{
+        atomic::{AtomicBool, AtomicU64, Ordering},
+        mpsc::{self, SyncSender},
+        Arc, Mutex,
+    },
+};
+
+use crate::huddle::pocket::{load_voice_style, VoiceStyle, DEFAULT_VOICE, VOICE_FILE_EXT};
+
+#[derive(Debug)]
+pub(super) struct PendingVoiceChange {
+    pub(super) generation: u64,
+    acknowledged: tokio::sync::oneshot::Sender<()>,
+}
+
+pub(super) type VoiceChangeAck = Arc<Mutex<Option<PendingVoiceChange>>>;
+pub(super) type WorkerVoiceState = (Arc<Mutex<String>>, Arc<AtomicU64>, VoiceChangeAck);
+pub(super) type WorkerCancelSignals = (Arc<AtomicBool>, Arc<AtomicBool>);
+pub(super) type CancelTextState<'a> = (
+    &'a mpsc::Receiver<QueuedText>,
+    &'a mut VecDeque<QueuedText>,
+    &'a mut Option<QueuedText>,
+);
+pub(super) type CancelSignals<'a> = (&'a AtomicBool, &'a AtomicBool);
+
+#[derive(Debug)]
+pub(super) struct QueuedText {
+    pub(super) generation: u64,
+    pub(super) route_id: u64,
+    pub(super) text: String,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct TtsTextSender {
+    pub(super) text_tx: SyncSender<QueuedText>,
+    pub(super) generation: u64,
+}
+
+impl TtsTextSender {
+    pub(crate) fn send(&self, route_id: u64, text: String) -> Result<(), String> {
+        self.text_tx
+            .send(QueuedText {
+                generation: self.generation,
+                route_id,
+                text,
+            })
+            .map_err(|error| error.to_string())
+    }
+}
+
+pub(super) fn begin_voice_change(
+    selected_voice: &Mutex<String>,
+    voice_generation: &AtomicU64,
+    voice_cancel: &AtomicBool,
+    voice_change_ack: &VoiceChangeAck,
+    voice: &str,
+) -> Option<tokio::sync::oneshot::Receiver<()>> {
+    let mut pending_ack = voice_change_ack
+        .lock()
+        .unwrap_or_else(|error| error.into_inner());
+    let mut selected = selected_voice
+        .lock()
+        .unwrap_or_else(|error| error.into_inner());
+    if selected.as_str() == voice {
+        return None;
+    }
+
+    let (sender, receiver) = tokio::sync::oneshot::channel();
+    voice_cancel.store(true, Ordering::Release);
+    let generation = voice_generation.fetch_add(1, Ordering::AcqRel) + 1;
+    if let Some(superseded) = pending_ack.replace(PendingVoiceChange {
+        generation,
+        acknowledged: sender,
+    }) {
+        let _ = superseded.acknowledged.send(());
+    }
+    *selected = voice.to_string();
+    Some(receiver)
+}
+
+pub(super) fn acknowledge_voice_change(
+    voice_change_ack: &VoiceChangeAck,
+    voice_cancel: &AtomicBool,
+) {
+    let mut pending_ack = voice_change_ack
+        .lock()
+        .unwrap_or_else(|error| error.into_inner());
+    if voice_cancel.load(Ordering::Acquire) {
+        return;
+    }
+    if let Some(pending) = pending_ack.take() {
+        let _ = pending.acknowledged.send(());
+    }
+}
+
+pub(super) fn finish_voice_change_ack(voice_change_ack: &VoiceChangeAck) {
+    if let Some(pending) = voice_change_ack
+        .lock()
+        .unwrap_or_else(|error| error.into_inner())
+        .take()
+    {
+        let _ = pending.acknowledged.send(());
+    }
+}
+
+pub(super) fn reconcile_selected_voice(
+    model_dir: &Path,
+    selected_voice: &Mutex<String>,
+    voice_name: &mut String,
+    style: &mut VoiceStyle,
+) -> bool {
+    let requested_voice = selected_voice
+        .lock()
+        .unwrap_or_else(|error| error.into_inner())
+        .clone();
+    if requested_voice == *voice_name {
+        return true;
+    }
+
+    let requested_path = voice_path(model_dir, &requested_voice);
+    match load_voice_style(&requested_path) {
+        Ok(requested_style) => {
+            *style = requested_style;
+            *voice_name = requested_voice;
+            true
+        }
+        Err(_) => {
+            eprintln!("buzz-desktop: tts stage=voice_switch status=fallback reason=voice_style");
+            let fallback_path = model_dir.join(format!("{DEFAULT_VOICE}.{VOICE_FILE_EXT}"));
+            match load_voice_style(&fallback_path) {
+                Ok(fallback_style) => {
+                    *style = fallback_style;
+                    *voice_name = DEFAULT_VOICE.to_string();
+                    *selected_voice
+                        .lock()
+                        .unwrap_or_else(|lock_error| lock_error.into_inner()) =
+                        DEFAULT_VOICE.to_string();
+                    true
+                }
+                Err(_) => {
+                    eprintln!(
+                        "buzz-desktop: tts stage=voice_switch status=failed reason=fallback_voice_style"
+                    );
+                    false
+                }
+            }
+        }
+    }
+}
+
+pub(super) fn voice_path(model_dir: &Path, voice: &str) -> std::path::PathBuf {
+    let path = Path::new(voice);
+    if path.is_absolute() {
+        path.to_path_buf()
+    } else {
+        model_dir.join(format!("{voice}.{VOICE_FILE_EXT}"))
+    }
+}
+
+pub(super) fn retain_cancelled_text(
+    deferred_text: &mut VecDeque<QueuedText>,
+    current_text: &mut Option<QueuedText>,
+    text_rx: &mpsc::Receiver<QueuedText>,
+    preserve_generation: Option<u64>,
+) {
+    if let Some(generation) = preserve_generation {
+        deferred_text.retain(|text| {
+            let preserve = text.generation >= generation;
+            if !preserve {
+                log_cancelled_route(text.route_id, "voice_switch");
+            }
+            preserve
+        });
+        if let Some(text) = current_text.take() {
+            if text.generation >= generation {
+                deferred_text.push_front(text);
+            } else {
+                log_cancelled_route(text.route_id, "voice_switch");
+            }
+        }
+        while let Ok(text) = text_rx.try_recv() {
+            if text.generation >= generation {
+                deferred_text.push_back(text);
+            } else {
+                log_cancelled_route(text.route_id, "voice_switch");
+            }
+        }
+    } else {
+        for text in deferred_text.drain(..) {
+            log_cancelled_route(text.route_id, "barge_in");
+        }
+        if let Some(text) = current_text.take() {
+            log_cancelled_route(text.route_id, "barge_in");
+        }
+        while let Ok(text) = text_rx.try_recv() {
+            log_cancelled_route(text.route_id, "barge_in");
+        }
+    }
+}
+
+fn log_cancelled_route(route_id: u64, reason: &str) {
+    eprintln!("buzz-desktop: tts stage=queue status=dropped reason={reason} route_id={route_id}");
+}
diff --git a/desktop/src-tauri/src/identity_storage.rs b/desktop/src-tauri/src/identity_storage.rs
new file mode 100644
index 0000000000..b39c1a0331
--- /dev/null
+++ b/desktop/src-tauri/src/identity_storage.rs
@@ -0,0 +1,62 @@
+use nostr::Keys;
+
+use crate::app_state::AppState;
+
+/// Durable location of the active human identity.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[repr(u8)]
+pub(crate) enum IdentityStorage {
+    Ephemeral = 0,
+    SystemKeyring = 1,
+    LocalFile = 2,
+    Environment = 3,
+}
+
+impl IdentityStorage {
+    pub(crate) fn as_str(self) -> &'static str {
+        match self {
+            Self::Ephemeral => "ephemeral",
+            Self::SystemKeyring => "system-keyring",
+            Self::LocalFile => "local-file",
+            Self::Environment => "environment",
+        }
+    }
+
+    fn from_u8(value: u8) -> Self {
+        match value {
+            1 => Self::SystemKeyring,
+            2 => Self::LocalFile,
+            3 => Self::Environment,
+            _ => Self::Ephemeral,
+        }
+    }
+}
+
+impl AppState {
+    pub(crate) fn identity_storage(&self) -> IdentityStorage {
+        IdentityStorage::from_u8(
+            self.identity_storage
+                .load(std::sync::atomic::Ordering::Acquire),
+        )
+    }
+
+    pub(crate) fn set_identity_storage(&self, storage: IdentityStorage) {
+        self.identity_storage
+            .store(storage as u8, std::sync::atomic::Ordering::Release);
+    }
+}
+
+/// Recovery state produced by identity resolution.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum RecoveryState {
+    None,
+    Lost,
+    KeyringLocked,
+}
+
+/// Identity and persistence metadata produced by startup resolution.
+pub(crate) struct ResolvedIdentity {
+    pub(crate) keys: Keys,
+    pub(crate) recovery: RecoveryState,
+    pub(crate) storage: IdentityStorage,
+}
diff --git a/desktop/src-tauri/src/key_backup.rs b/desktop/src-tauri/src/key_backup.rs
new file mode 100644
index 0000000000..f97bf95a67
--- /dev/null
+++ b/desktop/src-tauri/src/key_backup.rs
@@ -0,0 +1,234 @@
+//! NIP-49 encrypted local key backup.
+//!
+//! Creates a password-encrypted `ncryptsec` backup of the user's identity key
+//! for a user-selected local file. The blob is **local-only by contract**: it must
+//! never be transmitted to a relay on any path. That contract is enforced at
+//! runtime by [`crate::egress_guard`] (wired into every relay event-body
+//! constructor and the native websocket send loop) and structurally by the
+//! source-allowlist scan in this module's tests.
+//!
+//! Creation decrypt-verifies the fresh blob against the live identity before
+//! returning it. Portable copies use atomic, owner-only file writes.
+
+use nostr::nips::nip49::{EncryptedSecretKey, KeySecurity};
+use nostr::{FromBech32, Keys, ToBech32};
+
+/// Bech32 prefix of NIP-49 encrypted secret keys. Import routing is
+/// case-insensitive because bech32 permits all-uppercase encodings.
+pub const NCRYPTSEC_HRP: &str = "ncryptsec1";
+
+/// scrypt cost for new backups (2^18 — Gossip's desktop default, ~256 MiB).
+/// The blob self-describes its cost, so this can be raised later without
+/// breaking existing backups.
+pub const BACKUP_LOG_N: u8 = 18;
+
+/// Highest scrypt cost accepted when decrypting an untrusted backup.
+///
+/// NIP-49 intentionally leaves `log_n` client-selected. Capping it at the tier
+/// Buzz itself emits keeps generated and upstream-compatible lower-cost backups
+/// readable without allowing a crafted payload to request unbounded memory
+/// before password authentication.
+pub const MAX_VERIFY_LOG_N: u8 = BACKUP_LOG_N;
+
+/// Filename of the app-managed canonical backup inside the app data dir.
+pub const BACKUP_FILE_NAME: &str = "identity.ncryptsec";
+
+/// Default number of words in a generated backup passphrase. Three words
+/// from a 1296-word list ≈ 31 bits of entropy before the scrypt work factor.
+pub const DEFAULT_PASSPHRASE_WORDS: usize = 3;
+
+/// Bounds for the generator's word-count control. At the lower bound a draw
+/// can fall below [`MIN_PASSPHRASE_LEN`] (three 3-char words), so
+/// [`generate_passphrase`] re-draws until the phrase meets the minimum.
+pub const MIN_PASSPHRASE_WORDS: usize = 3;
+pub const MAX_PASSPHRASE_WORDS: usize = 10;
+
+/// EFF short wordlist 2.0 (1296 words, one per line).
+const WORDLIST: &str = include_str!("assets/eff_short_wordlist_2_0.txt");
+
+/// Minimum length for a user-chosen passphrase.
+pub const MIN_PASSPHRASE_LEN: usize = 12;
+
+/// Encrypt the identity secret key under `password` and verify the result.
+///
+/// Returns the bech32 `ncryptsec1…` string. The fresh blob is decrypted and
+/// its derived pubkey compared to the live identity **before** returning, so
+/// a returned blob is always provably recoverable with the same password.
+pub fn create_backup_blob(keys: &Keys, password: &str, log_n: u8) -> Result<String, String> {
+    let secret_key = keys.secret_key();
+
+    let encrypted = EncryptedSecretKey::new(secret_key, password, log_n, KeySecurity::Unknown)
+        .map_err(|e| format!("encrypt key backup: {e}"))?;
+
+    let ncryptsec = encrypted
+        .to_bech32()
+        .map_err(|e| format!("encode ncryptsec: {e}"))?;
+
+    // Integrity check: decrypt the fresh blob and confirm it recovers the
+    // exact live identity. A corrupted or mis-encrypted blob must never be
+    // shown to the user as a "backup". This is the second, deliberate KDF
+    // invocation of the one-artifact-per-action contract.
+    verify_backup_blob(&ncryptsec, password, &keys.public_key())?;
+
+    Ok(ncryptsec)
+}
+
+/// Decrypt `ncryptsec` with `password` and assert it recovers a key whose
+/// public key equals `expected_pubkey`.
+pub fn verify_backup_blob(
+    ncryptsec: &str,
+    password: &str,
+    expected_pubkey: &nostr::PublicKey,
+) -> Result<(), String> {
+    let encrypted = parse_ncryptsec(ncryptsec)?;
+    let recovered = encrypted
+        .decrypt(password)
+        .map_err(|e| format!("verify key backup (decrypt): {e}"))?;
+    let recovered_keys = Keys::new(recovered);
+    if recovered_keys.public_key() != *expected_pubkey {
+        return Err("verify key backup: decrypted key does not match identity".to_string());
+    }
+    Ok(())
+}
+
+/// Parse a bech32 `ncryptsec1…` string, rejecting anything that is not a
+/// structurally valid NIP-49 payload.
+pub fn parse_ncryptsec(input: &str) -> Result<EncryptedSecretKey, String> {
+    EncryptedSecretKey::from_bech32(input.trim()).map_err(|e| format!("invalid ncryptsec: {e}"))
+}
+
+/// Decrypt an `ncryptsec1…` string with `password` into identity keys.
+pub fn decrypt_ncryptsec(input: &str, password: &str) -> Result<Keys, String> {
+    let encrypted = parse_ncryptsec(input)?;
+    let log_n = encrypted.log_n();
+    if log_n > MAX_VERIFY_LOG_N {
+        return Err(format!(
+            "unsupported backup KDF cost: log_n {log_n} exceeds maximum {MAX_VERIFY_LOG_N}"
+        ));
+    }
+    let secret_key = encrypted
+        .decrypt(password)
+        .map_err(|_| "wrong backup password or damaged key backup".to_string())?;
+    Ok(Keys::new(secret_key))
+}
+
+/// Recover identity keys from either an encrypted NIP-49 backup or the raw
+/// nsec/hex formats accepted before encrypted imports were added.
+pub fn recover_keys_from_input(input: &str, password: Option<&str>) -> Result<Keys, String> {
+    let trimmed = input.trim();
+    let is_ncryptsec = trimmed
+        .get(..NCRYPTSEC_HRP.len())
+        .is_some_and(|prefix| prefix.eq_ignore_ascii_case(NCRYPTSEC_HRP));
+
+    if is_ncryptsec {
+        let password = password.ok_or_else(|| "key backup requires a password".to_string())?;
+        decrypt_ncryptsec(trimmed, password)
+    } else {
+        Keys::parse(trimmed).map_err(|e| format!("Invalid private key: {e}"))
+    }
+}
+
+/// Path of the canonical app-managed backup file.
+pub fn backup_file_path(data_dir: &std::path::Path) -> std::path::PathBuf {
+    data_dir.join(BACKUP_FILE_NAME)
+}
+
+/// Atomically write `ncryptsec` to `path` with owner-only permissions, then
+/// reread and byte-compare. Same crash-safety pattern as
+/// `app_state::save_key_file`.
+pub fn write_backup_file(path: &std::path::Path, ncryptsec: &str) -> Result<(), String> {
+    use atomic_write_file::AtomicWriteFile;
+    use std::io::Write;
+
+    let mut file = AtomicWriteFile::open(path)
+        .map_err(|e| format!("open backup file for atomic write: {e}"))?;
+
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        file.set_permissions(std::fs::Permissions::from_mode(0o600))
+            .map_err(|e| format!("set backup file permissions: {e}"))?;
+    }
+
+    file.write_all(ncryptsec.as_bytes())
+        .map_err(|e| format!("write backup file: {e}"))?;
+    file.commit()
+        .map_err(|e| format!("commit backup file: {e}"))?;
+
+    // Reread and byte-compare: only report success for bytes that are
+    // actually on disk.
+    let on_disk = std::fs::read_to_string(path).map_err(|e| format!("reread backup file: {e}"))?;
+    if on_disk != ncryptsec {
+        return Err("backup file verification failed: on-disk bytes differ".to_string());
+    }
+
+    Ok(())
+}
+
+/// Delete the app-managed backup if present. Missing files are already clean.
+pub fn delete_backup_file(data_dir: &std::path::Path) -> Result<(), String> {
+    let path = backup_file_path(data_dir);
+    match std::fs::remove_file(path) {
+        Ok(()) => Ok(()),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(e) => Err(format!("delete stale backup file: {e}")),
+    }
+}
+
+/// Remove the app-managed backup only when an import changes identities.
+pub fn cleanup_stale_backup(
+    previous: &nostr::PublicKey,
+    new: &nostr::PublicKey,
+    data_dir: &std::path::Path,
+) -> Result<(), String> {
+    if previous != new {
+        delete_backup_file(data_dir)?;
+    }
+    Ok(())
+}
+
+/// Generate a passphrase of `word_count` EFF short-wordlist words joined by
+/// `separator`, using OS entropy.
+///
+/// `word_count` is clamped to `MIN_PASSPHRASE_WORDS..=MAX_PASSPHRASE_WORDS`.
+/// Because a low-word-count draw can land under [`MIN_PASSPHRASE_LEN`]
+/// (e.g. three 3-char words), whole phrases below the minimum are rejected
+/// and re-drawn — the result always passes the same length gate applied to
+/// user-chosen passphrases. Uses rejection sampling for a uniform
+/// distribution over the 1296 words.
+pub fn generate_passphrase(word_count: usize, separator: &str) -> Result<String, String> {
+    let word_count = word_count.clamp(MIN_PASSPHRASE_WORDS, MAX_PASSPHRASE_WORDS);
+    let words: Vec<&str> = WORDLIST.lines().filter(|l| !l.is_empty()).collect();
+    if words.len() != 1296 {
+        return Err(format!(
+            "wordlist corrupted: expected 1296 words, found {}",
+            words.len()
+        ));
+    }
+
+    // At 3 words the under-length probability per draw is small, so a few
+    // attempts always suffice; the cap only guards against a logic bug
+    // becoming an infinite loop.
+    for _ in 0..128 {
+        let mut chosen: Vec<&str> = Vec::with_capacity(word_count);
+        while chosen.len() < word_count {
+            let mut buf = [0u8; 2];
+            getrandom::getrandom(&mut buf).map_err(|e| format!("entropy source: {e}"))?;
+            let value = u16::from_le_bytes(buf);
+            // Rejection sampling: accept only values below the largest
+            // multiple of 1296 that fits in u16 (65536 - 65536 % 1296 = 64800).
+            if value < 64800 {
+                chosen.push(words[(value as usize) % 1296]);
+            }
+        }
+        let phrase = chosen.join(separator);
+        if phrase.chars().count() >= MIN_PASSPHRASE_LEN {
+            return Ok(phrase);
+        }
+    }
+    Err("could not generate a passphrase meeting the minimum length".to_string())
+}
+
+#[cfg(test)]
+#[path = "key_backup_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/key_backup_tests.rs b/desktop/src-tauri/src/key_backup_tests.rs
new file mode 100644
index 0000000000..b9713201e1
--- /dev/null
+++ b/desktop/src-tauri/src/key_backup_tests.rs
@@ -0,0 +1,230 @@
+use super::*;
+
+/// NIP-49 spec vector (same as rust-nostr's upstream test): decrypts with
+/// password "nostr" at our call sites.
+const SPEC_NCRYPTSEC: &str = "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+const SPEC_SECRET_HEX: &str = "3501454135014541350145413501453fefb02227e449e57cf4d3a3ce05378683";
+
+/// Fast scrypt tier for tests. log_n 18 is exercised once in
+/// `round_trip_at_production_cost`.
+const FAST_LOG_N: u8 = 16;
+
+// ── Codec ─────────────────────────────────────────────────────────────────────
+
+#[test]
+fn spec_vector_decrypts_at_our_call_site() {
+    let keys = decrypt_ncryptsec(SPEC_NCRYPTSEC, "nostr").unwrap();
+    assert_eq!(keys.secret_key().to_secret_hex(), SPEC_SECRET_HEX);
+}
+
+#[test]
+fn round_trip_fast_tier() {
+    let keys = Keys::generate();
+    let blob = create_backup_blob(&keys, "correct horse battery", FAST_LOG_N).unwrap();
+    assert!(blob.starts_with("ncryptsec1"));
+    let recovered = decrypt_ncryptsec(&blob, "correct horse battery").unwrap();
+    assert_eq!(recovered.public_key(), keys.public_key());
+}
+
+#[test]
+fn round_trip_at_production_cost() {
+    // One log_n 18 round trip: proves the production constant works end to
+    // end (slow — several seconds — but deliberate; see plan D5).
+    let keys = Keys::generate();
+    let blob = create_backup_blob(&keys, "production cost tier check", BACKUP_LOG_N).unwrap();
+    let recovered = decrypt_ncryptsec(&blob, "production cost tier check").unwrap();
+    assert_eq!(recovered.public_key(), keys.public_key());
+}
+
+#[test]
+fn wrong_password_is_a_friendly_error() {
+    let keys = Keys::generate();
+    let blob = create_backup_blob(&keys, "right password", FAST_LOG_N).unwrap();
+    let err = decrypt_ncryptsec(&blob, "wrong password").unwrap_err();
+    assert_eq!(err, "wrong backup password or damaged key backup");
+}
+
+#[test]
+fn nfkc_cross_form_passphrase_round_trips() {
+    // "é" composed (U+00E9) vs decomposed (e + U+0301): NIP-49 mandates NFKC
+    // normalization, so a passphrase entered in either form must decrypt.
+    let keys = Keys::generate();
+    let composed = "caf\u{00e9} passphrase";
+    let decomposed = "cafe\u{0301} passphrase";
+    assert_ne!(composed, decomposed);
+    let blob = create_backup_blob(&keys, composed, FAST_LOG_N).unwrap();
+    let recovered = decrypt_ncryptsec(&blob, decomposed).unwrap();
+    assert_eq!(recovered.public_key(), keys.public_key());
+}
+
+#[test]
+fn parse_rejects_garbage_and_wrong_hrp() {
+    assert!(parse_ncryptsec("garbage").is_err());
+    assert!(parse_ncryptsec("").is_err());
+    // Valid bech32, wrong HRP (an nsec is not an encrypted backup).
+    let nsec = Keys::generate().secret_key().to_bech32().unwrap();
+    assert!(parse_ncryptsec(&nsec).is_err());
+    // Truncated blob.
+    assert!(parse_ncryptsec(&SPEC_NCRYPTSEC[..SPEC_NCRYPTSEC.len() - 10]).is_err());
+}
+
+#[test]
+fn verify_backup_blob_catches_pubkey_mismatch() {
+    // Corrupted-blob simulation: the blob decrypts fine but recovers a key
+    // that is not the live identity — verification must fail.
+    let other = Keys::generate();
+    let blob = create_backup_blob(&other, "some password", FAST_LOG_N).unwrap();
+    let live = Keys::generate();
+    let err = verify_backup_blob(&blob, "some password", &live.public_key()).unwrap_err();
+    assert!(err.contains("does not match identity"), "{err}");
+}
+
+// ── Import key recovery ───────────────────────────────────────────────────────
+
+#[test]
+fn recover_keys_ncryptsec_happy_path() {
+    let keys = recover_keys_from_input(&format!("  {SPEC_NCRYPTSEC}\n"), Some("nostr")).unwrap();
+    assert_eq!(keys.secret_key().to_secret_hex(), SPEC_SECRET_HEX);
+}
+
+#[test]
+fn recover_keys_ncryptsec_requires_password() {
+    let err = recover_keys_from_input(SPEC_NCRYPTSEC, None).unwrap_err();
+    assert_eq!(err, "key backup requires a password");
+}
+
+#[test]
+fn recover_keys_ncryptsec_wrong_password() {
+    let err = recover_keys_from_input(SPEC_NCRYPTSEC, Some("wrong")).unwrap_err();
+    assert_eq!(err, "wrong backup password or damaged key backup");
+}
+
+#[test]
+fn recover_keys_uppercase_ncryptsec_classifies_as_encrypted() {
+    let upper = SPEC_NCRYPTSEC.to_ascii_uppercase();
+    assert_eq!(
+        recover_keys_from_input(&upper, None).unwrap_err(),
+        "key backup requires a password"
+    );
+    let keys = recover_keys_from_input(&upper, Some("nostr")).unwrap();
+    assert_eq!(keys.secret_key().to_secret_hex(), SPEC_SECRET_HEX);
+
+    let mut mixed = SPEC_NCRYPTSEC.to_string();
+    mixed.replace_range(0..1, "N");
+    let err = recover_keys_from_input(&mixed, Some("nostr")).unwrap_err();
+    assert!(err.contains("invalid ncryptsec"), "{err}");
+}
+
+#[test]
+fn recover_keys_raw_nsec_path_unchanged() {
+    let keys = Keys::generate();
+    let nsec = keys.secret_key().to_bech32().unwrap();
+    let recovered = recover_keys_from_input(&nsec, Some("ignored")).unwrap();
+    assert_eq!(recovered.public_key(), keys.public_key());
+    let recovered = recover_keys_from_input(&nsec, None).unwrap();
+    assert_eq!(recovered.public_key(), keys.public_key());
+    assert!(recover_keys_from_input("garbage", None).is_err());
+}
+
+// ── File lifecycle ────────────────────────────────────────────────────────────
+
+#[test]
+fn write_backup_file_persists_0600_and_verifies() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = backup_file_path(dir.path());
+    write_backup_file(&path, SPEC_NCRYPTSEC).unwrap();
+
+    let on_disk = std::fs::read_to_string(&path).unwrap();
+    assert_eq!(on_disk, SPEC_NCRYPTSEC);
+
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let mode = std::fs::metadata(&path).unwrap().permissions().mode();
+        assert_eq!(mode & 0o777, 0o600, "backup file must be owner-only");
+    }
+}
+
+#[test]
+fn write_backup_file_overwrites_atomically() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = backup_file_path(dir.path());
+    write_backup_file(&path, "ncryptsec1old").unwrap();
+    write_backup_file(&path, SPEC_NCRYPTSEC).unwrap();
+    assert_eq!(std::fs::read_to_string(&path).unwrap(), SPEC_NCRYPTSEC);
+    // No leftover temp files from the atomic write.
+    let entries: Vec<_> = std::fs::read_dir(dir.path())
+        .unwrap()
+        .map(|e| e.unwrap().file_name())
+        .collect();
+    assert_eq!(entries, vec![std::ffi::OsString::from(BACKUP_FILE_NAME)]);
+}
+
+#[test]
+fn delete_backup_file_is_idempotent() {
+    let dir = tempfile::tempdir().unwrap();
+    delete_backup_file(dir.path()).unwrap();
+    let path = backup_file_path(dir.path());
+    write_backup_file(&path, SPEC_NCRYPTSEC).unwrap();
+    delete_backup_file(dir.path()).unwrap();
+    assert!(!path.exists());
+}
+
+#[test]
+fn cleanup_stale_backup_removes_only_on_identity_change() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = backup_file_path(dir.path());
+    let a = Keys::generate().public_key();
+    let b = Keys::generate().public_key();
+
+    write_backup_file(&path, SPEC_NCRYPTSEC).unwrap();
+    cleanup_stale_backup(&a, &a, dir.path()).unwrap();
+    assert!(path.exists(), "same identity must keep the backup");
+
+    cleanup_stale_backup(&a, &b, dir.path()).unwrap();
+    assert!(
+        !path.exists(),
+        "identity change must remove the stale backup"
+    );
+}
+
+#[test]
+fn generated_passphrase_respects_word_count_and_separator() {
+    let words: std::collections::HashSet<&str> =
+        WORDLIST.lines().filter(|l| !l.is_empty()).collect();
+    assert_eq!(words.len(), 1296, "EFF short wordlist 2.0 has 1296 words");
+
+    for (count, separator) in [(3, "-"), (4, "-"), (6, " "), (5, "."), (10, "")] {
+        let phrase = generate_passphrase(count, separator).unwrap();
+        if separator.is_empty() {
+            // No separator to split on; length gate below still applies.
+        } else {
+            let parts: Vec<&str> = phrase.split(separator).collect();
+            assert_eq!(parts.len(), count);
+            for w in &parts {
+                assert!(words.contains(w), "unknown word {w:?}");
+            }
+        }
+        assert!(phrase.chars().count() >= MIN_PASSPHRASE_LEN);
+    }
+}
+
+#[test]
+fn generated_passphrase_clamps_word_count() {
+    // Below the floor: clamped up to MIN_PASSPHRASE_WORDS, never shorter.
+    let phrase = generate_passphrase(1, "-").unwrap();
+    assert_eq!(phrase.split('-').count(), MIN_PASSPHRASE_WORDS);
+    // Above the ceiling: clamped down to MAX_PASSPHRASE_WORDS.
+    let phrase = generate_passphrase(50, "-").unwrap();
+    assert_eq!(phrase.split('-').count(), MAX_PASSPHRASE_WORDS);
+}
+
+#[test]
+fn generated_passphrases_are_not_repeated() {
+    // 3 words × ~10.3 bits each — a collision across 8 draws would indicate a
+    // broken entropy source, not bad luck.
+    let mut seen = std::collections::HashSet::new();
+    for _ in 0..8 {
+        assert!(seen.insert(generate_passphrase(DEFAULT_PASSPHRASE_WORDS, "-").unwrap()));
+    }
+}
diff --git a/desktop/src-tauri/src/lib.rs b/desktop/src-tauri/src/lib.rs
index 35f4eae866..c4b733e3e0 100644
--- a/desktop/src-tauri/src/lib.rs
+++ b/desktop/src-tauri/src/lib.rs
@@ -4,9 +4,13 @@ mod archive;
 mod builderlab;
 mod commands;
 mod deep_link;
+mod egress_guard;
 mod event_sync;
 mod events;
 mod huddle;
+mod identity_storage;
+mod key_backup;
+mod linux_media;
 mod managed_agents;
 mod media_proxy;
 #[cfg(feature = "mesh-llm")]
@@ -28,6 +32,8 @@ mod reset;
 mod secret_store;
 mod shutdown;
 mod templates;
+#[cfg(target_os = "macos")]
+mod tray_menu;
 mod util;
 #[cfg(target_os = "linux")]
 pub mod webkit_rendering;
@@ -59,14 +65,13 @@ use mesh_llm_stubs::*;
 #[cfg(all(feature = "mesh-llm", target_os = "macos"))]
 use shutdown::{hard_exit_after_mesh_shutdown, relaunch_after_mesh_shutdown};
 use shutdown::{is_restart_request, shut_down_app};
-use std::sync::{
-    atomic::{AtomicBool, Ordering},
-    Arc,
-};
-#[cfg(target_os = "macos")]
-use tauri::Listener;
+use std::sync::{atomic::AtomicBool, atomic::Ordering, Arc};
 use tauri::{Emitter, Manager, RunEvent};
+#[cfg(target_os = "macos")]
+use tauri::{Listener, WindowEvent};
 use tauri_plugin_window_state::StateFlags;
+#[cfg(target_os = "macos")]
+use tray_menu::show_main_window;
 
 #[cfg(target_os = "macos")]
 const INITIAL_RENDER_READY_EVENT: &str = "initial-render-ready";
@@ -195,6 +200,11 @@ pub fn run() {
                         return;
                     }
 
+                    // Linux/WebKitGTK needs media-stream settings and a
+                    // permission-request handler for getUserMedia; no-op
+                    // on macOS/Windows.
+                    linux_media::enable_media_capture(&webview);
+
                     // macOS applies the restored geometry asynchronously. Wait
                     // for several identical outer bounds and for React to
                     // commit the startup surface before revealing it.
@@ -360,6 +370,8 @@ pub fn run() {
         .manage(commands::pairing::PairingHandle::new())
         .setup(move |app| {
             let app_handle = app.handle().clone();
+            #[cfg(target_os = "macos")]
+            tray_menu::init(&app_handle)?;
 
             // ── Phase 2: boot-time sentinel wipe ──────────────────────────────
             // Must run before migrations and identity resolution so the wipe
@@ -452,6 +464,18 @@ pub fn run() {
                 *guard = Some(app_handle.clone());
             }
 
+            let (tts_settings, tts_settings_load_error) =
+                huddle::tts_settings::load_for_app(&app_handle);
+            if let Ok(mut guard) = state.huddle_audio.tts.lock() {
+                *guard = tts_settings.clone();
+            }
+            if let Ok(mut guard) = state.huddle_audio.tts_load_error.lock() {
+                *guard = tts_settings_load_error;
+            }
+            if let Ok(mut huddle) = state.huddle_state.lock() {
+                huddle.tts_enabled = tts_settings.agent_text_to_speech;
+            }
+
             // Bring up the runtime-owned shared-compute coordinator before
             // saved agents are restored. Its lifetime is tied to the app, not
             // a UI mount; it publishes discovery and reconciles membership for
@@ -657,6 +681,10 @@ pub fn run() {
             title_bar_double_click,
             get_identity,
             get_nsec,
+            generate_backup_passphrase,
+            create_ncryptsec_backup,
+            verify_ncryptsec_backup,
+            save_ncryptsec_copy,
             import_identity,
             persist_current_identity,
             get_profile,
@@ -820,6 +848,12 @@ pub fn run() {
             update_team,
             delete_team,
             export_agent_snapshot,
+            card_mint_key_status,
+            card_mint_save_openai_key,
+            mint_agent_card,
+            save_agent_card,
+            list_agent_cards,
+            load_agent_card,
             preview_agent_snapshot_import,
             confirm_agent_snapshot_import,
             encode_agent_snapshot_for_send,
@@ -858,6 +892,12 @@ pub fn run() {
             download_voice_models,
             get_model_status,
             set_tts_enabled,
+            huddle::tts_settings::get_tts_settings,
+            huddle::tts_settings::list_voice_registry,
+            huddle::tts_settings::set_pocket_voice,
+            huddle::tts_settings::preview_pocket_voice,
+            huddle::tts_settings::import_pocket_voice,
+            huddle::tts_settings::delete_pocket_voice,
             speak_agent_message,
             add_agent_to_huddle,
             check_pipeline_hotstart,
@@ -895,6 +935,14 @@ pub fn run() {
             archive::read_unindexed_observer_rows,
             is_auto_update_supported,
             set_window_vibrancy,
+            #[cfg(target_os = "macos")]
+            tray_menu::clear_tray_agent_activity,
+            #[cfg(target_os = "macos")]
+            tray_menu::requeue_tray_actions,
+            #[cfg(target_os = "macos")]
+            tray_menu::take_tray_actions,
+            #[cfg(target_os = "macos")]
+            tray_menu::update_tray_agent_activity,
         ])
         .build(tauri::generate_context!())
         .expect("error while building tauri application");
@@ -907,6 +955,22 @@ pub fn run() {
     let run_shutdown_done = Arc::clone(&shutdown_done);
     let restart_requested = Arc::new(AtomicBool::new(false));
     app.run(move |app_handle, event| match event {
+        #[cfg(target_os = "macos")]
+        RunEvent::Reopen { .. } => show_main_window(app_handle),
+        #[cfg(target_os = "macos")]
+        RunEvent::WindowEvent {
+            label,
+            event: WindowEvent::CloseRequested { api, .. },
+            ..
+        } if label == "main" => {
+            // Keep the webview alive so Buzz can be reopened from its tray menu.
+            api.prevent_close();
+            if let Some(window) = app_handle.get_webview_window("main") {
+                if let Err(error) = window.hide() {
+                    eprintln!("buzz-desktop: failed to hide main window: {error}");
+                }
+            }
+        }
         RunEvent::ExitRequested { code, .. } => {
             if is_restart_request(code) {
                 restart_requested.store(true, Ordering::SeqCst);
diff --git a/desktop/src-tauri/src/linux_media.rs b/desktop/src-tauri/src/linux_media.rs
new file mode 100644
index 0000000000..240e2f8a77
--- /dev/null
+++ b/desktop/src-tauri/src/linux_media.rs
@@ -0,0 +1,146 @@
+//! Linux-only: enable media capture (`getUserMedia`) in the WebKitGTK webview.
+//!
+//! On macOS (WKWebView) and Windows (WebView2) the media-permission prompt is
+//! routed to the OS automatically, so microphone/camera capture "just works".
+//! WebKitGTK is different on two counts, and both must be handled or capture
+//! fails on Linux only:
+//!
+//! * `enable-media-stream` is **off by default**, so `navigator.mediaDevices`
+//!   never exposes a working `getUserMedia`; and
+//! * the default `permission-request` handler **denies every request**, so even
+//!   with media-stream on, the call rejects with `NotAllowedError`.
+//!
+//! This module reaches the underlying `webkit2gtk::WebView` via
+//! [`tauri::Webview::with_webview`], enables media-stream, and installs a
+//! `permission-request` handler that is **deny-by-default**: a `UserMedia`
+//! request is allowed only when it comes from a trusted app origin and asks for
+//! an audio and/or video device. Tauri does not restrict navigation by default,
+//! so without the origin check any document that ended up in this webview would
+//! inherit silent mic/camera access for the process lifetime.
+//!
+//! Buzz's AppImage pins `GDK_BACKEND=x11` (see [`crate::webkit_rendering`]),
+//! which is the backend WebKitGTK media capture is reliable on.
+
+/// The origin Tauri serves the packaged app from on Linux.
+/// Consumed only by linux-gated [`enable_media_capture`]; kept compiling on all
+/// platforms so the unit tests run everywhere.
+#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
+const PROD_ORIGIN: &str = "tauri://localhost";
+
+/// The Vite dev-server origin (`devUrl` in `tauri.conf.json`, `strictPort`
+/// 1420 in `vite.config.ts`). Only trusted in debug builds.
+#[cfg(debug_assertions)]
+#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
+const DEV_ORIGIN: &str = "http://localhost:1420";
+
+/// Whether `uri` (the webview's current document URI) is a trusted app origin
+/// allowed to use mic/camera. Matches the origin exactly or as a path prefix so
+/// `tauri://localhost.evil.com` and `http://localhost:14200` do not slip
+/// through. Pure and platform-independent so it can be unit-tested everywhere.
+#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
+fn is_trusted_media_origin(uri: &str) -> bool {
+    fn matches(uri: &str, origin: &str) -> bool {
+        uri == origin
+            || uri
+                .strip_prefix(origin)
+                .is_some_and(|rest| rest.starts_with('/'))
+    }
+
+    if matches(uri, PROD_ORIGIN) {
+        return true;
+    }
+    #[cfg(debug_assertions)]
+    if matches(uri, DEV_ORIGIN) {
+        return true;
+    }
+    false
+}
+
+/// Enable microphone/camera capture for `webview` if it is running on
+/// WebKitGTK. A no-op on every non-Linux target, so callers can invoke it
+/// unconditionally from shared startup code.
+#[cfg(target_os = "linux")]
+pub fn enable_media_capture<R: tauri::Runtime>(webview: &tauri::Webview<R>) {
+    use webkit2gtk::{
+        glib::prelude::Cast, PermissionRequestExt, SettingsExt, UserMediaPermissionRequest,
+        UserMediaPermissionRequestExt, WebViewExt,
+    };
+
+    // `with_webview` runs the closure on the UI thread, which GTK calls
+    // require. It errors only if the platform webview is unavailable.
+    let result = webview.with_webview(|platform_webview| {
+        // On Linux this is the underlying `webkit2gtk::WebView`.
+        let webview = platform_webview.inner();
+
+        if let Some(settings) = WebViewExt::settings(&webview) {
+            settings.set_enable_media_stream(true);
+        }
+
+        // Deny-by-default: allow only mic/camera requests from a trusted app
+        // origin; deny everything else (still returning `true` so WebKit's
+        // auto-deny default does not also run). Non-`UserMedia` requests return
+        // `false` and keep their default handling.
+        webview.connect_permission_request(|wv, request| {
+            let Some(request) = request.downcast_ref::<UserMediaPermissionRequest>() else {
+                return false;
+            };
+
+            let uri = wv.uri().map(|u| u.to_string()).unwrap_or_default();
+            let for_device = request.is_for_audio_device() || request.is_for_video_device();
+
+            if for_device && is_trusted_media_origin(&uri) {
+                request.allow();
+            } else {
+                request.deny();
+            }
+            true
+        });
+    });
+
+    if let Err(error) = result {
+        eprintln!("buzz-desktop: could not enable WebKitGTK media capture: {error}");
+    }
+}
+
+/// No-op stub so shared startup code can call [`enable_media_capture`] on every
+/// platform. macOS and Windows route media permissions through the OS.
+#[cfg(not(target_os = "linux"))]
+pub fn enable_media_capture<R: tauri::Runtime>(_webview: &tauri::Webview<R>) {}
+
+#[cfg(test)]
+mod tests {
+    use super::is_trusted_media_origin;
+
+    #[test]
+    fn allows_production_app_origin() {
+        assert!(is_trusted_media_origin("tauri://localhost"));
+        assert!(is_trusted_media_origin(
+            "tauri://localhost/channels/general"
+        ));
+    }
+
+    #[test]
+    fn denies_untrusted_origins() {
+        assert!(!is_trusted_media_origin(""));
+        assert!(!is_trusted_media_origin("https://evil.example.com"));
+        // Prefix look-alikes must not slip through.
+        assert!(!is_trusted_media_origin("tauri://localhost.evil.com"));
+        assert!(!is_trusted_media_origin("tauri://localhostfoo"));
+    }
+
+    #[cfg(debug_assertions)]
+    #[test]
+    fn allows_dev_origin_in_debug_only() {
+        assert!(is_trusted_media_origin("http://localhost:1420"));
+        assert!(is_trusted_media_origin("http://localhost:1420/"));
+        // A different localhost port is still untrusted.
+        assert!(!is_trusted_media_origin("http://localhost:14200"));
+        assert!(!is_trusted_media_origin("http://localhost:3000"));
+    }
+
+    #[cfg(not(debug_assertions))]
+    #[test]
+    fn denies_dev_origin_in_release() {
+        assert!(!is_trusted_media_origin("http://localhost:1420"));
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/agent_snapshot.rs b/desktop/src-tauri/src/managed_agents/agent_snapshot.rs
index 16a0d35b23..7c08e7095f 100644
--- a/desktop/src-tauri/src/managed_agents/agent_snapshot.rs
+++ b/desktop/src-tauri/src/managed_agents/agent_snapshot.rs
@@ -306,9 +306,22 @@ pub fn encode_snapshot_png(
         );
     }
 
-    // Manifest → JSON → base64 for the tEXt chunk payload.
+    // Manifest → JSON for the tEXt chunk payload. The payload/PNG composition
+    // is shared with the locked-card encoder in `agent_snapshot_envelope`;
+    // plain cards remain byte-identical to the pre-envelope encoder.
     let json_bytes = encode_snapshot_json(snapshot)?;
-    let chunk_text = STANDARD.encode(&json_bytes);
+    encode_chunk_payload_png(&json_bytes, avatar_bytes)
+}
+
+/// Encode arbitrary chunk-payload JSON (plain manifest or locked envelope)
+/// into a PNG carrying it base64-encoded in the `buzz_agent_snapshot` tEXt
+/// chunk. Shared by the plain encoder above and
+/// `agent_snapshot_envelope::encode_locked_snapshot_png`.
+pub(crate) fn encode_chunk_payload_png(
+    json_bytes: &[u8],
+    avatar_bytes: Option<&[u8]>,
+) -> Result<Vec<u8>, String> {
+    let chunk_text = STANDARD.encode(json_bytes);
 
     // Use the avatar as the PNG image body, transcoding decodable non-PNG
     // avatars. Fall back to a minimal 1×1 transparent placeholder only when
@@ -334,8 +347,11 @@ pub fn encode_snapshot_png(
     Ok(png_bytes)
 }
 
-/// Decode a manifest from a `.agent.png` tEXt chunk.
-pub fn decode_snapshot_png(png_bytes: &[u8]) -> Result<AgentSnapshot, String> {
+/// Extract and base64-decode the raw `buzz_agent_snapshot` chunk payload
+/// (JSON bytes) from a PNG, without interpreting it. The payload may be a
+/// plain manifest or a locked envelope — callers dispatch on the parsed
+/// `format` via `agent_snapshot_envelope::parse_chunk_payload`.
+pub(crate) fn extract_chunk_payload_png(png_bytes: &[u8]) -> Result<Vec<u8>, String> {
     let decoder = Decoder::new(Cursor::new(png_bytes));
     let reader = decoder
         .read_info()
@@ -349,10 +365,18 @@ pub fn decode_snapshot_png(png_bytes: &[u8]) -> Result<AgentSnapshot, String> {
         .map(|c| c.text.as_str())
         .ok_or_else(|| "PNG does not contain a buzz_agent_snapshot tEXt chunk".to_string())?;
 
-    let json_bytes = STANDARD
+    STANDARD
         .decode(chunk_text.trim())
-        .map_err(|e| format!("Invalid base64 in PNG chunk: {e}"))?;
+        .map_err(|e| format!("Invalid base64 in PNG chunk: {e}"))
+}
 
+/// Decode a manifest from a `.agent.png` tEXt chunk.
+///
+/// Plain snapshots only — a locked (encrypted) chunk payload fails here with
+/// the manifest format error. Import paths that must handle locked cards go
+/// through `agent_snapshot_envelope::parse_chunk_payload` instead.
+pub fn decode_snapshot_png(png_bytes: &[u8]) -> Result<AgentSnapshot, String> {
+    let json_bytes = extract_chunk_payload_png(png_bytes)?;
     decode_snapshot_json(&json_bytes)
 }
 
@@ -473,527 +497,5 @@ fn inject_text_chunk(png_bytes: &[u8], keyword: &str, text: &str) -> Result<Vec<
 // ── Tests ─────────────────────────────────────────────────────────────────────
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::managed_agents::types::{BackendKind, ManagedAgentRecord, RespondTo};
-    use std::collections::BTreeMap;
-
-    /// Build a minimal `ManagedAgentRecord` for testing. Only the fields
-    /// relevant to snapshot export are filled; the rest use defaults.
-    fn minimal_record() -> ManagedAgentRecord {
-        ManagedAgentRecord {
-            pubkey: "deadbeef".to_string(),
-            name: "Test Agent".to_string(),
-            display_name: Some("Test Agent Display".to_string()),
-            persona_id: Some("SENTINEL_PERSONA_ID".to_string()), // MUST NOT appear in snapshot
-            team_id: Some("SENTINEL_TEAM_ID".to_string()),       // MUST NOT appear in snapshot
-            private_key_nsec: "nsec1secret".to_string(),         // MUST NOT appear in snapshot
-            auth_tag: Some("auth-tag-secret".to_string()),       // MUST NOT appear in snapshot
-            relay_url: "wss://relay.example.com".to_string(),    // MUST NOT appear in snapshot
-            avatar_url: Some("https://example.com/avatar.png".to_string()),
-            acp_command: "/usr/local/bin/acp".to_string(), // MUST NOT appear in snapshot
-            agent_command: "goose".to_string(),            // MUST NOT appear in snapshot
-            agent_command_override: Some("goose-override".to_string()), // MUST NOT appear
-            agent_args: vec!["--arg".to_string()],         // MUST NOT appear in snapshot
-            mcp_command: "mcp-server".to_string(),         // MUST NOT appear in snapshot
-            turn_timeout_seconds: 120,                     // deprecated, MUST NOT appear
-            idle_timeout_seconds: Some(30),
-            max_turn_duration_seconds: Some(600),
-            parallelism: 2,
-            system_prompt: Some("You are a test agent.".to_string()),
-            model: Some("claude-opus-4".to_string()),
-            provider: Some("anthropic".to_string()),
-            persona_source_version: Some("v1.0".to_string()), // MUST NOT appear
-            env_vars: {
-                let mut m = BTreeMap::new();
-                m.insert("API_KEY".to_string(), "secret123".to_string()); // MUST NOT appear
-                m
-            },
-            start_on_app_launch: true,
-            auto_restart_on_config_change: true,
-            runtime_pid: Some(12345), // MUST NOT appear
-            backend: BackendKind::Provider {
-                // MUST NOT appear — carries a provider secret
-                id: "SENTINEL_BACKEND_ID".to_string(),
-                config: serde_json::json!({"api_key": "SENTINEL_BACKEND_SECRET"}),
-            },
-            backend_agent_id: Some("SENTINEL_BACKEND_AGENT_ID".to_string()), // MUST NOT appear
-            provider_binary_path: Some("/usr/bin/SENTINEL_PROVIDER_BINARY".to_string()), // MUST NOT appear
-            persona_team_dir: Some(std::path::PathBuf::from("SENTINEL_TEAM_DIR")), // MUST NOT appear
-            persona_name_in_team: Some("SENTINEL_NAME_IN_TEAM".to_string()), // MUST NOT appear
-            created_at: "2024-01-01T00:00:00Z".to_string(),
-            updated_at: "2024-01-02T00:00:00Z".to_string(),
-            last_started_at: Some("2024-01-03T00:00:00Z".to_string()), // MUST NOT appear
-            last_stopped_at: None,
-            last_exit_code: Some(0), // MUST NOT appear
-            last_error: Some("SENTINEL_LAST_ERROR".to_string()), // MUST NOT appear
-            last_error_code: Some(42), // MUST NOT appear
-            respond_to: RespondTo::default(),
-            respond_to_allowlist: vec!["pubkey1hex".to_string()],
-            slug: Some("test-agent".to_string()),
-            runtime: Some("goose".to_string()),
-            name_pool: vec!["Alice".to_string(), "Bob".to_string()],
-            is_builtin: false,
-            is_active: true,
-            shared: false,
-            source_team: Some("team-id-123".to_string()), // MUST NOT appear
-            source_team_persona_slug: Some("lep".to_string()), // MUST NOT appear
-            definition_respond_to: Some("allowlist".to_string()),
-            catalog_source: None,
-            definition_respond_to_allowlist: vec!["abc123def".to_string()],
-            definition_parallelism: Some(4),
-            relay_mesh: None,
-        }
-    }
-
-    // ── Round-trip tests ──────────────────────────────────────────────────────
-
-    #[test]
-    fn json_round_trip_config_only() {
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
-        let bytes = encode_snapshot_json(&snapshot).unwrap();
-        let parsed = decode_snapshot_json(&bytes).unwrap();
-        assert_eq!(parsed, snapshot);
-    }
-
-    #[test]
-    fn json_round_trip_with_memory() {
-        let record = minimal_record();
-        let entries = vec![
-            AgentSnapshotMemoryEntry {
-                slug: "core".to_string(),
-                body: "I am a test agent.".to_string(),
-            },
-            AgentSnapshotMemoryEntry {
-                slug: "mem/research".to_string(),
-                body: "Some research notes.".to_string(),
-            },
-        ];
-        let snapshot = build_snapshot(&record, MemoryLevel::Everything, entries, None);
-        let bytes = encode_snapshot_json(&snapshot).unwrap();
-        let parsed = decode_snapshot_json(&bytes).unwrap();
-        assert_eq!(parsed, snapshot);
-    }
-
-    #[test]
-    fn png_round_trip_no_memory() {
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
-        let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
-        let parsed = decode_snapshot_png(&png_bytes).unwrap();
-        assert_eq!(parsed.definition.name, snapshot.definition.name);
-        assert_eq!(parsed.profile.display_name, snapshot.profile.display_name);
-        assert_eq!(parsed.memory.level, MemoryLevel::None);
-    }
-
-    #[test]
-    fn png_round_trip_with_avatar_png() {
-        // Build a minimal PNG avatar.
-        let avatar = make_png_with_text("dummy", "value").unwrap();
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&avatar));
-        // Avatar should be inlined as a data URL.
-        assert!(snapshot
-            .profile
-            .avatar_data_url
-            .as_deref()
-            .unwrap_or("")
-            .starts_with("data:image/png;base64,"));
-
-        let png_bytes = encode_snapshot_png(&snapshot, Some(&avatar)).unwrap();
-        let parsed = decode_snapshot_png(&png_bytes).unwrap();
-        assert_eq!(parsed.definition.name, snapshot.definition.name);
-    }
-
-    #[test]
-    fn png_snapshot_transcodes_jpeg_avatar_into_image_body() {
-        let avatar = image::DynamicImage::ImageRgb8(image::RgbImage::from_pixel(
-            3,
-            2,
-            image::Rgb([0x12, 0x34, 0x56]),
-        ));
-        let mut jpeg_bytes = Vec::new();
-        avatar
-            .write_to(&mut Cursor::new(&mut jpeg_bytes), image::ImageFormat::Jpeg)
-            .unwrap();
-
-        let snapshot = build_snapshot(
-            &minimal_record(),
-            MemoryLevel::None,
-            vec![],
-            Some(&jpeg_bytes),
-        );
-        let png_bytes = encode_snapshot_png(&snapshot, Some(&jpeg_bytes)).unwrap();
-        let decoder = Decoder::new(Cursor::new(png_bytes));
-        let reader = decoder.read_info().unwrap();
-
-        assert_eq!((reader.info().width, reader.info().height), (3, 2));
-    }
-
-    // ── PNG memory parity ─────────────────────────────────────────────────────
-
-    #[test]
-    fn png_round_trip_with_core_memory() {
-        let record = minimal_record();
-        let entries = vec![AgentSnapshotMemoryEntry {
-            slug: "core".to_string(),
-            body: "remember this".to_string(),
-        }];
-        let snapshot = build_snapshot(&record, MemoryLevel::Core, entries, None);
-
-        let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
-        let parsed = decode_snapshot_png(&png_bytes).unwrap();
-
-        assert_eq!(parsed.memory, snapshot.memory);
-    }
-
-    #[test]
-    fn png_round_trip_with_everything_memory() {
-        let record = minimal_record();
-        let entries = vec![
-            AgentSnapshotMemoryEntry {
-                slug: "core".to_string(),
-                body: "remember this".to_string(),
-            },
-            AgentSnapshotMemoryEntry {
-                slug: "mem/notes".to_string(),
-                body: "private notes".to_string(),
-            },
-        ];
-        let snapshot = build_snapshot(&record, MemoryLevel::Everything, entries, None);
-
-        let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
-        let parsed = decode_snapshot_png(&png_bytes).unwrap();
-
-        assert_eq!(parsed.memory, snapshot.memory);
-    }
-
-    #[test]
-    fn png_export_with_no_memory_succeeds() {
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
-        assert!(encode_snapshot_png(&snapshot, None).is_ok());
-    }
-
-    #[test]
-    fn png_export_rejects_none_level_with_nonempty_entries() {
-        // Inconsistent state: level == None but entries is non-empty.
-        // The encoder must reject this to prevent a memory-leak bypass.
-        let record = minimal_record();
-        let entries = vec![AgentSnapshotMemoryEntry {
-            slug: "core".to_string(),
-            body: "leaked memory".to_string(),
-        }];
-        // Build with entries, then override level to None in the struct.
-        let mut snapshot = build_snapshot(&record, MemoryLevel::Core, entries, None);
-        snapshot.memory.level = MemoryLevel::None; // force inconsistency
-        let result = encode_snapshot_png(&snapshot, None);
-        assert!(
-            result.is_err(),
-            "PNG encoder must reject level=None with non-empty entries"
-        );
-        assert!(
-            result
-                .unwrap_err()
-                .contains("memory.level 'none' and non-empty memory entries"),
-            "Error must explain the malformed memory state"
-        );
-    }
-
-    // ── Secret exclusion tests ────────────────────────────────────────────────
-    //
-    // These tests assert that every field in the exclusion list is absent from
-    // the serialized snapshot. We serialize to JSON and assert the key is NOT
-    // present.
-
-    fn snapshot_json_string(record: &ManagedAgentRecord) -> String {
-        let snapshot = build_snapshot(record, MemoryLevel::None, vec![], None);
-        let bytes = encode_snapshot_json(&snapshot).unwrap();
-        String::from_utf8(bytes).unwrap()
-    }
-
-    #[test]
-    fn secret_exclusion_private_key_nsec_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("nsec1secret"),
-            "nsec must not appear in snapshot"
-        );
-        assert!(
-            !json.contains("privateKeyNsec") && !json.contains("private_key_nsec"),
-            "privateKeyNsec field must not appear in snapshot"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_auth_tag_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("auth-tag-secret"),
-            "auth_tag value must not appear in snapshot"
-        );
-        assert!(
-            !json.contains("authTag") && !json.contains("auth_tag"),
-            "authTag field must not appear in snapshot"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_env_vars_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("API_KEY") && !json.contains("secret123"),
-            "env_vars content must not appear in snapshot"
-        );
-        assert!(
-            !json.contains("envVars") && !json.contains("env_vars"),
-            "envVars field must not appear in snapshot"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_relay_url_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("wss://relay.example.com"),
-            "relay_url value must not appear in snapshot"
-        );
-        assert!(
-            !json.contains("relayUrl") && !json.contains("relay_url"),
-            "relayUrl field must not appear in snapshot"
-        );
-    }
-
-    #[test]
-    fn snapshot_omits_removed_mcp_toolsets_config() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("mcpToolsets") && !json.contains("mcp_toolsets"),
-            "removed MCP toolsets config must not re-enter snapshots"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_machine_commands_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        // acp_command / agent_command / agent_command_override / agent_args / mcp_command
-        assert!(
-            !json.contains("/usr/local/bin/acp"),
-            "acp_command path must not appear"
-        );
-        assert!(
-            !json.contains("acpCommand") && !json.contains("acp_command"),
-            "acpCommand field must not appear"
-        );
-        assert!(
-            !json.contains("agentCommand") && !json.contains("agent_command"),
-            "agentCommand field must not appear"
-        );
-        assert!(
-            !json.contains("mcpCommand") && !json.contains("mcp_command"),
-            "mcpCommand field must not appear"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_runtime_state_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("runtimePid") && !json.contains("runtime_pid"),
-            "runtimePid must not appear"
-        );
-        assert!(
-            !json.contains("backendAgentId") && !json.contains("backend_agent_id"),
-            "backendAgentId must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_BACKEND_AGENT_ID"),
-            "backendAgentId value must not appear"
-        );
-        assert!(
-            !json.contains("providerBinaryPath") && !json.contains("provider_binary_path"),
-            "providerBinaryPath must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_PROVIDER_BINARY"),
-            "providerBinaryPath value must not appear"
-        );
-        assert!(
-            !json.contains("lastStartedAt") && !json.contains("last_started_at"),
-            "lastStartedAt must not appear"
-        );
-        assert!(
-            !json.contains("lastExitCode") && !json.contains("last_exit_code"),
-            "lastExitCode must not appear"
-        );
-        // backend blob — neither the type tag nor provider secret must leak.
-        assert!(
-            !json.contains("\"backend\"") && !json.contains("backend"),
-            "backend field must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_BACKEND_ID") && !json.contains("SENTINEL_BACKEND_SECRET"),
-            "backend config values must not appear"
-        );
-        // last_error / last_error_code
-        assert!(
-            !json.contains("lastError") && !json.contains("last_error"),
-            "lastError must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_LAST_ERROR"),
-            "lastError value must not appear"
-        );
-        assert!(
-            !json.contains("lastErrorCode") && !json.contains("last_error_code"),
-            "lastErrorCode must not appear"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_lineage_ids_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("team-id-123"),
-            "source_team value must not appear"
-        );
-        assert!(
-            !json.contains("sourceTeam") && !json.contains("source_team"),
-            "sourceTeam field must not appear"
-        );
-        assert!(
-            !json.contains("sourceTeamPersonaSlug"),
-            "sourceTeamPersonaSlug must not appear"
-        );
-        assert!(
-            !json.contains("personaSourceVersion") && !json.contains("persona_source_version"),
-            "personaSourceVersion must not appear"
-        );
-        // personaId
-        assert!(
-            !json.contains("personaId") && !json.contains("persona_id"),
-            "personaId field must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_PERSONA_ID"),
-            "personaId value must not appear"
-        );
-        // teamId
-        assert!(
-            !json.contains("teamId") && !json.contains("team_id"),
-            "teamId field must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_TEAM_ID"),
-            "teamId value must not appear"
-        );
-        // personaTeamDir
-        assert!(
-            !json.contains("personaTeamDir") && !json.contains("persona_team_dir"),
-            "personaTeamDir field must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_TEAM_DIR"),
-            "personaTeamDir value must not appear"
-        );
-        // personaNameInTeam
-        assert!(
-            !json.contains("personaNameInTeam") && !json.contains("persona_name_in_team"),
-            "personaNameInTeam field must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_NAME_IN_TEAM"),
-            "personaNameInTeam value must not appear"
-        );
-    }
-
-    // ── Definition field presence tests ──────────────────────────────────────
-
-    #[test]
-    fn definition_fields_present_in_snapshot() {
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
-
-        assert_eq!(snapshot.definition.name, "Test Agent Display");
-        assert!(!snapshot.definition.source_is_builtin);
-        assert_eq!(
-            snapshot.definition.system_prompt.as_deref(),
-            Some("You are a test agent.")
-        );
-        assert_eq!(snapshot.definition.runtime.as_deref(), Some("goose"));
-        assert_eq!(snapshot.definition.model.as_deref(), Some("claude-opus-4"));
-        assert_eq!(snapshot.definition.provider.as_deref(), Some("anthropic"));
-        assert_eq!(snapshot.definition.name_pool, vec!["Alice", "Bob"]);
-        // definition_respond_to maps to respond_to in the snapshot definition
-        assert_eq!(snapshot.definition.respond_to.as_deref(), Some("allowlist"));
-        // definition_respond_to_allowlist should be included
-        assert!(!snapshot.definition.respond_to_allowlist.is_empty());
-    }
-
-    #[test]
-    fn profile_fields_present_in_snapshot() {
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
-        assert_eq!(snapshot.profile.display_name, "Test Agent Display");
-        // No bytes → should fall back to avatar_url
-        assert_eq!(
-            snapshot.profile.avatar_url.as_deref(),
-            Some("https://example.com/avatar.png")
-        );
-        assert!(snapshot.profile.avatar_data_url.is_none());
-    }
-
-    #[test]
-    fn avatar_inlined_when_under_size_limit() {
-        let record = minimal_record();
-        let small_png = make_png_with_text("k", "v").unwrap();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&small_png));
-        assert!(snapshot.profile.avatar_data_url.is_some());
-        assert!(snapshot.profile.avatar_url.is_none());
-    }
-
-    #[test]
-    fn avatar_url_fallback_when_over_size_limit() {
-        let mut record = minimal_record();
-        record.avatar_url = Some("https://example.com/big.png".to_string());
-        // Synthesize oversized avatar bytes (> 2 MB) — just a large zeroed vec.
-        let big_bytes = vec![0u8; MAX_AVATAR_INLINE_BYTES + 1];
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&big_bytes));
-        assert!(snapshot.profile.avatar_data_url.is_none());
-        assert_eq!(
-            snapshot.profile.avatar_url.as_deref(),
-            Some("https://example.com/big.png")
-        );
-    }
-
-    // ── Format/version validation ─────────────────────────────────────────────
-
-    #[test]
-    fn invalid_format_discriminator_is_rejected() {
-        let mut snapshot = build_snapshot(&minimal_record(), MemoryLevel::None, vec![], None);
-        snapshot.format = "not-a-buzz-snapshot".to_string();
-        let bytes = serde_json::to_vec(&snapshot).unwrap();
-        let result = decode_snapshot_json(&bytes);
-        assert!(result.is_err());
-        assert!(result.unwrap_err().contains("Unsupported snapshot format"));
-    }
-
-    #[test]
-    fn unsupported_version_is_rejected() {
-        let mut snapshot = build_snapshot(&minimal_record(), MemoryLevel::None, vec![], None);
-        snapshot.version = 99;
-        let bytes = serde_json::to_vec(&snapshot).unwrap();
-        let result = decode_snapshot_json(&bytes);
-        assert!(result.is_err());
-        assert!(result.unwrap_err().contains("Unsupported snapshot version"));
-    }
-}
+#[path = "agent_snapshot_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/managed_agents/agent_snapshot_envelope.rs b/desktop/src-tauri/src/managed_agents/agent_snapshot_envelope.rs
new file mode 100644
index 0000000000..8508c27073
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/agent_snapshot_envelope.rs
@@ -0,0 +1,638 @@
+//! Locked (encrypted) agent-card envelope — NIP-44 v2 over the snapshot manifest.
+//!
+//! A locked card carries the same `buzz_agent_snapshot` tEXt chunk as a plain
+//! card, but the chunk JSON is a typed outer envelope whose ciphertext
+//! decrypts to the ordinary manifest. The NIP-44 v2 conversation key is
+//! symmetric over the (owner, agent) pair, so BOTH the owner's and the
+//! agent's nsec decrypt the card — nobody else's does (NIP-AE's scheme).
+//!
+//! Wire contract (agreed with Wren, buzz-agent-trading-cards thread):
+//! - Plain cards keep today's exact bytes; detection dispatches once on the
+//!   exact `format` discriminator and rejects unknown versions/schemes
+//!   rather than falling through to manifest parsing.
+//! - Key lookup is exact-endpoint only: the owner identity key when its
+//!   pubkey equals `ownerPubkey`, or a hydrated local managed-agent record
+//!   whose record pubkey AND derived-secret pubkey equal `agentPubkey`.
+//!   No trial decryption; anything else fails closed as locked.
+//! - Caps beyond the outer 10 MiB PNG gate: 65,535-byte NIP-44 plaintext
+//!   limit on the serialized manifest BEFORE encryption; envelope JSON and
+//!   ciphertext are capped before serde/base64/decrypt work; decrypted bytes
+//!   are capped before snapshot parsing.
+//! - Decrypt/auth failures return only the locked-card refusal — never
+//!   partial plaintext or crypto details.
+
+use buzz_core_pkg::engram::NIP44_PLAINTEXT_MAX;
+use nostr::nips::nip44::{self, Version};
+use nostr::{Keys, PublicKey, SecretKey};
+use serde::{Deserialize, Serialize};
+
+use super::agent_snapshot::{
+    decode_snapshot_json, encode_chunk_payload_png, encode_snapshot_json, AgentSnapshot,
+    MemoryLevel, FORMAT_DISCRIMINATOR,
+};
+use super::types::ManagedAgentRecord;
+
+/// Discriminator for the locked envelope. Distinct from the plain manifest's
+/// `buzz-agent-snapshot` so detection never guesses.
+pub const LOCKED_FORMAT: &str = "buzz-agent-snapshot-encrypted";
+/// Envelope schema version this module produces and accepts.
+pub const LOCKED_VERSION: u32 = 1;
+/// Encryption scheme identifier this module produces and accepts.
+pub const LOCKED_SCHEME: &str = "nip44-v2";
+
+/// A max-size NIP-44 v2 payload (1 version + 32 nonce + 2 len + 65,536
+/// padded + 32 MAC = 65,603 bytes) base64-encodes to 87,472 chars.
+/// Anything larger is rejected before base64/decrypt work.
+pub const MAX_LOCKED_CIPHERTEXT_BYTES: usize = 90_000;
+/// Envelope JSON = ciphertext + two pubkeys + fixed keys. Rejected before
+/// typed deserialization.
+pub const MAX_LOCKED_ENVELOPE_JSON_BYTES: usize = MAX_LOCKED_CIPHERTEXT_BYTES + 1024;
+
+/// The only error a failed unlock may surface. Deliberately says nothing
+/// about which key was tried or why decryption failed.
+pub const LOCKED_CARD_REFUSAL: &str =
+    "This card is locked to its owner and agent. Only they can import it.";
+
+// ── Envelope types ────────────────────────────────────────────────────────────
+
+/// Typed outer envelope stored (base64 JSON) in the `buzz_agent_snapshot`
+/// chunk of a locked card.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct LockedSnapshotEnvelope {
+    /// Always [`LOCKED_FORMAT`].
+    pub format: String,
+    /// Always [`LOCKED_VERSION`].
+    pub version: u32,
+    pub encryption: LockedEncryption,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct LockedEncryption {
+    /// Always [`LOCKED_SCHEME`].
+    pub scheme: String,
+    /// Owner identity pubkey (64 lowercase hex). Plaintext so a decryptor
+    /// knows which counterparty to pair with.
+    pub owner_pubkey: String,
+    /// Agent instance pubkey (64 lowercase hex).
+    pub agent_pubkey: String,
+    /// NIP-44 v2 ciphertext (base64) of the plain manifest JSON.
+    pub ciphertext: String,
+}
+
+/// Result of parsing a chunk payload: either today's plain manifest or a
+/// validated locked envelope. The plain manifest is boxed because it may
+/// inline a multi-KB avatar data URL, dwarfing the envelope variant.
+#[derive(Debug)]
+pub enum ChunkPayload {
+    Plain(Box<AgentSnapshot>),
+    Locked(LockedSnapshotEnvelope),
+}
+
+/// Minimal probe used to read the `format` discriminator without building a
+/// full JSON tree for large plain manifests.
+#[derive(Deserialize)]
+struct FormatProbe {
+    #[serde(default)]
+    format: Option<String>,
+}
+
+// ── Validation ────────────────────────────────────────────────────────────────
+
+/// Canonical pubkey check: exactly 64 lowercase hex chars that parse as a
+/// valid x-only pubkey. Lowercase is required so string comparisons against
+/// record pubkeys (always `to_hex()` output) stay sound. Curve validation is
+/// explicit: nostr's `PublicKey::from_hex` only decodes 32 bytes and defers
+/// lift-x validation to `xonly()`, so a non-point like `"f" * 64` would
+/// otherwise pass structurally and fail only at decrypt time.
+pub(crate) fn parse_canonical_pubkey(field: &str, value: &str) -> Result<PublicKey, String> {
+    if value.len() != 64
+        || !value
+            .chars()
+            .all(|c| c.is_ascii_digit() || ('a'..='f').contains(&c))
+    {
+        return Err(format!(
+            "Locked card envelope has a malformed {field} (expected 64 lowercase hex chars)."
+        ));
+    }
+    let pubkey = PublicKey::from_hex(value)
+        .map_err(|_| format!("Locked card envelope has an invalid {field}."))?;
+    pubkey
+        .xonly()
+        .map_err(|_| format!("Locked card envelope has an invalid {field} (not a curve point)."))?;
+    Ok(pubkey)
+}
+
+/// Structural validation of a locked envelope: exact version + scheme,
+/// canonical pubkeys, distinct endpoints, bounded ciphertext. Does no
+/// key lookup or crypto.
+pub fn validate_envelope(
+    envelope: &LockedSnapshotEnvelope,
+) -> Result<(PublicKey, PublicKey), String> {
+    if envelope.format != LOCKED_FORMAT {
+        return Err(format!(
+            "Unsupported locked card format: {:?} (expected {LOCKED_FORMAT:?})",
+            envelope.format
+        ));
+    }
+    if envelope.version != LOCKED_VERSION {
+        return Err(format!(
+            "Unsupported locked card envelope version: {} (expected {LOCKED_VERSION})",
+            envelope.version
+        ));
+    }
+    if envelope.encryption.scheme != LOCKED_SCHEME {
+        return Err(format!(
+            "Unsupported locked card encryption scheme: {:?} (expected {LOCKED_SCHEME:?})",
+            envelope.encryption.scheme
+        ));
+    }
+    let owner = parse_canonical_pubkey("ownerPubkey", &envelope.encryption.owner_pubkey)?;
+    let agent = parse_canonical_pubkey("agentPubkey", &envelope.encryption.agent_pubkey)?;
+    if owner == agent {
+        return Err("Locked card envelope owner and agent pubkeys must differ.".to_string());
+    }
+    if envelope.encryption.ciphertext.len() > MAX_LOCKED_CIPHERTEXT_BYTES {
+        return Err("Locked card ciphertext exceeds the maximum size.".to_string());
+    }
+    if envelope.encryption.ciphertext.is_empty() {
+        return Err("Locked card ciphertext is empty.".to_string());
+    }
+    Ok((owner, agent))
+}
+
+// ── Dispatch ──────────────────────────────────────────────────────────────────
+
+/// Parse a raw chunk payload (JSON bytes from `extract_chunk_payload_png` or
+/// an `.agent.json` file) and dispatch on the exact `format` discriminator.
+///
+/// - `buzz-agent-snapshot` → full plain-manifest decode + validation.
+/// - `buzz-agent-snapshot-encrypted` → size caps, typed envelope parse,
+///   structural validation. No decryption happens here.
+/// - anything else (including missing `format`) → error, never a fall-through.
+pub fn parse_chunk_payload(json_bytes: &[u8]) -> Result<ChunkPayload, String> {
+    let probe: FormatProbe =
+        serde_json::from_slice(json_bytes).map_err(|e| format!("Invalid snapshot JSON: {e}"))?;
+    match probe.format.as_deref() {
+        Some(f) if f == FORMAT_DISCRIMINATOR => Ok(ChunkPayload::Plain(Box::new(
+            decode_snapshot_json(json_bytes)?,
+        ))),
+        Some(f) if f == LOCKED_FORMAT => {
+            // Cap the envelope JSON before typed deserialization; a locked
+            // envelope is small by construction (unlike plain manifests,
+            // which may inline a multi-MB avatar).
+            if json_bytes.len() > MAX_LOCKED_ENVELOPE_JSON_BYTES {
+                return Err("Locked card envelope exceeds the maximum size.".to_string());
+            }
+            let envelope: LockedSnapshotEnvelope = serde_json::from_slice(json_bytes)
+                .map_err(|e| format!("Invalid locked card envelope: {e}"))?;
+            validate_envelope(&envelope)?;
+            Ok(ChunkPayload::Locked(envelope))
+        }
+        Some(other) => Err(format!("Unsupported snapshot format: {other:?}")),
+        None => Err("Snapshot payload has no format discriminator.".to_string()),
+    }
+}
+
+// ── Encrypt ───────────────────────────────────────────────────────────────────
+
+/// Encrypt a snapshot manifest into a locked envelope under the NIP-44 v2
+/// conversation key for (owner secret, agent pubkey).
+///
+/// Fails clearly (never silently truncates) when the serialized manifest
+/// exceeds the NIP-44 plaintext limit.
+pub fn encrypt_snapshot_envelope(
+    snapshot: &AgentSnapshot,
+    owner_keys: &Keys,
+    agent_pubkey: &PublicKey,
+) -> Result<LockedSnapshotEnvelope, String> {
+    let json_bytes = encode_snapshot_json(snapshot)?;
+    if json_bytes.len() > NIP44_PLAINTEXT_MAX {
+        return Err(format!(
+            "Agent manifest is too large to lock ({} bytes; the encrypted \
+             format caps at {NIP44_PLAINTEXT_MAX}). Reduce the avatar size \
+             or mint an unlocked card.",
+            json_bytes.len()
+        ));
+    }
+    let plaintext = std::str::from_utf8(&json_bytes)
+        .map_err(|e| format!("Manifest JSON was not UTF-8: {e}"))?;
+    let ciphertext = nip44::encrypt(
+        owner_keys.secret_key(),
+        agent_pubkey,
+        plaintext,
+        Version::V2,
+    )
+    .map_err(|e| format!("Failed to encrypt card manifest: {e}"))?;
+
+    Ok(LockedSnapshotEnvelope {
+        format: LOCKED_FORMAT.to_string(),
+        version: LOCKED_VERSION,
+        encryption: LockedEncryption {
+            scheme: LOCKED_SCHEME.to_string(),
+            owner_pubkey: owner_keys.public_key().to_hex(),
+            agent_pubkey: agent_pubkey.to_hex(),
+            ciphertext,
+        },
+    })
+}
+
+/// Encode a snapshot into a LOCKED `.agent.png`: encrypt the manifest into
+/// the envelope, then compose the PNG through the same chunk encoder plain
+/// cards use. Mirrors `encode_snapshot_png`'s structural memory guard.
+pub fn encode_locked_snapshot_png(
+    snapshot: &AgentSnapshot,
+    owner_keys: &Keys,
+    agent_pubkey: &PublicKey,
+    avatar_bytes: Option<&[u8]>,
+) -> Result<Vec<u8>, String> {
+    if snapshot.memory.level == MemoryLevel::None && !snapshot.memory.entries.is_empty() {
+        return Err(
+            "Cannot write a snapshot with memory.level 'none' and non-empty memory entries."
+                .to_string(),
+        );
+    }
+    let envelope = encrypt_snapshot_envelope(snapshot, owner_keys, agent_pubkey)?;
+    let envelope_json = serde_json::to_vec(&envelope)
+        .map_err(|e| format!("Failed to serialize locked card envelope: {e}"))?;
+    encode_chunk_payload_png(&envelope_json, avatar_bytes)
+}
+
+// ── Decrypt ───────────────────────────────────────────────────────────────────
+
+/// Exact-endpoint key resolution (no trial decryption):
+/// - the owner identity secret, only when its pubkey equals `ownerPubkey`;
+/// - a hydrated local managed-agent record whose record pubkey AND
+///   derived-secret pubkey both equal `agentPubkey`.
+///
+/// Returns `None` when neither exact endpoint exists — callers fail closed
+/// with [`LOCKED_CARD_REFUSAL`].
+pub fn resolve_unlock_secret(
+    envelope: &LockedSnapshotEnvelope,
+    owner_keys: Option<&Keys>,
+    records: &[ManagedAgentRecord],
+) -> Option<SecretKey> {
+    if let Some(keys) = owner_keys {
+        if keys.public_key().to_hex() == envelope.encryption.owner_pubkey {
+            return Some(keys.secret_key().clone());
+        }
+    }
+    let record = records
+        .iter()
+        .find(|r| r.pubkey == envelope.encryption.agent_pubkey)?;
+    let agent_keys = Keys::parse(record.private_key_nsec.trim()).ok()?;
+    if agent_keys.public_key().to_hex() != envelope.encryption.agent_pubkey {
+        return None;
+    }
+    Some(agent_keys.secret_key().clone())
+}
+
+/// Decrypt a validated envelope with `my_secret`, which must be one of the
+/// envelope's two exact endpoints (its derived pubkey selects the
+/// counterparty). Returns the decoded, validated snapshot manifest.
+///
+/// Every auth/crypto failure maps to [`LOCKED_CARD_REFUSAL`] — nothing about
+/// the failure mode leaks. Manifest decode errors after a successful decrypt
+/// are surfaced normally (the caller proved key possession).
+pub fn decrypt_envelope(
+    envelope: &LockedSnapshotEnvelope,
+    my_secret: &SecretKey,
+) -> Result<AgentSnapshot, String> {
+    let (owner_pub, agent_pub) = validate_envelope(envelope)?;
+    let my_pub = Keys::new(my_secret.clone()).public_key();
+    let counterparty = if my_pub == owner_pub {
+        agent_pub
+    } else if my_pub == agent_pub {
+        owner_pub
+    } else {
+        return Err(LOCKED_CARD_REFUSAL.to_string());
+    };
+
+    let plaintext = nip44::decrypt(my_secret, &counterparty, &envelope.encryption.ciphertext)
+        .map_err(|_| LOCKED_CARD_REFUSAL.to_string())?;
+    if plaintext.len() > NIP44_PLAINTEXT_MAX {
+        return Err(LOCKED_CARD_REFUSAL.to_string());
+    }
+    decode_snapshot_json(plaintext.as_bytes())
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::managed_agents::agent_snapshot::{
+        extract_chunk_payload_png, AgentSnapshotDefinition, AgentSnapshotMemory,
+        AgentSnapshotProfile, FORMAT_VERSION,
+    };
+
+    fn sample_snapshot() -> AgentSnapshot {
+        AgentSnapshot {
+            format: FORMAT_DISCRIMINATOR.to_string(),
+            version: FORMAT_VERSION,
+            definition: AgentSnapshotDefinition {
+                name: "Locked Test".to_string(),
+                system_prompt: Some("You are a locked test agent.".to_string()),
+                runtime: None,
+                model: None,
+                provider: None,
+                parallelism: Some(1),
+                respond_to: None,
+                respond_to_allowlist: Vec::new(),
+                name_pool: Vec::new(),
+                idle_timeout_seconds: None,
+                max_turn_duration_seconds: None,
+                source_is_builtin: false,
+            },
+            profile: AgentSnapshotProfile {
+                display_name: "Locked Test".to_string(),
+                about: None,
+                avatar_data_url: None,
+                avatar_url: None,
+            },
+            memory: AgentSnapshotMemory {
+                level: MemoryLevel::None,
+                entries: Vec::new(),
+            },
+        }
+    }
+
+    fn owner_agent_keys() -> (Keys, Keys) {
+        (Keys::generate(), Keys::generate())
+    }
+
+    /// Minimal hydrated record for endpoint-resolution tests. Only the
+    /// pubkey/nsec pair matters here.
+    fn record_with_keys(pubkey: String, private_key_nsec: String) -> ManagedAgentRecord {
+        ManagedAgentRecord {
+            pubkey,
+            name: "Locked Test".to_string(),
+            persona_id: None,
+            private_key_nsec,
+            auth_tag: None,
+            relay_url: "ws://localhost:3000".to_string(),
+            avatar_url: None,
+            acp_command: "buzz-acp".to_string(),
+            agent_command: "goose".to_string(),
+            agent_args: vec![],
+            mcp_command: String::new(),
+            turn_timeout_seconds: 300,
+            idle_timeout_seconds: None,
+            max_turn_duration_seconds: None,
+            parallelism: 1,
+            system_prompt: None,
+            model: None,
+            env_vars: std::collections::BTreeMap::new(),
+            start_on_app_launch: false,
+            auto_restart_on_config_change: true,
+            runtime_pid: None,
+            backend: crate::managed_agents::types::BackendKind::Local,
+            backend_agent_id: None,
+            provider_binary_path: None,
+            team_id: None,
+            persona_team_dir: None,
+            persona_name_in_team: None,
+            created_at: String::new(),
+            updated_at: String::new(),
+            last_started_at: None,
+            last_stopped_at: None,
+            last_exit_code: None,
+            last_error: None,
+            last_error_code: None,
+            respond_to: crate::managed_agents::types::RespondTo::OwnerOnly,
+            respond_to_allowlist: vec![],
+            display_name: None,
+            slug: None,
+            runtime: None,
+            name_pool: Vec::new(),
+            is_builtin: false,
+            is_active: true,
+            shared: false,
+            source_team: None,
+            source_team_persona_slug: None,
+            catalog_source: None,
+            definition_respond_to: None,
+            definition_respond_to_allowlist: Vec::new(),
+            definition_parallelism: None,
+            relay_mesh: None,
+            agent_command_override: None,
+            persona_source_version: None,
+            provider: None,
+        }
+    }
+
+    fn locked_envelope() -> (LockedSnapshotEnvelope, Keys, Keys) {
+        let (owner, agent) = owner_agent_keys();
+        let env =
+            encrypt_snapshot_envelope(&sample_snapshot(), &owner, &agent.public_key()).unwrap();
+        (env, owner, agent)
+    }
+
+    #[test]
+    fn owner_secret_decrypts() {
+        let (env, owner, _agent) = locked_envelope();
+        let decoded = decrypt_envelope(&env, owner.secret_key()).unwrap();
+        assert_eq!(decoded, sample_snapshot());
+    }
+
+    #[test]
+    fn agent_secret_decrypts() {
+        let (env, _owner, agent) = locked_envelope();
+        let decoded = decrypt_envelope(&env, agent.secret_key()).unwrap();
+        assert_eq!(decoded, sample_snapshot());
+    }
+
+    #[test]
+    fn unrelated_key_fails_closed_with_refusal_only() {
+        let (env, _owner, _agent) = locked_envelope();
+        let stranger = Keys::generate();
+        let err = decrypt_envelope(&env, stranger.secret_key()).unwrap_err();
+        assert_eq!(err, LOCKED_CARD_REFUSAL);
+    }
+
+    #[test]
+    fn tampered_ciphertext_fails_with_refusal_only() {
+        let (mut env, owner, _agent) = locked_envelope();
+        // Flip a character mid-ciphertext (keep valid base64 alphabet).
+        let mid = env.encryption.ciphertext.len() / 2;
+        let mut bytes = env.encryption.ciphertext.into_bytes();
+        bytes[mid] = if bytes[mid] == b'A' { b'B' } else { b'A' };
+        env.encryption.ciphertext = String::from_utf8(bytes).unwrap();
+        let err = decrypt_envelope(&env, owner.secret_key()).unwrap_err();
+        assert_eq!(err, LOCKED_CARD_REFUSAL);
+    }
+
+    #[test]
+    fn swapped_pubkeys_fail_closed_at_endpoint_resolution() {
+        let (mut env, owner, agent) = locked_envelope();
+        std::mem::swap(
+            &mut env.encryption.owner_pubkey,
+            &mut env.encryption.agent_pubkey,
+        );
+        // The NIP-44 conversation key is symmetric over the pair, so a swap
+        // cannot grant a stranger anything — but it desyncs the routing
+        // hints, and exact-endpoint resolution fails closed rather than
+        // guessing: the owner identity no longer matches `ownerPubkey`, and
+        // no local record holds the pubkey now in `agentPubkey`.
+        assert!(resolve_unlock_secret(&env, Some(&owner), &[]).is_none());
+        let nsec = nostr::ToBech32::to_bech32(agent.secret_key()).unwrap();
+        let record = record_with_keys(agent.public_key().to_hex(), nsec);
+        assert!(resolve_unlock_secret(&env, None, std::slice::from_ref(&record)).is_none());
+    }
+
+    #[test]
+    fn mislabeled_pubkey_fails_decryption_with_refusal_only() {
+        // Replacing `agentPubkey` with a third party's key makes the owner
+        // derive the wrong conversation key — the NIP-44 MAC fails and only
+        // the refusal surfaces.
+        let (mut env, owner, _agent) = locked_envelope();
+        env.encryption.agent_pubkey = Keys::generate().public_key().to_hex();
+        let err = decrypt_envelope(&env, owner.secret_key()).unwrap_err();
+        assert_eq!(err, LOCKED_CARD_REFUSAL);
+    }
+
+    #[test]
+    fn malformed_pubkeys_rejected_structurally() {
+        let (env, _owner, _agent) = locked_envelope();
+
+        let mut short = env.clone();
+        short.encryption.owner_pubkey = "abc123".to_string();
+        assert!(validate_envelope(&short).unwrap_err().contains("malformed"));
+
+        let mut upper = env.clone();
+        upper.encryption.agent_pubkey = upper.encryption.agent_pubkey.to_uppercase();
+        assert!(validate_envelope(&upper).unwrap_err().contains("malformed"));
+
+        // A 64-hex string that is not a curve point (lift-x fails for
+        // x = p-1... all-f) must be rejected STRUCTURALLY — before any key
+        // lookup or decrypt work — per the wire contract.
+        let mut not_a_point = env.clone();
+        not_a_point.encryption.agent_pubkey = "f".repeat(64);
+        assert!(validate_envelope(&not_a_point)
+            .unwrap_err()
+            .contains("not a curve point"));
+
+        let mut same = env;
+        same.encryption.agent_pubkey = same.encryption.owner_pubkey.clone();
+        assert!(validate_envelope(&same).unwrap_err().contains("differ"));
+    }
+
+    #[test]
+    fn unknown_format_version_scheme_rejected() {
+        let (env, ..) = locked_envelope();
+
+        let mut bad_version = env.clone();
+        bad_version.version = 2;
+        assert!(validate_envelope(&bad_version)
+            .unwrap_err()
+            .contains("version"));
+
+        let mut bad_scheme = env.clone();
+        bad_scheme.encryption.scheme = "nip44-v3".to_string();
+        assert!(validate_envelope(&bad_scheme)
+            .unwrap_err()
+            .contains("scheme"));
+
+        // Unknown top-level format never falls through to manifest parsing.
+        let unknown = serde_json::json!({"format": "buzz-agent-snapshot-v9", "version": 1});
+        let err = parse_chunk_payload(unknown.to_string().as_bytes()).unwrap_err();
+        assert!(err.contains("Unsupported snapshot format"), "{err}");
+
+        let missing = serde_json::json!({"version": 1});
+        let err = parse_chunk_payload(missing.to_string().as_bytes()).unwrap_err();
+        assert!(err.contains("no format discriminator"), "{err}");
+    }
+
+    #[test]
+    fn plaintext_cap_enforced_before_encryption() {
+        let (owner, agent) = owner_agent_keys();
+        let mut snapshot = sample_snapshot();
+        // Inflate the manifest beyond the NIP-44 plaintext limit.
+        snapshot.definition.system_prompt = Some("x".repeat(NIP44_PLAINTEXT_MAX));
+        let err = encrypt_snapshot_envelope(&snapshot, &owner, &agent.public_key()).unwrap_err();
+        assert!(err.contains("too large to lock"), "{err}");
+    }
+
+    #[test]
+    fn ciphertext_and_envelope_caps_enforced_before_crypto() {
+        let (mut env, ..) = locked_envelope();
+        env.encryption.ciphertext = "A".repeat(MAX_LOCKED_CIPHERTEXT_BYTES + 1);
+        assert!(validate_envelope(&env)
+            .unwrap_err()
+            .contains("maximum size"));
+
+        // Oversized envelope JSON is rejected before typed deserialization.
+        let huge = format!(
+            r#"{{"format":"{LOCKED_FORMAT}","version":1,"pad":"{}","encryption":{{}}}}"#,
+            "p".repeat(MAX_LOCKED_ENVELOPE_JSON_BYTES)
+        );
+        let err = parse_chunk_payload(huge.as_bytes()).unwrap_err();
+        assert!(err.contains("maximum size"), "{err}");
+    }
+
+    #[test]
+    fn locked_png_round_trips_through_chunk_and_decrypt() {
+        let (owner, agent) = owner_agent_keys();
+        let snapshot = sample_snapshot();
+        let png = encode_locked_snapshot_png(&snapshot, &owner, &agent.public_key(), None).unwrap();
+
+        let payload = extract_chunk_payload_png(&png).unwrap();
+        let ChunkPayload::Locked(env) = parse_chunk_payload(&payload).unwrap() else {
+            panic!("locked PNG must parse as a locked envelope");
+        };
+        // Both endpoints decrypt to the same logical manifest (compare
+        // manifests, never ciphertext — the NIP-44 nonce is random).
+        assert_eq!(
+            decrypt_envelope(&env, owner.secret_key()).unwrap(),
+            snapshot
+        );
+        assert_eq!(
+            decrypt_envelope(&env, agent.secret_key()).unwrap(),
+            snapshot
+        );
+    }
+
+    #[test]
+    fn plain_manifest_dispatches_to_plain() {
+        let json = encode_snapshot_json(&sample_snapshot()).unwrap();
+        let ChunkPayload::Plain(decoded) = parse_chunk_payload(&json).unwrap() else {
+            panic!("plain manifest must parse as Plain");
+        };
+        assert_eq!(*decoded, sample_snapshot());
+    }
+
+    #[test]
+    fn resolve_unlock_secret_owner_exact_endpoint() {
+        let (env, owner, _agent) = locked_envelope();
+        let secret = resolve_unlock_secret(&env, Some(&owner), &[]).unwrap();
+        assert_eq!(&secret, owner.secret_key());
+
+        // A different identity key is NOT tried.
+        let other = Keys::generate();
+        assert!(resolve_unlock_secret(&env, Some(&other), &[]).is_none());
+        assert!(resolve_unlock_secret(&env, None, &[]).is_none());
+    }
+
+    #[test]
+    fn resolve_unlock_secret_agent_requires_record_and_derived_match() {
+        let (env, _owner, agent) = locked_envelope();
+        let nsec = nostr::ToBech32::to_bech32(agent.secret_key()).unwrap();
+
+        let record = record_with_keys(agent.public_key().to_hex(), nsec);
+        let secret = resolve_unlock_secret(&env, None, std::slice::from_ref(&record)).unwrap();
+        assert_eq!(&secret, agent.secret_key());
+
+        // Record pubkey matches but the stored secret derives a DIFFERENT
+        // pubkey → refused (no trial decryption on mismatched material).
+        let mut forged = record.clone();
+        forged.private_key_nsec =
+            nostr::ToBech32::to_bech32(Keys::generate().secret_key()).unwrap();
+        assert!(resolve_unlock_secret(&env, None, std::slice::from_ref(&forged)).is_none());
+
+        // Record for some other agent → not an endpoint.
+        let mut unrelated = record;
+        unrelated.pubkey = Keys::generate().public_key().to_hex();
+        assert!(resolve_unlock_secret(&env, None, std::slice::from_ref(&unrelated)).is_none());
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/agent_snapshot_tests.rs b/desktop/src-tauri/src/managed_agents/agent_snapshot_tests.rs
new file mode 100644
index 0000000000..b4492418e5
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/agent_snapshot_tests.rs
@@ -0,0 +1,599 @@
+//! Unit tests for `managed_agents/agent_snapshot.rs`.
+//!
+//! Kept in a sibling file so `agent_snapshot.rs` stays under the
+//! 1000-line gate; `#[path]`-included from there.
+
+use super::*;
+use crate::managed_agents::types::{BackendKind, ManagedAgentRecord, RespondTo};
+use std::collections::BTreeMap;
+
+/// Build a minimal `ManagedAgentRecord` for testing. Only the fields
+/// relevant to snapshot export are filled; the rest use defaults.
+fn minimal_record() -> ManagedAgentRecord {
+    ManagedAgentRecord {
+        pubkey: "deadbeef".to_string(),
+        name: "Test Agent".to_string(),
+        display_name: Some("Test Agent Display".to_string()),
+        persona_id: Some("SENTINEL_PERSONA_ID".to_string()), // MUST NOT appear in snapshot
+        team_id: Some("SENTINEL_TEAM_ID".to_string()),       // MUST NOT appear in snapshot
+        private_key_nsec: "nsec1secret".to_string(),         // MUST NOT appear in snapshot
+        auth_tag: Some("auth-tag-secret".to_string()),       // MUST NOT appear in snapshot
+        relay_url: "wss://relay.example.com".to_string(),    // MUST NOT appear in snapshot
+        avatar_url: Some("https://example.com/avatar.png".to_string()),
+        acp_command: "/usr/local/bin/acp".to_string(), // MUST NOT appear in snapshot
+        agent_command: "goose".to_string(),            // MUST NOT appear in snapshot
+        agent_command_override: Some("goose-override".to_string()), // MUST NOT appear
+        agent_args: vec!["--arg".to_string()],         // MUST NOT appear in snapshot
+        mcp_command: "mcp-server".to_string(),         // MUST NOT appear in snapshot
+        turn_timeout_seconds: 120,                     // deprecated, MUST NOT appear
+        idle_timeout_seconds: Some(30),
+        max_turn_duration_seconds: Some(600),
+        parallelism: 2,
+        system_prompt: Some("You are a test agent.".to_string()),
+        model: Some("claude-opus-4".to_string()),
+        provider: Some("anthropic".to_string()),
+        persona_source_version: Some("v1.0".to_string()), // MUST NOT appear
+        env_vars: {
+            let mut m = BTreeMap::new();
+            m.insert("API_KEY".to_string(), "secret123".to_string()); // MUST NOT appear
+            m
+        },
+        start_on_app_launch: true,
+        auto_restart_on_config_change: true,
+        runtime_pid: Some(12345), // MUST NOT appear
+        backend: BackendKind::Provider {
+            // MUST NOT appear — carries a provider secret
+            id: "SENTINEL_BACKEND_ID".to_string(),
+            config: serde_json::json!({"api_key": "SENTINEL_BACKEND_SECRET"}),
+        },
+        backend_agent_id: Some("SENTINEL_BACKEND_AGENT_ID".to_string()), // MUST NOT appear
+        provider_binary_path: Some("/usr/bin/SENTINEL_PROVIDER_BINARY".to_string()), // MUST NOT appear
+        persona_team_dir: Some(std::path::PathBuf::from("SENTINEL_TEAM_DIR")), // MUST NOT appear
+        persona_name_in_team: Some("SENTINEL_NAME_IN_TEAM".to_string()),       // MUST NOT appear
+        created_at: "2024-01-01T00:00:00Z".to_string(),
+        updated_at: "2024-01-02T00:00:00Z".to_string(),
+        last_started_at: Some("2024-01-03T00:00:00Z".to_string()), // MUST NOT appear
+        last_stopped_at: None,
+        last_exit_code: Some(0), // MUST NOT appear
+        last_error: Some("SENTINEL_LAST_ERROR".to_string()), // MUST NOT appear
+        last_error_code: Some(42), // MUST NOT appear
+        respond_to: RespondTo::default(),
+        respond_to_allowlist: vec!["pubkey1hex".to_string()],
+        slug: Some("test-agent".to_string()),
+        runtime: Some("goose".to_string()),
+        name_pool: vec!["Alice".to_string(), "Bob".to_string()],
+        is_builtin: false,
+        is_active: true,
+        shared: false,
+        source_team: Some("team-id-123".to_string()), // MUST NOT appear
+        source_team_persona_slug: Some("lep".to_string()), // MUST NOT appear
+        definition_respond_to: Some("allowlist".to_string()),
+        catalog_source: None,
+        definition_respond_to_allowlist: vec!["abc123def".to_string()],
+        definition_parallelism: Some(4),
+        relay_mesh: None,
+    }
+}
+
+// ── Round-trip tests ──────────────────────────────────────────────────────
+
+#[test]
+fn json_round_trip_config_only() {
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+    let bytes = encode_snapshot_json(&snapshot).unwrap();
+    let parsed = decode_snapshot_json(&bytes).unwrap();
+    assert_eq!(parsed, snapshot);
+}
+
+#[test]
+fn json_round_trip_with_memory() {
+    let record = minimal_record();
+    let entries = vec![
+        AgentSnapshotMemoryEntry {
+            slug: "core".to_string(),
+            body: "I am a test agent.".to_string(),
+        },
+        AgentSnapshotMemoryEntry {
+            slug: "mem/research".to_string(),
+            body: "Some research notes.".to_string(),
+        },
+    ];
+    let snapshot = build_snapshot(&record, MemoryLevel::Everything, entries, None);
+    let bytes = encode_snapshot_json(&snapshot).unwrap();
+    let parsed = decode_snapshot_json(&bytes).unwrap();
+    assert_eq!(parsed, snapshot);
+}
+
+#[test]
+fn png_round_trip_no_memory() {
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+    let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
+    let parsed = decode_snapshot_png(&png_bytes).unwrap();
+    assert_eq!(parsed.definition.name, snapshot.definition.name);
+    assert_eq!(parsed.profile.display_name, snapshot.profile.display_name);
+    assert_eq!(parsed.memory.level, MemoryLevel::None);
+}
+
+#[test]
+fn png_round_trip_with_avatar_png() {
+    // Build a minimal PNG avatar.
+    let avatar = make_png_with_text("dummy", "value").unwrap();
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&avatar));
+    // Avatar should be inlined as a data URL.
+    assert!(snapshot
+        .profile
+        .avatar_data_url
+        .as_deref()
+        .unwrap_or("")
+        .starts_with("data:image/png;base64,"));
+
+    let png_bytes = encode_snapshot_png(&snapshot, Some(&avatar)).unwrap();
+    let parsed = decode_snapshot_png(&png_bytes).unwrap();
+    assert_eq!(parsed.definition.name, snapshot.definition.name);
+}
+
+/// Plain-card byte compatibility: `encode_snapshot_png` was refactored
+/// through the shared `encode_chunk_payload_png` when locked cards were
+/// added. Plain cards must emit byte-identical PNGs to the pre-envelope
+/// encoder. This vector reimplements the legacy encoder body verbatim and
+/// asserts equality on all three composition paths: placeholder (no avatar),
+/// PNG-avatar (where tEXt chunk injection ordering matters), and
+/// JPEG-avatar transcode.
+#[test]
+fn plain_encoder_bytes_identical_to_pre_envelope_encoder() {
+    // Verbatim pre-refactor `encode_snapshot_png` body (post memory guard).
+    fn legacy_encode(
+        snapshot: &AgentSnapshot,
+        avatar_bytes: Option<&[u8]>,
+    ) -> Result<Vec<u8>, String> {
+        let json_bytes = encode_snapshot_json(snapshot)?;
+        let chunk_text = STANDARD.encode(&json_bytes);
+        let png_bytes = match avatar_bytes.filter(|bytes| !bytes.is_empty()) {
+            Some(bytes) => {
+                let encoded_avatar = if bytes.starts_with(b"\x89PNG") {
+                    inject_text_chunk(bytes, PNG_CHUNK_KEYWORD, &chunk_text).or_else(|_| {
+                        transcode_avatar_to_png_with_text(bytes, PNG_CHUNK_KEYWORD, &chunk_text)
+                    })
+                } else {
+                    transcode_avatar_to_png_with_text(bytes, PNG_CHUNK_KEYWORD, &chunk_text)
+                };
+                match encoded_avatar {
+                    Ok(png_bytes) => png_bytes,
+                    Err(_) => make_png_with_text(PNG_CHUNK_KEYWORD, &chunk_text)?,
+                }
+            }
+            None => make_png_with_text(PNG_CHUNK_KEYWORD, &chunk_text)?,
+        };
+        Ok(png_bytes)
+    }
+
+    let record = minimal_record();
+
+    // Placeholder path (no avatar).
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+    assert_eq!(
+        encode_snapshot_png(&snapshot, None).unwrap(),
+        legacy_encode(&snapshot, None).unwrap(),
+        "placeholder-path plain PNG bytes must match the pre-envelope encoder"
+    );
+
+    // PNG-avatar path: chunk injected into the avatar image body.
+    let avatar = make_png_with_text("dummy", "value").unwrap();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&avatar));
+    assert_eq!(
+        encode_snapshot_png(&snapshot, Some(&avatar)).unwrap(),
+        legacy_encode(&snapshot, Some(&avatar)).unwrap(),
+        "avatar-path plain PNG bytes must match the pre-envelope encoder"
+    );
+
+    // JPEG-avatar path: transcode-to-PNG composition.
+    let jpeg_avatar = image::DynamicImage::ImageRgb8(image::RgbImage::from_pixel(
+        4,
+        4,
+        image::Rgb([0x10, 0x20, 0x30]),
+    ));
+    let mut jpeg_bytes = Vec::new();
+    jpeg_avatar
+        .write_to(&mut Cursor::new(&mut jpeg_bytes), image::ImageFormat::Jpeg)
+        .unwrap();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&jpeg_bytes));
+    assert_eq!(
+        encode_snapshot_png(&snapshot, Some(&jpeg_bytes)).unwrap(),
+        legacy_encode(&snapshot, Some(&jpeg_bytes)).unwrap(),
+        "transcode-path plain PNG bytes must match the pre-envelope encoder"
+    );
+}
+
+#[test]
+fn png_snapshot_transcodes_jpeg_avatar_into_image_body() {
+    let avatar = image::DynamicImage::ImageRgb8(image::RgbImage::from_pixel(
+        3,
+        2,
+        image::Rgb([0x12, 0x34, 0x56]),
+    ));
+    let mut jpeg_bytes = Vec::new();
+    avatar
+        .write_to(&mut Cursor::new(&mut jpeg_bytes), image::ImageFormat::Jpeg)
+        .unwrap();
+
+    let snapshot = build_snapshot(
+        &minimal_record(),
+        MemoryLevel::None,
+        vec![],
+        Some(&jpeg_bytes),
+    );
+    let png_bytes = encode_snapshot_png(&snapshot, Some(&jpeg_bytes)).unwrap();
+    let decoder = Decoder::new(Cursor::new(png_bytes));
+    let reader = decoder.read_info().unwrap();
+
+    assert_eq!((reader.info().width, reader.info().height), (3, 2));
+}
+
+// ── PNG memory parity ─────────────────────────────────────────────────────
+
+#[test]
+fn png_round_trip_with_core_memory() {
+    let record = minimal_record();
+    let entries = vec![AgentSnapshotMemoryEntry {
+        slug: "core".to_string(),
+        body: "remember this".to_string(),
+    }];
+    let snapshot = build_snapshot(&record, MemoryLevel::Core, entries, None);
+
+    let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
+    let parsed = decode_snapshot_png(&png_bytes).unwrap();
+
+    assert_eq!(parsed.memory, snapshot.memory);
+}
+
+#[test]
+fn png_round_trip_with_everything_memory() {
+    let record = minimal_record();
+    let entries = vec![
+        AgentSnapshotMemoryEntry {
+            slug: "core".to_string(),
+            body: "remember this".to_string(),
+        },
+        AgentSnapshotMemoryEntry {
+            slug: "mem/notes".to_string(),
+            body: "private notes".to_string(),
+        },
+    ];
+    let snapshot = build_snapshot(&record, MemoryLevel::Everything, entries, None);
+
+    let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
+    let parsed = decode_snapshot_png(&png_bytes).unwrap();
+
+    assert_eq!(parsed.memory, snapshot.memory);
+}
+
+#[test]
+fn png_export_with_no_memory_succeeds() {
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+    assert!(encode_snapshot_png(&snapshot, None).is_ok());
+}
+
+#[test]
+fn png_export_rejects_none_level_with_nonempty_entries() {
+    // Inconsistent state: level == None but entries is non-empty.
+    // The encoder must reject this to prevent a memory-leak bypass.
+    let record = minimal_record();
+    let entries = vec![AgentSnapshotMemoryEntry {
+        slug: "core".to_string(),
+        body: "leaked memory".to_string(),
+    }];
+    // Build with entries, then override level to None in the struct.
+    let mut snapshot = build_snapshot(&record, MemoryLevel::Core, entries, None);
+    snapshot.memory.level = MemoryLevel::None; // force inconsistency
+    let result = encode_snapshot_png(&snapshot, None);
+    assert!(
+        result.is_err(),
+        "PNG encoder must reject level=None with non-empty entries"
+    );
+    assert!(
+        result
+            .unwrap_err()
+            .contains("memory.level 'none' and non-empty memory entries"),
+        "Error must explain the malformed memory state"
+    );
+}
+
+// ── Secret exclusion tests ────────────────────────────────────────────────
+//
+// These tests assert that every field in the exclusion list is absent from
+// the serialized snapshot. We serialize to JSON and assert the key is NOT
+// present.
+
+fn snapshot_json_string(record: &ManagedAgentRecord) -> String {
+    let snapshot = build_snapshot(record, MemoryLevel::None, vec![], None);
+    let bytes = encode_snapshot_json(&snapshot).unwrap();
+    String::from_utf8(bytes).unwrap()
+}
+
+#[test]
+fn secret_exclusion_private_key_nsec_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("nsec1secret"),
+        "nsec must not appear in snapshot"
+    );
+    assert!(
+        !json.contains("privateKeyNsec") && !json.contains("private_key_nsec"),
+        "privateKeyNsec field must not appear in snapshot"
+    );
+}
+
+#[test]
+fn secret_exclusion_auth_tag_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("auth-tag-secret"),
+        "auth_tag value must not appear in snapshot"
+    );
+    assert!(
+        !json.contains("authTag") && !json.contains("auth_tag"),
+        "authTag field must not appear in snapshot"
+    );
+}
+
+#[test]
+fn secret_exclusion_env_vars_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("API_KEY") && !json.contains("secret123"),
+        "env_vars content must not appear in snapshot"
+    );
+    assert!(
+        !json.contains("envVars") && !json.contains("env_vars"),
+        "envVars field must not appear in snapshot"
+    );
+}
+
+#[test]
+fn secret_exclusion_relay_url_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("wss://relay.example.com"),
+        "relay_url value must not appear in snapshot"
+    );
+    assert!(
+        !json.contains("relayUrl") && !json.contains("relay_url"),
+        "relayUrl field must not appear in snapshot"
+    );
+}
+
+#[test]
+fn snapshot_omits_removed_mcp_toolsets_config() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("mcpToolsets") && !json.contains("mcp_toolsets"),
+        "removed MCP toolsets config must not re-enter snapshots"
+    );
+}
+
+#[test]
+fn secret_exclusion_machine_commands_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    // acp_command / agent_command / agent_command_override / agent_args / mcp_command
+    assert!(
+        !json.contains("/usr/local/bin/acp"),
+        "acp_command path must not appear"
+    );
+    assert!(
+        !json.contains("acpCommand") && !json.contains("acp_command"),
+        "acpCommand field must not appear"
+    );
+    assert!(
+        !json.contains("agentCommand") && !json.contains("agent_command"),
+        "agentCommand field must not appear"
+    );
+    assert!(
+        !json.contains("mcpCommand") && !json.contains("mcp_command"),
+        "mcpCommand field must not appear"
+    );
+}
+
+#[test]
+fn secret_exclusion_runtime_state_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("runtimePid") && !json.contains("runtime_pid"),
+        "runtimePid must not appear"
+    );
+    assert!(
+        !json.contains("backendAgentId") && !json.contains("backend_agent_id"),
+        "backendAgentId must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_BACKEND_AGENT_ID"),
+        "backendAgentId value must not appear"
+    );
+    assert!(
+        !json.contains("providerBinaryPath") && !json.contains("provider_binary_path"),
+        "providerBinaryPath must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_PROVIDER_BINARY"),
+        "providerBinaryPath value must not appear"
+    );
+    assert!(
+        !json.contains("lastStartedAt") && !json.contains("last_started_at"),
+        "lastStartedAt must not appear"
+    );
+    assert!(
+        !json.contains("lastExitCode") && !json.contains("last_exit_code"),
+        "lastExitCode must not appear"
+    );
+    // backend blob — neither the type tag nor provider secret must leak.
+    assert!(
+        !json.contains("\"backend\"") && !json.contains("backend"),
+        "backend field must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_BACKEND_ID") && !json.contains("SENTINEL_BACKEND_SECRET"),
+        "backend config values must not appear"
+    );
+    // last_error / last_error_code
+    assert!(
+        !json.contains("lastError") && !json.contains("last_error"),
+        "lastError must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_LAST_ERROR"),
+        "lastError value must not appear"
+    );
+    assert!(
+        !json.contains("lastErrorCode") && !json.contains("last_error_code"),
+        "lastErrorCode must not appear"
+    );
+}
+
+#[test]
+fn secret_exclusion_lineage_ids_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("team-id-123"),
+        "source_team value must not appear"
+    );
+    assert!(
+        !json.contains("sourceTeam") && !json.contains("source_team"),
+        "sourceTeam field must not appear"
+    );
+    assert!(
+        !json.contains("sourceTeamPersonaSlug"),
+        "sourceTeamPersonaSlug must not appear"
+    );
+    assert!(
+        !json.contains("personaSourceVersion") && !json.contains("persona_source_version"),
+        "personaSourceVersion must not appear"
+    );
+    // personaId
+    assert!(
+        !json.contains("personaId") && !json.contains("persona_id"),
+        "personaId field must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_PERSONA_ID"),
+        "personaId value must not appear"
+    );
+    // teamId
+    assert!(
+        !json.contains("teamId") && !json.contains("team_id"),
+        "teamId field must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_TEAM_ID"),
+        "teamId value must not appear"
+    );
+    // personaTeamDir
+    assert!(
+        !json.contains("personaTeamDir") && !json.contains("persona_team_dir"),
+        "personaTeamDir field must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_TEAM_DIR"),
+        "personaTeamDir value must not appear"
+    );
+    // personaNameInTeam
+    assert!(
+        !json.contains("personaNameInTeam") && !json.contains("persona_name_in_team"),
+        "personaNameInTeam field must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_NAME_IN_TEAM"),
+        "personaNameInTeam value must not appear"
+    );
+}
+
+// ── Definition field presence tests ──────────────────────────────────────
+
+#[test]
+fn definition_fields_present_in_snapshot() {
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+
+    assert_eq!(snapshot.definition.name, "Test Agent Display");
+    assert!(!snapshot.definition.source_is_builtin);
+    assert_eq!(
+        snapshot.definition.system_prompt.as_deref(),
+        Some("You are a test agent.")
+    );
+    assert_eq!(snapshot.definition.runtime.as_deref(), Some("goose"));
+    assert_eq!(snapshot.definition.model.as_deref(), Some("claude-opus-4"));
+    assert_eq!(snapshot.definition.provider.as_deref(), Some("anthropic"));
+    assert_eq!(snapshot.definition.name_pool, vec!["Alice", "Bob"]);
+    // definition_respond_to maps to respond_to in the snapshot definition
+    assert_eq!(snapshot.definition.respond_to.as_deref(), Some("allowlist"));
+    // definition_respond_to_allowlist should be included
+    assert!(!snapshot.definition.respond_to_allowlist.is_empty());
+}
+
+#[test]
+fn profile_fields_present_in_snapshot() {
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+    assert_eq!(snapshot.profile.display_name, "Test Agent Display");
+    // No bytes → should fall back to avatar_url
+    assert_eq!(
+        snapshot.profile.avatar_url.as_deref(),
+        Some("https://example.com/avatar.png")
+    );
+    assert!(snapshot.profile.avatar_data_url.is_none());
+}
+
+#[test]
+fn avatar_inlined_when_under_size_limit() {
+    let record = minimal_record();
+    let small_png = make_png_with_text("k", "v").unwrap();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&small_png));
+    assert!(snapshot.profile.avatar_data_url.is_some());
+    assert!(snapshot.profile.avatar_url.is_none());
+}
+
+#[test]
+fn avatar_url_fallback_when_over_size_limit() {
+    let mut record = minimal_record();
+    record.avatar_url = Some("https://example.com/big.png".to_string());
+    // Synthesize oversized avatar bytes (> 2 MB) — just a large zeroed vec.
+    let big_bytes = vec![0u8; MAX_AVATAR_INLINE_BYTES + 1];
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&big_bytes));
+    assert!(snapshot.profile.avatar_data_url.is_none());
+    assert_eq!(
+        snapshot.profile.avatar_url.as_deref(),
+        Some("https://example.com/big.png")
+    );
+}
+
+// ── Format/version validation ─────────────────────────────────────────────
+
+#[test]
+fn invalid_format_discriminator_is_rejected() {
+    let mut snapshot = build_snapshot(&minimal_record(), MemoryLevel::None, vec![], None);
+    snapshot.format = "not-a-buzz-snapshot".to_string();
+    let bytes = serde_json::to_vec(&snapshot).unwrap();
+    let result = decode_snapshot_json(&bytes);
+    assert!(result.is_err());
+    assert!(result.unwrap_err().contains("Unsupported snapshot format"));
+}
+
+#[test]
+fn unsupported_version_is_rejected() {
+    let mut snapshot = build_snapshot(&minimal_record(), MemoryLevel::None, vec![], None);
+    snapshot.version = 99;
+    let bytes = serde_json::to_vec(&snapshot).unwrap();
+    let result = decode_snapshot_json(&bytes);
+    assert!(result.is_err());
+    assert!(result.unwrap_err().contains("Unsupported snapshot version"));
+}
diff --git a/desktop/src-tauri/src/managed_agents/backend.rs b/desktop/src-tauri/src/managed_agents/backend.rs
index 2a72af92d7..84dd7e99da 100644
--- a/desktop/src-tauri/src/managed_agents/backend.rs
+++ b/desktop/src-tauri/src/managed_agents/backend.rs
@@ -1,3 +1,4 @@
+use sha2::{Digest, Sha256};
 use std::io::{BufReader, Read, Write};
 use std::path::{Path, PathBuf};
 use std::sync::mpsc;
@@ -7,6 +8,61 @@ const STDERR_CAP: usize = 65536;
 /// Provider responses should be small JSON objects. Cap stdout to prevent a
 /// buggy or malicious provider from OOM-ing the desktop process.
 const STDOUT_CAP: usize = 1_048_576; // 1 MB
+const PROVIDER_PROTOCOL_VERSION: u64 = 1;
+
+fn validate_provider_info(info: &serde_json::Value) -> Result<(), String> {
+    let object = info
+        .as_object()
+        .ok_or_else(|| "provider info response must be a JSON object".to_string())?;
+    let actual_version = object
+        .get("protocol_version")
+        .and_then(serde_json::Value::as_u64);
+    if actual_version != Some(PROVIDER_PROTOCOL_VERSION) {
+        return Err(match actual_version {
+            Some(version) => format!(
+                "unsupported provider protocol version {version}; desktop requires {PROVIDER_PROTOCOL_VERSION}"
+            ),
+            None => "provider info response missing integer protocol_version".to_string(),
+        });
+    }
+    if object.get("ok") != Some(&serde_json::Value::Bool(true)) {
+        return Err("provider info response must contain ok: true".to_string());
+    }
+    for field in ["name", "version", "description"] {
+        if object
+            .get(field)
+            .is_none_or(|value| value.as_str().is_none_or(str::is_empty))
+        {
+            return Err(format!(
+                "provider info response missing non-empty string {field}"
+            ));
+        }
+    }
+    if !object
+        .get("config_schema")
+        .is_some_and(serde_json::Value::is_object)
+    {
+        return Err("provider info response missing object config_schema".to_string());
+    }
+
+    const FIELDS: &[&str] = &[
+        "ok",
+        "name",
+        "version",
+        "protocol_version",
+        "description",
+        "config_schema",
+    ];
+    if let Some(field) = object
+        .keys()
+        .find(|field| !FIELDS.contains(&field.as_str()))
+    {
+        return Err(format!(
+            "provider info response contains unknown field {field}"
+        ));
+    }
+    Ok(())
+}
 
 /// Invoke a provider binary: write JSON to stdin, read JSON from stdout.
 ///
@@ -286,7 +342,7 @@ fn redact_secrets(s: &str) -> String {
 /// (would match every short token in normal log output). Entries are
 /// applied in decreasing length order so superstrings get scrubbed before
 /// substrings — protects against partial overlap leaks.
-fn redact_secrets_with(s: &str, extras: &[&str]) -> String {
+pub(crate) fn redact_secrets_with(s: &str, extras: &[&str]) -> String {
     let mut result = s.to_string();
 
     // Extras: longest first to avoid partial-overlap leaks. We use
@@ -305,9 +361,23 @@ fn redact_secrets_with(s: &str, extras: &[&str]) -> String {
 
     // Then prefix-based scrubbing. This loop *can* re-scan because each
     // replacement shortens the buffer past the matched prefix — the
-    // replacement marker `[REDACTED]` does not contain `nsec1` or
-    // `sprt_tok_`, so progress is guaranteed.
-    for prefix in &["nsec1", "sprt_tok_"] {
+    // replacement marker `[REDACTED]` contains none of these prefixes, so
+    // progress is guaranteed. Any prefix added here must preserve that.
+    //
+    // GitHub tokens are recognised by shape as well as by variable name: a
+    // token reaches output from outside our environment too — embedded in a
+    // git remote URL an installer echoes, say — where no name-based rule can
+    // see it.
+    for prefix in &[
+        "nsec1",
+        "sprt_tok_",
+        "ghp_",
+        "gho_",
+        "ghu_",
+        "ghs_",
+        "ghr_",
+        "github_pat_",
+    ] {
         while let Some(pos) = result.find(prefix) {
             let end = result[pos..]
                 .find(|c: char| c.is_whitespace() || c == '"' || c == '\'')
@@ -319,23 +389,29 @@ fn redact_secrets_with(s: &str, extras: &[&str]) -> String {
     result
 }
 
-/// Collect string values from `request["agent"]["env_vars"]` (if present)
-/// to feed into [`redact_secrets_with`]. Returns an empty Vec if the
-/// request shape doesn't match, which is fine — falls back to the default
-/// prefix-based scrubbing.
+/// Collect string values from every environment map a deploy request can
+/// carry. Providers may echo any of these values in diagnostics, including
+/// definition/baked values that exist only in the resolved launch block.
 fn env_secrets_from_request(request: &serde_json::Value) -> Vec<String> {
-    request
-        .get("agent")
-        .and_then(|a| a.get("env_vars"))
-        .and_then(|e| e.as_object())
-        .map(|obj| {
-            obj.values()
-                .filter_map(|v| v.as_str())
-                .filter(|s| !s.is_empty())
-                .map(String::from)
-                .collect()
-        })
-        .unwrap_or_default()
+    let agent = request.get("agent");
+    let maps = [
+        agent.and_then(|value| value.get("env_vars")),
+        agent
+            .and_then(|value| value.get("launch"))
+            .and_then(|value| value.get("env")),
+        agent
+            .and_then(|value| value.get("launch"))
+            .and_then(|value| value.get("policy_env")),
+    ];
+
+    maps.into_iter()
+        .flatten()
+        .filter_map(serde_json::Value::as_object)
+        .flat_map(|map| map.values())
+        .filter_map(serde_json::Value::as_str)
+        .filter(|value| !value.is_empty())
+        .map(String::from)
+        .collect()
 }
 
 /// Public-in-crate helper: redact every non-empty value from `env` (plus
@@ -354,22 +430,102 @@ pub(crate) fn redact_env_values_in(
     redact_secrets_with(s, &values)
 }
 
-/// Deploy an agent via provider binary. Returns the provider-assigned agent_id.
-///
-/// `request_id` is included for provider-side logging/correlation but is not
-/// validated in the response — the stdin→stdout exchange is 1:1 per process.
+/// Copy a resolved provider into a private staging directory while hashing
+/// exactly the bytes copied. The staged file becomes non-writable before either
+/// invocation, closing the path replacement and in-place rewrite races.
+fn stage_provider(
+    binary: &Path,
+) -> Result<(tempfile::TempDir, PathBuf, String, std::fs::File), String> {
+    let directory = tempfile::Builder::new()
+        .prefix("buzz-provider-")
+        .tempdir()
+        .map_err(|error| format!("failed to create provider staging directory: {error}"))?;
+    let suffix = if cfg!(windows) { ".exe" } else { "" };
+    let staged_path = directory.path().join(format!("provider{suffix}"));
+    let mut source = std::fs::File::open(binary)
+        .map_err(|error| format!("failed to open provider for staging: {error}"))?;
+    let mut staged = std::fs::OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .open(&staged_path)
+        .map_err(|error| format!("failed to create staged provider: {error}"))?;
+    let mut hasher = Sha256::new();
+    let mut buffer = [0_u8; 64 * 1024];
+    loop {
+        let count = source
+            .read(&mut buffer)
+            .map_err(|error| format!("failed to read provider for staging: {error}"))?;
+        if count == 0 {
+            break;
+        }
+        staged
+            .write_all(&buffer[..count])
+            .map_err(|error| format!("failed to write staged provider: {error}"))?;
+        hasher.update(&buffer[..count]);
+    }
+    staged
+        .sync_all()
+        .map_err(|error| format!("failed to sync staged provider: {error}"))?;
+
+    let mut permissions = staged
+        .metadata()
+        .map_err(|error| format!("failed to inspect staged provider: {error}"))?
+        .permissions();
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        permissions.set_mode(0o500);
+    }
+    #[cfg(not(unix))]
+    permissions.set_readonly(true);
+    std::fs::set_permissions(&staged_path, permissions)
+        .map_err(|error| format!("failed to protect staged provider: {error}"))?;
+    drop(staged);
+
+    #[cfg(windows)]
+    let execution_guard = {
+        use std::os::windows::fs::OpenOptionsExt;
+        std::fs::OpenOptions::new()
+            .read(true)
+            // Permit CreateProcess to read the image while denying replacement,
+            // writes, and deletion until both invocations finish.
+            .share_mode(windows_sys::Win32::Storage::FileSystem::FILE_SHARE_READ)
+            .open(&staged_path)
+    };
+    #[cfg(not(windows))]
+    let execution_guard = std::fs::File::open(&staged_path);
+    let execution_guard = execution_guard
+        .map_err(|error| format!("failed to lock staged provider for execution: {error}"))?;
+    Ok((
+        directory,
+        staged_path,
+        hex::encode(hasher.finalize()),
+        execution_guard,
+    ))
+}
+
+/// Deploy through one immutable staged copy: negotiate protocol v1 before the
+/// secret-bearing request, then invoke deploy on those exact same bytes.
 pub fn provider_deploy(
     binary: &Path,
     agent: &serde_json::Value,
     provider_config: &serde_json::Value,
 ) -> Result<String, String> {
+    let (_directory, staged, _digest, _execution_guard) = stage_provider(binary)?;
+    let info_request = serde_json::json!({
+        "op": "info",
+        "request_id": uuid::Uuid::new_v4().to_string(),
+    });
+    let info = invoke_provider(&staged, &info_request, Duration::from_secs(10))?;
+    validate_provider_info(&info)?;
+
     let request = serde_json::json!({
         "op": "deploy",
         "request_id": uuid::Uuid::new_v4().to_string(),
         "agent": agent,
         "provider_config": provider_config,
     });
-    let resp = invoke_provider(binary, &request, Duration::from_secs(600))?;
+    let resp = invoke_provider(&staged, &request, Duration::from_secs(600))?;
     resp["agent_id"]
         .as_str()
         .map(String::from)
@@ -409,6 +565,24 @@ pub fn validate_provider_config(config: &serde_json::Value) -> Result<(), String
     Ok(())
 }
 
+/// Derive a provider id from the filename Tauri stages at runtime. Tauri
+/// removes its target-triple suffix while copying an external binary, but on
+/// Windows leaves the executable/script extension, which is not part of the
+/// provider id.
+fn provider_id_from_filename(name: &str) -> Option<&str> {
+    let raw = name.strip_prefix("buzz-backend-")?;
+    let id = [".exe", ".bat", ".cmd"]
+        .into_iter()
+        .find_map(|extension| {
+            raw.get(raw.len().saturating_sub(extension.len())..)
+                .filter(|suffix| suffix.eq_ignore_ascii_case(extension))
+                .map(|_| &raw[..raw.len() - extension.len()])
+        })
+        .unwrap_or(raw);
+
+    (!id.is_empty()).then_some(id)
+}
+
 /// Enumerate PATH for buzz-backend-* executables. Returns (id, path) pairs.
 /// Only includes files that are executable. Does NOT execute any binaries.
 ///
@@ -450,10 +624,12 @@ pub fn discover_provider_candidates() -> Vec<(String, PathBuf)> {
         };
         for entry in entries.flatten() {
             let name = entry.file_name().to_string_lossy().to_string();
-            if let Some(id) = name.strip_prefix(prefix) {
-                if !id.is_empty() && !seen.contains(&name) && is_executable(&entry.path()) {
-                    seen.insert(name.clone());
-                    results.push((id.to_string(), entry.path()));
+            if name.starts_with(prefix) {
+                if let Some(id) = provider_id_from_filename(&name) {
+                    if !seen.contains(&name) && is_executable(&entry.path()) {
+                        seen.insert(name.clone());
+                        results.push((id.to_string(), entry.path()));
+                    }
                 }
             }
         }
@@ -524,180 +700,5 @@ pub struct BackendProviderInfo {
 }
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn redact_secrets_replaces_nsec() {
-        let s = "key=nsec1abc123def456 other";
-        let r = redact_secrets(s);
-        assert!(r.contains("[REDACTED]"));
-        assert!(!r.contains("nsec1abc123def456"));
-    }
-
-    #[test]
-    fn redact_secrets_replaces_token() {
-        let s = r#"{"token":"sprt_tok_xyz789"}"#;
-        let r = redact_secrets(s);
-        assert!(r.contains("[REDACTED]"));
-        assert!(!r.contains("sprt_tok_xyz789"));
-    }
-
-    #[test]
-    fn redact_secrets_with_extras_scrubs_user_env_values() {
-        // If a provider echoes back a user-supplied API key in its error
-        // output, the desktop must not surface that secret unredacted via
-        // `last_error`. We scrub the literal values that came from the
-        // request's `agent.env_vars`.
-        let secret = "sk-ant-api03-abc123def456";
-        let stderr = format!("auth failed with key {secret} on host api.anthropic.com");
-        let r = redact_secrets_with(&stderr, &[secret]);
-        assert!(r.contains("[REDACTED]"));
-        assert!(!r.contains(secret));
-    }
-
-    #[test]
-    fn redact_secrets_with_extras_skips_short_values() {
-        // Don't scrub values shorter than 4 chars — too noisy.
-        let r = redact_secrets_with("error code: 42", &["42"]);
-        assert!(r.contains("42"));
-    }
-
-    #[test]
-    fn redact_secrets_with_extras_terminates_when_value_substring_of_marker() {
-        // Regression: an earlier impl used `while let Some(pos) = find(value)`
-        // which never terminates if the user's env value is a substring of
-        // the replacement marker `[REDACTED]` — each replacement
-        // reintroduces the same text. Now uses `str::replace` (single-pass).
-        for value in ["REDACTED", "EDACTE", "REDA", "ACTED"] {
-            let r = redact_secrets_with(&format!("leak={value}"), &[value]);
-            assert!(r.contains("[REDACTED]"));
-        }
-    }
-
-    #[test]
-    fn redact_secrets_with_extras_handles_overlapping_secrets() {
-        // Longer entries get scrubbed first so the substring "abc12" isn't
-        // matched before "abc123" is consumed.
-        let s = "key1=abc123 key2=abc12";
-        let r = redact_secrets_with(s, &["abc12", "abc123"]);
-        assert!(!r.contains("abc123"));
-        assert!(!r.contains("abc12 "));
-    }
-
-    #[test]
-    fn env_secrets_from_request_extracts_string_values() {
-        let req = serde_json::json!({
-            "op": "deploy",
-            "agent": {
-                "env_vars": {
-                    "ANTHROPIC_API_KEY": "sk-ant-test",
-                    "EMPTY": "",
-                    "NUMERIC": 42,
-                },
-            },
-        });
-        let secrets = env_secrets_from_request(&req);
-        assert!(secrets.iter().any(|v| v == "sk-ant-test"));
-        // Empty and non-string values are filtered out.
-        assert_eq!(secrets.len(), 1);
-    }
-
-    #[test]
-    fn env_secrets_from_request_handles_missing_shape() {
-        assert!(env_secrets_from_request(&serde_json::json!({})).is_empty());
-        assert!(env_secrets_from_request(&serde_json::json!({"agent": {}})).is_empty());
-        assert!(
-            env_secrets_from_request(&serde_json::json!({"agent": {"env_vars": null}})).is_empty()
-        );
-    }
-
-    #[test]
-    fn redact_env_values_in_scrubs_map_values() {
-        let mut env = std::collections::BTreeMap::new();
-        env.insert("ANTHROPIC_API_KEY".to_string(), "sk-ant-real".to_string());
-        env.insert("EMPTY".to_string(), String::new());
-        let stderr = "auth=sk-ant-real failed; other context";
-        let r = redact_env_values_in(stderr, &env);
-        assert!(!r.contains("sk-ant-real"));
-        assert!(r.contains("[REDACTED]"));
-    }
-
-    #[test]
-    fn validate_provider_config_rejects_secret_key() {
-        let cfg = serde_json::json!({"api_key": "val"});
-        assert!(validate_provider_config(&cfg).is_err());
-    }
-
-    #[test]
-    fn validate_provider_config_rejects_nested() {
-        let cfg = serde_json::json!({"region": {"us": "east"}});
-        assert!(validate_provider_config(&cfg).is_err());
-    }
-
-    #[test]
-    fn validate_provider_config_accepts_scalars() {
-        let cfg = serde_json::json!({"region": "us-east-1", "tier": "standard"});
-        assert!(validate_provider_config(&cfg).is_ok());
-    }
-
-    #[test]
-    fn validate_provider_config_allows_key_as_substring() {
-        // "keyboard", "monkey" contain "key" as substring but not as a word segment.
-        let cfg = serde_json::json!({"keyboard_layout": "us", "monkey_wrench": "tight"});
-        assert!(validate_provider_config(&cfg).is_ok());
-    }
-
-    #[test]
-    fn validate_provider_config_rejects_camel_case_secrets() {
-        assert!(validate_provider_config(&serde_json::json!({"apiKey": "val"})).is_err());
-        assert!(validate_provider_config(&serde_json::json!({"accessToken": "val"})).is_err());
-        assert!(validate_provider_config(&serde_json::json!({"clientSecret": "val"})).is_err());
-        // ALL-CAPS variants
-        assert!(validate_provider_config(&serde_json::json!({"apiKEY": "val"})).is_err());
-        assert!(validate_provider_config(&serde_json::json!({"accessTOKEN": "val"})).is_err());
-    }
-
-    #[test]
-    fn split_config_key_handles_all_styles() {
-        assert_eq!(split_config_key("apiKey"), vec!["api", "key"]);
-        assert_eq!(split_config_key("access_token"), vec!["access", "token"]);
-        assert_eq!(split_config_key("keyboard"), vec!["keyboard"]);
-        assert_eq!(split_config_key("client-secret"), vec!["client", "secret"]);
-        // Acronym runs stay together
-        assert_eq!(split_config_key("APIKey"), vec!["api", "key"]);
-        assert_eq!(split_config_key("apiKEY"), vec!["api", "key"]);
-        assert_eq!(split_config_key("accessTOKEN"), vec!["access", "token"]);
-        assert_eq!(split_config_key("MyAPIKey"), vec!["my", "api", "key"]);
-    }
-
-    #[test]
-    fn resolve_provider_binary_rejects_invalid_ids() {
-        // Path traversal
-        assert!(resolve_provider_binary("../evil").is_err());
-        // Empty
-        assert!(resolve_provider_binary("").is_err());
-        // Uppercase
-        assert!(resolve_provider_binary("MyProvider").is_err());
-        // Spaces
-        assert!(resolve_provider_binary("my provider").is_err());
-        // Shell metacharacters
-        assert!(resolve_provider_binary("foo;rm -rf /").is_err());
-        // Valid format but not on PATH — should fail with "not found"
-        assert!(resolve_provider_binary("nonexistent-test-id-12345").is_err());
-    }
-
-    #[test]
-    fn resolve_provider_binary_accepts_valid_id_format() {
-        // Valid ID format should pass validation. If the binary happens to
-        // exist on PATH, Ok is returned; otherwise Err contains "not found"
-        // (not "invalid provider ID"). Either outcome proves validation passed.
-        match resolve_provider_binary("zzz-nonexistent-test-provider") {
-            Ok(_) => {} // unlikely but fine — binary exists
-            Err(e) => assert!(
-                e.contains("not found"),
-                "expected 'not found' error, got: {e}"
-            ),
-        }
-    }
-}
+#[path = "backend_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/managed_agents/backend_tests.rs b/desktop/src-tauri/src/managed_agents/backend_tests.rs
new file mode 100644
index 0000000000..ce1f81466f
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/backend_tests.rs
@@ -0,0 +1,452 @@
+use super::*;
+
+#[test]
+fn redact_secrets_replaces_nsec() {
+    let s = "key=nsec1abc123def456 other";
+    let r = redact_secrets(s);
+    assert!(r.contains("[REDACTED]"));
+    assert!(!r.contains("nsec1abc123def456"));
+}
+
+#[test]
+fn redact_secrets_replaces_token() {
+    let s = r#"{"token":"sprt_tok_xyz789"}"#;
+    let r = redact_secrets(s);
+    assert!(r.contains("[REDACTED]"));
+    assert!(!r.contains("sprt_tok_xyz789"));
+}
+
+#[test]
+fn redact_secrets_with_extras_scrubs_user_env_values() {
+    // If a provider echoes back a user-supplied API key in its error
+    // output, the desktop must not surface that secret unredacted via
+    // `last_error`. We scrub the literal values that came from the
+    // request's `agent.env_vars`.
+    let secret = "sk-ant-api03-abc123def456";
+    let stderr = format!("auth failed with key {secret} on host api.anthropic.com");
+    let r = redact_secrets_with(&stderr, &[secret]);
+    assert!(r.contains("[REDACTED]"));
+    assert!(!r.contains(secret));
+}
+
+#[test]
+fn redact_secrets_with_extras_skips_short_values() {
+    // Don't scrub values shorter than 4 chars — too noisy.
+    let r = redact_secrets_with("error code: 42", &["42"]);
+    assert!(r.contains("42"));
+}
+
+/// GitHub tokens are recognised by shape, so one that never passed through
+/// our environment — embedded in a remote URL an installer echoes — is
+/// still scrubbed. The scan runs to the next whitespace or quote, so the
+/// rest of the URL goes with it; over-redaction is the safe direction.
+#[test]
+fn redact_secrets_with_scrubs_github_token_prefixes() {
+    for token in [
+        "ghp_abcdefghij0123456789",
+        "gho_abcdefghij0123456789",
+        "ghu_abcdefghij0123456789",
+        "ghs_abcdefghij0123456789",
+        "ghr_abcdefghij0123456789",
+        "github_pat_abcdefghij0123456789",
+    ] {
+        let r = redact_secrets_with(&format!("cloning https://{token}@github.com/o/r now"), &[]);
+        assert!(!r.contains(token), "leaked {token}: {r}");
+        assert!(r.contains("[REDACTED]"), "got: {r}");
+        assert!(r.contains("cloning"), "scan must stop at whitespace: {r}");
+        assert!(r.ends_with(" now"), "scan must stop at whitespace: {r}");
+    }
+}
+
+#[test]
+fn redact_secrets_with_extras_terminates_when_value_substring_of_marker() {
+    // Regression: an earlier impl used `while let Some(pos) = find(value)`
+    // which never terminates if the user's env value is a substring of
+    // the replacement marker `[REDACTED]` — each replacement
+    // reintroduces the same text. Now uses `str::replace` (single-pass).
+    for value in ["REDACTED", "EDACTE", "REDA", "ACTED"] {
+        let r = redact_secrets_with(&format!("leak={value}"), &[value]);
+        assert!(r.contains("[REDACTED]"));
+    }
+}
+
+#[test]
+fn redact_secrets_with_extras_handles_overlapping_secrets() {
+    // Longer entries get scrubbed first so the substring "abc12" isn't
+    // matched before "abc123" is consumed.
+    let s = "key1=abc123 key2=abc12";
+    let r = redact_secrets_with(s, &["abc12", "abc123"]);
+    assert!(!r.contains("abc123"));
+    assert!(!r.contains("abc12 "));
+}
+
+#[test]
+fn env_secrets_from_request_extracts_string_values() {
+    let req = serde_json::json!({
+        "op": "deploy",
+        "agent": {
+            "env_vars": {
+                "ANTHROPIC_API_KEY": "sk-ant-test",
+                "EMPTY": "",
+                "NUMERIC": 42,
+            },
+        },
+    });
+    let secrets = env_secrets_from_request(&req);
+    assert!(secrets.iter().any(|v| v == "sk-ant-test"));
+    // Empty and non-string values are filtered out.
+    assert_eq!(secrets.len(), 1);
+}
+
+#[test]
+fn env_secrets_from_request_handles_missing_shape() {
+    assert!(env_secrets_from_request(&serde_json::json!({})).is_empty());
+    assert!(env_secrets_from_request(&serde_json::json!({"agent": {}})).is_empty());
+    assert!(env_secrets_from_request(&serde_json::json!({"agent": {"env_vars": null}})).is_empty());
+}
+
+#[test]
+fn redact_env_values_in_scrubs_map_values() {
+    let mut env = std::collections::BTreeMap::new();
+    env.insert("ANTHROPIC_API_KEY".to_string(), "sk-ant-real".to_string());
+    env.insert("EMPTY".to_string(), String::new());
+    let stderr = "auth=sk-ant-real failed; other context";
+    let r = redact_env_values_in(stderr, &env);
+    assert!(!r.contains("sk-ant-real"));
+    assert!(r.contains("[REDACTED]"));
+}
+
+#[test]
+fn env_secrets_from_request_includes_resolved_launch_maps() {
+    let req = serde_json::json!({
+        "agent": {
+            "env_vars": {"LEGACY": "legacy-secret"},
+            "launch": {
+                "env": {"PERSONA": "persona-secret"},
+                "policy_env": {"POLICY": "policy-secret"}
+            }
+        }
+    });
+    let secrets = env_secrets_from_request(&req);
+    assert_eq!(secrets.len(), 3);
+    for secret in ["legacy-secret", "persona-secret", "policy-secret"] {
+        assert!(secrets.iter().any(|candidate| candidate == secret));
+    }
+}
+
+#[cfg(unix)]
+fn write_test_provider(path: &Path, body: &str) {
+    use std::os::unix::fs::PermissionsExt;
+    std::fs::write(path, format!("#!/bin/sh\nset -eu\n{body}\n")).unwrap();
+    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o700)).unwrap();
+}
+
+#[cfg(unix)]
+#[test]
+fn provider_deploy_negotiates_and_deploys_the_same_staged_bytes() {
+    let directory = tempfile::tempdir().unwrap();
+    let provider = directory.path().join("provider");
+    let log = directory.path().join("invocations");
+    let body = format!(
+        r#"read request
+printf '%s\n' "$0" >> '{}'
+case "$request" in
+  *\"op\":\"info\"*) printf '%s\n' '{{"ok":true,"name":"test","version":"1.0.0","protocol_version":1,"description":"test provider","config_schema":{{}}}}' ;;
+  *\"op\":\"deploy\"*) printf '%s\n' '{{"ok":true,"agent_id":"remote-1"}}' ;;
+esac"#,
+        log.display()
+    );
+    write_test_provider(&provider, &body);
+
+    let id = provider_deploy(&provider, &serde_json::json!({}), &serde_json::json!({}))
+        .expect("staged deploy");
+    assert_eq!(id, "remote-1");
+    let paths: Vec<_> = std::fs::read_to_string(log)
+        .unwrap()
+        .lines()
+        .map(str::to_owned)
+        .collect();
+    assert_eq!(paths.len(), 2);
+    assert_eq!(paths[0], paths[1]);
+    assert_ne!(Path::new(&paths[0]), provider);
+    assert!(
+        !Path::new(&paths[0]).exists(),
+        "staging directory must be deleted"
+    );
+}
+
+#[cfg(unix)]
+fn replacement_provider() -> &'static str {
+    r#"#!/bin/sh
+set -eu
+read request
+case "$request" in
+  *\"op\":\"info\"*) printf '%s\n' '{"ok":true,"name":"replacement","version":"9.9.9","protocol_version":1,"description":"replacement provider","config_schema":{}}' ;;
+  *\"op\":\"deploy\"*) printf '%s\n' '{"ok":true,"agent_id":"replacement-bytes-ran"}' ;;
+esac
+"#
+}
+
+#[cfg(unix)]
+#[test]
+fn provider_deploy_uses_staged_bytes_after_same_inode_source_rewrite() {
+    use std::os::unix::fs::MetadataExt;
+
+    let directory = tempfile::tempdir().unwrap();
+    let provider = directory.path().join("provider");
+    let replacement = directory.path().join("replacement");
+    std::fs::write(&replacement, replacement_provider()).unwrap();
+    let body = format!(
+        r#"read request
+case "$request" in
+  *\"op\":\"info\"*)
+    cat '{}' > '{}'
+    chmod 700 '{}'
+    printf '%s\n' '{{"ok":true,"name":"original","version":"1.0.0","protocol_version":1,"description":"original provider","config_schema":{{}}}}'
+    ;;
+  *\"op\":\"deploy\"*) printf '%s\n' '{{"ok":true,"agent_id":"original-staged-bytes"}}' ;;
+esac"#,
+        replacement.display(),
+        provider.display(),
+        provider.display(),
+    );
+    write_test_provider(&provider, &body);
+    let inode_before = std::fs::metadata(&provider).unwrap().ino();
+
+    let id = provider_deploy(&provider, &serde_json::json!({}), &serde_json::json!({}))
+        .expect("deploy from immutable staged copy");
+
+    assert_eq!(id, "original-staged-bytes");
+    assert_eq!(
+        std::fs::metadata(&provider).unwrap().ino(),
+        inode_before,
+        "test must rewrite the source binary in place"
+    );
+    assert_eq!(
+        std::fs::read_to_string(&provider).unwrap(),
+        replacement_provider(),
+        "source pathname must contain replacement bytes before deploy"
+    );
+}
+
+#[cfg(unix)]
+#[test]
+fn provider_deploy_uses_staged_bytes_after_source_pathname_replacement() {
+    use std::os::unix::fs::{MetadataExt, PermissionsExt};
+
+    let directory = tempfile::tempdir().unwrap();
+    let provider = directory.path().join("provider");
+    let replacement = directory.path().join("replacement");
+    std::fs::write(&replacement, replacement_provider()).unwrap();
+    std::fs::set_permissions(&replacement, std::fs::Permissions::from_mode(0o700)).unwrap();
+    let body = format!(
+        r#"read request
+case "$request" in
+  *\"op\":\"info\"*)
+    mv '{}' '{}'
+    printf '%s\n' '{{"ok":true,"name":"original","version":"1.0.0","protocol_version":1,"description":"original provider","config_schema":{{}}}}'
+    ;;
+  *\"op\":\"deploy\"*) printf '%s\n' '{{"ok":true,"agent_id":"original-staged-bytes"}}' ;;
+esac"#,
+        replacement.display(),
+        provider.display(),
+    );
+    write_test_provider(&provider, &body);
+    let inode_before = std::fs::metadata(&provider).unwrap().ino();
+
+    let id = provider_deploy(&provider, &serde_json::json!({}), &serde_json::json!({}))
+        .expect("deploy from immutable staged copy");
+
+    assert_eq!(id, "original-staged-bytes");
+    assert_ne!(
+        std::fs::metadata(&provider).unwrap().ino(),
+        inode_before,
+        "test must replace the source pathname with a different inode"
+    );
+    assert_eq!(
+        std::fs::read_to_string(&provider).unwrap(),
+        replacement_provider(),
+        "source pathname must contain replacement bytes before deploy"
+    );
+}
+
+#[cfg(unix)]
+#[test]
+fn provider_deploy_refuses_mismatch_before_sending_agent_secret() {
+    let directory = tempfile::tempdir().unwrap();
+    let provider = directory.path().join("provider");
+    let marker = directory.path().join("deploy-received");
+    let body = format!(
+        r#"read request
+case "$request" in
+  *\"op\":\"info\"*) printf '%s\n' '{{"ok":true,"name":"test","version":"2.0.0","protocol_version":2,"description":"test provider","config_schema":{{}}}}' ;;
+  *\"op\":\"deploy\"*) touch '{}'; printf '%s\n' '{{"ok":true,"agent_id":"bad"}}' ;;
+esac"#,
+        marker.display()
+    );
+    write_test_provider(&provider, &body);
+
+    let error = provider_deploy(
+        &provider,
+        &serde_json::json!({"private_key_nsec": "nsec1must-not-cross"}),
+        &serde_json::json!({}),
+    )
+    .unwrap_err();
+    assert!(error.contains("protocol version 2"), "{error}");
+    assert!(!marker.exists());
+    assert!(!error.contains("nsec1must-not-cross"));
+}
+
+#[cfg(unix)]
+#[test]
+fn provider_deploy_requires_an_explicit_integer_protocol_version() {
+    let directory = tempfile::tempdir().unwrap();
+    let provider = directory.path().join("provider");
+    write_test_provider(
+        &provider,
+        r#"read request
+printf '%s\n' '{"ok":true,"version":"1.0.0"}'"#,
+    );
+
+    let error =
+        provider_deploy(&provider, &serde_json::json!({}), &serde_json::json!({})).unwrap_err();
+    assert!(
+        error.contains("missing integer protocol_version"),
+        "{error}"
+    );
+}
+
+#[test]
+fn provider_info_requires_the_complete_flat_wire_shape() {
+    let complete = serde_json::json!({
+        "ok": true,
+        "name": "kubernetes",
+        "version": "1.0.0",
+        "protocol_version": 1,
+        "description": "Kubernetes provider",
+        "config_schema": {}
+    });
+    assert!(validate_provider_info(&complete).is_ok());
+
+    let mut missing = complete.clone();
+    missing.as_object_mut().unwrap().remove("config_schema");
+    assert!(validate_provider_info(&missing)
+        .unwrap_err()
+        .contains("config_schema"));
+
+    let mut nested = complete;
+    nested.as_object_mut().unwrap().insert(
+        "provider".into(),
+        serde_json::json!({"protocol_version": 1}),
+    );
+    assert!(validate_provider_info(&nested)
+        .unwrap_err()
+        .contains("unknown field provider"));
+}
+
+#[test]
+fn validate_provider_config_rejects_secret_key() {
+    let cfg = serde_json::json!({"api_key": "val"});
+    assert!(validate_provider_config(&cfg).is_err());
+}
+
+#[test]
+fn validate_provider_config_rejects_nested() {
+    let cfg = serde_json::json!({"region": {"us": "east"}});
+    assert!(validate_provider_config(&cfg).is_err());
+}
+
+#[test]
+fn validate_provider_config_accepts_scalars() {
+    let cfg = serde_json::json!({"region": "us-east-1", "tier": "standard"});
+    assert!(validate_provider_config(&cfg).is_ok());
+}
+
+#[test]
+fn validate_provider_config_allows_key_as_substring() {
+    // "keyboard", "monkey" contain "key" as substring but not as a word segment.
+    let cfg = serde_json::json!({"keyboard_layout": "us", "monkey_wrench": "tight"});
+    assert!(validate_provider_config(&cfg).is_ok());
+}
+
+#[test]
+fn validate_provider_config_rejects_camel_case_secrets() {
+    assert!(validate_provider_config(&serde_json::json!({"apiKey": "val"})).is_err());
+    assert!(validate_provider_config(&serde_json::json!({"accessToken": "val"})).is_err());
+    assert!(validate_provider_config(&serde_json::json!({"clientSecret": "val"})).is_err());
+    // ALL-CAPS variants
+    assert!(validate_provider_config(&serde_json::json!({"apiKEY": "val"})).is_err());
+    assert!(validate_provider_config(&serde_json::json!({"accessTOKEN": "val"})).is_err());
+}
+
+#[test]
+fn split_config_key_handles_all_styles() {
+    assert_eq!(split_config_key("apiKey"), vec!["api", "key"]);
+    assert_eq!(split_config_key("access_token"), vec!["access", "token"]);
+    assert_eq!(split_config_key("keyboard"), vec!["keyboard"]);
+    assert_eq!(split_config_key("client-secret"), vec!["client", "secret"]);
+    // Acronym runs stay together
+    assert_eq!(split_config_key("APIKey"), vec!["api", "key"]);
+    assert_eq!(split_config_key("apiKEY"), vec!["api", "key"]);
+    assert_eq!(split_config_key("accessTOKEN"), vec!["access", "token"]);
+    assert_eq!(split_config_key("MyAPIKey"), vec!["my", "api", "key"]);
+}
+
+#[test]
+fn provider_filename_strips_the_windows_extension() {
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-kubernetes"),
+        Some("kubernetes")
+    );
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-kubernetes.exe"),
+        Some("kubernetes")
+    );
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-kubernetes.EXE"),
+        Some("kubernetes")
+    );
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-kubernetes.bat"),
+        Some("kubernetes")
+    );
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-kubernetes.CMD"),
+        Some("kubernetes")
+    );
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-my-provider"),
+        Some("my-provider")
+    );
+    assert_eq!(provider_id_from_filename("other"), None);
+}
+
+#[test]
+fn resolve_provider_binary_rejects_invalid_ids() {
+    // Path traversal
+    assert!(resolve_provider_binary("../evil").is_err());
+    // Empty
+    assert!(resolve_provider_binary("").is_err());
+    // Uppercase
+    assert!(resolve_provider_binary("MyProvider").is_err());
+    // Spaces
+    assert!(resolve_provider_binary("my provider").is_err());
+    // Shell metacharacters
+    assert!(resolve_provider_binary("foo;rm -rf /").is_err());
+    // Valid format but not on PATH — should fail with "not found"
+    assert!(resolve_provider_binary("nonexistent-test-id-12345").is_err());
+}
+
+#[test]
+fn resolve_provider_binary_accepts_valid_id_format() {
+    // Valid ID format should pass validation. If the binary happens to
+    // exist on PATH, Ok is returned; otherwise Err contains "not found"
+    // (not "invalid provider ID"). Either outcome proves validation passed.
+    match resolve_provider_binary("zzz-nonexistent-test-provider") {
+        Ok(_) => {} // unlikely but fine — binary exists
+        Err(e) => assert!(
+            e.contains("not found"),
+            "expected 'not found' error, got: {e}"
+        ),
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/discovery.rs b/desktop/src-tauri/src/managed_agents/discovery.rs
index eecbf4de3e..8d1b8a5013 100644
--- a/desktop/src-tauri/src/managed_agents/discovery.rs
+++ b/desktop/src-tauri/src/managed_agents/discovery.rs
@@ -10,8 +10,11 @@ use crate::managed_agents::{
     HarnessSource,
 };
 
+mod presets;
 mod runtime_metadata;
 
+use presets::{preset_catalog_entry, PRESET_HARNESSES};
+pub(crate) use presets::{preset_harness_definitions, preset_harness_ids};
 pub(crate) use runtime_metadata::KnownAcpRuntime;
 
 const GOOSE_AVATAR_URL: &str = "https://goose-docs.ai/img/logo_dark.png";
@@ -19,7 +22,6 @@ const CLAUDE_CODE_AVATAR_URL: &str = "https://anthropic.gallerycdn.vsassets.io/e
 const CODEX_AVATAR_URL: &str = "https://openai.gallerycdn.vsassets.io/extensions/openai/chatgpt/26.5313.41514/1773706730621/Microsoft.VisualStudio.Services.Icons.Default";
 const BUZZ_AGENT_AVATAR_URL: &str =
     "https://raw.githubusercontent.com/block/buzz/refs/heads/main/crates/buzz-agent/buzz-agent.png";
-
 fn common_binary_paths() -> &'static [PathBuf] {
     static PATHS: OnceLock<Vec<PathBuf>> = OnceLock::new();
     PATHS.get_or_init(|| {
@@ -41,6 +43,7 @@ fn common_binary_paths() -> &'static [PathBuf] {
                 home.join(".local/bin"),
                 home.join(".volta/bin"),
                 home.join(".asdf/shims"),
+                home.join(".bun/bin"),
             ]);
         }
         // Windows well-known dirs for npm global shims and standalone installer targets.
@@ -1436,225 +1439,6 @@ pub(crate) fn discover_acp_runtime_availability(runtime_id: &str) -> Option<AcpA
         .map(|partial| partial.entry.availability)
 }
 
-// ── Tier-2 preset harnesses ────────────────────────────────────────────────
-//
-// Static data for well-known ACP harnesses that have bundled logos and
-// verified command/args. PATH-probed at discovery time (Detected badge);
-// not editable or deletable by users. Logos are bundled assets referenced
-// by id in the frontend `RUNTIME_LOGOS` map.
-
-struct PresetHarness {
-    id: &'static str,
-    label: &'static str,
-    command: &'static str,
-    args: &'static [&'static str],
-    install_instructions_url: &'static str,
-    install_hint: &'static str,
-    /// Vendor CLI the ACP command wraps, when the preset is an adapter
-    /// (e.g. Amp's `amp-acp` wraps the separately-installed `amp` CLI).
-    /// Consulted only when the adapter is absent, so `AdapterMissing`
-    /// replaces the misleading `NotInstalled` when the CLI is present but
-    /// the adapter is not. Deliberately NOT fed through the builtins'
-    /// full `classify_runtime` predicate: that would flip
-    /// adapter-present/CLI-absent from today's `Available` to `CliMissing`
-    /// (unselectable), and presets carry a single flat `install_hint`, so
-    /// the `CliMissing` copy would tell the user to install the adapter
-    /// they already have. `None` when the command IS the vendor CLI.
-    underlying_cli: Option<&'static str>,
-}
-
-/// Build the catalog entry for one preset harness through an injectable
-/// resolver — the seam the preset loop consumes and tests bind.
-///
-/// Availability consumes only the adapter-missing arm of the builtin
-/// predicate: adapter presence alone decides `Available` (exactly today's
-/// behavior — an `amp-acp` without `amp` stays selectable), and
-/// `underlying_cli` is consulted only when the adapter is absent, to
-/// distinguish `AdapterMissing` (vendor CLI present) from `NotInstalled`
-/// (neither found). See the `underlying_cli` field doc for why the full
-/// `classify_runtime` predicate is deliberately not used here.
-fn preset_catalog_entry(
-    def: &PresetHarness,
-    resolve: impl Fn(&str) -> Option<PathBuf>,
-) -> AcpRuntimeCatalogEntry {
-    let (availability, command, binary_path) = match resolve(def.command) {
-        Some(path) => (
-            AcpAvailabilityStatus::Available,
-            Some(def.command.to_string()),
-            Some(path.display().to_string()),
-        ),
-        None => {
-            let underlying_cli_found = def
-                .underlying_cli
-                .map(|cli| resolve(cli).is_some())
-                .unwrap_or(false);
-            if underlying_cli_found {
-                (AcpAvailabilityStatus::AdapterMissing, None, None)
-            } else {
-                (AcpAvailabilityStatus::NotInstalled, None, None)
-            }
-        }
-    };
-    let underlying_cli_path = def
-        .underlying_cli
-        .and_then(resolve)
-        .map(|p| p.display().to_string());
-
-    let default_args = normalize_agent_args(
-        def.command,
-        def.args.iter().map(|s| s.to_string()).collect(),
-    );
-
-    AcpRuntimeCatalogEntry {
-        id: def.id.to_string(),
-        label: def.label.to_string(),
-        // No remote URL — all preset icons are bundled assets.
-        avatar_url: String::new(),
-        availability,
-        command,
-        binary_path,
-        default_args,
-        mcp_command: None,
-        model_env_var: None,
-        provider_env_var: None,
-        thinking_env_var: None,
-        install_hint: def.install_hint.to_string(),
-        install_instructions_url: def.install_instructions_url.to_string(),
-        can_auto_install: false,
-        // Kept false even for adapter presets: presets carry one flat
-        // install_hint (the adapter's), so the requiresExternalCli
-        // "CLI is missing" wording would pair the wrong noun with it.
-        // The builtin path, with per-availability hints, is the only
-        // consumer of the true case.
-        requires_external_cli: false,
-        underlying_cli_path,
-        node_required: false,
-        auth_status: AuthStatus::NotApplicable,
-        login_hint: None,
-        source: HarnessSource::Preset,
-        // Preset entries have static, non-editable env; definition_env is empty.
-        definition_env: Default::default(),
-    }
-}
-
-const PRESET_HARNESSES: &[PresetHarness] = &[
-    PresetHarness {
-        id: "cursor",
-        label: "Cursor",
-        command: "cursor-agent",
-        args: &["acp"],
-        install_instructions_url: "https://cursor.com/downloads",
-        install_hint: "Buzz talks to Cursor through the cursor-agent CLI's ACP mode.",
-        underlying_cli: None,
-    },
-    PresetHarness {
-        id: "omp",
-        label: "Oh My Pi",
-        command: "omp",
-        args: &["acp"],
-        install_instructions_url: "https://github.com/can1357/oh-my-pi",
-        install_hint: "Buzz talks to Oh My Pi through its CLI's ACP mode (omp acp).",
-        underlying_cli: None,
-    },
-    PresetHarness {
-        id: "grok",
-        label: "Grok Build",
-        command: "grok",
-        args: &["agent", "--always-approve", "stdio"],
-        install_instructions_url: "https://build.x.ai/docs",
-        install_hint: "Buzz talks to Grok Build through its CLI's agent stdio mode.",
-        underlying_cli: None,
-    },
-    PresetHarness {
-        id: "opencode",
-        label: "OpenCode",
-        command: "opencode",
-        args: &["acp"],
-        install_instructions_url: "https://opencode.ai/docs",
-        install_hint: "Buzz talks to OpenCode through its CLI's ACP mode (opencode acp).",
-        underlying_cli: None,
-    },
-    PresetHarness {
-        id: "kimi",
-        label: "Kimi Code",
-        command: "kimi",
-        args: &["acp"],
-        install_instructions_url: "https://kimi.ai/download",
-        install_hint: "Buzz talks to Kimi Code through its CLI's ACP mode (kimi acp).",
-        underlying_cli: None,
-    },
-    PresetHarness {
-        id: "amp",
-        label: "Amp",
-        command: "amp-acp",
-        args: &[],
-        install_instructions_url: "https://github.com/tao12345666333/amp-acp",
-        install_hint: "Buzz talks to the Amp CLI through the amp-acp adapter. Follow the setup guide to install the adapter so the amp-acp command is on your PATH.",
-        underlying_cli: Some("amp"),
-    },
-    PresetHarness {
-        id: "hermes",
-        label: "Hermes Agent",
-        command: "hermes-acp",
-        args: &[],
-        install_instructions_url: "https://hermes-agent.nousresearch.com",
-        install_hint: "Buzz talks to Hermes Agent through its hermes-acp command.",
-        underlying_cli: None,
-    },
-    PresetHarness {
-        id: "openclaw",
-        label: "OpenClaw",
-        command: "openclaw",
-        args: &["acp"],
-        install_instructions_url: "https://docs.openclaw.ai/start/getting-started",
-        install_hint: "Buzz talks to OpenClaw through its ACP mode (openclaw acp), which relies on the OpenClaw Gateway daemon. Follow the setup guide to install both.\n\n\
-            ⚠️  Execution-locus note: `openclaw acp` runs tools inside the \
-            OpenClaw Gateway daemon, not in the Desktop process. \
-            Desktop-injected BUZZ_* env vars are visible to the `openclaw` \
-            harness process itself, but do NOT automatically reach the \
-            Gateway's execution environment. If your tools or agent logic \
-            needs BUZZ_* credentials at execution time, set them on the \
-            Gateway's own environment separately.",
-        underlying_cli: None,
-    },
-];
-
-/// Return the static preset harness definitions as `HarnessDefinition` values.
-///
-/// Used by `warm_harness_registry_from_dir` to seed the loaded-harness registry
-/// at startup before the frontend triggers a full discovery run.
-pub(crate) fn preset_harness_definitions(
-) -> Vec<crate::managed_agents::custom_harnesses::HarnessDefinition> {
-    PRESET_HARNESSES
-        .iter()
-        .map(
-            |p| crate::managed_agents::custom_harnesses::HarnessDefinition {
-                id: p.id.to_string(),
-                label: p.label.to_string(),
-                command: p.command.to_string(),
-                args: p.args.iter().map(|s| s.to_string()).collect(),
-                env: std::collections::BTreeMap::new(),
-                install_instructions_url: p.install_instructions_url.to_string(),
-                install_hint: p.install_hint.to_string(),
-            },
-        )
-        .collect()
-}
-
-/// Return the static slice of preset harness IDs.
-///
-/// Used by `check_id_collision` in `custom_harnesses` to derive the reserved-ID
-/// set from the single source of truth (`PRESET_HARNESSES`) rather than a
-/// hand-maintained copy.  Adding a preset automatically reserves its ID.
-pub(crate) fn preset_harness_ids() -> &'static [&'static str] {
-    // `PRESET_HARNESSES` is `'static`; we project its `id` fields.
-    // Computed once via OnceLock to avoid repeated allocations on hot paths.
-    use std::sync::OnceLock;
-    static IDS: OnceLock<Vec<&'static str>> = OnceLock::new();
-    IDS.get_or_init(|| PRESET_HARNESSES.iter().map(|p| p.id).collect())
-        .as_slice()
-}
-
 /// Discover all ACP runtimes, optionally merging user-defined custom harnesses
 /// from `custom_harnesses_dir`.
 ///
diff --git a/desktop/src-tauri/src/managed_agents/discovery/presets.rs b/desktop/src-tauri/src/managed_agents/discovery/presets.rs
new file mode 100644
index 0000000000..3622b21c4a
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/discovery/presets.rs
@@ -0,0 +1,335 @@
+use std::path::PathBuf;
+use std::sync::OnceLock;
+
+use crate::managed_agents::{
+    AcpAvailabilityStatus, AcpRuntimeCatalogEntry, AuthStatus, HarnessSource,
+};
+
+use super::normalize_agent_args;
+
+/// Static data for a well-known tier-2 ACP harness.
+pub(super) struct PresetHarness {
+    pub(super) id: &'static str,
+    label: &'static str,
+    command: &'static str,
+    args: &'static [&'static str],
+    install_instructions_url: &'static str,
+    install_hint: &'static str,
+    /// Vendor CLI the ACP command wraps, when the preset is an adapter.
+    ///
+    /// Consulted only when the adapter is absent, so `AdapterMissing` replaces
+    /// `NotInstalled` when the CLI is present but the adapter is not. `None`
+    /// when the command is itself the vendor CLI.
+    underlying_cli: Option<&'static str>,
+}
+
+/// Build one preset catalog entry through an injectable command resolver.
+pub(super) fn preset_catalog_entry(
+    def: &PresetHarness,
+    resolve: impl Fn(&str) -> Option<PathBuf>,
+) -> AcpRuntimeCatalogEntry {
+    let (availability, command, binary_path) = match resolve(def.command) {
+        Some(path) => (
+            AcpAvailabilityStatus::Available,
+            Some(def.command.to_string()),
+            Some(path.display().to_string()),
+        ),
+        None => {
+            let underlying_cli_found = def
+                .underlying_cli
+                .map(|cli| resolve(cli).is_some())
+                .unwrap_or(false);
+            if underlying_cli_found {
+                (AcpAvailabilityStatus::AdapterMissing, None, None)
+            } else {
+                (AcpAvailabilityStatus::NotInstalled, None, None)
+            }
+        }
+    };
+    let underlying_cli_path = def
+        .underlying_cli
+        .and_then(resolve)
+        .map(|path| path.display().to_string());
+
+    AcpRuntimeCatalogEntry {
+        id: def.id.to_string(),
+        label: def.label.to_string(),
+        // No remote URL — all preset icons are bundled assets.
+        avatar_url: String::new(),
+        availability,
+        command,
+        binary_path,
+        default_args: normalize_agent_args(
+            def.command,
+            def.args.iter().map(|arg| arg.to_string()).collect(),
+        ),
+        mcp_command: None,
+        model_env_var: None,
+        provider_env_var: None,
+        thinking_env_var: None,
+        install_hint: def.install_hint.to_string(),
+        install_instructions_url: def.install_instructions_url.to_string(),
+        can_auto_install: false,
+        // Presets carry one flat install hint, so builtin external-CLI copy
+        // would name the wrong missing component for adapter presets.
+        requires_external_cli: false,
+        underlying_cli_path,
+        node_required: false,
+        auth_status: AuthStatus::NotApplicable,
+        login_hint: None,
+        source: HarnessSource::Preset,
+        definition_env: Default::default(),
+    }
+}
+
+pub(super) const PRESET_HARNESSES: &[PresetHarness] = &[
+    PresetHarness {
+        id: "devin",
+        label: "Devin",
+        command: "devin",
+        args: &["acp"],
+        install_instructions_url: "https://docs.devin.ai/cli",
+        install_hint: "Buzz talks to Devin through the official Devin CLI's ACP mode (devin acp).",
+        underlying_cli: None,
+    },
+    PresetHarness {
+        id: "cursor",
+        label: "Cursor",
+        command: "cursor-agent",
+        args: &["acp"],
+        install_instructions_url: "https://cursor.com/downloads",
+        install_hint: "Buzz talks to Cursor through the cursor-agent CLI's ACP mode.",
+        underlying_cli: None,
+    },
+    PresetHarness {
+        id: "omp",
+        label: "Oh My Pi",
+        command: "omp",
+        args: &["acp"],
+        install_instructions_url: "https://omp.sh/",
+        install_hint: "Buzz talks to Oh My Pi through its CLI's ACP mode (omp acp).",
+        underlying_cli: None,
+    },
+    PresetHarness {
+        id: "grok",
+        label: "Grok Build",
+        command: "grok",
+        args: &["agent", "--always-approve", "stdio"],
+        install_instructions_url: "https://build.x.ai/docs",
+        install_hint: "Buzz talks to Grok Build through its CLI's agent stdio mode.",
+        underlying_cli: None,
+    },
+    PresetHarness {
+        id: "opencode",
+        label: "OpenCode",
+        command: "opencode",
+        args: &["acp"],
+        install_instructions_url: "https://opencode.ai/docs",
+        install_hint: "Buzz talks to OpenCode through its CLI's ACP mode (opencode acp).",
+        underlying_cli: None,
+    },
+    PresetHarness {
+        id: "kimi",
+        label: "Kimi Code",
+        command: "kimi",
+        args: &["acp"],
+        install_instructions_url: "https://kimi.ai/download",
+        install_hint: "Buzz talks to Kimi Code through its CLI's ACP mode (kimi acp).",
+        underlying_cli: None,
+    },
+    PresetHarness {
+        id: "amp",
+        label: "Amp",
+        command: "amp-acp",
+        args: &[],
+        install_instructions_url: "https://github.com/tao12345666333/amp-acp",
+        install_hint: "Buzz talks to the Amp CLI through the amp-acp adapter. Follow the setup guide to install the adapter so the amp-acp command is on your PATH.",
+        underlying_cli: Some("amp"),
+    },
+    PresetHarness {
+        id: "hermes",
+        label: "Hermes Agent",
+        command: "hermes-acp",
+        args: &[],
+        install_instructions_url: "https://hermes-agent.nousresearch.com",
+        install_hint: "Buzz talks to Hermes Agent through its hermes-acp command.",
+        underlying_cli: None,
+    },
+    PresetHarness {
+        id: "openclaw",
+        label: "OpenClaw",
+        command: "openclaw",
+        args: &["acp"],
+        install_instructions_url: "https://docs.openclaw.ai/start/getting-started",
+        install_hint: "Buzz talks to OpenClaw through its ACP mode (openclaw acp), which relies on the OpenClaw Gateway daemon. Follow the setup guide to install both.\n\n\
+            ⚠️  Execution-locus note: `openclaw acp` runs tools inside the \
+            OpenClaw Gateway daemon, not in the Desktop process. \
+            Desktop-injected BUZZ_* env vars are visible to the `openclaw` \
+            harness process itself, but do NOT automatically reach the \
+            Gateway's execution environment. If your tools or agent logic \
+            needs BUZZ_* credentials at execution time, set them on the \
+            Gateway's own environment separately.",
+        underlying_cli: None,
+    },
+];
+
+/// Return preset definitions for the spawn/readiness registry.
+pub(crate) fn preset_harness_definitions(
+) -> Vec<crate::managed_agents::custom_harnesses::HarnessDefinition> {
+    PRESET_HARNESSES
+        .iter()
+        .map(
+            |preset| crate::managed_agents::custom_harnesses::HarnessDefinition {
+                id: preset.id.to_string(),
+                label: preset.label.to_string(),
+                command: preset.command.to_string(),
+                args: preset.args.iter().map(|arg| arg.to_string()).collect(),
+                env: Default::default(),
+                install_instructions_url: preset.install_instructions_url.to_string(),
+                install_hint: preset.install_hint.to_string(),
+            },
+        )
+        .collect()
+}
+
+/// Return preset IDs from the catalog's single source of truth.
+pub(crate) fn preset_harness_ids() -> &'static [&'static str] {
+    static IDS: OnceLock<Vec<&'static str>> = OnceLock::new();
+    IDS.get_or_init(|| PRESET_HARNESSES.iter().map(|preset| preset.id).collect())
+        .as_slice()
+}
+
+#[cfg(test)]
+mod tests {
+    use std::path::PathBuf;
+
+    use crate::managed_agents::{AcpAvailabilityStatus, AuthStatus, HarnessSource};
+
+    use super::{preset_catalog_entry, PresetHarness, PRESET_HARNESSES};
+
+    /// Amp-shaped preset: an ACP adapter wrapping a separately installed CLI.
+    const ADAPTER_PRESET: PresetHarness = PresetHarness {
+        id: "amp-test",
+        label: "Amp Test",
+        command: "amp-acp",
+        args: &[],
+        install_instructions_url: "https://example.com/install",
+        install_hint: "Install the amp-acp npm adapter.",
+        underlying_cli: Some("amp"),
+    };
+
+    #[test]
+    fn devin_preset_uses_official_native_acp_invocation() {
+        let preset = PRESET_HARNESSES
+            .iter()
+            .find(|preset| preset.id == "devin")
+            .expect("Devin preset should be present");
+
+        assert_eq!(preset.label, "Devin");
+        assert_eq!(preset.command, "devin");
+        assert_eq!(preset.args, &["acp"]);
+        assert_eq!(preset.underlying_cli, None);
+        assert_eq!(preset.install_instructions_url, "https://docs.devin.ai/cli");
+
+        let entry = preset_catalog_entry(preset, |command| {
+            (command == "devin").then(|| PathBuf::from("/usr/local/bin/devin"))
+        });
+        assert_eq!(entry.availability, AcpAvailabilityStatus::Available);
+        assert_eq!(entry.command.as_deref(), Some("devin"));
+        assert_eq!(entry.default_args, vec!["acp"]);
+        assert_eq!(entry.binary_path.as_deref(), Some("/usr/local/bin/devin"));
+        assert_eq!(entry.auth_status, AuthStatus::NotApplicable);
+        assert_eq!(entry.source, HarnessSource::Preset);
+
+        let missing_entry = preset_catalog_entry(preset, |_| None);
+        assert_eq!(
+            missing_entry.availability,
+            AcpAvailabilityStatus::NotInstalled
+        );
+        assert!(missing_entry.command.is_none());
+        assert_eq!(missing_entry.default_args, vec!["acp"]);
+    }
+
+    #[test]
+    fn devin_preset_is_exposed_in_the_runtime_catalog() {
+        use crate::managed_agents::custom_harnesses::registry_test_lock;
+
+        // Discovery touches process-global command-resolution and the loaded
+        // harness registry. Serialize with the other discovery tests.
+        let _path_guard = crate::managed_agents::lock_path_mutex();
+        let _registry_guard = registry_test_lock();
+
+        let entry = super::super::discover_acp_runtimes_from(None)
+            .into_iter()
+            .find(|entry| entry.id == "devin")
+            .expect("Devin preset should appear in the runtime catalog");
+
+        assert_eq!(entry.label, "Devin");
+        assert_eq!(entry.default_args, vec!["acp"]);
+        assert_eq!(entry.install_instructions_url, "https://docs.devin.ai/cli");
+        assert_eq!(entry.source, HarnessSource::Preset);
+    }
+
+    #[test]
+    fn adapter_missing_when_underlying_cli_present() {
+        let entry = preset_catalog_entry(&ADAPTER_PRESET, |command| {
+            (command == "amp").then(|| PathBuf::from("/usr/local/bin/amp"))
+        });
+        assert_eq!(entry.availability, AcpAvailabilityStatus::AdapterMissing);
+        assert!(entry.command.is_none());
+        assert!(entry.binary_path.is_none());
+        assert_eq!(
+            entry.underlying_cli_path.as_deref(),
+            Some("/usr/local/bin/amp")
+        );
+        assert!(!entry.requires_external_cli);
+        assert_eq!(entry.install_hint, "Install the amp-acp npm adapter.");
+    }
+
+    #[test]
+    fn not_installed_when_adapter_and_cli_are_missing() {
+        let entry = preset_catalog_entry(&ADAPTER_PRESET, |_| None);
+        assert_eq!(entry.availability, AcpAvailabilityStatus::NotInstalled);
+        assert!(entry.underlying_cli_path.is_none());
+        assert!(!entry.requires_external_cli);
+    }
+
+    #[test]
+    fn available_when_adapter_and_cli_are_present() {
+        let entry = preset_catalog_entry(&ADAPTER_PRESET, |command| match command {
+            "amp-acp" => Some(PathBuf::from("/usr/local/bin/amp-acp")),
+            "amp" => Some(PathBuf::from("/usr/local/bin/amp")),
+            _ => None,
+        });
+        assert_eq!(entry.availability, AcpAvailabilityStatus::Available);
+        assert_eq!(entry.command.as_deref(), Some("amp-acp"));
+        assert_eq!(entry.binary_path.as_deref(), Some("/usr/local/bin/amp-acp"));
+        assert_eq!(
+            entry.underlying_cli_path.as_deref(),
+            Some("/usr/local/bin/amp")
+        );
+    }
+
+    #[test]
+    fn adapter_presence_is_enough_for_availability() {
+        let entry = preset_catalog_entry(&ADAPTER_PRESET, |command| {
+            (command == "amp-acp").then(|| PathBuf::from("/usr/local/bin/amp-acp"))
+        });
+        assert_eq!(entry.availability, AcpAvailabilityStatus::Available);
+        assert_eq!(entry.command.as_deref(), Some("amp-acp"));
+        assert_eq!(entry.binary_path.as_deref(), Some("/usr/local/bin/amp-acp"));
+        assert!(entry.underlying_cli_path.is_none());
+    }
+
+    #[test]
+    fn preset_without_underlying_cli_stays_simple() {
+        let preset = PresetHarness {
+            underlying_cli: None,
+            ..ADAPTER_PRESET
+        };
+        let entry = preset_catalog_entry(&preset, |_| None);
+        assert_eq!(entry.availability, AcpAvailabilityStatus::NotInstalled);
+        assert!(!entry.requires_external_cli);
+        assert!(entry.underlying_cli_path.is_none());
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/discovery/tests.rs b/desktop/src-tauri/src/managed_agents/discovery/tests.rs
index 1b587dca0e..6fe6a77521 100644
--- a/desktop/src-tauri/src/managed_agents/discovery/tests.rs
+++ b/desktop/src-tauri/src/managed_agents/discovery/tests.rs
@@ -6,9 +6,9 @@ use super::{
     codex_adapter_is_outdated, create_time_agent_command_override, default_agent_command,
     effective_agent_command, find_nvm_default_bin, find_via_login_shell,
     is_login_shell_path_uninit, is_safe_nvm_tag, managed_agent_avatar_url, normalize_agent_args,
-    parse_semver_tag, preset_catalog_entry, probe_codex_acp_version, record_agent_command,
-    refresh_login_shell_path, try_record_agent_command, PresetHarness, BUZZ_AGENT_AVATAR_URL,
-    CLAUDE_CODE_AVATAR_URL, CODEX_AVATAR_URL, GOOSE_AVATAR_URL,
+    parse_semver_tag, probe_codex_acp_version, record_agent_command, refresh_login_shell_path,
+    try_record_agent_command, BUZZ_AGENT_AVATAR_URL, CLAUDE_CODE_AVATAR_URL, CODEX_AVATAR_URL,
+    GOOSE_AVATAR_URL,
 };
 use crate::managed_agents::AcpAvailabilityStatus;
 
@@ -187,90 +187,6 @@ fn classifies_cli_missing_when_adapter_found_but_cli_absent() {
     assert_eq!(path.as_deref(), Some("/opt/homebrew/bin/codex-acp"));
 }
 
-/// Amp-shaped preset: an ACP adapter (`amp-acp`) wrapping a separately
-/// installed vendor CLI (`amp`).
-const ADAPTER_PRESET: PresetHarness = PresetHarness {
-    id: "amp-test",
-    label: "Amp Test",
-    command: "amp-acp",
-    args: &[],
-    install_instructions_url: "https://example.com/install",
-    install_hint: "Install the amp-acp npm adapter.",
-    underlying_cli: Some("amp"),
-};
-
-#[test]
-fn preset_entry_adapter_missing_when_underlying_cli_present() {
-    // Vendor CLI resolves, adapter does not — the state Tyler's Amp
-    // hand-test hit. Must NOT degrade to the misleading NotInstalled.
-    let entry = preset_catalog_entry(&ADAPTER_PRESET, |cmd| {
-        (cmd == "amp").then(|| PathBuf::from("/usr/local/bin/amp"))
-    });
-    assert_eq!(entry.availability, AcpAvailabilityStatus::AdapterMissing);
-    assert!(entry.command.is_none());
-    assert!(entry.binary_path.is_none());
-    assert_eq!(
-        entry.underlying_cli_path.as_deref(),
-        Some("/usr/local/bin/amp")
-    );
-    assert!(!entry.requires_external_cli);
-    assert_eq!(entry.install_hint, "Install the amp-acp npm adapter.");
-}
-
-#[test]
-fn preset_entry_not_installed_when_both_missing() {
-    let entry = preset_catalog_entry(&ADAPTER_PRESET, |_| None);
-    assert_eq!(entry.availability, AcpAvailabilityStatus::NotInstalled);
-    assert!(entry.underlying_cli_path.is_none());
-    assert!(!entry.requires_external_cli);
-}
-
-#[test]
-fn preset_entry_available_when_adapter_and_cli_present() {
-    let entry = preset_catalog_entry(&ADAPTER_PRESET, |cmd| match cmd {
-        "amp-acp" => Some(PathBuf::from("/usr/local/bin/amp-acp")),
-        "amp" => Some(PathBuf::from("/usr/local/bin/amp")),
-        _ => None,
-    });
-    assert_eq!(entry.availability, AcpAvailabilityStatus::Available);
-    assert_eq!(entry.command.as_deref(), Some("amp-acp"));
-    assert_eq!(entry.binary_path.as_deref(), Some("/usr/local/bin/amp-acp"));
-    assert_eq!(
-        entry.underlying_cli_path.as_deref(),
-        Some("/usr/local/bin/amp")
-    );
-}
-
-#[test]
-fn preset_entry_stays_available_when_adapter_present_but_cli_absent() {
-    // Wren's regression guard: today an `amp-acp` install without `amp`
-    // is Available and selectable. Feeding underlying_cli through the
-    // FULL classify_runtime predicate would flip this to CliMissing
-    // (unselectable, with backwards install copy) — the adapter-missing
-    // arm is the only one presets consume.
-    let entry = preset_catalog_entry(&ADAPTER_PRESET, |cmd| {
-        (cmd == "amp-acp").then(|| PathBuf::from("/usr/local/bin/amp-acp"))
-    });
-    assert_eq!(entry.availability, AcpAvailabilityStatus::Available);
-    assert_eq!(entry.command.as_deref(), Some("amp-acp"));
-    assert_eq!(entry.binary_path.as_deref(), Some("/usr/local/bin/amp-acp"));
-    assert!(entry.underlying_cli_path.is_none());
-}
-
-#[test]
-fn preset_entry_without_underlying_cli_stays_simple() {
-    // Most presets: the command IS the vendor CLI. No external-CLI flag,
-    // absent command means plain NotInstalled.
-    let preset = PresetHarness {
-        underlying_cli: None,
-        ..ADAPTER_PRESET
-    };
-    let entry = preset_catalog_entry(&preset, |_| None);
-    assert_eq!(entry.availability, AcpAvailabilityStatus::NotInstalled);
-    assert!(!entry.requires_external_cli);
-    assert!(entry.underlying_cli_path.is_none());
-}
-
 fn persona_with_runtime(id: &str, runtime: Option<&str>) -> crate::managed_agents::AgentDefinition {
     crate::managed_agents::AgentDefinition {
         id: id.to_string(),
diff --git a/desktop/src-tauri/src/managed_agents/env_vars.rs b/desktop/src-tauri/src/managed_agents/env_vars.rs
index 592a5cbbd9..1653371e7f 100644
--- a/desktop/src-tauri/src/managed_agents/env_vars.rs
+++ b/desktop/src-tauri/src/managed_agents/env_vars.rs
@@ -77,6 +77,10 @@ pub(crate) const RESERVED_ENV_KEYS: &[&str] = &[
     "BUZZ_ACP_RESPOND_TO",
     "BUZZ_ACP_RESPOND_TO_ALLOWLIST",
     "BUZZ_ACP_AGENT_OWNER",
+    // Remote lifetime/presence policy: user env must not disable the
+    // desktop/provider-owned bounds while the saved record still promises them.
+    "BUZZ_ACP_EXIT_AFTER_INACTIVITY",
+    "BUZZ_ACP_NO_PRESENCE",
     // Readiness handoff: desktop is the ONLY readiness source. A saved or
     // ambient env var must not be able to forge setup mode (NotReady) on a
     // Ready agent or suppress it (empty/stale payload) on a NotReady one.
@@ -307,28 +311,5 @@ pub(crate) fn live_persona_env(
         .unwrap_or_default()
 }
 
-/// Resolve live env_vars for a linked persona, loading personas from disk.
-///
-/// Returns the persona's `env_vars` map if a persona_id is provided and found;
-/// returns an empty map if no persona is linked. Errors if the linked persona
-/// is missing. Used by the provider deploy path, which has no pre-loaded
-/// persona slice.
-pub(crate) fn resolve_persona_env(
-    app: &tauri::AppHandle,
-    persona_id: Option<&str>,
-) -> Result<std::collections::BTreeMap<String, String>, String> {
-    let Some(pid) = persona_id else {
-        return Ok(std::collections::BTreeMap::new());
-    };
-    let personas = super::load_personas(app).map_err(|e| {
-        format!("failed to load personas while resolving env for persona `{pid}`: {e}")
-    })?;
-    let persona = personas
-        .into_iter()
-        .find(|p| p.id == pid)
-        .ok_or_else(|| format!("persona `{pid}` not found while resolving env"))?;
-    Ok(persona.env_vars)
-}
-
 #[cfg(test)]
 mod tests;
diff --git a/desktop/src-tauri/src/managed_agents/env_vars/tests.rs b/desktop/src-tauri/src/managed_agents/env_vars/tests.rs
index cf57b12546..534c2e0835 100644
--- a/desktop/src-tauri/src/managed_agents/env_vars/tests.rs
+++ b/desktop/src-tauri/src/managed_agents/env_vars/tests.rs
@@ -158,6 +158,15 @@ fn reserved_keys_include_respond_to_gate() {
     }
 }
 
+#[test]
+fn reserved_keys_include_remote_lifetime_policy() {
+    for key in ["BUZZ_ACP_EXIT_AFTER_INACTIVITY", "BUZZ_ACP_NO_PRESENCE"] {
+        assert!(is_reserved_env_key(key), "{key} should be reserved");
+        let agent = map(&[(key, "0")]);
+        assert!(merged_user_env(&BTreeMap::new(), &agent).is_empty());
+    }
+}
+
 #[test]
 fn reserved_keys_include_code_execution_surface() {
     // The agent/MCP command + args are what Buzz actually exec's.
diff --git a/desktop/src-tauri/src/managed_agents/mod.rs b/desktop/src-tauri/src/managed_agents/mod.rs
index b0e86f8edb..772d707f27 100644
--- a/desktop/src-tauri/src/managed_agents/mod.rs
+++ b/desktop/src-tauri/src/managed_agents/mod.rs
@@ -1,6 +1,7 @@
 mod agent_env;
 pub(crate) mod agent_events;
 pub(crate) mod agent_snapshot;
+pub(crate) mod agent_snapshot_envelope;
 pub(crate) mod team_snapshot;
 pub(crate) use agent_env::{
     baked_build_env, build_buzz_agent_provider_defaults, discovery_env_with_baked_floor,
@@ -29,6 +30,7 @@ pub mod retention;
 mod runtime;
 mod runtime_commands;
 mod runtime_types;
+pub(crate) mod snapshot_avatar;
 pub(crate) mod spawn_hash;
 pub(crate) mod storage;
 pub(crate) mod team_events;
diff --git a/desktop/src-tauri/src/managed_agents/nest.rs b/desktop/src-tauri/src/managed_agents/nest.rs
index e13ab2baad..c8f008836d 100644
--- a/desktop/src-tauri/src/managed_agents/nest.rs
+++ b/desktop/src-tauri/src/managed_agents/nest.rs
@@ -50,7 +50,7 @@ const NEST_AGENTS_VERSION: u32 = 4;
 
 /// Template content version for SKILL.md.
 /// Bump this when changing `nest_skill.md` to trigger refresh on existing installs.
-const NEST_SKILL_VERSION: u32 = 4;
+const NEST_SKILL_VERSION: u32 = 5;
 
 const BEGIN_MARKER: &str = "<!-- BEGIN BUZZ MANAGED";
 const END_MARKER: &str = "<!-- END BUZZ MANAGED -->";
diff --git a/desktop/src-tauri/src/managed_agents/nest/tests.rs b/desktop/src-tauri/src/managed_agents/nest/tests.rs
index d2c415e725..031b049a49 100644
--- a/desktop/src-tauri/src/managed_agents/nest/tests.rs
+++ b/desktop/src-tauri/src/managed_agents/nest/tests.rs
@@ -29,6 +29,18 @@ fn init_nest_dir_prod_sets_buzz() {
     }
 }
 
+#[test]
+fn nest_skill_contains_safe_mention_workflow() {
+    assert!(BUZZ_CLI_SKILL_MD.contains("--mention <hex-or-npub>"));
+    assert!(BUZZ_CLI_SKILL_MD.contains("every presentation-only name that should notify"));
+    assert!(BUZZ_CLI_SKILL_MD
+        .contains("permits unresolved or ambiguous `@Name` text as presentation-only"));
+    assert!(BUZZ_CLI_SKILL_MD.contains("signed event's `mention_pubkeys`"));
+    assert!(BUZZ_CLI_SKILL_MD.contains("no follow-up verification command is needed"));
+    assert!(BUZZ_CLI_SKILL_MD.contains("Add membership separately only when authorized"));
+    assert!(BUZZ_CLI_SKILL_MD.contains("never changes membership automatically"));
+}
+
 #[test]
 fn ensure_nest_creates_all_dirs_and_agents_md() {
     let tmp = tempfile::tempdir().unwrap();
diff --git a/desktop/src-tauri/src/managed_agents/nest_skill.md b/desktop/src-tauri/src/managed_agents/nest_skill.md
index fefdfa77fa..79a5ea301d 100644
--- a/desktop/src-tauri/src/managed_agents/nest_skill.md
+++ b/desktop/src-tauri/src/managed_agents/nest_skill.md
@@ -87,14 +87,11 @@ Write commands are unaffected. `--format json` (default) returns full fields.
 
 ## Communication Patterns
 
-**Mentions that notify:** Use `@Name` directly in message content — the CLI auto-resolves channel members by name and adds the required p-tags. No `--mention` flag exists or is needed. `nostr:npub1…` inline references are also auto-resolved to p-tags without needing a flag.
+**Mentions that notify:** Keep readable `@Name` text in message content and, when intended pubkeys are known, pass the identities in the same send with repeatable `--mention <hex-or-npub>`. Any explicit identity (`--mention` or `nostr:npub...`) permits unresolved or ambiguous `@Name` text as presentation-only; uniquely resolved member names still add recipients. Include a pubkey for every presentation-only name that should notify. The CLI reports the signed event's `mention_pubkeys`; no follow-up verification command is needed. Without explicit identities, names resolve against current channel members. An unresolved/ambiguous name or non-member target stops before publishing. Add membership separately only when authorized, then retry; sending never changes membership automatically.
 
 ```bash
-# ✅ Correct — notification delivered automatically
-buzz messages send --channel <UUID> --content "@Alice check this"
-
-# Multiple mentions — same pattern
-buzz messages send --channel <UUID> --content "@Alice @Bob review please"
+buzz messages send --channel <UUID> \
+  --content "@Alice check this" --mention <alice-pubkey>
 ```
 
 ## DM Management
diff --git a/desktop/src-tauri/src/managed_agents/persona_events.rs b/desktop/src-tauri/src/managed_agents/persona_events.rs
index ea61a811db..6afc18a501 100644
--- a/desktop/src-tauri/src/managed_agents/persona_events.rs
+++ b/desktop/src-tauri/src/managed_agents/persona_events.rs
@@ -5,7 +5,7 @@
 
 use std::collections::BTreeMap;
 
-use buzz_core_pkg::kind::{persona_event_is_shared, KIND_PERSONA};
+use buzz_core_pkg::kind::{event_is_shared, KIND_PERSONA};
 use nostr::{EventBuilder, Kind, Tag};
 use serde::{Deserialize, Serialize};
 
@@ -192,7 +192,7 @@ pub fn persona_from_event(event: &nostr::Event) -> Result<AgentDefinition, Strin
         name_pool: content.name_pool,
         is_builtin: false,
         is_active: true,
-        shared: persona_event_is_shared(event),
+        shared: event_is_shared(event),
         source_team: None,
         source_team_persona_slug: Some(d_tag),
         catalog_source: None,
diff --git a/desktop/src-tauri/src/managed_agents/readiness.rs b/desktop/src-tauri/src/managed_agents/readiness.rs
index c053d933c5..fa8eb36fa1 100644
--- a/desktop/src-tauri/src/managed_agents/readiness.rs
+++ b/desktop/src-tauri/src/managed_agents/readiness.rs
@@ -481,6 +481,7 @@ fn buzz_agent_requirements(effective: &EffectiveAgentEnv) -> Vec<Requirement> {
         }
         Some("anthropic") => Some("ANTHROPIC_MODEL"),
         Some("openai") | Some("openai-compat") => Some("OPENAI_COMPAT_MODEL"),
+        Some("openrouter") => Some("OPENROUTER_MODEL"),
         _ => None,
     };
     let model_present = effective
@@ -523,6 +524,12 @@ fn buzz_agent_requirements(effective: &EffectiveAgentEnv) -> Vec<Requirement> {
                     key: "DATABRICKS_HOST".to_string(),
                 });
             }
+        Some("openrouter")
+            if env_key_missing("OPENROUTER_API_KEY") => {
+                missing.push(Requirement::EnvKey {
+                    key: "OPENROUTER_API_KEY".to_string(),
+                });
+            }
         _ => {
             // Unknown provider or no provider yet — only the NormalizedField
             // requirement above captures this gap.
@@ -630,6 +637,13 @@ fn goose_requirements(
                 key: "DATABRICKS_HOST".to_string(),
             });
         }
+        Some("openrouter")
+            if env_key_missing("OPENROUTER_API_KEY") && !file_key_present("OPENROUTER_API_KEY") =>
+        {
+            missing.push(Requirement::EnvKey {
+                key: "OPENROUTER_API_KEY".to_string(),
+            });
+        }
         _ => {}
     }
 
@@ -1668,195 +1682,62 @@ mod tests {
                 field: "model".to_string()
             }));
     }
-}
-
-// ── goose file-config–aware requirement tests ─────────────────────────────
-//
-// These tests call `goose_requirements` directly, injecting a synthetic
-// `RuntimeFileConfig` so there is no disk I/O and tests are deterministic.
-
-#[cfg(test)]
-mod goose_file_config_tests {
-    use std::collections::BTreeMap;
-
-    use super::*;
-    use crate::managed_agents::config_bridge::RuntimeFileConfig;
-
-    fn empty_env() -> EffectiveAgentEnv {
-        EffectiveAgentEnv {
-            env: BTreeMap::new(),
-            config_file_path: Some("~/.config/goose/config.yaml"),
-            effective_command: "goose".to_string(),
-        }
-    }
 
-    fn env_with(pairs: &[(&str, &str)]) -> EffectiveAgentEnv {
-        EffectiveAgentEnv {
-            env: pairs
-                .iter()
-                .map(|(k, v)| (k.to_string(), v.to_string()))
-                .collect(),
-            config_file_path: Some("~/.config/goose/config.yaml"),
-            effective_command: "goose".to_string(),
-        }
-    }
-
-    fn databricks_file_config() -> RuntimeFileConfig {
-        let mut extra = BTreeMap::new();
-        extra.insert(
-            "DATABRICKS_HOST".to_string(),
-            "https://dbc.example.com".to_string(),
-        );
-        RuntimeFileConfig {
-            provider: Some("databricks_v2".to_string()),
-            model: Some("goose-claude-4-6-opus".to_string()),
-            extra,
-            ..Default::default()
-        }
-    }
+    // ── OpenRouter readiness ─────────────────────────────────────────────
 
     #[test]
-    fn goose_file_config_silences_databricks_host_requirement() {
-        // File has provider, model, and DATABRICKS_HOST — all requirements silenced.
-        let env = empty_env();
-        let cfg = databricks_file_config();
-        let result = goose_requirements(&env, Some(&cfg));
-        assert!(
-            result.is_empty(),
-            "all requirements should be silenced by goose file config; \
-             got: {:?}",
-            result
-        );
-    }
-
-    #[test]
-    fn goose_env_empty_file_absent_still_not_ready() {
-        // No env, no file config → provider and model both required.
-        let env = empty_env();
-        let result = goose_requirements(&env, None);
-        assert!(
-            result.contains(&Requirement::NormalizedField {
-                field: "provider".to_string()
-            }),
-            "provider must be required when absent from both env and file"
-        );
-        assert!(
-            result.contains(&Requirement::NormalizedField {
-                field: "model".to_string()
-            }),
-            "model must be required when absent from both env and file"
-        );
-    }
-
-    #[test]
-    fn goose_file_config_silences_provider_and_model_but_not_anthropic_key() {
-        // File has provider=anthropic and model, but ANTHROPIC_API_KEY is not
-        // in the file's `extra` map — it must still be required.
-        let cfg = RuntimeFileConfig {
-            provider: Some("anthropic".to_string()),
-            model: Some("claude-opus-4-5".to_string()),
-            extra: BTreeMap::new(),
-            ..Default::default()
-        };
-        let env = empty_env();
-        let result = goose_requirements(&env, Some(&cfg));
-        // Provider and model silenced.
-        assert!(
-            !result.contains(&Requirement::NormalizedField {
-                field: "provider".to_string()
-            }),
-            "provider silenced by file config"
-        );
-        assert!(
-            !result.contains(&Requirement::NormalizedField {
-                field: "model".to_string()
-            }),
-            "model silenced by file config"
+    fn buzz_agent_openrouter_with_all_fields_is_ready() {
+        let env = make_env(
+            "buzz-agent",
+            env_with(&[
+                ("BUZZ_AGENT_PROVIDER", "openrouter"),
+                ("BUZZ_AGENT_MODEL", "anthropic/claude-sonnet-4"),
+                ("OPENROUTER_API_KEY", "sk-or-test-key"),
+            ]),
         );
-        // ANTHROPIC_API_KEY not in file extra → still required.
+        let result = agent_readiness(&env);
         assert!(
-            result.contains(&Requirement::EnvKey {
-                key: "ANTHROPIC_API_KEY".to_string()
-            }),
-            "ANTHROPIC_API_KEY must remain required when not in file extra"
+            result.is_ready(),
+            "openrouter with all fields should be ready"
         );
     }
 
     #[test]
-    fn goose_env_provider_wins_over_file_provider_for_cred_check() {
-        // Env has GOOSE_PROVIDER=anthropic (different from file's databricks_v2).
-        // The env provider must win for credential checking.
-        let env = env_with(&[
-            ("GOOSE_PROVIDER", "anthropic"),
-            ("GOOSE_MODEL", "claude-opus-4-5"),
-        ]);
-        let cfg = databricks_file_config(); // has provider=databricks_v2
-        let result = goose_requirements(&env, Some(&cfg));
-        // anthropic requires ANTHROPIC_API_KEY, not DATABRICKS_HOST.
-        assert!(
-            result.contains(&Requirement::EnvKey {
-                key: "ANTHROPIC_API_KEY".to_string()
-            }),
-            "env provider=anthropic must require ANTHROPIC_API_KEY"
-        );
-        assert!(
-            !result.contains(&Requirement::EnvKey {
-                key: "DATABRICKS_HOST".to_string()
-            }),
-            "env provider=anthropic must NOT require DATABRICKS_HOST"
+    fn buzz_agent_openrouter_missing_key_returns_not_ready() {
+        let env = make_env(
+            "buzz-agent",
+            env_with(&[
+                ("BUZZ_AGENT_PROVIDER", "openrouter"),
+                ("BUZZ_AGENT_MODEL", "anthropic/claude-sonnet-4"),
+            ]),
         );
+        let result = agent_readiness(&env);
+        assert!(!result.is_ready());
+        assert!(result.requirements().contains(&Requirement::EnvKey {
+            key: "OPENROUTER_API_KEY".to_string()
+        }));
     }
 
     #[test]
-    fn goose_flat_databricks_host_in_file_config_silences_requirement() {
-        // Will's typical goose config: flat DATABRICKS_HOST at the top level,
-        // no active_provider — provider inferred as "databricks".
-        // The parser must store extra["DATABRICKS_HOST"] = value (canonical key),
-        // and goose_requirements must then silence the DATABRICKS_HOST requirement.
-        let mut extra = BTreeMap::new();
-        extra.insert(
-            "DATABRICKS_HOST".to_string(),
-            "https://block.cloud.databricks.com".to_string(),
-        );
-        let cfg = RuntimeFileConfig {
-            provider: Some("databricks".to_string()),
-            model: Some("goose-claude-4-5".to_string()),
-            extra,
-            ..Default::default()
-        };
-        let env = empty_env();
-        let result = goose_requirements(&env, Some(&cfg));
-        // All requirements silenced — provider (file), model (file), DATABRICKS_HOST (file).
-        assert!(
-            result.is_empty(),
-            "flat DATABRICKS_HOST in file config must silence all requirements; \
-             got: {:?}",
-            result
+    fn buzz_agent_openrouter_with_provider_model_fallback_is_ready() {
+        let env = make_env(
+            "buzz-agent",
+            env_with(&[
+                ("BUZZ_AGENT_PROVIDER", "openrouter"),
+                ("OPENROUTER_MODEL", "google/gemini-2.5-flash"),
+                ("OPENROUTER_API_KEY", "sk-or-test-key"),
+            ]),
         );
-    }
-
-    #[test]
-    fn goose_goose_provider_databricks_flat_host_silences_databricks_host() {
-        // GOOSE_PROVIDER=databricks (not active_provider) + flat DATABRICKS_HOST.
-        // The parser canonicalizes to extra["DATABRICKS_HOST"]; readiness must silence it.
-        let mut extra = BTreeMap::new();
-        extra.insert(
-            "DATABRICKS_HOST".to_string(),
-            "https://dbc.example.com".to_string(),
-        );
-        let cfg = RuntimeFileConfig {
-            provider: Some("databricks".to_string()),
-            model: Some("some-model".to_string()),
-            extra,
-            ..Default::default()
-        };
-        let env = empty_env();
-        let result = goose_requirements(&env, Some(&cfg));
+        let result = agent_readiness(&env);
         assert!(
-            !result.contains(&Requirement::EnvKey {
-                key: "DATABRICKS_HOST".to_string()
-            }),
-            "DATABRICKS_HOST must be silenced when canonical key is in file extra"
+            result.is_ready(),
+            "OPENROUTER_MODEL fallback should satisfy model requirement"
         );
     }
 }
+
+// Goose file-config-aware requirement tests live in a sibling file so this
+// module stays under the desktop file-size ratchet.
+#[cfg(test)]
+#[path = "readiness_goose_file_config_tests.rs"]
+mod goose_file_config_tests;
diff --git a/desktop/src-tauri/src/managed_agents/readiness_goose_file_config_tests.rs b/desktop/src-tauri/src/managed_agents/readiness_goose_file_config_tests.rs
new file mode 100644
index 0000000000..46d0e4c7a7
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/readiness_goose_file_config_tests.rs
@@ -0,0 +1,190 @@
+//! Goose file-config-aware requirement tests.
+//!
+//! These tests call `goose_requirements` directly, injecting a synthetic
+//! `RuntimeFileConfig` so there is no disk I/O and tests are deterministic.
+//!
+//! Included from `readiness.rs` via `#[path]`; `super::*` therefore resolves
+//! against that module, matching the `storage_tests.rs` convention.
+
+use std::collections::BTreeMap;
+
+use super::*;
+use crate::managed_agents::config_bridge::RuntimeFileConfig;
+
+fn empty_env() -> EffectiveAgentEnv {
+    EffectiveAgentEnv {
+        env: BTreeMap::new(),
+        config_file_path: Some("~/.config/goose/config.yaml"),
+        effective_command: "goose".to_string(),
+    }
+}
+
+fn env_with(pairs: &[(&str, &str)]) -> EffectiveAgentEnv {
+    EffectiveAgentEnv {
+        env: pairs
+            .iter()
+            .map(|(k, v)| (k.to_string(), v.to_string()))
+            .collect(),
+        config_file_path: Some("~/.config/goose/config.yaml"),
+        effective_command: "goose".to_string(),
+    }
+}
+
+fn databricks_file_config() -> RuntimeFileConfig {
+    let mut extra = BTreeMap::new();
+    extra.insert(
+        "DATABRICKS_HOST".to_string(),
+        "https://dbc.example.com".to_string(),
+    );
+    RuntimeFileConfig {
+        provider: Some("databricks_v2".to_string()),
+        model: Some("goose-claude-4-6-opus".to_string()),
+        extra,
+        ..Default::default()
+    }
+}
+
+#[test]
+fn goose_file_config_silences_databricks_host_requirement() {
+    // File has provider, model, and DATABRICKS_HOST — all requirements silenced.
+    let env = empty_env();
+    let cfg = databricks_file_config();
+    let result = goose_requirements(&env, Some(&cfg));
+    assert!(
+        result.is_empty(),
+        "all requirements should be silenced by goose file config; \
+         got: {:?}",
+        result
+    );
+}
+
+#[test]
+fn goose_env_empty_file_absent_still_not_ready() {
+    // No env, no file config → provider and model both required.
+    let env = empty_env();
+    let result = goose_requirements(&env, None);
+    assert!(
+        result.contains(&Requirement::NormalizedField {
+            field: "provider".to_string()
+        }),
+        "provider must be required when absent from both env and file"
+    );
+    assert!(
+        result.contains(&Requirement::NormalizedField {
+            field: "model".to_string()
+        }),
+        "model must be required when absent from both env and file"
+    );
+}
+
+#[test]
+fn goose_file_config_silences_provider_and_model_but_not_anthropic_key() {
+    // File has provider=anthropic and model, but ANTHROPIC_API_KEY is not
+    // in the file's `extra` map — it must still be required.
+    let cfg = RuntimeFileConfig {
+        provider: Some("anthropic".to_string()),
+        model: Some("claude-opus-4-5".to_string()),
+        extra: BTreeMap::new(),
+        ..Default::default()
+    };
+    let env = empty_env();
+    let result = goose_requirements(&env, Some(&cfg));
+    // Provider and model silenced.
+    assert!(
+        !result.contains(&Requirement::NormalizedField {
+            field: "provider".to_string()
+        }),
+        "provider silenced by file config"
+    );
+    assert!(
+        !result.contains(&Requirement::NormalizedField {
+            field: "model".to_string()
+        }),
+        "model silenced by file config"
+    );
+    // ANTHROPIC_API_KEY not in file extra → still required.
+    assert!(
+        result.contains(&Requirement::EnvKey {
+            key: "ANTHROPIC_API_KEY".to_string()
+        }),
+        "ANTHROPIC_API_KEY must remain required when not in file extra"
+    );
+}
+
+#[test]
+fn goose_env_provider_wins_over_file_provider_for_cred_check() {
+    // Env has GOOSE_PROVIDER=anthropic (different from file's databricks_v2).
+    // The env provider must win for credential checking.
+    let env = env_with(&[
+        ("GOOSE_PROVIDER", "anthropic"),
+        ("GOOSE_MODEL", "claude-opus-4-5"),
+    ]);
+    let cfg = databricks_file_config(); // has provider=databricks_v2
+    let result = goose_requirements(&env, Some(&cfg));
+    // anthropic requires ANTHROPIC_API_KEY, not DATABRICKS_HOST.
+    assert!(
+        result.contains(&Requirement::EnvKey {
+            key: "ANTHROPIC_API_KEY".to_string()
+        }),
+        "env provider=anthropic must require ANTHROPIC_API_KEY"
+    );
+    assert!(
+        !result.contains(&Requirement::EnvKey {
+            key: "DATABRICKS_HOST".to_string()
+        }),
+        "env provider=anthropic must NOT require DATABRICKS_HOST"
+    );
+}
+
+#[test]
+fn goose_flat_databricks_host_in_file_config_silences_requirement() {
+    // Will's typical goose config: flat DATABRICKS_HOST at the top level,
+    // no active_provider — provider inferred as "databricks".
+    // The parser must store extra["DATABRICKS_HOST"] = value (canonical key),
+    // and goose_requirements must then silence the DATABRICKS_HOST requirement.
+    let mut extra = BTreeMap::new();
+    extra.insert(
+        "DATABRICKS_HOST".to_string(),
+        "https://block.cloud.databricks.com".to_string(),
+    );
+    let cfg = RuntimeFileConfig {
+        provider: Some("databricks".to_string()),
+        model: Some("goose-claude-4-5".to_string()),
+        extra,
+        ..Default::default()
+    };
+    let env = empty_env();
+    let result = goose_requirements(&env, Some(&cfg));
+    // All requirements silenced — provider (file), model (file), DATABRICKS_HOST (file).
+    assert!(
+        result.is_empty(),
+        "flat DATABRICKS_HOST in file config must silence all requirements; \
+         got: {:?}",
+        result
+    );
+}
+
+#[test]
+fn goose_goose_provider_databricks_flat_host_silences_databricks_host() {
+    // GOOSE_PROVIDER=databricks (not active_provider) + flat DATABRICKS_HOST.
+    // The parser canonicalizes to extra["DATABRICKS_HOST"]; readiness must silence it.
+    let mut extra = BTreeMap::new();
+    extra.insert(
+        "DATABRICKS_HOST".to_string(),
+        "https://dbc.example.com".to_string(),
+    );
+    let cfg = RuntimeFileConfig {
+        provider: Some("databricks".to_string()),
+        model: Some("some-model".to_string()),
+        extra,
+        ..Default::default()
+    };
+    let env = empty_env();
+    let result = goose_requirements(&env, Some(&cfg));
+    assert!(
+        !result.contains(&Requirement::EnvKey {
+            key: "DATABRICKS_HOST".to_string()
+        }),
+        "DATABRICKS_HOST must be silenced when canonical key is in file extra"
+    );
+}
diff --git a/desktop/src-tauri/src/managed_agents/relay_mesh.rs b/desktop/src-tauri/src/managed_agents/relay_mesh.rs
index 7a6f5b094a..5c246feedc 100644
--- a/desktop/src-tauri/src/managed_agents/relay_mesh.rs
+++ b/desktop/src-tauri/src/managed_agents/relay_mesh.rs
@@ -42,15 +42,66 @@ pub fn apply_relay_mesh_env(
         RELAY_MESH_PREFER_MESH_FOR_AUTO_ENV.to_string(),
         "1".to_string(),
     );
-    // Keep the requested response inside smaller local-model context windows,
-    // and spend that budget on an answer/tool call instead of hidden reasoning.
-    // Without both settings Qwen3 either fails the router's fit check at the
-    // agent default (32K) or can consume a tight cap before serializing a tool.
-    env.insert(
-        "BUZZ_AGENT_MAX_OUTPUT_TOKENS".to_string(),
-        "4096".to_string(),
-    );
-    env.insert("BUZZ_AGENT_THINKING_EFFORT".to_string(), "none".to_string());
+    // Keep the requested response inside smaller local-model context windows.
+    // These are defaults, not policy: the effective agent/persona/global env
+    // may deliberately choose a smaller cap or a different effort. This function
+    // runs after those layers during readiness, so never clobber their values.
+    insert_default_if_unset(env, "BUZZ_AGENT_MAX_OUTPUT_TOKENS", "4096");
+    // Mesh agents run on small local models, which are the ones most likely to
+    // do the work and then end the turn without publishing it — the failure the
+    // reply guard exists to catch. Everywhere else it stays opt-in and unset.
+    // A default, not policy: an explicit `0` from the agent/persona/global env
+    // survives (see `insert_default_if_unset`, and the copy-forward list in
+    // `relay_mesh_process_env` that preserves it through the spawn path).
+    insert_default_if_unset(env, "BUZZ_AGENT_REQUIRE_REPLY", "1");
+    // Deliberately no BUZZ_AGENT_THINKING_EFFORT default: mesh translates
+    // `reasoning_effort` into the chat template's `enable_thinking` flag, so any
+    // value we pick overrides each model's own template default — and the right
+    // value is model-specific. Measured with the real prompt and toolset:
+    // gemma-4-E4B delivers 0/8 at `none` but 6/6 with the field absent, while
+    // Qwen3-8B delivers 8/8 either way and burns ~4x the output tokens once
+    // thinking is on (121 -> ~470), risking the 4096 cap. Omitting the field
+    // lets every model use its own default; explicit agent/persona/global
+    // values still apply.
+}
+
+#[cfg(feature = "mesh-llm")]
+fn insert_default_if_unset(
+    env: &mut std::collections::BTreeMap<String, String>,
+    key: &str,
+    value: &str,
+) {
+    if env.get(key).is_none_or(|current| current.trim().is_empty()) {
+        env.insert(key.to_string(), value.to_string());
+    }
+}
+
+/// Build the final Mesh-specific process overrides from the already-resolved
+/// harness environment. Only user-owned generation controls are seeded: the
+/// derived provider/base URL/model values remain authoritative, and unrelated
+/// credentials (notably `OPENAI_API_KEY`) must not be copied back after the
+/// spawn path removes them.
+#[cfg(feature = "mesh-llm")]
+pub fn relay_mesh_process_env(
+    effective_env: &std::collections::BTreeMap<String, String>,
+    model: &str,
+) -> std::collections::BTreeMap<String, String> {
+    let mut env = std::collections::BTreeMap::new();
+    for key in [
+        "BUZZ_AGENT_MAX_OUTPUT_TOKENS",
+        "BUZZ_AGENT_THINKING_EFFORT",
+        // Must be copied forward for the user's value to survive: this map is
+        // written onto the command *after* the layered user env, so a key absent
+        // here is re-defaulted by `apply_relay_mesh_env` below and an explicit
+        // `BUZZ_AGENT_REQUIRE_REPLY=0` would be silently overridden back to `1`.
+        "BUZZ_AGENT_REQUIRE_REPLY",
+    ] {
+        if let Some(value) = effective_env.get(key) {
+            env.insert(key.to_string(), value.clone());
+        }
+    }
+    apply_relay_mesh_env(&mut env, Some(RELAY_MESH_PROVIDER_ID), Some(model));
+    env
 }
 
 #[cfg(all(test, feature = "mesh-llm"))]
@@ -60,7 +111,7 @@ mod tests {
     use super::*;
 
     #[test]
-    fn native_provider_uses_context_safe_non_reasoning_budget() {
+    fn native_provider_uses_context_safe_tool_calling_budget() {
         let mut env = BTreeMap::new();
         apply_relay_mesh_env(
             &mut env,
@@ -72,14 +123,135 @@ mod tests {
             env.get("BUZZ_AGENT_MAX_OUTPUT_TOKENS").map(String::as_str),
             Some("4096")
         );
+        // Must stay unset: any value we pick overrides the model's own chat
+        // template default, and the right value is model-specific ("none"
+        // stops gemma tool-calling; enabling thinking makes Qwen3 burn ~4x the
+        // output budget).
+        assert_eq!(env.get("BUZZ_AGENT_THINKING_EFFORT"), None);
+        assert_eq!(
+            env.get(RELAY_MESH_PREFER_MESH_FOR_AUTO_ENV)
+                .map(String::as_str),
+            Some("1")
+        );
+    }
+
+    #[test]
+    fn native_provider_preserves_explicit_generation_controls() {
+        let mut env = BTreeMap::from([
+            (
+                "BUZZ_AGENT_MAX_OUTPUT_TOKENS".to_string(),
+                "2048".to_string(),
+            ),
+            ("BUZZ_AGENT_THINKING_EFFORT".to_string(), "high".to_string()),
+        ]);
+        apply_relay_mesh_env(
+            &mut env,
+            Some(RELAY_MESH_PROVIDER_ID),
+            Some(RELAY_MESH_AUTO_MODEL_ID),
+        );
+
+        assert_eq!(
+            env.get("BUZZ_AGENT_MAX_OUTPUT_TOKENS").map(String::as_str),
+            Some("2048")
+        );
         assert_eq!(
             env.get("BUZZ_AGENT_THINKING_EFFORT").map(String::as_str),
-            Some("none")
+            Some("high")
+        );
+    }
+
+    #[test]
+    fn native_provider_enables_reply_guard_by_default() {
+        let mut env = BTreeMap::new();
+        apply_relay_mesh_env(
+            &mut env,
+            Some(RELAY_MESH_PROVIDER_ID),
+            Some(RELAY_MESH_AUTO_MODEL_ID),
         );
+
         assert_eq!(
-            env.get(RELAY_MESH_PREFER_MESH_FOR_AUTO_ENV)
-                .map(String::as_str),
+            env.get("BUZZ_AGENT_REQUIRE_REPLY").map(String::as_str),
+            Some("1"),
+            "mesh agents opt into the reply guard automatically"
+        );
+    }
+
+    #[test]
+    fn native_provider_preserves_explicit_reply_guard_opt_out() {
+        let mut env = BTreeMap::from([("BUZZ_AGENT_REQUIRE_REPLY".to_string(), "0".to_string())]);
+        apply_relay_mesh_env(
+            &mut env,
+            Some(RELAY_MESH_PROVIDER_ID),
+            Some(RELAY_MESH_AUTO_MODEL_ID),
+        );
+
+        assert_eq!(
+            env.get("BUZZ_AGENT_REQUIRE_REPLY").map(String::as_str),
+            Some("0"),
+            "an explicit opt-out is a user decision, not a value to re-default"
+        );
+    }
+
+    #[test]
+    fn non_mesh_provider_leaves_reply_guard_unset() {
+        let mut env = BTreeMap::new();
+        apply_relay_mesh_env(&mut env, Some("anthropic"), Some("claude-haiku-4.5"));
+
+        assert_eq!(
+            env.get("BUZZ_AGENT_REQUIRE_REPLY"),
+            None,
+            "the guard stays opt-in everywhere except mesh"
+        );
+        assert!(env.is_empty(), "non-mesh providers get no mesh env at all");
+    }
+
+    /// The spawn path writes this map onto the command *after* the layered user
+    /// env, so an explicit opt-out only survives if it is copied forward. Without
+    /// the copy-forward, `apply_relay_mesh_env` re-defaults it to `1` here and
+    /// silently overrides the user at spawn while readiness still shows `0`.
+    #[test]
+    fn process_env_preserves_explicit_reply_guard_opt_out() {
+        let effective_env =
+            BTreeMap::from([("BUZZ_AGENT_REQUIRE_REPLY".to_string(), "0".to_string())]);
+
+        let env = relay_mesh_process_env(&effective_env, "Gemma-4");
+
+        assert_eq!(
+            env.get("BUZZ_AGENT_REQUIRE_REPLY").map(String::as_str),
+            Some("0")
+        );
+    }
+
+    #[test]
+    fn process_env_enables_reply_guard_when_user_is_silent() {
+        let env = relay_mesh_process_env(&BTreeMap::new(), "Gemma-4");
+
+        assert_eq!(
+            env.get("BUZZ_AGENT_REQUIRE_REPLY").map(String::as_str),
             Some("1")
         );
     }
+
+    #[test]
+    fn process_env_seeds_controls_without_restoring_unrelated_credentials() {
+        let effective_env = BTreeMap::from([
+            (
+                "BUZZ_AGENT_MAX_OUTPUT_TOKENS".to_string(),
+                "1024".to_string(),
+            ),
+            ("OPENAI_API_KEY".to_string(), "must-not-leak".to_string()),
+        ]);
+
+        let env = relay_mesh_process_env(&effective_env, "Gemma-4");
+
+        assert_eq!(
+            env.get("BUZZ_AGENT_MAX_OUTPUT_TOKENS").map(String::as_str),
+            Some("1024")
+        );
+        assert_eq!(
+            env.get("OPENAI_COMPAT_MODEL").map(String::as_str),
+            Some("Gemma-4")
+        );
+        assert!(!env.contains_key("OPENAI_API_KEY"));
+    }
 }
diff --git a/desktop/src-tauri/src/managed_agents/runtime.rs b/desktop/src-tauri/src/managed_agents/runtime.rs
index f3b4cb67fd..37927961ed 100644
--- a/desktop/src-tauri/src/managed_agents/runtime.rs
+++ b/desktop/src-tauri/src/managed_agents/runtime.rs
@@ -869,12 +869,7 @@ pub fn spawn_agent_child(
     // uses the same trim semantics as the preflight callers.
     #[cfg(feature = "mesh-llm")]
     if let Some(ref mesh_model_id) = mesh_model_id {
-        let mut mesh_env = std::collections::BTreeMap::new();
-        super::apply_relay_mesh_env(
-            &mut mesh_env,
-            Some(super::RELAY_MESH_PROVIDER_ID),
-            Some(mesh_model_id.as_str()),
-        );
+        let mesh_env = super::relay_mesh_process_env(&descriptor.env, mesh_model_id);
         command.env_remove("OPENAI_API_KEY");
         for (key, value) in mesh_env {
             command.env(key, value);
diff --git a/desktop/src-tauri/src/managed_agents/snapshot_avatar.rs b/desktop/src-tauri/src/managed_agents/snapshot_avatar.rs
new file mode 100644
index 0000000000..a1044b31f4
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/snapshot_avatar.rs
@@ -0,0 +1,42 @@
+use base64::{engine::general_purpose::STANDARD, Engine as _};
+use image::ImageDecoder;
+use std::io::Cursor;
+
+const MAX_AVATAR_INLINE_BYTES: usize = 2 * 1024 * 1024;
+const MAX_AVATAR_DIMENSION: u32 = 2048;
+const MAX_AVATAR_DECODE_ALLOC: u64 = 32 * 1024 * 1024;
+
+/// Materialize a snapshot PNG's visible pixels as a bounded portable avatar.
+/// The exact transparent 1×1 no-avatar placeholder and images that cannot fit
+/// the persisted inline-avatar budget leave the manifest fallback intact.
+pub(crate) fn snapshot_png_avatar_data_url(png_bytes: &[u8]) -> Result<Option<String>, String> {
+    let reader = image::ImageReader::with_format(Cursor::new(png_bytes), image::ImageFormat::Png);
+    let mut decoder = reader
+        .into_decoder()
+        .map_err(|e| format!("Failed to decode snapshot avatar: {e}"))?;
+    let mut limits = image::Limits::default();
+    limits.max_image_width = Some(MAX_AVATAR_DIMENSION);
+    limits.max_image_height = Some(MAX_AVATAR_DIMENSION);
+    limits.max_alloc = Some(MAX_AVATAR_DECODE_ALLOC);
+    decoder
+        .set_limits(limits)
+        .map_err(|e| format!("Snapshot avatar exceeds safe decoding limits: {e}"))?;
+    let (width, height) = decoder.dimensions();
+    let image = image::DynamicImage::from_decoder(decoder)
+        .map_err(|e| format!("Failed to decode snapshot avatar: {e}"))?;
+    if width == 1 && height == 1 && image.to_rgba8().get_pixel(0, 0).0 == [0, 0, 0, 0] {
+        return Ok(None);
+    }
+
+    let mut clean_png = Vec::new();
+    image
+        .write_to(&mut Cursor::new(&mut clean_png), image::ImageFormat::Png)
+        .map_err(|e| format!("Failed to encode snapshot avatar: {e}"))?;
+    if clean_png.len() > MAX_AVATAR_INLINE_BYTES {
+        return Ok(None);
+    }
+    Ok(Some(format!(
+        "data:image/png;base64,{}",
+        STANDARD.encode(clean_png)
+    )))
+}
diff --git a/desktop/src-tauri/src/managed_agents/storage.rs b/desktop/src-tauri/src/managed_agents/storage.rs
index f6f89ed898..652bb9b9ea 100644
--- a/desktop/src-tauri/src/managed_agents/storage.rs
+++ b/desktop/src-tauri/src/managed_agents/storage.rs
@@ -52,6 +52,34 @@ fn managed_agents_logs_dir(app: &AppHandle) -> Result<PathBuf, String> {
     Ok(dir)
 }
 
+/// Install-log path for `runtime_id`, alongside the agent logs.
+pub fn install_log_path(app: &AppHandle, runtime_id: &str) -> Result<PathBuf, String> {
+    Ok(managed_agents_logs_dir(app)?.join(install_log_filename(runtime_id)?))
+}
+
+/// Filename for a runtime's install log, or an error for an id that must not
+/// become one.
+///
+/// The id is validated rather than trusted: ids reach this from user-defined
+/// custom harnesses as well as the catalog, and a `../` or a separator in one
+/// would place the log outside the logs directory. Rejecting beats sanitizing —
+/// a rejected id means no log, while a rewritten one could collide with another
+/// runtime's.
+fn install_log_filename(runtime_id: &str) -> Result<String, String> {
+    if runtime_id.is_empty() || !runtime_id.chars().all(is_safe_id_char) {
+        return Err(format!(
+            "unsafe runtime id for a log filename: {runtime_id}"
+        ));
+    }
+    Ok(format!("install-{runtime_id}.log"))
+}
+
+/// Characters allowed in a runtime id used as a filename. Excludes `/`, `\`,
+/// `:` and `.`, so no id can traverse or escape the logs directory.
+fn is_safe_id_char(c: char) -> bool {
+    c.is_ascii_alphanumeric() || c == '-' || c == '_'
+}
+
 pub fn managed_agent_log_path(app: &AppHandle, pubkey: &str) -> Result<PathBuf, String> {
     Ok(managed_agents_logs_dir(app)?.join(format!("{pubkey}.log")))
 }
@@ -632,6 +660,62 @@ pub(crate) fn open_log_file(path: &Path) -> Result<File, String> {
         .map_err(|error| format!("failed to open log file {}: {error}", path.display()))
 }
 
+/// Start a new install-log session at `path`: keep the previous run as
+/// `<path>.1` and return a freshly created, empty current file.
+///
+/// Rotating per *run* rather than by size is what bounds this file. A run
+/// writes one record per executed attempt, each capped by the log-scale
+/// capture, so one run's file is bounded by steps × attempts × cap and the
+/// history on disk is bounded at two runs. Size-triggered rotation could not
+/// promise either: it never replaced an existing `.1`, and on Windows —
+/// where rename does not replace its destination — it stopped working
+/// altogether once `.1` existed, leaving the current file to grow.
+///
+/// The old `.1` is therefore *removed* before the rename rather than renamed
+/// over. Every step is best-effort: a rotation that fails must not cost the
+/// user the install, so the session continues with a truncated current file.
+pub(crate) fn start_install_log_session(path: &Path) -> Result<File, String> {
+    if path.exists() {
+        let mut previous = path.as_os_str().to_owned();
+        previous.push(".1");
+        let previous = PathBuf::from(previous);
+        let _ = fs::remove_file(&previous);
+        let _ = fs::rename(path, &previous);
+    }
+    open_install_log(path, /* truncate */ true)
+}
+
+/// Open an install log for appending one more record to the current session.
+pub(crate) fn open_install_log_file(path: &Path) -> Result<File, String> {
+    open_install_log(path, /* truncate */ false)
+}
+
+/// Open an install log owner-only.
+///
+/// The mode is set *in the create* rather than chmod'd afterwards, so the file
+/// is never briefly group/world-readable. Install output can carry registry
+/// tokens and proxy credentials echoed by a failing installer, so the window
+/// matters even though it is short. An existing file's mode is left as-is —
+/// `OpenOptions::mode` only applies on creation, and silently re-tightening a
+/// file the user relaxed is not this function's call to make.
+fn open_install_log(path: &Path, truncate: bool) -> Result<File, String> {
+    let mut options = OpenOptions::new();
+    options.create(true);
+    if truncate {
+        options.write(true).truncate(true);
+    } else {
+        options.append(true);
+    }
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        options.mode(0o600);
+    }
+    options
+        .open(path)
+        .map_err(|error| format!("failed to open log file {}: {error}", path.display()))
+}
+
 pub(crate) fn append_log_marker(path: &Path, message: &str) -> Result<(), String> {
     let mut file = open_log_file(path)?;
     writeln!(file, "{message}").map_err(|error| format!("failed to write log marker: {error}"))
diff --git a/desktop/src-tauri/src/managed_agents/storage_tests.rs b/desktop/src-tauri/src/managed_agents/storage_tests.rs
index 73567bb915..9943c6b3ac 100644
--- a/desktop/src-tauri/src/managed_agents/storage_tests.rs
+++ b/desktop/src-tauri/src/managed_agents/storage_tests.rs
@@ -698,3 +698,135 @@ fn try_delete_agent_key_returns_result() {
     // team_snapshot::tests::rollback_aggregates_multiple_errors.
     let _: fn(&str) -> Result<(), String> = super::try_delete_agent_key;
 }
+
+// ── install logs ─────────────────────────────────────────────────────────────
+
+/// Install output can carry registry tokens and proxy credentials a failing
+/// installer echoed, and the file is written unattended. `0o600` must come from
+/// the create itself: a post-write `chmod` leaves a window where the umask
+/// decides, and a crash inside it leaves the log readable to other local users.
+#[cfg(unix)]
+#[test]
+fn install_log_is_created_owner_only_without_post_write_chmod() {
+    use std::os::unix::fs::PermissionsExt;
+
+    let dir = tempfile::tempdir().expect("temp dir");
+    let path = dir.path().join("install-goose.log");
+
+    let mut file = super::open_install_log_file(&path).expect("open install log");
+    file.write_all(b"npm ERR!\n").expect("write");
+
+    let mode = std::fs::metadata(&path)
+        .expect("metadata")
+        .permissions()
+        .mode()
+        & 0o777;
+    assert_eq!(mode, 0o600, "install logs must be owner-only");
+}
+
+/// A run starts a new current file and keeps the previous run as `.1`, so the
+/// two runs are never mixed and the history on disk stays bounded at two.
+#[test]
+fn install_log_session_keeps_the_previous_run_as_dot_one() {
+    let dir = tempfile::tempdir().expect("temp dir");
+    let path = dir.path().join("install-goose.log");
+
+    let mut first = super::start_install_log_session(&path).expect("first session");
+    first.write_all(b"run-one\n").expect("write");
+    let mut second = super::start_install_log_session(&path).expect("second session");
+    second.write_all(b"run-two\n").expect("write");
+
+    assert_eq!(
+        std::fs::read_to_string(&path).expect("read current"),
+        "run-two\n",
+        "the current file must hold only the newest run"
+    );
+    assert_eq!(
+        std::fs::read_to_string(dir.path().join("install-goose.log.1")).expect("read .1"),
+        "run-one\n",
+        "the previous run must be preserved as .1"
+    );
+}
+
+/// The third run must still rotate when `.1` already exists. Windows `rename`
+/// does not replace its destination, so a rename-only rotation silently stops
+/// working here and leaves the current file to grow across every later run —
+/// the old `.1` is removed first precisely so this cannot happen. Runs on the
+/// Windows target too: this is the path that fails there.
+#[test]
+fn install_log_session_replaces_an_existing_dot_one() {
+    let dir = tempfile::tempdir().expect("temp dir");
+    let path = dir.path().join("install-goose.log");
+    let rotated = dir.path().join("install-goose.log.1");
+    // Seed the state a rename-only rotation cannot get out of: both files exist.
+    std::fs::write(&path, b"previous-run\n").expect("seed current");
+    std::fs::write(&rotated, b"ancient-run\n").expect("seed .1");
+
+    let mut file = super::start_install_log_session(&path).expect("session");
+    file.write_all(b"fresh-run\n").expect("write");
+
+    assert_eq!(
+        std::fs::read_to_string(&path).expect("read current"),
+        "fresh-run\n",
+        "the current file must restart even when .1 was already present"
+    );
+    assert_eq!(
+        std::fs::read_to_string(&rotated).expect("read .1"),
+        "previous-run\n",
+        ".1 must be replaced by the run that just ended, not kept"
+    );
+}
+
+/// Records written after the session starts append to it — a run's later
+/// records must not erase its earlier ones.
+#[test]
+fn install_log_appends_within_a_session() {
+    let dir = tempfile::tempdir().expect("temp dir");
+    let path = dir.path().join("install-goose.log");
+
+    let mut session = super::start_install_log_session(&path).expect("session");
+    session.write_all(b"header\n").expect("write");
+    for record in ["first\n", "second\n"] {
+        let mut file = super::open_install_log_file(&path).expect("open install log");
+        file.write_all(record.as_bytes()).expect("write");
+    }
+
+    assert_eq!(
+        std::fs::read_to_string(&path).expect("read back"),
+        "header\nfirst\nsecond\n"
+    );
+}
+
+/// A runtime id becomes part of a filename. Ids reach this from user-defined
+/// custom harnesses as well as the catalog, so anything that could traverse or
+/// escape the logs directory is rejected rather than sanitized — a rejected id
+/// simply means no log, while a silently rewritten one could collide with
+/// another runtime's log.
+#[test]
+fn install_log_filename_rejects_ids_that_would_escape_the_logs_dir() {
+    for id in [
+        "../../etc/passwd",
+        "goose/../../evil",
+        "sub/dir",
+        "back\\slash",
+        "with.dot",
+        "",
+    ] {
+        assert!(
+            super::install_log_filename(id).is_err(),
+            "id {id:?} must not be accepted as a filename component"
+        );
+    }
+}
+
+/// Ordinary catalog and custom-harness ids are accepted — the guard must not
+/// reject the ids it exists to serve.
+#[test]
+fn install_log_filename_accepts_ordinary_runtime_ids() {
+    for id in ["goose", "claude-code", "buzz_agent", "codex2"] {
+        assert_eq!(
+            super::install_log_filename(id).expect("id must be usable in a log filename"),
+            format!("install-{id}.log")
+        );
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/types.rs b/desktop/src-tauri/src/managed_agents/types.rs
index 3d8e0ed02b..fcd8b13fc9 100644
--- a/desktop/src-tauri/src/managed_agents/types.rs
+++ b/desktop/src-tauri/src/managed_agents/types.rs
@@ -587,7 +587,8 @@ pub struct ManagedAgentLogResponse {
 pub enum AcpAvailabilityStatus {
     Available,
     AdapterMissing,
-    /// Adapter binary is present but is from the deprecated package (< 1.0). Reinstall required.
+    /// Adapter binary is present but unsupported — either the deprecated
+    /// package or a version below the supported floor. Reinstall required.
     AdapterOutdated,
     CliMissing,
     NotInstalled,
@@ -701,6 +702,10 @@ pub struct InstallRuntimeResult {
     /// Number of agents whose stop succeeded but respawn failed.
     /// Mirrors `GlobalAgentConfigSaveResult.failed_restart_count`.
     pub failed_restart_count: u32,
+    /// Install log file for this run, when one was written. The UI surfaces it
+    /// on failure so a user can read the full retry history instead of only the
+    /// last step's truncated output. `None` when no log could be opened.
+    pub log_path: Option<String>,
 }
 
 #[derive(Debug, Clone, Serialize)]
diff --git a/desktop/src-tauri/src/mesh_llm/catalog.rs b/desktop/src-tauri/src/mesh_llm/catalog.rs
index 385971cb86..1a11fcfcd1 100644
--- a/desktop/src-tauri/src/mesh_llm/catalog.rs
+++ b/desktop/src-tauri/src/mesh_llm/catalog.rs
@@ -19,12 +19,14 @@ use mesh_llm_system::vram::{format_rated_capacity, rated_capacity_gb};
 /// The large pick is resolved through mesh-llm's remote catalog
 /// (huggingface.co/datasets/meshllm/catalog), so it does not need to exist in
 /// the compiled `MODEL_CATALOG`; the entry is synthesized below.
-const CURATED_LARGE: &str = "gemma-4-26B-A4B-it-UD-Q4_K_M";
+const CURATED_LARGE: &str = "unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q4_K_M";
+const CURATED_LARGE_ALIAS: &str = "gemma-4-26B-A4B-it-UD-Q4_K_M";
 const CURATED_LARGE_SIZE: &str = "17GB";
 const CURATED_LARGE_FILE: &str = "gemma-4-26B-A4B-it-UD-Q4_K_M.gguf";
 const CURATED_LARGE_DESCRIPTION: &str =
     "Gemma 4 26B MoE (4B active) — Buzz default for 64GB+ machines";
-const CURATED_SMALL: &str = "Gemma-4-E4B-it-Q4_K_M";
+const CURATED_SMALL: &str = "unsloth/gemma-4-E4B-it-GGUF:Q4_K_M";
+const CURATED_SMALL_ALIAS: &str = "Gemma-4-E4B-it-Q4_K_M";
 /// Rated-capacity boundary between the two curated tiers, in GB (marketing
 /// capacity — a "64GB" Mac rates as 64 even though usable AI memory is less).
 const CURATED_LARGE_MIN_RATED_GB: u64 = 64;
@@ -37,6 +39,16 @@ fn buzz_recommended_model(rated_gb: Option<u64>) -> &'static str {
     }
 }
 
+/// Convert Buzz's pre-0.74 curated package aliases into the canonical model
+/// ids advertised and accepted by Mesh's OpenAI ingress.
+pub(crate) fn canonical_curated_model_id(model_id: &str) -> &str {
+    match model_id.trim() {
+        CURATED_SMALL_ALIAS => CURATED_SMALL,
+        CURATED_LARGE_ALIAS => CURATED_LARGE,
+        other => other,
+    }
+}
+
 /// How a model sits inside this machine's usable AI memory.
 /// Mirrors mesh-llm's private `fit_code_for_size_label` thresholds.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
@@ -146,12 +158,13 @@ fn build_catalog(
         .filter(|m| !is_draft_only(&m.name))
         .map(|m| {
             let size_gb = parse_size_gb(&m.size);
+            let name = canonical_curated_model_id(&m.name).to_string();
             MeshCatalogEntry {
                 fit: fit_code(size_gb, vram_gb),
-                installed: is_installed(&m.file, &m.name),
+                installed: is_installed(&m.file, &name) || is_installed(&m.file, &m.name),
                 recommended: false,
                 curated: false,
-                name: m.name.clone(),
+                name,
                 size: m.size.clone(),
                 size_gb,
                 description: m.description.clone(),
@@ -166,7 +179,8 @@ fn build_catalog(
         let size_gb = parse_size_gb(CURATED_LARGE_SIZE);
         entries.push(MeshCatalogEntry {
             fit: fit_code(size_gb, vram_gb),
-            installed: is_installed(CURATED_LARGE_FILE, CURATED_LARGE),
+            installed: is_installed(CURATED_LARGE_FILE, CURATED_LARGE)
+                || is_installed(CURATED_LARGE_FILE, CURATED_LARGE_ALIAS),
             recommended: false,
             curated: false,
             name: CURATED_LARGE.to_string(),
@@ -256,6 +270,8 @@ mod tests {
 
     #[test]
     fn recommendation_follows_buzz_curated_tiers() {
+        assert_eq!(CURATED_SMALL, "unsloth/gemma-4-E4B-it-GGUF:Q4_K_M");
+        assert_eq!(CURATED_LARGE, "unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q4_K_M");
         // 64GB+ rated machines get the large curated pick.
         let large = build_catalog(None, 64_000_000_000, 64.0, &[]);
         assert_eq!(large.recommended.as_deref(), Some(CURATED_LARGE));
@@ -269,6 +285,22 @@ mod tests {
         assert_eq!(tiny.recommended.as_deref(), Some(CURATED_SMALL));
     }
 
+    #[test]
+    fn curated_package_aliases_migrate_to_openai_model_ids() {
+        assert_eq!(
+            canonical_curated_model_id(CURATED_SMALL_ALIAS),
+            CURATED_SMALL
+        );
+        assert_eq!(
+            canonical_curated_model_id(CURATED_LARGE_ALIAS),
+            CURATED_LARGE
+        );
+        assert_eq!(
+            canonical_curated_model_id("other/model:Q4"),
+            "other/model:Q4"
+        );
+    }
+
     #[test]
     fn curated_picks_lead_the_catalog() {
         let catalog = build_catalog(None, 96_000_000_000, 96.0, &[]);
diff --git a/desktop/src-tauri/src/mesh_llm/coordinator.rs b/desktop/src-tauri/src/mesh_llm/coordinator.rs
index 1e279353b6..066fa46373 100644
--- a/desktop/src-tauri/src/mesh_llm/coordinator.rs
+++ b/desktop/src-tauri/src/mesh_llm/coordinator.rs
@@ -132,7 +132,7 @@ pub async fn start_coordinator(app: AppHandle) {
 /// MeshLLM establishes the encrypted peer transport itself.
 async fn reconcile_buzz_mesh_join(app: &AppHandle) -> Result<(), String> {
     let state = app.state::<AppState>();
-    let peer_ids = {
+    let (peer_ids, relay_url) = {
         let runtime = state.mesh_llm_runtime.lock().await;
         let Some(runtime) = runtime.as_ref() else {
             return Ok(());
@@ -141,10 +141,16 @@ async fn reconcile_buzz_mesh_join(app: &AppHandle) -> Result<(), String> {
             .status_report_payload()
             .await
             .map_err(|error| error.to_string())?;
-        visible_peer_ids(&payload)
+        let relay_url = runtime
+            .start_request()
+            .relay_url
+            .clone()
+            .unwrap_or_else(|| crate::relay::relay_ws_url_with_override(&state));
+        (visible_peer_ids(&payload), relay_url)
     };
 
-    let targets = crate::commands::mesh_llm::resolve_buzz_mesh_join_targets(&state).await?;
+    let targets =
+        crate::commands::mesh_llm::resolve_buzz_mesh_join_targets_at(&state, &relay_url).await?;
     let Some(target) = targets
         .into_iter()
         .find(|target| !target_is_visible(target, &peer_ids))
@@ -201,8 +207,13 @@ fn target_is_visible(target: &crate::mesh_llm::MeshServeTarget, peer_ids: &[Stri
 enum RosterReconcileAction {
     /// Keep the running allowlist untouched (no-op, or a failure we ride out).
     Keep,
-    /// Restart the node with a freshly resolved roster.
-    Restart(Vec<String>),
+    /// Restart Buzz so MeshLLM is rebuilt with a freshly resolved roster.
+    ///
+    /// MeshLLM's native listeners are process-owned in practice: stopping and
+    /// starting the embedded runtime in one process can terminate Buzz or race
+    /// ports 9337/3131. The process boundary is therefore part of the safety
+    /// contract, not an implementation detail.
+    RestartProcess,
     /// Observed a *shrink* (or empty) once. Hold the current allowlist and
     /// require the same reduced roster on the next poll before tearing down,
     /// so a single transient short-read never drops a member mid-inference.
@@ -224,9 +235,9 @@ fn roster_shrinks(current: &[String], fresh: &[String]) -> bool {
 /// Rules:
 /// - query failed (`Err`)              → `Keep` (never de-admit on a relay blip)
 /// - resolved roster == current        → `Keep` (no-op)
-/// - grows (only additions)            → `Restart` immediately (fast admission)
+/// - grows (only additions)            → `RestartProcess` immediately (fast admission)
 /// - shrinks/empties, first observation → `AwaitConfirm` (hold, re-check next poll)
-/// - shrinks/empties, confirmed         → `Restart` (same reduced roster twice)
+/// - shrinks/empties, confirmed         → `RestartProcess` (same reduced roster twice)
 fn roster_reconcile_action(
     current_owners: &[String],
     pending_shrink: Option<&[String]>,
@@ -248,13 +259,13 @@ fn roster_reconcile_action(
 
     // Growth (pure additions) is safe to apply immediately.
     if !roster_shrinks(current_owners, &fresh) {
-        return RosterReconcileAction::Restart(fresh);
+        return RosterReconcileAction::RestartProcess;
     }
 
     // A shrink (including down to empty) must be confirmed across two
     // consecutive polls with the *same* reduced roster before we tear down.
     match pending_shrink {
-        Some(pending) if pending == fresh => RosterReconcileAction::Restart(fresh),
+        Some(pending) if pending == fresh => RosterReconcileAction::RestartProcess,
         _ => RosterReconcileAction::AwaitConfirm(fresh),
     }
 }
@@ -283,8 +294,13 @@ async fn reconcile_roster(
     // other member on a transient relay blip (the flapping restart loop). Keep
     // the current allowlist and try again on the next poll. A shrink is held
     // for one extra poll (hysteresis) so a single short-read never tears down.
-    let query = crate::commands::mesh_llm::resolve_trusted_owner_ids(&state).await;
-    let fresh = match roster_reconcile_action(current_owners, pending_shrink.as_deref(), query) {
+    let relay_url = current_request
+        .relay_url
+        .as_deref()
+        .map(str::to_owned)
+        .unwrap_or_else(|| crate::relay::relay_ws_url_with_override(&state));
+    let query = crate::commands::mesh_llm::resolve_trusted_owner_ids_at(&state, &relay_url).await;
+    match roster_reconcile_action(current_owners, pending_shrink.as_deref(), query) {
         RosterReconcileAction::Keep => {
             *pending_shrink = None;
             return Ok(());
@@ -294,34 +310,12 @@ async fn reconcile_roster(
             *pending_shrink = Some(reduced);
             return Ok(());
         }
-        RosterReconcileAction::Restart(fresh) => {
+        RosterReconcileAction::RestartProcess => {
             *pending_shrink = None;
-            fresh
         }
-    };
+    }
 
-    let mut request = current_request.clone();
-    request.trusted_owner_ids = Some(fresh);
-    // Bootstrap endpoints are live device state, not configuration. The
-    // endpoint used at the previous start may belong to the member that just
-    // left or to a device whose iroh identity rotated while offline. Resolve a
-    // fresh validated peer for this restart; starting isolated is safe because
-    // the join watcher will converge it when a member next publishes.
-    request.join_token = match crate::commands::mesh_llm::resolve_buzz_mesh_join_targets(&state)
-        .await
-    {
-        Ok(targets) => targets
-            .into_iter()
-            .next()
-            .map(|target| target.endpoint_addr),
-        Err(error) => {
-            eprintln!(
-                "buzz-mesh: could not refresh bootstrap endpoint for roster restart; starting isolated: {error}"
-            );
-            None
-        }
-    };
-    let mut guard = state.mesh_llm_runtime.lock().await;
+    let guard = state.mesh_llm_runtime.lock().await;
     let startup_pending = match guard.as_ref() {
         Some(runtime) => runtime.is_starting().await,
         None => false,
@@ -342,24 +336,14 @@ async fn reconcile_roster(
         // snapshot.
         return Ok(());
     }
-    let Some(running) = guard.take() else {
+    if guard.is_none() {
         return Ok(());
-    };
-    eprintln!("buzz-mesh: membership roster changed; restarting mesh node with fresh allowlist");
-    if let Err(error) = running.stop().await {
-        drop(guard);
-        eprintln!(
-            "buzz-mesh: stopping mesh node for roster restart failed; restarting Buzz instead of racing the occupied ingress: {error}"
-        );
-        app.request_restart();
-        return Err(format!(
-            "mesh node shutdown failed during roster change: {error}"
-        ));
     }
-    let replacement = crate::mesh_llm::DesktopMeshRuntime::start(request)
-        .await
-        .map_err(|error| format!("mesh node restart after roster change failed: {error:#}"))?;
-    *guard = Some(replacement);
+    drop(guard);
+    eprintln!(
+        "buzz-mesh: membership roster changed; restarting Buzz to rebuild MeshLLM with the fresh community allowlist"
+    );
+    app.request_restart();
     Ok(())
 }
 
@@ -377,11 +361,15 @@ pub(crate) async fn publish_current_status_once(app: &AppHandle, reason: &str) {
     }
 }
 
-pub(crate) async fn publish_stopped_status_once(app: &AppHandle, reason: &str) {
+pub(crate) async fn publish_stopped_status_once_at(
+    app: &AppHandle,
+    relay_url: Option<&str>,
+    reason: &str,
+) {
     let state = app.state::<AppState>();
     match tokio::time::timeout(
         STATUS_PUBLISH_TIMEOUT,
-        publish_stopped_status_for_state(&state),
+        publish_stopped_status_for_state(&state, relay_url),
     )
     .await
     {
@@ -396,26 +384,43 @@ pub(crate) async fn publish_stopped_status_once(app: &AppHandle, reason: &str) {
 async fn publish_current_status_for_state(state: &AppState) -> Result<(), String> {
     let identity = super::ensure_owner_identity()
         .map_err(|error| format!("failed to load mesh owner identity: {error}"))?;
-    let mut payload = {
+    let (mut payload, relay_url) = {
         let runtime = state.mesh_llm_runtime.lock().await;
         match runtime.as_ref() {
-            Some(runtime) => runtime
-                .status_report_payload()
-                .await
-                .map_err(|error| error.to_string())?,
-            None => stopped_status_payload(&identity),
+            Some(runtime) => {
+                let payload = runtime
+                    .status_report_payload()
+                    .await
+                    .map_err(|error| error.to_string())?;
+                let relay_url = runtime
+                    .start_request()
+                    .relay_url
+                    .clone()
+                    .unwrap_or_else(|| crate::relay::relay_ws_url_with_override(state));
+                (payload, relay_url)
+            }
+            None => (
+                stopped_status_payload(&identity),
+                crate::relay::relay_ws_url_with_override(state),
+            ),
         }
     };
     bind_payload_to_member(state, &identity, &mut payload)?;
-    publish_status_report(state, payload).await
+    publish_status_report_at(state, &relay_url, payload).await
 }
 
-async fn publish_stopped_status_for_state(state: &AppState) -> Result<(), String> {
+async fn publish_stopped_status_for_state(
+    state: &AppState,
+    relay_url: Option<&str>,
+) -> Result<(), String> {
     let identity = super::ensure_owner_identity()
         .map_err(|error| format!("failed to load mesh owner identity: {error}"))?;
     let mut payload = stopped_status_payload(&identity);
     bind_payload_to_member(state, &identity, &mut payload)?;
-    publish_status_report(state, payload).await
+    let relay_url = relay_url
+        .map(str::to_owned)
+        .unwrap_or_else(|| crate::relay::relay_ws_url_with_override(state));
+    publish_status_report_at(state, &relay_url, payload).await
 }
 
 fn stopped_status_payload(identity: &super::identity::OwnerIdentity) -> serde_json::Value {
@@ -469,13 +474,21 @@ pub(crate) fn build_status_report_event(
     .tags([d, k]))
 }
 
-pub(crate) async fn publish_status_report(
+async fn publish_status_report_at(
     state: &AppState,
+    relay_url: &str,
     payload: serde_json::Value,
 ) -> Result<(), String> {
-    crate::relay::submit_event(build_status_report_event(payload)?, state)
-        .await
-        .map(|_| ())
+    let api_base_url = crate::relay::relay_http_base_url(relay_url);
+    let keys = state.signing_keys()?;
+    crate::relay::submit_event_at_with_keys(
+        build_status_report_event(payload)?,
+        state,
+        &api_base_url,
+        &keys,
+    )
+    .await
+    .map(|_| ())
 }
 
 #[cfg(test)]
@@ -554,11 +567,11 @@ mod tests {
 
     // Growth (pure additions) applies immediately — fast admission is fine.
     #[test]
-    fn roster_growth_restarts_immediately() {
+    fn roster_growth_requests_process_restart_immediately() {
         let current = vec!["owner-a".to_string()];
         let fresh = vec!["owner-a".to_string(), "owner-c".to_string()];
-        let action = roster_reconcile_action(&current, None, Ok(fresh.clone()));
-        assert_eq!(action, RosterReconcileAction::Restart(fresh));
+        let action = roster_reconcile_action(&current, None, Ok(fresh));
+        assert_eq!(action, RosterReconcileAction::RestartProcess);
     }
 
     // A shrink is NOT applied on first observation — it must be confirmed.
@@ -572,11 +585,11 @@ mod tests {
 
     // The same reduced roster on two consecutive polls confirms the shrink.
     #[test]
-    fn roster_shrink_restarts_once_confirmed() {
+    fn roster_shrink_requests_process_restart_once_confirmed() {
         let current = vec!["owner-a".to_string(), "owner-b".to_string()];
         let reduced = vec!["owner-a".to_string()];
         let action = roster_reconcile_action(&current, Some(&reduced), Ok(reduced.clone()));
-        assert_eq!(action, RosterReconcileAction::Restart(reduced));
+        assert_eq!(action, RosterReconcileAction::RestartProcess);
     }
 
     // A shrink that changes between polls is not confirmed — it re-holds with
@@ -600,7 +613,7 @@ mod tests {
         assert_eq!(first, RosterReconcileAction::AwaitConfirm(Vec::new()));
         let empty: Vec<String> = Vec::new();
         let confirmed = roster_reconcile_action(&current, Some(&empty), Ok(Vec::new()));
-        assert_eq!(confirmed, RosterReconcileAction::Restart(Vec::new()));
+        assert_eq!(confirmed, RosterReconcileAction::RestartProcess);
     }
 
     // A shrink followed by recovery to the full roster cancels the teardown.
diff --git a/desktop/src-tauri/src/mesh_llm/mod.rs b/desktop/src-tauri/src/mesh_llm/mod.rs
index 6e3ab4b28b..e206c53886 100644
--- a/desktop/src-tauri/src/mesh_llm/mod.rs
+++ b/desktop/src-tauri/src/mesh_llm/mod.rs
@@ -1,7 +1,7 @@
 use std::collections::BTreeMap;
 
 mod coordinator;
-pub(crate) use coordinator::{publish_current_status_once, publish_stopped_status_once};
+pub(crate) use coordinator::{publish_current_status_once, publish_stopped_status_once_at};
 pub use coordinator::{start_coordinator, MeshCoordinator, KIND_BUZZ_MESH_MEMBER_STATUS};
 
 mod discovery;
@@ -14,6 +14,7 @@ pub(crate) use discovery::{
 use discovery::{device_name_from_status, endpoint_id_from_status, enrich_status_payload_identity};
 
 mod catalog;
+pub(crate) use catalog::canonical_curated_model_id;
 pub use catalog::{model_catalog, MeshModelCatalog};
 
 mod identity;
@@ -200,6 +201,11 @@ pub struct StartMeshNodeRequest {
     /// accepted from the frontend and contains no relay address.
     #[serde(default, skip_deserializing)]
     pub mesh_name: Option<String>,
+    /// Relay this runtime's community membership and discovery are bound to.
+    /// Injected by the backend when sharing starts and retained across UI
+    /// workspace switches; moving a share requires an explicit stop/start.
+    #[serde(default, skip_deserializing)]
+    pub relay_url: Option<String>,
     /// Mesh owner ids admitted to this node (the member roster from
     /// member-signed discovery notes). `None` = caller did not resolve a roster
     /// (tests, direct invocations): the node runs without allowlist
@@ -308,17 +314,20 @@ pub const MESH_WORKER_STACK_SIZE: usize = 8 * 1024 * 1024;
 /// before the node starts. Without this the download happens *inside*
 /// `serve::start()` where the UI can only show a frozen "starting…" state.
 /// Already-installed models return immediately from the cache scan.
-async fn ensure_model_downloaded(model: &str) -> anyhow::Result<()> {
-    let model_owned = model.to_string();
-    let installed = tokio::task::spawn_blocking(move || {
+async fn model_is_installed(model: &str) -> bool {
+    let model_owned = model.replace("@main", "");
+    tokio::task::spawn_blocking(move || {
         let cache = mesh_llm_node::models::default_huggingface_cache_dir();
         mesh_llm_node::models::scan_installed_models(cache)
             .iter()
-            .any(|m| m.model_ref.contains(&model_owned))
+            .any(|m| m.model_ref.replace("@main", "").contains(&model_owned))
     })
     .await
-    .unwrap_or(false);
-    if installed {
+    .unwrap_or(false)
+}
+
+async fn ensure_model_downloaded(model: &str) -> anyhow::Result<()> {
+    if model_is_installed(model).await {
         return Ok(());
     }
     mesh_llm_host_runtime::models::download_model_ref_with_progress_details(model, true)
diff --git a/desktop/src-tauri/src/mesh_llm/mod_tests.rs b/desktop/src-tauri/src/mesh_llm/mod_tests.rs
index 0b726c264f..557cd040fa 100644
--- a/desktop/src-tauri/src/mesh_llm/mod_tests.rs
+++ b/desktop/src-tauri/src/mesh_llm/mod_tests.rs
@@ -12,6 +12,7 @@ fn pending_client_runtime(
         max_vram_gb: None,
         join_token: Some("initial-token".to_string()),
         mesh_name: None,
+        relay_url: None,
         trusted_owner_ids: None,
     };
     super::DesktopMeshRuntime {
diff --git a/desktop/src-tauri/src/mesh_llm/recovery.rs b/desktop/src-tauri/src/mesh_llm/recovery.rs
index 809fab8993..7933fd291e 100644
--- a/desktop/src-tauri/src/mesh_llm/recovery.rs
+++ b/desktop/src-tauri/src/mesh_llm/recovery.rs
@@ -149,34 +149,60 @@ fn should_evict_after_probe(
     probe: MeshIngressProbe,
     consecutive: u32,
 ) -> bool {
-    urgency == MeshRecoveryUrgency::Foreground && probe == MeshIngressProbe::PortClosed
-        || consecutive >= DEAD_PROBE_EVICT_THRESHOLD
+    // Only a CLOSED port is evidence of death. A bound-but-HTTP-unresponsive
+    // port ("Unhealthy") is a BUSY node, not a dead one: mesh serializes all
+    // HTTP on the ingress — including the `/v1/models` liveness probe — behind
+    // in-flight inference, so a large-prompt turn on a big model leaves the
+    // control plane unresponsive for the whole turn (measured ~27s on a
+    // gemma-4-26B node) while TCP-connect keeps answering in ~0ms. Model load
+    // and package-layer download are unresponsive in exactly the same way.
+    // Evicting on any of those turns ordinary backpressure into a destructive
+    // whole-app restart loop, which is the regression this fixes. A genuinely
+    // wedged bound port cannot be distinguished from a busy one without a
+    // lock-free health endpoint on the ingress (tracked upstream in mesh-llm);
+    // until that exists we never evict a bound port and rely solely on the
+    // unambiguous closed-port signal.
+    match probe {
+        MeshIngressProbe::Live | MeshIngressProbe::Unhealthy => false,
+        MeshIngressProbe::PortClosed => {
+            urgency == MeshRecoveryUrgency::Foreground || consecutive >= DEAD_PROBE_EVICT_THRESHOLD
+        }
+    }
+}
+
+fn requires_process_restart(
+    mode: crate::mesh_llm::MeshNodeMode,
+    startup_in_progress: bool,
+) -> bool {
+    startup_in_progress || mode == crate::mesh_llm::MeshNodeMode::Serve
 }
 
-/// Probe and, when justified, remove one stale runtime. A closed port is
-/// decisive for a foreground agent start; watchdog and ambiguous/unhealthy
-/// ports require consecutive failures to avoid restarting on a transient load
-/// spike.
+/// Probe and, when justified, remove one stale runtime. Only a CLOSED port is
+/// treated as death: a foreground agent start evicts immediately, the watchdog
+/// after a short consecutive-failure streak. A bound-but-unresponsive
+/// ("Unhealthy") port is never evicted — it is a busy or still-loading node,
+/// not a dead one (see `should_evict_after_probe`).
 pub(crate) async fn recover_stale_mesh_runtime(
     state: &AppState,
     urgency: MeshRecoveryUrgency,
 ) -> MeshRuntimeRecovery {
-    let (candidate_id, startup_in_progress) = match state.mesh_llm_runtime.lock().await.as_ref() {
-        Some(runtime) => (runtime.id(), runtime.is_starting().await),
-        None => {
-            state.mesh_recovery.reset_probe_streak();
-            // A cancelled SDK startup can outlive its Buzz-side task briefly
-            // because the embedded runtime runs on its own thread. Never start
-            // a replacement merely because the tracked handle is gone: first
-            // prove the old ingress is either still useful or has released the
-            // port. This closes the port-conflict loop in #2304.
-            return match probe_mesh_ingress().await {
-                MeshIngressProbe::Live => MeshRuntimeRecovery::Live,
-                MeshIngressProbe::PortClosed => MeshRuntimeRecovery::Absent,
-                MeshIngressProbe::Unhealthy => MeshRuntimeRecovery::ReleasePending,
-            };
-        }
-    };
+    let (candidate_id, startup_in_progress, candidate_mode) =
+        match state.mesh_llm_runtime.lock().await.as_ref() {
+            Some(runtime) => (runtime.id(), runtime.is_starting().await, runtime.mode()),
+            None => {
+                state.mesh_recovery.reset_probe_streak();
+                // A cancelled SDK startup can outlive its Buzz-side task briefly
+                // because the embedded runtime runs on its own thread. Never start
+                // a replacement merely because the tracked handle is gone: first
+                // prove the old ingress is either still useful or has released the
+                // port. This closes the port-conflict loop in #2304.
+                return match probe_mesh_ingress().await {
+                    MeshIngressProbe::Live => MeshRuntimeRecovery::Live,
+                    MeshIngressProbe::PortClosed => MeshRuntimeRecovery::Absent,
+                    MeshIngressProbe::Unhealthy => MeshRuntimeRecovery::ReleasePending,
+                };
+            }
+        };
     let probe = probe_mesh_ingress().await;
     if probe == MeshIngressProbe::Live {
         state.mesh_recovery.reset_probe_streak();
@@ -196,12 +222,13 @@ pub(crate) async fn recover_stale_mesh_runtime(
         return MeshRuntimeRecovery::Debouncing;
     }
 
-    // The pinned SDK does not yield its control handle until the management
-    // API is ready. Dropping its still-pending start future would detach the
-    // embedded runtime thread without sending a shutdown request, so Buzz must
-    // not evict it and race a replacement onto the same ports. A controlled
-    // app relaunch is the only process-owned cleanup boundary in this state.
-    if startup_in_progress {
+    // Never replace a serving runtime in-process. Its native listeners and
+    // model host are process-owned; stopping it here and then cold-starting a
+    // client silently disables Share Compute and can race ports 9337/3131.
+    // Pending client startups have the same ownership problem because the SDK
+    // has not yielded a shutdown handle yet. In both cases, process restart is
+    // the only boundary that preserves the configured role safely.
+    if requires_process_restart(candidate_mode, startup_in_progress) {
         state.mesh_recovery.reset_probe_streak();
         return MeshRuntimeRecovery::RestartRequired;
     }
@@ -241,6 +268,12 @@ pub(crate) async fn recover_stale_mesh_runtime(
 pub(crate) async fn rearm_relay_mesh_for_running_agents(app: &AppHandle) -> Result<(), String> {
     let state = app.state::<AppState>();
     let _rearm_guard = state.mesh_recovery.rearm_lock.lock().await;
+    let runtime_mode = state
+        .mesh_llm_runtime
+        .lock()
+        .await
+        .as_ref()
+        .map(|runtime| runtime.mode());
     let recovery = recover_stale_mesh_runtime(&state, MeshRecoveryUrgency::Watchdog).await;
     let active_pubkeys = active_managed_agent_pubkeys(&state);
     // Mesh participation is resolved through the same definition-authoritative
@@ -254,6 +287,13 @@ pub(crate) async fn rearm_relay_mesh_for_running_agents(app: &AppHandle) -> Resu
         | MeshRuntimeRecovery::Debouncing
         | MeshRuntimeRecovery::Replaced => return Ok(()),
         MeshRuntimeRecovery::RestartRequired => {
+            if runtime_mode == Some(crate::mesh_llm::MeshNodeMode::Serve) {
+                eprintln!(
+                    "buzz-mesh: serving ingress failed; restarting Buzz to restore Share Compute without changing roles"
+                );
+                app.request_restart();
+                return Ok(());
+            }
             let records = crate::managed_agents::load_managed_agents(app).unwrap_or_default();
             if !records.iter().any(|record| {
                 running_relay_mesh_model_id(record, &active_pubkeys, &personas, &global).is_some()
@@ -410,6 +450,7 @@ mod tests {
             name_pool: Vec::new(),
             is_builtin: false,
             is_active: true,
+            shared: false,
             source_team: None,
             source_team_persona_slug: None,
             catalog_source: None,
@@ -467,6 +508,89 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn watchdog_closed_port_still_evicts_after_consecutive_streak() {
+        // A genuinely dead listener (crashed / released its port) must still be
+        // reclaimed — the closed-port signal is unchanged by this fix.
+        assert!(!should_evict_after_probe(
+            MeshRecoveryUrgency::Watchdog,
+            MeshIngressProbe::PortClosed,
+            1
+        ));
+        assert!(should_evict_after_probe(
+            MeshRecoveryUrgency::Watchdog,
+            MeshIngressProbe::PortClosed,
+            DEAD_PROBE_EVICT_THRESHOLD
+        ));
+    }
+
+    #[test]
+    fn busy_or_loading_bound_port_is_never_evicted() {
+        // The regression this fixes: mesh serializes all ingress HTTP (incl.
+        // the `/v1/models` liveness probe) behind in-flight inference, so a
+        // large-prompt turn, a model load, or a layer download leaves the port
+        // bound-but-unresponsive ("Unhealthy"). No probe streak, and no
+        // urgency, may evict such a node — doing so restarts a node that is
+        // alive and working.
+        for consecutive in [1, 2, 5, 100] {
+            for urgency in [
+                MeshRecoveryUrgency::Watchdog,
+                MeshRecoveryUrgency::Foreground,
+            ] {
+                assert!(
+                    !should_evict_after_probe(urgency, MeshIngressProbe::Unhealthy, consecutive),
+                    "a bound-but-busy port must never evict (urgency={urgency:?}, \
+                     consecutive={consecutive})"
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn long_model_load_never_reaches_the_restart_path() {
+        // Pins the exact false positive this fix removes. A big model stays
+        // bound-but-unresponsive for MINUTES while it loads weights and
+        // downloads package layers, so the watchdog sees an unbroken run of
+        // `Unhealthy` probes. Walk ~5 minutes of watchdog passes at its 15s
+        // base interval and assert the eviction gate stays shut the whole way
+        // — for a serve node, one `true` here is a whole-app restart.
+        let state = MeshRecoveryState::default();
+        let runtime_id = 42;
+        let passes = (5 * 60) / 15;
+
+        for pass in 1..=passes {
+            let consecutive = state.record_dead_probe(runtime_id);
+            // The streak really does climb — the non-eviction below is the
+            // rule refusing to act, not the counter quietly resetting.
+            assert_eq!(
+                consecutive, pass,
+                "probe streak should keep climbing across a long load"
+            );
+            for urgency in [
+                MeshRecoveryUrgency::Watchdog,
+                MeshRecoveryUrgency::Foreground,
+            ] {
+                assert!(
+                    !should_evict_after_probe(urgency, MeshIngressProbe::Unhealthy, consecutive),
+                    "a still-loading node must never be evicted \
+                     (urgency={urgency:?}, minute={}, streak={consecutive})",
+                    pass * 15 / 60
+                );
+            }
+        }
+
+        // Sanity: the streak blew far past the threshold that used to evict,
+        // so the old logic WOULD have restarted this healthy loading node.
+        assert!(
+            passes >= DEAD_PROBE_EVICT_THRESHOLD,
+            "test must exceed the old eviction threshold to be meaningful"
+        );
+
+        // Once the load finishes and the ingress answers, the streak clears.
+        state.reset_probe_streak();
+        assert_eq!(state.record_dead_probe(runtime_id), 1);
+    }
+
     #[test]
     fn probe_streak_is_scoped_to_runtime_identity() {
         let state = MeshRecoveryState::default();
@@ -481,6 +605,22 @@ mod tests {
         assert!(STALE_STOP_TIMEOUT <= Duration::from_secs(15));
     }
 
+    #[test]
+    fn failed_serving_runtime_requires_process_restart_instead_of_client_fallback() {
+        assert!(requires_process_restart(
+            crate::mesh_llm::MeshNodeMode::Serve,
+            false
+        ));
+        assert!(requires_process_restart(
+            crate::mesh_llm::MeshNodeMode::Client,
+            true
+        ));
+        assert!(!requires_process_restart(
+            crate::mesh_llm::MeshNodeMode::Client,
+            false
+        ));
+    }
+
     #[test]
     fn only_running_relay_mesh_agents_trigger_rearm() {
         let personas: Vec<crate::managed_agents::AgentDefinition> = Vec::new();
@@ -531,4 +671,39 @@ mod tests {
         );
         assert!(!"user note: shared compute config".starts_with(MESH_REARM_ERROR_SENTINEL));
     }
+
+    // Black-box proof of the classification the eviction rule stands on. A
+    // mesh node busy in inference (or loading, or downloading) keeps its
+    // ingress TCP port accepting connections in ~0ms while HTTP does not answer
+    // within the probe timeout — measured directly against a gemma-4-26B node:
+    // a concurrent `/v1/models` took ~27s, queued behind one in-flight turn.
+    // This stands up exactly that shape — a listener that accepts then never
+    // replies — and asserts the probe reads `Unhealthy` (busy), the verdict
+    // `should_evict_after_probe` now refuses to evict on. If this regressed to
+    // `PortClosed`, a busy node would again be misread as dead and restarted.
+    #[tokio::test]
+    async fn bound_but_stalled_http_classifies_as_unhealthy_not_closed() {
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+            .await
+            .expect("bind ephemeral port");
+        let port = listener.local_addr().unwrap().port();
+        // Accept and hold connections open without ever writing a response —
+        // the wire-level equivalent of a node serializing HTTP behind a turn.
+        let accept_task = tokio::spawn(async move {
+            let mut held = Vec::new();
+            while let Ok((stream, _)) = listener.accept().await {
+                held.push(stream); // keep the socket open, never respond
+            }
+        });
+
+        let probe = probe_mesh_ingress_at(&format!("http://127.0.0.1:{port}/v1")).await;
+        accept_task.abort();
+
+        assert_eq!(
+            probe,
+            MeshIngressProbe::Unhealthy,
+            "a TCP-bound port that stalls HTTP (a busy/loading node) must read \
+             Unhealthy, never PortClosed — the eviction fix depends on this"
+        );
+    }
 }
diff --git a/desktop/src-tauri/src/models.rs b/desktop/src-tauri/src/models.rs
index 1d9747bc20..3f04d3d7a1 100644
--- a/desktop/src-tauri/src/models.rs
+++ b/desktop/src-tauri/src/models.rs
@@ -6,6 +6,8 @@ use serde::{Deserialize, Deserializer, Serialize};
 pub struct IdentityInfo {
     pub pubkey: String,
     pub display_name: String,
+    /// Durable location of the active identity key.
+    pub storage: String,
     /// True when the app booted with an ephemeral key because the OS keyring
     /// was empty despite a prior successful migration (key was externally
     /// deleted). The frontend routes to the nsec re-import step when true.
diff --git a/desktop/src-tauri/src/mouse_nav.rs b/desktop/src-tauri/src/mouse_nav.rs
new file mode 100644
index 0000000000..cd729f7304
--- /dev/null
+++ b/desktop/src-tauri/src/mouse_nav.rs
@@ -0,0 +1,142 @@
+//! Native macOS handler for back/forward navigation inputs (mouse X1/X2
+//! buttons and horizontal swipe gestures).
+//!
+//! WKWebView never delivers these inputs to the web content layer, so a DOM
+//! listener can't see them (Safari itself handles them natively in the app
+//! layer, not in the page). This module installs an NSEvent local monitor
+//! and emits a `mouse-nav` Tauri event that `useBackForwardControls` acts on
+//! in the frontend. Two event shapes map to navigation:
+//!
+//! - `otherMouseUp` with button 3/4 — mice whose X1/X2 buttons reach the app
+//!   as plain mouse buttons.
+//! - `swipe` with a horizontal delta — AppKit's page-swipe gesture
+//!   (`swipeWithEvent:`): `deltaX > 0` is back, `deltaX < 0` is forward.
+//!   Sent by mouse drivers that synthesize a page-swipe gesture for the
+//!   back/forward buttons instead of button-3/4 events (the hardware this
+//!   was verified on). Stock Apple trackpad and Magic Mouse swipes arrive
+//!   as phased scroll-wheel events instead, which this module does not
+//!   handle — that path (`ScrollWheel` + `trackSwipeEventWithOptions:`,
+//!   which also needs scroll-edge detection) is a follow-up.
+//!
+//! Compiled macOS-only (via `tray_menu`). Non-macOS X1/X2 behavior is left
+//! to the underlying webview.
+
+/// Maps an `otherMouseUp` button number to a navigation direction.
+/// Buttons 3 and 4 are X1 (back) and X2 (forward).
+fn direction_for_button(button: isize) -> Option<&'static str> {
+    match button {
+        3 => Some("back"),
+        4 => Some("forward"),
+        _ => None,
+    }
+}
+
+/// Maps a swipe gesture's horizontal delta to a navigation direction,
+/// following the AppKit `swipeWithEvent:` convention: positive is back,
+/// negative is forward. A swipe arrives as a begin/end pair and only the
+/// end event carries the direction, so `deltaX == 0` maps to `None`.
+fn direction_for_swipe(delta_x: f64) -> Option<&'static str> {
+    if delta_x > 0.0 {
+        Some("back")
+    } else if delta_x < 0.0 {
+        Some("forward")
+    } else {
+        None
+    }
+}
+
+pub fn init<R: tauri::Runtime>(app_handle: &tauri::AppHandle<R>) {
+    use block2::RcBlock;
+    use objc2_app_kit::{NSEvent, NSEventMask, NSEventType};
+    use tauri::Emitter;
+
+    let app = app_handle.clone();
+    let block = RcBlock::new(move |event: std::ptr::NonNull<NSEvent>| -> *mut NSEvent {
+        // SAFETY: the monitor hands us a valid NSEvent for the matched mask.
+        let ev = unsafe { event.as_ref() };
+
+        match ev.r#type() {
+            NSEventType::OtherMouseUp => {
+                if let Some(direction) = direction_for_button(ev.buttonNumber()) {
+                    // Emit to the main window explicitly instead of
+                    // broadcasting (`emit`) so navigation stays scoped if
+                    // multi-window ever lands. "main" is the default label
+                    // for the single configured window (see deep_link.rs).
+                    let _ = app.emit_to("main", "mouse-nav", direction);
+                    // Swallow the release: nothing downstream should also act
+                    // on it. The matching press deliberately passes through:
+                    // WKWebView never delivers X1/X2 to the page, so the
+                    // unmatched down is inert, and swallowing presses risks
+                    // interfering with AppKit behaviors keyed off mouse-down.
+                    return std::ptr::null_mut();
+                }
+            }
+            NSEventType::Swipe => {
+                if let Some(direction) = direction_for_swipe(ev.deltaX()) {
+                    let _ = app.emit_to("main", "mouse-nav", direction);
+                }
+                // Pass swipes through: nothing else navigates on them, and
+                // swallowing mid-gesture events could confuse AppKit's
+                // gesture tracking.
+            }
+            _ => {}
+        }
+
+        event.as_ptr()
+    });
+
+    // SAFETY: the block returns either null or the pointer it was given, both
+    // valid per the monitor contract. The returned monitor token is
+    // deliberately leaked: the monitor must live for the whole app lifetime.
+    let monitor = unsafe {
+        NSEvent::addLocalMonitorForEventsMatchingMask_handler(
+            NSEventMask::OtherMouseUp | NSEventMask::Swipe,
+            &block,
+        )
+    };
+
+    if let Some(monitor) = monitor {
+        std::mem::forget(monitor);
+    } else {
+        eprintln!("buzz-desktop: mouse-nav: failed to install NSEvent monitor");
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn button_3_is_back() {
+        assert_eq!(direction_for_button(3), Some("back"));
+    }
+
+    #[test]
+    fn button_4_is_forward() {
+        assert_eq!(direction_for_button(4), Some("forward"));
+    }
+
+    #[test]
+    fn other_buttons_do_not_navigate() {
+        for button in [0, 1, 2, 5, -1] {
+            assert_eq!(direction_for_button(button), None);
+        }
+    }
+
+    #[test]
+    fn positive_swipe_delta_is_back() {
+        assert_eq!(direction_for_swipe(1.0), Some("back"));
+        assert_eq!(direction_for_swipe(0.5), Some("back"));
+    }
+
+    #[test]
+    fn negative_swipe_delta_is_forward() {
+        assert_eq!(direction_for_swipe(-1.0), Some("forward"));
+        assert_eq!(direction_for_swipe(-0.5), Some("forward"));
+    }
+
+    #[test]
+    fn zero_delta_swipe_begin_event_is_ignored() {
+        assert_eq!(direction_for_swipe(0.0), None);
+    }
+}
diff --git a/desktop/src-tauri/src/native_websocket.rs b/desktop/src-tauri/src/native_websocket.rs
index c0cf2e76f1..128f2df79d 100644
--- a/desktop/src-tauri/src/native_websocket.rs
+++ b/desktop/src-tauri/src/native_websocket.rs
@@ -24,7 +24,7 @@ type Id = u32;
 
 #[derive(Debug, Deserialize)]
 #[serde(tag = "type", content = "data")]
-enum WebSocketMessage {
+pub(crate) enum WebSocketMessage {
     Text(String),
     Binary(Vec<u8>),
     Ping(Vec<u8>),
@@ -33,7 +33,7 @@ enum WebSocketMessage {
 }
 
 #[derive(Debug, Deserialize)]
-struct CloseFramePayload {
+pub(crate) struct CloseFramePayload {
     code: u16,
     reason: String,
 }
@@ -82,7 +82,7 @@ struct ConnectionHandle {
 }
 
 #[derive(Clone)]
-struct WebSocketManager {
+pub(crate) struct WebSocketManager {
     connections: Arc<Mutex<HashMap<Id, Arc<ConnectionHandle>>>>,
     connect_cancel: Arc<Mutex<CancellationToken>>,
 }
@@ -182,11 +182,23 @@ async fn connect(
     open_connection(manager.inner(), &url, on_message).await
 }
 
-async fn send_message(
+pub(crate) async fn send_message(
     manager: &WebSocketManager,
     id: Id,
     message: WebSocketMessage,
 ) -> Result<(), String> {
+    // Egress guard: the NIP-49 local key backup must never reach a relay.
+    // This is the single choke point for all webview-originated websocket
+    // frames (see `crate::egress_guard`).
+    match &message {
+        WebSocketMessage::Text(text) => {
+            crate::egress_guard::assert_no_key_backup(text, "websocket text frame")?
+        }
+        WebSocketMessage::Binary(bytes) => {
+            crate::egress_guard::assert_no_key_backup_bytes(bytes, "websocket binary frame")?
+        }
+        _ => {}
+    }
     let handle = manager
         .connections
         .lock()
diff --git a/desktop/src-tauri/src/relay.rs b/desktop/src-tauri/src/relay.rs
index f896695624..71aa21c413 100644
--- a/desktop/src-tauri/src/relay.rs
+++ b/desktop/src-tauri/src/relay.rs
@@ -450,6 +450,7 @@ pub async fn sync_managed_agent_profile(
     let event = build_profile_event(agent_keys, display_name, avatar_url, auth_tag)?;
     let event_json = event.as_json();
     let body_bytes = event_json.into_bytes();
+    crate::egress_guard::assert_no_key_backup_bytes(&body_bytes, "agent profile sync")?;
 
     let url = format!("{}/events", relay_http_base_url(relay_url));
     let auth = build_nip98_auth_header_for_keys(agent_keys, &Method::POST, &url, &body_bytes)?;
@@ -566,6 +567,7 @@ pub async fn submit_signed_event_with_keys(
     crate::relay_admission::wait_for_rate_limit().await;
     let url = format!("{}/events", relay_api_base_url_with_override(state));
     let body_bytes = event.as_json().into_bytes();
+    crate::egress_guard::assert_no_key_backup_bytes(&body_bytes, "signed event submit (keys)")?;
     let auth_header = build_nip98_auth_header_for_keys(keys, &Method::POST, &url, &body_bytes)?;
 
     let mut request = state
diff --git a/desktop/src-tauri/src/relay/submit.rs b/desktop/src-tauri/src/relay/submit.rs
index 2a42d86c2b..eaad29d3b1 100644
--- a/desktop/src-tauri/src/relay/submit.rs
+++ b/desktop/src-tauri/src/relay/submit.rs
@@ -25,6 +25,7 @@ pub async fn submit_signed_event_at_with_keys(
     crate::relay_admission::wait_for_rate_limit().await;
     let url = format!("{}/events", api_base_url.trim_end_matches('/'));
     let body_bytes = event.as_json().into_bytes();
+    crate::egress_guard::assert_no_key_backup_bytes(&body_bytes, "relay event submit")?;
     let auth_header = build_nip98_auth_header_for_keys(keys, &Method::POST, &url, &body_bytes)?;
 
     let response = state
diff --git a/desktop/src-tauri/src/reset.rs b/desktop/src-tauri/src/reset.rs
index d2e35e6839..18ddd80eb8 100644
--- a/desktop/src-tauri/src/reset.rs
+++ b/desktop/src-tauri/src/reset.rs
@@ -463,6 +463,26 @@ mod tests {
         assert_eq!(kc.delete_calls.get(), 1, "keychain deleted once");
     }
 
+    // ── NIP-49: the boot wipe destroys the app-managed key backup ─────────────
+
+    #[test]
+    fn test_wipe_removes_app_managed_key_backup() {
+        let tmp = TempDir::new().unwrap();
+        let app_data = make_app_data(&tmp);
+        let backup = crate::key_backup::backup_file_path(&app_data);
+        std::fs::write(&backup, b"encrypted-backup-bytes").unwrap();
+
+        write_sentinel(&app_data).unwrap();
+        let kc = FakeKeychain::ok();
+        let outcome = run_boot_reset_with_keychain(make_ctx(&app_data, &kc, false));
+
+        assert!(outcome.completed);
+        assert!(
+            !backup.exists(),
+            "sign-out wipe must destroy the app-managed key backup"
+        );
+    }
+
     // ── Test 3: keychain failure keeps sentinel ────────────────────────────────
 
     #[test]
diff --git a/desktop/src-tauri/src/tray_menu.rs b/desktop/src-tauri/src/tray_menu.rs
new file mode 100644
index 0000000000..6dcef0ecf7
--- /dev/null
+++ b/desktop/src-tauri/src/tray_menu.rs
@@ -0,0 +1,646 @@
+//! Native system-tray menu for the desktop app.
+//!
+//! The webview owns the live agent-turn state. It sends the small display
+//! projection here so the native menu can remain useful while Buzz is hidden.
+
+// Mouse back/forward (X1/X2 buttons and swipe) is also macOS-only native I/O;
+// group it here so both platform-layer init paths share one call site in lib.rs.
+#[path = "mouse_nav.rs"]
+pub(crate) mod mouse_nav;
+
+use std::{
+    sync::{Mutex, OnceLock},
+    time::{Duration, Instant},
+};
+
+#[cfg(target_os = "macos")]
+use objc2::MainThreadMarker;
+#[cfg(target_os = "macos")]
+use objc2_foundation::{NSProcessInfo, NSString};
+use serde::{Deserialize, Serialize};
+use tauri::{
+    image::Image,
+    menu::{Menu, MenuItem, PredefinedMenuItem},
+    tray::{TrayIcon, TrayIconBuilder},
+    AppHandle, Emitter, Manager, Runtime,
+};
+
+const TRAY_ID: &str = "buzz-tray";
+const OPEN_BUZZ_ID: &str = "tray-open-buzz";
+const NEW_CHANNEL_ID: &str = "tray-new-channel";
+const QUIT_ID: &str = "tray-quit";
+const OPEN_CHANNEL_PREFIX: &str = "tray-open-channel:";
+const OPEN_CHANNEL_ACTIVITY_SEPARATOR: char = '|';
+#[cfg(target_os = "macos")]
+const TRAY_MENU_MINIMUM_WIDTH: f64 = 320.0;
+
+static PREVIEW_STARTED_AT: OnceLock<Instant> = OnceLock::new();
+
+/// A local-only menu preview for demonstrating the working-agent section
+/// without connecting to a relay. It is deliberately unavailable in release
+/// builds and must be explicitly enabled when launching the debug app.
+fn preview_activities() -> Option<Vec<TrayAgentActivity>> {
+    if !cfg!(debug_assertions) || std::env::var("BUZZ_TRAY_MENU_DEMO").ok().as_deref() != Some("1")
+    {
+        return None;
+    }
+
+    let preview_elapsed = PREVIEW_STARTED_AT.get_or_init(Instant::now).elapsed();
+
+    Some(vec![
+        TrayAgentActivity {
+            activity_id: "tray-preview-planning-scout".into(),
+            agent_name: "Scout".into(),
+            channel_id: "tray-preview-planning".into(),
+            channel_name: "planning".into(),
+            elapsed: format_elapsed(Duration::from_secs(192) + preview_elapsed),
+        },
+        TrayAgentActivity {
+            activity_id: "tray-preview-planning-builder".into(),
+            agent_name: "Builder".into(),
+            channel_id: "tray-preview-planning".into(),
+            channel_name: "planning".into(),
+            elapsed: format_elapsed(Duration::from_secs(68) + preview_elapsed),
+        },
+        TrayAgentActivity {
+            activity_id: "tray-preview-mobile-reviewer".into(),
+            agent_name: "Reviewer".into(),
+            channel_id: "tray-preview-mobile".into(),
+            channel_name: "mobile".into(),
+            elapsed: format_elapsed(Duration::from_secs(31) + preview_elapsed),
+        },
+    ])
+}
+
+fn preview_recent_activities() -> Option<Vec<TrayAgentActivity>> {
+    if !cfg!(debug_assertions) || std::env::var("BUZZ_TRAY_MENU_DEMO").ok().as_deref() != Some("1")
+    {
+        return None;
+    }
+
+    Some(vec![TrayAgentActivity {
+        activity_id: "recent:tray-preview-design-architect".into(),
+        agent_name: "Architect".into(),
+        channel_id: "tray-preview-design".into(),
+        channel_name: "design".into(),
+        elapsed: "4m 25s".into(),
+    }])
+}
+
+fn format_elapsed(elapsed: Duration) -> String {
+    let total_seconds = elapsed.as_secs();
+    if total_seconds < 60 {
+        return format!("{total_seconds}s");
+    }
+
+    let seconds = total_seconds % 60;
+    let total_minutes = total_seconds / 60;
+    if total_minutes < 60 {
+        return format!("{total_minutes}m {seconds}s");
+    }
+
+    let minutes = total_minutes % 60;
+    let hours = total_minutes / 60;
+    format!("{hours}h {minutes}m {seconds}s")
+}
+
+/// Builds the standalone Buzz bee as a transparent, macOS template image.
+///
+/// The app icon includes a rounded square, which is useful for the Dock but
+/// looks out of place beside the monochrome menu-bar icons. Keeping this
+/// vector-derived mask here also lets macOS tint it correctly in light and
+/// dark menu bars without a separate bitmap asset.
+fn tray_bee_icon() -> Image<'static> {
+    const WIDTH: u32 = 64;
+    const HEIGHT: u32 = 43;
+    const SAMPLES_PER_AXIS: u32 = 4;
+    const BEE_WIDTH: f32 = 466.0;
+    const BEE_HEIGHT: f32 = 309.0;
+
+    fn circle_contains(x: f32, y: f32, center_x: f32, center_y: f32, radius: f32) -> bool {
+        let delta_x = x - center_x;
+        let delta_y = y - center_y;
+        delta_x * delta_x + delta_y * delta_y <= radius * radius
+    }
+
+    fn rounded_rect_contains(
+        x: f32,
+        y: f32,
+        left: f32,
+        top: f32,
+        width: f32,
+        height: f32,
+        radius: f32,
+    ) -> bool {
+        let right = left + width;
+        let bottom = top + height;
+        let closest_x = x.clamp(left + radius, right - radius);
+        let closest_y = y.clamp(top + radius, bottom - radius);
+        let delta_x = x - closest_x;
+        let delta_y = y - closest_y;
+        delta_x * delta_x + delta_y * delta_y <= radius * radius
+    }
+
+    fn bee_contains(x: f32, y: f32) -> bool {
+        let silhouette = circle_contains(x, y, 91.7, 154.5, 91.7)
+            || circle_contains(x, y, 374.3, 154.5, 91.7)
+            || rounded_rect_contains(x, y, 128.0, 0.0, 210.0, 309.0, 34.0);
+        let cutout = circle_contains(x, y, 193.3, 84.4, 27.0)
+            || circle_contains(x, y, 276.0, 84.4, 27.0)
+            || rounded_rect_contains(x, y, 166.3, 157.2, 136.9, 38.3, 5.0)
+            || rounded_rect_contains(x, y, 166.9, 235.1, 136.2, 37.6, 5.0);
+
+        silhouette && !cutout
+    }
+
+    let mut rgba = vec![0; (WIDTH * HEIGHT * 4) as usize];
+    let samples = SAMPLES_PER_AXIS * SAMPLES_PER_AXIS;
+
+    for pixel_y in 0..HEIGHT {
+        for pixel_x in 0..WIDTH {
+            let mut covered_samples = 0;
+            for sample_y in 0..SAMPLES_PER_AXIS {
+                for sample_x in 0..SAMPLES_PER_AXIS {
+                    let x = (pixel_x as f32 + (sample_x as f32 + 0.5) / SAMPLES_PER_AXIS as f32)
+                        / WIDTH as f32
+                        * BEE_WIDTH;
+                    let y = (pixel_y as f32 + (sample_y as f32 + 0.5) / SAMPLES_PER_AXIS as f32)
+                        / HEIGHT as f32
+                        * BEE_HEIGHT;
+                    if bee_contains(x, y) {
+                        covered_samples += 1;
+                    }
+                }
+            }
+
+            let index = ((pixel_y * WIDTH + pixel_x) * 4) as usize;
+            rgba[index + 3] = (covered_samples * u8::MAX as u32 / samples) as u8;
+        }
+    }
+
+    Image::new_owned(rgba, WIDTH, HEIGHT)
+}
+
+/// A running agent and its current channel.
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TrayAgentActivity {
+    activity_id: String,
+    agent_name: String,
+    channel_id: String,
+    channel_name: String,
+    elapsed: String,
+}
+
+struct TrayActivityMenuItem<R: Runtime> {
+    activity_id: String,
+    channel_id: String,
+    agent_item: MenuItem<R>,
+}
+
+struct TrayActionQueue {
+    community_generation: u64,
+    pending_actions: Vec<TrayAction>,
+}
+
+struct TrayMenuState<R: Runtime> {
+    activity_items: Mutex<Vec<TrayActivityMenuItem<R>>>,
+    action_queue: Mutex<TrayActionQueue>,
+}
+
+#[derive(Debug, Deserialize, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase", tag = "kind")]
+pub enum TrayAction {
+    NewChannel,
+    OpenChannel {
+        channel_id: String,
+        community_generation: u64,
+    },
+}
+
+pub(crate) fn show_main_window<R: Runtime>(app: &AppHandle<R>) {
+    let Some(window) = app.get_webview_window("main") else {
+        return;
+    };
+    if let Err(error) = window.unminimize() {
+        eprintln!("buzz-desktop: failed to restore main window from tray: {error}");
+        return;
+    }
+    if let Err(error) = window.show() {
+        eprintln!("buzz-desktop: failed to show main window from tray: {error}");
+        return;
+    }
+    if let Err(error) = window.set_focus() {
+        eprintln!("buzz-desktop: failed to focus main window from tray: {error}");
+    }
+}
+
+fn queue_tray_action<R: Runtime>(app: &AppHandle<R>, mut action: TrayAction) {
+    let state = app.state::<TrayMenuState<R>>();
+    let Ok(mut queue) = state.action_queue.lock() else {
+        eprintln!("buzz-desktop: tray action queue is unavailable");
+        return;
+    };
+    if let TrayAction::OpenChannel {
+        community_generation,
+        ..
+    } = &mut action
+    {
+        *community_generation = queue.community_generation;
+    }
+    queue.pending_actions.push(action);
+    drop(queue);
+
+    if let Err(error) = app.emit("tray-action-available", ()) {
+        eprintln!("buzz-desktop: failed to notify frontend of tray action: {error}");
+    }
+}
+
+fn append_separator<R: Runtime>(app: &AppHandle<R>, menu: &Menu<R>) -> tauri::Result<()> {
+    menu.append(&PredefinedMenuItem::separator(app)?)
+}
+
+fn agent_item_label(activity: &TrayAgentActivity) -> String {
+    let primary = format!("{} · {}", activity.agent_name, activity.elapsed);
+
+    #[cfg(target_os = "macos")]
+    {
+        if supports_menu_item_subtitles() {
+            primary
+        } else {
+            format!("{primary} — #{}", activity.channel_name)
+        }
+    }
+
+    #[cfg(not(target_os = "macos"))]
+    {
+        format!("{primary} — #{}", activity.channel_name)
+    }
+}
+
+#[cfg(target_os = "macos")]
+fn supports_menu_item_subtitles() -> bool {
+    static SUPPORTS_SUBTITLES: OnceLock<bool> = OnceLock::new();
+    *SUPPORTS_SUBTITLES.get_or_init(|| {
+        NSProcessInfo::processInfo()
+            .operatingSystemVersion()
+            .majorVersion
+            >= 14
+    })
+}
+
+fn channel_item_id(activity: &TrayAgentActivity) -> String {
+    format!(
+        "{OPEN_CHANNEL_PREFIX}{}{OPEN_CHANNEL_ACTIVITY_SEPARATOR}{}",
+        activity.channel_id, activity.activity_id
+    )
+}
+
+fn build_menu<R: Runtime>(
+    app: &AppHandle<R>,
+    activities: &[TrayAgentActivity],
+    recent_activities: &[TrayAgentActivity],
+) -> tauri::Result<(Menu<R>, Vec<TrayActivityMenuItem<R>>)> {
+    let menu = Menu::new(app)?;
+    let mut activity_items =
+        Vec::with_capacity(activities.len().saturating_add(recent_activities.len()));
+
+    let running = MenuItem::new(app, "Running", false, None::<&str>)?;
+    menu.append(&running)?;
+
+    if activities.is_empty() {
+        let empty = MenuItem::new(app, "No agents are running", false, None::<&str>)?;
+        menu.append(&empty)?;
+    } else {
+        append_activity_items(app, &menu, activities, &mut activity_items)?;
+    }
+
+    if !recent_activities.is_empty() {
+        append_separator(app, &menu)?;
+        let recent = MenuItem::new(app, "Recent", false, None::<&str>)?;
+        menu.append(&recent)?;
+        append_activity_items(app, &menu, recent_activities, &mut activity_items)?;
+    }
+
+    append_separator(app, &menu)?;
+    menu.append(&MenuItem::with_id(
+        app,
+        NEW_CHANNEL_ID,
+        "New Channel",
+        true,
+        None::<&str>,
+    )?)?;
+    append_separator(app, &menu)?;
+    menu.append(&MenuItem::with_id(
+        app,
+        OPEN_BUZZ_ID,
+        "Open Buzz",
+        true,
+        None::<&str>,
+    )?)?;
+    append_separator(app, &menu)?;
+    menu.append(&MenuItem::with_id(
+        app,
+        QUIT_ID,
+        "Quit Buzz",
+        true,
+        None::<&str>,
+    )?)?;
+
+    Ok((menu, activity_items))
+}
+
+fn append_activity_items<R: Runtime>(
+    app: &AppHandle<R>,
+    menu: &Menu<R>,
+    activities: &[TrayAgentActivity],
+    activity_items: &mut Vec<TrayActivityMenuItem<R>>,
+) -> tauri::Result<()> {
+    for activity in activities {
+        let agent_item = MenuItem::with_id(
+            app,
+            channel_item_id(activity),
+            agent_item_label(activity),
+            true,
+            None::<&str>,
+        )?;
+        menu.append(&agent_item)?;
+        activity_items.push(TrayActivityMenuItem {
+            activity_id: activity.activity_id.clone(),
+            channel_id: activity.channel_id.clone(),
+            agent_item,
+        });
+    }
+
+    Ok(())
+}
+
+#[cfg(target_os = "macos")]
+fn apply_activity_presentation<R: Runtime>(
+    tray: &TrayIcon<R>,
+    activities: &[TrayAgentActivity],
+    recent_activities: &[TrayAgentActivity],
+) -> Result<(), String> {
+    if !supports_menu_item_subtitles() {
+        return Ok(());
+    }
+
+    let subtitles = activities
+        .iter()
+        .chain(recent_activities)
+        .map(|activity| format!("#{}", activity.channel_name))
+        .collect::<Vec<_>>();
+    let running_count = activities.len();
+    let recent_count = recent_activities.len();
+
+    tray.with_inner_tray_icon(move |inner| {
+        let Some(status_item) = inner.ns_status_item() else {
+            return;
+        };
+        let Some(main_thread) = MainThreadMarker::new() else {
+            return;
+        };
+        let Some(menu) = status_item.menu(main_thread) else {
+            return;
+        };
+        menu.setMinimumWidth(TRAY_MENU_MINIMUM_WIDTH);
+
+        let mut item_index = 1;
+        for subtitle in subtitles.iter().take(running_count) {
+            if let Some(item) = menu.itemAtIndex(item_index) {
+                let subtitle = NSString::from_str(subtitle);
+                item.setSubtitle(Some(&subtitle));
+            }
+            item_index += 1;
+        }
+
+        if running_count == 0 {
+            item_index += 1;
+        }
+
+        if recent_count > 0 {
+            // The separator and Recent heading precede the completed rows.
+            item_index += 2;
+            for subtitle in subtitles.iter().skip(running_count) {
+                if let Some(item) = menu.itemAtIndex(item_index) {
+                    let subtitle = NSString::from_str(subtitle);
+                    item.setSubtitle(Some(&subtitle));
+                }
+                item_index += 1;
+            }
+        }
+    })
+    .map_err(|error| error.to_string())
+}
+
+#[cfg(not(target_os = "macos"))]
+fn apply_activity_presentation<R: Runtime>(
+    _tray: &TrayIcon<R>,
+    _activities: &[TrayAgentActivity],
+    _recent_activities: &[TrayAgentActivity],
+) -> Result<(), String> {
+    Ok(())
+}
+
+fn handle_menu_event<R: Runtime>(app: &AppHandle<R>, id: &str) {
+    match id {
+        OPEN_BUZZ_ID => show_main_window(app),
+        NEW_CHANNEL_ID => {
+            show_main_window(app);
+            queue_tray_action(app, TrayAction::NewChannel);
+        }
+        QUIT_ID => app.exit(0),
+        _ => {
+            let Some(channel_id) = id.strip_prefix(OPEN_CHANNEL_PREFIX) else {
+                return;
+            };
+            show_main_window(app);
+            let channel_id = channel_id
+                .split_once(OPEN_CHANNEL_ACTIVITY_SEPARATOR)
+                .map(|(channel_id, _)| channel_id)
+                .unwrap_or(channel_id);
+            queue_tray_action(
+                app,
+                TrayAction::OpenChannel {
+                    channel_id: channel_id.into(),
+                    community_generation: 0,
+                },
+            );
+        }
+    }
+}
+
+/// Installs the persistent Buzz tray icon with the initial empty activity menu.
+pub fn init<R: Runtime>(app: &AppHandle<R>) -> tauri::Result<()> {
+    let preview_activities = preview_activities();
+    let preview_recent_activities = preview_recent_activities();
+    let activities = preview_activities.as_deref().unwrap_or(&[]);
+    let recent_activities = preview_recent_activities.as_deref().unwrap_or(&[]);
+    let (menu, activity_items) = build_menu(app, activities, recent_activities)?;
+    app.manage(TrayMenuState {
+        activity_items: Mutex::new(activity_items),
+        action_queue: Mutex::new(TrayActionQueue {
+            community_generation: 0,
+            pending_actions: Vec::new(),
+        }),
+    });
+    let tray = TrayIconBuilder::with_id(TRAY_ID)
+        .menu(&menu)
+        .icon(tray_bee_icon())
+        .icon_as_template(true)
+        .on_menu_event(|app, event| handle_menu_event(app, event.id.as_ref()))
+        .build(app)?;
+    if let Err(error) = apply_activity_presentation(&tray, activities, recent_activities) {
+        eprintln!("buzz-desktop: failed to apply tray menu presentation: {error}");
+    }
+    mouse_nav::init(app);
+    Ok(())
+}
+
+/// Drains actions selected from the tray while the frontend was unavailable.
+#[tauri::command]
+pub fn take_tray_actions<R: Runtime>(app: AppHandle<R>) -> Result<Vec<TrayAction>, String> {
+    let state = app.state::<TrayMenuState<R>>();
+    let mut queue = state
+        .action_queue
+        .lock()
+        .map_err(|_| "Buzz tray action queue is unavailable".to_string())?;
+    Ok(std::mem::take(&mut queue.pending_actions))
+}
+
+fn requeue_actions(queue: &mut TrayActionQueue, mut actions: Vec<TrayAction>) {
+    actions.retain(|action| match action {
+        TrayAction::NewChannel => true,
+        TrayAction::OpenChannel {
+            community_generation,
+            ..
+        } => *community_generation == queue.community_generation,
+    });
+    actions.append(&mut queue.pending_actions);
+    queue.pending_actions = actions;
+}
+
+/// Restores actions that were drained as the frontend unmounted. Channel
+/// actions from a previous community generation are discarded.
+#[tauri::command]
+pub fn requeue_tray_actions<R: Runtime>(
+    app: AppHandle<R>,
+    actions: Vec<TrayAction>,
+) -> Result<(), String> {
+    let state = app.state::<TrayMenuState<R>>();
+    let mut queue = state
+        .action_queue
+        .lock()
+        .map_err(|_| "Buzz tray action queue is unavailable".to_string())?;
+    requeue_actions(&mut queue, actions);
+    drop(queue);
+    app.emit("tray-action-available", ())
+        .map_err(|error| error.to_string())
+}
+
+/// Clears community-scoped agent activity and queued channel navigation from
+/// the native tray menu.
+#[tauri::command]
+pub fn clear_tray_agent_activity<R: Runtime>(app: AppHandle<R>) -> Result<(), String> {
+    let state = app.state::<TrayMenuState<R>>();
+    let mut queue = state
+        .action_queue
+        .lock()
+        .map_err(|_| "Buzz tray action queue is unavailable".to_string())?;
+    queue.community_generation = queue.community_generation.wrapping_add(1);
+    queue
+        .pending_actions
+        .retain(|action| matches!(action, TrayAction::NewChannel));
+    drop(queue);
+
+    update_tray_agent_activity(app, Vec::new(), Vec::new())
+}
+
+/// Replaces the native menu's activity section with the current live work.
+#[tauri::command]
+pub fn update_tray_agent_activity<R: Runtime>(
+    app: AppHandle<R>,
+    activities: Vec<TrayAgentActivity>,
+    recent_activities: Vec<TrayAgentActivity>,
+) -> Result<(), String> {
+    let preview_activities = preview_activities();
+    let preview_recent_activities = preview_recent_activities();
+    let activities = preview_activities.as_deref().unwrap_or(&activities);
+    let recent_activities = preview_recent_activities
+        .as_deref()
+        .unwrap_or(&recent_activities);
+    let state = app.state::<TrayMenuState<R>>();
+    let mut activity_items = state
+        .activity_items
+        .lock()
+        .map_err(|_| "Buzz tray menu state is unavailable".to_string())?;
+
+    if activity_items.len() == activities.len().saturating_add(recent_activities.len())
+        && activity_items
+            .iter()
+            .zip(activities.iter().chain(recent_activities))
+            .all(|(item, activity)| {
+                item.activity_id == activity.activity_id && item.channel_id == activity.channel_id
+            })
+    {
+        for (item, activity) in activity_items
+            .iter()
+            .zip(activities.iter().chain(recent_activities))
+        {
+            item.agent_item
+                .set_text(agent_item_label(activity))
+                .map_err(|error| error.to_string())?;
+        }
+        let tray = app
+            .tray_by_id(TRAY_ID)
+            .ok_or_else(|| "Buzz tray icon is not available".to_string())?;
+        apply_activity_presentation(&tray, activities, recent_activities)?;
+        return Ok(());
+    }
+
+    let (menu, next_activity_items) =
+        build_menu(&app, activities, recent_activities).map_err(|error| error.to_string())?;
+    let tray = app
+        .tray_by_id(TRAY_ID)
+        .ok_or_else(|| "Buzz tray icon is not available".to_string())?;
+    tray.set_menu(Some(menu))
+        .map_err(|error| error.to_string())?;
+    apply_activity_presentation(&tray, activities, recent_activities)?;
+    *activity_items = next_activity_items;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{requeue_actions, TrayAction, TrayActionQueue};
+
+    #[test]
+    fn stale_channel_actions_are_not_requeued_after_community_change() {
+        let mut queue = TrayActionQueue {
+            community_generation: 2,
+            pending_actions: Vec::new(),
+        };
+
+        requeue_actions(
+            &mut queue,
+            vec![TrayAction::OpenChannel {
+                channel_id: "old-channel".into(),
+                community_generation: 1,
+            }],
+        );
+
+        assert!(queue.pending_actions.is_empty());
+    }
+
+    #[test]
+    fn new_channel_actions_survive_community_change() {
+        let mut queue = TrayActionQueue {
+            community_generation: 2,
+            pending_actions: Vec::new(),
+        };
+
+        requeue_actions(&mut queue, vec![TrayAction::NewChannel]);
+
+        assert_eq!(queue.pending_actions, vec![TrayAction::NewChannel]);
+    }
+}
diff --git a/desktop/src-tauri/tauri.conf.json b/desktop/src-tauri/tauri.conf.json
index 7a480c4c18..93326b9968 100644
--- a/desktop/src-tauri/tauri.conf.json
+++ b/desktop/src-tauri/tauri.conf.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://schema.tauri.app/config/2",
   "productName": "Buzz",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "identifier": "xyz.block.buzz.app",
   "build": {
     "beforeDevCommand": {
@@ -55,6 +55,7 @@
     "externalBin": [
       "binaries/buzz-acp",
       "binaries/buzz-agent",
+      "binaries/buzz-backend-kubernetes",
       "binaries/buzz-dev-mcp",
       "binaries/git-credential-nostr",
       "binaries/buzz"
diff --git a/desktop/src-tauri/tauri.windows.conf.json b/desktop/src-tauri/tauri.windows.conf.json
new file mode 100644
index 0000000000..abf09b5bfd
--- /dev/null
+++ b/desktop/src-tauri/tauri.windows.conf.json
@@ -0,0 +1,11 @@
+{
+  "bundle": {
+    "externalBin": [
+      "binaries/buzz-acp",
+      "binaries/buzz-agent",
+      "binaries/buzz-dev-mcp",
+      "binaries/git-credential-nostr",
+      "binaries/buzz"
+    ]
+  }
+}
diff --git a/desktop/src/app/App.tsx b/desktop/src/app/App.tsx
index 90b5bf5ebc..44618f2c72 100644
--- a/desktop/src/app/App.tsx
+++ b/desktop/src/app/App.tsx
@@ -56,6 +56,7 @@ import { WelcomeSetup } from "@/features/communities/ui/WelcomeSetup";
 import { CommunityApplyErrorScreen } from "@/features/communities/ui/CommunityApplyErrorScreen";
 import { CommunityChangeOverlay } from "@/features/communities/ui/CommunityChangeOverlay";
 import { setAvatarProfileSyncQueryClient } from "@/features/profile/avatarProfileSync";
+import { EncryptedBackupProvider } from "@/features/settings/EncryptedBackupProvider";
 import { createBuzzQueryClient } from "@/shared/api/queryClient";
 import { isSharedIdentity as isSharedIdentityCmd } from "@/shared/api/tauri";
 import { getProfile } from "@/shared/api/tauriProfiles";
@@ -270,9 +271,18 @@ function AppReady({
   }
 
   return (
-    <KnownAgentPubkeysProvider>
-      <RouterProvider router={router} />
-    </KnownAgentPubkeysProvider>
+    <EncryptedBackupProvider
+      onOpenSettings={() =>
+        void router.navigate({
+          to: "/settings",
+          search: { section: "profile" },
+        })
+      }
+    >
+      <KnownAgentPubkeysProvider>
+        <RouterProvider router={router} />
+      </KnownAgentPubkeysProvider>
+    </EncryptedBackupProvider>
   );
 }
 
diff --git a/desktop/src/app/AppHuddleBar.tsx b/desktop/src/app/AppHuddleBar.tsx
new file mode 100644
index 0000000000..9fa12d513f
--- /dev/null
+++ b/desktop/src/app/AppHuddleBar.tsx
@@ -0,0 +1,25 @@
+import type * as React from "react";
+
+import { HuddleBar } from "@/features/huddle";
+
+import { AppProfilePanelProvider } from "@/app/AppProfilePanelProvider";
+
+type AppHuddleBarProps = Pick<
+  React.ComponentProps<typeof HuddleBar>,
+  "onOpenThread" | "onVisibilityChange"
+>;
+
+export function AppHuddleBar({
+  onOpenThread,
+  onVisibilityChange,
+}: AppHuddleBarProps) {
+  return (
+    <AppProfilePanelProvider>
+      <HuddleBar
+        className="h-full"
+        onOpenThread={onOpenThread}
+        onVisibilityChange={onVisibilityChange}
+      />
+    </AppProfilePanelProvider>
+  );
+}
diff --git a/desktop/src/app/AppProfilePanelProvider.tsx b/desktop/src/app/AppProfilePanelProvider.tsx
new file mode 100644
index 0000000000..213acec498
--- /dev/null
+++ b/desktop/src/app/AppProfilePanelProvider.tsx
@@ -0,0 +1,22 @@
+import * as React from "react";
+
+import { useAppNavigation } from "@/app/navigation/useAppNavigation";
+import { ProfilePanelProvider } from "@/shared/context/ProfilePanelContext";
+
+export function AppProfilePanelProvider({
+  children,
+}: Readonly<{ children: React.ReactNode }>) {
+  const { goProfile } = useAppNavigation();
+  const handleOpenProfilePanel = React.useCallback(
+    (pubkey: string) => {
+      void goProfile(pubkey);
+    },
+    [goProfile],
+  );
+
+  return (
+    <ProfilePanelProvider onOpenProfilePanel={handleOpenProfilePanel}>
+      {children}
+    </ProfilePanelProvider>
+  );
+}
diff --git a/desktop/src/app/AppShell.tsx b/desktop/src/app/AppShell.tsx
index 75f57257cc..4eb0a42bbe 100644
--- a/desktop/src/app/AppShell.tsx
+++ b/desktop/src/app/AppShell.tsx
@@ -63,7 +63,8 @@ import {
   type SettingsSection,
   isSettingsSection,
 } from "@/features/settings/ui/SettingsPanels";
-import { HuddleBar, HuddleProvider } from "@/features/huddle";
+import { HuddleProvider } from "@/features/huddle";
+import { AppHuddleBar } from "@/app/AppHuddleBar";
 import { useDueReminderBadgeCount } from "@/features/reminders/hooks";
 import { RemindMeLaterProvider } from "@/features/reminders/ui/RemindMeLaterProvider";
 import { useReminderNotifications } from "@/features/reminders/useReminderNotifications";
@@ -96,7 +97,8 @@ import { useMessageDeepLinks } from "@/shared/useMessageDeepLinks";
 import { SidebarInset, SidebarProvider } from "@/shared/ui/sidebar";
 import { RelayConnectionOverlay } from "@/app/RelayConnectionOverlay";
 import { useSidebarRelayConnectionCard } from "@/features/sidebar/ui/useSidebarRelayConnectionCard";
-
+import { AppShellTrayMenu } from "@/app/useAppShellTrayMenu";
+import { AppProfilePanelProvider } from "@/app/AppProfilePanelProvider";
 const LazySettingsScreen = React.lazy(async () => {
   const module = await import("@/features/settings/ui/SettingsScreen");
   return { default: module.SettingsScreen };
@@ -159,7 +161,6 @@ export function AppShell() {
     ? locationSearchSection
     : DEFAULT_SETTINGS_SECTION;
   const startupReady = useDeferredStartup();
-
   const identityQuery = useIdentityQuery();
   const { mutedChannelIds, muteChannel, unmuteChannel } = useChannelMutes(
     identityQuery.data?.pubkey,
@@ -231,6 +232,7 @@ export function AppShell() {
   const relayConnectionCard = useSidebarRelayConnectionCard(
     channelsErrorMessage,
     communitiesHook.activeCommunity?.relayUrl,
+    `${communitiesHook.activeCommunity?.id ?? "none"}-${communitiesHook.reinitKey}`,
   );
   const memberChannels = React.useMemo(
     () => channels.filter((channel) => channel.isMember),
@@ -301,7 +303,6 @@ export function AppShell() {
       ? (channels.find((channel) => channel.id === targetChannelId) ?? null)
       : null;
   }, [channels, managedChannelId, selectedChannelId]);
-
   const {
     handleChannelNotification,
     handleDmNotification,
@@ -516,7 +517,6 @@ export function AppShell() {
     },
     [applyAgents, applyCanvas, createChannelMutation, goChannel],
   );
-
   const handleCreateForum = React.useCallback(
     async ({
       description,
@@ -584,7 +584,6 @@ export function AppShell() {
     },
     [goHome, hideDmMutation, selectedChannelId],
   );
-
   const handleOpenSettings = React.useCallback(
     (section: SettingsSection = DEFAULT_SETTINGS_SECTION) => {
       setIsChannelManagementOpen(false);
@@ -592,12 +591,10 @@ export function AppShell() {
     },
     [goSettings],
   );
-
   const handleCloseSettings = React.useCallback(
     () => closeSettings(),
     [closeSettings],
   );
-
   // Section switches rewrite the settings entry rather than stacking one
   // history entry per section, so back always exits settings in one step.
   const handleSettingsSectionChange = React.useCallback(
@@ -613,20 +610,13 @@ export function AppShell() {
     },
     [openSearchHit],
   );
-
   useAppShellLifecycleEffects({
     homeBadgeCountExcludingHighPriority,
     unreadChannelIds,
     unreadChannelNotificationCount,
   });
-
   // Dispatch `buzz://message` deep links into the router.
   useMessageDeepLinks();
-
-  const handleOpenNewDm = React.useCallback(
-    () => void goNewMessage(),
-    [goNewMessage],
-  );
   const handleOpenCreateChannel = React.useCallback(
     () => setIsCreateChannelOpen(true),
     [],
@@ -659,7 +649,7 @@ export function AppShell() {
 
       if (key === "k" && event.shiftKey) {
         event.preventDefault();
-        handleOpenNewDm();
+        void goNewMessage();
         return;
       }
 
@@ -688,9 +678,9 @@ export function AppShell() {
     };
   }, [
     handleOpenBrowseChannels,
-    handleOpenNewDm,
     handleOpenCreateChannel,
     handleOpenSearch,
+    goNewMessage,
     goHome,
     settingsOpen,
   ]);
@@ -706,9 +696,13 @@ export function AppShell() {
     markChannelRead,
     selectedView,
   });
-
   return (
     <PreventSleepProvider>
+      <AppShellTrayMenu
+        channels={channels}
+        goChannel={goChannel}
+        openCreateChannel={handleOpenCreateChannel}
+      />
       <ChannelNavigationProvider channels={channels}>
         <AppShellProvider
           value={{
@@ -768,216 +762,224 @@ export function AppShell() {
                     />
                   ) : null}
                   <SidebarProvider className="min-h-0 flex-1 flex-col overflow-hidden">
-                    {!settingsOpen ? (
-                      <AppTopChrome
-                        canGoBack={canGoBack}
-                        canGoForward={canGoForward}
-                        hasCommunityRail={hasCommunityRail}
-                        onGoBack={goBack}
-                        onGoForward={goForward}
-                      />
-                    ) : null}
-                    {settingsOpen ? (
-                      <div className="flex min-h-0 flex-1 overflow-hidden">
-                        <React.Suspense fallback={null}>
-                          <LazySettingsScreen
+                    <AppProfilePanelProvider>
+                      {!settingsOpen ? (
+                        <AppTopChrome
+                          canGoBack={canGoBack}
+                          canGoForward={canGoForward}
+                          hasCommunityRail={hasCommunityRail}
+                          onGoBack={goBack}
+                          onGoForward={goForward}
+                        />
+                      ) : null}
+                      {settingsOpen ? (
+                        <div className="flex min-h-0 flex-1 overflow-hidden">
+                          <React.Suspense fallback={null}>
+                            <LazySettingsScreen
+                              currentPubkey={identityQuery.data?.pubkey}
+                              fallbackDisplayName={
+                                identityQuery.data?.displayName
+                              }
+                              isUpdatingDesktopNotifications={
+                                notificationSettings.isUpdatingDesktopEnabled
+                              }
+                              notificationErrorMessage={
+                                notificationSettings.errorMessage
+                              }
+                              notificationPermission={
+                                notificationSettings.permission
+                              }
+                              notificationSettings={
+                                notificationSettings.settings
+                              }
+                              onClose={handleCloseSettings}
+                              onSectionChange={handleSettingsSectionChange}
+                              onSetDesktopNotificationsEnabled={
+                                notificationSettings.setDesktopEnabled
+                              }
+                              onSetHomeBadgeEnabled={
+                                notificationSettings.setHomeBadgeEnabled
+                              }
+                              onSetSlotAlertsEnabled={
+                                notificationSettings.setSlotAlertsEnabled
+                              }
+                              onSetNotifyWhileViewing={
+                                notificationSettings.setNotifyWhileViewing
+                              }
+                              onSetAllSlotAlertsEnabled={
+                                notificationSettings.setAllSlotAlertsEnabled
+                              }
+                              onSetSoundForSlot={
+                                notificationSettings.setSoundForSlot
+                              }
+                              section={settingsSection}
+                            />
+                          </React.Suspense>
+                        </div>
+                      ) : (
+                        <div className="flex min-h-0 flex-1 overflow-hidden">
+                          <AppSidebar
+                            activeCommunity={communitiesHook.activeCommunity}
+                            channels={sidebarChannels}
                             currentPubkey={identityQuery.data?.pubkey}
+                            errorMessage={channelsErrorMessage}
                             fallbackDisplayName={
                               identityQuery.data?.displayName
                             }
-                            isUpdatingDesktopNotifications={
-                              notificationSettings.isUpdatingDesktopEnabled
-                            }
-                            notificationErrorMessage={
-                              notificationSettings.errorMessage
-                            }
-                            notificationPermission={
-                              notificationSettings.permission
+                            homeBadgeCount={homeBadgeCount + dueReminderBadge}
+                            addCommunityPrefill={addCommunityDialog.prefill}
+                            isAddCommunityOpen={addCommunityDialog.open}
+                            relayConnectionCard={relayConnectionCard}
+                            isCreatingChannel={createChannelMutation.isPending}
+                            isCreatingForum={createForumMutation.isPending}
+                            isLoading={channelsQuery.isLoading}
+                            isCreateChannelOpen={isCreateChannelOpen}
+                            isPresencePending={presenceSession.isPending}
+                            onAddCommunity={(community) => {
+                              const id = communitiesHook.addCommunity({
+                                ...community,
+                                pubkey:
+                                  community.pubkey ??
+                                  identityQuery.data?.pubkey,
+                              });
+                              handleSwitchCommunity(id);
+                            }}
+                            onAddCommunityOpenChange={
+                              addCommunityDialog.onOpenChange
                             }
-                            notificationSettings={notificationSettings.settings}
-                            onClose={handleCloseSettings}
-                            onSectionChange={handleSettingsSectionChange}
-                            onSetDesktopNotificationsEnabled={
-                              notificationSettings.setDesktopEnabled
+                            onNewMessage={goNewMessage}
+                            onBackgroundClick={requestFocusedThreadClose}
+                            onCreateChannelOpenChange={setIsCreateChannelOpen}
+                            onOpenAddCommunity={addCommunityDialog.openDialog}
+                            onSendFeedback={() => setIsSendFeedbackOpen(true)}
+                            onUpdateCommunity={communitiesHook.updateCommunity}
+                            onRemoveCommunity={(id) =>
+                              void handleRemoveCommunity(id)
                             }
-                            onSetHomeBadgeEnabled={
-                              notificationSettings.setHomeBadgeEnabled
+                            onSwitchCommunity={handleSwitchCommunity}
+                            onCreateAgent={() => requestOpenCreateAgent()}
+                            selfPresenceStatus={presenceSession.currentStatus}
+                            communities={communitiesHook.communities}
+                            onCreateChannel={handleCreateChannel}
+                            onCreateForum={handleCreateForum}
+                            onHideDm={handleHideDm}
+                            onMarkAllChannelsRead={markAllChannelsRead}
+                            onMarkChannelRead={markChannelRead}
+                            onMarkChannelUnread={markChannelUnread}
+                            onBrowseChannels={handleOpenBrowseChannels}
+                            onOpenDm={async ({ pubkeys }) => {
+                              const directMessage =
+                                await openDmMutation.mutateAsync({
+                                  pubkeys,
+                                });
+                              await goChannel(directMessage.id);
+                            }}
+                            onSelectAgents={() => void goAgents()}
+                            onSelectChannel={(channelId) =>
+                              void goChannel(channelId)
                             }
-                            onSetSlotAlertsEnabled={
-                              notificationSettings.setSlotAlertsEnabled
+                            onOpenSearchResult={handleOpenSearchResult}
+                            searchChannels={channels}
+                            searchFocusRequest={searchFocusRequest}
+                            onSelectHome={() => void goHome()}
+                            onSelectProjects={() => void goProjects()}
+                            onSelectPulse={() => void goPulse()}
+                            onSelectSettings={handleOpenSettings}
+                            onSelectWorkflows={() => void goWorkflows()}
+                            onSetPresenceStatus={(status) =>
+                              presenceSession.setStatus(status)
                             }
-                            onSetNotifyWhileViewing={
-                              notificationSettings.setNotifyWhileViewing
+                            onSetUserStatus={(text, emoji) =>
+                              setUserStatusMutation.mutate({ text, emoji })
                             }
-                            onSetAllSlotAlertsEnabled={
-                              notificationSettings.setAllSlotAlertsEnabled
+                            onClearUserStatus={() =>
+                              setUserStatusMutation.mutate({
+                                text: "",
+                                emoji: "",
+                              })
                             }
-                            onSetSoundForSlot={
-                              notificationSettings.setSoundForSlot
+                            profile={profileQuery.data}
+                            selfUserStatus={
+                              deferredPubkey
+                                ? (selfStatusQuery.data?.[
+                                    deferredPubkey.toLowerCase()
+                                  ] ?? undefined)
+                                : undefined
                             }
-                            section={settingsSection}
+                            selectedChannelId={selectedChannelId}
+                            selectedView={selectedView}
+                            unreadChannelIds={unreadChannelIds}
+                            unreadChannelCounts={unreadChannelCounts}
+                            mutedChannelIds={mutedChannelIds}
+                            onMuteChannel={muteChannel}
+                            onUnmuteChannel={unmuteChannel}
+                            starredChannelIds={starredChannelIds}
+                            onStarChannel={starChannel}
+                            onUnstarChannel={unstarChannel}
                           />
-                        </React.Suspense>
-                      </div>
-                    ) : (
-                      <div className="flex min-h-0 flex-1 overflow-hidden">
-                        <AppSidebar
-                          activeCommunity={communitiesHook.activeCommunity}
-                          channels={sidebarChannels}
-                          currentPubkey={identityQuery.data?.pubkey}
-                          errorMessage={channelsErrorMessage}
-                          fallbackDisplayName={identityQuery.data?.displayName}
-                          homeBadgeCount={homeBadgeCount + dueReminderBadge}
-                          addCommunityPrefill={addCommunityDialog.prefill}
-                          isAddCommunityOpen={addCommunityDialog.open}
-                          relayConnectionCard={relayConnectionCard}
-                          isCreatingChannel={createChannelMutation.isPending}
-                          isCreatingForum={createForumMutation.isPending}
-                          isLoading={channelsQuery.isLoading}
-                          isCreateChannelOpen={isCreateChannelOpen}
-                          isPresencePending={presenceSession.isPending}
-                          onAddCommunity={(community) => {
-                            const id = communitiesHook.addCommunity({
-                              ...community,
-                              pubkey:
-                                community.pubkey ?? identityQuery.data?.pubkey,
-                            });
-                            handleSwitchCommunity(id);
-                          }}
-                          onAddCommunityOpenChange={
-                            addCommunityDialog.onOpenChange
-                          }
-                          onNewMessage={handleOpenNewDm}
-                          onBackgroundClick={requestFocusedThreadClose}
-                          onCreateChannelOpenChange={setIsCreateChannelOpen}
-                          onOpenAddCommunity={addCommunityDialog.openDialog}
-                          onSendFeedback={() => setIsSendFeedbackOpen(true)}
-                          onUpdateCommunity={communitiesHook.updateCommunity}
-                          onRemoveCommunity={(id) =>
-                            void handleRemoveCommunity(id)
-                          }
-                          onSwitchCommunity={handleSwitchCommunity}
-                          onCreateAgent={() => requestOpenCreateAgent()}
-                          selfPresenceStatus={presenceSession.currentStatus}
-                          communities={communitiesHook.communities}
-                          onCreateChannel={handleCreateChannel}
-                          onCreateForum={handleCreateForum}
-                          onHideDm={handleHideDm}
-                          onMarkAllChannelsRead={markAllChannelsRead}
-                          onMarkChannelRead={markChannelRead}
-                          onMarkChannelUnread={markChannelUnread}
-                          onBrowseChannels={handleOpenBrowseChannels}
-                          onOpenDm={async ({ pubkeys }) => {
-                            const directMessage =
-                              await openDmMutation.mutateAsync({
-                                pubkeys,
-                              });
-                            await goChannel(directMessage.id);
-                          }}
-                          onSelectAgents={() => void goAgents()}
-                          onSelectChannel={(channelId) =>
-                            void goChannel(channelId)
-                          }
-                          onOpenSearchResult={handleOpenSearchResult}
-                          searchChannels={channels}
-                          searchFocusRequest={searchFocusRequest}
-                          onSelectHome={() => void goHome()}
-                          onSelectProjects={() => void goProjects()}
-                          onSelectPulse={() => void goPulse()}
-                          onSelectSettings={handleOpenSettings}
-                          onSelectWorkflows={() => void goWorkflows()}
-                          onSetPresenceStatus={(status) =>
-                            presenceSession.setStatus(status)
-                          }
-                          onSetUserStatus={(text, emoji) =>
-                            setUserStatusMutation.mutate({ text, emoji })
-                          }
-                          onClearUserStatus={() =>
-                            setUserStatusMutation.mutate({
-                              text: "",
-                              emoji: "",
-                            })
-                          }
-                          profile={profileQuery.data}
-                          selfUserStatus={
-                            deferredPubkey
-                              ? (selfStatusQuery.data?.[
-                                  deferredPubkey.toLowerCase()
-                                ] ?? undefined)
-                              : undefined
+                          <MainInsetProvider mainInsetRef={mainInsetRef}>
+                            <SidebarInset
+                              ref={mainInsetRef}
+                              className="isolate min-h-0 min-w-0 overflow-hidden bg-sidebar"
+                              data-buzz-glass-inset
+                              data-buzz-shadow-viewport
+                              style={
+                                chromeCssVarDefaults as React.CSSProperties
+                              }
+                            >
+                              <BuzzTheme.ContentSurface>
+                                <Outlet />
+                              </BuzzTheme.ContentSurface>
+                            </SidebarInset>
+                          </MainInsetProvider>
+                          <RelayConnectionOverlay
+                            card={relayConnectionCard}
+                            errorMessage={channelsErrorMessage}
+                            hasCommunityRail={hasCommunityRail}
+                            isHuddleDrawerOpen={isHuddleDrawerOpen}
+                          />
+                        </div>
+                      )}
+                      <RequestedAgentCreateDialogs />
+                      <AgentManagementDialogs />
+                      <AppShellOverlays
+                        activeChannel={managedChannel}
+                        browseDialogType={browseDialogType}
+                        channels={channels}
+                        currentPubkey={identityQuery.data?.pubkey}
+                        isChannelManagementOpen={isChannelManagementOpen}
+                        isCreatingBrowseChannel={
+                          createChannelMutation.isPending ||
+                          createForumMutation.isPending
+                        }
+                        onBrowseChannelJoin={handleBrowseChannelJoin}
+                        onBrowseChannelCreate={handleBrowseChannelCreate}
+                        onBrowseDialogOpenChange={handleBrowseDialogOpenChange}
+                        onChannelManagementOpenChange={(open) => {
+                          setIsChannelManagementOpen(open);
+                          if (!open) {
+                            setManagedChannelId(null);
                           }
-                          selectedChannelId={selectedChannelId}
-                          selectedView={selectedView}
-                          unreadChannelIds={unreadChannelIds}
-                          unreadChannelCounts={unreadChannelCounts}
-                          mutedChannelIds={mutedChannelIds}
-                          onMuteChannel={muteChannel}
-                          onUnmuteChannel={unmuteChannel}
-                          starredChannelIds={starredChannelIds}
-                          onStarChannel={starChannel}
-                          onUnstarChannel={unstarChannel}
-                        />
-                        <MainInsetProvider mainInsetRef={mainInsetRef}>
-                          <SidebarInset
-                            ref={mainInsetRef}
-                            className="isolate min-h-0 min-w-0 overflow-hidden bg-sidebar"
-                            data-buzz-glass-inset
-                            data-buzz-shadow-viewport
-                            style={chromeCssVarDefaults as React.CSSProperties}
-                          >
-                            <BuzzTheme.ContentSurface>
-                              <Outlet />
-                            </BuzzTheme.ContentSurface>
-                          </SidebarInset>
-                        </MainInsetProvider>
-                        <RelayConnectionOverlay
-                          card={relayConnectionCard}
-                          errorMessage={channelsErrorMessage}
-                          hasCommunityRail={hasCommunityRail}
-                          isHuddleDrawerOpen={isHuddleDrawerOpen}
-                        />
-                      </div>
-                    )}
-                    <RequestedAgentCreateDialogs />
-                    <AgentManagementDialogs />
-                    <AppShellOverlays
-                      activeChannel={managedChannel}
-                      browseDialogType={browseDialogType}
-                      channels={channels}
-                      currentPubkey={identityQuery.data?.pubkey}
-                      isChannelManagementOpen={isChannelManagementOpen}
-                      isCreatingBrowseChannel={
-                        createChannelMutation.isPending ||
-                        createForumMutation.isPending
-                      }
-                      onBrowseChannelJoin={handleBrowseChannelJoin}
-                      onBrowseChannelCreate={handleBrowseChannelCreate}
-                      onBrowseDialogOpenChange={handleBrowseDialogOpenChange}
-                      onChannelManagementOpenChange={(open) => {
-                        setIsChannelManagementOpen(open);
-                        if (!open) {
+                        }}
+                        onDeleteActiveChannel={() => {
+                          setIsChannelManagementOpen(false);
                           setManagedChannelId(null);
-                        }
-                      }}
-                      onDeleteActiveChannel={() => {
-                        setIsChannelManagementOpen(false);
-                        setManagedChannelId(null);
-                        void goHome({ replace: true });
-                      }}
-                      onSelectChannel={(channelId) => {
-                        void goChannel(channelId);
-                      }}
-                    />
-                    <SendFeedbackController
-                      onOpenChange={setIsSendFeedbackOpen}
-                      open={isSendFeedbackOpen}
-                    />
+                          void goHome({ replace: true });
+                        }}
+                        onSelectChannel={(channelId) => {
+                          void goChannel(channelId);
+                        }}
+                      />
+                      <SendFeedbackController
+                        onOpenChange={setIsSendFeedbackOpen}
+                        open={isSendFeedbackOpen}
+                      />
+                    </AppProfilePanelProvider>
                   </SidebarProvider>
                 </div>
 
                 <div className="absolute inset-x-0 bottom-0 z-0 h-(--buzz-huddle-drawer-height)">
-                  <HuddleBar
-                    className="h-full"
+                  <AppHuddleBar
                     onOpenThread={(channelId, messageId) => {
                       void goChannel(channelId, {
                         messageId,
diff --git a/desktop/src/app/navigation/backForwardChords.test.mjs b/desktop/src/app/navigation/backForwardChords.test.mjs
new file mode 100644
index 0000000000..cb60203d04
--- /dev/null
+++ b/desktop/src/app/navigation/backForwardChords.test.mjs
@@ -0,0 +1,139 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { matchBackForwardChord } from "./backForwardChords.ts";
+
+function chord(overrides = {}) {
+  return {
+    altKey: false,
+    code: "",
+    ctrlKey: false,
+    key: "",
+    metaKey: false,
+    shiftKey: false,
+    ...overrides,
+  };
+}
+
+// ── macOS: ⌘[ / ⌘] ───────────────────────────────────────────────────────────
+
+test("mac: ⌘[ matches back", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ key: "[", metaKey: true }), true),
+    "back",
+  );
+});
+
+test("mac: ⌘] matches forward", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ key: "]", metaKey: true }), true),
+    "forward",
+  );
+});
+
+test("mac: matches by code for non-US layouts", () => {
+  assert.equal(
+    matchBackForwardChord(
+      chord({ code: "BracketLeft", key: "Dead", metaKey: true }),
+      true,
+    ),
+    "back",
+  );
+  assert.equal(
+    matchBackForwardChord(
+      chord({ code: "BracketRight", key: "Dead", metaKey: true }),
+      true,
+    ),
+    "forward",
+  );
+});
+
+test("mac: requires meta", () => {
+  assert.equal(matchBackForwardChord(chord({ key: "[" }), true), null);
+});
+
+test("mac: rejects extra modifiers", () => {
+  for (const extra of [
+    { altKey: true },
+    { ctrlKey: true },
+    { shiftKey: true },
+  ]) {
+    assert.equal(
+      matchBackForwardChord(chord({ key: "[", metaKey: true, ...extra }), true),
+      null,
+    );
+  }
+});
+
+test("mac: Alt+arrows do not match (that is the win/linux chord)", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ altKey: true, key: "ArrowLeft" }), true),
+    null,
+  );
+});
+
+test("mac: ⌘←/⌘→ never match — they are line start/end in text editing", () => {
+  // Deliberately unbound: editable targets must keep receiving ⌘←/⌘→ so
+  // line-start/line-end editing still works. Only ⌘[ / ⌘] navigate.
+  assert.equal(
+    matchBackForwardChord(chord({ key: "ArrowLeft", metaKey: true }), true),
+    null,
+  );
+  assert.equal(
+    matchBackForwardChord(chord({ key: "ArrowRight", metaKey: true }), true),
+    null,
+  );
+});
+
+// ── Windows/Linux: Alt+← / Alt+→ ─────────────────────────────────────────────
+
+test("win/linux: Alt+ArrowLeft matches back", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ altKey: true, key: "ArrowLeft" }), false),
+    "back",
+  );
+});
+
+test("win/linux: Alt+ArrowRight matches forward", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ altKey: true, key: "ArrowRight" }), false),
+    "forward",
+  );
+});
+
+test("win/linux: requires alt", () => {
+  assert.equal(matchBackForwardChord(chord({ key: "ArrowLeft" }), false), null);
+});
+
+test("win/linux: rejects extra modifiers", () => {
+  for (const extra of [
+    { ctrlKey: true },
+    { metaKey: true },
+    { shiftKey: true },
+  ]) {
+    assert.equal(
+      matchBackForwardChord(
+        chord({ altKey: true, key: "ArrowLeft", ...extra }),
+        false,
+      ),
+      null,
+    );
+  }
+});
+
+test("win/linux: ⌘[ does not match (that is the mac chord)", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ key: "[", metaKey: true }), false),
+    null,
+  );
+});
+
+// ── Non-chord keys never match ────────────────────────────────────────────────
+
+test("plain bracket / arrow keys without the platform modifier never match", () => {
+  for (const isMac of [true, false]) {
+    for (const key of ["[", "]", "ArrowLeft", "ArrowRight", "a", "Enter"]) {
+      assert.equal(matchBackForwardChord(chord({ key }), isMac), null);
+    }
+  }
+});
diff --git a/desktop/src/app/navigation/backForwardChords.ts b/desktop/src/app/navigation/backForwardChords.ts
new file mode 100644
index 0000000000..ac81f52ea7
--- /dev/null
+++ b/desktop/src/app/navigation/backForwardChords.ts
@@ -0,0 +1,51 @@
+/**
+ * Global back/forward navigation chords.
+ *
+ * macOS: ⌘[ / ⌘] — matching Safari, Chrome, Finder, and Slack.
+ * Windows/Linux: Alt+← / Alt+→ — matching browsers and Slack.
+ *
+ * Kept pure (no DOM access) so chord matching can be unit tested; the
+ * window listener wiring lives in `useBackForwardControls`.
+ */
+
+export type BackForwardDirection = "back" | "forward";
+
+export type BackForwardChordEvent = Pick<
+  KeyboardEvent,
+  "altKey" | "code" | "ctrlKey" | "key" | "metaKey" | "shiftKey"
+>;
+
+export function matchBackForwardChord(
+  event: BackForwardChordEvent,
+  isMac: boolean,
+): BackForwardDirection | null {
+  if (isMac) {
+    if (!event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) {
+      return null;
+    }
+
+    if (event.key === "[" || event.code === "BracketLeft") {
+      return "back";
+    }
+
+    if (event.key === "]" || event.code === "BracketRight") {
+      return "forward";
+    }
+
+    return null;
+  }
+
+  if (!event.altKey || event.metaKey || event.ctrlKey || event.shiftKey) {
+    return null;
+  }
+
+  if (event.key === "ArrowLeft") {
+    return "back";
+  }
+
+  if (event.key === "ArrowRight") {
+    return "forward";
+  }
+
+  return null;
+}
diff --git a/desktop/src/app/navigation/useAppNavigation.ts b/desktop/src/app/navigation/useAppNavigation.ts
index f928970610..d19ac03120 100644
--- a/desktop/src/app/navigation/useAppNavigation.ts
+++ b/desktop/src/app/navigation/useAppNavigation.ts
@@ -79,6 +79,18 @@ export function useAppNavigation() {
     [commitNavigation],
   );
 
+  const goProfile = React.useCallback(
+    (pubkey: string, behavior?: NavigationBehavior) =>
+      commitNavigation(
+        {
+          to: "/pulse",
+          search: { profile: pubkey },
+        },
+        behavior,
+      ),
+    [commitNavigation],
+  );
+
   const goProjects = React.useCallback(
     (behavior?: NavigationBehavior) =>
       commitNavigation(
@@ -303,6 +315,7 @@ export function useAppNavigation() {
     goProject,
     goProjects,
     goPulse,
+    goProfile,
     goSettings,
     goWorkflow,
     goWorkflows,
diff --git a/desktop/src/app/navigation/useBackForwardControls.ts b/desktop/src/app/navigation/useBackForwardControls.ts
index 7f7d84f6d7..e5513247d5 100644
--- a/desktop/src/app/navigation/useBackForwardControls.ts
+++ b/desktop/src/app/navigation/useBackForwardControls.ts
@@ -4,7 +4,10 @@ import {
   useRouter,
   useRouterState,
 } from "@tanstack/react-router";
+import { isTauri } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
 
+import { matchBackForwardChord } from "@/app/navigation/backForwardChords";
 import { isMacPlatform } from "@/shared/lib/platform";
 import { trimMapToSize } from "@/shared/lib/trimMapToSize";
 
@@ -14,19 +17,6 @@ type RouterHistoryState = {
   key?: string;
 };
 
-function isEditableTarget(target: EventTarget | null): boolean {
-  if (!(target instanceof HTMLElement)) {
-    return false;
-  }
-
-  return (
-    target.isContentEditable ||
-    target.closest(
-      'input, textarea, select, [contenteditable=""], [contenteditable="true"]',
-    ) !== null
-  );
-}
-
 export function useBackForwardControls() {
   const router = useRouter();
   const canGoBack = useCanGoBack();
@@ -81,42 +71,34 @@ export function useBackForwardControls() {
   }, [canGoForward, router.history]);
 
   const handleKeyDown = React.useEffectEvent((event: KeyboardEvent) => {
-    if (isEditableTarget(event.target)) {
+    // Note: the chords deliberately fire even when focus is inside an
+    // editable element. The composer autofocuses on every channel switch
+    // (`useComposerAutofocus`), so in steady state focus almost always
+    // lives in a contenteditable — an editable-target guard here made the
+    // shortcuts effectively dead (#3775). Safe because neither ⌘[ / ⌘]
+    // (macOS) nor Alt+←/→ (Windows/Linux) carry text-editing semantics,
+    // and the TipTap editor binds no conflicting shortcuts.
+    const direction = matchBackForwardChord(event, isMacPlatform());
+
+    if (direction === "back") {
+      event.preventDefault();
+      goBack();
       return;
     }
 
-    const isMac = isMacPlatform();
-    const isBackShortcut = isMac
-      ? event.metaKey &&
-        !event.ctrlKey &&
-        !event.altKey &&
-        !event.shiftKey &&
-        (event.key === "[" || event.code === "BracketLeft")
-      : event.altKey &&
-        !event.metaKey &&
-        !event.ctrlKey &&
-        !event.shiftKey &&
-        event.key === "ArrowLeft";
-    const isForwardShortcut = isMac
-      ? event.metaKey &&
-        !event.ctrlKey &&
-        !event.altKey &&
-        !event.shiftKey &&
-        (event.key === "]" || event.code === "BracketRight")
-      : event.altKey &&
-        !event.metaKey &&
-        !event.ctrlKey &&
-        !event.shiftKey &&
-        event.key === "ArrowRight";
-
-    if (isBackShortcut) {
+    if (direction === "forward") {
       event.preventDefault();
+      goForward();
+    }
+  });
+
+  const handleMouseNav = React.useEffectEvent((direction: string) => {
+    if (direction === "back") {
       goBack();
       return;
     }
 
-    if (isForwardShortcut) {
-      event.preventDefault();
+    if (direction === "forward") {
       goForward();
     }
   });
@@ -128,6 +110,23 @@ export function useBackForwardControls() {
     };
   }, []);
 
+  // macOS: WKWebView never delivers X1/X2 button events or horizontal
+  // swipe gestures to the DOM, so the native layer catches them
+  // (`mouse_nav.rs`) and forwards them as a Tauri event.
+  React.useEffect(() => {
+    if (!isTauri()) {
+      return;
+    }
+
+    const unlistenPromise = listen<string>("mouse-nav", (event) => {
+      handleMouseNav(event.payload);
+    });
+
+    return () => {
+      void unlistenPromise.then((unlisten) => unlisten());
+    };
+  }, []);
+
   return {
     canGoBack,
     canGoForward,
diff --git a/desktop/src/app/useAppShellTrayMenu.tsx b/desktop/src/app/useAppShellTrayMenu.tsx
new file mode 100644
index 0000000000..e4b9774848
--- /dev/null
+++ b/desktop/src/app/useAppShellTrayMenu.tsx
@@ -0,0 +1,41 @@
+import type { Channel } from "@/shared/api/types";
+import { isMacPlatform } from "@/shared/lib/platform";
+
+import { useTrayMenu } from "@/app/useTrayMenu";
+
+/** Keeps the ticking native tray menu outside AppShell's render cycle. */
+export function AppShellTrayMenu({
+  channels,
+  goChannel,
+  openCreateChannel,
+}: {
+  channels: Channel[];
+  goChannel: (channelId: string) => Promise<unknown>;
+  openCreateChannel: () => void;
+}) {
+  if (!isMacPlatform()) return null;
+  return (
+    <MacAppShellTrayMenu
+      channels={channels}
+      goChannel={goChannel}
+      openCreateChannel={openCreateChannel}
+    />
+  );
+}
+
+function MacAppShellTrayMenu({
+  channels,
+  goChannel,
+  openCreateChannel,
+}: {
+  channels: Channel[];
+  goChannel: (channelId: string) => Promise<unknown>;
+  openCreateChannel: () => void;
+}): null {
+  useTrayMenu({
+    channels,
+    goChannel,
+    openCreateChannel,
+  });
+  return null;
+}
diff --git a/desktop/src/app/useTrayMenu.ts b/desktop/src/app/useTrayMenu.ts
new file mode 100644
index 0000000000..355c8e5d4f
--- /dev/null
+++ b/desktop/src/app/useTrayMenu.ts
@@ -0,0 +1,160 @@
+import * as React from "react";
+import { isTauri, invoke } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
+
+import {
+  getActiveTurnsForAgent,
+  useActiveAgentTurnsByChannel,
+} from "@/features/agents/activeAgentTurnsStore";
+import {
+  useManagedAgentsQuery,
+  useRelayAgentsQuery,
+} from "@/features/agents/hooks";
+import { normalizePubkey, truncatePubkey } from "@/shared/lib/pubkey";
+import { useNow } from "@/shared/lib/useNow";
+import { formatElapsed } from "@/features/agents/ui/agentSessionUtils";
+import type { Channel } from "@/shared/api/types";
+
+type TrayAgentActivity = {
+  activityId: string;
+  agentName: string;
+  channelId: string;
+  channelName: string;
+  elapsed: string;
+};
+
+type TrayAction =
+  | { kind: "newChannel" }
+  | { kind: "openChannel"; channelId: string };
+
+const MAX_RECENT_TRAY_ACTIVITIES = 5;
+
+/**
+ * Keeps Buzz's native tray menu synchronized with active agent turns and
+ * forwards its navigation actions into the React app.
+ */
+export function useTrayMenu({
+  channels,
+  goChannel,
+  openCreateChannel,
+}: {
+  channels: Channel[];
+  goChannel: (channelId: string) => Promise<unknown>;
+  openCreateChannel: () => void;
+}): void {
+  const activeTurns = useActiveAgentTurnsByChannel();
+  const now = useNow(1000);
+  const managedAgents = useManagedAgentsQuery().data;
+  const relayAgents = useRelayAgentsQuery().data;
+  const previousActivitiesRef = React.useRef(
+    new Map<string, TrayAgentActivity>(),
+  );
+  const [recentActivities, setRecentActivities] = React.useState<
+    TrayAgentActivity[]
+  >([]);
+
+  const activities = React.useMemo<TrayAgentActivity[]>(() => {
+    const channelNames = new Map(
+      channels.map((channel) => [channel.id, channel.name]),
+    );
+    const agentNames = new Map<string, string>();
+    for (const agent of [...(managedAgents ?? []), ...(relayAgents ?? [])]) {
+      agentNames.set(normalizePubkey(agent.pubkey), agent.name);
+    }
+
+    return activeTurns.flatMap((channelTurn) =>
+      channelTurn.agentPubkeys.map((pubkey) => {
+        const agentTurn = getActiveTurnsForAgent(pubkey).find(
+          (turn) => turn.channelId === channelTurn.channelId,
+        );
+
+        return {
+          activityId: `${channelTurn.channelId}:${normalizePubkey(pubkey)}`,
+          agentName:
+            agentNames.get(normalizePubkey(pubkey)) ??
+            `Agent ${truncatePubkey(pubkey)}`,
+          channelId: channelTurn.channelId,
+          channelName:
+            channelNames.get(channelTurn.channelId) ?? "Unknown channel",
+          elapsed: formatElapsed(
+            now - (agentTurn?.anchorAt ?? channelTurn.anchorAt),
+          ),
+        };
+      }),
+    );
+  }, [activeTurns, channels, managedAgents, now, relayAgents]);
+
+  React.useEffect(() => {
+    const currentActivities = new Map(
+      activities.map((activity) => [activity.activityId, activity]),
+    );
+    const completedActivities = [...previousActivitiesRef.current.entries()]
+      .filter(([activityId]) => !currentActivities.has(activityId))
+      .map(([, activity]) => ({
+        ...activity,
+        activityId: `recent:${activity.activityId}:${Date.now()}`,
+      }));
+
+    if (completedActivities.length > 0) {
+      setRecentActivities((current) =>
+        [...completedActivities, ...current].slice(
+          0,
+          MAX_RECENT_TRAY_ACTIVITIES,
+        ),
+      );
+    }
+    previousActivitiesRef.current = currentActivities;
+  }, [activities]);
+
+  React.useEffect(() => {
+    if (!isTauri()) return;
+    void invoke("update_tray_agent_activity", {
+      activities,
+      recentActivities,
+    }).catch((error) => {
+      console.error("Failed to update the macOS tray menu", error);
+    });
+  }, [activities, recentActivities]);
+
+  React.useEffect(() => {
+    if (!isTauri()) return;
+
+    let disposed = false;
+    let unlisten: (() => void) | undefined;
+
+    const handlePendingActions = async () => {
+      if (disposed) return;
+      const actions = await invoke<TrayAction[]>("take_tray_actions");
+      if (disposed) {
+        if (actions.length > 0) {
+          await invoke("requeue_tray_actions", { actions });
+        }
+        return;
+      }
+      for (const action of actions) {
+        if (action.kind === "newChannel") {
+          openCreateChannel();
+        } else {
+          void goChannel(action.channelId);
+        }
+      }
+    };
+
+    void (async () => {
+      const nextUnlisten = await listen("tray-action-available", () => {
+        void handlePendingActions();
+      });
+      if (disposed) {
+        nextUnlisten();
+        return;
+      }
+      unlisten = nextUnlisten;
+      await handlePendingActions();
+    })();
+
+    return () => {
+      disposed = true;
+      unlisten?.();
+    };
+  }, [goChannel, openCreateChannel]);
+}
diff --git a/desktop/src/features/agents/AGENTS.md b/desktop/src/features/agents/AGENTS.md
index 35ad4a63af..d9222c7032 100644
--- a/desktop/src/features/agents/AGENTS.md
+++ b/desktop/src/features/agents/AGENTS.md
@@ -114,6 +114,39 @@ with a TypeScript lookup table or an id comparison in a component.
     published or removed. A queued update must stay visibly queued, and the
     catalog itself must render only relay-confirmed publications — never an
     optimistic local persona.
+11. **Shared agent access names the consequence where it is selected.** The
+   shared respond-to field shows a persistent warning whenever `anyone` **or**
+   `allowlist` is selected — both hand the host's access to someone other than
+   the owner, so both disclose it and only the audience phrase differs. This
+   covers persona-backed create and edit surfaces. Keep that disclosure in
+   the shared field instead of adding surface-specific flags. It renders
+   directly below the selector for `anyone` but *after* the people picker for
+   `allowlist`, so it never sits between the user and the selection they came
+   to make. The copy leads with the audience ("Anyone can use this agent to
+   access…") so it reads as a warning rather than an explanation, and stays one
+   sentence — don't split the mechanism into a second sentence. Both the machine
+   and the stakes it names come from `lib/agentAccessWarning.ts`, keyed on an
+   optional `runLocation`: instance surfaces resolve it from
+   `ManagedAgent.backend` via `runLocationForBackend`, and the create flow from
+   `WhereToRunDraft.runOn` via `runLocationForRunOn`. `AgentDialog` is the one
+   place that resolves it for dialog surfaces and publishes it through
+   `ui/AgentRunLocationContext.tsx`; the field reads that context and lets an
+   explicit `runLocation` prop win. Do **not** thread the value as a prop
+   through `AgentDefinitionDialog` / `AgentInstanceEditDialog` — both are
+   already over the 1000-line ceiling, and neither uses the value itself.
+   Surfaces rendered outside `AgentDialog` (e.g. `EditRespondToDialog`) pass the
+   prop directly. Local names "your
+   computer, including files, accounts, and connected tools"; remote names "the
+   server it runs on, including any accounts and tools available there" —
+   deliberately *not* the owner's files, which aren't theirs to describe on a
+   host they don't own. **An unknown location falls back to the local wording —
+   never hedge with "computer or server".** A remote host requires an
+   installed `buzz-backend-*` provider, and without one `WhereToRunSection`
+   never renders, so "server" would name a concept the owner has never been
+   shown; when it *is* remote they picked that host from the selector
+   themselves. Never synthesize a run location a surface doesn't have. Don't
+   expose `respond-to`, `allowlist`, Nostr, or harness jargon in primary UI
+   copy.
 
 ## The tests that enforce this
 
@@ -128,6 +161,12 @@ with a TypeScript lookup table or an id comparison in a component.
   `isCacheableDiscoveryResponse`, `deriveModelDiscoveryPending`,
   `isSuccessfulEmptyDiscovery`. If the "reopen to retry" copy becomes inert
   again, these tests will catch it.
+- `ui/respondToFieldContract.test.mjs` — plain-language mode labels, the
+  persistent warning contract for shared agent access, and its two render
+  positions (after the people picker for `allowlist`).
+- `lib/agentAccessWarning.test.mjs` — every mode × run-location copy variant
+  plus both resolvers, including unknown-reads-as-local and
+  blank-`runOn`-is-not-a-provider.
 - `desktop/tests/e2e/onboarding-agent-defaults.spec.ts` — onboarding behavior
   acceptance coverage for readiness, failure states, defaults, navigation,
   successful-empty vs failed optional-model discovery, and persistence races.
diff --git a/desktop/src/features/agents/cardMintStore.test.mjs b/desktop/src/features/agents/cardMintStore.test.mjs
new file mode 100644
index 0000000000..eb9c0f07b0
--- /dev/null
+++ b/desktop/src/features/agents/cardMintStore.test.mjs
@@ -0,0 +1,170 @@
+import assert from "node:assert/strict";
+import { beforeEach, describe, it } from "node:test";
+
+// cardMintStore drives the non-blocking mint flow: the dialog dispatches a
+// job and closes; the composer chip, completion toast, and viewer all read
+// this store. These tests exercise the job lifecycle with an injected mintFn
+// (never the real Tauri command).
+//
+// The store imports sonner (toast); calling toast outside a mounted <Toaster>
+// only queues, so no DOM is required.
+
+import {
+  dismissCardMintJob,
+  getCardGalleryOpen,
+  getCardMintJobs,
+  getCardViewerState,
+  closeCardViewer,
+  openCardViewer,
+  resetCardMintStore,
+  runCardMintJob,
+  setCardGalleryOpen,
+  subscribeCardMintStore,
+  viewMintedCardJob,
+} from "./cardMintStore.ts";
+
+const CARD = {
+  cardPngBase64: "aGVsbG8=",
+  fileName: "eva.agent.png",
+  designerNotes: "notes",
+  locked: false,
+  memoryLevel: "none",
+};
+
+const INPUT = { agentId: "agent-1", agentName: "Eva" };
+
+describe("cardMintStore", () => {
+  beforeEach(() => {
+    resetCardMintStore();
+  });
+
+  it("forwards the mint input — including memoryLevel — to mintFn", async () => {
+    const seen = [];
+    await runCardMintJob(
+      { ...INPUT, styleNotes: "stormy", lock: true, memoryLevel: "core" },
+      (...args) => {
+        seen.push(args);
+        return Promise.resolve({ ...CARD, memoryLevel: "core" });
+      },
+    );
+    assert.deepEqual(seen, [["agent-1", "stormy", true, "core"]]);
+
+    // Omitted memoryLevel stays undefined so Rust applies its "none" default.
+    await runCardMintJob(INPUT, (...args) => {
+      seen.push(args);
+      return Promise.resolve(CARD);
+    });
+    assert.deepEqual(seen[1], ["agent-1", undefined, undefined, undefined]);
+  });
+
+  it("tracks a successful mint through minting → done", async () => {
+    let resolveMint;
+    const pending = new Promise((resolve) => {
+      resolveMint = resolve;
+    });
+    const run = runCardMintJob(INPUT, () => pending);
+
+    let jobs = getCardMintJobs();
+    assert.equal(jobs.length, 1);
+    assert.equal(jobs[0].phase, "minting");
+    assert.equal(jobs[0].input.agentName, "Eva");
+    assert.equal(jobs[0].card, null);
+
+    resolveMint(CARD);
+    await run;
+
+    jobs = getCardMintJobs();
+    assert.equal(jobs.length, 1);
+    assert.equal(jobs[0].phase, "done");
+    assert.deepEqual(jobs[0].card, CARD);
+    assert.equal(jobs[0].error, null);
+  });
+
+  it("records the error message on a failed mint", async () => {
+    await runCardMintJob(INPUT, () => Promise.reject(new Error("boom")));
+    const jobs = getCardMintJobs();
+    assert.equal(jobs.length, 1);
+    assert.equal(jobs[0].phase, "error");
+    assert.equal(jobs[0].error, "boom");
+    assert.equal(jobs[0].card, null);
+  });
+
+  it("strips the NO_OPENAI_KEY wire prefix from mint errors", async () => {
+    await runCardMintJob(INPUT, () =>
+      Promise.reject(new Error("NO_OPENAI_KEY: No OPENAI_API_KEY found.")),
+    );
+    assert.equal(getCardMintJobs()[0].error, "No OPENAI_API_KEY found.");
+  });
+
+  it("viewMintedCardJob moves a done job into the viewer and clears the chip", async () => {
+    await runCardMintJob(INPUT, () => Promise.resolve(CARD));
+    const jobId = getCardMintJobs()[0].jobId;
+
+    viewMintedCardJob(jobId);
+
+    assert.equal(getCardMintJobs().length, 0);
+    const viewer = getCardViewerState();
+    assert.ok(viewer);
+    assert.equal(viewer.agentName, "Eva");
+    assert.deepEqual(viewer.card, CARD);
+    // Fresh mints keep their input so the viewer can reroll.
+    assert.deepEqual(viewer.remint, INPUT);
+  });
+
+  it("viewMintedCardJob ignores jobs that are still minting", () => {
+    let resolveMint;
+    void runCardMintJob(
+      INPUT,
+      () => new Promise((resolve) => (resolveMint = resolve)),
+    );
+    const jobId = getCardMintJobs()[0].jobId;
+
+    viewMintedCardJob(jobId);
+
+    assert.equal(getCardMintJobs().length, 1);
+    assert.equal(getCardViewerState(), null);
+    resolveMint(CARD); // avoid a dangling promise
+  });
+
+  it("dismissCardMintJob removes only the named job", async () => {
+    await runCardMintJob(INPUT, () => Promise.reject(new Error("a")));
+    await runCardMintJob({ agentId: "agent-2", agentName: "Wren" }, () =>
+      Promise.reject(new Error("b")),
+    );
+    const [first, second] = getCardMintJobs();
+
+    dismissCardMintJob(first.jobId);
+
+    const jobs = getCardMintJobs();
+    assert.equal(jobs.length, 1);
+    assert.equal(jobs[0].jobId, second.jobId);
+  });
+
+  it("openCardViewer/closeCardViewer manage archive views without remint", () => {
+    openCardViewer({ card: CARD, agentName: "Eva", remint: null });
+    assert.equal(getCardViewerState()?.remint, null);
+    closeCardViewer();
+    assert.equal(getCardViewerState(), null);
+  });
+
+  it("gallery open flag toggles and notifies subscribers", () => {
+    let notified = 0;
+    const unsubscribe = subscribeCardMintStore(() => {
+      notified += 1;
+    });
+    setCardGalleryOpen(true);
+    assert.equal(getCardGalleryOpen(), true);
+    setCardGalleryOpen(true); // no-op must not notify
+    setCardGalleryOpen(false);
+    assert.equal(getCardGalleryOpen(), false);
+    assert.equal(notified, 2);
+    unsubscribe();
+  });
+
+  it("concurrent jobs keep distinct snapshots (referential updates)", async () => {
+    const before = getCardMintJobs();
+    await runCardMintJob(INPUT, () => Promise.resolve(CARD));
+    const after = getCardMintJobs();
+    assert.notEqual(before, after, "snapshot identity must change on update");
+  });
+});
diff --git a/desktop/src/features/agents/cardMintStore.ts b/desktop/src/features/agents/cardMintStore.ts
new file mode 100644
index 0000000000..0e4746d445
--- /dev/null
+++ b/desktop/src/features/agents/cardMintStore.ts
@@ -0,0 +1,227 @@
+import * as React from "react";
+import { toast } from "sonner";
+
+import {
+  mintAgentCard,
+  NO_OPENAI_KEY_PREFIX,
+  type MintedAgentCard,
+  type SnapshotMemoryLevel,
+} from "@/shared/api/tauriPersonas";
+
+/**
+ * Module store for agent-card mints (`useSyncExternalStore` pattern, same as
+ * `avatarPresentationStore`).
+ *
+ * A mint is one stateless ~2–3 minute Rust call. Owning the in-flight promise
+ * here — instead of inside the mint dialog — is what makes the dialog
+ * non-blocking: it dispatches and closes, the composer activity rail shows a
+ * live "Minting card…" chip, and completion lands as a clickable toast plus a
+ * persistent "card ready" chip, none of which need the dialog mounted.
+ */
+
+/** Everything needed to run (or re-run) one mint. */
+export type CardMintInput = {
+  agentId: string;
+  agentName: string;
+  styleNotes?: string;
+  lock?: boolean;
+  /** Memory to embed in the card's snapshot. Omitted = "none". */
+  memoryLevel?: SnapshotMemoryLevel;
+};
+
+export type CardMintJob = {
+  jobId: string;
+  input: CardMintInput;
+  phase: "minting" | "done" | "error";
+  /** Populated when phase is "done". */
+  card: MintedAgentCard | null;
+  /** Populated when phase is "error". */
+  error: string | null;
+  startedAt: number;
+};
+
+/** Card content shown by the global viewer dialog. */
+export type CardViewerState = {
+  card: MintedAgentCard;
+  agentName: string;
+  /**
+   * Present when the card can be rerolled (fresh mints carry their input;
+   * archive views do not — the original style notes are gone).
+   */
+  remint: CardMintInput | null;
+  /**
+   * Monotonic per-open sequence, assigned by the store. The viewer keys its
+   * content on this so switching cards remounts (resetting recipients/menu
+   * state) — card bytes can't serve as the key because every card PNG shares
+   * the same header prefix and dimensions.
+   */
+  viewerSeq: number;
+};
+
+let jobs: CardMintJob[] = [];
+let viewer: CardViewerState | null = null;
+let galleryOpen = false;
+const listeners = new Set<() => void>();
+let nextJobId = 1;
+let nextViewerSeq = 1;
+
+function emitChange(): void {
+  for (const listener of listeners) listener();
+}
+
+function updateJob(jobId: string, patch: Partial<CardMintJob>): void {
+  jobs = jobs.map((job) => (job.jobId === jobId ? { ...job, ...patch } : job));
+  emitChange();
+}
+
+/**
+ * Run one mint as a background job. `mintFn` is injectable for tests; the
+ * public `startCardMint` binds the real Tauri command.
+ */
+export async function runCardMintJob(
+  input: CardMintInput,
+  mintFn: (
+    id: string,
+    styleNotes?: string,
+    lock?: boolean,
+    memoryLevel?: SnapshotMemoryLevel,
+  ) => Promise<MintedAgentCard>,
+): Promise<void> {
+  const jobId = `card-mint-${nextJobId++}`;
+  jobs = [
+    ...jobs,
+    {
+      jobId,
+      input,
+      phase: "minting",
+      card: null,
+      error: null,
+      startedAt: Date.now(),
+    },
+  ];
+  emitChange();
+
+  try {
+    const card = await mintFn(
+      input.agentId,
+      input.styleNotes,
+      input.lock,
+      input.memoryLevel,
+    );
+    updateJob(jobId, { phase: "done", card });
+    toast.success(`${input.agentName}'s card is ready`, {
+      action: {
+        label: "View card",
+        onClick: () => viewMintedCardJob(jobId),
+      },
+      duration: 10_000,
+    });
+  } catch (error) {
+    let message = error instanceof Error ? error.message : "Card mint failed.";
+    if (message.startsWith(NO_OPENAI_KEY_PREFIX)) {
+      // The dialog pre-checks the key, so this only happens when the key was
+      // removed between dialog-open and mint. The dialog's key-setup panel is
+      // long gone — surface a plain instruction instead of the wire prefix.
+      message = message.slice(NO_OPENAI_KEY_PREFIX.length).trim();
+    }
+    updateJob(jobId, { phase: "error", error: message });
+    toast.error(`Minting ${input.agentName}'s card failed`, {
+      description: message,
+    });
+  }
+}
+
+/** Start a mint in the background. Fire-and-forget; state flows via the store. */
+export function startCardMint(input: CardMintInput): void {
+  void runCardMintJob(input, mintAgentCard);
+}
+
+/** Open the finished card of a job in the viewer and clear its rail chip. */
+export function viewMintedCardJob(jobId: string): void {
+  const job = jobs.find((candidate) => candidate.jobId === jobId);
+  if (job?.phase !== "done" || !job.card) return;
+  viewer = {
+    card: job.card,
+    agentName: job.input.agentName,
+    remint: job.input,
+    viewerSeq: nextViewerSeq++,
+  };
+  jobs = jobs.filter((candidate) => candidate.jobId !== jobId);
+  emitChange();
+}
+
+/** Remove a job chip (used for error dismissal). */
+export function dismissCardMintJob(jobId: string): void {
+  const next = jobs.filter((candidate) => candidate.jobId !== jobId);
+  if (next.length === jobs.length) return;
+  jobs = next;
+  emitChange();
+}
+
+/** Open the viewer on an arbitrary card (e.g. one loaded from the archive). */
+export function openCardViewer(
+  state: Omit<CardViewerState, "viewerSeq">,
+): void {
+  viewer = { ...state, viewerSeq: nextViewerSeq++ };
+  emitChange();
+}
+
+export function closeCardViewer(): void {
+  if (!viewer) return;
+  viewer = null;
+  emitChange();
+}
+
+export function setCardGalleryOpen(open: boolean): void {
+  if (galleryOpen === open) return;
+  galleryOpen = open;
+  emitChange();
+}
+
+export function resetCardMintStore(): void {
+  jobs = [];
+  viewer = null;
+  galleryOpen = false;
+  emitChange();
+}
+
+export function getCardMintJobs(): CardMintJob[] {
+  return jobs;
+}
+
+export function getCardViewerState(): CardViewerState | null {
+  return viewer;
+}
+
+export function getCardGalleryOpen(): boolean {
+  return galleryOpen;
+}
+
+export function subscribeCardMintStore(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function useCardMintJobs(): CardMintJob[] {
+  return React.useSyncExternalStore(
+    subscribeCardMintStore,
+    getCardMintJobs,
+    getCardMintJobs,
+  );
+}
+
+export function useCardViewerState(): CardViewerState | null {
+  return React.useSyncExternalStore(
+    subscribeCardMintStore,
+    getCardViewerState,
+    getCardViewerState,
+  );
+}
+
+export function useCardGalleryOpen(): boolean {
+  return React.useSyncExternalStore(
+    subscribeCardMintStore,
+    getCardGalleryOpen,
+    getCardGalleryOpen,
+  );
+}
diff --git a/desktop/src/features/agents/lib/agentAccessWarning.test.mjs b/desktop/src/features/agents/lib/agentAccessWarning.test.mjs
new file mode 100644
index 0000000000..0a3d13ce7b
--- /dev/null
+++ b/desktop/src/features/agents/lib/agentAccessWarning.test.mjs
@@ -0,0 +1,89 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  agentAccessWarningText,
+  runLocationForBackend,
+  runLocationForRunOn,
+} from "./agentAccessWarning.ts";
+
+test("only the modes that share access warn", () => {
+  assert.equal(agentAccessWarningText("owner-only", "local"), null);
+  assert.ok(agentAccessWarningText("anyone", "local"));
+  assert.ok(agentAccessWarningText("allowlist", "local"));
+});
+
+test("a local agent names this computer and what is reachable on it", () => {
+  assert.equal(
+    agentAccessWarningText("anyone", "local"),
+    "Anyone can use this agent to access your computer, including files, accounts, and connected tools.",
+  );
+  assert.equal(
+    agentAccessWarningText("allowlist", "local"),
+    "Selected people can use this agent to access your computer, including files, accounts, and connected tools.",
+  );
+});
+
+test("a provider-backed agent names the server, and not the owner's files", () => {
+  // A remote host's files aren't the owner's to describe, so the tail narrows
+  // to the accounts and tools provisioned there.
+  assert.equal(
+    agentAccessWarningText("anyone", "remote"),
+    "Anyone can use this agent to access the server it runs on, including any accounts and tools available there.",
+  );
+  assert.equal(
+    agentAccessWarningText("allowlist", "remote"),
+    "Selected people can use this agent to access the server it runs on, including any accounts and tools available there.",
+  );
+  assert.doesNotMatch(
+    agentAccessWarningText("anyone", "remote"),
+    /your computer/,
+  );
+});
+
+test("an unknown run location reads as local, not as a hedge", () => {
+  // "computer or server" names a concept most owners have never been shown:
+  // the Run on selector only renders when a buzz-backend-* provider exists.
+  for (const unknown of [undefined, null]) {
+    assert.equal(
+      agentAccessWarningText("anyone", unknown),
+      "Anyone can use this agent to access your computer, including files, accounts, and connected tools.",
+    );
+  }
+});
+
+test("every variant leads with the audience and stays jargon-free", () => {
+  for (const mode of ["anyone", "allowlist"]) {
+    for (const runLocation of [null, "local", "remote"]) {
+      const text = agentAccessWarningText(mode, runLocation);
+      assert.match(
+        text,
+        /^(Anyone|Selected people) can use this agent to access/,
+      );
+      assert.doesNotMatch(text, /respond-to|allowlist|pubkey|Nostr|harness/i);
+    }
+  }
+});
+
+test("runLocationForBackend maps the backend union", () => {
+  assert.equal(runLocationForBackend({ type: "local" }), "local");
+  assert.equal(
+    runLocationForBackend({ type: "provider", id: "blox", config: {} }),
+    "remote",
+  );
+  assert.equal(runLocationForBackend(null), null);
+  assert.equal(runLocationForBackend(undefined), null);
+});
+
+test("runLocationForRunOn treats a provider id as remote", () => {
+  assert.equal(runLocationForRunOn("local"), "local");
+  assert.equal(runLocationForRunOn("blox"), "remote");
+});
+
+test("runLocationForRunOn treats a blank value as unknown", () => {
+  // `runOn` is typed `"local" | string`, so a blank must not read as a
+  // provider id and produce the server wording.
+  assert.equal(runLocationForRunOn(""), null);
+  assert.equal(runLocationForRunOn(null), null);
+  assert.equal(runLocationForRunOn(undefined), null);
+});
diff --git a/desktop/src/features/agents/lib/agentAccessWarning.ts b/desktop/src/features/agents/lib/agentAccessWarning.ts
new file mode 100644
index 0000000000..d98058f5bf
--- /dev/null
+++ b/desktop/src/features/agents/lib/agentAccessWarning.ts
@@ -0,0 +1,63 @@
+import type { ManagedAgentBackend, RespondToMode } from "@/shared/api/types";
+
+/**
+ * Where an agent's process runs, as far as the calling surface can tell.
+ *
+ * Deliberately coarser than `ManagedAgentBackend`: the warning copy only needs
+ * to know "this machine" vs "somewhere else", so surfaces resolve their own
+ * backend shape down to this before handing it over. `null` means the surface
+ * genuinely cannot tell — see `agentAccessWarningText` for how that is
+ * treated.
+ */
+export type AgentRunLocation = "local" | "remote";
+
+/** Resolve a running agent's backend record. `null` when the backend is unknown. */
+export function runLocationForBackend(
+  backend: ManagedAgentBackend | null | undefined,
+): AgentRunLocation | null {
+  if (!backend) return null;
+  return backend.type === "local" ? "local" : "remote";
+}
+
+/**
+ * Resolve the create flow's `WhereToRunDraft.runOn`, which is `"local"` or a
+ * discovered provider id. An empty string is treated as unknown rather than as
+ * a provider, since `runOn` is typed `"local" | string`.
+ */
+export function runLocationForRunOn(
+  runOn: string | null | undefined,
+): AgentRunLocation | null {
+  if (!runOn) return null;
+  return runOn === "local" ? "local" : "remote";
+}
+
+/**
+ * Copy for the shared-access warning in the respond-to field, or `null` for
+ * modes that share nothing.
+ *
+ * Both `anyone` and `allowlist` hand the host's access to someone other than
+ * the owner, so both warn; only the audience phrase differs.
+ *
+ * An unknown run location falls back to the same "your computer" wording as
+ * `local` rather than hedging with "computer or server". A remote host is only
+ * reachable when a `buzz-backend-*` provider binary is installed — without one
+ * `WhereToRunSection`'s "Run on" selector never renders and every agent is
+ * local — so hedging would name a concept most owners have never been shown.
+ * When it *is* remote the owner picked that host from the selector
+ * deliberately, so naming a server is meaningful there.
+ */
+export function agentAccessWarningText(
+  mode: RespondToMode,
+  runLocation?: AgentRunLocation | null,
+): string | null {
+  if (mode !== "anyone" && mode !== "allowlist") return null;
+  const audience = mode === "anyone" ? "Anyone" : "Selected people";
+  // The two locations differ in more than the noun: a local agent reaches the
+  // owner's own files, while a remote host's files aren't theirs to describe —
+  // only the accounts and tools provisioned there.
+  const target =
+    runLocation === "remote"
+      ? "the server it runs on, including any accounts and tools available there"
+      : "your computer, including files, accounts, and connected tools";
+  return `${audience} can use this agent to access ${target}.`;
+}
diff --git a/desktop/src/features/agents/lib/agentCardGalleryState.test.mjs b/desktop/src/features/agents/lib/agentCardGalleryState.test.mjs
new file mode 100644
index 0000000000..ebc7caa8f4
--- /dev/null
+++ b/desktop/src/features/agents/lib/agentCardGalleryState.test.mjs
@@ -0,0 +1,96 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+// Pins the gallery's query-state boundary: a rejected `list_agent_cards`
+// MUST surface as an error state — never as "No cards yet". `data` falls
+// back to `[]` at the call site, so an emptiness-first branch would render
+// a permissions/IPC failure as a false empty archive of paid cards.
+
+import { agentCardGalleryViewState } from "./agentCardGalleryState.ts";
+
+describe("agentCardGalleryViewState", () => {
+  it("maps a rejected query to an error state with the message, not empty", () => {
+    const state = agentCardGalleryViewState({
+      isLoading: false,
+      isError: true,
+      error: new Error("cards directory unreadable"),
+      data: undefined,
+    });
+    assert.deepEqual(state, {
+      kind: "error",
+      message: "cards directory unreadable",
+    });
+  });
+
+  it("error wins even when data has fallen back to an empty array", () => {
+    // react-query keeps `data: undefined` on first failure, but the call
+    // site coalesces to []. Guard the exact shape that caused the bug.
+    const state = agentCardGalleryViewState({
+      isLoading: false,
+      isError: true,
+      error: new Error("ipc failure"),
+      data: [],
+    });
+    assert.equal(state.kind, "error");
+  });
+
+  it("stringifies non-Error rejections", () => {
+    const state = agentCardGalleryViewState({
+      isLoading: false,
+      isError: true,
+      error: "permission denied",
+      data: undefined,
+    });
+    assert.deepEqual(state, { kind: "error", message: "permission denied" });
+  });
+
+  it("null/undefined rejections still produce a message", () => {
+    const state = agentCardGalleryViewState({
+      isLoading: false,
+      isError: true,
+      error: null,
+      data: undefined,
+    });
+    assert.deepEqual(state, { kind: "error", message: "unknown error" });
+  });
+
+  it("loading while fetching", () => {
+    const state = agentCardGalleryViewState({
+      isLoading: true,
+      isError: false,
+      error: null,
+      data: undefined,
+    });
+    assert.deepEqual(state, { kind: "loading" });
+  });
+
+  it("no data yet (not loading, not error) stays loading, not empty", () => {
+    const state = agentCardGalleryViewState({
+      isLoading: false,
+      isError: false,
+      error: null,
+      data: undefined,
+    });
+    assert.deepEqual(state, { kind: "loading" });
+  });
+
+  it("resolved and empty is the only path to the empty state", () => {
+    const state = agentCardGalleryViewState({
+      isLoading: false,
+      isError: false,
+      error: null,
+      data: [],
+    });
+    assert.deepEqual(state, { kind: "empty" });
+  });
+
+  it("resolved with cards renders cards", () => {
+    const state = agentCardGalleryViewState({
+      isLoading: false,
+      isError: false,
+      error: null,
+      data: [{ storedFileName: "a.png" }],
+    });
+    assert.deepEqual(state, { kind: "cards" });
+  });
+});
diff --git a/desktop/src/features/agents/lib/agentCardGalleryState.ts b/desktop/src/features/agents/lib/agentCardGalleryState.ts
new file mode 100644
index 0000000000..8f6cf4269e
--- /dev/null
+++ b/desktop/src/features/agents/lib/agentCardGalleryState.ts
@@ -0,0 +1,35 @@
+/**
+ * View-state selection for the minted-card gallery.
+ *
+ * Kept as a pure function so the error boundary is testable without a DOM:
+ * a rejected `list_agent_cards` query MUST surface as an error state, never
+ * as an empty archive — "No cards yet" on a permissions/IPC failure tells
+ * someone their paid, persisted cards do not exist.
+ */
+
+export type AgentCardGalleryViewState =
+  | { kind: "loading" }
+  | { kind: "error"; message: string }
+  | { kind: "empty" }
+  | { kind: "cards" };
+
+export function agentCardGalleryViewState(query: {
+  isLoading: boolean;
+  isError: boolean;
+  error: unknown;
+  data: readonly unknown[] | undefined;
+}): AgentCardGalleryViewState {
+  // Error wins over everything: `data` falls back to `[]` at the call site,
+  // so checking emptiness first would render a failure as a false empty.
+  if (query.isError) {
+    const message =
+      query.error instanceof Error
+        ? query.error.message
+        : String(query.error ?? "unknown error");
+    return { kind: "error", message };
+  }
+  if (query.isLoading || query.data === undefined) {
+    return { kind: "loading" };
+  }
+  return query.data.length === 0 ? { kind: "empty" } : { kind: "cards" };
+}
diff --git a/desktop/src/features/agents/lib/personaCatalogRelay.test.mjs b/desktop/src/features/agents/lib/personaCatalogRelay.test.mjs
index 24f6959b1c..fbaf1f5274 100644
--- a/desktop/src/features/agents/lib/personaCatalogRelay.test.mjs
+++ b/desktop/src/features/agents/lib/personaCatalogRelay.test.mjs
@@ -205,6 +205,30 @@ test("test_non_svg_data_avatar_is_rejected", () => {
   assert.equal(catalogAvatarUrl("data:image/png,%89PNG"), null);
 });
 
+test("test_legacy_inline_raster_avatar_survives_the_catalog", () => {
+  for (const mime of ["png", "jpeg", "gif", "webp"]) {
+    const avatar = `data:image/${mime};base64,iVBORw0KGgo=`;
+    assert.equal(catalogAvatarUrl(avatar), avatar);
+  }
+});
+
+test("test_inline_raster_avatar_rejects_unbounded_or_malformed_payloads", () => {
+  const prefix = "data:image/png;base64,";
+  const payloadLength = 256 * 1_024 - prefix.length;
+  const validPayloadLength = payloadLength - (payloadLength % 4);
+  const withinCap = `${prefix}${"a".repeat(validPayloadLength - 2)}==`;
+  assert.ok(withinCap.length <= 256 * 1_024);
+  assert.equal(catalogAvatarUrl(withinCap), withinCap);
+  assert.equal(
+    catalogAvatarUrl(
+      `${withinCap}${"a".repeat(256 * 1_024 - withinCap.length + 1)}`,
+    ),
+    null,
+  );
+  assert.equal(catalogAvatarUrl("data:image/png;base64,not base64"), null);
+  assert.equal(catalogAvatarUrl("data:image/bmp;base64,aA=="), null);
+});
+
 test("test_oversized_inline_svg_avatar_is_rejected", () => {
   const withinCap = `data:image/svg+xml,${"a".repeat(8_192 - "data:image/svg+xml,".length)}`;
   assert.equal(withinCap.length, 8_192);
diff --git a/desktop/src/features/agents/lib/personaCatalogRelay.ts b/desktop/src/features/agents/lib/personaCatalogRelay.ts
index c85a976ba6..02c3f8e202 100644
--- a/desktop/src/features/agents/lib/personaCatalogRelay.ts
+++ b/desktop/src/features/agents/lib/personaCatalogRelay.ts
@@ -93,6 +93,16 @@ function isSafeHttpUrl(value: unknown): value is string {
 const INLINE_SVG_AVATAR_PREFIX = "data:image/svg+xml,";
 const MAX_INLINE_SVG_AVATAR_LENGTH = 8_192;
 
+/**
+ * Shared persona heads can carry an uploaded avatar as an inline raster. Keep
+ * those self-contained images renderable without accepting arbitrary `data:`
+ * URLs: only the raster MIME types browsers decode in `<img>`, strict base64
+ * shape, and a bound no larger than the relay's event-content ceiling.
+ */
+const MAX_INLINE_RASTER_AVATAR_LENGTH = 256 * 1_024;
+const INLINE_RASTER_AVATAR_RE =
+  /^data:image\/(?:png|jpeg|gif|webp);base64,([A-Za-z0-9+/]+={0,2})$/u;
+
 function isInlineSvgAvatar(value: unknown): value is string {
   return (
     typeof value === "string" &&
@@ -101,6 +111,17 @@ function isInlineSvgAvatar(value: unknown): value is string {
   );
 }
 
+function isInlineRasterAvatar(value: unknown): value is string {
+  if (
+    typeof value !== "string" ||
+    value.length > MAX_INLINE_RASTER_AVATAR_LENGTH
+  ) {
+    return false;
+  }
+  const match = INLINE_RASTER_AVATAR_RE.exec(value);
+  return match !== null && (match[1]?.length ?? 0) % 4 === 0;
+}
+
 function optionalString(value: unknown): string | null {
   return typeof value === "string" && value.trim().length > 0 ? value : null;
 }
@@ -121,7 +142,9 @@ function parsePersonaContent(event: RelayEvent): CatalogAgentProjection | null {
   }
 
   const avatarUrl =
-    isSafeHttpUrl(parsed.avatar_url) || isInlineSvgAvatar(parsed.avatar_url)
+    isSafeHttpUrl(parsed.avatar_url) ||
+    isInlineSvgAvatar(parsed.avatar_url) ||
+    isInlineRasterAvatar(parsed.avatar_url)
       ? parsed.avatar_url
       : null;
   const namePool = Array.isArray(parsed.name_pool)
diff --git a/desktop/src/features/agents/lib/useInstallOutputLine.test.mjs b/desktop/src/features/agents/lib/useInstallOutputLine.test.mjs
new file mode 100644
index 0000000000..d65583e00d
--- /dev/null
+++ b/desktop/src/features/agents/lib/useInstallOutputLine.test.mjs
@@ -0,0 +1,82 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { nextInstallOutputLine } from "./useInstallOutputLine.ts";
+
+function event(runtimeId, seq, line) {
+  return { runtime_id: runtimeId, seq, line };
+}
+
+test("nextInstallOutputLine: adopts the first line for the watched runtime", () => {
+  assert.deepEqual(
+    nextInstallOutputLine(null, event("goose", 0, "downloading"), "goose"),
+    { seq: 0, line: "downloading" },
+  );
+});
+
+test("nextInstallOutputLine: a later line replaces the current one", () => {
+  const current = { seq: 4, line: "downloading" };
+
+  assert.deepEqual(
+    nextInstallOutputLine(current, event("goose", 5, "unpacking"), "goose"),
+    { seq: 5, line: "unpacking" },
+  );
+});
+
+test("nextInstallOutputLine: ignores a line from another runtime", () => {
+  const current = { seq: 1, line: "downloading" };
+
+  assert.equal(
+    nextInstallOutputLine(current, event("codex", 2, "other work"), "goose"),
+    current,
+  );
+});
+
+test("nextInstallOutputLine: ignores an out-of-order line", () => {
+  const current = { seq: 7, line: "retrying" };
+
+  assert.equal(
+    nextInstallOutputLine(current, event("goose", 6, "stale line"), "goose"),
+    current,
+  );
+});
+
+test("nextInstallOutputLine: ignores a replay of the current sequence number", () => {
+  const current = { seq: 7, line: "retrying" };
+
+  assert.equal(
+    nextInstallOutputLine(current, event("goose", 7, "duplicate"), "goose"),
+    current,
+  );
+});
+
+test("nextInstallOutputLine: a null line clears the display", () => {
+  const current = { seq: 3, line: "download failed" };
+
+  assert.deepEqual(
+    nextInstallOutputLine(current, event("goose", 4, null), "goose"),
+    { seq: 4, line: null },
+  );
+});
+
+test("nextInstallOutputLine: a later step's first line is adopted after a higher attempt", () => {
+  // The seq is install-wide: step 2 attempt 1 always follows step 1 attempt 2,
+  // which is exactly what an attempt-keyed comparison got wrong.
+  const current = { seq: 9, line: "step one, attempt two" };
+
+  assert.deepEqual(
+    nextInstallOutputLine(
+      current,
+      event("goose", 10, "step two, attempt one"),
+      "goose",
+    ),
+    { seq: 10, line: "step two, attempt one" },
+  );
+});
+
+test("nextInstallOutputLine: a first event mid-install is adopted", () => {
+  assert.deepEqual(
+    nextInstallOutputLine(null, event("goose", 42, "downloading"), "goose"),
+    { seq: 42, line: "downloading" },
+  );
+});
diff --git a/desktop/src/features/agents/lib/useInstallOutputLine.ts b/desktop/src/features/agents/lib/useInstallOutputLine.ts
new file mode 100644
index 0000000000..9f50843fc7
--- /dev/null
+++ b/desktop/src/features/agents/lib/useInstallOutputLine.ts
@@ -0,0 +1,108 @@
+import * as React from "react";
+import { listen } from "@tauri-apps/api/event";
+
+/** Mirror of the Rust `InstallOutputEvent` payload (install_report.rs). */
+export type InstallOutputEvent = {
+  runtime_id: string;
+  /** Monotonic across the whole install, not per step or per attempt. */
+  seq: number;
+  /** Null is the start signal: clear the displayed line now. */
+  line: string | null;
+};
+
+/** The line being shown, and the sequence number that produced it. */
+export type InstallOutputState = {
+  seq: number;
+  line: string | null;
+};
+
+/**
+ * Fold one event into the displayed line.
+ *
+ * Events from another runtime are ignored — every install card listens to the
+ * same channel. So is an out-of-order event: emission is monotonic in `seq`, so
+ * a lower one has already been superseded. That matters at a retry boundary,
+ * where a line emitted just as the next attempt starts would otherwise sit
+ * under the spinner showing the failure the user already had.
+ *
+ * The ordering key is the install-wide `seq` rather than the attempt number,
+ * which restarts at 1 for every step: keyed on attempt, a step that succeeded on
+ * attempt 2 would make the next step's attempt-1 output look stale and freeze
+ * the display for the rest of the install.
+ */
+export function nextInstallOutputLine(
+  current: InstallOutputState | null,
+  event: InstallOutputEvent,
+  runtimeId: string,
+): InstallOutputState | null {
+  if (event.runtime_id !== runtimeId) return current;
+  if (current && event.seq <= current.seq) return current;
+  return { seq: event.seq, line: event.line };
+}
+
+/**
+ * The install command's most recent output line for `runtimeId`, or null when
+ * nothing is being shown — the install is not running, nothing has printed yet,
+ * or the backend cleared the line because a new attempt is starting.
+ *
+ * An install runs for up to 15 minutes with no other feedback than a spinner;
+ * this turns that wait into observable progress. The backend throttles
+ * emission, so this re-renders a few times a second at most.
+ *
+ * Pass `isInstalling` so the line clears when the install settles — a finished
+ * install must not leave its last line under a fresh Install button.
+ */
+export function useInstallOutputLine(
+  runtimeId: string,
+  isInstalling: boolean,
+): string | null {
+  const [state, setState] = React.useState<InstallOutputState | null>(null);
+
+  // Subscribed for this runtime's whole lifetime, not just while installing.
+  // The install command is invoked from the click handler, so the backend can
+  // emit the attempt-start clear and the first line before React commits
+  // `isInstalling` — and there is no replay, so a subscription that waited for
+  // that commit would lose those events permanently. A fast command's entire
+  // output is exactly what fits in that window.
+  React.useEffect(() => {
+    let cancelled = false;
+    let unlisten: (() => void) | null = null;
+    (async () => {
+      try {
+        const stop = await listen<InstallOutputEvent>(
+          "acp-install-output",
+          (event) => {
+            if (cancelled) return;
+            setState((current) =>
+              nextInstallOutputLine(current, event.payload, runtimeId),
+            );
+          },
+        );
+        if (cancelled) {
+          stop();
+        } else {
+          unlisten = stop;
+        }
+      } catch {
+        // Event system unavailable (web/e2e) — the spinner shows alone.
+      }
+    })();
+    return () => {
+      cancelled = true;
+      unlisten?.();
+    };
+  }, [runtimeId]);
+
+  // `seq` is monotonic within one install and restarts at 0 for the next, so
+  // state must not outlive the run that produced it: a retained higher `seq`
+  // would make every event of the following install look superseded. Settling
+  // is the run boundary, so it is where the ordering key resets.
+  React.useEffect(() => {
+    if (!isInstalling) setState(null);
+  }, [isInstalling]);
+
+  // Events that arrive after the install settles — a drain flushing its last
+  // line — must not reappear under a fresh Install button, so the line is
+  // reported only while the install is running.
+  return (isInstalling ? state?.line : null) ?? null;
+}
diff --git a/desktop/src/features/agents/ui/AgentCardMintDialog.tsx b/desktop/src/features/agents/ui/AgentCardMintDialog.tsx
new file mode 100644
index 0000000000..219de4aefa
--- /dev/null
+++ b/desktop/src/features/agents/ui/AgentCardMintDialog.tsx
@@ -0,0 +1,364 @@
+import * as React from "react";
+import {
+  AlertCircle,
+  Brain,
+  ExternalLink,
+  GalleryVerticalEnd,
+  KeyRound,
+  Lock,
+  Sparkles,
+} from "lucide-react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { openUrl } from "@tauri-apps/plugin-opener";
+import { toast } from "sonner";
+
+import {
+  setCardGalleryOpen,
+  startCardMint,
+} from "@/features/agents/cardMintStore";
+import { globalAgentConfigQueryKey } from "@/features/agents/useGlobalAgentConfig";
+import {
+  cardMintKeyStatus,
+  cardMintSaveOpenaiKey,
+  type SnapshotMemoryLevel,
+} from "@/shared/api/tauriPersonas";
+import { Button } from "@/shared/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/shared/ui/dialog";
+import { Input } from "@/shared/ui/input";
+import { Switch } from "@/shared/ui/switch";
+import { Textarea } from "@/shared/ui/textarea";
+import { SnapshotOptionMenu } from "./SnapshotOptionMenu";
+
+const OPENAI_KEYS_URL = "https://platform.openai.com/api-keys";
+
+/** Same three levels as snapshot export; "Agent only" is the safe default. */
+const MEMORY_LEVELS: { value: SnapshotMemoryLevel; label: string }[] = [
+  { value: "none", label: "Agent only" },
+  { value: "core", label: "Agent + core memory" },
+  { value: "everything", label: "Agent + all memories" },
+];
+
+/**
+ * The free alternative, as an action: ordinary snapshot export shares the
+ * same importable agent without card art or API spend. Rendered in both the
+ * key-setup panel and the normal pre-mint form (the cost disclosure and its
+ * escape hatch must be visible BEFORE any spend, not only during onboarding).
+ */
+function FreeSharePathRow({
+  disabled,
+  onExportInstead,
+}: {
+  disabled: boolean;
+  onExportInstead?: () => void;
+}) {
+  return (
+    <div
+      className="flex items-center justify-between gap-3"
+      data-testid="agent-card-free-path"
+    >
+      <p className="text-xs text-muted-foreground">
+        Don’t want to spend money? Ordinary export shares the same importable
+        agent — free, just without the card art.
+      </p>
+      {onExportInstead ? (
+        <Button
+          className="shrink-0"
+          data-testid="agent-card-export-instead"
+          disabled={disabled}
+          onClick={onExportInstead}
+          size="sm"
+          variant="outline"
+        >
+          Share without card art
+        </Button>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * Mint-a-trading-card dialog — the pre-mint half only: key setup (when
+ * needed) → optional style notes → "Mint card". Minting itself runs as a
+ * background job in `cardMintStore`: this dialog dispatches and closes, the
+ * composer activity rail shows live status, and the finished card opens in
+ * the global `AgentCardViewerDialog` (preview, reroll, save, share).
+ *
+ * The saved PNG carries the agent's `buzz_agent_snapshot` chunk, so sharing
+ * the card shares an importable agent (fresh identity, never secrets; memory
+ * only when the owner opts in below — plaintext unless the card is locked).
+ * All snapshot construction and verification happens in Rust.
+ */
+export function AgentCardMintDialog({
+  agentId,
+  agentName,
+  canLock,
+  onExportInstead,
+  onOpenChange,
+}: {
+  /** Instance pubkey or definition slug — same resolution as snapshot export. */
+  agentId: string;
+  agentName: string;
+  /**
+   * True when the agent has a linked instance (a keypair to lock to).
+   * Locking is disabled — with an explanation — for bare definitions.
+   */
+  canLock: boolean;
+  /**
+   * Free alternative: close this dialog and open the ordinary snapshot
+   * export flow (no API spend). Omitted = the action is not rendered.
+   */
+  onExportInstead?: () => void;
+  onOpenChange: (open: boolean) => void;
+}) {
+  const [styleNotes, setStyleNotes] = React.useState("");
+  const [lockCard, setLockCard] = React.useState(false);
+  const [memoryLevel, setMemoryLevel] =
+    React.useState<SnapshotMemoryLevel>("none");
+  const [keyDraft, setKeyDraft] = React.useState("");
+
+  const queryClient = useQueryClient();
+
+  const effectiveLock = canLock && lockCard;
+  // Embedded memory is plaintext in an unlocked card — and unlocked cards
+  // are meant to be shared. A locked card encrypts the whole manifest to the
+  // (owner, agent) pair, so the plaintext warning would be false there.
+  const showMemoryWarning = memoryLevel !== "none" && !effectiveLock;
+
+  // Whether a key already resolves through the agent's env layering. While
+  // unknown (loading/error) we show the normal mint form — the mint itself
+  // still fails cleanly if no key exists.
+  const keyStatusQuery = useQuery({
+    queryKey: ["cardMintKeyStatus", agentId],
+    queryFn: () => cardMintKeyStatus(agentId),
+  });
+  const needsKey = keyStatusQuery.data === false;
+
+  // Save the pasted key into the global Agent Defaults env — the same single
+  // source of truth every agent inherits. Narrow Rust seam: validated
+  // single-key merge, never restarts running agents (the mint re-reads
+  // config per call, so no restart is needed for minting).
+  const saveKeyMutation = useMutation({
+    mutationFn: (key: string) => cardMintSaveOpenaiKey(key),
+    onSuccess: () => {
+      queryClient.setQueryData(["cardMintKeyStatus", agentId], true);
+      // The Agent Defaults editor caches the whole config — refetch it so a
+      // later-opened settings view shows the key we just wrote.
+      void queryClient.invalidateQueries({
+        queryKey: globalAgentConfigQueryKey,
+      });
+      setKeyDraft("");
+      toast.success(
+        "API key saved to your agent defaults. Running agents pick it up on their next restart.",
+      );
+    },
+    onError: (error) =>
+      toast.error(typeof error === "string" ? error : "Couldn't save the key."),
+  });
+
+  function beginMint() {
+    // Dispatch to the background store and close: the composer rail shows
+    // "Minting card…" and the completion toast opens the viewer.
+    startCardMint({
+      agentId,
+      agentName,
+      styleNotes: styleNotes.trim() || undefined,
+      lock: effectiveLock,
+      memoryLevel: canLock ? memoryLevel : "none",
+    });
+    onOpenChange(false);
+  }
+
+  return (
+    <Dialog onOpenChange={onOpenChange} open>
+      <DialogContent className="max-w-md" data-testid="agent-card-mint-dialog">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <Sparkles className="h-4 w-4" />
+            {`Create ${agentName}'s card`}
+          </DialogTitle>
+          <DialogDescription>
+            Mint a collectible trading card that doubles as a shareable,
+            importable copy of this agent.
+          </DialogDescription>
+        </DialogHeader>
+
+        {needsKey ? (
+          <div
+            className="flex flex-col gap-4"
+            data-testid="agent-card-key-setup"
+          >
+            <div className="flex flex-col gap-2 rounded-md border border-border p-3">
+              <span className="flex items-center gap-1.5 text-sm font-medium">
+                <KeyRound className="h-3.5 w-3.5" />
+                One-time setup: OpenAI API key
+              </span>
+              <p className="text-xs text-muted-foreground">
+                Minting a card costs money — it generates the art and card text
+                through the OpenAI API with your key (typically well under a
+                dollar per mint, billed by OpenAI). The key is saved to your
+                agent defaults, so you only do this once.
+              </p>
+              <Button
+                className="w-fit px-0 text-xs"
+                data-testid="agent-card-key-link"
+                onClick={() =>
+                  void openUrl(OPENAI_KEYS_URL).catch(() => {
+                    toast.error("Failed to open link");
+                  })
+                }
+                size="sm"
+                variant="link"
+              >
+                <ExternalLink className="mr-1 h-3 w-3" />
+                Get a key at platform.openai.com
+              </Button>
+              <Input
+                autoFocus
+                data-testid="agent-card-key-input"
+                disabled={saveKeyMutation.isPending}
+                onChange={(e) => setKeyDraft(e.target.value)}
+                placeholder="sk-…"
+                type="password"
+                value={keyDraft}
+              />
+            </div>
+            <FreeSharePathRow
+              disabled={saveKeyMutation.isPending}
+              onExportInstead={onExportInstead}
+            />
+            <div className="flex justify-end">
+              <Button
+                data-testid="agent-card-key-save"
+                disabled={
+                  saveKeyMutation.isPending || keyDraft.trim().length === 0
+                }
+                onClick={() => saveKeyMutation.mutate(keyDraft.trim())}
+              >
+                <KeyRound className="mr-2 h-4 w-4" />
+                {saveKeyMutation.isPending ? "Saving…" : "Save key & continue"}
+              </Button>
+            </div>
+          </div>
+        ) : (
+          <div className="flex flex-col gap-4">
+            <div className="flex flex-col gap-1.5">
+              <Textarea
+                onChange={(e) => setStyleNotes(e.target.value)}
+                placeholder="Optional style notes for the art and card text"
+                rows={3}
+                value={styleNotes}
+              />
+              <p className="text-xs text-muted-foreground">
+                E.g. art “stormy night, lightning motif” or ability “Verify —
+                scry 2”. Your directions take priority; anything you leave open
+                is designed for you.
+              </p>
+            </div>
+            <div className="flex items-center justify-between gap-3 rounded-md border border-border p-3">
+              <div className="flex flex-col gap-0.5">
+                <span className="flex items-center gap-1.5 text-sm font-medium">
+                  <Brain className="h-3.5 w-3.5" />
+                  Memories
+                </span>
+                <span className="text-xs text-muted-foreground">
+                  {canLock
+                    ? "Choose how much memory the embedded agent carries."
+                    : "Including memory needs a linked agent instance — start this agent once to enable it."}
+                </span>
+              </div>
+              {canLock ? (
+                <SnapshotOptionMenu
+                  ariaLabel="Memories"
+                  className="font-medium text-foreground"
+                  onValueChange={(value) =>
+                    setMemoryLevel(value as SnapshotMemoryLevel)
+                  }
+                  options={MEMORY_LEVELS}
+                  testId="agent-card-memory-trigger"
+                  value={memoryLevel}
+                />
+              ) : (
+                <span
+                  className="inline-flex h-8 w-auto shrink-0 items-center justify-end px-2 text-sm font-medium"
+                  data-testid="agent-card-memory-value"
+                >
+                  Agent only
+                </span>
+              )}
+            </div>
+            {showMemoryWarning ? (
+              <div
+                className="flex items-start gap-2 rounded-md border border-amber-500/30 bg-amber-500/10 px-3 py-2 text-sm text-amber-700 dark:text-amber-400"
+                data-testid="agent-card-memory-warning"
+              >
+                <AlertCircle className="mt-0.5 h-4 w-4 shrink-0" />
+                <p>
+                  Memory is stored as <strong>plaintext</strong> in the card,
+                  readable by anyone who has the PNG — and cards are made for
+                  sharing. Lock the card or only share it with people you trust.
+                </p>
+              </div>
+            ) : null}
+            <div className="flex items-start justify-between gap-3 rounded-md border border-border p-3">
+              <div className="flex flex-col gap-0.5">
+                <span className="flex items-center gap-1.5 text-sm font-medium">
+                  <Lock className="h-3.5 w-3.5" />
+                  Lock card
+                </span>
+                <span className="text-xs text-muted-foreground">
+                  {canLock
+                    ? "Encrypt the embedded agent so only you and this agent can import it. Anyone else sees just the image."
+                    : "Locking needs a linked agent instance — start this agent once to enable it."}
+                </span>
+              </div>
+              <Switch
+                checked={canLock && lockCard}
+                data-testid="agent-card-lock-toggle"
+                disabled={!canLock}
+                onCheckedChange={setLockCard}
+              />
+            </div>
+            <p
+              className="text-xs text-muted-foreground"
+              data-testid="agent-card-cost-note"
+            >
+              Minting calls the OpenAI API with your key and costs money —
+              typically well under a dollar per mint, billed by OpenAI. It runs
+              in the background (takes a few minutes); you can keep using Buzz
+              while it works.
+            </p>
+            <FreeSharePathRow
+              disabled={false}
+              onExportInstead={onExportInstead}
+            />
+            <div className="flex items-center justify-between gap-2">
+              <Button
+                className="px-0 text-xs"
+                data-testid="agent-card-open-gallery"
+                onClick={() => {
+                  onOpenChange(false);
+                  setCardGalleryOpen(true);
+                }}
+                size="sm"
+                variant="link"
+              >
+                <GalleryVerticalEnd className="mr-1 h-3 w-3" />
+                View minted cards
+              </Button>
+              <Button onClick={beginMint} data-testid="agent-card-mint">
+                <Sparkles className="mr-2 h-4 w-4" />
+                Mint card
+              </Button>
+            </div>
+          </div>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/desktop/src/features/agents/ui/AgentCardViewerDialog.tsx b/desktop/src/features/agents/ui/AgentCardViewerDialog.tsx
new file mode 100644
index 0000000000..c2422466e4
--- /dev/null
+++ b/desktop/src/features/agents/ui/AgentCardViewerDialog.tsx
@@ -0,0 +1,369 @@
+import * as React from "react";
+import { Download, Lock, RefreshCw, Send, Sparkles } from "lucide-react";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { toast } from "sonner";
+
+import {
+  closeCardViewer,
+  openCardViewer,
+  setCardGalleryOpen,
+  startCardMint,
+  useCardGalleryOpen,
+  useCardViewerState,
+  type CardMintInput,
+} from "@/features/agents/cardMintStore";
+import { agentCardGalleryViewState } from "@/features/agents/lib/agentCardGalleryState";
+import {
+  useOpenDmMutation,
+  useUpsertCachedChannel,
+} from "@/features/channels/hooks";
+import {
+  listAgentCards,
+  loadAgentCard,
+  saveAgentCard,
+  type ArchivedAgentCard,
+  type MintedAgentCard,
+} from "@/shared/api/tauriPersonas";
+import type { UserSearchResult } from "@/shared/api/types";
+import { Button } from "@/shared/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/shared/ui/dialog";
+import {
+  MediaContextMenu,
+  type MediaContextMenuPosition,
+  useDismissMediaContextMenu,
+} from "@/shared/ui/markdown/MediaContextMenu";
+
+import { PersonaShareRecipients } from "./PersonaShareRecipients";
+import { useSnapshotSendController } from "./useSnapshotSendController";
+
+/** Decode base64 card bytes into the number[] shape the upload path expects. */
+function cardBytesFromBase64(b64: string): number[] {
+  return Array.from(atob(b64), (char) => char.charCodeAt(0));
+}
+
+/**
+ * Global card surfaces, mounted once in `AppShell` next to the other global
+ * dialogs and driven by `cardMintStore`: the finished-card viewer plus the
+ * previous-mints gallery.
+ */
+export function AgentCardDialogs() {
+  return (
+    <>
+      <AgentCardViewerDialog />
+      <AgentCardGalleryDialog />
+    </>
+  );
+}
+
+/**
+ * Global viewer for a finished agent trading card — the post-mint half of the
+ * old blocking mint dialog, now openable from anywhere (completion toast,
+ * composer "card ready" chip, or the previous-cards gallery). Mounted once in
+ * `AppShell` next to the other global dialogs and driven by `cardMintStore`.
+ *
+ * The card image carries the same right-click download menu inline channel
+ * images have (`MediaContextMenu`), but routed through `save_agent_card`:
+ * `download_image` only accepts relay `/media/` URLs, and this card exists
+ * only as local base64.
+ */
+export function AgentCardViewerDialog() {
+  const state = useCardViewerState();
+
+  // Keyed remount resets recipients/menu state when a different card opens.
+  if (!state) return null;
+  return (
+    <AgentCardViewerContent
+      key={state.viewerSeq}
+      agentName={state.agentName}
+      card={state.card}
+      remint={state.remint}
+    />
+  );
+}
+
+function AgentCardViewerContent({
+  agentName,
+  card,
+  remint,
+}: {
+  agentName: string;
+  card: MintedAgentCard;
+  remint: CardMintInput | null;
+}) {
+  const [recipients, setRecipients] = React.useState<UserSearchResult[]>([]);
+  const [menu, setMenu] = React.useState<MediaContextMenuPosition | null>(null);
+  const closeMenu = React.useCallback(() => setMenu(null), []);
+  useDismissMediaContextMenu(Boolean(menu), closeMenu);
+
+  const sendController = useSnapshotSendController(true);
+  const openDmMutation = useOpenDmMutation();
+  const upsertCachedChannel = useUpsertCachedChannel();
+
+  const saveMutation = useMutation({
+    mutationFn: () => saveAgentCard(card.cardPngBase64, card.fileName),
+    onSuccess: (saved) => {
+      if (saved) {
+        toast.success(
+          `Saved ${agentName}'s card. Share it — the card IS the agent.`,
+        );
+      }
+    },
+    onError: (error: Error) => toast.error(error.message),
+  });
+
+  const isSending =
+    sendController.state.phase !== "idle" &&
+    sendController.state.phase !== "done" &&
+    sendController.state.phase !== "error";
+  const isBusy = saveMutation.isPending || isSending;
+
+  async function sendToRecipients() {
+    if (recipients.length === 0) return;
+    const sent = await sendController.beginSend(
+      async () => ({
+        fileBytes: cardBytesFromBase64(card.cardPngBase64),
+        fileName: card.fileName,
+      }),
+      async () => {
+        const directMessage = await openDmMutation.mutateAsync({
+          pubkeys: recipients.map((recipient) => recipient.pubkey),
+        });
+        await upsertCachedChannel(directMessage);
+        return directMessage.id;
+      },
+      agentName,
+    );
+    if (sent) {
+      toast.success(`Sent ${agentName}'s card.`);
+      closeCardViewer();
+    } else if (sent === false) {
+      toast.error("Couldn’t send the card. Try again.");
+    }
+  }
+
+  return (
+    <Dialog onOpenChange={(open) => !open && closeCardViewer()} open>
+      <DialogContent
+        className="max-w-md"
+        data-testid="agent-card-viewer-dialog"
+      >
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <Sparkles className="h-4 w-4" />
+            {`${agentName}'s card`}
+          </DialogTitle>
+          <DialogDescription>
+            {card.locked
+              ? "This card is locked: only you and the agent can import it. Anyone else sees just the image."
+              : card.memoryLevel === "none"
+                ? "The card carries the agent — anyone who imports this PNG gets a working copy (config only, fresh identity, no memories)."
+                : `The card carries the agent — anyone who imports this PNG gets a working copy (fresh identity) including its ${card.memoryLevel === "core" ? "core memory" : "memories"}, stored as plaintext.`}
+          </DialogDescription>
+        </DialogHeader>
+        <div className="flex flex-col gap-4">
+          <img
+            alt={`${agentName} trading card`}
+            className="mx-auto max-h-[28rem] rounded-lg border shadow-lg"
+            data-testid="agent-card-preview"
+            onContextMenu={(event) => {
+              event.preventDefault();
+              setMenu({ x: event.clientX, y: event.clientY });
+            }}
+            src={`data:image/png;base64,${card.cardPngBase64}`}
+          />
+          {menu ? (
+            <MediaContextMenu
+              dataAttributes={["data-agent-card-context-menu"]}
+              items={[
+                {
+                  label: "Download card",
+                  onSelect: () => {
+                    closeMenu();
+                    saveMutation.mutate();
+                  },
+                },
+              ]}
+              position={menu}
+            />
+          ) : null}
+          <PersonaShareRecipients
+            disabled={isBusy || !sendController.isDmSafetyReady}
+            excludedPubkeys={
+              sendController.relaySelfPubkey
+                ? [sendController.relaySelfPubkey]
+                : []
+            }
+            onSelectionChange={setRecipients}
+            open
+            selectedUsers={recipients}
+            testIdPrefix="agent-card-share"
+          />
+          <div className="flex justify-end gap-2">
+            {remint ? (
+              <Button
+                disabled={isBusy}
+                data-testid="agent-card-reroll"
+                onClick={() => {
+                  // Reroll = a fresh background mint with the same input; the
+                  // viewer closes and the composer chip takes over.
+                  startCardMint(remint);
+                  closeCardViewer();
+                }}
+                variant="outline"
+              >
+                <RefreshCw className="mr-2 h-4 w-4" />
+                Reroll
+              </Button>
+            ) : null}
+            <Button
+              disabled={isBusy}
+              onClick={() => saveMutation.mutate()}
+              data-testid="agent-card-save"
+              variant={recipients.length > 0 ? "outline" : "default"}
+            >
+              <Download className="mr-2 h-4 w-4" />
+              Save card
+            </Button>
+            {recipients.length > 0 ? (
+              <Button
+                disabled={isBusy}
+                onClick={() => void sendToRecipients()}
+                data-testid="agent-card-send"
+              >
+                <Send className="mr-2 h-4 w-4" />
+                {isSending ? "Sending…" : "Send"}
+              </Button>
+            ) : null}
+          </div>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+/**
+ * Gallery of all previously minted cards, newest first. Every successful mint
+ * is archived to the app data dir by Rust; clicking a tile loads the full PNG
+ * and opens it in the viewer (save/share, no reroll — the original style
+ * notes are not retained).
+ */
+export function AgentCardGalleryDialog() {
+  const open = useCardGalleryOpen();
+  if (!open) return null;
+  return <AgentCardGalleryContent />;
+}
+
+function AgentCardGalleryContent() {
+  const cardsQuery = useQuery({
+    queryKey: ["agentCardArchive"],
+    queryFn: listAgentCards,
+  });
+
+  const openMutation = useMutation({
+    mutationFn: async (entry: ArchivedAgentCard) => {
+      const cardPngBase64 = await loadAgentCard(entry.storedFileName);
+      return { entry, cardPngBase64 };
+    },
+    onSuccess: ({ entry, cardPngBase64 }) => {
+      setCardGalleryOpen(false);
+      openCardViewer({
+        agentName: entry.agentName,
+        card: {
+          cardPngBase64,
+          fileName: entry.fileName,
+          designerNotes: entry.designerNotes,
+          locked: entry.locked,
+          memoryLevel: entry.memoryLevel,
+        },
+        remint: null,
+      });
+    },
+    onError: (error: Error) => toast.error(error.message),
+  });
+
+  const cards = cardsQuery.data ?? [];
+  const viewState = agentCardGalleryViewState(cardsQuery);
+
+  return (
+    <Dialog onOpenChange={(open) => setCardGalleryOpen(open)} open>
+      <DialogContent
+        className="max-w-lg"
+        data-testid="agent-card-gallery-dialog"
+      >
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <Sparkles className="h-4 w-4" />
+            Minted cards
+          </DialogTitle>
+          <DialogDescription>
+            Every card you’ve minted, newest first. Click one to view, save, or
+            share it.
+          </DialogDescription>
+        </DialogHeader>
+        {viewState.kind === "loading" ? (
+          <p className="py-8 text-center text-sm text-muted-foreground">
+            Loading cards…
+          </p>
+        ) : viewState.kind === "error" ? (
+          <div
+            className="flex flex-col items-center gap-3 py-8"
+            data-testid="agent-card-gallery-error"
+            role="alert"
+          >
+            <p className="text-center text-sm text-destructive">
+              Couldn’t load your minted cards: {viewState.message}
+            </p>
+            <Button
+              disabled={cardsQuery.isFetching}
+              onClick={() => void cardsQuery.refetch()}
+              size="sm"
+              variant="outline"
+            >
+              <RefreshCw className="mr-2 h-4 w-4" />
+              {cardsQuery.isFetching ? "Retrying…" : "Retry"}
+            </Button>
+          </div>
+        ) : viewState.kind === "empty" ? (
+          <p className="py-8 text-center text-sm text-muted-foreground">
+            No cards yet — mint one from an agent’s profile.
+          </p>
+        ) : (
+          <div className="grid max-h-[60vh] grid-cols-3 gap-3 overflow-y-auto pr-1">
+            {cards.map((entry) => (
+              <button
+                className="group flex flex-col gap-1.5 text-left"
+                data-testid="agent-card-gallery-item"
+                disabled={openMutation.isPending}
+                key={entry.storedFileName}
+                onClick={() => openMutation.mutate(entry)}
+                type="button"
+              >
+                {entry.thumbJpegBase64 ? (
+                  <img
+                    alt={`${entry.agentName} trading card`}
+                    className="aspect-2/3 w-full rounded-lg border object-cover shadow-sm transition-transform group-hover:scale-[1.02]"
+                    src={`data:image/jpeg;base64,${entry.thumbJpegBase64}`}
+                  />
+                ) : (
+                  <div className="flex aspect-2/3 w-full items-center justify-center rounded-lg border bg-muted/40">
+                    <Sparkles className="h-6 w-6 text-muted-foreground" />
+                  </div>
+                )}
+                <span className="flex items-center gap-1 truncate text-xs text-muted-foreground">
+                  {entry.locked ? <Lock className="h-3 w-3 shrink-0" /> : null}
+                  <span className="truncate">{entry.agentName}</span>
+                </span>
+              </button>
+            ))}
+          </div>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/desktop/src/features/agents/ui/AgentDialog.tsx b/desktop/src/features/agents/ui/AgentDialog.tsx
index f5be3cc7e8..dc608da489 100644
--- a/desktop/src/features/agents/ui/AgentDialog.tsx
+++ b/desktop/src/features/agents/ui/AgentDialog.tsx
@@ -6,6 +6,11 @@ import type {
   ManagedAgent,
   UpdatePersonaInput,
 } from "@/shared/api/types";
+import {
+  runLocationForBackend,
+  runLocationForRunOn,
+} from "../lib/agentAccessWarning";
+import { AgentRunLocationProvider } from "./AgentRunLocationContext";
 import type { BackendIntent } from "../lib/instanceInputForDefinition";
 import type { AgentCreateIntent } from "./agentCreateIntent";
 import type { EditAgentFocusTarget } from "@/features/agents/openEditAgentEvent";
@@ -89,17 +94,25 @@ type AgentDialogProps =
 export function AgentDialog(props: AgentDialogProps) {
   if (props.mode === "instance-edit") {
     return (
-      <AgentInstanceEditDialog
-        agent={props.agent}
-        onEditLinkedPersona={props.onEditLinkedPersona}
-        onOpenChange={props.onOpenChange}
-        onUpdated={props.onUpdated}
-        open={props.open}
-        initialFocus={props.initialFocus}
-      />
+      // A running instance knows its own backend, so the respond-to warning can
+      // name the machine it will actually run on.
+      <AgentRunLocationProvider
+        runLocation={runLocationForBackend(props.agent.backend)}
+      >
+        <AgentInstanceEditDialog
+          agent={props.agent}
+          onEditLinkedPersona={props.onEditLinkedPersona}
+          onOpenChange={props.onOpenChange}
+          onUpdated={props.onUpdated}
+          open={props.open}
+          initialFocus={props.initialFocus}
+        />
+      </AgentRunLocationProvider>
     );
   }
   if (props.mode === "definition-edit") {
+    // A definition has no instance and no run draft, so the run location stays
+    // unknown and the warning uses its local-wording fallback.
     const { mode: _mode, ...definitionProps } = props;
     return <AgentDefinitionDialog {...definitionProps} />;
   }
@@ -124,35 +137,39 @@ function AgentCreateDialogRouter({
   const copy = createPersonaDialogState();
 
   return (
-    <AgentDefinitionDialog
-      createRunSection={
-        <WhereToRunSection
-          draft={runDraft}
-          isPending={isDefinitionPending}
-          onDraftChange={setRunDraft}
-        />
-      }
-      createSubmitBlocked={!canSubmitWhereToRun(runDraft)}
-      description={copy.description}
-      error={definitionError}
-      initialValues={initialValues}
-      isPending={isDefinitionPending}
-      onOpenChange={onOpenChange}
-      onSubmit={async (input) => {
-        const submitted = await onSubmitDefinition(
-          input,
-          "definition_start",
-          resolveBackendIntent(runDraft),
-        );
-        if (submitted) {
-          onOpenChange(false);
+    // The create flow is the one surface that knows where the agent will run,
+    // because it owns the "Run on" draft.
+    <AgentRunLocationProvider runLocation={runLocationForRunOn(runDraft.runOn)}>
+      <AgentDefinitionDialog
+        createRunSection={
+          <WhereToRunSection
+            draft={runDraft}
+            isPending={isDefinitionPending}
+            onDraftChange={setRunDraft}
+          />
         }
-      }}
-      open
-      runtimes={runtimes}
-      runtimesLoading={runtimesLoading}
-      submitLabel={copy.submitLabel}
-      title={copy.title}
-    />
+        createSubmitBlocked={!canSubmitWhereToRun(runDraft)}
+        description={copy.description}
+        error={definitionError}
+        initialValues={initialValues}
+        isPending={isDefinitionPending}
+        onOpenChange={onOpenChange}
+        onSubmit={async (input) => {
+          const submitted = await onSubmitDefinition(
+            input,
+            "definition_start",
+            resolveBackendIntent(runDraft),
+          );
+          if (submitted) {
+            onOpenChange(false);
+          }
+        }}
+        open
+        runtimes={runtimes}
+        runtimesLoading={runtimesLoading}
+        submitLabel={copy.submitLabel}
+        title={copy.title}
+      />
+    </AgentRunLocationProvider>
   );
 }
diff --git a/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx b/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx
index f3c410e2ff..79d1e9a790 100644
--- a/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx
+++ b/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx
@@ -936,7 +936,7 @@ export function AgentInstanceEditDialog({
               </div>
             </div>
 
-            {/* Who can talk to this agent */}
+            {/* Who can send instructions */}
             <CreateAgentRespondToField
               allowlist={respondToAllowlist}
               disabled={updateMutation.isPending}
diff --git a/desktop/src/features/agents/ui/AgentManagementDialogs.tsx b/desktop/src/features/agents/ui/AgentManagementDialogs.tsx
index 604bf9f703..0d01cbbcd1 100644
--- a/desktop/src/features/agents/ui/AgentManagementDialogs.tsx
+++ b/desktop/src/features/agents/ui/AgentManagementDialogs.tsx
@@ -1,4 +1,5 @@
 import { useAgentManagement } from "@/features/agents/useAgentManagement";
+import { AgentCardDialogs } from "./AgentCardViewerDialog";
 import { AgentDialog } from "./AgentDialog";
 import { SecretRevealDialog } from "./SecretRevealDialog";
 
@@ -55,6 +56,7 @@ export function AgentManagementDialogs() {
           title="Edit agent"
         />
       ) : null}
+      <AgentCardDialogs />
     </>
   );
 }
diff --git a/desktop/src/features/agents/ui/AgentRunLocationContext.tsx b/desktop/src/features/agents/ui/AgentRunLocationContext.tsx
new file mode 100644
index 0000000000..5815130b47
--- /dev/null
+++ b/desktop/src/features/agents/ui/AgentRunLocationContext.tsx
@@ -0,0 +1,43 @@
+import * as React from "react";
+
+import type { AgentRunLocation } from "../lib/agentAccessWarning";
+
+/**
+ * Where the agent a dialog subtree is editing will run.
+ *
+ * Context rather than a prop on purpose: the only consumer is the respond-to
+ * warning, buried several levels inside `AgentDefinitionDialog` (1000+ lines)
+ * and `AgentInstanceEditDialog` (1200+ lines). Threading a prop through them
+ * would grow two files that are already over the 1000-line ceiling enforced by
+ * `desktop/scripts/check-file-sizes.mjs`, for a value neither of them uses.
+ *
+ * `AgentDialog` is the single entry point for all three dialog modes, so it is
+ * the one place that provides this. Surfaces that render the respond-to field
+ * outside that tree (e.g. `EditRespondToDialog`) pass the `runLocation` prop
+ * directly instead.
+ *
+ * The default is `null` — unknown. Never provide a guessed value; the copy
+ * falls back to the local wording, which is correct for any owner who has not
+ * installed a `buzz-backend-*` provider.
+ */
+const AgentRunLocationContext = React.createContext<AgentRunLocation | null>(
+  null,
+);
+
+export function AgentRunLocationProvider({
+  children,
+  runLocation,
+}: {
+  children: React.ReactNode;
+  runLocation: AgentRunLocation | null;
+}) {
+  return (
+    <AgentRunLocationContext.Provider value={runLocation}>
+      {children}
+    </AgentRunLocationContext.Provider>
+  );
+}
+
+export function useAgentRunLocation(): AgentRunLocation | null {
+  return React.useContext(AgentRunLocationContext);
+}
diff --git a/desktop/src/features/agents/ui/AgentSnapshotImportDialog.tsx b/desktop/src/features/agents/ui/AgentSnapshotImportDialog.tsx
index 4a9584dfb9..0527565763 100644
--- a/desktop/src/features/agents/ui/AgentSnapshotImportDialog.tsx
+++ b/desktop/src/features/agents/ui/AgentSnapshotImportDialog.tsx
@@ -1,5 +1,5 @@
 import * as React from "react";
-import { AlertCircle, Upload } from "lucide-react";
+import { AlertCircle, Lock, Upload } from "lucide-react";
 
 import type {
   AgentSnapshotImportPreview,
@@ -72,7 +72,7 @@ export function AgentSnapshotImportDialog({
     <Dialog onOpenChange={onOpenChange} open={open}>
       <DialogContent
         aria-describedby={undefined}
-        className="max-w-md"
+        className="max-h-[85vh] max-w-2xl overflow-y-auto"
         data-testid="agent-snapshot-import-dialog"
         showCloseButton={false}
       >
@@ -141,7 +141,7 @@ export function AgentSnapshotImportDialog({
 
 // ── Preview body ──────────────────────────────────────────────────────────────
 
-function PreviewBody({
+export function PreviewBody({
   preview,
   hasMemory,
   memoryLevelLabel,
@@ -159,19 +159,49 @@ function PreviewBody({
       {/* Agent identity */}
       <div className="space-y-1">
         <p className="text-sm font-medium">{preview.displayName}</p>
-        {preview.systemPrompt ? (
-          <p className="line-clamp-3 text-xs text-muted-foreground">
-            {preview.systemPrompt}
-          </p>
-        ) : null}
       </div>
 
+      {/* Locked-card provenance: this file was encrypted to this machine's
+          keys and has been unlocked for review. */}
+      {preview.locked ? (
+        <div
+          className="flex items-start gap-2 rounded-md border border-border bg-muted/40 px-3 py-2 text-sm"
+          data-testid="agent-snapshot-import-locked-notice"
+        >
+          <Lock className="mt-0.5 h-4 w-4 shrink-0" />
+          <p>
+            This card is <strong>locked</strong> — its agent is encrypted to the
+            original owner and agent keys. Your keys unlocked it; the full
+            decrypted payload is shown below.
+          </p>
+        </div>
+      ) : null}
+
       <AgentDefinitionMetadata
         isBuiltIn={preview.isBuiltIn}
         model={preview.model}
         runtime={preview.runtime}
       />
 
+      {/* Portable behavior — never hide executable configuration behind a summary. */}
+      <section
+        className="space-y-2 rounded-md border border-border p-3"
+        data-testid="agent-snapshot-import-behavior"
+      >
+        <div>
+          <p className="text-sm font-medium">Agent instructions</p>
+          <p className="text-xs text-muted-foreground">
+            Review the instructions this agent will follow after import.
+          </p>
+        </div>
+        <pre
+          className="max-h-48 overflow-auto whitespace-pre-wrap break-words rounded bg-muted/60 p-3 text-xs"
+          data-testid="agent-snapshot-import-system-prompt"
+        >
+          {preview.systemPrompt || "No system prompt included."}
+        </pre>
+      </section>
+
       <p className="text-sm text-muted-foreground">
         A new agent will be created with a fresh keypair. The imported agent is
         independent of the source — identity never travels.
@@ -211,9 +241,19 @@ function PreviewBody({
             {preview.sourceAllowlistCount === 1 ? "y" : "ies"})
           </p>
           <p className="text-xs text-muted-foreground">
-            This snapshot includes a source-environment pubkey allowlist. Those
-            identities are not meaningful on your relay.
+            This snapshot includes source-environment pubkeys. Review every key
+            before choosing Keep; Clear is safer when you do not recognize them.
           </p>
+          <ul
+            className="max-h-28 space-y-1 overflow-y-auto rounded bg-muted/60 p-2 font-mono text-xs"
+            data-testid="agent-snapshot-import-allowlist-values"
+          >
+            {preview.sourceAllowlist.map((pubkey) => (
+              <li className="break-all" key={pubkey}>
+                {pubkey}
+              </li>
+            ))}
+          </ul>
           <div className="flex flex-col gap-1.5">
             <label className="flex cursor-pointer items-center gap-2">
               <input
@@ -242,6 +282,22 @@ function PreviewBody({
           </div>
         </div>
       ) : null}
+
+      <details
+        className="rounded-md border border-border p-3"
+        data-testid="agent-snapshot-import-manifest"
+      >
+        <summary className="cursor-pointer text-sm font-medium">
+          Full embedded manifest
+        </summary>
+        <p className="mt-2 text-xs text-muted-foreground">
+          This is the complete portable payload decoded from the file. Secrets,
+          credentials, and source identity are not part of the snapshot format.
+        </p>
+        <pre className="mt-2 max-h-64 overflow-auto whitespace-pre-wrap break-words rounded bg-muted/60 p-3 text-xs">
+          {preview.manifestJson}
+        </pre>
+      </details>
     </div>
   );
 }
diff --git a/desktop/src/features/agents/ui/AgentsView.tsx b/desktop/src/features/agents/ui/AgentsView.tsx
index 6e55f92dfe..3d1673c365 100644
--- a/desktop/src/features/agents/ui/AgentsView.tsx
+++ b/desktop/src/features/agents/ui/AgentsView.tsx
@@ -1,5 +1,5 @@
 import * as React from "react";
-import { OctagonX, Settings2 } from "lucide-react";
+import { EllipsisVertical, OctagonX, Settings2 } from "lucide-react";
 import {
   consumePendingSnapshotImport,
   subscribeSnapshotImport,
@@ -20,10 +20,7 @@ import { SecretRevealDialog } from "./SecretRevealDialog";
 import { TeamDeleteDialog } from "./TeamDeleteDialog";
 import { TeamDialog } from "./TeamDialog";
 import { TeamsSection } from "./TeamsSection";
-import {
-  AGENT_CARD_GRID_COLUMNS_CLASS,
-  UnifiedAgentsSection,
-} from "./UnifiedAgentsSection";
+import { UnifiedAgentsSection } from "./UnifiedAgentsSection";
 import { useManagedAgentActions } from "./useManagedAgentActions";
 import { usePersonaActions } from "./usePersonaActions";
 import { useTeamActions } from "./useTeamActions";
@@ -32,6 +29,12 @@ import { useBakedBuildEnvQuery } from "@/features/agents/hooks";
 import { isManagedAgentActive } from "@/features/agents/lib/managedAgentControlActions";
 import { useGlobalAgentConfig } from "@/features/agents/useGlobalAgentConfig";
 import { Button } from "@/shared/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/shared/ui/dropdown-menu";
 import { PageHeader } from "@/shared/ui/PageHeader";
 import { getInheritedAgentDefaults } from "./bakedEnvHelpers";
 
@@ -44,6 +47,8 @@ export function AgentsView() {
   const personas = usePersonaActions();
   const teamImportInputRef = React.useRef<HTMLInputElement | null>(null);
   const aiDefaultsTriggerRef = React.useRef<HTMLButtonElement>(null);
+  const fullAiDefaultsTriggerRef = React.useRef<HTMLButtonElement>(null);
+  const compactActionsTriggerRef = React.useRef<HTMLButtonElement>(null);
   const [isAiDefaultsOpen, setIsAiDefaultsOpen] = React.useState(false);
   // Exclusivity: create never sets `personaDialogState` (edit/dup/import do),
   // so the create-mode and definition-edit AgentDialog mounts never coexist.
@@ -53,6 +58,22 @@ export function AgentsView() {
     personas.prepareCreate();
     setIsCreateDialogOpen(true);
   }
+
+  function openAiDefaults(trigger: HTMLButtonElement | null) {
+    aiDefaultsTriggerRef.current = trigger;
+    setIsAiDefaultsOpen(true);
+  }
+
+  function setAiDefaultsDialogOpen(open: boolean) {
+    if (!open) {
+      aiDefaultsTriggerRef.current =
+        fullAiDefaultsTriggerRef.current?.offsetParent !== null
+          ? fullAiDefaultsTriggerRef.current
+          : compactActionsTriggerRef.current;
+    }
+    setIsAiDefaultsOpen(open);
+  }
+
   const teamActions = useTeamActions(
     {
       setActionNoticeMessage: agents.setActionNoticeMessage,
@@ -113,43 +134,84 @@ export function AgentsView() {
     <>
       <div className="flex-1 overflow-y-auto overflow-x-hidden overscroll-contain px-4 py-7 sm:px-6 sm:py-8">
         <div
-          className={`mx-auto grid w-full max-w-6xl ${AGENT_CARD_GRID_COLUMNS_CLASS} justify-start gap-x-3 gap-y-8`}
+          className="mx-auto w-full max-w-6xl space-y-8 [container-type:inline-size]"
+          data-testid="agents-page-content"
         >
           <PageHeader
-            className="col-[1/-1]"
             action={
-              <div className="flex flex-wrap justify-end gap-2">
-                <Button
-                  data-testid="agent-defaults-button"
-                  ref={aiDefaultsTriggerRef}
-                  onClick={() => setIsAiDefaultsOpen(true)}
-                  size="sm"
-                  variant="outline"
-                >
-                  <Settings2 />
-                  {hasSavedAgentDefaults
-                    ? "Agent defaults"
-                    : "Set agent defaults"}
-                </Button>
-                {runningAgentCount > 0 ? (
+              <>
+                <div className="flex flex-wrap justify-end gap-2 [@container(max-width:40rem)]:hidden">
                   <Button
-                    disabled={isActionPending}
-                    onClick={() => {
-                      void agents.handleBulkStopRunning();
-                    }}
+                    data-testid="agent-defaults-button"
+                    ref={fullAiDefaultsTriggerRef}
+                    onClick={(event) => openAiDefaults(event.currentTarget)}
                     size="sm"
                     variant="outline"
                   >
-                    <OctagonX />
-                    Stop running agents
+                    <Settings2 />
+                    {hasSavedAgentDefaults
+                      ? "Agent defaults"
+                      : "Set agent defaults"}
                   </Button>
-                ) : null}
-              </div>
+                  {runningAgentCount > 0 ? (
+                    <Button
+                      disabled={isActionPending}
+                      onClick={() => {
+                        void agents.handleBulkStopRunning();
+                      }}
+                      size="sm"
+                      variant="outline"
+                    >
+                      <OctagonX />
+                      Stop running agents
+                    </Button>
+                  ) : null}
+                </div>
+
+                <DropdownMenu modal={false}>
+                  <DropdownMenuTrigger asChild>
+                    <Button
+                      aria-label="Agent actions"
+                      className="hidden [@container(max-width:40rem)]:inline-flex"
+                      data-testid="agent-actions-menu-trigger"
+                      ref={compactActionsTriggerRef}
+                      size="icon"
+                      type="button"
+                      variant="outline"
+                    >
+                      <EllipsisVertical />
+                    </Button>
+                  </DropdownMenuTrigger>
+                  <DropdownMenuContent align="end">
+                    <DropdownMenuItem
+                      onSelect={() => {
+                        openAiDefaults(compactActionsTriggerRef.current);
+                      }}
+                    >
+                      <Settings2 />
+                      {hasSavedAgentDefaults
+                        ? "Agent defaults"
+                        : "Set agent defaults"}
+                    </DropdownMenuItem>
+                    {runningAgentCount > 0 ? (
+                      <DropdownMenuItem
+                        disabled={isActionPending}
+                        onSelect={() => {
+                          void agents.handleBulkStopRunning();
+                        }}
+                      >
+                        <OctagonX />
+                        Stop running agents
+                      </DropdownMenuItem>
+                    ) : null}
+                  </DropdownMenuContent>
+                </DropdownMenu>
+              </>
             }
             description="Set up and manage your agents."
             title="Agents"
           />
-          <div className="col-[1/-1] flex flex-col gap-8">
+          <div className="flex flex-col gap-8">
             <UnifiedAgentsSection
               defaultModel={inheritedDefaults.model.value}
               actionErrorMessage={agents.actionErrorMessage}
@@ -238,7 +300,7 @@ export function AgentsView() {
       </div>
 
       <AgentDefaultsDialog
-        onOpenChange={setIsAiDefaultsOpen}
+        onOpenChange={setAiDefaultsDialogOpen}
         open={isAiDefaultsOpen}
         returnFocusRef={aiDefaultsTriggerRef}
       />
@@ -358,6 +420,7 @@ export function AgentsView() {
           )}
           isPending={personas.isPending}
           linkedAgentPubkey={personas.personaToShare.linkedAgentPubkey}
+          effectiveAvatarUrl={personas.personaToShare.effectiveAvatarUrl}
           onCatalogShareLevelChange={(shareLevel) => {
             const shareTarget = personas.personaToShare;
             if (!shareTarget) return;
@@ -392,6 +455,7 @@ export function AgentsView() {
               personas.handleExportSnapshot(
                 personas.personaToExportSnapshot.persona,
                 personas.personaToExportSnapshot.linkedAgentPubkey,
+                personas.personaToExportSnapshot.effectiveAvatarUrl,
                 memoryLevel,
                 format,
               );
diff --git a/desktop/src/features/agents/ui/CardMintComposerChip.tsx b/desktop/src/features/agents/ui/CardMintComposerChip.tsx
new file mode 100644
index 0000000000..158ec9a07b
--- /dev/null
+++ b/desktop/src/features/agents/ui/CardMintComposerChip.tsx
@@ -0,0 +1,78 @@
+import { Loader2, Sparkles, X } from "lucide-react";
+
+import {
+  dismissCardMintJob,
+  useCardMintJobs,
+  viewMintedCardJob,
+} from "@/features/agents/cardMintStore";
+import { Shimmer } from "@/shared/ui/Shimmer";
+
+/**
+ * Composer-rail status for background card mints: a live "Minting card…"
+ * row while the ~2–3 minute mint runs, then a clickable "card is ready" row
+ * (opens the viewer) or a dismissible failure row. Rendered inside the
+ * composer dock's bottom activity rail next to agent-working/typing rows.
+ */
+export function CardMintComposerChip() {
+  const jobs = useCardMintJobs();
+  if (jobs.length === 0) return null;
+
+  return (
+    <div
+      className="flex min-w-0 flex-col justify-center gap-0.5"
+      data-testid="card-mint-composer-chip"
+    >
+      {jobs.map((job) => {
+        if (job.phase === "minting") {
+          return (
+            <span
+              className="flex min-w-0 items-center gap-1.5 text-xs text-muted-foreground"
+              data-testid="card-mint-status-minting"
+              key={job.jobId}
+            >
+              <Loader2 className="h-3.5 w-3.5 shrink-0 animate-spin opacity-70" />
+              <Shimmer className="-my-px truncate py-px">
+                {`Minting ${job.input.agentName}’s card… (takes a few minutes)`}
+              </Shimmer>
+            </span>
+          );
+        }
+        if (job.phase === "done") {
+          return (
+            <button
+              className="flex min-w-0 items-center gap-1.5 text-xs text-primary hover:underline"
+              data-testid="card-mint-status-done"
+              key={job.jobId}
+              onClick={() => viewMintedCardJob(job.jobId)}
+              type="button"
+            >
+              <Sparkles className="h-3.5 w-3.5 shrink-0" />
+              <span className="truncate">
+                {`${job.input.agentName}’s card is ready — view it`}
+              </span>
+            </button>
+          );
+        }
+        return (
+          <span
+            className="flex min-w-0 items-center gap-1.5 text-xs text-destructive"
+            data-testid="card-mint-status-error"
+            key={job.jobId}
+          >
+            <span className="truncate">
+              {`Minting ${job.input.agentName}’s card failed`}
+            </span>
+            <button
+              aria-label="Dismiss failed mint"
+              className="shrink-0 opacity-70 hover:opacity-100"
+              onClick={() => dismissCardMintJob(job.jobId)}
+              type="button"
+            >
+              <X className="h-3.5 w-3.5" />
+            </button>
+          </span>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/desktop/src/features/agents/ui/PersonaCatalogDialog.tsx b/desktop/src/features/agents/ui/PersonaCatalogDialog.tsx
index ba76d6e4ed..e1ec946092 100644
--- a/desktop/src/features/agents/ui/PersonaCatalogDialog.tsx
+++ b/desktop/src/features/agents/ui/PersonaCatalogDialog.tsx
@@ -2,6 +2,7 @@ import * as React from "react";
 
 import { isCatalogPersonaSelected } from "@/features/agents/lib/catalog";
 import { isCatalogPersona } from "@/features/agents/lib/personaCatalogRelay";
+import { useUsersBatchQuery } from "@/features/profile/hooks";
 import { ProfileAvatar } from "@/features/profile/ui/ProfileAvatar";
 import type { AgentPersona } from "@/shared/api/types";
 import { useFeedbackToasts } from "@/shared/hooks/useToastEffect";
@@ -276,7 +277,42 @@ function PersonaCatalogChooser({
   );
 }
 
+/**
+ * Derives the "Added by" label for a catalog entry from a resolved profile
+ * summary. Prefers `displayName`, falls back to `name`, then to the default
+ * "Community member" string when both are absent, null, or whitespace-only.
+ */
+export function resolveCatalogOwnerLabel(
+  summary:
+    | { displayName?: string | null; name?: string | null }
+    | null
+    | undefined,
+): string {
+  return (
+    summary?.displayName?.trim() || summary?.name?.trim() || "Community member"
+  );
+}
+
 function PersonaCatalogDetail({ persona }: { persona: AgentPersona }) {
+  const isCommunityEntry =
+    isCatalogPersona(persona) && !persona.catalogSource.isOwn;
+  const ownerPubkey = isCommunityEntry
+    ? persona.catalogSource.ownerPubkey
+    : undefined;
+  const ownerBatchQuery = useUsersBatchQuery(ownerPubkey ? [ownerPubkey] : [], {
+    enabled: !!ownerPubkey,
+  });
+
+  let addedByLabel: string;
+  if (!isCommunityEntry) {
+    addedByLabel = "You";
+  } else {
+    const summary = ownerPubkey
+      ? ownerBatchQuery.data?.profiles[ownerPubkey.toLowerCase()]
+      : undefined;
+    addedByLabel = resolveCatalogOwnerLabel(summary);
+  }
+
   return (
     <div className="w-full min-w-0 max-w-full space-y-6 overflow-x-hidden">
       <div className="flex items-center gap-3">
@@ -290,14 +326,7 @@ function PersonaCatalogDetail({ persona }: { persona: AgentPersona }) {
             {persona.displayName}
           </h3>
           {persona.isBuiltIn ? null : (
-            <PersonaAddedBy
-              className="mt-0.5"
-              label={
-                isCatalogPersona(persona) && !persona.catalogSource.isOwn
-                  ? "Community member"
-                  : "You"
-              }
-            />
+            <PersonaAddedBy className="mt-0.5" label={addedByLabel} />
           )}
         </div>
       </div>
diff --git a/desktop/src/features/agents/ui/PersonaShareDialog.tsx b/desktop/src/features/agents/ui/PersonaShareDialog.tsx
index af45e8f071..5cf4f9ea3b 100644
--- a/desktop/src/features/agents/ui/PersonaShareDialog.tsx
+++ b/desktop/src/features/agents/ui/PersonaShareDialog.tsx
@@ -37,10 +37,13 @@ import {
   Dialog,
   DialogClose,
   DialogContent,
+  DialogDescription,
   DialogHeader,
   DialogTitle,
 } from "@/shared/ui/dialog";
+import { Separator } from "@/shared/ui/separator";
 import { Spinner } from "@/shared/ui/spinner";
+import { Switch } from "@/shared/ui/switch";
 
 import {
   formatShareRecipientName,
@@ -54,6 +57,7 @@ type PersonaShareDialogProps = {
   catalogShareLevel: CatalogPersonaShareLevel;
   isPending: boolean;
   linkedAgentPubkey: string | null;
+  effectiveAvatarUrl: string | null;
   onCatalogShareLevelChange: (shareLevel: CatalogPersonaShareLevel) => void;
   onExport: () => void;
   onOpenChange: (open: boolean) => void;
@@ -62,7 +66,7 @@ type PersonaShareDialogProps = {
 };
 
 type SnapshotShareDialogProps = {
-  afterLink?: React.ReactNode;
+  beforeExport?: React.ReactNode;
   displayName: string;
   encodeSnapshot: (
     memoryLevel: SnapshotMemoryLevel,
@@ -197,7 +201,6 @@ function MemoryShareConfirmation({
 function ShareLevelControl({
   ariaLabel,
   disabled,
-  hasMemoryOptions,
   testId,
   value,
   options,
@@ -205,27 +208,11 @@ function ShareLevelControl({
 }: {
   ariaLabel: string;
   disabled: boolean;
-  hasMemoryOptions: boolean;
   testId: string;
   value: SnapshotMemoryLevel;
   options: { value: SnapshotMemoryLevel; label: string }[];
   onChange: (level: SnapshotMemoryLevel) => void;
 }) {
-  if (!hasMemoryOptions) {
-    // Nothing to choose from, so there is no dropdown to open. State the
-    // outcome rather than naming the sole option: the memory-level labels
-    // ("Agent only", "+ core memory", …) are comparative and only make sense
-    // when the alternatives are actually offered.
-    return (
-      <span
-        className="inline-flex h-8 w-auto shrink-0 items-center justify-end px-2 text-sm text-muted-foreground"
-        data-testid={testId}
-      >
-        No memories included
-      </span>
-    );
-  }
-
   return (
     <SnapshotOptionMenu
       ariaLabel={ariaLabel}
@@ -239,7 +226,7 @@ function ShareLevelControl({
 }
 
 export function SnapshotShareDialog({
-  afterLink,
+  beforeExport,
   displayName,
   encodeSnapshot,
   hasMemoryOptions,
@@ -451,7 +438,6 @@ export function SnapshotShareDialog({
   return (
     <Dialog onOpenChange={handleDialogOpenChange} open={open}>
       <DialogContent
-        aria-describedby={undefined}
         className="max-w-xl gap-3 bg-transparent p-0 shadow-none"
         data-testid={`${testIdPrefix}-dialog`}
         showCloseButton={false}
@@ -460,10 +446,16 @@ export function SnapshotShareDialog({
           className="relative rounded-2xl bg-background p-6 pb-4 shadow-2xl"
           data-testid={`${testIdPrefix}-main-card`}
         >
-          <DialogHeader className="space-y-0">
+          <DialogHeader>
             <DialogTitle className="min-w-0 truncate pr-10">
               Share {displayName}
             </DialogTitle>
+            <DialogDescription
+              data-testid={`${testIdPrefix}-share-description`}
+            >
+              Anyone you share this {itemLabel} with will receive a copy they
+              can add and use. Changes you make later won’t sync.
+            </DialogDescription>
           </DialogHeader>
           <DialogClose
             className="absolute right-4 top-4 flex h-8 w-8 shrink-0 items-center justify-center rounded-md text-muted-foreground transition-colors duration-150 ease-out hover:bg-accent hover:text-accent-foreground focus:outline-hidden focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-100"
@@ -520,34 +512,44 @@ export function SnapshotShareDialog({
                   ) : null}
                 </AnimatePresence>
               </div>
-              <p
-                className="text-xs text-secondary-foreground/75"
-                data-testid={`${testIdPrefix}-send-description`}
-              >
-                They’ll receive a copy they can add and use. Changes you make
-                later won’t sync.
-              </p>
             </div>
 
+            {hasMemoryOptions ? (
+              <section
+                className="space-y-2"
+                data-testid={`${testIdPrefix}-link-settings`}
+              >
+                <h3 className="text-xs font-medium text-secondary-foreground/75">
+                  Share settings
+                </h3>
+                <div
+                  className="flex items-center gap-3"
+                  data-testid={`${testIdPrefix}-share-level-row`}
+                >
+                  <h4 className="min-w-0 flex-1 text-sm font-medium">
+                    What’s included
+                  </h4>
+                  <ShareLevelControl
+                    ariaLabel="What to include"
+                    disabled={isInterfacePending}
+                    onChange={setShareLevel}
+                    options={shareLevels}
+                    testId={`${testIdPrefix}-share-level`}
+                    value={shareLevel}
+                  />
+                </div>
+              </section>
+            ) : null}
+
+            <Separator
+              className="bg-input/40"
+              data-testid={`${testIdPrefix}-link-divider`}
+            />
+
             <div
-              className="flex items-center gap-3 pt-2"
+              className="flex justify-end"
               data-testid={`${testIdPrefix}-link-row`}
             >
-              <span
-                className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-muted text-muted-foreground"
-                data-testid={`${testIdPrefix}-link-icon`}
-              >
-                <Link2 className="h-4 w-4" />
-              </span>
-              <div
-                className="min-w-0 flex-1"
-                data-testid={`${testIdPrefix}-link-copy`}
-              >
-                <h3 className="text-sm font-medium">Share with a link</h3>
-                <p className="text-xs text-secondary-foreground/75">
-                  Anyone with the link can add and use a copy.
-                </p>
-              </div>
               <Button
                 asChild
                 className="shrink-0 border-border shadow-none disabled:opacity-100"
@@ -621,24 +623,6 @@ export function SnapshotShareDialog({
               </Button>
             </div>
 
-            <div
-              className="flex items-center gap-3"
-              data-testid={`${testIdPrefix}-share-level-row`}
-            >
-              <h3 className="min-w-0 flex-1 text-sm font-medium">
-                What’s included
-              </h3>
-              <ShareLevelControl
-                ariaLabel="What to include"
-                disabled={isInterfacePending}
-                hasMemoryOptions={hasMemoryOptions}
-                onChange={setShareLevel}
-                options={shareLevels}
-                testId={`${testIdPrefix}-share-level`}
-                value={shareLevel}
-              />
-            </div>
-
             <AnimatePresence initial={false}>
               {showMemoryWarning ? (
                 <motion.div
@@ -663,10 +647,9 @@ export function SnapshotShareDialog({
                 </motion.div>
               ) : null}
             </AnimatePresence>
-
-            {afterLink}
           </div>
         </div>
+        {beforeExport}
         <button
           className="relative flex min-h-14 w-full items-center gap-3 rounded-2xl bg-background px-5 py-4 text-left text-sm font-medium shadow-2xl outline-hidden transition-colors hover:bg-muted focus-visible:bg-muted disabled:cursor-default disabled:opacity-100"
           data-testid={`${testIdPrefix}-export`}
@@ -694,6 +677,7 @@ export function PersonaShareDialog({
   catalogShareLevel,
   isPending,
   linkedAgentPubkey,
+  effectiveAvatarUrl,
   onCatalogShareLevelChange,
   onExport,
   onOpenChange,
@@ -701,13 +685,6 @@ export function PersonaShareDialog({
   persona,
 }: PersonaShareDialogProps) {
   const encodeSnapshotMutation = useEncodeAgentSnapshotForSendMutation();
-  const catalogShareLevels = React.useMemo(
-    () => [
-      { value: "not-shared", label: "Not shared" },
-      { value: "none", label: "Shared" },
-    ],
-    [],
-  );
   const encodeSnapshot = React.useCallback(
     async (memoryLevel: SnapshotMemoryLevel) =>
       encodeSnapshotMutation.mutateAsync({
@@ -715,27 +692,25 @@ export function PersonaShareDialog({
         memoryLevel: linkedAgentPubkey ? memoryLevel : "none",
         format: "png",
         memorySourcePubkey: linkedAgentPubkey,
-        avatarPngDataUrl: await resolveSnapshotAvatarPng(persona.avatarUrl),
+        avatarPngDataUrl: await resolveSnapshotAvatarPng(effectiveAvatarUrl),
       }),
     [
       encodeSnapshotMutation.mutateAsync,
+      effectiveAvatarUrl,
       linkedAgentPubkey,
-      persona.avatarUrl,
       persona.id,
     ],
   );
 
   return (
     <SnapshotShareDialog
-      afterLink={
+      beforeExport={
         persona.isBuiltIn ? null : (
           <section
-            className="flex min-h-16 w-full items-center gap-3"
+            className="relative flex min-h-16 w-full items-center gap-3 rounded-2xl bg-background px-5 py-4 shadow-2xl"
             data-testid="persona-share-catalog"
           >
-            <span className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-muted text-muted-foreground">
-              <BookUser className="h-4 w-4" />
-            </span>
+            <BookUser className="h-4 w-4 shrink-0 text-muted-foreground" />
             <div className="min-w-0 flex-1">
               <h3 className="text-sm font-medium">Share to catalog</h3>
               <p className="text-xs text-secondary-foreground/75">
@@ -744,20 +719,16 @@ export function PersonaShareDialog({
                 included.
               </p>
             </div>
-            <div className="flex shrink-0 items-center">
-              <SnapshotOptionMenu
-                ariaLabel="What to share in the catalog"
-                disabled={isPending}
-                onValueChange={(nextValue) =>
-                  onCatalogShareLevelChange(
-                    nextValue as CatalogPersonaShareLevel,
-                  )
-                }
-                options={catalogShareLevels}
-                testId="persona-share-catalog-access"
-                value={catalogShareLevel}
-              />
-            </div>
+            <Switch
+              aria-label="Share to catalog"
+              checked={catalogShareLevel !== "not-shared"}
+              data-testid="persona-share-catalog-access"
+              disabled={isPending}
+              onCheckedChange={(checked) =>
+                onCatalogShareLevelChange(checked ? "none" : "not-shared")
+              }
+              style={{ cursor: "default" }}
+            />
           </section>
         )
       }
diff --git a/desktop/src/features/agents/ui/ProviderConfigFields.test.mjs b/desktop/src/features/agents/ui/ProviderConfigFields.test.mjs
new file mode 100644
index 0000000000..0dfd80d444
--- /dev/null
+++ b/desktop/src/features/agents/ui/ProviderConfigFields.test.mjs
@@ -0,0 +1,31 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { coerceConfigValues } from "./ProviderConfigFields.tsx";
+
+const schema = {
+  properties: {
+    inactivity_seconds: { type: "integer" },
+    threshold: { type: "number" },
+    label: { type: "string" },
+  },
+};
+
+describe("coerceConfigValues", () => {
+  it("omits cleared numeric fields without losing explicit zero", () => {
+    assert.deepEqual(
+      coerceConfigValues(
+        { inactivity_seconds: "", threshold: "0", label: "" },
+        schema,
+      ),
+      { threshold: 0, label: "" },
+    );
+  });
+
+  it("preserves nonempty invalid numeric input for provider validation", () => {
+    assert.deepEqual(
+      coerceConfigValues({ inactivity_seconds: "not-a-number" }, schema),
+      { inactivity_seconds: "not-a-number" },
+    );
+  });
+});
diff --git a/desktop/src/features/agents/ui/ProviderConfigFields.tsx b/desktop/src/features/agents/ui/ProviderConfigFields.tsx
index e922dd9c1a..031b0b7277 100644
--- a/desktop/src/features/agents/ui/ProviderConfigFields.tsx
+++ b/desktop/src/features/agents/ui/ProviderConfigFields.tsx
@@ -14,7 +14,8 @@ export function coerceConfigValues(
   for (const [key, value] of Object.entries(config)) {
     const prop = properties[key] as Record<string, unknown> | undefined;
     const schemaType = prop?.type;
-    if ((schemaType === "integer" || schemaType === "number") && value !== "") {
+    if (schemaType === "integer" || schemaType === "number") {
+      if (value === "") continue;
       const num = Number(value);
       result[key] = Number.isNaN(num) ? value : num;
     } else if (schemaType === "boolean") {
diff --git a/desktop/src/features/agents/ui/RespondToField.tsx b/desktop/src/features/agents/ui/RespondToField.tsx
index d9773ad681..b32b9e0983 100644
--- a/desktop/src/features/agents/ui/RespondToField.tsx
+++ b/desktop/src/features/agents/ui/RespondToField.tsx
@@ -1,5 +1,5 @@
 import * as React from "react";
-import { ChevronDown, Search, X } from "lucide-react";
+import { AlertTriangle, ChevronDown, Search, X } from "lucide-react";
 import {
   mergeAllowlist,
   parsePubkeyInput,
@@ -13,6 +13,11 @@ import { cn } from "@/shared/lib/cn";
 import { Input } from "@/shared/ui/input";
 import { Textarea } from "@/shared/ui/textarea";
 import { UserAvatar } from "@/shared/ui/UserAvatar";
+import {
+  type AgentRunLocation,
+  agentAccessWarningText,
+} from "@/features/agents/lib/agentAccessWarning";
+import { useAgentRunLocation } from "./AgentRunLocationContext";
 import { PersonaDropdownField } from "./PersonaDropdownField";
 import type { PersonaDropdownOption } from "./agentConfigOptions";
 
@@ -20,14 +25,25 @@ import type { PersonaDropdownOption } from "./agentConfigOptions";
  * Inbound author gate UI for create/edit agent dialogs.
  *
  * Dropdown:
- *   - Owner only  (default; matches `buzz-acp --respond-to=owner-only`)
- *   - Anyone      (`--respond-to=anyone` — fully open bot)
- *   - Allowlist   (`--respond-to=allowlist`, plus the chip list as
- *                  `--respond-to-allowlist`)
+ *   - Only me        (default; maps to `buzz-acp --respond-to=owner-only`)
+ *   - Anyone         (`--respond-to=anyone` — fully open agent)
+ *   - Selected people (`--respond-to=allowlist`, plus the selected pubkeys as
+ *                     `--respond-to-allowlist`)
  *
  * `nobody` is intentionally not surfaced — it pairs with a heartbeat-only
  * setup that has no meaningful GUI use case.
  *
+ * Anyone and Selected people both share the host's access with someone other
+ * than the owner, so both render the persistent warning; only the audience
+ * phrase differs. It leads with the audience so it reads as a warning rather
+ * than an explanation, and stays one sentence — Only me already owns the line
+ * below the control.
+ *
+ * Which machine and stakes it names follow the optional `runLocation` prop, and
+ * an unknown location falls back to the local wording rather than hedging with
+ * "computer or server" — see `lib/agentAccessWarning.ts` for the copy and the
+ * reasoning.
+ *
  * Validation is duplicated lightly here for inline UX feedback only; the
  * authoritative validator is `validate_respond_to_allowlist` in
  * `desktop/src-tauri/src/managed_agents/types.rs`.
@@ -53,7 +69,7 @@ function formatSearchUserSecondary(user: UserSearchResult) {
 const RESPOND_TO_OPTIONS: PersonaDropdownOption[] = [
   { label: "Only me (default)", value: "owner-only" },
   { label: "Anyone", value: "anyone" },
-  { label: "Allowlist", value: "allowlist" },
+  { label: "Selected people", value: "allowlist" },
 ];
 
 export function CreateAgentRespondToField({
@@ -64,6 +80,7 @@ export function CreateAgentRespondToField({
   ownerPubkey,
   disabled,
   variant,
+  runLocation,
 }: {
   mode: RespondToMode;
   allowlist: string[];
@@ -78,6 +95,12 @@ export function CreateAgentRespondToField({
   disabled?: boolean;
   /** When "persona", uses PersonaDropdownField styling to match the persona dialog. */
   variant?: "default" | "persona";
+  /**
+   * Where the agent's process runs, when the surface can tell. Omit or pass
+   * `null` when it can't — the warning then uses the same "your computer"
+   * wording as a local agent rather than hedging. Never synthesize a value.
+   */
+  runLocation?: AgentRunLocation | null;
 }) {
   const [query, setQuery] = React.useState("");
   const [isDirectEntryOpen, setIsDirectEntryOpen] = React.useState(false);
@@ -132,6 +155,33 @@ export function CreateAgentRespondToField({
 
   const isPersonaVariant = variant === "persona";
 
+  // An explicit prop wins; otherwise inherit from the dialog subtree. Surfaces
+  // inside AgentDialog get it from context (see AgentRunLocationContext for
+  // why), standalone ones like EditRespondToDialog pass the prop.
+  const inheritedRunLocation = useAgentRunLocation();
+  const warningText = agentAccessWarningText(
+    mode,
+    runLocation ?? inheritedRunLocation,
+  );
+
+  // Rendered in two positions: directly below the selector for Anyone, but
+  // after the people picker for Selected people, so it never sits between the
+  // user and the selection they came here to make.
+  const accessWarning = warningText ? (
+    <div
+      className="flex items-start gap-2 rounded-xl border border-warning/30 bg-warning-bg px-3 py-2.5"
+      data-testid="agent-access-warning"
+    >
+      <AlertTriangle
+        aria-hidden="true"
+        className="mt-0.5 h-4 w-4 shrink-0 text-warning"
+      />
+      <p aria-live="polite" className="text-xs leading-5 text-warning">
+        {warningText}
+      </p>
+    </div>
+  ) : null;
+
   return (
     <div className="space-y-2" data-testid="agent-respond-to">
       <label
@@ -142,7 +192,7 @@ export function CreateAgentRespondToField({
         }
         htmlFor="agent-respond-to"
       >
-        Who can talk to this agent
+        Who can send instructions
       </label>
       {isPersonaVariant ? (
         <PersonaDropdownField
@@ -162,16 +212,17 @@ export function CreateAgentRespondToField({
           onChange={(e) => onModeChange(e.target.value as RespondToMode)}
           value={mode}
         >
-          <option value="owner-only">Owner only (default)</option>
-          <option value="anyone">Anyone</option>
-          <option value="allowlist">Allowlist</option>
+          {RESPOND_TO_OPTIONS.map((option) => (
+            <option key={option.value} value={option.value}>
+              {option.label}
+            </option>
+          ))}
         </select>
       )}
-      {!isPersonaVariant ? (
+      {mode === "anyone" ? accessWarning : null}
+      {mode === "owner-only" ? (
         <p className="text-xs text-muted-foreground">
-          Controls which Nostr authors the agent listens to (@mentions, DMs,
-          thread replies). The agent&apos;s owner can always shut it down with
-          <span className="font-mono"> !shutdown</span>.
+          Only you can send instructions.
         </p>
       ) : null}
       {mode === "allowlist" ? (
@@ -202,6 +253,7 @@ export function CreateAgentRespondToField({
           variant={isPersonaVariant ? "persona" : "default"}
         />
       ) : null}
+      {mode === "allowlist" ? accessWarning : null}
     </div>
   );
 }
@@ -269,7 +321,7 @@ function AllowlistPicker({
     >
       {!isPersona ? (
         <div className="flex items-center justify-between gap-2">
-          <span className="text-sm font-medium">Allowed pubkeys</span>
+          <span className="text-sm font-medium">Selected people</span>
           <span className="rounded-full bg-background px-2 py-1 text-2xs font-medium leading-none text-muted-foreground">
             {allowlist.length} selected
           </span>
@@ -277,13 +329,13 @@ function AllowlistPicker({
       ) : null}
       {!isPersona && ownerPubkey ? (
         <p className="text-xs text-muted-foreground">
-          Owner (
-          <PubKey pubkey={ownerPubkey} />) is always implicitly allowed by the
-          harness — no need to add it here.
+          You (
+          <PubKey pubkey={ownerPubkey} />) can always use this agent. You
+          don&apos;t need to add yourself.
         </p>
       ) : !isPersona ? (
         <p className="text-xs text-muted-foreground">
-          The agent&apos;s owner is always implicitly allowed.
+          You can always use this agent.
         </p>
       ) : null}
       <div className="rounded-lg border border-border/80 bg-background">
@@ -452,7 +504,7 @@ function AllowlistPicker({
                   onClick={onAddFromPaste}
                   type="button"
                 >
-                  Add to allowlist
+                  Add people
                 </button>
               </div>
             </div>
diff --git a/desktop/src/features/agents/ui/TeamsSection.tsx b/desktop/src/features/agents/ui/TeamsSection.tsx
index f974081b7d..c5a7a078b3 100644
--- a/desktop/src/features/agents/ui/TeamsSection.tsx
+++ b/desktop/src/features/agents/ui/TeamsSection.tsx
@@ -20,9 +20,9 @@ import { IdentityCardSkeleton } from "@/shared/ui/identity-card-skeleton";
 import { SectionHeader } from "@/shared/ui/PageHeader";
 import { CreateIdentityCard } from "./CreateIdentityCard";
 import { TeamIdentityCard } from "./TeamIdentityCard";
+import { IDENTITY_CARD_GRID_CLASS } from "./UnifiedAgentsSection";
 
 const TEAM_CARD_COLUMN_CLASS = "w-full";
-const TEAM_CARD_GRID_CLASS = `${TEAM_CARD_COLUMN_CLASS} mx-auto grid max-w-[996px] grid-cols-[repeat(auto-fill,minmax(220px,240px))] justify-center gap-3`;
 
 type TeamsSectionProps = {
   teams: AgentTeam[];
@@ -63,7 +63,7 @@ export function TeamsSection({
       </div>
 
       {isLoading ? (
-        <div className={TEAM_CARD_GRID_CLASS}>
+        <div className={IDENTITY_CARD_GRID_CLASS}>
           <IdentityCardSkeleton
             footerSubtitleWidthClass="w-14"
             footerTitleWidthClass="w-24"
@@ -83,7 +83,7 @@ export function TeamsSection({
       ) : null}
 
       {!isLoading ? (
-        <div className={TEAM_CARD_GRID_CLASS}>
+        <div className={IDENTITY_CARD_GRID_CLASS}>
           {teams.map((team) => {
             const resolution = resolveTeamPersonas(team, personas);
             const missingPersonaCount = resolution.missingPersonaCount;
diff --git a/desktop/src/features/agents/ui/UnifiedAgentsSection.tsx b/desktop/src/features/agents/ui/UnifiedAgentsSection.tsx
index 34f9f9819f..19a5ef1171 100644
--- a/desktop/src/features/agents/ui/UnifiedAgentsSection.tsx
+++ b/desktop/src/features/agents/ui/UnifiedAgentsSection.tsx
@@ -58,6 +58,7 @@ type UnifiedAgentsSectionProps = {
   onSharePersona: (
     persona: AgentPersona,
     linkedAgent: ManagedAgent | undefined,
+    effectiveAvatarUrl: string | null,
   ) => void;
   onDeactivatePersona: (persona: AgentPersona) => void;
   onDeletePersona: (persona: AgentPersona) => void;
@@ -67,7 +68,7 @@ type UnifiedAgentsSectionProps = {
 const AGENT_CARD_COLUMN_CLASS = "w-full";
 export const AGENT_CARD_GRID_COLUMNS_CLASS =
   "grid-cols-[repeat(auto-fill,minmax(220px,240px))]";
-const AGENT_CARD_GRID_CLASS = `${AGENT_CARD_COLUMN_CLASS} ${AGENT_CARD_GRID_COLUMNS_CLASS} grid justify-start gap-3`;
+export const IDENTITY_CARD_GRID_CLASS = `${AGENT_CARD_COLUMN_CLASS} ${AGENT_CARD_GRID_COLUMNS_CLASS} grid justify-start gap-3 [@container(max-width:40rem)]:justify-center`;
 
 export function UnifiedAgentsSection(props: UnifiedAgentsSectionProps) {
   const {
@@ -152,14 +153,16 @@ export function UnifiedAgentsSection(props: UnifiedAgentsSectionProps) {
 
       {!isLoading ? (
         <div className="space-y-3" data-testid="unified-agents-groups">
-          <div className={AGENT_CARD_GRID_CLASS}>
+          <div className={IDENTITY_CARD_GRID_CLASS}>
             {groups.map((group) => {
               const profileAgent = pickProfileAgent(group.agents);
               return (
                 <AgentPersonaCard
-                  actions={
+                  actions={(effectiveAvatarUrl, isEffectiveAvatarLoading) => (
                     <PersonaActionsMenu
-                      isActionPending={isActionPending}
+                      isActionPending={
+                        isActionPending || isEffectiveAvatarLoading
+                      }
                       isPending={isPersonasPending}
                       persona={group.persona}
                       linkedAgent={profileAgent}
@@ -167,9 +170,11 @@ export function UnifiedAgentsSection(props: UnifiedAgentsSectionProps) {
                       onDelete={onDeletePersona}
                       onDuplicate={onDuplicatePersona}
                       onEdit={onEditPersona}
-                      onShare={onSharePersona}
+                      onShare={(persona, linkedAgent) =>
+                        onSharePersona(persona, linkedAgent, effectiveAvatarUrl)
+                      }
                     />
-                  }
+                  )}
                   agent={profileAgent}
                   defaultModel={defaultModel}
                   key={group.persona.id}
@@ -250,7 +255,10 @@ function AgentPersonaCard({
   onStartAgent,
   onStartPersona,
 }: {
-  actions?: React.ReactNode;
+  actions?: (
+    effectiveAvatarUrl: string | null,
+    isEffectiveAvatarLoading: boolean,
+  ) => React.ReactNode;
   agent: ManagedAgent | undefined;
   defaultModel: string;
   persona: AgentPersona;
@@ -282,7 +290,10 @@ function AgentPersonaCard({
 
   return (
     <AgentIdentityCard
-      actions={actions}
+      actions={actions?.(
+        avatarUrl,
+        Boolean(agent && !persona.avatarUrl && profileQuery.isPending),
+      )}
       ariaLabel={`${title} agent profile`}
       avatar={
         agent ? (
@@ -468,7 +479,7 @@ function NewAgentCard({
 
 function LoadingSkeleton() {
   return (
-    <div className={AGENT_CARD_GRID_CLASS}>
+    <div className={IDENTITY_CARD_GRID_CLASS}>
       <IdentityCardSkeleton
         footerSubtitleWidthClass="w-14"
         footerTitleWidthClass="w-24"
@@ -526,7 +537,7 @@ function CollapsibleAgentGroup({
         <span className="text-xs text-muted-foreground">({agents.length})</span>
       </button>
       {!isCollapsed ? (
-        <div className={AGENT_CARD_GRID_CLASS}>
+        <div className={IDENTITY_CARD_GRID_CLASS}>
           {agents.map((agent) => (
             <StandaloneAgentCard
               agent={agent}
diff --git a/desktop/src/features/agents/ui/agentConfigOptions.tsx b/desktop/src/features/agents/ui/agentConfigOptions.tsx
index 1313d2cec4..d51c970f29 100644
--- a/desktop/src/features/agents/ui/agentConfigOptions.tsx
+++ b/desktop/src/features/agents/ui/agentConfigOptions.tsx
@@ -42,6 +42,7 @@ const KNOWN_LLM_PROVIDER_IDS = [
   "databricks_v2",
   "openai",
   "openai-compat",
+  "openrouter",
 ] as const;
 
 type PersonaLlmProviderId = (typeof KNOWN_LLM_PROVIDER_IDS)[number];
@@ -109,6 +110,10 @@ const PROVIDER_CREDENTIAL_CONFIG: Partial<
   "databricks-v2": {
     requiredEnvKeys: ["DATABRICKS_HOST"],
   },
+  openrouter: {
+    requiredEnvKeys: ["OPENROUTER_API_KEY"],
+    secretEnvVar: "OPENROUTER_API_KEY",
+  },
 };
 
 const DEFAULT_MODEL_OPTION: PersonaModelOption = {
@@ -120,6 +125,7 @@ export const PERSONA_LLM_PROVIDER_OPTIONS: readonly PersonaModelOption[] = [
   { id: "anthropic", label: "Anthropic" },
   { id: "openai", label: "OpenAI" },
   { id: "openai-compat", label: "OpenAI-compatible" },
+  { id: "openrouter", label: "OpenRouter" },
   { id: "relay-mesh", label: "Buzz shared compute" },
   { id: "databricks", label: "Databricks" },
   { id: "databricks_v2", label: "Databricks v2" },
@@ -279,7 +285,8 @@ export function providerRequiresExplicitModel(
   return (
     trimmedProvider === "anthropic" ||
     trimmedProvider === "openai" ||
-    trimmedProvider === "openai-compat"
+    trimmedProvider === "openai-compat" ||
+    trimmedProvider === "openrouter"
   );
 }
 
diff --git a/desktop/src/features/agents/ui/agentDialogRouting.test.mjs b/desktop/src/features/agents/ui/agentDialogRouting.test.mjs
index 196dceeef0..15b6b7cf87 100644
--- a/desktop/src/features/agents/ui/agentDialogRouting.test.mjs
+++ b/desktop/src/features/agents/ui/agentDialogRouting.test.mjs
@@ -4,6 +4,7 @@ import test from "node:test";
 import { AgentDialog } from "./AgentDialog.tsx";
 import { AgentDefinitionDialog } from "./AgentDefinitionDialog.tsx";
 import { AgentInstanceEditDialog } from "./AgentInstanceEditDialog.tsx";
+import { AgentRunLocationProvider } from "./AgentRunLocationContext.tsx";
 
 // ── Phase 1B.3c routing pinning ─────────────────────────────────────────────
 //
@@ -54,8 +55,13 @@ test("instance-edit routes to AgentInstanceEditDialog with its contract props",
     open: true,
   });
 
-  assert.equal(element.type, AgentInstanceEditDialog);
-  assert.deepEqual(element.props, {
+  // The arm wraps the form in the run-location provider so the respond-to
+  // warning can name the machine without the value being threaded as a prop
+  // through AgentInstanceEditDialog (see AgentRunLocationContext for why).
+  assert.equal(element.type, AgentRunLocationProvider);
+  const form = element.props.children;
+  assert.equal(form.type, AgentInstanceEditDialog);
+  assert.deepEqual(form.props, {
     agent,
     onEditLinkedPersona: undefined,
     onOpenChange,
@@ -65,6 +71,25 @@ test("instance-edit routes to AgentInstanceEditDialog with its contract props",
   });
 });
 
+test("instance-edit publishes the run location resolved from the agent backend", () => {
+  const routeWithBackend = (backend) =>
+    AgentDialog({
+      mode: "instance-edit",
+      agent: { pubkey: "abc", name: "test-agent", backend },
+      onOpenChange: noop,
+      onUpdated: noop,
+      open: true,
+    }).props.runLocation;
+
+  assert.equal(routeWithBackend({ type: "local" }), "local");
+  assert.equal(
+    routeWithBackend({ type: "provider", id: "blox", config: {} }),
+    "remote",
+  );
+  // An agent with no backend record has an unknown location — never a guess.
+  assert.equal(routeWithBackend(undefined), null);
+});
+
 test("create mode routes to the internal create router, not a form directly", () => {
   const element = AgentDialog({
     mode: "definition",
diff --git a/desktop/src/features/agents/ui/agentSessionTranscript.test.mjs b/desktop/src/features/agents/ui/agentSessionTranscript.test.mjs
index cc6f0467d6..b4a139eb0e 100644
--- a/desktop/src/features/agents/ui/agentSessionTranscript.test.mjs
+++ b/desktop/src/features/agents/ui/agentSessionTranscript.test.mjs
@@ -1879,3 +1879,201 @@ test("buildTranscript five-section system prompt card is standalone with all sec
     "prompt context must NOT contain system-prompt sections (Base/System/Team Instructions/Core Memory/Channel Canvas)",
   );
 });
+
+// --- claude-agent-acp _meta.systemPrompt.append transport ---
+
+test("buildTranscript session/new via _meta.systemPrompt.append produces identical standalone card as bare systemPrompt field", () => {
+  // claude-agent-acp delivers the system prompt at _meta.systemPrompt.append
+  // instead of the bare systemPrompt field. The observer must extract it and
+  // build the identical standalone card (same five sections, same acpSource,
+  // same turnId: null, same placement before the first turn).
+  const CH = "55555555-5555-5555-5555-555555555555";
+  const SYSTEM_PROMPT = [
+    "[Base]",
+    "You are a helpful assistant.",
+    "",
+    "[System]",
+    "Custom persona.",
+    "",
+    "---",
+    "# Team Instructions",
+    "Always tag on handoff.",
+    "",
+    "[Agent Memory \u2014 core]",
+    "I am Duncan.",
+    "",
+    "[Channel Canvas]",
+    "Canvas revision (event ID): a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
+    "Last modified: 2026-07-01T10:00:00Z",
+    "Fetch current content with: buzz canvas get --channel 55555555-5555-5555-5555-555555555555",
+  ].join("\n");
+
+  const makeEvents = (params) => [
+    {
+      seq: 1,
+      timestamp: "2026-07-01T10:00:00.000Z",
+      kind: "turn_started",
+      agentIndex: 0,
+      channelId: CH,
+      sessionId: null,
+      turnId: "turn-1",
+      payload: { source: "channel", triggeringEventIds: [] },
+    },
+    {
+      seq: 2,
+      timestamp: "2026-07-01T10:00:00.100Z",
+      kind: "acp_write",
+      agentIndex: 0,
+      channelId: CH,
+      sessionId: null,
+      turnId: "turn-1",
+      payload: { jsonrpc: "2.0", id: 1, method: "session/new", params },
+    },
+    {
+      seq: 3,
+      timestamp: "2026-07-01T10:00:00.200Z",
+      kind: "session_resolved",
+      agentIndex: 0,
+      channelId: CH,
+      sessionId: "sess-cc",
+      turnId: "turn-1",
+      payload: { sessionId: "sess-cc", isNewSession: true },
+    },
+    {
+      seq: 4,
+      timestamp: "2026-07-01T10:00:01.000Z",
+      kind: "acp_write",
+      agentIndex: 0,
+      channelId: CH,
+      sessionId: "sess-cc",
+      turnId: "turn-1",
+      payload: {
+        jsonrpc: "2.0",
+        id: 2,
+        method: "session/prompt",
+        params: {
+          sessionId: "sess-cc",
+          prompt: [
+            {
+              type: "text",
+              text: `[Buzz event: @mention]\nEvent ID: ${"a".repeat(64)}\nFrom: x (hex: ${"b".repeat(64)})\nContent: hello`,
+            },
+            { type: "text", text: "[Thread context]\nPrior messages here." },
+          ],
+        },
+      },
+    },
+  ];
+
+  // Build transcript from the claude-agent-acp _meta transport.
+  const metaEvents = makeEvents({
+    _meta: { systemPrompt: { append: SYSTEM_PROMPT } },
+  });
+  const metaRaw = buildTranscript(metaEvents);
+  const metaBlocks = buildTranscriptDisplayBlocks(metaRaw);
+  const metaFlat = flattenDisplayBlocks(metaBlocks);
+
+  // Also build from the standard bare-field transport for comparison.
+  const fieldEvents = makeEvents({ systemPrompt: SYSTEM_PROMPT });
+  const fieldRaw = buildTranscript(fieldEvents);
+  const fieldBlocks = buildTranscriptDisplayBlocks(fieldRaw);
+
+  // (a) Both produce exactly one standalone system-prompt single block.
+  const metaSPBlocks = metaBlocks.filter(
+    (b) => b.kind === "single" && b.item?.acpSource === "session/new",
+  );
+  const fieldSPBlocks = fieldBlocks.filter(
+    (b) => b.kind === "single" && b.item?.acpSource === "session/new",
+  );
+  assert.equal(
+    metaSPBlocks.length,
+    1,
+    "_meta: exactly one standalone system-prompt block",
+  );
+  assert.equal(
+    fieldSPBlocks.length,
+    1,
+    "field: exactly one standalone system-prompt block",
+  );
+
+  // (b) Both carry the same five ordered sections.
+  const EXPECTED_TITLES = [
+    "Base",
+    "System",
+    "Team Instructions",
+    "Core Memory",
+    "Channel Canvas",
+  ];
+  const metaTitles = (metaSPBlocks[0].item?.sections ?? []).map((s) => s.title);
+  const fieldTitles = (fieldSPBlocks[0].item?.sections ?? []).map(
+    (s) => s.title,
+  );
+  assert.deepEqual(
+    metaTitles,
+    EXPECTED_TITLES,
+    "_meta: five sections in order",
+  );
+  assert.deepEqual(
+    fieldTitles,
+    EXPECTED_TITLES,
+    "field: five sections in order",
+  );
+
+  // (c) System prompt appears before Prompt context in both display orders.
+  const metaSPIdx = metaFlat.findIndex((i) => i.title === "System prompt");
+  const metaPCIdx = metaFlat.findIndex((i) => i.title === "Prompt context");
+  assert.ok(metaSPIdx !== -1, "_meta: System prompt item present");
+  assert.ok(metaPCIdx !== -1, "_meta: Prompt context item present");
+  assert.ok(
+    metaSPIdx < metaPCIdx,
+    `_meta: System prompt (${metaSPIdx}) must precede Prompt context (${metaPCIdx})`,
+  );
+
+  // (d) The _meta item has turnId: null (standalone, not in a turn bucket).
+  const metaSPRawIdx = metaRaw.findIndex((i) => i.title === "System prompt");
+  assert.equal(
+    metaRaw[metaSPRawIdx]?.turnId ?? null,
+    null,
+    "_meta: system-prompt item must have turnId=null",
+  );
+});
+
+test("buildTranscript session/new bare systemPrompt field takes precedence over _meta.systemPrompt.append", () => {
+  // When both transports are present (non-standard but must not regress),
+  // the standard bare field must win — a reversed ?? would silently use the
+  // wrong text and the card body would differ from the wire source of truth.
+  const CH = "66666666-6666-6666-6666-666666666666";
+  const events = [
+    {
+      seq: 1,
+      timestamp: "2026-07-01T10:00:00.000Z",
+      kind: "acp_write",
+      agentIndex: 0,
+      channelId: CH,
+      sessionId: "sess-both",
+      turnId: "turn-1",
+      payload: {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "session/new",
+        params: {
+          systemPrompt: "[Base]\nWinner.",
+          _meta: { systemPrompt: { append: "[Base]\nLoser." } },
+        },
+      },
+    },
+  ];
+
+  const rawItems = buildTranscript(events);
+  const spItem = rawItems.find((i) => i.title === "System prompt");
+  assert.ok(spItem, "System prompt item must be present");
+  const bodies = (spItem.sections ?? []).map((s) => s.body).join("|");
+  assert.ok(
+    bodies.includes("Winner"),
+    "bare systemPrompt must win over _meta.systemPrompt.append",
+  );
+  assert.ok(
+    !bodies.includes("Loser"),
+    "_meta.systemPrompt.append must not appear when bare field is present",
+  );
+});
diff --git a/desktop/src/features/agents/ui/agentSessionTranscript.ts b/desktop/src/features/agents/ui/agentSessionTranscript.ts
index 962290c6ca..e371bf5fc3 100644
--- a/desktop/src/features/agents/ui/agentSessionTranscript.ts
+++ b/desktop/src/features/agents/ui/agentSessionTranscript.ts
@@ -872,14 +872,14 @@ export function processTranscriptEvent(
     } else if (event.kind === "acp_write" && method === "session/new") {
       // The base + persona prompts ride session/new's systemPrompt, framed by
       // the harness as [Base]/[System]/[Agent Memory — core]/[Channel Canvas].
-      // Each session/new event is keyed by (seq, timestamp) — the same dedup
-      // pair used by observerRelayStore — so distinct sessions each retain
-      // their own system-prompt card even across archive rebuilds where two
-      // processes may emit the same seq. turnId: null keeps it out of turn
-      // buckets; acpSource "session/new" lets the display grouper place it
-      // as a standalone card before the session's first turn.
+      // claude-agent-acp uses _meta.systemPrompt.append instead; both paths
+      // produce the same standalone card (turnId: null, acpSource "session/new");
+      // the bare field takes precedence when both are present.
       const params = asRecord(payload.params);
-      const systemPrompt = asString(params.systemPrompt);
+      const metaPrompt = asString(
+        asRecord(asRecord(params._meta).systemPrompt).append,
+      );
+      const systemPrompt = asString(params.systemPrompt) ?? metaPrompt;
       if (systemPrompt) {
         const sections = parseSystemPromptSections(systemPrompt);
         if (sections.length > 0) {
diff --git a/desktop/src/features/agents/ui/agentSnapshotImportDialog.test.mjs b/desktop/src/features/agents/ui/agentSnapshotImportDialog.test.mjs
index 3ddaf19724..a02bb5a825 100644
--- a/desktop/src/features/agents/ui/agentSnapshotImportDialog.test.mjs
+++ b/desktop/src/features/agents/ui/agentSnapshotImportDialog.test.mjs
@@ -9,7 +9,7 @@ import test from "node:test";
 // memoryErrors strings are carried through to a bounded list element with the
 // correct data-testid. No DOM or test renderer is needed.
 
-import { ResultBody } from "./AgentSnapshotImportDialog.tsx";
+import { PreviewBody, ResultBody } from "./AgentSnapshotImportDialog.tsx";
 
 /**
  * Walk a React element tree (breadth-first) and collect all elements that
@@ -71,6 +71,68 @@ function makeResult(overrides = {}) {
   };
 }
 
+function makePreview(overrides = {}) {
+  return {
+    displayName: "TestBot",
+    systemPrompt: "Inspect every boundary before changing code.",
+    avatarUrl: null,
+    memoryLevel: "none",
+    memoryEntryCount: 0,
+    hasSourceAllowlist: true,
+    sourceAllowlistCount: 2,
+    sourceAllowlist: ["a".repeat(64), "b".repeat(64)],
+    manifestJson: '{\n  "format": "buzz-agent-snapshot"\n}',
+    locked: false,
+    ...overrides,
+  };
+}
+
+// ── preview transparency ──────────────────────────────────────────────────────
+
+test("preview_body_discloses_prompt_allowlist_and_full_manifest", () => {
+  const preview = makePreview();
+  const element = PreviewBody({
+    preview,
+    hasMemory: false,
+    memoryLevelLabel: "none",
+    keepAllowlist: false,
+    onKeepAllowlistChange: () => {},
+  });
+  const allText = collectText(element).join(" ");
+
+  assert.ok(allText.includes(preview.systemPrompt));
+  for (const pubkey of preview.sourceAllowlist) {
+    assert.ok(allText.includes(pubkey), `missing allowlist pubkey ${pubkey}`);
+  }
+  assert.ok(allText.includes(preview.manifestJson));
+  assert.equal(
+    findAll(
+      element,
+      (n) => n.props?.["data-testid"] === "agent-snapshot-import-manifest",
+    ).length,
+    1,
+  );
+});
+
+// ── locked-card provenance notice ─────────────────────────────────────────────
+
+test("preview_body_shows_locked_notice_only_for_locked_cards", () => {
+  const lockedNotice = (locked) =>
+    findAll(
+      PreviewBody({
+        preview: makePreview({ locked }),
+        hasMemory: false,
+        memoryLevelLabel: "none",
+        keepAllowlist: false,
+        onKeepAllowlistChange: () => {},
+      }),
+      (n) => n.props?.["data-testid"] === "agent-snapshot-import-locked-notice",
+    );
+
+  assert.equal(lockedNotice(true).length, 1);
+  assert.equal(lockedNotice(false).length, 0);
+});
+
 // ── memory errors detail list ─────────────────────────────────────────────────
 
 test("result_body_renders_memory_errors_list_with_test_id", () => {
diff --git a/desktop/src/features/agents/ui/buzzAgentConfig.ts b/desktop/src/features/agents/ui/buzzAgentConfig.ts
index a0271fec0f..be663c35cb 100644
--- a/desktop/src/features/agents/ui/buzzAgentConfig.ts
+++ b/desktop/src/features/agents/ui/buzzAgentConfig.ts
@@ -128,6 +128,9 @@ export function getProviderEffortConfig(
     // databricks v1 uses OpenAI Chat Completions wire format.
     return openaiConfig(m);
   }
+  if (provider === "openrouter") {
+    return { validValues: ALL_VALUES, defaultValue: "medium" };
+  }
   // openai-compat, unknown, empty — all values, default medium.
   return { validValues: ALL_VALUES, defaultValue: "medium" };
 }
diff --git a/desktop/src/features/agents/ui/effortTable.fixture.json b/desktop/src/features/agents/ui/effortTable.fixture.json
index defb1f86de..d097bc995f 100644
--- a/desktop/src/features/agents/ui/effortTable.fixture.json
+++ b/desktop/src/features/agents/ui/effortTable.fixture.json
@@ -209,6 +209,13 @@
     "validValues": ["none", "minimal", "low", "medium", "high", "xhigh", "max"],
     "defaultValue": "medium"
   },
+  {
+    "note": "openrouter: all-7 with medium default",
+    "provider": "openrouter",
+    "model": "",
+    "validValues": ["none", "minimal", "low", "medium", "high", "xhigh", "max"],
+    "defaultValue": "medium"
+  },
   {
     "note": "empty provider: all-7 with medium default",
     "provider": "",
diff --git a/desktop/src/features/agents/ui/personaCatalogOwnerLabel.test.mjs b/desktop/src/features/agents/ui/personaCatalogOwnerLabel.test.mjs
new file mode 100644
index 0000000000..7ad726352f
--- /dev/null
+++ b/desktop/src/features/agents/ui/personaCatalogOwnerLabel.test.mjs
@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { resolveCatalogOwnerLabel } from "./PersonaCatalogDialog.tsx";
+
+// ── null / undefined summary ──────────────────────────────────────────────────
+
+test("test_null_summary_returns_community_member", () => {
+  assert.equal(resolveCatalogOwnerLabel(null), "Community member");
+});
+
+test("test_undefined_summary_returns_community_member", () => {
+  assert.equal(resolveCatalogOwnerLabel(undefined), "Community member");
+});
+
+// ── populated displayName ─────────────────────────────────────────────────────
+
+test("test_display_name_present_returns_display_name", () => {
+  assert.equal(
+    resolveCatalogOwnerLabel({ displayName: "Alice", name: "alice" }),
+    "Alice",
+  );
+});
+
+test("test_display_name_present_without_name_returns_display_name", () => {
+  assert.equal(resolveCatalogOwnerLabel({ displayName: "Alice" }), "Alice");
+});
+
+// ── empty / whitespace displayName with valid name ────────────────────────────
+
+test("test_empty_display_name_falls_through_to_name", () => {
+  assert.equal(
+    resolveCatalogOwnerLabel({ displayName: "", name: "alice" }),
+    "alice",
+  );
+});
+
+test("test_whitespace_only_display_name_falls_through_to_name", () => {
+  assert.equal(
+    resolveCatalogOwnerLabel({ displayName: "   ", name: "alice" }),
+    "alice",
+  );
+});
+
+// ── both candidates absent / empty ────────────────────────────────────────────
+
+test("test_both_null_returns_community_member", () => {
+  assert.equal(
+    resolveCatalogOwnerLabel({ displayName: null, name: null }),
+    "Community member",
+  );
+});
+
+test("test_both_empty_returns_community_member", () => {
+  assert.equal(
+    resolveCatalogOwnerLabel({ displayName: "", name: "" }),
+    "Community member",
+  );
+});
+
+test("test_both_whitespace_returns_community_member", () => {
+  assert.equal(
+    resolveCatalogOwnerLabel({ displayName: "  ", name: "\t" }),
+    "Community member",
+  );
+});
+
+test("test_display_name_absent_name_present_returns_name", () => {
+  assert.equal(resolveCatalogOwnerLabel({ name: "alice" }), "alice");
+});
+
+test("test_display_name_null_name_present_returns_name", () => {
+  assert.equal(
+    resolveCatalogOwnerLabel({ displayName: null, name: "alice" }),
+    "alice",
+  );
+});
diff --git a/desktop/src/features/agents/ui/respondToFieldContract.test.mjs b/desktop/src/features/agents/ui/respondToFieldContract.test.mjs
new file mode 100644
index 0000000000..c3efd34650
--- /dev/null
+++ b/desktop/src/features/agents/ui/respondToFieldContract.test.mjs
@@ -0,0 +1,67 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+
+const respondToFieldSource = await readFile(
+  new URL("./RespondToField.tsx", import.meta.url),
+  "utf8",
+);
+
+/**
+ * Copy assertions run against this rather than the raw source: JSX text wraps
+ * wherever the formatter decides, and a sentence split across lines should not
+ * fail a copy test.
+ */
+const collapsedSource = respondToFieldSource.replace(/\s+/g, " ");
+
+for (const label of ["Only me (default)", "Selected people", "Anyone"]) {
+  test(`respond-to control uses the plain-language label: ${label}`, () => {
+    assert.ok(respondToFieldSource.includes(`label: "${label}"`));
+  });
+}
+
+test("native and persona controls share one option list", () => {
+  assert.match(
+    respondToFieldSource,
+    /<select[\s\S]*RESPOND_TO_OPTIONS\.map\(\(option\) => \([\s\S]*<option/,
+  );
+});
+
+test("every shared-access mode renders a persistent warning", () => {
+  // Anyone and Selected people both hand host access to someone other than the
+  // owner, so both warn; only the audience phrase differs.
+  assert.match(respondToFieldSource, /mode === "anyone" \? accessWarning/);
+  assert.match(respondToFieldSource, /mode === "allowlist" \? accessWarning/);
+});
+
+test("the Selected people warning sits after the people picker", () => {
+  // It must not sit between the user and the selection they came here to make.
+  const pickerAt = respondToFieldSource.indexOf("<AllowlistPicker");
+  const warningAt = respondToFieldSource.indexOf(
+    'mode === "allowlist" ? accessWarning',
+  );
+  assert.ok(pickerAt > 0 && warningAt > pickerAt);
+});
+
+test("the warning copy comes from the shared helper, not inline text", () => {
+  // Guards against a surface hand-rolling its own wording, which is how the
+  // machine name drifts out of sync with the actual run location.
+  // An explicit prop wins over the AgentRunLocationContext fallback, so the
+  // call site must keep that precedence rather than reading only one source.
+  assert.match(
+    collapsedSource,
+    /agentAccessWarningText\( mode, runLocation \?\? inheritedRunLocation, \)/,
+  );
+  assert.match(collapsedSource, /<p aria-live="polite"[^>]*> \{warningText\}/);
+});
+
+test("primary respond-to copy does not expose implementation jargon", () => {
+  const primaryFieldSource = respondToFieldSource.slice(
+    respondToFieldSource.indexOf('data-testid="agent-respond-to"'),
+    respondToFieldSource.indexOf("const HEX_64_RE"),
+  );
+
+  for (const jargon of ["Nostr authors", "!shutdown"]) {
+    assert.doesNotMatch(primaryFieldSource, new RegExp(jargon));
+  }
+});
diff --git a/desktop/src/features/agents/ui/usePersonaActions.ts b/desktop/src/features/agents/ui/usePersonaActions.ts
index 0c56eeac10..2c7668969a 100644
--- a/desktop/src/features/agents/ui/usePersonaActions.ts
+++ b/desktop/src/features/agents/ui/usePersonaActions.ts
@@ -99,10 +99,12 @@ export function usePersonaActions() {
   const [personaToShare, setPersonaToShare] = React.useState<{
     persona: AgentPersona;
     linkedAgentPubkey: string | null;
+    effectiveAvatarUrl: string | null;
   } | null>(null);
   const [personaToExportSnapshot, setPersonaToExportSnapshot] = React.useState<{
     persona: AgentPersona;
     linkedAgentPubkey: string | null;
+    effectiveAvatarUrl: string | null;
   } | null>(null);
   const [snapshotImportState, setSnapshotImportState] = React.useState<{
     fileBytes: number[];
@@ -447,17 +449,20 @@ export function usePersonaActions() {
   function openShare(
     persona: AgentPersona,
     linkedAgent: ManagedAgent | undefined,
+    effectiveAvatarUrl: string | null,
   ) {
     clearFeedback("library");
     setPersonaToShare({
       persona,
       linkedAgentPubkey: linkedAgent?.pubkey ?? null,
+      effectiveAvatarUrl,
     });
   }
 
   function handleExportSnapshot(
     persona: AgentPersona,
     linkedAgentPubkey: string | null,
+    effectiveAvatarUrl: string | null,
     memoryLevel: SnapshotMemoryLevel,
     format: SnapshotFormat,
   ) {
@@ -469,7 +474,7 @@ export function usePersonaActions() {
         memoryLevel,
         format,
         memorySourcePubkey: linkedAgentPubkey,
-        avatarUrl: persona.avatarUrl,
+        avatarUrl: effectiveAvatarUrl,
       },
       {
         onSuccess: (saved) => {
diff --git a/desktop/src/features/channels/ui/AgentSessionThreadPanel.tsx b/desktop/src/features/channels/ui/AgentSessionThreadPanel.tsx
index a907f87245..641b81490b 100644
--- a/desktop/src/features/channels/ui/AgentSessionThreadPanel.tsx
+++ b/desktop/src/features/channels/ui/AgentSessionThreadPanel.tsx
@@ -35,10 +35,12 @@ import {
   AuxiliaryPanelHeader,
   AuxiliaryPanelHeaderActions,
   AuxiliaryPanelHeaderGroup,
-  AuxiliaryPanelHeaderTitleBlock,
 } from "@/shared/layout/AuxiliaryPanel";
 import { Button } from "@/shared/ui/button";
 import type { UserProfileLookup } from "@/features/profile/lib/identity";
+import { resolveUserLabel } from "@/features/profile/lib/identity";
+import { ProfileAvatar } from "@/features/profile/ui/ProfileAvatar";
+import { normalizePubkey } from "@/shared/lib/pubkey";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -237,6 +239,15 @@ export function AgentSessionThreadPanel({
       ? `#${scopeChannelName}`
       : "1 channel"
     : "All channels";
+  const agentProfile = profiles?.[normalizePubkey(agent.pubkey)] ?? null;
+  const agentLabel = resolveUserLabel({
+    pubkey: agent.pubkey,
+    fallbackName: agent.name,
+    profiles,
+    preferResolvedSelfLabel: true,
+  });
+  const viewLabel = showRawFeed ? "Raw ACP activity" : "Activity";
+  const headerScopeLabel = `${viewLabel} · ${scopeLabel}`;
   const animateActivity = useTranscriptAnimationEnabled();
   const showTimestamps = useTranscriptTimestampsEnabled();
   async function handleInterruptTurn() {
@@ -417,19 +428,39 @@ export function AgentSessionThreadPanel({
         backButtonTestId="agent-session-back"
         onBack={onBack}
       >
-        <AuxiliaryPanelHeaderTitleBlock
-          subtitle={lastUpdatedLabel}
-          subtitleTitle={lastUpdatedTitle}
-          title={showRawFeed ? "Raw ACP Activity" : "Activity"}
+        <ProfileAvatar
+          avatarUrl={agentProfile?.avatarUrl ?? null}
+          className="size-9"
+          label={agentLabel}
+          testId="agent-session-agent-avatar"
         />
-        {/* Scope label: makes channel-targeted vs all-channels state obvious
-            (an all-channels pane can look "wrong" without it). */}
-        <span
-          className="min-w-0 shrink truncate text-xs text-muted-foreground"
-          data-testid="agent-session-scope-label"
-        >
-          {scopeLabel}
-        </span>
+        <div className="min-w-0 flex-1">
+          <h2
+            className="truncate text-sm font-semibold leading-5"
+            data-testid="agent-session-agent-name"
+            title={agentLabel}
+          >
+            {agentLabel}
+          </h2>
+          <div className="flex min-w-0 items-center gap-1 text-xs text-muted-foreground">
+            <p
+              className="min-w-0 flex-1 truncate"
+              data-testid="agent-session-scope-label"
+            >
+              {headerScopeLabel}
+            </p>
+            <span aria-hidden="true" className="shrink-0">
+              ·
+            </span>
+            <span
+              className="shrink-0"
+              data-testid="agent-session-recency-label"
+              title={lastUpdatedTitle}
+            >
+              {lastUpdatedLabel}
+            </span>
+          </div>
+        </div>
       </AuxiliaryPanelHeaderGroup>
       {agentHeaderActions}
     </>
diff --git a/desktop/src/features/channels/ui/ChannelComposerActivityAccessory.tsx b/desktop/src/features/channels/ui/ChannelComposerActivityAccessory.tsx
index 216b205fcc..f99888f011 100644
--- a/desktop/src/features/channels/ui/ChannelComposerActivityAccessory.tsx
+++ b/desktop/src/features/channels/ui/ChannelComposerActivityAccessory.tsx
@@ -1,5 +1,7 @@
 import type { ComponentProps } from "react";
 
+import { CardMintComposerChip } from "@/features/agents/ui/CardMintComposerChip";
+import { useCardMintJobs } from "@/features/agents/cardMintStore";
 import { BotActivityComposerAction } from "@/features/channels/ui/BotActivityBar";
 import { ComposerActivityAccessory } from "@/features/messages/ui/ComposerActivityAccessory";
 import { TypingIndicatorRow } from "@/features/messages/ui/TypingIndicatorRow";
@@ -31,6 +33,7 @@ export function ChannelComposerActivityAccessory({
   visible,
   workingBotPubkeys,
 }: ChannelComposerActivityAccessoryProps) {
+  const cardMintJobs = useCardMintJobs();
   return (
     <ComposerActivityAccessory
       className="px-5"
@@ -38,6 +41,7 @@ export function ChannelComposerActivityAccessory({
       visible={visible}
     >
       <div className="flex w-full items-center gap-2 overflow-visible pl-2">
+        {cardMintJobs.length > 0 ? <CardMintComposerChip /> : null}
         {workingBotPubkeys.length > 0 ? (
           <div className="flex min-w-0 flex-1 overflow-visible">
             <BotActivityComposerAction
diff --git a/desktop/src/features/channels/ui/ChannelMemberInviteCard.tsx b/desktop/src/features/channels/ui/ChannelMemberInviteCard.tsx
index 63ab164ea4..dd370e8c61 100644
--- a/desktop/src/features/channels/ui/ChannelMemberInviteCard.tsx
+++ b/desktop/src/features/channels/ui/ChannelMemberInviteCard.tsx
@@ -1,6 +1,7 @@
 import { Search, UserPlus, X } from "lucide-react";
 import * as React from "react";
 
+import { parsePubkeyInput } from "@/shared/lib/nostrUtils";
 import { truncatePubkey } from "@/shared/lib/pubkey";
 import { PubKey } from "@/shared/ui/PubKey";
 import { useIsArchivedPredicate } from "@/features/identity-archive/hooks";
@@ -105,6 +106,35 @@ export function ChannelMemberInviteCard({
     ],
   );
 
+  // Someone without a kind:0 profile on the relay is invisible to user
+  // search — let the caller paste their npub or hex pubkey directly instead.
+  const directInvitee = React.useMemo<UserSearchResult | null>(() => {
+    const pubkey = parsePubkeyInput(deferredInviteQuery);
+    if (
+      pubkey === null ||
+      memberPubkeys.has(pubkey) ||
+      selectedInviteePubkeys.has(pubkey) ||
+      (userSearchQuery.data ?? []).some(
+        (user) => user.pubkey.toLowerCase() === pubkey,
+      )
+    ) {
+      return null;
+    }
+    return {
+      pubkey,
+      displayName: null,
+      avatarUrl: null,
+      nip05Handle: null,
+      ownerPubkey: null,
+      isAgent: false,
+    };
+  }, [
+    deferredInviteQuery,
+    memberPubkeys,
+    selectedInviteePubkeys,
+    userSearchQuery.data,
+  ]);
+
   React.useEffect(() => {
     if (!open) {
       setInviteQuery("");
@@ -161,7 +191,7 @@ export function ChannelMemberInviteCard({
               disabled={isPending}
               id="channel-management-search-users"
               onChange={(event) => setInviteQuery(event.target.value)}
-              placeholder="Search people and agents"
+              placeholder="Search people, or paste a public key"
               value={inviteQuery}
             />
           </div>
@@ -217,12 +247,41 @@ export function ChannelMemberInviteCard({
           ) : null}
           {deferredInviteQuery.length > 0 ? (
             <div className="border-t border-border/70 px-2 py-2">
-              {userSearchQuery.isLoading ? (
+              {userSearchQuery.isLoading && !directInvitee ? (
                 <p className="px-2 py-1 text-sm text-muted-foreground">
                   Searching…
                 </p>
-              ) : inviteSearchResults.length > 0 ? (
+              ) : inviteSearchResults.length > 0 || directInvitee ? (
                 <div className="max-h-44 space-y-1 overflow-y-auto">
+                  {directInvitee ? (
+                    <button
+                      className="flex w-full items-center justify-between rounded-md px-2.5 py-1.5 text-left transition-colors hover:bg-accent hover:text-accent-foreground"
+                      data-testid={`channel-direct-invite-${directInvitee.pubkey}`}
+                      onClick={() => {
+                        setSelectedInvitees((current) => [
+                          ...current,
+                          directInvitee,
+                        ]);
+                        setInviteQuery("");
+                      }}
+                      type="button"
+                    >
+                      <div className="flex min-w-0 items-center gap-2">
+                        <UserAvatar
+                          avatarUrl={null}
+                          displayName={truncatePubkey(directInvitee.pubkey)}
+                          size="xs"
+                        />
+                        <p className="truncate text-sm font-medium leading-5">
+                          {truncatePubkey(directInvitee.pubkey)}
+                        </p>
+                        <span className="shrink-0 text-xs text-muted-foreground">
+                          by public key
+                        </span>
+                      </div>
+                      <span className="text-xs text-muted-foreground">Add</span>
+                    </button>
+                  ) : null}
                   {inviteSearchResults.map((result) => (
                     <button
                       className="flex w-full items-center justify-between rounded-md px-2.5 py-1.5 text-left transition-colors hover:bg-accent hover:text-accent-foreground"
diff --git a/desktop/src/features/channels/ui/ChannelMembersBar.tsx b/desktop/src/features/channels/ui/ChannelMembersBar.tsx
index c87617ce9b..7b9bf2b79f 100644
--- a/desktop/src/features/channels/ui/ChannelMembersBar.tsx
+++ b/desktop/src/features/channels/ui/ChannelMembersBar.tsx
@@ -11,9 +11,15 @@ import {
   useManagedAgentsQuery,
   useRelayAgentsQuery,
 } from "@/features/agents/hooks";
+import { mergeChannelKnownAgentPubkeys } from "@/features/agents/knownAgentPubkeys";
 import { requestOpenCreateAgent } from "@/features/agents/openCreateAgentEvent";
 import { useChannelMembersQuery } from "@/features/channels/hooks";
+import {
+  getDmHuddleMemberPubkeys,
+  hasOtherDmParticipant,
+} from "@/features/channels/lib/dmHuddleMembers";
 import { canStartHuddleInChannel } from "@/features/channels/lib/huddleAvailability";
+import { useUsersBatchQuery } from "@/features/profile/hooks";
 import type { Channel } from "@/shared/api/types";
 import { normalizePubkey } from "@/shared/lib/pubkey";
 import { Button } from "@/shared/ui/button";
@@ -64,6 +70,41 @@ export function ChannelMembersBar({
   const managedAgentsQuery = useManagedAgentsQuery();
   const relayAgentsQuery = useRelayAgentsQuery();
   const members = membersQuery.data ?? [];
+  const dmProfilesQuery = useUsersBatchQuery(
+    channel.channelType === "dm" ? channel.participantPubkeys : [],
+    { enabled: channel.channelType === "dm" },
+  );
+  const huddleAgentPubkeys = React.useMemo(() => {
+    const pubkeys = new Set(
+      mergeChannelKnownAgentPubkeys(
+        membersQuery.data,
+        managedAgentsQuery.data,
+        relayAgentsQuery.data,
+      ),
+    );
+    for (const [pubkey, profile] of Object.entries(
+      dmProfilesQuery.data?.profiles ?? {},
+    )) {
+      if (profile.isAgent) pubkeys.add(normalizePubkey(pubkey));
+    }
+    return pubkeys;
+  }, [
+    dmProfilesQuery.data?.profiles,
+    managedAgentsQuery.data,
+    membersQuery.data,
+    relayAgentsQuery.data,
+  ]);
+  const huddleMemberPubkeys = React.useMemo(
+    () => getDmHuddleMemberPubkeys(channel, huddleAgentPubkeys, currentPubkey),
+    [channel, currentPubkey, huddleAgentPubkeys],
+  );
+  const huddleMemberPubkeysPending =
+    hasOtherDmParticipant(channel, currentPubkey) &&
+    (membersQuery.isPending ||
+      managedAgentsQuery.isPending ||
+      relayAgentsQuery.isPending ||
+      dmProfilesQuery.isPending ||
+      dmProfilesQuery.isPlaceholderData);
   const memberCount = membersQuery.data?.length ?? channel.memberCount;
   const providers = React.useMemo(
     () =>
@@ -117,7 +158,7 @@ export function ChannelMembersBar({
         try {
           await startHuddle(
             channel.id,
-            [],
+            [...huddleMemberPubkeys],
             buildHuddleChannelName({
               channel,
               currentPubkey,
@@ -133,7 +174,9 @@ export function ChannelMembersBar({
         }
       }}
       renderMode={variant === "compact" ? "menu-item" : "button"}
-      startDisabled={!canStartHuddle || isStartingHuddle}
+      startDisabled={
+        !canStartHuddle || isStartingHuddle || huddleMemberPubkeysPending
+      }
     />
   );
 
diff --git a/desktop/src/features/channels/ui/ChannelPane.tsx b/desktop/src/features/channels/ui/ChannelPane.tsx
index 92fa172ff5..770c45e445 100644
--- a/desktop/src/features/channels/ui/ChannelPane.tsx
+++ b/desktop/src/features/channels/ui/ChannelPane.tsx
@@ -21,10 +21,7 @@ import {
   getDmHuddleMemberPubkeys,
   hasOtherDmParticipant,
 } from "@/features/channels/lib/dmHuddleMembers";
-import {
-  buildVideoReviewCommentsByRootId,
-  buildVideoReviewContextForMessage,
-} from "@/features/messages/lib/videoReviewContext";
+import { buildVideoReviewContextsByMessageId } from "@/features/messages/lib/videoReviewContext";
 import { useComposerHeightPadding } from "@/features/messages/ui/useComposerHeightPadding";
 import { UserProfilePanel } from "@/features/profile/ui/UserProfilePanel";
 import { ChannelFindBar } from "@/features/search/ui/ChannelFindBar";
@@ -39,6 +36,7 @@ import { useThreadViewMode } from "@/features/channels/lib/threadViewModePrefere
 import { useThreadViewModeSwitch } from "@/features/channels/ui/useThreadViewModeSwitch";
 import { useFocusDrawerPresence } from "@/features/channels/ui/useFocusDrawerPresence";
 import { useChannelWorkingAgentPubkeys } from "@/features/agents/agentWorkingSignal";
+import { useCardMintJobs } from "@/features/agents/cardMintStore";
 import { BotActivityComposerAction } from "@/features/channels/ui/BotActivityBar";
 import { ChannelComposerActivityAccessory } from "@/features/channels/ui/ChannelComposerActivityAccessory";
 import {
@@ -150,6 +148,7 @@ export const ChannelPane = React.memo(function ChannelPane({
   profilePanelTab,
   profilePanelView,
   targetMessageId,
+  threadAllMessages,
   threadHeadMessage,
   threadMessages,
   threadMessagesPending = false,
@@ -410,7 +409,11 @@ export const ChannelPane = React.memo(function ChannelPane({
     activeChannel?.id ?? null,
   );
   const hasComposerBotActivity = composerWorkingBotPubkeys.length > 0;
-  const hasComposerBottomActivity = hasComposerBotActivity || hasTypingActivity;
+  // Background card mints surface in the same rail ("Minting card…" chip),
+  // so they must also reserve the activity row.
+  const hasCardMintActivity = useCardMintJobs().length > 0;
+  const hasComposerBottomActivity =
+    hasComposerBotActivity || hasTypingActivity || hasCardMintActivity;
   const threadComposerBotTypingPubkeys = React.useMemo(() => {
     if (!openThreadHeadId) return [];
     return botTypingEntries
@@ -472,25 +475,26 @@ export const ChannelPane = React.memo(function ChannelPane({
     threadHeadMessage,
     threadMessages,
   });
-  const videoReviewCommentsByRootId = React.useMemo(
-    () => buildVideoReviewCommentsByRootId(messages),
-    [messages],
-  );
   const activeVideoReviewCommentSender = activeChannel?.archivedAt
     ? undefined
     : onSendVideoReviewComment;
-  const threadHeadVideoReviewContext = React.useMemo(() => {
-    if (!threadHeadMessage) {
-      return undefined;
+  const threadVideoReviewContextsByMessageId = React.useMemo(() => {
+    const messagesById = new Map(
+      messages.map((message) => [message.id, message]),
+    );
+    if (threadHeadMessage) {
+      messagesById.set(threadHeadMessage.id, threadHeadMessage);
+    }
+    for (const message of threadAllMessages) {
+      messagesById.set(message.id, message);
     }
 
-    return buildVideoReviewContextForMessage({
+    return buildVideoReviewContextsByMessageId({
       channelId: activeChannel?.id ?? null,
       channelName: activeChannel?.name,
       channelType: activeChannel?.channelType ?? null,
-      comments: videoReviewCommentsByRootId.get(threadHeadMessage.id) ?? [],
       isSendingVideoReviewComment: isSending,
-      message: threadHeadMessage,
+      messages: [...messagesById.values()],
       onSendVideoReviewComment: activeVideoReviewCommentSender,
       onToggleReaction,
       profiles,
@@ -499,10 +503,11 @@ export const ChannelPane = React.memo(function ChannelPane({
     activeChannel,
     activeVideoReviewCommentSender,
     isSending,
+    messages,
     onToggleReaction,
     profiles,
+    threadAllMessages,
     threadHeadMessage,
-    videoReviewCommentsByRootId,
   ]);
 
   const isOverlay = useIsThreadPanelOverlay();
@@ -676,6 +681,7 @@ export const ChannelPane = React.memo(function ChannelPane({
             onMarkUnread={onMarkUnread}
             onMarkRead={onMarkRead}
             onReply={activeChannel?.archivedAt ? undefined : onOpenThread}
+            onOpenThread={onOpenThread}
             channelName={activeChannel?.name}
             channelType={activeChannel?.channelType ?? null}
             isSendingVideoReviewComment={isSending}
@@ -876,7 +882,9 @@ export const ChannelPane = React.memo(function ChannelPane({
                 scrollTargetHighlights={!layoutScrollTargetId}
                 scrollTargetId={layoutScrollTargetId ?? threadScrollTargetId}
                 threadHead={threadHeadMessage}
-                threadHeadVideoReviewContext={threadHeadVideoReviewContext}
+                videoReviewContextsByMessageId={
+                  threadVideoReviewContextsByMessageId
+                }
                 widthPx={threadPanelWidthPx}
                 threadReplies={threadMessages}
                 threadRepliesPending={threadMessagesPending}
diff --git a/desktop/src/features/channels/ui/ChannelPane.types.ts b/desktop/src/features/channels/ui/ChannelPane.types.ts
index 5a27d85c4d..7257d8cd55 100644
--- a/desktop/src/features/channels/ui/ChannelPane.types.ts
+++ b/desktop/src/features/channels/ui/ChannelPane.types.ts
@@ -151,6 +151,7 @@ export type ChannelPaneProps = {
   profilePanelTab: ProfilePanelTab;
   profilePanelView: ProfilePanelView;
   threadHeadMessage: TimelineMessage | null;
+  threadAllMessages: TimelineMessage[];
   threadMessages: MainTimelineEntry[];
   threadMessagesPending?: boolean;
   threadPanelWidthPx: number;
diff --git a/desktop/src/features/channels/ui/ChannelScreen.tsx b/desktop/src/features/channels/ui/ChannelScreen.tsx
index 52b3ae7fb7..b4d33b4776 100644
--- a/desktop/src/features/channels/ui/ChannelScreen.tsx
+++ b/desktop/src/features/channels/ui/ChannelScreen.tsx
@@ -48,6 +48,7 @@ import {
   channelWindowThreadSummaries,
   type ChannelWindowThreadSummary,
 } from "@/features/messages/lib/channelWindowStore";
+import { DeleteMessageConfirmDialog } from "@/features/messages/ui/DeleteMessageConfirmDialog";
 import { getThreadReference } from "@/features/messages/lib/threading";
 import { imetaMediaFromTags } from "@/features/messages/lib/imetaMediaMarkdown";
 import {
@@ -483,6 +484,9 @@ export function ChannelScreen({
       timelineMessages.find((message) => message.id === editTargetId) ?? null,
     [editTargetId, timelineMessages],
   );
+  // Event id awaiting the empty-edit "Delete message?" confirmation (non-null
+  // while the dialog is open); see handleEditSave.
+  const [emptyDeleteId, setEmptyDeleteId] = React.useState<string | null>(null);
   const {
     handleCancelEdit,
     handleCancelThreadReply,
@@ -506,6 +510,7 @@ export function ChannelScreen({
     markRevealedRepliesRead,
     openThreadHeadId: effectiveOpenThreadHeadId,
     onOptimisticOpenThreadHeadIdChange: setOptimisticOpenThreadHeadId,
+    onRequestEmptyEditDelete: setEmptyDeleteId,
     sendMessageMutation,
     setExpandedThreadReplyIds,
     setEditTargetId,
@@ -691,6 +696,7 @@ export function ChannelScreen({
       channelManagementOpen,
   );
   const displayedThreadHeadMessage = threadPanelData.threadHead;
+  const displayedThreadAllMessages = threadPanelData.messages;
   const displayedThreadMessages = threadPanelData.visibleReplies;
   const displayedThreadReplyTargetMessage = threadPanelData.replyTargetMessage;
   const displayedThreadFirstUnreadReplyId = displayedThreadHeadMessage
@@ -801,6 +807,19 @@ export function ChannelScreen({
           open={welcomeAgentCreate.isOpen}
           sendError={welcomeAgentCreate.error}
         />
+        <DeleteMessageConfirmDialog
+          onConfirm={() => {
+            if (emptyDeleteId) {
+              setEditTargetId(null);
+              void handleDelete({ id: emptyDeleteId });
+            }
+            setEmptyDeleteId(null);
+          }}
+          onOpenChange={(open) => {
+            if (!open) setEmptyDeleteId(null);
+          }}
+          open={emptyDeleteId !== null}
+        />
         <div
           className="flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden"
           ref={channelContentRef}
@@ -944,6 +963,7 @@ export function ChannelScreen({
                   firstUnreadMessageId={firstUnreadMessageId}
                   unreadCount={unreadCount}
                   targetMessageId={mainTimelineTargetMessageId}
+                  threadAllMessages={displayedThreadAllMessages}
                   threadHeadMessage={displayedThreadHeadMessage}
                   threadMessages={displayedThreadMessages}
                   threadMessagesPending={threadRepliesQuery.isPending}
diff --git a/desktop/src/features/channels/ui/ChannelScreenHeader.tsx b/desktop/src/features/channels/ui/ChannelScreenHeader.tsx
index a3a8a20231..4c545baf68 100644
--- a/desktop/src/features/channels/ui/ChannelScreenHeader.tsx
+++ b/desktop/src/features/channels/ui/ChannelScreenHeader.tsx
@@ -13,6 +13,7 @@ import {
   ProfileAvatarWithStatus,
   scaleProfileAvatarStatusGeometry,
 } from "@/features/profile/ui/ProfileAvatarWithStatus";
+import { UserProfilePopover } from "@/features/profile/ui/UserProfilePopover";
 import { Button } from "@/shared/ui/button";
 import type { Channel, PresenceStatus } from "@/shared/api/types";
 import { UserAvatar } from "@/shared/ui/UserAvatar";
@@ -65,6 +66,7 @@ export function ChannelScreenHeader({
   const isGroupDm =
     activeChannel?.channelType === "dm" &&
     activeDmHeaderParticipants.length > 1;
+  const activeDmParticipant = activeDmHeaderParticipants[0] ?? null;
   const showJoinButton =
     activeChannel !== null &&
     !activeChannel.isMember &&
@@ -113,6 +115,25 @@ export function ChannelScreenHeader({
             <DmHeaderParticipantStack
               participants={activeDmHeaderParticipants}
             />
+          ) : activeDmParticipant ? (
+            <UserProfilePopover
+              pubkey={activeDmParticipant.pubkey}
+              triggerAriaLabel={`Open profile for ${activeChannelTitle}`}
+              triggerElement="span"
+            >
+              <ProfileAvatarWithStatus
+                avatarClassName="text-xs"
+                avatarUrl={activeDmAvatarUrl}
+                className="mr-1.5 h-8 w-8"
+                geometry={DM_HEADER_AVATAR_STATUS_GEOMETRY}
+                iconClassName="h-4 w-4"
+                label={activeChannelTitle}
+                size={DM_HEADER_AVATAR_SIZE}
+                status={activeDmPresenceStatus ?? "offline"}
+                statusTestId="chat-presence-badge"
+                testId="chat-header-dm-avatar"
+              />
+            </UserProfilePopover>
           ) : (
             <ProfileAvatarWithStatus
               avatarClassName="text-xs"
@@ -152,31 +173,36 @@ function DmHeaderParticipantStack({
 
   return (
     <div
-      aria-hidden="true"
       className="mr-1.5 flex shrink-0 items-center"
       data-testid="chat-header-dm-avatar-stack"
     >
       {visibleParticipants.map((participant, index) => (
-        <div
-          className={index > 0 ? "-ml-2" : ""}
-          data-testid="chat-header-dm-avatar-stack-participant"
+        <UserProfilePopover
           key={participant.pubkey}
-          style={{
-            zIndex: index + 1,
-            ...(index < stackItemCount - 1 && {
-              mask: "radial-gradient(circle 18px at calc(100% + 4px) 50%, transparent 99%, #fff 100%)",
-              WebkitMask:
-                "radial-gradient(circle 18px at calc(100% + 4px) 50%, transparent 99%, #fff 100%)",
-            }),
-          }}
+          pubkey={participant.pubkey}
+          triggerAriaLabel={`Open profile for ${participant.displayName}`}
+          triggerElement="span"
         >
-          <UserAvatar
-            avatarUrl={participant.avatarUrl}
-            className="h-8 w-8 text-xs"
-            displayName={participant.displayName}
-            size="sm"
-          />
-        </div>
+          <span
+            className={index > 0 ? "-ml-2" : ""}
+            data-testid="chat-header-dm-avatar-stack-participant"
+            style={{
+              zIndex: index + 1,
+              ...(index < stackItemCount - 1 && {
+                mask: "radial-gradient(circle 18px at calc(100% + 4px) 50%, transparent 99%, #fff 100%)",
+                WebkitMask:
+                  "radial-gradient(circle 18px at calc(100% + 4px) 50%, transparent 99%, #fff 100%)",
+              }),
+            }}
+          >
+            <UserAvatar
+              avatarUrl={participant.avatarUrl}
+              className="h-8 w-8 text-xs"
+              displayName={participant.displayName}
+              size="sm"
+            />
+          </span>
+        </UserProfilePopover>
       ))}
       {hiddenCount > 0 ? (
         <div
diff --git a/desktop/src/features/channels/ui/EditRespondToDialog.tsx b/desktop/src/features/channels/ui/EditRespondToDialog.tsx
index 11a2dcd09d..d9f091e902 100644
--- a/desktop/src/features/channels/ui/EditRespondToDialog.tsx
+++ b/desktop/src/features/channels/ui/EditRespondToDialog.tsx
@@ -1,6 +1,7 @@
 import * as React from "react";
 
 import { useUpdateManagedAgentMutation } from "@/features/agents/hooks";
+import { runLocationForBackend } from "@/features/agents/lib/agentAccessWarning";
 import { CreateAgentRespondToField } from "@/features/agents/ui/RespondToField";
 import type { ManagedAgent, RespondToMode } from "@/shared/api/types";
 import { Button } from "@/shared/ui/button";
@@ -54,9 +55,9 @@ export function EditRespondToDialog({
     <Dialog onOpenChange={onOpenChange} open={open}>
       <DialogContent className="max-w-md">
         <DialogHeader>
-          <DialogTitle>Edit respond-to</DialogTitle>
+          <DialogTitle>Manage agent access</DialogTitle>
           <DialogDescription>
-            Choose who {agent?.name ?? "this agent"} responds to.
+            Choose who can send instructions to {agent?.name ?? "this agent"}.
           </DialogDescription>
         </DialogHeader>
         <CreateAgentRespondToField
@@ -66,6 +67,7 @@ export function EditRespondToDialog({
           onAllowlistChange={setRespondToAllowlist}
           onModeChange={setRespondTo}
           ownerPubkey={currentPubkey}
+          runLocation={runLocationForBackend(agent?.backend)}
         />
         {updateMutation.error instanceof Error ? (
           <p className="text-sm text-destructive">
@@ -87,7 +89,7 @@ export function EditRespondToDialog({
             size="sm"
             type="button"
           >
-            {updateMutation.isPending ? "Saving..." : "Save"}
+            {updateMutation.isPending ? "Saving..." : "Save access"}
           </Button>
         </div>
       </DialogContent>
diff --git a/desktop/src/features/channels/ui/MembersSidebarMemberCard.tsx b/desktop/src/features/channels/ui/MembersSidebarMemberCard.tsx
index a332cb8500..b375649292 100644
--- a/desktop/src/features/channels/ui/MembersSidebarMemberCard.tsx
+++ b/desktop/src/features/channels/ui/MembersSidebarMemberCard.tsx
@@ -109,9 +109,9 @@ function formatRespondToLabel(agent: ManagedAgent) {
     case "anyone":
       return "Anyone";
     case "allowlist":
-      return `Allowlist (${agent.respondToAllowlist.length})`;
+      return `Selected people (${agent.respondToAllowlist.length})`;
     default:
-      return "Owner only";
+      return "Only me";
   }
 }
 
@@ -379,7 +379,7 @@ function MemberActionsMenu({
                 onClick={() => onEditRespondTo(managedAgent)}
               >
                 <Pencil className="h-4 w-4" />
-                Edit respond-to...
+                Manage agent access...
               </DropdownMenuItem>
             ) : null}
             {canRemoveMember || showChangeRole ? (
diff --git a/desktop/src/features/channels/unreadReadMarker.test.mjs b/desktop/src/features/channels/unreadReadMarker.test.mjs
index e05e2ba0b2..6ea0916413 100644
--- a/desktop/src/features/channels/unreadReadMarker.test.mjs
+++ b/desktop/src/features/channels/unreadReadMarker.test.mjs
@@ -18,6 +18,7 @@ import {
 } from "./useUnreadChannels.ts";
 import {
   isChannelUnreadTriggerKind,
+  trackSeenEvent,
   withChannelTagFallback,
 } from "./useLiveChannelUpdates.ts";
 import {
@@ -90,6 +91,16 @@ test("live event with h tag is preserved", () => {
   assert.equal(withChannelTagFallback(message, "other-channel"), message);
 });
 
+test("notification event guard suppresses reconnect replay and stays bounded", () => {
+  const seen = new Set();
+
+  assert.equal(trackSeenEvent(seen, "event-a", 2), true);
+  assert.equal(trackSeenEvent(seen, "event-a", 2), false);
+  assert.equal(trackSeenEvent(seen, "event-b", 2), true);
+  assert.equal(trackSeenEvent(seen, "event-c", 2), true);
+  assert.deepEqual([...seen], ["event-b", "event-c"]);
+});
+
 test("dmHuddleStart_isDmOnlyUnreadTrigger", () => {
   assert.equal(
     isChannelUnreadTriggerKind(KIND_HUDDLE_STARTED, true),
diff --git a/desktop/src/features/channels/useChannelPaneHandlers.ts b/desktop/src/features/channels/useChannelPaneHandlers.ts
index 8c5f54fffc..53170257a4 100644
--- a/desktop/src/features/channels/useChannelPaneHandlers.ts
+++ b/desktop/src/features/channels/useChannelPaneHandlers.ts
@@ -25,6 +25,7 @@ export function useChannelPaneHandlers({
   getReplyDescendantIdsForMessage,
   markRevealedRepliesRead,
   onOptimisticOpenThreadHeadIdChange,
+  onRequestEmptyEditDelete,
   openThreadHeadId,
   sendMessageMutation,
   setExpandedThreadReplyIds,
@@ -45,6 +46,7 @@ export function useChannelPaneHandlers({
   onOptimisticOpenThreadHeadIdChange: React.Dispatch<
     React.SetStateAction<string | null | undefined>
   >;
+  onRequestEmptyEditDelete: (eventId: string) => void;
   openThreadHeadId: string | null;
   sendMessageMutation: ReturnType<typeof useSendMessageMutation>;
   setExpandedThreadReplyIds: React.Dispatch<React.SetStateAction<Set<string>>>;
@@ -154,6 +156,22 @@ export function useChannelPaneHandlers({
         return;
       }
 
+      // Clearing an edit to empty (no text, no attachments) is the keyboard
+      // shorthand for "Delete message". Rather than publish an empty edit,
+      // route it through the same "Delete message?" confirmation the Delete
+      // button shows. Keep edit mode active while the dialog is open so Cancel
+      // returns the user to the editor; edit mode is exited only once the
+      // deletion is confirmed (see ChannelScreen's onConfirm). Single decision
+      // point for both the main timeline and thread panel — both route
+      // edit-save through here.
+      const isEmptyDeletion =
+        content.trim().length === 0 &&
+        (mediaTags === undefined || mediaTags.length === 0);
+      if (isEmptyDeletion) {
+        onRequestEmptyEditDelete(eventId);
+        return;
+      }
+
       await editMutateRef.current({
         eventId,
         content,
@@ -162,7 +180,7 @@ export function useChannelPaneHandlers({
       });
       setEditTargetId(null);
     },
-    [setEditTargetId],
+    [onRequestEmptyEditDelete, setEditTargetId],
   );
 
   const handleOpenThread = React.useCallback(
diff --git a/desktop/src/features/channels/useLiveChannelUpdates.ts b/desktop/src/features/channels/useLiveChannelUpdates.ts
index aeb3abb905..800467b6ea 100644
--- a/desktop/src/features/channels/useLiveChannelUpdates.ts
+++ b/desktop/src/features/channels/useLiveChannelUpdates.ts
@@ -110,13 +110,19 @@ function isExternalMentionEvent(event: RelayEvent, currentPubkey: string) {
   );
 }
 
-function trackSeenEvent(seenEventIds: Set<string>, eventId: string): boolean {
+const SEEN_NOTIFICATION_EVENT_LIMIT = 5_000;
+
+export function trackSeenEvent(
+  seenEventIds: Set<string>,
+  eventId: string,
+  limit = 200,
+): boolean {
   if (seenEventIds.has(eventId)) {
     return false;
   }
 
   seenEventIds.add(eventId);
-  if (seenEventIds.size > 200) {
+  if (seenEventIds.size > limit) {
     const oldestEventId = seenEventIds.values().next().value;
     if (oldestEventId) {
       seenEventIds.delete(oldestEventId);
@@ -135,6 +141,11 @@ export function useLiveChannelUpdates(
   const normalizedCurrentPubkey =
     options.currentPubkey?.trim().toLowerCase() ?? "";
   const seenMentionEventIdsRef = React.useRef(new Set<string>());
+  // Reconnect replay overlaps each live filter by five seconds so no message is
+  // lost at the boundary. Keep one shared guard for every notification side
+  // effect: the same event can be replayed repeatedly while a relay flaps, and
+  // mention events also arrive through both the channel and mention filters.
+  const seenNotificationEventIdsRef = React.useRef(new Set<string>());
   const channelsInvalidateRef = React.useRef<TrailingDebounce | null>(null);
   if (channelsInvalidateRef.current === null) {
     channelsInvalidateRef.current = createTrailingDebounce(() => {
@@ -164,7 +175,6 @@ export function useLiveChannelUpdates(
       ),
     [channels],
   );
-  const seenDmEventIdsRef = React.useRef(new Set<string>());
   const dmSubscriptionStartedAtRef = React.useRef(0);
 
   // Reset subscription timestamp when identity changes.
@@ -181,44 +191,42 @@ export function useLiveChannelUpdates(
     [channels],
   );
 
-  const handleDmEvent = React.useEffectEvent((event: RelayEvent) => {
-    // Only human-visible message kinds should fire DM notifications.
-    if (!isDmNotifiableKind(event.kind)) {
-      return;
-    }
-
-    // Suppress backlog events that predate our subscription — these are
-    // historical replays, not live messages.
-    if (event.created_at < dmSubscriptionStartedAtRef.current) {
-      return;
-    }
+  const handleDmEvent = React.useEffectEvent(
+    (event: RelayEvent, isFirstNotificationDelivery: boolean) => {
+      // Only human-visible message kinds should fire DM notifications.
+      if (!isDmNotifiableKind(event.kind) || !isFirstNotificationDelivery) {
+        return;
+      }
 
-    const channelId = getChannelIdFromTags(event.tags);
-    if (!channelId) {
-      return;
-    }
+      // Suppress backlog events that predate our subscription — these are
+      // historical replays, not live messages.
+      if (event.created_at < dmSubscriptionStartedAtRef.current) {
+        return;
+      }
 
-    if (!isExternalMentionEvent(event, normalizedCurrentPubkey)) {
-      return;
-    }
+      const channelId = getChannelIdFromTags(event.tags);
+      if (!channelId) {
+        return;
+      }
 
-    const dmChannel = dmChannelMap.get(channelId);
-    if (!dmChannel) {
-      return;
-    }
+      if (!isExternalMentionEvent(event, normalizedCurrentPubkey)) {
+        return;
+      }
 
-    if (!trackSeenEvent(seenDmEventIdsRef.current, event.id)) {
-      return;
-    }
+      const dmChannel = dmChannelMap.get(channelId);
+      if (!dmChannel) {
+        return;
+      }
 
-    // Don't fire a notification for the channel the user is already viewing,
-    // unless the notify-while-viewing setting opts in.
-    if (channelId === activeChannelId && !options.notifyForActiveChannel) {
-      return;
-    }
+      // Don't fire a notification for the channel the user is already viewing,
+      // unless the notify-while-viewing setting opts in.
+      if (channelId === activeChannelId && !options.notifyForActiveChannel) {
+        return;
+      }
 
-    options.onDmMessage?.(event, dmChannel);
-  });
+      options.onDmMessage?.(event, dmChannel);
+    },
+  );
 
   const handleIncomingMessage = React.useEffectEvent((event: RelayEvent) => {
     const channelId = getChannelIdFromTags(event.tags);
@@ -226,12 +234,6 @@ export function useLiveChannelUpdates(
       return;
     }
 
-    // Track DM events even for the active channel so the dedup set stays
-    // current. The handler itself skips firing the notification callback
-    // when the user is already viewing the DM (unless opted in via
-    // notifyForActiveChannel).
-    handleDmEvent(event);
-
     if (!liveChannelIds.has(channelId)) {
       if (channelId !== activeChannelId) {
         invalidateChannelsDebounced();
@@ -263,9 +265,21 @@ export function useLiveChannelUpdates(
       isUnreadTriggerKind &&
       (normalizedCurrentPubkey.length === 0 ||
         event.pubkey.toLowerCase() !== normalizedCurrentPubkey);
+    const isFirstNotificationDelivery =
+      !isExternalTriggerEvent ||
+      trackSeenEvent(
+        seenNotificationEventIdsRef.current,
+        event.id,
+        SEEN_NOTIFICATION_EVENT_LIMIT,
+      );
     const isThreadedReply = isThreadReply(event.tags);
 
-    if (isExternalTriggerEvent) {
+    // DM alerts and every other notification side effect share this delivery
+    // decision, preventing a replayed event from escaping through a second
+    // callback path.
+    handleDmEvent(event, isFirstNotificationDelivery);
+
+    if (isExternalTriggerEvent && isFirstNotificationDelivery) {
       const shouldNotify = shouldNotifyForEvent(
         event,
         normalizedCurrentPubkey,
diff --git a/desktop/src/features/communities/hostedCommunityApi.ts b/desktop/src/features/communities/hostedCommunityApi.ts
index 16f9f92567..0aca17a17d 100644
--- a/desktop/src/features/communities/hostedCommunityApi.ts
+++ b/desktop/src/features/communities/hostedCommunityApi.ts
@@ -1,7 +1,7 @@
 import { invoke } from "@tauri-apps/api/core";
 
 export const HOSTED_COMMUNITY_SUFFIX = "communities.buzz.xyz";
-export const HOSTED_COMMUNITY_LIMIT = 3;
+export const HOSTED_COMMUNITY_LIMIT = 5;
 export const VALID_HOSTED_COMMUNITY_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
 export type BuilderlabAuth = {
diff --git a/desktop/src/features/communities/useCommunityInit.ts b/desktop/src/features/communities/useCommunityInit.ts
index abb49485d2..afa69f913f 100644
--- a/desktop/src/features/communities/useCommunityInit.ts
+++ b/desktop/src/features/communities/useCommunityInit.ts
@@ -1,4 +1,6 @@
 import { useEffect, useRef, useState } from "react";
+import { isTauri } from "@tauri-apps/api/core";
+import { isMacPlatform } from "@/shared/lib/platform";
 
 import { relayClient } from "@/shared/api/relayClient";
 import { resetRateLimitGate } from "@/shared/api/relayRateLimitGate";
@@ -8,6 +10,7 @@ import {
   getDefaultRelayUrl,
 } from "@/shared/api/tauri";
 import { getIdentity } from "@/shared/api/tauriIdentity";
+import { clearTrayAgentActivity } from "@/shared/api/trayMenu";
 import { getOverrides } from "@/shared/features";
 import { resetMediaCaches } from "@/shared/lib/mediaUrl";
 import { clearSearchHitEventCache } from "@/app/navigation/searchHitEventCache";
@@ -53,6 +56,9 @@ function resetCommunityState({
   resetAgentObserverStore();
   resetActiveAgentTurnsStore();
   resetAgentWorkingSignal();
+  if (isTauri() && isMacPlatform()) {
+    void clearTrayAgentActivity();
+  }
   if (resetAvatarState) {
     resetAvatarProfileSync();
     resetAvatarPresentations();
diff --git a/desktop/src/features/community-members/ui/AddMemberDialog.tsx b/desktop/src/features/community-members/ui/AddMemberDialog.tsx
index 73e5c31b71..76f28e96dd 100644
--- a/desktop/src/features/community-members/ui/AddMemberDialog.tsx
+++ b/desktop/src/features/community-members/ui/AddMemberDialog.tsx
@@ -1,3 +1,5 @@
+import { ChevronDown, Search } from "lucide-react";
+import { AnimatePresence, motion, useReducedMotion } from "motion/react";
 import * as React from "react";
 import { toast } from "sonner";
 
@@ -5,8 +7,13 @@ import {
   useAddRelayMemberMutation,
   useRelayMembersQuery,
 } from "@/features/community-members/hooks";
-import type { RelayMemberRole } from "@/shared/api/types";
-import { cn } from "@/shared/lib/cn";
+import { useIsArchivedPredicate } from "@/features/identity-archive/hooks";
+import { useUserSearchQuery } from "@/features/profile/hooks";
+import { ProfileAvatar } from "@/features/profile/ui/ProfileAvatar";
+import { SelectedRecipientChip } from "@/features/profile/ui/SelectedRecipientChip";
+import type { RelayMemberRole, UserSearchResult } from "@/shared/api/types";
+import { parsePubkeyInput } from "@/shared/lib/nostrUtils";
+import { truncatePubkey } from "@/shared/lib/pubkey";
 import { Button } from "@/shared/ui/button";
 import {
   Dialog,
@@ -15,67 +22,449 @@ import {
   DialogHeader,
   DialogTitle,
 } from "@/shared/ui/dialog";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuTrigger,
+} from "@/shared/ui/dropdown-menu";
 import { Input } from "@/shared/ui/input";
+import { Popover, PopoverAnchor, PopoverContent } from "@/shared/ui/popover";
 
-const PUBKEY_REGEX = /^[0-9a-f]{64}$/;
-
-const ROLE_OPTIONS: Array<{ value: RelayMemberRole; label: string }> = [
-  { value: "member", label: "Member" },
-  { value: "admin", label: "Admin" },
+const ROLE_OPTIONS: Array<{
+  value: RelayMemberRole;
+  label: string;
+}> = [
+  {
+    value: "member",
+    label: "Member",
+  },
+  {
+    value: "admin",
+    label: "Admin",
+  },
 ];
 
-export function AddMemberDialog({
+function formatSearchUserName(user: UserSearchResult) {
+  return (
+    user.displayName?.trim() ||
+    user.nip05Handle?.trim() ||
+    truncatePubkey(user.pubkey)
+  );
+}
+
+export function DirectAddMemberForm({
   isOwner,
-  open,
-  onOpenChange,
+  onAdded,
+  showLabel = true,
+  submitLabel = "Add member",
 }: {
   isOwner: boolean;
-  open: boolean;
-  onOpenChange: (open: boolean) => void;
+  onAdded?: () => void;
+  showLabel?: boolean;
+  submitLabel?: string;
 }) {
   const addMutation = useAddRelayMemberMutation();
   const membersQuery = useRelayMembersQuery();
-  const [pubkey, setPubkey] = React.useState("");
+  const [query, setQuery] = React.useState("");
+  const [selectedUsers, setSelectedUsers] = React.useState<UserSearchResult[]>(
+    [],
+  );
   const [role, setRole] = React.useState<RelayMemberRole>("member");
+  const [isPickerOpen, setIsPickerOpen] = React.useState(false);
+  const searchInputRef = React.useRef<HTMLInputElement>(null);
+  const shouldReduceMotion = useReducedMotion();
 
-  const normalizedPubkey = pubkey.trim().toLowerCase();
-  const isValidPubkey = PUBKEY_REGEX.test(normalizedPubkey);
+  const deferredQuery = React.useDeferredValue(query.trim());
+  const parsedPubkey = parsePubkeyInput(deferredQuery);
+  const userSearchQuery = useUserSearchQuery(deferredQuery, {
+    enabled: deferredQuery.length > 0,
+    limit: 8,
+  });
+  const isArchived = useIsArchivedPredicate();
+  const selectedPubkeys = React.useMemo(
+    () => new Set(selectedUsers.map((user) => user.pubkey.toLowerCase())),
+    [selectedUsers],
+  );
   const isAlreadyMember =
-    isValidPubkey &&
-    !addMutation.isPending &&
+    parsedPubkey !== null &&
     (membersQuery.data ?? []).some(
-      (m) => m.pubkey.toLowerCase() === normalizedPubkey,
+      (m) => m.pubkey.toLowerCase() === parsedPubkey.toLowerCase(),
     );
-  const canAdd = isValidPubkey && !isAlreadyMember && !addMutation.isPending;
+  const canAdd = selectedUsers.length > 0 && !addMutation.isPending;
+  const searchResults = React.useMemo(
+    () =>
+      (userSearchQuery.data ?? []).filter(
+        (user) =>
+          !isArchived(user.pubkey) &&
+          !selectedPubkeys.has(user.pubkey.toLowerCase()) &&
+          !(membersQuery.data ?? []).some(
+            (member) =>
+              member.pubkey.toLowerCase() === user.pubkey.toLowerCase(),
+          ),
+      ),
+    [isArchived, membersQuery.data, selectedPubkeys, userSearchQuery.data],
+  );
+  const directResult = React.useMemo<UserSearchResult | null>(() => {
+    if (
+      parsedPubkey === null ||
+      isAlreadyMember ||
+      selectedPubkeys.has(parsedPubkey.toLowerCase()) ||
+      searchResults.some(
+        (user) => user.pubkey.toLowerCase() === parsedPubkey.toLowerCase(),
+      )
+    ) {
+      return null;
+    }
+    return {
+      pubkey: parsedPubkey,
+      displayName: null,
+      avatarUrl: null,
+      nip05Handle: null,
+      ownerPubkey: null,
+      isAgent: false,
+    };
+  }, [isAlreadyMember, parsedPubkey, searchResults, selectedPubkeys]);
+  const roleOptions = React.useMemo(
+    () => ROLE_OPTIONS.filter((option) => isOwner || option.value === "member"),
+    [isOwner],
+  );
+  const selectedRoleLabel =
+    roleOptions.find((option) => option.value === role)?.label ?? "Member";
+  const actionTransition = shouldReduceMotion
+    ? { duration: 0 }
+    : { duration: 0.18, ease: [0.23, 1, 0.32, 1] as const };
 
   function reset() {
-    setPubkey("");
+    setQuery("");
+    setSelectedUsers([]);
     setRole("member");
+    setIsPickerOpen(false);
     addMutation.reset();
   }
 
-  function handleOpenChange(next: boolean) {
-    if (!next) {
-      reset();
-    }
-    onOpenChange(next);
+  function selectUser(user: UserSearchResult) {
+    setSelectedUsers((currentUsers) =>
+      currentUsers.some(
+        (currentUser) =>
+          currentUser.pubkey.toLowerCase() === user.pubkey.toLowerCase(),
+      )
+        ? currentUsers
+        : [...currentUsers, user],
+    );
+    setQuery("");
+    setIsPickerOpen(true);
+    window.requestAnimationFrame(() => {
+      searchInputRef.current?.focus({ preventScroll: true });
+    });
   }
 
-  function handleAdd() {
-    if (!canAdd) return;
-    addMutation.mutate(
-      { pubkey: normalizedPubkey, role },
-      {
-        onSuccess: () => {
-          toast.success("Member added");
-          handleOpenChange(false);
-        },
-      },
+  function removeUser(pubkey: string) {
+    setSelectedUsers((currentUsers) =>
+      currentUsers.filter(
+        (user) => user.pubkey.toLowerCase() !== pubkey.toLowerCase(),
+      ),
     );
+    searchInputRef.current?.focus({ preventScroll: true });
+  }
+
+  async function handleAdd() {
+    if (!canAdd) return;
+
+    try {
+      for (const user of selectedUsers) {
+        await addMutation.mutateAsync({ pubkey: user.pubkey, role });
+      }
+      toast.success(
+        selectedUsers.length === 1
+          ? role === "admin"
+            ? "Admin added"
+            : "Member added"
+          : role === "admin"
+            ? "Admins added"
+            : "Members added",
+      );
+      reset();
+      onAdded?.();
+    } catch {
+      // The mutation exposes the API error below the field.
+    }
   }
 
   return (
-    <Dialog onOpenChange={handleOpenChange} open={open}>
+    <form
+      className="space-y-4"
+      data-testid="direct-add-member-form"
+      onSubmit={(event) => {
+        event.preventDefault();
+        handleAdd();
+      }}
+    >
+      <div className="space-y-1.5">
+        {showLabel ? (
+          <label className="text-sm font-medium" htmlFor="member-search">
+            Person
+          </label>
+        ) : null}
+        <div className="flex gap-2">
+          <Popover
+            modal={false}
+            onOpenChange={setIsPickerOpen}
+            open={isPickerOpen && deferredQuery.length > 0}
+          >
+            <PopoverAnchor asChild>
+              <div
+                className="min-w-0 flex-1 rounded-md border border-input bg-background focus-within:ring-1 focus-within:ring-ring"
+                data-testid="member-recipient-field"
+              >
+                <div
+                  className={`grid min-h-10 min-w-0 grid-cols-[minmax(0,1fr)_auto] gap-x-3 p-1.5 ${selectedUsers.length > 1 ? "items-start" : "items-center"}`}
+                >
+                  <div className="flex min-w-0 flex-wrap items-center gap-1.5">
+                    {selectedUsers.length === 0 ? (
+                      <Search className="h-4 w-4 shrink-0 text-muted-foreground/55" />
+                    ) : null}
+                    {selectedUsers.map((user) => (
+                      <motion.div
+                        key={user.pubkey}
+                        layout="position"
+                        transition={actionTransition}
+                      >
+                        <SelectedRecipientChip
+                          disabled={addMutation.isPending}
+                          inspectable={false}
+                          label={formatSearchUserName(user)}
+                          onRemove={() => removeUser(user.pubkey)}
+                          poofOnRemove={false}
+                          testIds={{
+                            chip: `member-search-selection-remove-${user.pubkey}`,
+                          }}
+                          user={user}
+                        />
+                      </motion.div>
+                    ))}
+                    <Input
+                      aria-autocomplete="list"
+                      aria-controls="member-search-results"
+                      aria-expanded={isPickerOpen}
+                      autoCapitalize="none"
+                      autoCorrect="off"
+                      className="h-7 w-auto min-w-16 flex-1 border-0 bg-transparent px-0 py-0.5 text-sm shadow-none outline-hidden placeholder:text-muted-foreground/55 focus-visible:ring-0"
+                      data-testid="member-pubkey-input"
+                      disabled={addMutation.isPending}
+                      id="member-search"
+                      onChange={(event) => {
+                        setQuery(event.target.value);
+                        setIsPickerOpen(true);
+                      }}
+                      onFocus={() => setIsPickerOpen(true)}
+                      onKeyDown={(event) => {
+                        if (
+                          event.key === "Backspace" &&
+                          query.length === 0 &&
+                          selectedUsers.length > 0
+                        ) {
+                          event.preventDefault();
+                          const lastUser = selectedUsers.at(-1);
+                          if (lastUser) removeUser(lastUser.pubkey);
+                        }
+                      }}
+                      placeholder={
+                        selectedUsers.length === 0
+                          ? "Search people or paste an npub"
+                          : ""
+                      }
+                      ref={searchInputRef}
+                      role="combobox"
+                      spellCheck={false}
+                      value={query}
+                    />
+                  </div>
+                  <AnimatePresence initial={false}>
+                    {selectedUsers.length > 0 ? (
+                      <motion.div
+                        animate={{ opacity: 1, scale: 1, x: 0 }}
+                        className="shrink-0"
+                        exit={{ opacity: 0, scale: 0.96, x: -4 }}
+                        initial={{ opacity: 0, scale: 0.96, x: -4 }}
+                        transition={actionTransition}
+                      >
+                        <DropdownMenu modal={false}>
+                          <DropdownMenuTrigger asChild>
+                            <button
+                              aria-label="Choose member role"
+                              className="inline-flex items-center gap-1.5 bg-transparent text-sm text-muted-foreground outline-hidden transition-colors hover:text-foreground focus-visible:text-foreground disabled:cursor-not-allowed disabled:opacity-60"
+                              data-testid="member-role"
+                              disabled={addMutation.isPending}
+                              type="button"
+                            >
+                              {selectedRoleLabel}
+                              <ChevronDown className="h-3.5 w-3.5 shrink-0" />
+                            </button>
+                          </DropdownMenuTrigger>
+                          <DropdownMenuContent
+                            align="end"
+                            onCloseAutoFocus={(event) => event.preventDefault()}
+                            sideOffset={4}
+                            style={{ minWidth: "13rem" }}
+                          >
+                            <DropdownMenuRadioGroup
+                              onValueChange={(value) =>
+                                setRole(value as RelayMemberRole)
+                              }
+                              value={role}
+                            >
+                              {roleOptions.map((option) => (
+                                <DropdownMenuRadioItem
+                                  key={option.value}
+                                  value={option.value}
+                                >
+                                  {option.label}
+                                </DropdownMenuRadioItem>
+                              ))}
+                            </DropdownMenuRadioGroup>
+                          </DropdownMenuContent>
+                        </DropdownMenu>
+                      </motion.div>
+                    ) : null}
+                  </AnimatePresence>
+                </div>
+              </div>
+            </PopoverAnchor>
+            <PopoverContent
+              align="start"
+              className="w-(--radix-popover-trigger-width) overflow-hidden p-0"
+              data-testid="member-search-popover"
+              onCloseAutoFocus={(event) => event.preventDefault()}
+              onOpenAutoFocus={(event) => event.preventDefault()}
+              sideOffset={6}
+            >
+              <div
+                className="max-h-64 overflow-y-auto overscroll-contain py-1"
+                data-testid="member-search-results"
+                id="member-search-results"
+                role="listbox"
+              >
+                {userSearchQuery.isLoading ? (
+                  <p className="px-3 py-3 text-sm text-muted-foreground">
+                    Searching…
+                  </p>
+                ) : searchResults.length > 0 || directResult ? (
+                  <>
+                    {directResult ? (
+                      <SearchResult
+                        onSelect={() => selectUser(directResult)}
+                        user={directResult}
+                      />
+                    ) : null}
+                    {searchResults.map((user) => (
+                      <SearchResult
+                        key={user.pubkey}
+                        onSelect={() => selectUser(user)}
+                        user={user}
+                      />
+                    ))}
+                  </>
+                ) : (
+                  <p className="px-3 py-3 text-sm text-muted-foreground">
+                    No people found. Paste a full npub or hex public key to add
+                    someone directly.
+                  </p>
+                )}
+              </div>
+            </PopoverContent>
+          </Popover>
+          <AnimatePresence initial={false}>
+            {selectedUsers.length > 0 ? (
+              <motion.div
+                animate={{ opacity: 1, scale: 1, x: 0 }}
+                className="shrink-0"
+                exit={{ opacity: 0, scale: 0.96, x: -4 }}
+                initial={{ opacity: 0, scale: 0.96, x: -4 }}
+                transition={actionTransition}
+              >
+                <Button
+                  className="h-11"
+                  data-testid="confirm-add-member"
+                  disabled={!canAdd}
+                  size="sm"
+                  type="submit"
+                >
+                  {addMutation.isPending ? "Inviting…" : submitLabel}
+                </Button>
+              </motion.div>
+            ) : null}
+          </AnimatePresence>
+        </div>
+        {isAlreadyMember ? (
+          <p className="text-xs text-destructive">
+            This person is already a community member.
+          </p>
+        ) : null}
+        {userSearchQuery.error instanceof Error ? (
+          <p className="text-xs text-destructive">
+            {userSearchQuery.error.message}
+          </p>
+        ) : null}
+      </div>
+
+      {addMutation.error instanceof Error ? (
+        <p className="rounded-xl border border-destructive/30 bg-destructive/10 px-3 py-2 text-sm text-destructive">
+          {addMutation.error.message}
+        </p>
+      ) : null}
+    </form>
+  );
+}
+
+function SearchResult({
+  onSelect,
+  user,
+}: {
+  onSelect: () => void;
+  user: UserSearchResult;
+}) {
+  const name = formatSearchUserName(user);
+  const isDirectPubkey = user.displayName === null && user.nip05Handle === null;
+
+  return (
+    <button
+      className="flex min-h-11 w-full items-center gap-3 px-3 py-2 text-left transition-colors hover:bg-muted/50 focus-visible:bg-muted/50 focus-visible:outline-hidden"
+      data-testid={`member-search-result-${user.pubkey}`}
+      onClick={onSelect}
+      role="option"
+      type="button"
+    >
+      <ProfileAvatar
+        avatarUrl={user.avatarUrl}
+        className="h-8 w-8 text-xs shadow-none"
+        iconClassName="h-4 w-4"
+        label={name}
+      />
+      <span className="min-w-0 flex-1 truncate text-sm font-medium">
+        {name}
+      </span>
+      {isDirectPubkey ? (
+        <span className="shrink-0 text-xs text-muted-foreground">
+          public key
+        </span>
+      ) : null}
+    </button>
+  );
+}
+
+export function AddMemberDialog({
+  isOwner,
+  open,
+  onOpenChange,
+}: {
+  isOwner: boolean;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}) {
+  return (
+    <Dialog onOpenChange={onOpenChange} open={open}>
       <DialogContent
         className="max-w-md overflow-hidden p-0"
         data-testid="add-relay-member-dialog"
@@ -84,102 +473,15 @@ export function AddMemberDialog({
           <DialogHeader className="border-b border-border/60 px-6 py-5 pr-14">
             <DialogTitle>Add member</DialogTitle>
             <DialogDescription>
-              Add a user to this relay by their public key.
+              Add a person to this community by their public key.
             </DialogDescription>
           </DialogHeader>
-
-          <form
-            className="contents"
-            onSubmit={(e) => {
-              e.preventDefault();
-              handleAdd();
-            }}
-          >
-            <div className="flex-1 overflow-y-auto px-6 py-4">
-              <div className="space-y-4">
-                <div className="space-y-1.5">
-                  <label
-                    className="text-sm font-medium"
-                    htmlFor="member-pubkey"
-                  >
-                    Public key
-                  </label>
-                  <Input
-                    autoCapitalize="none"
-                    autoCorrect="off"
-                    data-testid="member-pubkey-input"
-                    id="member-pubkey"
-                    maxLength={64}
-                    onChange={(e) => setPubkey(e.target.value)}
-                    placeholder="64-character hex pubkey"
-                    spellCheck={false}
-                    value={pubkey}
-                  />
-                  {pubkey.trim().length > 0 && !isValidPubkey ? (
-                    <p className="text-xs text-destructive">
-                      Must be exactly 64 lowercase hex characters.
-                    </p>
-                  ) : null}
-                  {isAlreadyMember ? (
-                    <p className="text-xs text-destructive">
-                      This pubkey is already a relay member.
-                    </p>
-                  ) : null}
-                </div>
-
-                <div className="space-y-1.5">
-                  <p className="text-sm font-medium">Role</p>
-                  <div className="flex gap-2">
-                    {ROLE_OPTIONS.filter(
-                      (opt) => isOwner || opt.value === "member",
-                    ).map((opt) => (
-                      <button
-                        aria-pressed={role === opt.value}
-                        className={cn(
-                          "rounded-lg border px-3 py-1.5 text-sm transition-colors",
-                          role === opt.value
-                            ? "border-primary bg-primary/10 text-foreground"
-                            : "border-border/60 text-muted-foreground hover:bg-accent",
-                        )}
-                        data-testid={`member-role-${opt.value}`}
-                        key={opt.value}
-                        onClick={() => setRole(opt.value)}
-                        type="button"
-                      >
-                        {opt.label}
-                      </button>
-                    ))}
-                  </div>
-                </div>
-
-                {addMutation.error instanceof Error ? (
-                  <p className="rounded-xl border border-destructive/30 bg-destructive/10 px-3 py-2 text-sm text-destructive">
-                    {addMutation.error.message}
-                  </p>
-                ) : null}
-              </div>
-            </div>
-
-            <div className="flex justify-end gap-2 border-t border-border/60 bg-background/95 px-6 py-4">
-              <Button
-                data-testid="cancel-add-member"
-                onClick={() => handleOpenChange(false)}
-                size="sm"
-                type="button"
-                variant="outline"
-              >
-                Cancel
-              </Button>
-              <Button
-                data-testid="confirm-add-member"
-                disabled={!canAdd}
-                size="sm"
-                type="submit"
-              >
-                {addMutation.isPending ? "Adding..." : "Add member"}
-              </Button>
-            </div>
-          </form>
+          <div className="px-6 py-4">
+            <DirectAddMemberForm
+              isOwner={isOwner}
+              onAdded={() => onOpenChange(false)}
+            />
+          </div>
         </div>
       </DialogContent>
     </Dialog>
diff --git a/desktop/src/features/community-members/ui/CommunityInviteDialog.tsx b/desktop/src/features/community-members/ui/CommunityInviteDialog.tsx
index bd23e2bbec..c5cabc26a6 100644
--- a/desktop/src/features/community-members/ui/CommunityInviteDialog.tsx
+++ b/desktop/src/features/community-members/ui/CommunityInviteDialog.tsx
@@ -3,23 +3,25 @@ import * as React from "react";
 import {
   Dialog,
   DialogContent,
+  DialogDescription,
   DialogHeader,
   DialogTitle,
 } from "@/shared/ui/dialog";
+import { DirectAddMemberForm } from "./AddMemberDialog";
 import {
   DEFAULT_INVITE_TTL_SECS,
   InviteLinkSection,
 } from "./InviteLinkSection";
 
 export function CommunityInviteDialog({
+  isOwner,
   onOpenChange,
   open,
 }: {
+  isOwner: boolean;
   onOpenChange: (open: boolean) => void;
   open: boolean;
 }) {
-  // Email delivery is not available yet, so the modal only mints shareable
-  // invite links through the relay's existing invite flow.
   const [ttlSecs, setTtlSecs] = React.useState(DEFAULT_INVITE_TTL_SECS);
 
   React.useEffect(() => {
@@ -29,15 +31,30 @@ export function CommunityInviteDialog({
   return (
     <Dialog onOpenChange={onOpenChange} open={open}>
       <DialogContent
-        aria-describedby={undefined}
         className="max-h-[85vh] max-w-xl overflow-y-auto"
         data-testid="community-invite-dialog"
       >
-        <DialogHeader className="space-y-0">
+        <DialogHeader>
           <DialogTitle>Invite to community</DialogTitle>
+          <DialogDescription>
+            Add someone directly or share a link they can use to join.
+          </DialogDescription>
         </DialogHeader>
 
-        <InviteLinkSection onTtlSecsChange={setTtlSecs} ttlSecs={ttlSecs} />
+        <section className="mt-2 space-y-3">
+          <DirectAddMemberForm
+            isOwner={isOwner}
+            showLabel={false}
+            submitLabel="Invite"
+          />
+        </section>
+
+        <section className="space-y-3">
+          <p className="text-2xs font-medium text-secondary-foreground/75">
+            Link settings
+          </p>
+          <InviteLinkSection onTtlSecsChange={setTtlSecs} ttlSecs={ttlSecs} />
+        </section>
       </DialogContent>
     </Dialog>
   );
diff --git a/desktop/src/features/community-members/ui/CommunityMembersSettingsCard.tsx b/desktop/src/features/community-members/ui/CommunityMembersSettingsCard.tsx
index 9097f35387..d861fae802 100644
--- a/desktop/src/features/community-members/ui/CommunityMembersSettingsCard.tsx
+++ b/desktop/src/features/community-members/ui/CommunityMembersSettingsCard.tsx
@@ -11,6 +11,7 @@ import {
 } from "@/features/community-members/hooks";
 import { useUsersBatchQuery } from "@/features/profile/hooks";
 import { ProfileAvatar } from "@/features/profile/ui/ProfileAvatar";
+import { UserProfilePopover } from "@/features/profile/ui/UserProfilePopover";
 import { SettingsSectionHeader } from "@/features/settings/ui/SettingsSectionHeader";
 import type {
   RelayMember,
@@ -129,11 +130,17 @@ function RelayMemberRow({
       className="group/member flex min-h-14 items-center gap-3 px-1 py-2.5"
       data-testid={`relay-member-row-${member.pubkey}`}
     >
-      <ProfileAvatar
-        avatarUrl={profile?.avatarUrl ?? null}
-        className="h-9 w-9 text-xs shadow-none"
-        label={displayName}
-      />
+      <UserProfilePopover
+        pubkey={member.pubkey}
+        triggerAriaLabel={`Open profile for ${displayName}`}
+        triggerElement="span"
+      >
+        <ProfileAvatar
+          avatarUrl={profile?.avatarUrl ?? null}
+          className="h-9 w-9 text-xs shadow-none"
+          label={displayName}
+        />
+      </UserProfilePopover>
       <div className="min-w-0 flex-1">
         <div className="flex min-w-0 items-center gap-1.5 text-sm font-medium">
           <HoverMemberIdentity
@@ -370,6 +377,7 @@ export function CommunityMembersSettingsCard({
       </div>
 
       <CommunityInviteDialog
+        isOwner={currentRole === "owner"}
         onOpenChange={setInviteDialogOpen}
         open={inviteDialogOpen}
       />
diff --git a/desktop/src/features/community-members/ui/InviteLinkSection.tsx b/desktop/src/features/community-members/ui/InviteLinkSection.tsx
index c4e140f723..05b4687289 100644
--- a/desktop/src/features/community-members/ui/InviteLinkSection.tsx
+++ b/desktop/src/features/community-members/ui/InviteLinkSection.tsx
@@ -8,16 +8,12 @@ import { Button } from "@/shared/ui/button";
 import {
   DropdownMenu,
   DropdownMenuContent,
-  DropdownMenuLabel,
   DropdownMenuRadioGroup,
   DropdownMenuRadioItem,
-  DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "@/shared/ui/dropdown-menu";
-import { Input } from "@/shared/ui/input";
 import { Separator } from "@/shared/ui/separator";
 import { Spinner } from "@/shared/ui/spinner";
-import { Switch } from "@/shared/ui/switch";
 
 const TTL_OPTIONS: { label: string; value: number }[] = [
   { label: "1 day", value: 24 * 60 * 60 },
@@ -26,6 +22,15 @@ const TTL_OPTIONS: { label: string; value: number }[] = [
   { label: "30 days", value: 30 * 24 * 60 * 60 },
 ];
 
+const MAX_USE_OPTIONS: { label: string; value: number | null }[] = [
+  { label: "No limit", value: null },
+  { label: "1 use", value: 1 },
+  { label: "3 uses", value: 3 },
+  { label: "5 uses", value: 5 },
+  { label: "10 uses", value: 10 },
+  { label: "25 uses", value: 25 },
+];
+
 export const DEFAULT_INVITE_TTL_SECS = TTL_OPTIONS[1].value;
 
 type CopyStatus = "idle" | "copying" | "copied";
@@ -45,16 +50,12 @@ export function InviteLinkSection({
   ttlSecs: number;
 }) {
   const [copyStatus, setCopyStatus] = React.useState<CopyStatus>("idle");
-  const [maxUsesEnabled, setMaxUsesEnabled] = React.useState(true);
-  const [maxUsesInput, setMaxUsesInput] = React.useState("3");
-  const parsedMaxUses = Number(maxUsesInput);
-  const maxUsesValid =
-    !maxUsesEnabled ||
-    (Number.isInteger(parsedMaxUses) &&
-      parsedMaxUses >= 1 &&
-      parsedMaxUses <= 10000);
+  const [maxUses, setMaxUses] = React.useState<number | null>(null);
   const ttlLabel =
     TTL_OPTIONS.find((option) => option.value === ttlSecs)?.label ?? "3 days";
+  const maxUsesLabel =
+    MAX_USE_OPTIONS.find((option) => option.value === maxUses)?.label ??
+    "No limit";
   const copyLabel =
     copyStatus === "copying"
       ? "Copying…"
@@ -69,13 +70,10 @@ export function InviteLinkSection({
   }, [copyStatus]);
 
   async function handleCopy() {
-    if (copyStatus === "copying" || !maxUsesValid) return;
+    if (copyStatus === "copying") return;
     setCopyStatus("copying");
     try {
-      const invite = await mintInvite({
-        ttlSecs,
-        maxUses: maxUsesEnabled ? parsedMaxUses : null,
-      });
+      const invite = await mintInvite({ ttlSecs, maxUses });
       await writeTextToClipboard(invite.url);
       setCopyStatus("copied");
       toast.success("Invite link copied");
@@ -86,83 +84,80 @@ export function InviteLinkSection({
   }
 
   return (
-    <section className="pt-2" data-testid="community-invite-link-section">
-      <div className="flex items-center gap-3">
-        <span className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-muted text-muted-foreground">
-          <Link2 aria-hidden="true" className="h-4 w-4" />
-        </span>
-        <div className="min-w-0 flex-1">
-          <h3 className="text-sm font-medium">Share with a link</h3>
-          <p className="text-xs text-secondary-foreground/75">
-            Anyone with the link can join this community.
-          </p>
+    <section data-testid="community-invite-link-section">
+      <div className="space-y-3">
+        <div className="flex items-center justify-between gap-4">
+          <span className="text-sm font-medium">Expires after</span>
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button
+                aria-label="Choose invite expiry"
+                className="h-8 shrink-0 gap-1.5 px-2 text-sm text-muted-foreground"
+                data-testid="invite-link-ttl-trigger"
+                disabled={copyStatus === "copying"}
+                size="sm"
+                type="button"
+                variant="ghost"
+              >
+                {ttlLabel}
+                <ChevronDown aria-hidden="true" className="h-3.5 w-3.5" />
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end" className="w-40">
+              <DropdownMenuRadioGroup
+                onValueChange={(value) => onTtlSecsChange(Number(value))}
+                value={String(ttlSecs)}
+              >
+                {TTL_OPTIONS.map((option) => (
+                  <DropdownMenuRadioItem
+                    data-testid={`invite-link-ttl-${option.value}`}
+                    key={option.value}
+                    value={String(option.value)}
+                  >
+                    {option.label}
+                  </DropdownMenuRadioItem>
+                ))}
+              </DropdownMenuRadioGroup>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </div>
+        <div className="flex items-center justify-between gap-4">
+          <span className="text-sm font-medium">Limit number of uses</span>
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button
+                aria-label="Choose maximum invite uses"
+                className="h-8 shrink-0 gap-1.5 px-2 text-sm text-muted-foreground"
+                data-testid="invite-link-max-uses-trigger"
+                disabled={copyStatus === "copying"}
+                size="sm"
+                type="button"
+                variant="ghost"
+              >
+                {maxUsesLabel}
+                <ChevronDown aria-hidden="true" className="h-3.5 w-3.5" />
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end" className="w-40">
+              <DropdownMenuRadioGroup
+                onValueChange={(value) =>
+                  setMaxUses(value === "no-limit" ? null : Number(value))
+                }
+                value={String(maxUses ?? "no-limit")}
+              >
+                {MAX_USE_OPTIONS.map((option) => (
+                  <DropdownMenuRadioItem
+                    data-testid={`invite-link-max-uses-${option.value ?? "no-limit"}`}
+                    key={option.value ?? "no-limit"}
+                    value={String(option.value ?? "no-limit")}
+                  >
+                    {option.label}
+                  </DropdownMenuRadioItem>
+                ))}
+              </DropdownMenuRadioGroup>
+            </DropdownMenuContent>
+          </DropdownMenu>
         </div>
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            <Button
-              aria-label="Choose invite expiry"
-              className="h-8 shrink-0 gap-1.5 px-2 text-muted-foreground"
-              data-testid="invite-link-ttl-trigger"
-              disabled={copyStatus === "copying"}
-              size="sm"
-              type="button"
-              variant="ghost"
-            >
-              {ttlLabel}
-              <ChevronDown aria-hidden="true" className="h-3.5 w-3.5" />
-            </Button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent align="end" className="w-40">
-            <DropdownMenuLabel>Expires after</DropdownMenuLabel>
-            <DropdownMenuSeparator />
-            <DropdownMenuRadioGroup
-              onValueChange={(value) => onTtlSecsChange(Number(value))}
-              value={String(ttlSecs)}
-            >
-              {TTL_OPTIONS.map((option) => (
-                <DropdownMenuRadioItem
-                  data-testid={`invite-link-ttl-${option.value}`}
-                  key={option.value}
-                  value={String(option.value)}
-                >
-                  {option.label}
-                </DropdownMenuRadioItem>
-              ))}
-            </DropdownMenuRadioGroup>
-          </DropdownMenuContent>
-        </DropdownMenu>
-      </div>
-      <div className="mt-3 flex items-center gap-2 text-xs">
-        <Switch
-          checked={maxUsesEnabled}
-          data-testid="invite-link-max-uses-switch"
-          id="invite-max-uses"
-          onCheckedChange={setMaxUsesEnabled}
-        />
-        <label className="text-muted-foreground" htmlFor="invite-max-uses">
-          Limit uses
-        </label>
-        {maxUsesEnabled ? (
-          <Input
-            className="h-7 w-20"
-            data-testid="invite-link-max-uses-input"
-            inputMode="numeric"
-            max={10000}
-            min={1}
-            onChange={(event) => setMaxUsesInput(event.target.value)}
-            placeholder="3"
-            type="number"
-            value={maxUsesInput}
-          />
-        ) : null}
-        {maxUsesEnabled && !maxUsesValid ? (
-          <span
-            className="text-destructive"
-            data-testid="invite-link-max-uses-error"
-          >
-            Enter a whole number from 1 to 10,000
-          </span>
-        ) : null}
       </div>
       <Separator className="my-4 bg-input/40" />
       <div className="flex justify-end">
@@ -170,7 +165,7 @@ export function InviteLinkSection({
           className="shrink-0 border-border shadow-none"
           data-copy-status={copyStatus}
           data-testid="copy-invite-link"
-          disabled={copyStatus === "copying" || !maxUsesValid}
+          disabled={copyStatus === "copying"}
           onClick={() => void handleCopy()}
           size="sm"
           type="button"
diff --git a/desktop/src/features/huddle/HuddleContext.tsx b/desktop/src/features/huddle/HuddleContext.tsx
index 804eb4bc0e..03620838a3 100644
--- a/desktop/src/features/huddle/HuddleContext.tsx
+++ b/desktop/src/features/huddle/HuddleContext.tsx
@@ -339,6 +339,28 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
     [],
   );
 
+  /**
+   * Clean up only this provider's media after its start token is superseded.
+   * The action that changed the token owns backend teardown; issuing a global
+   * leave here could terminate a replacement huddle started by a new provider.
+   */
+  const cleanupSupersededStart = React.useCallback(
+    (worklet: AudioWorkletHandle | null) => {
+      try {
+        worklet?.stop();
+      } catch {
+        /* best-effort */
+      }
+      workletRef.current = null;
+      rustActiveRef.current = false;
+      setLocalAudioTrack(null);
+      setMicConnected(false);
+      setEphemeralChannelId(null);
+      setActiveSpeakers([]);
+    },
+    [],
+  );
+
   /** Shared media setup: get mic, setup AudioWorklet, confirm active.
    *  Used by both startHuddle and joinHuddle after the Rust backend call succeeds. */
   const connectAndSetupMedia = React.useCallback(
@@ -443,7 +465,7 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
           await connectAndSetupMedia(joinInfo, myToken);
         } catch (e) {
           if (e instanceof Error && e.message === "superseded") {
-            await cleanupFailedStart(workletRef.current, true);
+            cleanupSupersededStart(workletRef.current);
             return;
           }
           throw e;
@@ -466,7 +488,7 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
         busyRef.current = false;
       }
     },
-    [cleanupFailedStart, connectAndSetupMedia],
+    [cleanupFailedStart, cleanupSupersededStart, connectAndSetupMedia],
   );
 
   const joinHuddle = React.useCallback(
@@ -489,7 +511,7 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
           await connectAndSetupMedia(joinInfo, myToken);
         } catch (e) {
           if (e instanceof Error && e.message === "superseded") {
-            await cleanupFailedStart(workletRef.current, false);
+            cleanupSupersededStart(workletRef.current);
             return;
           }
           throw e;
@@ -512,7 +534,7 @@ export function HuddleProvider({ children }: { children: React.ReactNode }) {
         busyRef.current = false;
       }
     },
-    [cleanupFailedStart, connectAndSetupMedia],
+    [cleanupFailedStart, cleanupSupersededStart, connectAndSetupMedia],
   );
 
   useTtsSubscription(ephemeralChannelId, selfPubkeyRef);
diff --git a/desktop/src/features/huddle/components/HuddleBar.tsx b/desktop/src/features/huddle/components/HuddleBar.tsx
index 35d660e475..758726cf58 100644
--- a/desktop/src/features/huddle/components/HuddleBar.tsx
+++ b/desktop/src/features/huddle/components/HuddleBar.tsx
@@ -242,7 +242,10 @@ export function HuddleBar({
 
     // Primary: listen for Rust-emitted state change events
     listen<HuddleState>("huddle-state-changed", (event) => {
-      if (!cancelled) applyIncomingState(event.payload);
+      if (!cancelled) {
+        stateGenerationRef.current += 1;
+        applyIncomingState(event.payload);
+      }
     }).then((fn) => {
       if (cancelled) fn();
       else unlisten = fn;
@@ -757,14 +760,11 @@ export function HuddleBar({
                   transcriptionEnabled ? "Stop transcript" : "Start transcript"
                 }
                 aria-pressed={transcriptionEnabled}
-                className={cn(
-                  "buzz-huddle-control-button h-12 w-12 shrink-0 rounded-md",
-                  transcriptionEnabled && "text-foreground",
-                )}
+                className="buzz-huddle-control-button h-12 w-12 shrink-0 rounded-md"
                 onClick={() => void handleToggleTranscript()}
                 size="icon"
                 type="button"
-                variant={transcriptionEnabled ? "secondary" : "ghost"}
+                variant="ghost"
               >
                 <Captions className="h-4 w-4" />
               </Button>
diff --git a/desktop/src/features/huddle/components/ParticipantList.tsx b/desktop/src/features/huddle/components/ParticipantList.tsx
index c445711dfc..9454f51f5b 100644
--- a/desktop/src/features/huddle/components/ParticipantList.tsx
+++ b/desktop/src/features/huddle/components/ParticipantList.tsx
@@ -3,6 +3,7 @@ import * as React from "react";
 
 import { useUsersBatchQuery } from "@/features/profile/hooks";
 import { ProfileAvatar } from "@/features/profile/ui/ProfileAvatar";
+import { UserProfilePopover } from "@/features/profile/ui/UserProfilePopover";
 import { cn } from "@/shared/lib/cn";
 import { Button } from "@/shared/ui/button";
 import { Popover, PopoverContent, PopoverTrigger } from "@/shared/ui/popover";
@@ -86,19 +87,25 @@ export function HuddleParticipantsControl({
                 className="flex min-w-0 items-center gap-2 rounded-md px-2 py-1.5"
                 key={pubkey}
               >
-                {profile?.displayName || profile?.avatarUrl ? (
-                  <ProfileAvatar
-                    avatarUrl={profile.avatarUrl ?? null}
-                    label={profile.displayName || pubkey.slice(0, 6)}
-                    className={cn(
-                      "h-8 w-8 rounded-full text-2xs",
-                      isActive &&
-                        "ring-2 ring-green-500 ring-offset-1 ring-offset-background",
-                    )}
-                  />
-                ) : (
-                  <HexAvatar pubkey={pubkey} isActive={isActive} size="lg" />
-                )}
+                <UserProfilePopover
+                  pubkey={pubkey}
+                  triggerAriaLabel={`Open profile for ${displayName}`}
+                  triggerElement="span"
+                >
+                  {profile?.displayName || profile?.avatarUrl ? (
+                    <ProfileAvatar
+                      avatarUrl={profile.avatarUrl ?? null}
+                      label={profile.displayName || truncatePubkey(pubkey)}
+                      className={cn(
+                        "h-8 w-8 rounded-full text-2xs",
+                        isActive &&
+                          "ring-2 ring-green-500 ring-offset-1 ring-offset-background",
+                      )}
+                    />
+                  ) : (
+                    <HexAvatar pubkey={pubkey} isActive={isActive} size="lg" />
+                  )}
+                </UserProfilePopover>
 
                 <div className="min-w-0 flex-1">
                   <div className="truncate text-sm font-medium">
diff --git a/desktop/src/features/huddle/lib/ttsLiveMessages.test.mjs b/desktop/src/features/huddle/lib/ttsLiveMessages.test.mjs
new file mode 100644
index 0000000000..8bacceff9c
--- /dev/null
+++ b/desktop/src/features/huddle/lib/ttsLiveMessages.test.mjs
@@ -0,0 +1,271 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  classifySpeakableAgentText,
+  createInitialTtsReadinessGate,
+  createLatestStateGate,
+  createOrderedSpeaker,
+  routeLiveAgentText,
+} from "./ttsLiveMessages.ts";
+
+const agents = new Set(["agent"]);
+const CHANNEL = "active-huddle";
+const base = {
+  id: "1",
+  kind: 9,
+  pubkey: "agent",
+  content: "Hello there",
+  tags: [["h", CHANNEL]],
+};
+const speakableText = (event, selfPubkey = "human") =>
+  classifySpeakableAgentText(event, agents, selfPubkey, CHANNEL).text;
+
+test("speaks only new agent-authored text message events", () => {
+  assert.equal(speakableText(base), "Hello there");
+  assert.equal(
+    speakableText({ ...base, kind: 40002 }),
+    "Hello there",
+    "managed stream-message-v2 replies are spoken",
+  );
+  assert.equal(
+    speakableText({ ...base, kind: 7 }),
+    null,
+    "reactions and other event kinds are excluded",
+  );
+  assert.equal(
+    speakableText({ ...base, kind: 10 }),
+    null,
+    "edits and status events are excluded",
+  );
+  assert.equal(
+    speakableText({ ...base, pubkey: "human" }),
+    null,
+    "human-authored messages are excluded",
+  );
+  assert.equal(
+    speakableText({ ...base, content: " " }),
+    null,
+    "empty and non-text content are excluded",
+  );
+  assert.equal(
+    speakableText({ ...base, content: "K" }),
+    "K",
+    "one-character agent text remains speakable",
+  );
+  assert.equal(
+    speakableText({ ...base, content: "[System] tool started" }),
+    null,
+    "legacy system rows are excluded",
+  );
+  assert.equal(
+    speakableText({ ...base, tags: [["h", "another-huddle"]] }),
+    null,
+    "messages for another huddle are excluded",
+  );
+});
+
+test("routes managed stream-message-v2 through membership and enabled ordering", async () => {
+  const invoked = [];
+  const speaker = createOrderedSpeaker(async (text, routeId) => {
+    invoked.push({ text, routeId });
+  }, assert.fail);
+
+  assert.equal(
+    routeLiveAgentText(
+      { ...base, kind: 40002 },
+      agents,
+      "human",
+      CHANNEL,
+      77,
+      speaker.enqueue,
+    ),
+    "queued",
+  );
+  assert.equal(
+    routeLiveAgentText(
+      { ...base, kind: 7 },
+      agents,
+      "human",
+      CHANNEL,
+      78,
+      speaker.enqueue,
+    ),
+    "unsupported_kind",
+  );
+  assert.equal(
+    routeLiveAgentText(
+      { ...base, tags: [["h", "wrong"]] },
+      agents,
+      "human",
+      CHANNEL,
+      79,
+      speaker.enqueue,
+    ),
+    "h_tag_mismatch",
+  );
+  assert.equal(
+    routeLiveAgentText(
+      { ...base, pubkey: "human" },
+      agents,
+      "human",
+      CHANNEL,
+      80,
+      speaker.enqueue,
+    ),
+    "author_not_agent",
+  );
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(invoked, [{ text: "Hello there", routeId: 77 }]);
+});
+
+test("strips attachment markup and skips attachment-only events", () => {
+  const url = "https://cdn.example/voice.png";
+  const tags = [...base.tags, ["imeta", `url ${url}`, "m image/png"]];
+  assert.equal(
+    speakableText({ ...base, content: `![image](${url})`, tags }),
+    null,
+  );
+  assert.equal(
+    speakableText({
+      ...base,
+      content: `Here is the diagram.\n\n![image](${url})`,
+      tags,
+    }),
+    "Here is the diagram.",
+  );
+  assert.equal(
+    speakableText({ ...base, content: `||\n![image](${url})\n||`, tags }),
+    null,
+  );
+});
+
+test("queues agent messages in live thread arrival order", async () => {
+  const spoken = [];
+  let releaseFirst;
+  const firstBlocked = new Promise((resolve) => {
+    releaseFirst = resolve;
+  });
+  const speaker = createOrderedSpeaker(async (text, routeId) => {
+    if (text === "first") await firstBlocked;
+    spoken.push([text, routeId]);
+  }, assert.fail);
+
+  speaker.enqueue("first", 41);
+  speaker.enqueue("second", 42);
+  await Promise.resolve();
+  assert.deepEqual(spoken, []);
+  releaseFirst();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(spoken, [
+    ["first", 41],
+    ["second", 42],
+  ]);
+});
+
+test("disabling cancels queued speech and rejects new messages until enabled", async () => {
+  const invoked = [];
+  const dropped = [];
+  let releaseFirst;
+  const firstBlocked = new Promise((resolve) => {
+    releaseFirst = resolve;
+  });
+  const speaker = createOrderedSpeaker(
+    async (text) => {
+      invoked.push(text);
+      if (text === "first") await firstBlocked;
+    },
+    assert.fail,
+    true,
+    (routeId, reason) => dropped.push([routeId, reason]),
+  );
+
+  speaker.enqueue("first", 51);
+  speaker.enqueue("queued-before-off", 52);
+  await Promise.resolve();
+  speaker.setEnabled(false);
+  speaker.enqueue("while-off");
+  releaseFirst();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  speaker.setEnabled(true);
+  speaker.enqueue("after-on");
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(invoked, ["first", "after-on"]);
+  assert.deepEqual(dropped, [[52, "disabled"]]);
+});
+
+test("does not speak before the native enabled state is known", async () => {
+  const invoked = [];
+  const speaker = createOrderedSpeaker(
+    async (text) => invoked.push(text),
+    assert.fail,
+    false,
+  );
+
+  speaker.enqueue("before-state");
+  await Promise.resolve();
+  speaker.setEnabled(true);
+  speaker.enqueue("after-state");
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(invoked, ["after-state"]);
+});
+
+test("a live TTS state event supersedes a delayed bootstrap result", () => {
+  const applied = [];
+  const gate = createLatestStateGate((enabled) => applied.push(enabled));
+  const applyBootstrap = gate.beginSnapshot();
+
+  gate.applyEvent(false);
+  applyBootstrap(true);
+
+  assert.deepEqual(applied, [false]);
+});
+
+test("buffers initial live events until membership and TTS state resolve", () => {
+  const delivered = [];
+  const gate = createInitialTtsReadinessGate((event) => delivered.push(event));
+  gate.push("first");
+  gate.push("second");
+  assert.deepEqual(delivered, []);
+  gate.markMembershipKnown();
+  assert.deepEqual(delivered, []);
+  gate.markTtsStateKnown();
+  gate.push("third");
+  assert.deepEqual(delivered, ["first", "second", "third"]);
+});
+
+test("preserves the first agent reply when membership resolves before TTS state", async () => {
+  const spoken = [];
+  const speaker = createOrderedSpeaker(
+    async (text) => spoken.push(text),
+    assert.fail,
+    false,
+  );
+  const gate = createInitialTtsReadinessGate((text) =>
+    speaker.enqueue(text, 1),
+  );
+
+  gate.push("first agent reply");
+  gate.markMembershipKnown();
+  speaker.setEnabled(true);
+  gate.markTtsStateKnown();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  assert.deepEqual(spoken, ["first agent reply"]);
+});
+
+test("drops the initial buffer fail-closed with the readiness failure", () => {
+  const delivered = [];
+  const dropped = [];
+  const gate = createInitialTtsReadinessGate(
+    (event) => delivered.push(event),
+    (event, reason) => dropped.push({ event, reason }),
+  );
+  gate.push("unverified");
+  gate.fail("tts_state_unavailable");
+  gate.push("after-failure");
+  assert.deepEqual(delivered, ["after-failure"]);
+  assert.deepEqual(dropped, [
+    { event: "unverified", reason: "tts_state_unavailable" },
+  ]);
+});
diff --git a/desktop/src/features/huddle/lib/ttsLiveMessages.ts b/desktop/src/features/huddle/lib/ttsLiveMessages.ts
new file mode 100644
index 0000000000..5a5a29afa5
--- /dev/null
+++ b/desktop/src/features/huddle/lib/ttsLiveMessages.ts
@@ -0,0 +1,200 @@
+import {
+  KIND_STREAM_MESSAGE,
+  KIND_STREAM_MESSAGE_V2,
+} from "../../../shared/constants/kinds.ts";
+
+export type LiveTtsEvent = {
+  id: string;
+  kind: number;
+  pubkey: string;
+  content: string;
+  tags: string[][];
+};
+
+export type LiveTtsEligibility =
+  | { text: string; reason: null }
+  | {
+      text: null;
+      reason:
+        | "unsupported_kind"
+        | "h_tag_mismatch"
+        | "author_not_agent"
+        | "self_authored"
+        | "empty_or_system";
+    };
+
+export type LiveTtsRouteResult =
+  | "queued"
+  | "disabled"
+  | Exclude<LiveTtsEligibility, { text: string }>["reason"];
+
+function textWithoutAttachments(event: LiveTtsEvent): string {
+  const urls = new Set(
+    event.tags
+      .filter((tag) => tag[0] === "imeta")
+      .flatMap((tag) =>
+        tag
+          .slice(1)
+          .filter((field) => field.startsWith("url "))
+          .map((field) => field.slice(4)),
+      ),
+  );
+  if (urls.size === 0) return event.content;
+  const withoutMedia = event.content
+    .split("\n")
+    .filter(
+      (line) => !Array.from(urls).some((url) => line.includes(`](${url})`)),
+    )
+    .join("\n");
+  return withoutMedia.replace(
+    /(^|\n)\s*\|\|\s*\n(?:\s*\n)*\s*\|\|\s*(?=\n|$)/gu,
+    "$1",
+  );
+}
+
+export function classifySpeakableAgentText(
+  event: LiveTtsEvent,
+  agentPubkeys: ReadonlySet<string>,
+  selfPubkey: string | null,
+  channelId: string,
+): LiveTtsEligibility {
+  if (
+    event.kind !== KIND_STREAM_MESSAGE &&
+    event.kind !== KIND_STREAM_MESSAGE_V2
+  )
+    return { text: null, reason: "unsupported_kind" };
+  if (!event.tags.some((tag) => tag[0] === "h" && tag[1] === channelId))
+    return { text: null, reason: "h_tag_mismatch" };
+  if (!agentPubkeys.has(event.pubkey))
+    return { text: null, reason: "author_not_agent" };
+  if (event.pubkey === selfPubkey)
+    return { text: null, reason: "self_authored" };
+  const content = textWithoutAttachments(event).trim();
+  if (content.length === 0 || content.startsWith("[System]"))
+    return { text: null, reason: "empty_or_system" };
+  return { text: content, reason: null };
+}
+
+/** Classify and enqueue one live event through the production routing seam. */
+export function routeLiveAgentText(
+  event: LiveTtsEvent,
+  agentPubkeys: ReadonlySet<string>,
+  selfPubkey: string | null,
+  channelId: string,
+  routeId: number,
+  enqueue: (text: string, routeId: number) => "queued" | "disabled",
+): LiveTtsRouteResult {
+  const eligibility = classifySpeakableAgentText(
+    event,
+    agentPubkeys,
+    selfPubkey,
+    channelId,
+  );
+  if (eligibility.text === null) return eligibility.reason;
+  return enqueue(eligibility.text, routeId);
+}
+
+/**
+ * Serialize native speak calls so live messages enter the bounded Pocket queue
+ * in thread arrival order even when the bridge resolves calls asynchronously.
+ */
+export function createOrderedSpeaker(
+  speak: (text: string, routeId: number) => Promise<void>,
+  onError: (error: unknown) => void,
+  initiallyEnabled = true,
+  onDrop: (routeId: number, reason: "disabled") => void = () => {},
+): {
+  enqueue: (text: string, routeId?: number) => "queued" | "disabled";
+  setEnabled: (enabled: boolean) => void;
+} {
+  let tail = Promise.resolve();
+  let enabled = initiallyEnabled;
+  let generation = 0;
+  return {
+    enqueue(text, routeId = 0) {
+      if (!enabled) return "disabled";
+      const queuedGeneration = generation;
+      tail = tail
+        .then(() => {
+          if (!enabled || generation !== queuedGeneration) {
+            onDrop(routeId, "disabled");
+            return;
+          }
+          return speak(text, routeId);
+        })
+        .catch(onError);
+      return "queued";
+    },
+    setEnabled(nextEnabled) {
+      if (!nextEnabled) generation += 1;
+      enabled = nextEnabled;
+    },
+  };
+}
+
+/** Ensure a delayed bootstrap snapshot cannot overwrite a newer live event. */
+export function createLatestStateGate<T>(apply: (value: T) => void): {
+  applyEvent: (value: T) => void;
+  beginSnapshot: () => (value: T) => void;
+} {
+  let revision = 0;
+  return {
+    applyEvent(value) {
+      revision += 1;
+      apply(value);
+    },
+    beginSnapshot() {
+      const snapshotRevision = revision;
+      return (value) => {
+        if (revision === snapshotRevision) apply(value);
+      };
+    },
+  };
+}
+
+/** Hold live events until initial membership and TTS state are both known. */
+export function createInitialTtsReadinessGate<T>(
+  deliver: (event: T) => void,
+  drop: (
+    event: T,
+    reason: "membership_unavailable" | "tts_state_unavailable",
+  ) => void = () => {},
+): {
+  push: (event: T) => void;
+  markMembershipKnown: () => void;
+  markTtsStateKnown: () => void;
+  fail: (reason: "membership_unavailable" | "tts_state_unavailable") => void;
+} {
+  let settled = false;
+  let membershipKnown = false;
+  let ttsStateKnown = false;
+  let pending: T[] = [];
+  const releaseIfReady = () => {
+    if (settled || !membershipKnown || !ttsStateKnown) return;
+    settled = true;
+    const buffered = pending;
+    pending = [];
+    for (const event of buffered) deliver(event);
+  };
+  return {
+    push(event) {
+      if (settled) deliver(event);
+      else pending.push(event);
+    },
+    markMembershipKnown() {
+      membershipKnown = true;
+      releaseIfReady();
+    },
+    markTtsStateKnown() {
+      ttsStateKnown = true;
+      releaseIfReady();
+    },
+    fail(reason) {
+      if (settled) return;
+      settled = true;
+      const dropped = pending;
+      pending = [];
+      for (const event of dropped) drop(event, reason);
+    },
+  };
+}
diff --git a/desktop/src/features/huddle/lib/useTtsSubscription.ts b/desktop/src/features/huddle/lib/useTtsSubscription.ts
index d534fc0166..64fb96efcd 100644
--- a/desktop/src/features/huddle/lib/useTtsSubscription.ts
+++ b/desktop/src/features/huddle/lib/useTtsSubscription.ts
@@ -1,13 +1,28 @@
 import { invoke } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
 import * as React from "react";
 
+import { buildHuddleTtsLiveFilter } from "@/shared/api/relayChannelFilters";
 import { relayClient } from "@/shared/api/relayClient";
+import {
+  createInitialTtsReadinessGate,
+  createLatestStateGate,
+  createOrderedSpeaker,
+  routeLiveAgentText,
+} from "./ttsLiveMessages";
 
 const AGENT_PUBKEY_REFRESH_INTERVAL_MS = 30_000;
+let nextTtsRouteId = 1;
+
+function allocateTtsRouteId(): number {
+  const routeId = nextTtsRouteId;
+  nextTtsRouteId += 1;
+  return routeId;
+}
 
 /**
  * Subscribe to agent TTS messages on the ephemeral huddle channel.
- * Pipes agent kind:9 messages to `speak_agent_message` on the Rust backend.
+ * Pipes new agent message events to `speak_agent_message` on the Rust backend.
  *
  * Extracted from HuddleContext to keep file sizes manageable.
  */
@@ -20,6 +35,8 @@ export function useTtsSubscription(
 
     let disposed = false;
     let cleanup: (() => void) | null = null;
+    let unlistenHuddleState: (() => void) | null = null;
+    let ttsStateKnown = false;
 
     // ── Agent identity (authoritative, fail-closed) ───────────────────────
     //
@@ -33,43 +50,156 @@ export function useTtsSubscription(
     let agentsLoaded = false;
     const agentPubkeys = new Set<string>();
 
-    async function loadAgentPubkeys() {
+    const speakInOrder = createOrderedSpeaker(
+      async (text, routeId) => {
+        if (!disposed) {
+          console.debug(
+            `[huddle] tts stage=invoke status=attempted route_id=${routeId}`,
+          );
+          try {
+            await invoke("speak_agent_message", { text, routeId });
+            console.debug(
+              `[huddle] tts stage=invoke status=accepted route_id=${routeId}`,
+            );
+          } catch (error) {
+            console.warn(
+              `[huddle] tts stage=invoke status=failed reason=native_error route_id=${routeId}`,
+            );
+            throw error;
+          }
+        }
+      },
+      () => {},
+      false,
+      (routeId, reason) => {
+        console.debug(
+          `[huddle] tts stage=queue status=dropped reason=${reason} route_id=${routeId}`,
+        );
+      },
+    );
+
+    const deliver = ({
+      event,
+      routeId,
+    }: {
+      event: Parameters<typeof routeLiveAgentText>[0];
+      routeId: number;
+    }) => {
+      if (disposed) return;
+      if (!agentsLoaded) {
+        console.debug(
+          `[huddle] tts stage=eligibility status=rejected reason=membership_unavailable route_id=${routeId}`,
+        );
+        return;
+      }
+      const result = routeLiveAgentText(
+        event,
+        agentPubkeys,
+        selfPubkeyRef.current,
+        ephemeralChannelId,
+        routeId,
+        speakInOrder.enqueue,
+      );
+      if (result === "queued") {
+        console.debug(
+          `[huddle] tts stage=eligibility status=accepted route_id=${routeId}`,
+        );
+      } else {
+        const reason =
+          result === "disabled" && !ttsStateKnown
+            ? "tts_state_unknown"
+            : result;
+        console.debug(
+          `[huddle] tts stage=eligibility status=rejected reason=${reason} route_id=${routeId}`,
+        );
+      }
+    };
+    const initialReadinessGate = createInitialTtsReadinessGate(
+      deliver,
+      ({ routeId }, reason) => {
+        console.debug(
+          `[huddle] tts stage=eligibility status=rejected reason=${reason} route_id=${routeId}`,
+        );
+      },
+    );
+
+    async function loadAgentPubkeys(initial = false) {
       try {
         const pubkeys = await invoke<string[]>("get_huddle_agent_pubkeys");
+        if (disposed) return;
         agentPubkeys.clear();
         for (const pk of pubkeys) agentPubkeys.add(pk);
         agentsLoaded = true;
+        if (initial) {
+          initialReadinessGate.markMembershipKnown();
+        }
       } catch (e) {
         // Fail-closed on ALL failures, including refresh after prior success.
         // Clear the set and mark as not loaded — TTS goes mute until the
         // next successful refresh. Stale membership must never authorize speech.
         agentPubkeys.clear();
         agentsLoaded = false;
+        if (initial) {
+          initialReadinessGate.fail("membership_unavailable");
+        }
         console.error("[huddle] Failed to load agent pubkeys:", e);
       }
     }
 
     // Initial load + periodic refresh (catches mid-huddle agent additions).
-    void loadAgentPubkeys();
+    void loadAgentPubkeys(true);
     const agentRefreshId = window.setInterval(() => {
       void loadAgentPubkeys();
     }, AGENT_PUBKEY_REFRESH_INTERVAL_MS);
 
+    // Install the state listener before requesting a snapshot. If a newer
+    // event arrives while IPC is pending, it supersedes the stale snapshot.
+    const ttsStateGate = createLatestStateGate<{ tts_enabled: boolean }>(
+      (state) => {
+        if (!disposed) {
+          ttsStateKnown = true;
+          speakInOrder.setEnabled(state.tts_enabled);
+          initialReadinessGate.markTtsStateKnown();
+        }
+      },
+    );
+    void listen<{ tts_enabled: boolean }>("huddle-state-changed", (event) => {
+      if (!disposed) ttsStateGate.applyEvent(event.payload);
+    })
+      .then((unlisten) => {
+        if (disposed) {
+          unlisten();
+          return;
+        }
+        unlistenHuddleState = unlisten;
+        const applyBootstrap = ttsStateGate.beginSnapshot();
+        void invoke<{ tts_enabled: boolean }>("get_huddle_state")
+          .then((state) => {
+            if (!disposed) applyBootstrap(state);
+          })
+          .catch((err) => {
+            if (!ttsStateKnown)
+              initialReadinessGate.fail("tts_state_unavailable");
+            console.warn("[huddle] Failed to load TTS state:", err);
+          });
+      })
+      .catch((err) => {
+        speakInOrder.setEnabled(false);
+        initialReadinessGate.fail("tts_state_unavailable");
+        console.warn("[huddle] Failed to listen for TTS state:", err);
+      });
+
     // ── Live-only subscription ───────────────────────────────────────────
-    // subscribeToChannelLive uses `since: now` — the relay never sends
-    // historical backlog. Every event delivered is a live message.
+    // A limit:0 subscription receives future message fan-out while the relay
+    // returns no stored rows, including pre-join rows from the current second.
     // Event-ID dedup handles reconnect replay (same event arriving twice).
     const seenEventIds = new Set<string>();
     const seenOrder: string[] = [];
     const MAX_SEEN_EVENTS = 5000;
-
     relayClient
-      .subscribeToChannelLive(ephemeralChannelId, (event) => {
+      .subscribeLive(buildHuddleTtsLiveFilter(ephemeralChannelId), (event) => {
         if (disposed) return;
-        // Defense-in-depth: subscription already filters to kind:9 only.
-        if (event.kind !== 9) return;
-
-        // Dedup by event ID (covers reconnect replay).
+        // Dedup by event ID if a relay repeats live fan-out.
         if (seenEventIds.has(event.id)) return;
         seenEventIds.add(event.id);
         seenOrder.push(event.id);
@@ -78,20 +208,15 @@ export function useTtsSubscription(
           if (oldest !== undefined) seenEventIds.delete(oldest);
         }
 
-        // Fail-closed: don't speak until agent list is loaded.
-        if (!agentsLoaded) return;
-        // Only speak agent messages — skip human STT transcripts.
-        if (!agentPubkeys.has(event.pubkey)) return;
-        if (event.pubkey === selfPubkeyRef.current) return;
-        if (event.content.trim().length <= 1) return;
-        // Legacy: skip [System]-prefixed messages from before kind:48106.
-        if (event.content.startsWith("[System]")) return;
-        invoke("speak_agent_message", { text: event.content }).catch((err) => {
-          console.warn(
-            "[huddle] TTS speak failed (backpressure or pipeline unavailable):",
-            err,
+        // Preserve arrival order until initial membership and TTS state are
+        // both known. A failed readiness check clears this buffer fail-closed.
+        const routeId = allocateTtsRouteId();
+        if (!agentsLoaded) {
+          console.debug(
+            `[huddle] tts stage=eligibility status=deferred reason=membership_unavailable route_id=${routeId}`,
           );
-        });
+        }
+        initialReadinessGate.push({ event, routeId });
       })
       .then((dispose) => {
         if (disposed) {
@@ -106,7 +231,9 @@ export function useTtsSubscription(
 
     return () => {
       disposed = true;
+      speakInOrder.setEnabled(false);
       cleanup?.();
+      unlistenHuddleState?.();
       window.clearInterval(agentRefreshId);
     };
   }, [ephemeralChannelId, selfPubkeyRef]);
diff --git a/desktop/src/features/mesh-compute/ui/MeshComputeSettingsCard.tsx b/desktop/src/features/mesh-compute/ui/MeshComputeSettingsCard.tsx
index 76f86f8054..fd7550eff0 100644
--- a/desktop/src/features/mesh-compute/ui/MeshComputeSettingsCard.tsx
+++ b/desktop/src/features/mesh-compute/ui/MeshComputeSettingsCard.tsx
@@ -107,7 +107,9 @@ export function MeshComputeSettingsCard() {
 
   // One-shot hardware-aware catalog fetch. Purely additive: when it fails
   // (stub build, survey error) the card falls back to the free-text field.
-  // Keep an empty draft empty so the UI can explicitly ask the member to choose.
+  // When there is no saved choice, make the curated recommendation the actual
+  // default so a new member can turn Share Compute on directly. An explicit
+  // saved draft always wins.
   React.useEffect(() => {
     let cancelled = false;
     (async () => {
@@ -115,6 +117,11 @@ export function MeshComputeSettingsCard() {
         const value = await meshModelCatalog();
         if (cancelled) return;
         setCatalog(value);
+        setModelInput((current) => {
+          if (current.trim() !== "" || !value.recommended) return current;
+          writeDraft(MODEL_DRAFT_STORAGE_KEY, value.recommended);
+          return value.recommended;
+        });
       } catch {
         // Non-fatal — picker just doesn't render.
       }
diff --git a/desktop/src/features/messages/lib/independentThreadPanel.ts b/desktop/src/features/messages/lib/independentThreadPanel.ts
index 4562928d8b..7652c2508c 100644
--- a/desktop/src/features/messages/lib/independentThreadPanel.ts
+++ b/desktop/src/features/messages/lib/independentThreadPanel.ts
@@ -11,16 +11,18 @@ export function buildIndependentThreadPanel(
   ...formatArgs: Tail<Parameters<typeof formatTimelineMessages>>
 ) {
   if (!rootId) {
-    return buildThreadPanelData([], null, replyTargetId, expandedReplyIds);
+    return {
+      ...buildThreadPanelData([], null, replyTargetId, expandedReplyIds),
+      messages: [],
+    };
   }
   const head = channelEvents.find((event) => event.id === rootId);
   const events = head ? [head, ...replyEvents] : replyEvents;
-  return buildThreadPanelData(
-    formatTimelineMessages(events, ...formatArgs),
-    rootId,
-    replyTargetId,
-    expandedReplyIds,
-  );
+  const messages = formatTimelineMessages(events, ...formatArgs);
+  return {
+    ...buildThreadPanelData(messages, rootId, replyTargetId, expandedReplyIds),
+    messages,
+  };
 }
 
 type Tail<T extends readonly unknown[]> = T extends readonly [
diff --git a/desktop/src/features/messages/lib/rowHeightEstimate.test.mjs b/desktop/src/features/messages/lib/rowHeightEstimate.test.mjs
index dc33da4f8f..f17a53c661 100644
--- a/desktop/src/features/messages/lib/rowHeightEstimate.test.mjs
+++ b/desktop/src/features/messages/lib/rowHeightEstimate.test.mjs
@@ -23,6 +23,13 @@ test("estimateRowHeight: short text is near the floor", () => {
   assert.ok(h >= 60 && h < 120, `expected small, got ${h}`);
 });
 
+test("estimateRowHeight: continuation reserves its uniform padding", () => {
+  const h = estimateRowHeight(msg({ body: "hello" }), {
+    isContinuation: true,
+  });
+  assert.equal(h, 28);
+});
+
 test("estimateRowHeight: many lines reserve more", () => {
   const tall = estimateRowHeight(
     msg({ body: Array.from({ length: 20 }, (_, i) => `line ${i}`).join("\n") }),
diff --git a/desktop/src/features/messages/lib/rowHeightEstimate.ts b/desktop/src/features/messages/lib/rowHeightEstimate.ts
index f2fb268167..acefae95d4 100644
--- a/desktop/src/features/messages/lib/rowHeightEstimate.ts
+++ b/desktop/src/features/messages/lib/rowHeightEstimate.ts
@@ -26,13 +26,13 @@ const TEXT_LINE_HEIGHT = 20;
 const CODE_LINE_HEIGHT = 19;
 const CHARS_PER_LINE = 64; // rough wrap width at the timeline column
 const ROW_CHROME = 26; // author/time header + denser row padding
-const CONTINUATION_ROW_CHROME = 8; // dense row padding only; header/avatar are hidden
+const CONTINUATION_ROW_CHROME = 8; // uniform py-1 padding; header/avatar are hidden
 const MEDIA_BLOCK_MARGIN_TOP = 4; // image/video blocks use mt-1 in markdown
 const REACTION_ROW = 24;
 const PREVIEW_CARD = 70;
 const MESSAGE_ITEM_BOTTOM_PADDING = 10; // TimelineMessageList pb-2.5
 const MIN_ESTIMATE = 60; // never reserve less than the old flat floor
-const CONTINUATION_MIN_ESTIMATE = 34;
+const CONTINUATION_MIN_ESTIMATE = 28;
 
 function mediaHeightFromDim(dim: string | undefined): number {
   const dimensions = dimensionsFromDim(dim);
diff --git a/desktop/src/features/messages/lib/systemEventCopy.test.mjs b/desktop/src/features/messages/lib/systemEventCopy.test.mjs
new file mode 100644
index 0000000000..eeed9d543c
--- /dev/null
+++ b/desktop/src/features/messages/lib/systemEventCopy.test.mjs
@@ -0,0 +1,107 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  describeChannelTextFieldChange,
+  toInlineName,
+} from "./systemEventCopy.ts";
+
+test("a set topic is quoted verbatim", () => {
+  assert.equal(
+    describeChannelTextFieldChange("topic", "Release planning"),
+    "changed the topic to “Release planning”",
+  );
+});
+
+test("a set purpose names the purpose, not the topic", () => {
+  assert.equal(
+    describeChannelTextFieldChange("purpose", "Where we ship from"),
+    "changed the purpose to “Where we ship from”",
+  );
+});
+
+// The relay reports a clear as a change carrying an empty string, so without
+// this branch the timeline reads: changed the topic to “”.
+test("an empty value reads as cleared, not as a change to empty quotes", () => {
+  for (const blank of ["", undefined, null]) {
+    assert.equal(
+      describeChannelTextFieldChange("topic", blank),
+      "cleared the topic",
+    );
+    assert.equal(
+      describeChannelTextFieldChange("purpose", blank),
+      "cleared the purpose",
+    );
+  }
+});
+
+test("a whitespace-only value reads as cleared", () => {
+  assert.equal(
+    describeChannelTextFieldChange("topic", "   \n\t "),
+    "cleared the topic",
+  );
+});
+
+test("surrounding whitespace is trimmed out of the quotes", () => {
+  assert.equal(
+    describeChannelTextFieldChange("topic", "  Release planning  "),
+    "changed the topic to “Release planning”",
+  );
+});
+
+test("no caption announces empty quotes", () => {
+  for (const value of ["", " ", null, undefined, "Real topic"]) {
+    for (const field of ["topic", "purpose"]) {
+      assert.doesNotMatch(
+        describeChannelTextFieldChange(field, value),
+        /“”|""/,
+        `${field} with ${JSON.stringify(value)} must not render empty quotes`,
+      );
+    }
+  }
+});
+
+test("the reader's own name is lowercase mid-sentence", () => {
+  // "added by You" next to an agent's "managed by you" was the inconsistency.
+  assert.equal(toInlineName("You", true), "you");
+});
+
+test("cleared and changed captions use the same noun", () => {
+  // Not "cleared the channel topic" against "changed the topic to …".
+  assert.match(describeChannelTextFieldChange("topic", ""), /\bthe topic\b/);
+  assert.match(
+    describeChannelTextFieldChange("topic", "Ship it"),
+    /\bthe topic\b/,
+  );
+  for (const value of ["", "Ship it"]) {
+    assert.doesNotMatch(
+      describeChannelTextFieldChange("topic", value),
+      /channel topic/,
+    );
+  }
+});
+
+test("every other name keeps its own capitalization", () => {
+  for (const name of [
+    "Alice Chen",
+    "you-know-who",
+    "Someone",
+    "npub1abc…def",
+  ]) {
+    assert.equal(toInlineName(name, false), name);
+  }
+});
+
+test("someone else whose display name is literally You is left alone", () => {
+  // The decisive case: the label is user-controlled, identity is not. Matching
+  // on the string would rewrite this person's name as if they were the reader.
+  assert.equal(toInlineName("You", false), "You");
+  assert.equal(toInlineName("Youssef", false), "Youssef");
+  assert.equal(toInlineName("You Know Who", false), "You Know Who");
+});
+
+test("the reader is lowercased whatever their profile name says", () => {
+  // Self resolution never consults the profile, but the rule keys on identity,
+  // so it does not matter what the label happens to be.
+  assert.equal(toInlineName("Alice Chen", true), "you");
+});
diff --git a/desktop/src/features/messages/lib/systemEventCopy.ts b/desktop/src/features/messages/lib/systemEventCopy.ts
new file mode 100644
index 0000000000..bae6abb09b
--- /dev/null
+++ b/desktop/src/features/messages/lib/systemEventCopy.ts
@@ -0,0 +1,59 @@
+/**
+ * Copy for channel system events (the "joined", "added by", "changed the
+ * topic" captions in the message timeline).
+ *
+ * These live outside `SystemMessageRow` so the wording is a pure function of
+ * the payload and can be asserted directly in tests. Only cases whose caption
+ * is plain text belong here — cases that interpolate a profile link build their
+ * JSX in the component.
+ */
+
+/** Curly quotes, so the caption matches the typography used elsewhere in chat. */
+const OPEN_QUOTE = "“";
+const CLOSE_QUOTE = "”";
+
+export type ChannelTextField = "topic" | "purpose";
+
+/**
+ * Caption for a channel topic or purpose change.
+ *
+ * Bare "the topic" rather than "the channel topic": this row only ever renders
+ * in a channel timeline, under that channel's own header, so naming the channel
+ * again is redundant — and it keeps the cleared and changed captions on the same
+ * noun instead of one saying "channel topic" and the other "topic".
+ *
+ * A blank value means the field was cleared: the relay reports a clear as a
+ * `topic_changed` / `purpose_changed` event carrying an empty string, not as a
+ * separate event type. Without this branch the timeline renders `changed the
+ * topic to ""`, which reads like the topic was set to two quote marks.
+ * Whitespace-only values are treated as cleared for the same reason.
+ */
+export function describeChannelTextFieldChange(
+  field: ChannelTextField,
+  value: string | null | undefined,
+): string {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return `cleared the ${field}`;
+  }
+  return `changed the ${field} to ${OPEN_QUOTE}${trimmed}${CLOSE_QUOTE}`;
+}
+
+/**
+ * Adjusts a resolved display name for use inside a sentence rather than in the
+ * name slot at the top of a row — "added by you", "removed you from the channel".
+ *
+ * `resolveUserLabel` returns "You" for the current user, which is right standing
+ * alone and wrong mid-phrase. Agent ownership already draws the same distinction
+ * from the other side: `formatOwnerLabel` returns lowercase "you" because it is
+ * only ever read as "managed by you".
+ *
+ * `isSelf` is the caller's pubkey comparison, not an inspection of `label`.
+ * Matching on the string would also rewrite a different person whose display
+ * name happens to be "You" — the label is user-controlled, identity is not.
+ * Every name that isn't the reader's own is a proper noun and is returned
+ * untouched.
+ */
+export function toInlineName(label: string, isSelf: boolean): string {
+  return isSelf ? "you" : label;
+}
diff --git a/desktop/src/features/messages/lib/timelineItems.test.mjs b/desktop/src/features/messages/lib/timelineItems.test.mjs
index cdc40b875e..4677fe7b49 100644
--- a/desktop/src/features/messages/lib/timelineItems.test.mjs
+++ b/desktop/src/features/messages/lib/timelineItems.test.mjs
@@ -245,6 +245,36 @@ test("buildTimelineItems: consecutive same-author messages within the window are
   );
 });
 
+test("buildTimelineItems: pending messages remain standalone until acknowledged", () => {
+  const entries = [
+    entry({ id: "a", pubkey: "author-a", createdAt: dayAt(2026, 6, 14) }),
+    entry({
+      id: "b",
+      pubkey: "author-a",
+      createdAt: dayAt(2026, 6, 14, 12, 2),
+      pending: true,
+    }),
+    entry({
+      id: "c",
+      pubkey: "author-a",
+      createdAt: dayAt(2026, 6, 14, 12, 3),
+    }),
+  ];
+
+  const messageItems = buildTimelineItems(entries, null).items.filter(
+    (item) => item.kind === "message",
+  );
+
+  assert.deepEqual(
+    messageItems.map((item) => item.isContinuation),
+    [false, false, false],
+  );
+  assert.deepEqual(
+    messageItems.map((item) => item.isFollowedByContinuation),
+    [false, false, false],
+  );
+});
+
 test("buildTimelineItems: same-author messages past the window start a new group", () => {
   const author = "author-a";
   const entries = [
diff --git a/desktop/src/features/messages/lib/timelineItems.ts b/desktop/src/features/messages/lib/timelineItems.ts
index 007d77c020..72b83f0a07 100644
--- a/desktop/src/features/messages/lib/timelineItems.ts
+++ b/desktop/src/features/messages/lib/timelineItems.ts
@@ -232,8 +232,13 @@ export function buildTimelineItems(
       continue;
     }
 
+    // Pending rows render with their own header so the send status can sit
+    // beside the timestamp. Keep the timeline spacing and row estimate in
+    // that same standalone state until the send acknowledgement arrives.
     const isContinuation =
+      !message.pending &&
       previousGroupEntry !== null &&
+      !previousGroupEntry.message.pending &&
       hasSameMessageAuthor(previousGroupEntry.message, message) &&
       isWithinGroupingWindow(
         previousGroupEntry.message.createdAt,
diff --git a/desktop/src/features/messages/lib/useEmojiAutocomplete.ts b/desktop/src/features/messages/lib/useEmojiAutocomplete.ts
index 53ef44b28d..57e458bc91 100644
--- a/desktop/src/features/messages/lib/useEmojiAutocomplete.ts
+++ b/desktop/src/features/messages/lib/useEmojiAutocomplete.ts
@@ -4,7 +4,11 @@ import { init, SearchIndex } from "emoji-mart";
 import data from "@emoji-mart/data";
 
 import type { CustomEmoji } from "@/shared/lib/remarkCustomEmoji";
-import { fuzzyStandardEmoji, rankByShortcode } from "@/shared/lib/emojiSearch";
+import {
+  fuzzyStandardEmoji,
+  rankByShortcode,
+  rankShortcodeMatchesFirst,
+} from "@/shared/lib/emojiSearch";
 import { rewriteRelayUrl } from "@/shared/lib/mediaUrl";
 import type { AutocompleteEdit } from "./useRichTextEditor";
 
@@ -18,7 +22,7 @@ export type EmojiSuggestion = {
 
 const EMOJI_DEBOUNCE_MS = 120;
 const MIN_QUERY_LENGTH = 2;
-const MAX_RESULTS = 8;
+const UNLIMITED_RESULTS = Number.POSITIVE_INFINITY;
 
 init({ data });
 
@@ -81,7 +85,7 @@ export function useEmojiAutocomplete(customEmoji: CustomEmoji[] = []) {
       emojiQuery,
       customEmojiRef.current,
       (e) => e.shortcode,
-      MAX_RESULTS,
+      UNLIMITED_RESULTS,
     ).map((e) => ({
       id: e.shortcode,
       name: e.shortcode,
@@ -89,7 +93,10 @@ export function useEmojiAutocomplete(customEmoji: CustomEmoji[] = []) {
       url: rewriteRelayUrl(e.url),
     }));
 
-    SearchIndex.search(emojiQuery)
+    SearchIndex.search(emojiQuery, {
+      caller: "useEmojiAutocomplete",
+      maxResults: UNLIMITED_RESULTS,
+    })
       .then(
         (
           results: Array<{
@@ -106,23 +113,28 @@ export function useEmojiAutocomplete(customEmoji: CustomEmoji[] = []) {
               native: emoji.skins[0]?.native ?? "",
             }))
             .filter((e) => e.native !== "");
-          // Top up remaining slots with fuzzy shortcode matches emoji-mart
-          // missed — its token-prefix search can't cross `_` (so `pointup`
-          // finds nothing). Skip ids already shown to avoid duplicates.
+          // Add fuzzy shortcode matches emoji-mart missed — its token-prefix
+          // search can't cross `_` (so `pointup` finds nothing). Skip ids
+          // already shown to avoid duplicates.
           const shown = new Set<string>(
             [...customMatches, ...standard].map((e) => e.id),
           );
           const fuzzy: EmojiSuggestion[] = fuzzyStandardEmoji(
             emojiQuery,
-            MAX_RESULTS - customMatches.length - standard.length,
+            UNLIMITED_RESULTS,
             shown,
           ).map((e) => ({ id: e.id, name: e.name, native: e.native }));
-          // Custom emoji first (community-specific), then standard, then fuzzy.
-          const merged = [...customMatches, ...standard, ...fuzzy].slice(
-            0,
-            MAX_RESULTS,
+          // Rank exact/prefix shortcode matches across custom and standard emoji
+          // before semantic and weaker matches (for example, `joy` before
+          // `bufo_joy`). Keep emoji-mart's name/keyword results ahead of loose
+          // substring and subsequence matches.
+          setSuggestions(
+            rankShortcodeMatchesFirst(
+              emojiQuery,
+              [...standard, ...customMatches, ...fuzzy],
+              (emoji) => emoji.id,
+            ),
           );
-          setSuggestions(merged);
           setEmojiSelectedIndex(0);
         },
       )
diff --git a/desktop/src/features/messages/lib/videoReviewContext.test.mjs b/desktop/src/features/messages/lib/videoReviewContext.test.mjs
index de35d53ce3..8ecb5f5798 100644
--- a/desktop/src/features/messages/lib/videoReviewContext.test.mjs
+++ b/desktop/src/features/messages/lib/videoReviewContext.test.mjs
@@ -5,6 +5,7 @@ import {
   buildVideoReviewCommentsByRootId,
   buildVideoReviewCommentsForRoot,
   buildVideoReviewContextForMessage,
+  buildVideoReviewContextsByMessageId,
   hasVideoAttachment,
 } from "./videoReviewContext.ts";
 
@@ -209,3 +210,30 @@ test("buildVideoReviewContextForMessage posts against the source video", async (
     },
   ]);
 });
+
+test("buildVideoReviewContextsByMessageId includes video replies", () => {
+  const root = message({ id: "root", body: "Review request" });
+  const videoReply = message({
+    id: "video-reply",
+    body: "![video](https://relay/media/a.mp4)",
+    parentId: root.id,
+    rootId: root.id,
+  });
+  const comment = message({
+    id: "comment",
+    body: "[00:01] tighten this",
+    parentId: videoReply.id,
+    rootId: root.id,
+  });
+
+  const contexts = buildVideoReviewContextsByMessageId({
+    channelId: "channel",
+    messages: [root, videoReply, comment],
+  });
+
+  assert.deepEqual([...contexts.keys()], [videoReply.id]);
+  assert.deepEqual(
+    contexts.get(videoReply.id)?.comments.map((item) => item.id),
+    [comment.id],
+  );
+});
diff --git a/desktop/src/features/messages/lib/videoReviewContext.ts b/desktop/src/features/messages/lib/videoReviewContext.ts
index 8d0798db40..f605952f5a 100644
--- a/desktop/src/features/messages/lib/videoReviewContext.ts
+++ b/desktop/src/features/messages/lib/videoReviewContext.ts
@@ -148,3 +148,48 @@ export function buildVideoReviewContextForMessage({
     rootEventId: message.id,
   };
 }
+
+export function buildVideoReviewContextsByMessageId({
+  channelId,
+  channelName,
+  channelType,
+  isSendingVideoReviewComment = false,
+  messages,
+  onSendVideoReviewComment,
+  onToggleReaction,
+  profiles,
+}: {
+  channelId?: string | null;
+  channelName?: string;
+  channelType?: ChannelType | null;
+  isSendingVideoReviewComment?: boolean;
+  messages: TimelineMessage[];
+  onSendVideoReviewComment?: SendVideoReviewComment;
+  onToggleReaction?: ToggleMessageReaction;
+  profiles?: UserProfileLookup;
+}): ReadonlyMap<string, VideoReviewContext> {
+  const contexts = new Map<string, VideoReviewContext>();
+  if (!messages.some(hasVideoAttachment)) {
+    return contexts;
+  }
+
+  const commentsByRootId = buildVideoReviewCommentsByRootId(messages);
+  for (const message of messages) {
+    const context = buildVideoReviewContextForMessage({
+      channelId,
+      channelName,
+      channelType,
+      comments: commentsByRootId.get(message.id) ?? [],
+      isSendingVideoReviewComment,
+      message,
+      onSendVideoReviewComment,
+      onToggleReaction,
+      profiles,
+    });
+    if (context) {
+      contexts.set(message.id, context);
+    }
+  }
+
+  return contexts;
+}
diff --git a/desktop/src/features/messages/ui/DeleteMessageConfirmDialog.tsx b/desktop/src/features/messages/ui/DeleteMessageConfirmDialog.tsx
new file mode 100644
index 0000000000..9802f09efc
--- /dev/null
+++ b/desktop/src/features/messages/ui/DeleteMessageConfirmDialog.tsx
@@ -0,0 +1,53 @@
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/shared/ui/alert-dialog";
+import { Button } from "@/shared/ui/button";
+
+/**
+ * The "Delete message?" confirmation. Single definition shared by every
+ * surface that deletes a message — the message action menu (MessageActionBar)
+ * and the empty-edit delete path (clearing an edit to empty and hitting accept
+ * routes here, so it prompts exactly like the menu's Delete does). `onConfirm`
+ * fires when the user presses Delete; the caller owns the actual deletion.
+ */
+export function DeleteMessageConfirmDialog({
+  open,
+  onOpenChange,
+  onConfirm,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  onConfirm: () => void;
+}) {
+  return (
+    <AlertDialog onOpenChange={onOpenChange} open={open}>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Delete message?</AlertDialogTitle>
+          <AlertDialogDescription>
+            This will permanently delete this message and cannot be undone.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel asChild>
+            <Button type="button" variant="outline">
+              Cancel
+            </Button>
+          </AlertDialogCancel>
+          <AlertDialogAction asChild>
+            <Button onClick={onConfirm} type="button" variant="destructive">
+              Delete
+            </Button>
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
diff --git a/desktop/src/features/messages/ui/DirectMessageIntroAvatarStack.tsx b/desktop/src/features/messages/ui/DirectMessageIntroAvatarStack.tsx
index 1a1018fbe7..e2922d80b7 100644
--- a/desktop/src/features/messages/ui/DirectMessageIntroAvatarStack.tsx
+++ b/desktop/src/features/messages/ui/DirectMessageIntroAvatarStack.tsx
@@ -1,4 +1,5 @@
 import { getDmParticipantPreview } from "@/features/channels/lib/dmParticipantDisplay";
+import { UserProfilePopover } from "@/features/profile/ui/UserProfilePopover";
 import { UserAvatar } from "@/shared/ui/UserAvatar";
 
 export type DirectMessageIntroParticipant = {
@@ -18,31 +19,36 @@ export function DirectMessageIntroAvatarStack({
 
   return (
     <div
-      aria-hidden="true"
       className="flex shrink-0 items-center"
       data-testid="message-dm-intro-avatar-stack"
     >
       {visibleParticipants.map((participant, index) => (
-        <div
-          className={index > 0 ? "-ml-5" : ""}
-          data-testid="message-dm-intro-avatar-stack-participant"
+        <UserProfilePopover
           key={participant.pubkey}
-          style={{
-            zIndex: index + 1,
-            ...(index < stackItemCount - 1 && {
-              mask: "radial-gradient(circle 34px at calc(100% + 10px) 50%, transparent 99%, #fff 100%)",
-              WebkitMask:
-                "radial-gradient(circle 34px at calc(100% + 10px) 50%, transparent 99%, #fff 100%)",
-            }),
-          }}
+          pubkey={participant.pubkey}
+          triggerAriaLabel={`Open profile for ${participant.displayName}`}
+          triggerElement="span"
         >
-          <UserAvatar
-            avatarUrl={participant.avatarUrl}
-            className="h-[60px] w-[60px] text-base"
-            displayName={participant.displayName}
-            size="md"
-          />
-        </div>
+          <span
+            className={index > 0 ? "-ml-5" : ""}
+            data-testid="message-dm-intro-avatar-stack-participant"
+            style={{
+              zIndex: index + 1,
+              ...(index < stackItemCount - 1 && {
+                mask: "radial-gradient(circle 34px at calc(100% + 10px) 50%, transparent 99%, #fff 100%)",
+                WebkitMask:
+                  "radial-gradient(circle 34px at calc(100% + 10px) 50%, transparent 99%, #fff 100%)",
+              }),
+            }}
+          >
+            <UserAvatar
+              avatarUrl={participant.avatarUrl}
+              className="h-[60px] w-[60px] text-base"
+              displayName={participant.displayName}
+              size="md"
+            />
+          </span>
+        </UserProfilePopover>
       ))}
       {hiddenCount > 0 ? (
         <div
diff --git a/desktop/src/features/messages/ui/EmojiAutocomplete.tsx b/desktop/src/features/messages/ui/EmojiAutocomplete.tsx
index 3b6fa3a2d2..d44933aef1 100644
--- a/desktop/src/features/messages/ui/EmojiAutocomplete.tsx
+++ b/desktop/src/features/messages/ui/EmojiAutocomplete.tsx
@@ -2,6 +2,10 @@ import * as React from "react";
 
 import type { EmojiSuggestion } from "@/features/messages/lib/useEmojiAutocomplete";
 import { cn } from "@/shared/lib/cn";
+import {
+  type ListVirtualizer,
+  VirtualizedList,
+} from "@/shared/ui/VirtualizedList";
 import {
   POPOVER_CUSTOM_ENTER_MOTION_CLASS,
   POPOVER_SHADOW_STYLE,
@@ -21,15 +25,21 @@ export const EmojiAutocomplete = React.memo(function EmojiAutocomplete({
   onSelect,
   position = "above",
 }: EmojiAutocompleteProps) {
-  const listRef = React.useRef<HTMLDivElement>(null);
+  const listVirtualizerRef = React.useRef<ListVirtualizer | null>(null);
 
   React.useEffect(() => {
-    const activeItem = listRef.current?.children[selectedIndex] as
-      | HTMLElement
-      | undefined;
-    activeItem?.scrollIntoView({ block: "nearest" });
+    listVirtualizerRef.current?.scrollToIndex(selectedIndex, {
+      align: "auto",
+    });
   }, [selectedIndex]);
 
+  const handleVirtualizer = React.useCallback(
+    (virtualizer: ListVirtualizer) => {
+      listVirtualizerRef.current = virtualizer;
+    },
+    [],
+  );
+
   if (suggestions.length === 0) {
     return null;
   }
@@ -43,47 +53,55 @@ export const EmojiAutocomplete = React.memo(function EmojiAutocomplete({
     >
       <div
         className={cn(
-          "max-h-48 overflow-y-auto rounded-xl p-1",
+          "rounded-xl p-1",
           POPOVER_CUSTOM_ENTER_MOTION_CLASS,
           position === "below"
             ? "origin-top slide-in-from-top-1"
             : "origin-bottom slide-in-from-bottom-1",
           POPOVER_SURFACE_CLASS,
         )}
-        ref={listRef}
+        data-testid="emoji-autocomplete"
         style={POPOVER_SHADOW_STYLE}
       >
-        {suggestions.map((suggestion, index) => (
-          <button
-            className={cn(
-              "flex w-full cursor-pointer items-center gap-2 rounded-lg px-3 py-1.5 text-left text-sm",
-              index === selectedIndex
-                ? "bg-accent text-accent-foreground"
-                : "text-popover-foreground hover:bg-accent/50",
-            )}
-            key={suggestion.id}
-            onMouseDown={(event) => {
-              event.preventDefault();
-              onSelect(suggestion);
-            }}
-            tabIndex={-1}
-            type="button"
-          >
-            {suggestion.url ? (
-              <img
-                alt={`:${suggestion.id}:`}
-                src={suggestion.url}
-                className="h-5 w-5 object-contain"
-                draggable={false}
-              />
-            ) : (
-              <span className="text-lg leading-none">{suggestion.native}</span>
-            )}
-            <span className="truncate text-muted-foreground">
-              :{suggestion.id}:
-            </span>
-          </button>
-        ))}
+        <VirtualizedList
+          className="max-h-48"
+          estimateSize={36}
+          getItemKey={(suggestion) => suggestion.id}
+          items={suggestions}
+          onVirtualizer={handleVirtualizer}
+          renderItem={(suggestion, index) => (
+            <button
+              className={cn(
+                "flex w-full cursor-pointer items-center gap-2 rounded-lg px-3 py-1.5 text-left text-sm",
+                index === selectedIndex
+                  ? "bg-accent text-accent-foreground"
+                  : "text-popover-foreground hover:bg-accent/50",
+              )}
+              onMouseDown={(event) => {
+                event.preventDefault();
+                onSelect(suggestion);
+              }}
+              tabIndex={-1}
+              type="button"
+            >
+              {suggestion.url ? (
+                <img
+                  alt={`:${suggestion.id}:`}
+                  src={suggestion.url}
+                  className="h-5 w-5 object-contain"
+                  draggable={false}
+                />
+              ) : (
+                <span className="text-lg leading-none">
+                  {suggestion.native}
+                </span>
+              )}
+              <span className="truncate text-muted-foreground">
+                :{suggestion.id}:
+              </span>
+            </button>
+          )}
+        />
       </div>
     </div>
   );
diff --git a/desktop/src/features/messages/ui/MessageActionBar.tsx b/desktop/src/features/messages/ui/MessageActionBar.tsx
index ba45bc62fb..967e50f5d2 100644
--- a/desktop/src/features/messages/ui/MessageActionBar.tsx
+++ b/desktop/src/features/messages/ui/MessageActionBar.tsx
@@ -35,17 +35,8 @@ import { copyTextToClipboard } from "@/shared/lib/clipboard";
 import { emojiDisplayName } from "@/shared/lib/emojiName";
 import { rewriteRelayUrl } from "@/shared/lib/mediaUrl";
 import { KIND_HUDDLE_STARTED } from "@/shared/constants/kinds";
-import {
-  AlertDialog,
-  AlertDialogAction,
-  AlertDialogCancel,
-  AlertDialogContent,
-  AlertDialogDescription,
-  AlertDialogFooter,
-  AlertDialogHeader,
-  AlertDialogTitle,
-} from "@/shared/ui/alert-dialog";
 import { Button } from "@/shared/ui/button";
+import { DeleteMessageConfirmDialog } from "./DeleteMessageConfirmDialog";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -277,35 +268,11 @@ function MoreActionsMenu({
       </DropdownMenu>
 
       {onDelete ? (
-        <AlertDialog
+        <DeleteMessageConfirmDialog
+          onConfirm={() => onDelete(message)}
           onOpenChange={setIsDeleteDialogOpen}
           open={isDeleteDialogOpen}
-        >
-          <AlertDialogContent>
-            <AlertDialogHeader>
-              <AlertDialogTitle>Delete message?</AlertDialogTitle>
-              <AlertDialogDescription>
-                This will permanently delete this message and cannot be undone.
-              </AlertDialogDescription>
-            </AlertDialogHeader>
-            <AlertDialogFooter>
-              <AlertDialogCancel asChild>
-                <Button type="button" variant="outline">
-                  Cancel
-                </Button>
-              </AlertDialogCancel>
-              <AlertDialogAction asChild>
-                <Button
-                  onClick={() => onDelete(message)}
-                  type="button"
-                  variant="destructive"
-                >
-                  Delete
-                </Button>
-              </AlertDialogAction>
-            </AlertDialogFooter>
-          </AlertDialogContent>
-        </AlertDialog>
+        />
       ) : null}
 
       {canReport ? (
diff --git a/desktop/src/features/messages/ui/MessageComposer.tsx b/desktop/src/features/messages/ui/MessageComposer.tsx
index df3a734cee..69e4ec67b5 100644
--- a/desktop/src/features/messages/ui/MessageComposer.tsx
+++ b/desktop/src/features/messages/ui/MessageComposer.tsx
@@ -513,10 +513,9 @@ function MessageComposerImpl({
     if (editTargetRef.current && onEditSaveRef.current) {
       if (isSendingRef.current || isUploadingRef.current) return;
       const currentPendingImeta = media.pendingImetaRef.current;
-      const hasMedia = currentPendingImeta.length > 0;
-      // Empty text + zero attachments is a no-op (don't let edit become an
-      // effective deletion).
-      if (!trimmed && !hasMedia) return;
+      // No empty-edit guard here: clearing an edit to empty (no text, no
+      // attachments) flows through to onEditSave as empty content, which
+      // deletes the message instead of publishing it (see handleEditSave).
 
       // Build the edit's body + imeta tag set. Coerce `mediaTags ?? []`
       // because edit semantics use `[]` as the explicit "wipe all
diff --git a/desktop/src/features/messages/ui/MessageRow.tsx b/desktop/src/features/messages/ui/MessageRow.tsx
index afcb3e863c..286526b658 100644
--- a/desktop/src/features/messages/ui/MessageRow.tsx
+++ b/desktop/src/features/messages/ui/MessageRow.tsx
@@ -1,4 +1,5 @@
 import * as React from "react";
+import { AlertTriangle } from "lucide-react";
 
 import {
   depthGuideActionsEqual,
@@ -87,6 +88,7 @@ export const MessageRow = React.memo(
     onMarkRead,
     onToggleReaction,
     onReply,
+    onOpenThread,
     onEntranceComplete,
     playEntrance = false,
     onUnfollowThread,
@@ -134,6 +136,7 @@ export const MessageRow = React.memo(
       remove: boolean,
     ) => Promise<void>;
     onReply?: (message: TimelineMessage) => void;
+    onOpenThread?: (message: TimelineMessage) => void;
     onUnfollowThread?: (message: TimelineMessage) => void;
     onEntranceComplete?: (messageId: string) => void;
     playEntrance?: boolean;
@@ -142,6 +145,9 @@ export const MessageRow = React.memo(
     showDepthGuides?: boolean;
     videoReviewContext?: VideoReviewContext;
   }) {
+    // Keep the transient send state with its timestamp rather than collapsing
+    // it into a grouped message row with no header.
+    const isDisplayedAsContinuation = isContinuation && !message.pending;
     const [expandedDiffId, setExpandedDiffId] = React.useState<string | null>(
       null,
     );
@@ -331,7 +337,7 @@ export const MessageRow = React.memo(
             <HuddleAttachment
               channelId={channelId}
               message={message}
-              onOpenThread={onReply}
+              onOpenThread={onOpenThread}
             />
           );
         default:
@@ -383,12 +389,8 @@ export const MessageRow = React.memo(
     const guideBleedRem = isThreadReplyLayout ? 0.25 : 0;
     const avatarButtonRadiusClass = "rounded-full";
 
-    const respondToDotColor =
-      message.respondTo === "anyone"
-        ? "bg-emerald-500"
-        : message.respondTo === "allowlist"
-          ? "bg-amber-500"
-          : null;
+    const showRespondToIndicator =
+      message.respondTo === "anyone" || message.respondTo === "allowlist";
 
     const avatarNode = (
       <div className="relative shrink-0">
@@ -399,18 +401,31 @@ export const MessageRow = React.memo(
           displayName={message.author}
           testId="message-avatar"
         />
-        {respondToDotColor && !isThreadReplyLayout ? (
+        {showRespondToIndicator && !isThreadReplyLayout ? (
           <span
             className={cn(
               "absolute -bottom-0.5 -right-0.5 flex h-3 w-3 items-center justify-center rounded-full bg-background",
             )}
+            role="img"
+            aria-label={
+              message.respondTo === "anyone"
+                ? "Anyone can send instructions to this agent"
+                : "Selected people can send instructions to this agent"
+            }
             title={
               message.respondTo === "anyone"
-                ? "Responds to anyone"
-                : "Responds to allowlist"
+                ? "Anyone can send instructions to this agent"
+                : "Selected people can send instructions to this agent"
             }
           >
-            <span className={cn("h-2 w-2 rounded-full", respondToDotColor)} />
+            {message.respondTo === "anyone" ? (
+              <AlertTriangle
+                aria-hidden="true"
+                className="h-2.5 w-2.5 fill-background text-amber-500"
+              />
+            ) : (
+              <span className="h-2 w-2 rounded-full bg-blue-500" />
+            )}
           </span>
         ) : null}
       </div>
@@ -420,8 +435,8 @@ export const MessageRow = React.memo(
       <div
         aria-hidden="true"
         className={cn(
-          "flex w-9 shrink-0 items-start justify-end pt-0.5",
-          isThreadReplyLayout ? "min-h-9 self-start" : "self-stretch",
+          "flex w-9 shrink-0 justify-end items-start pt-0.5",
+          isThreadReplyLayout ? "self-start" : "self-stretch",
         )}
       >
         <MessageTimestamp
@@ -433,7 +448,7 @@ export const MessageRow = React.memo(
       </div>
     );
 
-    const avatarGutterNode = isContinuation ? (
+    const avatarGutterNode = isDisplayedAsContinuation ? (
       continuationTimestampGutter
     ) : message.pubkey ? (
       <UserProfilePopover
@@ -472,7 +487,9 @@ export const MessageRow = React.memo(
         className={cn(
           "absolute right-2 top-1 z-10 sm:pointer-events-none",
           actionBarPlacement === "floating"
-            ? "sm:top-0 sm:-translate-y-1/2"
+            ? isContinuation
+              ? "sm:-top-3 sm:-translate-y-1/2"
+              : "sm:top-0 sm:-translate-y-1/2"
             : "sm:top-1 sm:translate-y-0",
         )}
       >
@@ -505,7 +522,12 @@ export const MessageRow = React.memo(
       message.pending || message.edited ? (
         <>
           {message.pending ? (
-            <p className="font-medium text-primary/80">Sending</p>
+            <p
+              className="font-normal text-muted-foreground/70"
+              data-testid="message-send-status"
+            >
+              Sending…
+            </p>
           ) : null}
           {message.edited ? (
             <Tooltip>
@@ -526,13 +548,13 @@ export const MessageRow = React.memo(
     );
 
     const continuationMetadataNode =
-      isContinuation && statusMetadataNode ? (
+      isDisplayedAsContinuation && statusMetadataNode ? (
         <div className="mt-0.5 flex items-baseline gap-2 text-xs">
           {statusMetadataNode}
         </div>
       ) : null;
 
-    const headerNode = isContinuation ? null : (
+    const headerNode = isDisplayedAsContinuation ? null : (
       <MessageHeaderRow>
         {message.pubkey ? (
           <UserProfilePopover
@@ -560,7 +582,9 @@ export const MessageRow = React.memo(
         ) : null}
       </MessageHeaderRow>
     );
-    const bodyContainerClass = isContinuation ? "mt-0" : bodyOffsetClass;
+    const bodyContainerClass = isDisplayedAsContinuation
+      ? "mt-0"
+      : bodyOffsetClass;
 
     const messageBodyNode = (
       <>
@@ -778,7 +802,7 @@ export const MessageRow = React.memo(
                 ? "mx-1 px-2"
                 : "px-2",
             "flex gap-2.5",
-            isContinuation ? "items-center" : "items-start",
+            isDisplayedAsContinuation ? "items-center" : "items-start",
             hasActiveReminder ? "bg-blue-500/10" : "",
             highlighted
               ? "-mx-4 rounded-none px-6 before:absolute before:-inset-y-1.5 before:inset-x-0 before:animate-[route-target-highlight-fade_2s_ease-out_forwards] before:bg-primary/10 before:content-[''] motion-reduce:before:animate-none sm:-mx-6 sm:px-8"
diff --git a/desktop/src/features/messages/ui/MessageThreadPanel.tsx b/desktop/src/features/messages/ui/MessageThreadPanel.tsx
index 08a57fa4c6..85a6f6b930 100644
--- a/desktop/src/features/messages/ui/MessageThreadPanel.tsx
+++ b/desktop/src/features/messages/ui/MessageThreadPanel.tsx
@@ -108,7 +108,7 @@ type MessageThreadPanelProps = ThreadPanelLayoutProps & {
   threadUnreadCount?: number;
   threadReplyUnreadCounts?: ReadonlyMap<string, number>;
   threadTypingPubkeys: string[];
-  threadHeadVideoReviewContext?: VideoReviewContext;
+  videoReviewContextsByMessageId?: ReadonlyMap<string, VideoReviewContext>;
   activityAccessoryContent?: React.ReactNode;
   activityAccessoryVisible: boolean;
   widthPx: number;
@@ -221,7 +221,7 @@ export function MessageThreadPanel({
   scrollTargetId,
   scrollTargetHighlights = true,
   threadHead,
-  threadHeadVideoReviewContext,
+  videoReviewContextsByMessageId,
   threadReplies,
   threadRepliesPending = false,
   threadUnreadCount,
@@ -600,7 +600,9 @@ export function MessageThreadPanel({
               }
               profiles={profiles}
               showDepthGuides={shouldShowThreadBranchGuides}
-              videoReviewContext={threadHeadVideoReviewContext}
+              videoReviewContext={videoReviewContextsByMessageId?.get(
+                threadHead.id,
+              )}
             />
           </div>
         </div>
@@ -753,9 +755,13 @@ export function MessageThreadPanel({
                         onMarkUnread={onMarkUnread}
                         onMarkRead={onMarkRead}
                         onReply={onSelectReplyTarget}
+                        onOpenThread={onExpandReplies}
                         onToggleReaction={onToggleReaction}
                         profiles={profiles}
                         showDepthGuides={shouldShowThreadBranchGuides}
+                        videoReviewContext={videoReviewContextsByMessageId?.get(
+                          entry.message.id,
+                        )}
                       />
                       {entry.summary ? (
                         <MessageThreadSummaryRow
diff --git a/desktop/src/features/messages/ui/MessageTimeline.tsx b/desktop/src/features/messages/ui/MessageTimeline.tsx
index cc5fb1e3dc..954da08b01 100644
--- a/desktop/src/features/messages/ui/MessageTimeline.tsx
+++ b/desktop/src/features/messages/ui/MessageTimeline.tsx
@@ -84,6 +84,7 @@ type MessageTimelineProps = {
   onMarkUnread?: (message: TimelineMessage) => void;
   onMarkRead?: (message: TimelineMessage) => void;
   onReply?: (message: TimelineMessage) => void;
+  onOpenThread?: (message: TimelineMessage) => void;
   isSendingVideoReviewComment?: boolean;
   onSendVideoReviewComment?: (
     message: TimelineMessage,
@@ -178,6 +179,7 @@ const MessageTimelineBase = React.forwardRef<
     onMarkUnread,
     onMarkRead,
     onReply,
+    onOpenThread,
     channelName,
     channelType,
     isSendingVideoReviewComment = false,
@@ -635,6 +637,7 @@ const MessageTimelineBase = React.forwardRef<
       onMarkUnread={onMarkUnread}
       onMarkRead={onMarkRead}
       onReply={onReply}
+      onOpenThread={onOpenThread}
       isSendingVideoReviewComment={isSendingVideoReviewComment}
       onSendVideoReviewComment={onSendVideoReviewComment}
       onStartReached={loadOlderViaVirtualizer}
diff --git a/desktop/src/features/messages/ui/SystemMessageRow.tsx b/desktop/src/features/messages/ui/SystemMessageRow.tsx
index 4410964dd9..c4637d2823 100644
--- a/desktop/src/features/messages/ui/SystemMessageRow.tsx
+++ b/desktop/src/features/messages/ui/SystemMessageRow.tsx
@@ -28,6 +28,10 @@ import {
 import { Popover, PopoverContent, PopoverTrigger } from "@/shared/ui/popover";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
 import { UserAvatar } from "@/shared/ui/UserAvatar";
+import {
+  describeChannelTextFieldChange,
+  toInlineName,
+} from "../lib/systemEventCopy";
 import { MessageAgentOwner } from "./MessageAgentOwner";
 import { MessageAuthorText, MessageHeaderRow } from "./MessageHeader";
 import { MessageTimestamp } from "./MessageTimestamp";
@@ -180,6 +184,29 @@ function resolveDisplayLabel(
   return resolveLabel(pubkey, currentPubkey, profiles);
 }
 
+function isSelfPubkey(
+  pubkey: string | undefined,
+  currentPubkey: string | undefined,
+): boolean {
+  return Boolean(
+    pubkey &&
+      currentPubkey &&
+      normalizePubkey(pubkey) === normalizePubkey(currentPubkey),
+  );
+}
+
+/** Same label as `resolveDisplayLabel`, adjusted for mid-sentence use. */
+function resolveInlineDisplayLabel(
+  pubkey: string | undefined,
+  currentPubkey: string | undefined,
+  profiles: UserProfileLookup | undefined,
+): string {
+  return toInlineName(
+    resolveLabel(pubkey, currentPubkey, profiles),
+    isSelfPubkey(pubkey, currentPubkey),
+  );
+}
+
 function isKnownAgentPubkey(
   pubkey: string | undefined,
   profiles: UserProfileLookup | undefined,
@@ -386,7 +413,7 @@ function MembershipPersonName({
       pubkey={pubkey}
       underlineOnHover
     >
-      {resolveDisplayLabel(pubkey, currentPubkey, profiles)}
+      {resolveInlineDisplayLabel(pubkey, currentPubkey, profiles)}
     </ProfileName>
   );
 }
@@ -497,12 +524,17 @@ function describeSystemEvent(
     currentPubkey,
     profiles,
   );
+  const inlineTargetLabel = resolveInlineDisplayLabel(
+    payload.target,
+    currentPubkey,
+    profiles,
+  );
   const actorName = (
     <ProfileName pubkey={payload.actor}>{actorLabel}</ProfileName>
   );
   const targetName = (
     <ProfileName highlight isAgent={isTargetAgent} pubkey={payload.target}>
-      {targetLabel}
+      {inlineTargetLabel}
     </ProfileName>
   );
   const membershipTitle = (
@@ -522,9 +554,13 @@ function describeSystemEvent(
         title: membershipTitle,
         action: (
           <>
-            was added by{" "}
+            added by{" "}
             <ProfileName pubkey={payload.actor} underlineOnHover>
-              {resolveDisplayLabel(payload.actor, currentPubkey, profiles)}
+              {resolveInlineDisplayLabel(
+                payload.actor,
+                currentPubkey,
+                profiles,
+              )}
             </ProfileName>
             , along with{" "}
             <MemberNamesInlineList
@@ -566,9 +602,13 @@ function describeSystemEvent(
         title: membershipTitle,
         action: (
           <>
-            was added by{" "}
+            added by{" "}
             <ProfileName pubkey={payload.actor} underlineOnHover>
-              {resolveDisplayLabel(payload.actor, currentPubkey, profiles)}
+              {resolveInlineDisplayLabel(
+                payload.actor,
+                currentPubkey,
+                profiles,
+              )}
             </ProfileName>
           </>
         ),
@@ -587,12 +627,12 @@ function describeSystemEvent(
     case "topic_changed":
       return {
         title: actorName,
-        action: <>changed the topic to &ldquo;{payload.topic}&rdquo;</>,
+        action: describeChannelTextFieldChange("topic", payload.topic),
       };
     case "purpose_changed":
       return {
         title: actorName,
-        action: <>changed the purpose to &ldquo;{payload.purpose}&rdquo;</>,
+        action: describeChannelTextFieldChange("purpose", payload.purpose),
       };
     case "channel_created":
       return {
diff --git a/desktop/src/features/messages/ui/TimelineMessageList.tsx b/desktop/src/features/messages/ui/TimelineMessageList.tsx
index 3c35cb6d43..89183d0856 100644
--- a/desktop/src/features/messages/ui/TimelineMessageList.tsx
+++ b/desktop/src/features/messages/ui/TimelineMessageList.tsx
@@ -22,11 +22,8 @@ import { THREAD_REPLY_ROW_MARGIN_INLINE_REM } from "@/features/messages/lib/thre
 import { buildMainTimelineEntries } from "@/features/messages/lib/threadPanel";
 import type { MainTimelineEntry } from "@/features/messages/lib/threadPanel";
 import type { ChannelWindowThreadSummary } from "@/features/messages/lib/channelWindowStore";
-import {
-  buildVideoReviewCommentsByRootId,
-  buildVideoReviewContextForMessage,
-  hasVideoAttachment,
-} from "@/features/messages/lib/videoReviewContext";
+import { buildVideoReviewContextsByMessageId } from "@/features/messages/lib/videoReviewContext";
+import type { buildVideoReviewContextForMessage } from "@/features/messages/lib/videoReviewContext";
 import type { TimelineMessage } from "@/features/messages/types";
 import { canManageMessageForCurrentUser } from "@/features/messages/lib/canManageMessage";
 import type { UserProfileLookup } from "@/features/profile/lib/identity";
@@ -80,6 +77,7 @@ type TimelineMessageListProps = {
   onMarkUnread?: (message: TimelineMessage) => void;
   onMarkRead?: (message: TimelineMessage) => void;
   onReply?: (message: TimelineMessage) => void;
+  onOpenThread?: (message: TimelineMessage) => void;
   isSendingVideoReviewComment?: boolean;
   onSendVideoReviewComment?: (
     message: TimelineMessage,
@@ -145,6 +143,7 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
   onMarkUnread,
   onMarkRead,
   onReply,
+  onOpenThread,
   isSendingVideoReviewComment = false,
   onSendVideoReviewComment,
   onToggleReaction,
@@ -170,40 +169,21 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
       buildMainTimelineEntries(messages, undefined, threadSummaries, profiles),
     [mainEntries, messages, profiles, threadSummaries],
   );
-  const reviewCommentsByRootId = React.useMemo(
-    () =>
-      messages.some(hasVideoAttachment)
-        ? buildVideoReviewCommentsByRootId(messages)
-        : new Map<string, TimelineMessage[]>(),
-    [messages],
-  );
   // Contexts are memoized per message id so MessageRow/Markdown memo
   // comparisons hold across unrelated timeline re-renders (typing
   // indicators, presence updates) — a fresh context object per render would
   // defeat the memo and re-render every video message on every pass.
   const videoReviewContextById = React.useMemo(() => {
-    const contexts = new Map<
-      string,
-      NonNullable<ReturnType<typeof buildVideoReviewContextForMessage>>
-    >();
-    for (const message of messages) {
-      const comments = reviewCommentsByRootId.get(message.id) ?? [];
-      const context = buildVideoReviewContextForMessage({
-        channelId,
-        channelName,
-        channelType,
-        comments,
-        isSendingVideoReviewComment,
-        message,
-        onSendVideoReviewComment,
-        onToggleReaction,
-        profiles,
-      });
-      if (context) {
-        contexts.set(message.id, context);
-      }
-    }
-    return contexts;
+    return buildVideoReviewContextsByMessageId({
+      channelId,
+      channelName,
+      channelType,
+      isSendingVideoReviewComment,
+      messages,
+      onSendVideoReviewComment,
+      onToggleReaction,
+      profiles,
+    });
   }, [
     channelId,
     channelName,
@@ -213,7 +193,6 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
     onSendVideoReviewComment,
     onToggleReaction,
     profiles,
-    reviewCommentsByRootId,
   ]);
 
   // The flattened item stream, memoized on the entries and the unread boundary
@@ -278,6 +257,7 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
               onMarkRead={onMarkRead}
               onMarkUnread={onMarkUnread}
               onReply={onReply}
+              onOpenThread={onOpenThread}
               onToggleReaction={onToggleReaction}
               profiles={profiles}
               searchActiveMessageId={searchActiveMessageId}
@@ -309,6 +289,7 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
       onMarkRead,
       onMarkUnread,
       onReply,
+      onOpenThread,
       onToggleReaction,
       profiles,
       ownerProfiles,
@@ -722,6 +703,7 @@ type MessageRowItemProps = Pick<
   | "onMarkUnread"
   | "onMarkRead"
   | "onReply"
+  | "onOpenThread"
   | "onToggleReaction"
   | "profiles"
   | "searchActiveMessageId"
@@ -760,6 +742,7 @@ function MessageRowItem({
   onMarkUnread,
   onMarkRead,
   onReply,
+  onOpenThread,
   onToggleReaction,
   profiles,
   searchActiveMessageId,
@@ -778,7 +761,7 @@ function MessageRowItem({
   const canDelete = canManage && onDelete ? onDelete : undefined;
   const canEdit = canManage && onEdit ? onEdit : undefined;
 
-  if (summary && onReply) {
+  if (summary && onOpenThread) {
     const isHighlighted = message.id === highlightedMessageId;
     return (
       <div
@@ -813,6 +796,7 @@ function MessageRowItem({
           onMarkUnread={onMarkUnread}
           onToggleReaction={onToggleReaction}
           onReply={onReply}
+          onOpenThread={onOpenThread}
           onUnfollowThread={
             unfollowThreadById
               ? () => unfollowThreadById(message.id)
@@ -825,7 +809,7 @@ function MessageRowItem({
         <MessageThreadSummaryRow
           depth={message.depth}
           message={message}
-          onOpenThread={onReply}
+          onOpenThread={onOpenThread}
           showDepthGuides={false}
           summary={summary}
           summaryIndentOffsetRem={-THREAD_REPLY_ROW_MARGIN_INLINE_REM}
@@ -862,6 +846,7 @@ function MessageRowItem({
         onMarkUnread={onMarkUnread}
         onToggleReaction={onToggleReaction}
         onReply={onReply}
+        onOpenThread={onOpenThread}
         profiles={profiles}
         searchQuery={isSearchMatch ? searchQuery : undefined}
         showDepthGuides={false}
diff --git a/desktop/src/features/messages/ui/useAnchoredScroll.lifecycle.test.mjs b/desktop/src/features/messages/ui/useAnchoredScroll.lifecycle.test.mjs
index 1fdfb05857..ee3fec1a98 100644
--- a/desktop/src/features/messages/ui/useAnchoredScroll.lifecycle.test.mjs
+++ b/desktop/src/features/messages/ui/useAnchoredScroll.lifecycle.test.mjs
@@ -247,13 +247,20 @@ function Harness({ channelId, onTargetSettled, refs }) {
   return null;
 }
 
-function BottomStateHarness({ messages, onState, refs }) {
+function BottomStateHarness({
+  messages,
+  onState,
+  refs,
+  targetMessageId = null,
+}) {
   const anchored = useAnchoredScroll({
     channelId: "conversation",
     contentRef: refs.content,
     isLoading: false,
     messages,
+    pinTargetCentered: targetMessageId !== null,
     scrollContainerRef: refs.container,
+    targetMessageId,
   });
   onState(anchored);
   return null;
@@ -329,6 +336,90 @@ test("channel change attaches pinned-center observers after refs mount", async (
   });
 });
 
+test("arrival at the physical floor does not preserve a stale unread state", async () => {
+  const refs = {
+    container: { current: null },
+    content: { current: null },
+  };
+  const root = createRoot(document.createElement("div"));
+  const nodes = makePinnedCenterNodes();
+  refs.container.current = nodes.container;
+  refs.content.current = nodes.content;
+  let state = null;
+  const render = (messages) =>
+    root.render(
+      React.createElement(BottomStateHarness, {
+        messages,
+        onState: (nextState) => {
+          state = nextState;
+        },
+        refs,
+      }),
+    );
+
+  await act(async () => render([{ id: "first" }]));
+  await act(async () => new Promise((resolve) => setTimeout(resolve, 0)));
+  nodes.container.scrollTop = 100;
+  await act(async () => state.onScroll());
+  nodes.container.scrollTop = 100;
+  await act(async () => state.onScroll());
+  assert.equal(state.isAtBottom, false);
+
+  // Native anchoring can return the viewport to the floor without a scroll or
+  // resize callback, leaving only the hook's cached message anchor stale.
+  nodes.container.scrollTop =
+    nodes.container.scrollHeight - nodes.container.clientHeight;
+  await act(async () => render([{ id: "first" }, { id: "second" }]));
+
+  assert.equal(state.isAtBottom, true);
+  assert.equal(state.newMessageCount, 0);
+  await act(async () => root.unmount());
+});
+
+test("arrival does not steal an active layout target during floor-like reflow", async () => {
+  const refs = {
+    container: { current: null },
+    content: { current: null },
+  };
+  const root = createRoot(document.createElement("div"));
+  const nodes = makePinnedCenterNodes();
+  refs.container.current = nodes.container;
+  refs.content.current = nodes.content;
+  let state = null;
+  const render = (messages, targetMessageId = null) =>
+    root.render(
+      React.createElement(BottomStateHarness, {
+        messages,
+        onState: (nextState) => {
+          state = nextState;
+        },
+        refs,
+        targetMessageId,
+      }),
+    );
+
+  await act(async () => render([{ id: "selected" }]));
+  await act(async () => new Promise((resolve) => setTimeout(resolve, 0)));
+  nodes.container.scrollTop = 100;
+  await act(async () => state.onScroll());
+  nodes.container.scrollTop = 100;
+  await act(async () => state.onScroll());
+  assert.equal(state.isAtBottom, false);
+
+  // A focus/split presentation switch can commit fresh replies while the old
+  // container geometry momentarily reads as the physical floor. The explicit
+  // layout target must win so the reading row is restored after reflow.
+  nodes.container.scrollTop =
+    nodes.container.scrollHeight - nodes.container.clientHeight;
+  await act(async () =>
+    render([{ id: "selected" }, { id: "second" }], "selected"),
+  );
+
+  assert.equal(state.isAtBottom, false);
+  assert.equal(state.newMessageCount, 1);
+  await act(async () => root.unmount());
+});
+
 test("container resize clears a stale new-message state at the physical floor", async () => {
   const refs = {
     container: { current: null },
diff --git a/desktop/src/features/messages/ui/useAnchoredScroll.ts b/desktop/src/features/messages/ui/useAnchoredScroll.ts
index add9439599..0bfcb3b3e2 100644
--- a/desktop/src/features/messages/ui/useAnchoredScroll.ts
+++ b/desktop/src/features/messages/ui/useAnchoredScroll.ts
@@ -714,6 +714,22 @@ export function useAnchoredScroll({
         container.scrollTo({ top: container.scrollHeight, behavior: "auto" });
       }
       if (newLatestArrived) setNewMessageCount(0);
+    } else if (
+      messagesArrived > 0 &&
+      !targetMessageId &&
+      !virtualizerOwnsPrependAnchoring &&
+      isAtBottomNow(container)
+    ) {
+      // A native scroll/layout callback may not have reconciled a stale
+      // message anchor before this append commits. If the rendered result is
+      // still physically at the floor (common in short threads), do not turn
+      // that stale anchor into a visible unread affordance. Active navigation
+      // targets own the viewport and must be preserved across presentation
+      // reflow even when the old geometry momentarily reads as the floor.
+      anchorRef.current = { kind: "at-bottom" };
+      container.scrollTo({ top: container.scrollHeight, behavior: "auto" });
+      setIsAtBottom(true);
+      setNewMessageCount(0);
     } else if (messagesArrived > 0 && !virtualizerOwnsPrependAnchoring) {
       // Anchored mid-history. An older-history prepend grows the content above
       // the reading row; the browser's native scroll anchoring does NOT correct
diff --git a/desktop/src/features/onboarding/lib/encryptedBackup.test.mjs b/desktop/src/features/onboarding/lib/encryptedBackup.test.mjs
new file mode 100644
index 0000000000..b570153185
--- /dev/null
+++ b/desktop/src/features/onboarding/lib/encryptedBackup.test.mjs
@@ -0,0 +1,118 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  MIN_PASSPHRASE_LEN,
+  downloadDisabled,
+  isEncrypting,
+  passphraseIssue,
+  pendingEncryptPassphrase,
+  effectivePassphrase,
+  encryptedBackupReducer,
+  initialEncryptedBackupState,
+} from "./encryptedBackup.ts";
+const reduce = (events, from = initialEncryptedBackupState) =>
+  events.reduce(encryptedBackupReducer, from);
+test("password validation mirrors Rust character counting", () => {
+  assert.equal(passphraseIssue(""), null);
+  assert.match(passphraseIssue("short"), new RegExp(`${MIN_PASSPHRASE_LEN}`));
+  const emoji = "😀".repeat(MIN_PASSPHRASE_LEN);
+  assert.equal(passphraseIssue(emoji), null);
+  assert.equal(
+    effectivePassphrase(reduce([{ type: "set-passphrase", value: emoji }])),
+    emoji,
+  );
+});
+test("valid password requests encryption without copying it into events", () => {
+  const ready = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+  ]);
+  assert.equal(pendingEncryptPassphrase(ready), "one-two-three-four");
+  const started = reduce([{ type: "encrypt-started", requestId: 1 }], ready);
+  assert.equal(isEncrypting(started), true);
+  assert.equal(started.requestId, 1);
+  assert.equal(Object.hasOwn(started, "encryptingPassphrase"), false);
+});
+test("background encryption remains silent until download is clicked", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "encrypt-succeeded", requestId: 1, ncryptsec: "ncryptsec1abc" },
+  ]);
+  assert.equal(state.passphrase, "one-two-three-four");
+  assert.equal(state.encrypted, "ncryptsec1abc");
+  assert.equal(state.ncryptsec, null);
+  assert.equal(state.savedPassword, false);
+  assert.equal(state.requestId, null);
+});
+test("stale async completions cannot replace current request", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "set-passphrase", value: "five-six-seven-eight" },
+    { type: "encrypt-started", requestId: 2 },
+    { type: "encrypt-succeeded", requestId: 1, ncryptsec: "ncryptsec1stale" },
+  ]);
+  assert.equal(state.requestId, 2);
+  assert.equal(state.encrypted, null);
+  assert.equal(state.passphrase, "five-six-seven-eight");
+});
+test("failure clears submitted password", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "download-clicked" },
+    { type: "encrypt-failed", requestId: 1, message: "keychain unavailable" },
+  ]);
+  assert.equal(state.passphrase, "");
+  assert.equal(state.createError, "keychain unavailable");
+  assert.equal(state.downloadPending, false);
+  assert.equal(downloadDisabled(state), true);
+});
+test("queued download commits and clears password", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "download-clicked" },
+    { type: "encrypt-succeeded", requestId: 1, ncryptsec: "ncryptsec1abc" },
+  ]);
+  assert.equal(state.ncryptsec, "ncryptsec1abc");
+  assert.equal(state.passphrase, "");
+  assert.equal(state.savedPassword, true);
+});
+test("Back preserves blob for immediate re-download without password", () => {
+  const made = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "encrypt-succeeded", requestId: 1, ncryptsec: "ncryptsec1abc" },
+    { type: "download-clicked" },
+    { type: "back-to-password" },
+  ]);
+  assert.equal(made.ncryptsec, "ncryptsec1abc");
+  assert.equal(made.passphrase, "");
+  assert.equal(downloadDisabled(made), false);
+});
+test("starting over discards blob and invalidates late requests", () => {
+  const made = {
+    ...initialEncryptedBackupState,
+    ncryptsec: "ncryptsec1abc",
+    encrypted: "ncryptsec1abc",
+    savedPassword: true,
+    nextRequestId: 3,
+  };
+  const fresh = reduce([{ type: "start-new-backup" }], made);
+  assert.equal(fresh.ncryptsec, null);
+  assert.equal(fresh.nextRequestId, 4);
+  assert.equal(
+    reduce(
+      [
+        {
+          type: "encrypt-succeeded",
+          requestId: 2,
+          ncryptsec: "ncryptsec1stale",
+        },
+      ],
+      fresh,
+    ).ncryptsec,
+    null,
+  );
+});
diff --git a/desktop/src/features/onboarding/lib/encryptedBackup.ts b/desktop/src/features/onboarding/lib/encryptedBackup.ts
new file mode 100644
index 0000000000..2f7d4a0bb0
--- /dev/null
+++ b/desktop/src/features/onboarding/lib/encryptedBackup.ts
@@ -0,0 +1,135 @@
+/** Pure state model for NIP-49 backup creation. */
+export const MIN_PASSPHRASE_LEN = 12;
+
+export type EncryptedBackupState = {
+  passphrase: string;
+  requestId: number | null;
+  nextRequestId: number;
+  encrypted: string | null;
+  createError: string | null;
+  downloadPending: boolean;
+  ncryptsec: string | null;
+  savedPassword: boolean;
+};
+
+export const initialEncryptedBackupState: EncryptedBackupState = {
+  passphrase: "",
+  requestId: null,
+  nextRequestId: 1,
+  encrypted: null,
+  createError: null,
+  downloadPending: false,
+  ncryptsec: null,
+  savedPassword: false,
+};
+
+export type EncryptedBackupEvent =
+  | { type: "set-passphrase"; value: string }
+  | { type: "encrypt-started"; requestId: number }
+  | { type: "encrypt-succeeded"; requestId: number; ncryptsec: string }
+  | { type: "encrypt-failed"; requestId: number; message: string }
+  | { type: "download-clicked" }
+  | { type: "back-to-password" }
+  | { type: "start-new-backup" };
+
+export function encryptedBackupReducer(
+  state: EncryptedBackupState,
+  event: EncryptedBackupEvent,
+): EncryptedBackupState {
+  switch (event.type) {
+    case "set-passphrase":
+      return {
+        ...state,
+        passphrase: event.value,
+        encrypted: null,
+        createError: null,
+      };
+    case "encrypt-started":
+      return {
+        ...state,
+        requestId: event.requestId,
+        nextRequestId: Math.max(state.nextRequestId, event.requestId + 1),
+        createError: null,
+      };
+    case "encrypt-succeeded":
+      if (event.requestId !== state.requestId) return state;
+      if (state.downloadPending) {
+        return {
+          ...state,
+          passphrase: "",
+          requestId: null,
+          encrypted: event.ncryptsec,
+          ncryptsec: event.ncryptsec,
+          downloadPending: false,
+          savedPassword: true,
+        };
+      }
+      return {
+        ...state,
+        requestId: null,
+        encrypted: event.ncryptsec,
+      };
+    case "encrypt-failed":
+      if (event.requestId !== state.requestId) return state;
+      return {
+        ...state,
+        passphrase: "",
+        requestId: null,
+        createError: event.message,
+        downloadPending: false,
+      };
+    case "download-clicked":
+      if (
+        state.ncryptsec ||
+        state.downloadPending ||
+        (!state.encrypted && !effectivePassphrase(state))
+      )
+        return state;
+      return state.encrypted
+        ? {
+            ...state,
+            ncryptsec: state.encrypted,
+            passphrase: "",
+            savedPassword: true,
+          }
+        : { ...state, downloadPending: true };
+    case "back-to-password":
+      return { ...state, createError: null };
+    case "start-new-backup":
+      return {
+        ...initialEncryptedBackupState,
+        nextRequestId: state.nextRequestId + 1,
+      };
+  }
+}
+
+export function passphraseIssue(passphrase: string): string | null {
+  if (passphrase.length === 0) return null;
+  return [...passphrase].length < MIN_PASSPHRASE_LEN
+    ? `Use at least ${MIN_PASSPHRASE_LEN} characters.`
+    : null;
+}
+export function effectivePassphrase(
+  state: EncryptedBackupState,
+): string | null {
+  return [...state.passphrase].length < MIN_PASSPHRASE_LEN
+    ? null
+    : state.passphrase;
+}
+export function pendingEncryptPassphrase(
+  state: EncryptedBackupState,
+): string | null {
+  if (state.savedPassword || state.encrypted || state.requestId !== null)
+    return null;
+  return effectivePassphrase(state);
+}
+export function isEncrypting(state: EncryptedBackupState): boolean {
+  return state.requestId !== null;
+}
+export function downloadDisabled(state: EncryptedBackupState): boolean {
+  if (state.savedPassword && state.ncryptsec) return false;
+  return (
+    state.downloadPending ||
+    (!state.encrypted && effectivePassphrase(state) === null)
+  );
+}
diff --git a/desktop/src/features/onboarding/lib/keyImportInput.test.mjs b/desktop/src/features/onboarding/lib/keyImportInput.test.mjs
new file mode 100644
index 0000000000..bc0bb4b4d7
--- /dev/null
+++ b/desktop/src/features/onboarding/lib/keyImportInput.test.mjs
@@ -0,0 +1,73 @@
+/**
+ * Pure-logic tests for key-import input classification (nsec vs NIP-49
+ * ncryptsec) and submit gating.
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { nsecEncode } from "nostr-tools/nip19";
+import { generateSecretKey } from "nostr-tools/pure";
+import {
+  classifyKeyImportInput,
+  isPlausibleNcryptsec,
+  keyImportSubmitEnabled,
+  NCRYPTSEC_ENCODED_LENGTH,
+} from "./keyImportInput.ts";
+
+// NIP-49 spec vector — structurally valid encrypted backup.
+const NCRYPTSEC =
+  "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+
+const VALID_NSEC = nsecEncode(generateSecretKey());
+
+test("classify_by_hrp_with_whitespace_tolerance", () => {
+  assert.equal(classifyKeyImportInput(`  ${NCRYPTSEC}\n`), "ncryptsec");
+  assert.equal(classifyKeyImportInput(VALID_NSEC), "nsec");
+  assert.equal(classifyKeyImportInput("npub1whatever"), "unknown");
+  assert.equal(classifyKeyImportInput(""), "unknown");
+  // nsec must not be shadowed by the longer HRP check.
+  assert.equal(classifyKeyImportInput("nsec1"), "nsec");
+});
+
+test("uppercase_bech32_encoding_classifies_and_gates_like_lowercase", () => {
+  // Bech32 permits an all-uppercase encoding; it must route to the
+  // encrypted path (matching Rust) and be submit-plausible.
+  const upper = NCRYPTSEC.toUpperCase();
+  assert.equal(classifyKeyImportInput(upper), "ncryptsec");
+  assert.equal(isPlausibleNcryptsec(upper), true);
+  assert.equal(keyImportSubmitEnabled(upper, ""), false);
+  assert.equal(keyImportSubmitEnabled(upper, "hunter2hunter2"), true);
+  // Mixed case: routed encrypted (Rust reports the accurate error) but
+  // never plausible/submittable — mixed-case bech32 cannot decode.
+  const mixed = `N${NCRYPTSEC.slice(1)}`;
+  assert.equal(classifyKeyImportInput(mixed), "ncryptsec");
+  assert.equal(isPlausibleNcryptsec(mixed), false);
+  assert.equal(keyImportSubmitEnabled(mixed, "hunter2hunter2"), false);
+});
+
+test("plausible_ncryptsec_requires_complete_checksummed_nip49_payload", () => {
+  assert.equal(NCRYPTSEC.length, NCRYPTSEC_ENCODED_LENGTH);
+  assert.equal(isPlausibleNcryptsec(NCRYPTSEC), true);
+  assert.equal(isPlausibleNcryptsec(`  ${NCRYPTSEC}\n`), true);
+  assert.equal(isPlausibleNcryptsec(NCRYPTSEC.slice(0, -1)), false);
+  assert.equal(isPlausibleNcryptsec(`${NCRYPTSEC}q`), false);
+  // Same length and charset, but a changed checksum must not advance the UI.
+  assert.equal(isPlausibleNcryptsec(`${NCRYPTSEC.slice(0, -1)}q`), false);
+  // '1' and 'b' / 'i' / 'o' are not in the Bech32 data charset.
+  assert.equal(isPlausibleNcryptsec("ncryptsec1bio"), false);
+  assert.equal(isPlausibleNcryptsec("ncryptsec1"), false);
+  assert.equal(isPlausibleNcryptsec("ncryptsec1 with spaces"), false);
+});
+
+test("submit_gating_nsec_path_unchanged", () => {
+  assert.equal(keyImportSubmitEnabled(VALID_NSEC, ""), true);
+  assert.equal(keyImportSubmitEnabled("nsec1garbage", ""), false);
+  assert.equal(keyImportSubmitEnabled("", ""), false);
+});
+
+test("submit_gating_ncryptsec_requires_passphrase", () => {
+  assert.equal(keyImportSubmitEnabled(NCRYPTSEC, ""), false);
+  assert.equal(keyImportSubmitEnabled(NCRYPTSEC, "hunter2hunter2"), true);
+  // Structurally implausible blob never submits, passphrase or not.
+  assert.equal(keyImportSubmitEnabled("ncryptsec1bio", "hunter2"), false);
+});
diff --git a/desktop/src/features/onboarding/lib/keyImportInput.ts b/desktop/src/features/onboarding/lib/keyImportInput.ts
new file mode 100644
index 0000000000..0f6fc609ed
--- /dev/null
+++ b/desktop/src/features/onboarding/lib/keyImportInput.ts
@@ -0,0 +1,127 @@
+/**
+ * Pure classification + submit gating for the key-import form, unit-testable
+ * without a DOM.
+ *
+ * `ncryptsec1…` is a NIP-49 encrypted backup: no npub preview is possible
+ * (the pubkey is inside the encrypted payload) and a passphrase is required.
+ * Password validation happens in Rust at decrypt time; this module performs
+ * the password-independent Bech32 and NIP-49 structure checks needed to decide
+ * when the form can safely switch modes.
+ */
+
+import { nsecToNpub } from "@/shared/lib/nostrUtils";
+
+export type KeyImportKind = "nsec" | "ncryptsec" | "unknown";
+
+const NCRYPTSEC_HRP = "ncryptsec";
+const NIP49_VERSION = 2;
+const NIP49_PAYLOAD_BYTES = 91;
+/** Current NIP-49 payloads encode to 162 characters including the checksum. */
+export const NCRYPTSEC_ENCODED_LENGTH = 162;
+const BECH32_CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
+const BECH32_GENERATORS = [
+  0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3,
+] as const;
+
+function bech32Polymod(values: readonly number[]): number {
+  let checksum = 1;
+  for (const value of values) {
+    const high = checksum >>> 25;
+    checksum = ((checksum & 0x1ffffff) << 5) ^ value;
+    for (let index = 0; index < BECH32_GENERATORS.length; index += 1) {
+      if ((high >>> index) & 1) checksum ^= BECH32_GENERATORS[index];
+    }
+  }
+  return checksum >>> 0;
+}
+
+function expandBech32Hrp(hrp: string): number[] {
+  return [
+    ...Array.from(hrp, (character) => character.charCodeAt(0) >>> 5),
+    0,
+    ...Array.from(hrp, (character) => character.charCodeAt(0) & 31),
+  ];
+}
+
+function convertFiveBitWordsToBytes(words: readonly number[]): number[] | null {
+  let accumulator = 0;
+  let bitCount = 0;
+  const bytes: number[] = [];
+
+  for (const word of words) {
+    accumulator = (accumulator << 5) | word;
+    bitCount += 5;
+    while (bitCount >= 8) {
+      bitCount -= 8;
+      bytes.push((accumulator >>> bitCount) & 0xff);
+    }
+  }
+
+  // Bech32 conversion without padding permits fewer than five zero remainder
+  // bits. Any larger or non-zero remainder is not a canonical byte encoding.
+  if (bitCount >= 5 || ((accumulator << (8 - bitCount)) & 0xff) !== 0) {
+    return null;
+  }
+  return bytes;
+}
+
+export function classifyKeyImportInput(input: string): KeyImportKind {
+  const trimmed = input.trim();
+  // Case-insensitive on the HRP to match the Rust classifier: an uppercase
+  // valid backup routes to the encrypted path (and decodes there); mixed
+  // case routes there too and fails in Rust with the accurate error.
+  if (trimmed.slice(0, 10).toLowerCase() === "ncryptsec1") return "ncryptsec";
+  if (trimmed.startsWith("nsec1")) return "nsec";
+  return "unknown";
+}
+
+/**
+ * Password-independent NIP-49 validation used for the automatic UI transition.
+ * A candidate must have canonical casing and length, a valid Bech32 checksum,
+ * and the current 91-byte/version-2 NIP-49 payload shape.
+ */
+export function isPlausibleNcryptsec(input: string): boolean {
+  const trimmed = input.trim();
+  if (trimmed.length !== NCRYPTSEC_ENCODED_LENGTH) return false;
+  if (trimmed !== trimmed.toLowerCase() && trimmed !== trimmed.toUpperCase()) {
+    return false;
+  }
+
+  const normalized = trimmed.toLowerCase();
+  const separatorIndex = normalized.lastIndexOf("1");
+  if (
+    separatorIndex !== NCRYPTSEC_HRP.length ||
+    normalized.slice(0, separatorIndex) !== NCRYPTSEC_HRP
+  ) {
+    return false;
+  }
+
+  const encoded = normalized.slice(separatorIndex + 1);
+  const words = Array.from(encoded, (character) =>
+    BECH32_CHARSET.indexOf(character),
+  );
+  if (words.some((word) => word < 0) || words.length <= 6) return false;
+  if (bech32Polymod([...expandBech32Hrp(NCRYPTSEC_HRP), ...words]) !== 1) {
+    return false;
+  }
+
+  const payload = convertFiveBitWordsToBytes(words.slice(0, -6));
+  return (
+    payload?.length === NIP49_PAYLOAD_BYTES && payload[0] === NIP49_VERSION
+  );
+}
+
+/**
+ * Whether the import form's submit should be enabled.
+ * nsec: must derive an npub. ncryptsec: plausible blob + non-empty passphrase.
+ */
+export function keyImportSubmitEnabled(
+  input: string,
+  passphrase: string,
+): boolean {
+  const kind = classifyKeyImportInput(input);
+  if (kind === "ncryptsec") {
+    return isPlausibleNcryptsec(input) && passphrase.length > 0;
+  }
+  return nsecToNpub(input) !== null;
+}
diff --git a/desktop/src/features/onboarding/ui/BackupPasswordTimeline.tsx b/desktop/src/features/onboarding/ui/BackupPasswordTimeline.tsx
new file mode 100644
index 0000000000..610c104d95
--- /dev/null
+++ b/desktop/src/features/onboarding/ui/BackupPasswordTimeline.tsx
@@ -0,0 +1,130 @@
+import { FileKey2, LockKeyhole, LockOpen } from "lucide-react";
+import { motion, useReducedMotion } from "motion/react";
+
+import { cn } from "@/shared/lib/cn";
+
+const BACKUP_KEY_DOTS = [
+  "key-dot-1",
+  "key-dot-2",
+  "key-dot-3",
+  "key-dot-4",
+  "key-dot-5",
+  "key-dot-6",
+  "key-dot-7",
+  "key-dot-8",
+  "key-dot-9",
+] as const;
+
+const TIMELINE_CONNECTOR_DOTS = [
+  "connector-dot-1",
+  "connector-dot-2",
+  "connector-dot-3",
+  "connector-dot-4",
+] as const;
+
+const TIMELINE_DOT_INITIAL = { opacity: 0.35, scale: 0.85 };
+const TIMELINE_DOT_PULSE = {
+  opacity: [0.35, 1, 0.35],
+  scale: [0.85, 1.25, 0.85],
+};
+const TIMELINE_DOT_TRANSITION = {
+  duration: 0.7,
+  ease: "easeInOut" as const,
+  repeat: Number.POSITIVE_INFINITY,
+  repeatDelay: 1.2,
+};
+const TIMELINE_TOP_DOT_TRANSITIONS = TIMELINE_CONNECTOR_DOTS.map(
+  (_, index) => ({
+    ...TIMELINE_DOT_TRANSITION,
+    delay: index * 0.16,
+  }),
+);
+const TIMELINE_BOTTOM_DOT_TRANSITIONS = TIMELINE_CONNECTOR_DOTS.map(
+  (_, index) => ({
+    ...TIMELINE_DOT_TRANSITION,
+    delay: (index + TIMELINE_CONNECTOR_DOTS.length) * 0.16 + 0.24,
+  }),
+);
+
+/**
+ * Decorative timeline shared by backup creation and encrypted-backup restore.
+ * Backup creation reads key → password → lock; restore reads encrypted file →
+ * password → unlocked account. The password field is layered over the center.
+ */
+export function BackupPasswordTimeline({
+  className,
+  mode = "backup",
+}: {
+  className?: string;
+  mode?: "backup" | "restore";
+}) {
+  const reduceMotion = useReducedMotion() ?? false;
+
+  return (
+    <div
+      aria-hidden
+      className={cn(
+        "pointer-events-none absolute inset-0 [@media(max-height:40rem)]:hidden",
+        className,
+      )}
+      data-testid="backup-password-timeline"
+    >
+      {mode === "restore" ? (
+        <div
+          className="absolute left-1/2 top-0 -translate-x-1/2 text-foreground/85"
+          data-testid="restore-ncryptsec-affordance"
+        >
+          <FileKey2 className="size-10" />
+        </div>
+      ) : (
+        <div className="absolute inset-x-0 top-4 flex items-center justify-center gap-2">
+          {BACKUP_KEY_DOTS.map((dot) => (
+            <span
+              className="block size-2 rounded-full bg-foreground/85"
+              key={dot}
+            />
+          ))}
+        </div>
+      )}
+      <div
+        className={cn(
+          "absolute left-1/2 flex h-12 -translate-x-1/2 flex-col justify-between",
+          mode === "restore" ? "top-15" : "top-11",
+        )}
+      >
+        {TIMELINE_CONNECTOR_DOTS.map((dot, index) => (
+          <motion.span
+            animate={reduceMotion ? undefined : TIMELINE_DOT_PULSE}
+            className="block size-1.5 rounded-full bg-foreground/65"
+            initial={reduceMotion ? false : TIMELINE_DOT_INITIAL}
+            key={`top-${dot}`}
+            transition={
+              reduceMotion ? undefined : TIMELINE_TOP_DOT_TRANSITIONS[index]
+            }
+          />
+        ))}
+      </div>
+      <div className="absolute bottom-15 left-1/2 flex h-12 -translate-x-1/2 flex-col justify-between">
+        {TIMELINE_CONNECTOR_DOTS.map((dot, index) => (
+          <motion.span
+            animate={reduceMotion ? undefined : TIMELINE_DOT_PULSE}
+            className="block size-1.5 rounded-full bg-foreground/65"
+            initial={reduceMotion ? false : TIMELINE_DOT_INITIAL}
+            key={`bottom-${dot}`}
+            transition={
+              reduceMotion ? undefined : TIMELINE_BOTTOM_DOT_TRANSITIONS[index]
+            }
+          />
+        ))}
+      </div>
+      {mode === "restore" ? (
+        <LockOpen
+          className="absolute bottom-0 left-1/2 size-10 -translate-x-1/2 text-foreground/85"
+          data-testid="restore-unlock-icon"
+        />
+      ) : (
+        <LockKeyhole className="absolute bottom-0 left-1/2 size-10 -translate-x-1/2 text-foreground/85" />
+      )}
+    </div>
+  );
+}
diff --git a/desktop/src/features/onboarding/ui/BackupStep.tsx b/desktop/src/features/onboarding/ui/BackupStep.tsx
index ed2184baaa..99d9c6324d 100644
--- a/desktop/src/features/onboarding/ui/BackupStep.tsx
+++ b/desktop/src/features/onboarding/ui/BackupStep.tsx
@@ -1,183 +1,438 @@
-import { AlertTriangle, Info, RefreshCw } from "lucide-react";
+import { Check, Copy, Eye, EyeOff, Info, ShieldCheck } from "lucide-react";
+import { useReducedMotion } from "motion/react";
 import * as React from "react";
 
 import { getNsec } from "@/shared/api/tauriIdentity";
+import type { IdentityStorage } from "@/shared/api/types";
+import { cn } from "@/shared/lib/cn";
+import { writeTextToClipboard } from "@/shared/lib/clipboard";
 import { Button } from "@/shared/ui/button";
+import { FuzzyLogo } from "@/shared/ui/buzz-logo/FuzzyLogo";
 import { Card } from "@/shared/ui/card";
 import { Spinner } from "@/shared/ui/spinner";
-import { ONBOARDING_PRIMARY_CTA_CLASS } from "./OnboardingChrome";
+import {
+  ONBOARDING_PRIMARY_CTA_CLASS,
+  ONBOARDING_SECONDARY_CTA_CLASS,
+} from "./OnboardingChrome";
 import { OnboardingFooter } from "./OnboardingFooter";
 import {
   type OnboardingTransitionDirection,
   OnboardingSlideTransition,
 } from "./OnboardingSlideTransition";
-import { NsecMaskedDisplay } from "./NsecMaskedDisplay";
+import { ONBOARDING_KEY_TEXT_CLASS } from "./NsecMaskedDisplay";
 
 /**
- * Pure helper so the disabled logic can be unit-tested without a DOM.
- *
- * Disabled while loading (key not fetched yet) or after a failed load (only
- * the explicit "Skip for now" ghost advances past an error).
+ * How long the "Creating your identity key" loader holds the stage before the
+ * finished state fades in. Purely perceptual — the key already exists; the
+ * pause sells the creation moment.
  */
-export function backupNextDisabled({
-  isLoading,
-  loadError,
-}: {
-  isLoading: boolean;
-  loadError: string | null;
-}): boolean {
-  return isLoading || loadError !== null;
+const INTRO_HOLD_MS = 1400;
+
+/**
+ * The creation moment should only be sold once per app session. Module-level
+ * so remounts (e.g. navigating Back and returning to this step) skip the fake
+ * hold and show the finished state instantly.
+ */
+let introPlayed = false;
+
+const REVEAL_ANIMATION_CLASS =
+  "animate-in fade-in duration-700 motion-reduce:animate-none";
+
+const BACKUP_OPTION_CLASS =
+  "flex min-h-48 w-full flex-col items-start justify-start px-6 py-5 text-left text-foreground";
+
+/** Viewing the key never blocks onboarding — Next is always actionable. */
+export function backupNextDisabled(): boolean {
+  return false;
 }
 
 type BackupStepProps = {
   direction: OnboardingTransitionDirection;
+  identityStorage?: IdentityStorage;
   onBack: () => void;
   onNext: () => void;
+  onOpenPasswordBackup: () => void;
+  onShowOptions: () => void;
+  optionsExpanded: boolean;
+  returningFromSecurity: boolean;
 };
 
 /**
- * Onboarding backup step — shows the user their freshly created key so they
- * can save it somewhere safe. Only shown on the fresh-key path.
+ * Onboarding identity-key step — shows the freshly created key, then opens a
+ * dark backup-options state. Copy fetches the raw key only after an explicit
+ * click; password backup opens the separate security flow. Neither method
+ * blocks Next.
  */
-export function BackupStep({ direction, onBack, onNext }: BackupStepProps) {
+export function BackupStep({
+  direction,
+  identityStorage,
+  onBack,
+  onNext,
+  onOpenPasswordBackup,
+  onShowOptions,
+  optionsExpanded,
+  returningFromSecurity,
+}: BackupStepProps) {
+  const reduceMotion = useReducedMotion() ?? false;
+  const [created, setCreated] = React.useState(introPlayed || reduceMotion);
+  const [copyState, setCopyState] = React.useState<
+    "idle" | "copying" | "copied"
+  >("idle");
+  const [copyError, setCopyError] = React.useState<string | null>(null);
   const [nsec, setNsec] = React.useState<string | null>(null);
-  const [isLoading, setIsLoading] = React.useState(true);
-  const [loadError, setLoadError] = React.useState<string | null>(null);
+  const [isRevealed, setIsRevealed] = React.useState(false);
   const cancelledRef = React.useRef(false);
+  const copiedTimerRef = React.useRef<number | null>(null);
 
-  const loadNsec = React.useCallback(async () => {
-    setIsLoading(true);
-    setLoadError(null);
-    try {
-      const value = await getNsec();
-      if (!cancelledRef.current) setNsec(value);
-    } catch (err) {
-      if (!cancelledRef.current)
-        setLoadError(
-          err instanceof Error
-            ? err.message
-            : "Failed to retrieve private key.",
-        );
-    } finally {
-      if (!cancelledRef.current) setIsLoading(false);
+  React.useEffect(() => {
+    if (introPlayed) return;
+    if (reduceMotion) {
+      introPlayed = true;
+      setCreated(true);
+      return;
     }
-  }, []);
+    const timer = window.setTimeout(() => {
+      introPlayed = true;
+      setCreated(true);
+    }, INTRO_HOLD_MS);
+    return () => window.clearTimeout(timer);
+  }, [reduceMotion]);
 
   React.useEffect(() => {
     cancelledRef.current = false;
-    void loadNsec();
     return () => {
       // Back-during-fetch: cancel any in-flight setState calls and clear the
       // nsec from memory on unmount (backup step is only on the fresh-key path).
       cancelledRef.current = true;
       setNsec(null);
+      if (copiedTimerRef.current !== null)
+        window.clearTimeout(copiedTimerRef.current);
     };
-  }, [loadNsec]);
+  }, []);
+
+  const copyKeyToClipboard = React.useCallback(async () => {
+    setCopyState("copying");
+    setCopyError(null);
+    try {
+      const value = nsec ?? (await getNsec());
+      await writeTextToClipboard(value);
+      if (cancelledRef.current) return;
+      setCopyState("copied");
+      if (copiedTimerRef.current !== null)
+        window.clearTimeout(copiedTimerRef.current);
+      copiedTimerRef.current = window.setTimeout(() => {
+        if (!cancelledRef.current) setCopyState("idle");
+      }, 2000);
+    } catch (err) {
+      if (cancelledRef.current) return;
+      setCopyState("idle");
+      setCopyError(
+        err instanceof Error ? err.message : "Failed to retrieve private key.",
+      );
+    }
+  }, [nsec]);
+
+  const toggleReveal = React.useCallback(async () => {
+    if (isRevealed) {
+      setIsRevealed(false);
+      return;
+    }
+    setCopyError(null);
+    try {
+      // The raw key enters the DOM only after this explicit reveal action.
+      const value = nsec ?? (await getNsec());
+      if (cancelledRef.current) return;
+      setNsec(value);
+      setIsRevealed(true);
+    } catch (err) {
+      if (cancelledRef.current) return;
+      setCopyError(
+        err instanceof Error ? err.message : "Failed to retrieve private key.",
+      );
+    }
+  }, [isRevealed, nsec]);
+
+  // Fixed-length decorative mask (nsec keys are 63 chars) so no key material
+  // is fetched just to render the blurred row. Bullets are joined with a
+  // zero-width space: WebKit won't line-break a run of U+2022 without an
+  // explicit break opportunity, so the masked row would overflow otherwise.
+  const maskedKey = React.useMemo(
+    () => Array.from({ length: nsec?.length ?? 63 }, () => "•").join("\u200b"),
+    [nsec],
+  );
+  const storageDescription =
+    identityStorage === "system-keyring"
+      ? "Buzz keeps your identity key in your system keychain. Your computer may ask for your password when Buzz needs to read the key."
+      : identityStorage === "local-file"
+        ? "Your system keychain wasn’t available, so Buzz keeps your identity key in a private file on this device."
+        : "Buzz keeps your identity key protected on this device. Make a separate backup in case you lose access.";
+  const storageTitle =
+    identityStorage === "system-keyring"
+      ? "Protected by your system keychain"
+      : identityStorage === "local-file"
+        ? "Stored in private device storage"
+        : "Protected in private device storage";
+  const introStorageDescription =
+    identityStorage === "system-keyring"
+      ? "Buzz keeps your identity key in your system keychain."
+      : identityStorage === "local-file"
+        ? "Buzz keeps your identity key in a private file on this device because the system keychain wasn’t available."
+        : "Your identity key is protected on this device.";
+
+  if (optionsExpanded) {
+    return (
+      <OnboardingSlideTransition
+        className="flex min-h-0 w-full flex-col items-center"
+        data-testid="onboarding-page-backup-options"
+        direction={direction}
+        effect={direction === "forward" ? "mask-reveal-up" : "line-slide"}
+        transitionKey={`backup-options-${direction}`}
+      >
+        <div className="flex w-full max-w-140 shrink-0 flex-col text-center">
+          <h1 className="text-title font-normal text-foreground">
+            Backup options
+          </h1>
+          <p className="mt-5 text-sm leading-6 text-foreground/75">
+            Your identity key works like a password for your Buzz account. Keep
+            a copy somewhere safe. You can create a backup file and lock it with
+            a password you can remember.
+          </p>
+        </div>
+
+        <div className="flex w-full max-w-260 flex-1 flex-col justify-center py-10">
+          <div
+            className="grid w-full grid-cols-1 gap-5 md:grid-cols-2 lg:grid-cols-3"
+            data-testid="backup-options"
+          >
+            <div
+              className={cn(BACKUP_OPTION_CLASS, "md:col-span-2 lg:col-span-1")}
+              data-testid="backup-option-panel"
+            >
+              <span className="text-lg font-medium">{storageTitle}</span>
+              <span className="mt-3 block text-sm leading-6 text-foreground/65">
+                {storageDescription}
+              </span>
+            </div>
+
+            <div
+              className={BACKUP_OPTION_CLASS}
+              data-testid="backup-option-panel"
+            >
+              <span className="text-lg font-medium">
+                Saved in your password manager
+              </span>
+              <span className="mt-3 block text-sm leading-6 text-foreground/65">
+                Copy your identity key, then save it in a password manager like
+                1Password.
+              </span>
+              <Button
+                className={cn(
+                  ONBOARDING_SECONDARY_CTA_CLASS,
+                  "mt-5 w-fit gap-2 px-5",
+                )}
+                data-testid="backup-copy-key"
+                disabled={copyState === "copying"}
+                onClick={() => void copyKeyToClipboard()}
+                type="button"
+                variant="ghost"
+              >
+                {copyState === "copying" ? (
+                  <Spinner className="h-4 w-4 border-2" />
+                ) : copyState === "copied" ? (
+                  <Check className="h-4 w-4" aria-hidden="true" />
+                ) : (
+                  <Copy className="h-4 w-4" aria-hidden="true" />
+                )}
+                {copyState === "copying"
+                  ? "Copying…"
+                  : copyState === "copied"
+                    ? "Copied to clipboard"
+                    : "Copy to clipboard"}
+              </Button>
+            </div>
+
+            <div
+              className={BACKUP_OPTION_CLASS}
+              data-testid="backup-option-panel"
+            >
+              <span className="text-lg font-medium">
+                Locked in a backup file
+              </span>
+              <span className="mt-3 block text-sm leading-6 text-foreground/65">
+                Create a backup file and choose a password you can remember.
+                You’ll need both to restore your account.
+              </span>
+              <Button
+                className={cn(
+                  ONBOARDING_SECONDARY_CTA_CLASS,
+                  "mt-5 w-fit gap-2 px-5",
+                )}
+                data-testid="backup-option-password"
+                onClick={onOpenPasswordBackup}
+                type="button"
+                variant="ghost"
+              >
+                <ShieldCheck className="h-5 w-5" aria-hidden="true" />
+                Create locked backup
+              </Button>
+            </div>
+          </div>
+
+          {copyError ? (
+            <p
+              className="mt-4 text-center text-sm text-destructive"
+              data-testid="backup-copy-error"
+            >
+              Could not retrieve your private key: {copyError}. You can continue
+              and find it later in Settings &gt; Profile &gt; Identity.
+            </p>
+          ) : null}
+        </div>
+      </OnboardingSlideTransition>
+    );
+  }
 
   return (
     <OnboardingSlideTransition
       className="flex min-h-0 w-full flex-col items-center"
       data-testid="onboarding-page-backup"
       direction={direction}
-      transitionKey={`backup-${direction}`}
+      effect={returningFromSecurity ? "mask-reveal-down" : "line-slide"}
+      transitionKey={`backup-${direction}-${returningFromSecurity ? "down" : "line"}`}
     >
       <div className="flex w-full max-w-[500px] shrink-0 flex-col text-center">
-        <h1 className="text-title font-normal text-foreground">
-          Your unique identity key has been created
+        {/* Plain string concat: cn()'s tailwind-merge misreads the custom
+            text-title size token as conflicting with text-foreground. */}
+        <h1
+          className={`text-title font-normal text-foreground ${REVEAL_ANIMATION_CLASS}`}
+          key={created ? "created" : "creating"}
+        >
+          {created
+            ? "Your unique identity key has been created"
+            : "Creating your identity key"}
         </h1>
-        <p className="mt-5 text-sm leading-6 text-foreground/80">
-          This key is stored in your system keychain, but save it some place
-          safe in case you ever need to restore your account.
-        </p>
-      </div>
-
-      <div className="flex w-full max-w-[1040px] flex-1 flex-col justify-center py-10">
-        {isLoading ? (
-          <div className="flex items-center justify-center gap-2 py-6 text-sm text-foreground/70">
-            <Spinner className="h-4 w-4 border-2" />
-            Loading your private key…
-          </div>
-        ) : loadError ? (
-          <div className="mx-auto max-w-[500px] space-y-3 text-left">
-            <div
-              className="flex items-start gap-3 rounded-lg border border-destructive/30 bg-destructive/10 px-4 py-3 text-sm text-destructive"
-              data-testid="backup-load-error"
-            >
-              <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0" />
-              <span>
-                Could not retrieve your private key: {loadError}. You can
-                continue and find it later in Settings &gt; Profile &gt;
-                Identity.
-              </span>
-            </div>
-            <Button
-              className="h-8 gap-1.5 text-sm"
-              data-testid="backup-retry"
-              onClick={() => void loadNsec()}
-              size="sm"
+        {created ? (
+          <p
+            className={cn(
+              "mt-5 text-sm leading-6 text-foreground/80",
+              REVEAL_ANIMATION_CLASS,
+            )}
+          >
+            {introStorageDescription} You can continue now, or{" "}
+            <button
+              className="rounded-sm font-medium underline decoration-foreground/40 underline-offset-4 transition-colors hover:decoration-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+              data-testid="backup-options-link"
+              onClick={onShowOptions}
               type="button"
-              variant="outline"
             >
-              <RefreshCw className="h-3.5 w-3.5" />
-              Try again
-            </Button>
-          </div>
-        ) : nsec ? (
-          <Card className="w-full px-8 py-6" variant="textured">
-            <div className="mx-auto w-full max-w-[832px]">
-              <NsecMaskedDisplay nsec={nsec} variant="bare" />
-            </div>
-          </Card>
-        ) : (
-          <p className="text-center text-sm text-foreground/70">
-            No key available to back up.
-          </p>
-        )}
-
-        {nsec ? (
-          <p className="mx-auto mt-6 flex max-w-[440px] items-start justify-center gap-1.5 text-center text-xs leading-5 text-[var(--buzz-onboarding-backup-ink)]">
-            <Info className="mt-0.5 h-3.5 w-3.5 shrink-0" />
-            <span>
-              Never share your private key. Anyone with this key can impersonate
-              you and access everything in your account.
-            </span>
+              review backup options
+            </button>{" "}
+            for ways to restore your account.
           </p>
         ) : null}
       </div>
 
-      <OnboardingFooter>
-        <Button
-          className={ONBOARDING_PRIMARY_CTA_CLASS}
-          data-testid="onboarding-next"
-          disabled={backupNextDisabled({ isLoading, loadError })}
-          onClick={onNext}
-          type="button"
+      {!created ? (
+        <div
+          className="flex w-full flex-1 items-center justify-center py-10"
+          data-testid="backup-intro-logo"
         >
-          Next
-        </Button>
+          <FuzzyLogo
+            ariaLabel="Creating your identity key"
+            className="w-20! text-foreground"
+            fuzz
+            loop
+            loopRestSeconds={0}
+          />
+        </div>
+      ) : (
+        <div
+          className={cn(
+            "flex w-full max-w-[1040px] flex-1 flex-col justify-center py-10",
+            REVEAL_ANIMATION_CLASS,
+          )}
+        >
+          <div className="w-full">
+            <Card className="px-8 py-6" variant="textured">
+              <div className="mx-auto flex w-full min-w-0 max-w-[832px] items-center gap-4">
+                <div className="min-w-0 flex-1">
+                  <p
+                    className={cn(
+                      ONBOARDING_KEY_TEXT_CLASS,
+                      isRevealed && nsec
+                        ? "select-text"
+                        : "select-none blur-[4px]",
+                    )}
+                    data-testid="backup-key-value"
+                  >
+                    {isRevealed && nsec ? nsec : maskedKey}
+                  </p>
+                </div>
+                <Button
+                  aria-label={
+                    isRevealed ? "Hide private key" : "Reveal private key"
+                  }
+                  className="h-10 w-10 shrink-0 text-muted-foreground hover:text-foreground"
+                  data-testid="backup-key-reveal-toggle"
+                  onClick={() => void toggleReveal()}
+                  size="icon"
+                  type="button"
+                  variant="ghost"
+                >
+                  {isRevealed ? (
+                    <EyeOff className="h-6 w-6" aria-hidden="true" />
+                  ) : (
+                    <Eye className="h-6 w-6" aria-hidden="true" />
+                  )}
+                </Button>
+              </div>
+            </Card>
+
+            {copyError ? (
+              <p
+                className="mt-4 text-center text-sm text-destructive"
+                data-testid="backup-copy-error"
+              >
+                Could not retrieve your private key: {copyError}. You can
+                continue and find it later in Settings &gt; Profile &gt;
+                Identity.
+              </p>
+            ) : null}
 
-        {loadError ? (
+            <p className="mx-auto mt-5 flex max-w-[440px] items-start justify-center gap-1.5 text-center text-xs leading-5 text-[var(--buzz-onboarding-backup-ink)]">
+              <Info className="mt-0.5 h-3.5 w-3.5 shrink-0" />
+              <span>
+                Never share your private key. Anyone with this key can
+                impersonate you and access everything in your account.
+              </span>
+            </p>
+          </div>
+        </div>
+      )}
+
+      {created ? (
+        <OnboardingFooter className={REVEAL_ANIMATION_CLASS}>
           <Button
-            className="h-9 rounded-full px-5 text-muted-foreground hover:text-accent-foreground"
-            data-testid="backup-skip"
+            className={ONBOARDING_PRIMARY_CTA_CLASS}
+            data-testid="onboarding-next"
+            disabled={backupNextDisabled()}
             onClick={onNext}
             type="button"
-            variant="ghost"
           >
-            Skip for now
+            Next
           </Button>
-        ) : null}
 
-        <Button
-          className="h-9 rounded-full bg-foreground/10 px-6 hover:bg-foreground/15"
-          data-testid="onboarding-back"
-          onClick={onBack}
-          type="button"
-          variant="ghost"
-        >
-          Back
-        </Button>
-      </OnboardingFooter>
+          <Button
+            className={ONBOARDING_SECONDARY_CTA_CLASS}
+            data-testid="onboarding-back"
+            onClick={onBack}
+            type="button"
+            variant="ghost"
+          >
+            Back
+          </Button>
+        </OnboardingFooter>
+      ) : null}
     </OnboardingSlideTransition>
   );
 }
diff --git a/desktop/src/features/onboarding/ui/BackupTestFlow.tsx b/desktop/src/features/onboarding/ui/BackupTestFlow.tsx
new file mode 100644
index 0000000000..9370d5c061
--- /dev/null
+++ b/desktop/src/features/onboarding/ui/BackupTestFlow.tsx
@@ -0,0 +1,745 @@
+import { Check, CircleHelp, Eye, EyeOff, FileKey2, FileUp } from "lucide-react";
+import { motion, useReducedMotion } from "motion/react";
+import * as React from "react";
+import { createPortal } from "react-dom";
+
+import {
+  getNsec,
+  verifyNcryptsecBackup,
+  type BackupVerification,
+} from "@/shared/api/tauriIdentity";
+import { cn } from "@/shared/lib/cn";
+import { Button } from "@/shared/ui/button";
+import { Card } from "@/shared/ui/card";
+import { Input } from "@/shared/ui/input";
+import { PubKey } from "@/shared/ui/PubKey";
+import { Spinner } from "@/shared/ui/spinner";
+import {
+  ONBOARDING_SECURITY_PRIMARY_CTA_CLASS,
+  ONBOARDING_SECONDARY_CTA_CLASS,
+} from "./OnboardingChrome";
+
+type BackupTestStage = "drop" | "password" | "success";
+
+/**
+ * Durable progress through the test flow. Owned by the host so navigating
+ * away (e.g. onboarding Back) and returning doesn't force the user to
+ * re-drop the file. The password attempt is deliberately NOT part of this
+ * state — it lives only in short-lived component state and is cleared the
+ * moment it's submitted or the component unmounts.
+ */
+export type BackupTestProgress = {
+  stage: BackupTestStage;
+  /** Name of the accepted file once the drop check passed. */
+  fileName: string | null;
+  /** Contents of the accepted file, pending or past verification. */
+  ncryptsec: string | null;
+  /** The Rust-verified public identity once decryption succeeded. */
+  result: BackupVerification | null;
+};
+
+export const initialBackupTestProgress: BackupTestProgress = {
+  stage: "drop",
+  fileName: null,
+  ncryptsec: null,
+  result: null,
+};
+
+type BackupTestFlowProps = {
+  /** "spotlight" is the onboarding treatment; "boxed" fits settings cards. */
+  variant?: "spotlight" | "boxed";
+  /**
+   * When supplied, only this exact just-created file is accepted — the
+   * onboarding ceremony proves the user saved *that* backup. Without it the
+   * flow is a general-purpose tester for any key backup file.
+   */
+  expectedNcryptsec?: string;
+  /** Re-open the native save dialog for another copy of the backup file. */
+  onSaveCopy?: () => void;
+  isSaving?: boolean;
+  saveError?: string | null;
+  /** Optional onboarding footer target for the verification CTA. */
+  verifyButtonPortal?: HTMLElement | null;
+  /** Host-owned progress so it survives this component unmounting. */
+  progress: BackupTestProgress;
+  onProgressChange: React.Dispatch<React.SetStateAction<BackupTestProgress>>;
+  /** Fired once when the user completes the test successfully. */
+  onVerified?: () => void;
+};
+
+const BURST_EMOJIS = ["🎉", "✨", "🐝", "🍯", "🔑", "💛"] as const;
+const BURST_PARTICLE_COUNT = 18;
+const VERIFICATION_CONNECTOR_DOTS = [
+  "verification-dot-1",
+  "verification-dot-2",
+  "verification-dot-3",
+  "verification-dot-4",
+] as const;
+const VERIFICATION_DOT_ANIMATION = {
+  opacity: [0.35, 1, 0.35],
+  scale: [0.85, 1.25, 0.85],
+};
+const VERIFICATION_DOT_TRANSITION = {
+  duration: 0.7,
+  ease: "easeInOut" as const,
+  repeat: Number.POSITIVE_INFINITY,
+  repeatDelay: 1.2,
+};
+const PRIVATE_KEY_MASK = Array.from({ length: 63 }, () => "•").join("\u200b");
+
+type BurstParticle = {
+  id: number;
+  x: number;
+  y: number;
+  emoji: string;
+  delay: number;
+  scale: number;
+  rotate: number;
+};
+
+/**
+ * One-shot radial emoji burst behind the success badge. Purely decorative —
+ * skipped entirely under reduced motion.
+ */
+function SuccessBurst() {
+  const particles = React.useMemo<BurstParticle[]>(
+    () =>
+      Array.from({ length: BURST_PARTICLE_COUNT }, (_, i) => {
+        const angle =
+          (i / BURST_PARTICLE_COUNT) * Math.PI * 2 + Math.random() * 0.5;
+        const distance = 70 + Math.random() * 80;
+        return {
+          id: i,
+          x: Math.cos(angle) * distance,
+          y: Math.sin(angle) * distance,
+          emoji: BURST_EMOJIS[i % BURST_EMOJIS.length],
+          delay: Math.random() * 0.18,
+          scale: 0.8 + Math.random() * 0.7,
+          rotate: -120 + Math.random() * 240,
+        };
+      }),
+    [],
+  );
+
+  return (
+    <div
+      aria-hidden
+      className="pointer-events-none absolute inset-0 flex items-center justify-center overflow-visible"
+    >
+      {particles.map((particle) => (
+        <motion.span
+          animate={{
+            x: particle.x,
+            y: particle.y,
+            opacity: 0,
+            scale: particle.scale,
+            rotate: particle.rotate,
+          }}
+          className="absolute text-xl"
+          initial={{ x: 0, y: 0, opacity: 1, scale: 0.3, rotate: 0 }}
+          key={particle.id}
+          transition={{
+            duration: 0.9,
+            delay: particle.delay,
+            ease: "easeOut",
+          }}
+        >
+          {particle.emoji}
+        </motion.span>
+      ))}
+    </div>
+  );
+}
+
+function VerificationConnector({
+  delayOffset,
+  reduceMotion,
+}: {
+  delayOffset: number;
+  reduceMotion: boolean;
+}) {
+  return (
+    <div
+      aria-hidden
+      className="my-5 flex h-14 flex-col items-center justify-between py-1"
+    >
+      {VERIFICATION_CONNECTOR_DOTS.map((dot, index) => (
+        <motion.span
+          animate={reduceMotion ? undefined : VERIFICATION_DOT_ANIMATION}
+          className="block size-1.5 rounded-full bg-foreground/65"
+          initial={reduceMotion ? false : { opacity: 0.35, scale: 0.85 }}
+          key={dot}
+          transition={
+            reduceMotion
+              ? undefined
+              : {
+                  ...VERIFICATION_DOT_TRANSITION,
+                  delay:
+                    (VERIFICATION_CONNECTOR_DOTS.length -
+                      1 -
+                      index +
+                      delayOffset) *
+                    0.16,
+                }
+          }
+        />
+      ))}
+    </div>
+  );
+}
+
+/**
+ * "Test your backup" flow: the user drops a backup file onto a large
+ * dropzone, then enters its password. Verification is a real NIP-49 decrypt
+ * in Rust — the submitted password is cleared immediately after the result
+ * and only the derived public identity ever comes back.
+ */
+export function BackupTestFlow({
+  variant = "spotlight",
+  expectedNcryptsec,
+  onSaveCopy,
+  isSaving = false,
+  saveError,
+  verifyButtonPortal,
+  progress,
+  onProgressChange,
+  onVerified,
+}: BackupTestFlowProps) {
+  const reduceMotion = useReducedMotion() ?? false;
+  const { stage, fileName, ncryptsec, result } = progress;
+  // True while a file drag is anywhere over the window — the drop overlay
+  // takes over the host surface only for the duration of the drag.
+  const [isWindowDragging, setIsWindowDragging] = React.useState(false);
+  const dragDepthRef = React.useRef(0);
+
+  React.useEffect(() => {
+    // dragenter/dragleave fire per nested element, so track depth to know
+    // when the drag has actually left the window.
+    const handleDragEnter = (event: DragEvent) => {
+      if (!event.dataTransfer?.types.includes("Files")) return;
+      dragDepthRef.current += 1;
+      setIsWindowDragging(true);
+    };
+    const handleDragLeave = () => {
+      dragDepthRef.current = Math.max(0, dragDepthRef.current - 1);
+      if (dragDepthRef.current === 0) setIsWindowDragging(false);
+    };
+    const handleDragEnd = () => {
+      dragDepthRef.current = 0;
+      setIsWindowDragging(false);
+    };
+    window.addEventListener("dragenter", handleDragEnter);
+    window.addEventListener("dragleave", handleDragLeave);
+    window.addEventListener("drop", handleDragEnd);
+    window.addEventListener("dragend", handleDragEnd);
+    return () => {
+      window.removeEventListener("dragenter", handleDragEnter);
+      window.removeEventListener("dragleave", handleDragLeave);
+      window.removeEventListener("drop", handleDragEnd);
+      window.removeEventListener("dragend", handleDragEnd);
+    };
+  }, []);
+
+  // The password attempt is component-local, never host state: it is cleared
+  // when verification is submitted and when this component unmounts.
+  const [attempt, setAttempt] = React.useState("");
+  const [error, setError] = React.useState<string | null>(null);
+  const [isVerifying, setIsVerifying] = React.useState(false);
+  const [isRevealed, setIsRevealed] = React.useState(false);
+  const [successNsec, setSuccessNsec] = React.useState<string | null>(null);
+  const [isSuccessNsecRevealed, setIsSuccessNsecRevealed] =
+    React.useState(false);
+  const [isLoadingSuccessNsec, setIsLoadingSuccessNsec] = React.useState(false);
+  const [successNsecError, setSuccessNsecError] = React.useState<string | null>(
+    null,
+  );
+  const fileInputRef = React.useRef<HTMLInputElement | null>(null);
+  const passwordInputRef = React.useRef<HTMLInputElement | null>(null);
+  const mountedRef = React.useRef(true);
+  // Opaque correlation id so a stale in-flight verification can't commit
+  // after "Use a different file" or unmount.
+  const requestRef = React.useRef(0);
+
+  React.useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      requestRef.current += 1;
+      setAttempt("");
+    };
+  }, []);
+
+  React.useEffect(() => {
+    if (stage === "password") passwordInputRef.current?.focus();
+  }, [stage]);
+
+  const handleFile = React.useCallback(
+    async (file: File) => {
+      let text: string;
+      try {
+        text = (await file.text()).trim();
+      } catch {
+        if (mountedRef.current) setError("Could not read that file.");
+        return;
+      }
+      if (!mountedRef.current) return;
+      if (!text.toLowerCase().startsWith("ncryptsec1")) {
+        setError(
+          expectedNcryptsec
+            ? "That doesn't look like your key backup. Choose the file you just downloaded."
+            : "That doesn't look like a key backup file.",
+        );
+        return;
+      }
+      if (expectedNcryptsec && text !== expectedNcryptsec.trim()) {
+        setError("That's a key backup, but not the one you just downloaded.");
+        return;
+      }
+      setError(null);
+      setAttempt("");
+      onProgressChange({
+        stage: "password",
+        fileName: file.name,
+        ncryptsec: text,
+        result: null,
+      });
+    },
+    [expectedNcryptsec, onProgressChange],
+  );
+
+  const handleVerify = React.useCallback(async () => {
+    if (!ncryptsec || !attempt || isVerifying) return;
+    const password = attempt;
+    const requestId = ++requestRef.current;
+    setIsVerifying(true);
+    setError(null);
+    setIsRevealed(false);
+    // Clear the attempt the moment it's handed to Rust — success or failure,
+    // the typed password never lingers in the field.
+    setAttempt("");
+    try {
+      const verified = await verifyNcryptsecBackup(ncryptsec, password);
+      if (!mountedRef.current || requestId !== requestRef.current) return;
+      onProgressChange((prev) => ({
+        ...prev,
+        stage: "success",
+        result: verified,
+      }));
+      onVerified?.();
+    } catch (err) {
+      if (mountedRef.current && requestId === requestRef.current)
+        setError(
+          err instanceof Error ? err.message : "Could not verify this backup.",
+        );
+    } finally {
+      if (mountedRef.current && requestId === requestRef.current)
+        setIsVerifying(false);
+    }
+  }, [attempt, isVerifying, ncryptsec, onProgressChange, onVerified]);
+
+  const toggleSuccessNsec = React.useCallback(async () => {
+    if (isSuccessNsecRevealed) {
+      setIsSuccessNsecRevealed(false);
+      return;
+    }
+    if (successNsec) {
+      setIsSuccessNsecRevealed(true);
+      return;
+    }
+    setIsLoadingSuccessNsec(true);
+    setSuccessNsecError(null);
+    try {
+      const value = await getNsec();
+      if (!mountedRef.current) return;
+      setSuccessNsec(value);
+      setIsSuccessNsecRevealed(true);
+    } catch (err) {
+      if (!mountedRef.current) return;
+      setSuccessNsecError(
+        err instanceof Error ? err.message : "Could not retrieve your key.",
+      );
+    } finally {
+      if (mountedRef.current) setIsLoadingSuccessNsec(false);
+    }
+  }, [isSuccessNsecRevealed, successNsec]);
+
+  const isSpotlight = variant === "spotlight";
+
+  if (stage === "success" && result) {
+    // The onboarding ceremony pins the exact file, so a success there is by
+    // construction the current identity — celebrate and move on. The general
+    // tester reports which identity the backup unlocks.
+    const isCeremony = Boolean(expectedNcryptsec);
+    return (
+      <div
+        className="relative flex flex-col items-center gap-4 py-4 text-center"
+        data-testid="backup-test-success"
+      >
+        {reduceMotion ? null : <SuccessBurst />}
+        <motion.div
+          animate={{ scale: 1, opacity: 1 }}
+          className="flex h-16 w-16 items-center justify-center rounded-full bg-primary text-primary-foreground"
+          initial={reduceMotion ? false : { scale: 0, opacity: 0 }}
+          transition={
+            reduceMotion
+              ? { duration: 0 }
+              : { type: "spring", stiffness: 380, damping: 18 }
+          }
+        >
+          <Check aria-hidden="true" className="h-8 w-8" strokeWidth={3} />
+        </motion.div>
+        <motion.div
+          animate={{ opacity: 1, y: 0 }}
+          initial={reduceMotion ? false : { opacity: 0, y: 8 }}
+          transition={
+            reduceMotion ? { duration: 0 } : { delay: 0.15, duration: 0.35 }
+          }
+        >
+          {isCeremony ? (
+            <div className="w-full max-w-140">
+              <p className="text-lg font-medium text-foreground">
+                Your backup works!
+              </p>
+              <p className="mt-1.5 text-sm leading-6 text-muted-foreground">
+                File and password verified. Keep them both somewhere safe —
+                that&apos;s all you need to restore your identity.
+              </p>
+              <div className="mx-auto mt-4 flex max-w-110 min-w-0 items-center gap-2 text-left">
+                <p
+                  className={cn(
+                    "min-w-0 flex-1 break-all font-mono text-base leading-6 wrap-anywhere",
+                    isSuccessNsecRevealed
+                      ? "select-text text-foreground"
+                      : "select-none blur-[2px] text-muted-foreground",
+                  )}
+                  data-testid="backup-success-nsec-value"
+                >
+                  {isSuccessNsecRevealed && successNsec
+                    ? successNsec
+                    : PRIVATE_KEY_MASK}
+                </p>
+                <Button
+                  aria-label={
+                    isSuccessNsecRevealed
+                      ? "Hide unlocked private key"
+                      : "Reveal unlocked private key"
+                  }
+                  className="size-9 shrink-0 text-muted-foreground hover:text-foreground"
+                  data-testid="backup-success-nsec-toggle"
+                  disabled={isLoadingSuccessNsec}
+                  onClick={() => void toggleSuccessNsec()}
+                  size="icon"
+                  type="button"
+                  variant="ghost"
+                >
+                  {isLoadingSuccessNsec ? (
+                    <Spinner className="size-4 border-2" />
+                  ) : isSuccessNsecRevealed ? (
+                    <EyeOff aria-hidden="true" className="size-4" />
+                  ) : (
+                    <Eye aria-hidden="true" className="size-4" />
+                  )}
+                </Button>
+              </div>
+              {successNsecError ? (
+                <p
+                  className="mt-2 text-xs text-destructive"
+                  data-testid="backup-success-nsec-error"
+                  role="alert"
+                >
+                  {successNsecError}
+                </p>
+              ) : null}
+            </div>
+          ) : (
+            <>
+              <p className="text-lg font-medium text-foreground">
+                This backup works
+              </p>
+              <p className="mt-1.5 text-sm leading-6 text-muted-foreground">
+                {result.matchesCurrentIdentity
+                  ? "It restores your current Buzz identity."
+                  : "It restores a different identity than the one signed in here."}
+              </p>
+              <div className="mt-3 flex justify-center">
+                <PubKey
+                  pubkey={result.pubkey}
+                  testId="backup-test-npub"
+                  variant="full"
+                />
+              </div>
+            </>
+          )}
+        </motion.div>
+        {isCeremony ? null : (
+          <Button
+            className="h-8 rounded-full px-4 text-xs text-muted-foreground hover:text-foreground"
+            data-testid="backup-test-another"
+            onClick={() => {
+              setError(null);
+              onProgressChange(initialBackupTestProgress);
+            }}
+            type="button"
+            variant="ghost"
+          >
+            Test another backup
+          </Button>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={cn(
+        "mx-auto w-full space-y-4",
+        isSpotlight ? "max-w-140" : "max-w-125",
+      )}
+      data-testid="backup-test-flow"
+    >
+      {stage === "drop" ? (
+        <motion.div
+          animate={{ opacity: 1, y: 0 }}
+          className="relative space-y-4"
+          initial={reduceMotion ? false : { opacity: 0, y: 10 }}
+          key="drop"
+          transition={{ duration: reduceMotion ? 0 : 0.3, ease: "easeOut" }}
+        >
+          <input
+            accept=".ncryptsec,text/plain"
+            className="sr-only"
+            data-testid="backup-test-file-input"
+            onChange={(event) => {
+              const file = event.target.files?.[0];
+              // Allow re-selecting the same file after an error.
+              event.target.value = "";
+              if (file) void handleFile(file);
+            }}
+            ref={fileInputRef}
+            tabIndex={-1}
+            type="file"
+          />
+          <Button
+            className={cn(
+              "mx-auto",
+              isSpotlight
+                ? ONBOARDING_SECURITY_PRIMARY_CTA_CLASS
+                : "h-9 px-6 text-primary-foreground",
+            )}
+            data-testid="backup-test-dropzone"
+            onClick={() => fileInputRef.current?.click()}
+            type="button"
+          >
+            <span className="font-medium text-sm">Select your backup file</span>
+          </Button>
+          {isWindowDragging ? (
+            /*
+             * Composer-style takeover: fills the nearest positioned host
+             * surface (the onboarding card / the settings backup row) and is
+             * itself the drop target, so anywhere on that surface accepts
+             * the file.
+             */
+            // biome-ignore lint/a11y/noStaticElementInteractions: pointer-only drop target; the select button is the keyboard-accessible path
+            <div
+              className="absolute inset-2 z-10 mt-0! flex items-center justify-center bg-primary/10 backdrop-blur-sm"
+              data-testid="backup-test-drop-overlay"
+              onDragOver={(event) => event.preventDefault()}
+              onDrop={(event) => {
+                event.preventDefault();
+                const file = event.dataTransfer.files?.[0];
+                if (file) void handleFile(file);
+              }}
+            >
+              <Card
+                className="flex-row items-center gap-2 px-10 py-8 text-sm font-semibold text-foreground"
+                textureSize="compact"
+                textureTone="dark"
+                variant="textured"
+              >
+                <FileUp aria-hidden="true" className="size-4" />
+                <span>Drop your backup file here</span>
+              </Card>
+            </div>
+          ) : null}
+          {error ? (
+            <p
+              className="text-center text-sm text-destructive"
+              data-testid="backup-test-error"
+              role="alert"
+            >
+              {error}
+            </p>
+          ) : null}
+          {onSaveCopy ? (
+            <div className="flex flex-col items-center gap-2">
+              <Button
+                className={cn(
+                  "gap-1.5",
+                  isSpotlight
+                    ? ONBOARDING_SECONDARY_CTA_CLASS
+                    : "h-9 rounded-full bg-foreground/10 px-6 text-sm hover:bg-foreground/15",
+                )}
+                data-testid="encrypted-backup-save-copy"
+                disabled={isSaving}
+                onClick={onSaveCopy}
+                type="button"
+                variant="ghost"
+              >
+                {isSaving ? <Spinner className="h-4 w-4 border-2" /> : null}
+                Re-download backup
+              </Button>
+            </div>
+          ) : null}
+          {saveError ? (
+            <p className="text-center text-sm text-destructive">{saveError}</p>
+          ) : null}
+        </motion.div>
+      ) : (
+        <motion.div
+          animate={{ opacity: 1, y: 0 }}
+          className="space-y-4"
+          initial={reduceMotion ? false : { opacity: 0, y: 10 }}
+          key="password"
+          transition={{ duration: reduceMotion ? 0 : 0.3, ease: "easeOut" }}
+        >
+          {(() => {
+            const fileRow = (
+              <div
+                className="flex max-w-full items-center gap-3 rounded-2xl border border-foreground/15 bg-foreground/10 px-4 py-3 text-foreground shadow-sm animate-in fade-in slide-in-from-bottom-1 duration-300 motion-reduce:animate-none"
+                data-testid="backup-test-file-accepted"
+              >
+                <span className="flex size-9 shrink-0 items-center justify-center rounded-xl bg-foreground/10">
+                  <FileKey2
+                    aria-hidden="true"
+                    className="size-5 text-foreground/80"
+                  />
+                </span>
+                <span className="max-w-70 truncate font-mono text-sm">
+                  {fileName}
+                </span>
+              </div>
+            );
+            const passwordField = (
+              <div className="relative w-full">
+                <Input
+                  aria-label="Backup password"
+                  autoComplete="off"
+                  className={cn(
+                    "font-mono",
+                    isSpotlight
+                      ? "h-14 rounded-2xl border-black/20 bg-white px-14 text-center text-lg text-black/80 shadow-none placeholder:text-black/55 focus-visible:ring-black/35"
+                      : "h-10 bg-background pr-10",
+                  )}
+                  data-testid="backup-test-password"
+                  disabled={isVerifying}
+                  onChange={(event) => setAttempt(event.target.value)}
+                  onKeyDown={(event) => {
+                    if (event.key === "Enter") {
+                      event.preventDefault();
+                      void handleVerify();
+                    }
+                  }}
+                  placeholder="Your backup password"
+                  ref={passwordInputRef}
+                  type={isRevealed ? "text" : "password"}
+                  value={attempt}
+                />
+                <Button
+                  aria-label={isRevealed ? "Hide password" : "Reveal password"}
+                  className={cn(
+                    "absolute right-1 top-1/2 h-8 w-8 -translate-y-1/2 text-muted-foreground hover:text-foreground",
+                    isSpotlight &&
+                      "text-black/55 hover:bg-black/5 hover:text-black/80",
+                  )}
+                  data-testid="backup-test-password-reveal-toggle"
+                  disabled={isVerifying}
+                  onClick={() => setIsRevealed((revealed) => !revealed)}
+                  size="icon"
+                  type="button"
+                  variant="ghost"
+                >
+                  {isRevealed ? (
+                    <EyeOff aria-hidden="true" className="h-4 w-4" />
+                  ) : (
+                    <Eye aria-hidden="true" className="h-4 w-4" />
+                  )}
+                </Button>
+                {error ? (
+                  <p
+                    className="absolute left-1 top-full mt-1 text-xs text-destructive animate-in fade-in duration-200 motion-reduce:animate-none"
+                    data-testid="backup-test-error"
+                    role="alert"
+                  >
+                    {error}
+                  </p>
+                ) : null}
+              </div>
+            );
+            if (!isSpotlight) {
+              return (
+                <>
+                  {fileRow}
+                  <p className="text-center text-sm leading-6 text-muted-foreground">
+                    Enter the password to prove you can unlock this backup.
+                  </p>
+                  {passwordField}
+                </>
+              );
+            }
+            return (
+              <div className="flex w-full flex-col items-center">
+                <CircleHelp
+                  aria-hidden="true"
+                  className="size-10 text-foreground/85"
+                />
+                <VerificationConnector
+                  delayOffset={VERIFICATION_CONNECTOR_DOTS.length}
+                  reduceMotion={reduceMotion}
+                />
+                {passwordField}
+                <VerificationConnector
+                  delayOffset={0}
+                  reduceMotion={reduceMotion}
+                />
+                {fileRow}
+              </div>
+            );
+          })()}
+          {(() => {
+            const verifyButton = (
+              <Button
+                className={cn(
+                  "font-medium",
+                  isSpotlight
+                    ? ONBOARDING_SECURITY_PRIMARY_CTA_CLASS
+                    : "h-9 px-6 text-sm text-primary-foreground",
+                )}
+                data-testid="backup-test-verify"
+                disabled={!attempt || isVerifying}
+                onClick={() => void handleVerify()}
+                type="button"
+              >
+                {isVerifying ? (
+                  <>
+                    <Spinner className="h-4 w-4 border-2" />
+                    Checking…
+                  </>
+                ) : (
+                  "Verify backup"
+                )}
+              </Button>
+            );
+            if (verifyButtonPortal === undefined) {
+              return (
+                <div className="flex justify-center pt-2">{verifyButton}</div>
+              );
+            }
+            return verifyButtonPortal
+              ? createPortal(verifyButton, verifyButtonPortal)
+              : null;
+          })()}
+        </motion.div>
+      )}
+    </div>
+  );
+}
diff --git a/desktop/src/features/onboarding/ui/CommunityOnboardingFlow.tsx b/desktop/src/features/onboarding/ui/CommunityOnboardingFlow.tsx
index 4b729ab33f..98210c57cd 100644
--- a/desktop/src/features/onboarding/ui/CommunityOnboardingFlow.tsx
+++ b/desktop/src/features/onboarding/ui/CommunityOnboardingFlow.tsx
@@ -160,6 +160,7 @@ export function CommunityOnboardingFlow({
     [],
   );
   const [isPending, setIsPending] = React.useState(false);
+  const checkedProfileTransactionRef = React.useRef<string | null>(null);
   const [starterChannelFailureCount, setStarterChannelFailureCount] =
     React.useState(0);
   const [deniedPubkey, setDeniedPubkey] = React.useState("");
@@ -283,6 +284,22 @@ export function CommunityOnboardingFlow({
   }, [isPending, update]);
 
   const isProfileStage = transaction?.stage === "profile";
+  React.useEffect(() => {
+    if (!isProfileStage || !transaction) return;
+    if (checkedProfileTransactionRef.current === transaction.id) return;
+
+    checkedProfileTransactionRef.current = transaction.id;
+    void getProfile()
+      .then((profile) => {
+        if (profile.hasProfileEvent) {
+          update({ stage: "team-intro", error: undefined }, transaction.id);
+        }
+      })
+      .catch(() => {
+        // Discovery is best-effort. Staying on the profile step preserves the
+        // existing path when the relay cannot answer the lookup.
+      });
+  }, [isProfileStage, transaction, update]);
   const isTeamStage =
     transaction?.stage === "team-intro" ||
     transaction?.stage === "finalizing" ||
diff --git a/desktop/src/features/onboarding/ui/DownloadKeyStep.tsx b/desktop/src/features/onboarding/ui/DownloadKeyStep.tsx
new file mode 100644
index 0000000000..3d69150049
--- /dev/null
+++ b/desktop/src/features/onboarding/ui/DownloadKeyStep.tsx
@@ -0,0 +1,139 @@
+import { motion, useReducedMotion } from "motion/react";
+import * as React from "react";
+
+import { Button } from "@/shared/ui/button";
+import {
+  ONBOARDING_SECURITY_PRIMARY_CTA_CLASS,
+  ONBOARDING_SECONDARY_CTA_CLASS,
+} from "./OnboardingChrome";
+import { OnboardingFooter } from "./OnboardingFooter";
+import {
+  type OnboardingTransitionDirection,
+  OnboardingSlideTransition,
+} from "./OnboardingSlideTransition";
+import {
+  type EncryptedBackupSession,
+  EncryptedBackupCreator,
+} from "./EncryptedBackupCreator";
+
+type DownloadKeyStepProps = {
+  direction: OnboardingTransitionDirection;
+  /** Backup state owned by the parent flow across the creation and test views. */
+  session: EncryptedBackupSession;
+  onBack: () => void;
+};
+
+/**
+ * Password-backup security subview within the identity-key onboarding step.
+ * The raw key never enters this component: Rust builds the NIP-49 payload
+ * locally and the native save dialog produces the user-owned file.
+ */
+export function DownloadKeyStep({
+  direction,
+  session,
+  onBack,
+}: DownloadKeyStepProps) {
+  const reduceMotion = useReducedMotion() ?? false;
+  // Once the encrypted payload is saved, the creator advances to its guided
+  // backup test while this surface keeps its own navigation.
+  const hasCreated = session.created;
+  const hasVerifiedBackup = session.verified;
+  const hasSelectedBackup = session.test.stage === "password";
+  const [primaryActionSlot, setPrimaryActionSlot] =
+    React.useState<HTMLElement | null>(null);
+
+  return (
+    <OnboardingSlideTransition
+      className="flex min-h-0 w-full flex-col items-center"
+      data-testid="onboarding-page-download"
+      direction={direction}
+      transitionKey={`download-${direction}`}
+    >
+      <motion.div
+        animate={{ opacity: 1, y: 0 }}
+        className="flex w-full max-w-[500px] shrink-0 flex-col text-center"
+        initial={reduceMotion ? false : { opacity: 0, y: 10 }}
+        key={
+          hasVerifiedBackup
+            ? "success-heading"
+            : hasCreated
+              ? "test-heading"
+              : "password-heading"
+        }
+        transition={{ duration: reduceMotion ? 0 : 0.3, ease: "easeOut" }}
+      >
+        {/* Plain string concat: cn()'s tailwind-merge misreads the custom
+            text-title size token as conflicting with text-foreground. */}
+        <h1 className="text-title font-normal text-foreground">
+          {hasVerifiedBackup
+            ? "Your backup is verified"
+            : hasSelectedBackup
+              ? "That’s your backup file"
+              : hasCreated
+                ? "Optionally, test your backup"
+                : "Backup your key with a password"}
+        </h1>
+        <p className="mt-5 text-sm leading-6 text-foreground/80">
+          {hasVerifiedBackup
+            ? "Your file and password can restore your identity."
+            : hasSelectedBackup
+              ? "Now enter your password to prove you can unlock it."
+              : hasCreated
+                ? "Learn how your backup works. Drop the file you just saved and unlock it with your password."
+                : "Keep the downloaded file private — you need both it and your password to restore your identity. Save the backup password somewhere safe; Buzz cannot reset it if lost."}
+        </p>
+      </motion.div>
+
+      <div className="flex w-full max-w-[1040px] flex-1 flex-col justify-center py-10">
+        <div className="w-full">
+          <motion.div
+            animate={{ opacity: 1, y: 0 }}
+            initial={reduceMotion ? false : { opacity: 0, y: 12 }}
+            key={hasCreated ? "test-panel" : "password-panel"}
+            transition={{
+              delay: reduceMotion ? 0 : 0.12,
+              duration: reduceMotion ? 0 : 0.4,
+              ease: "easeOut",
+            }}
+          >
+            <div
+              className="mx-auto w-full max-w-140 px-6 py-5"
+              data-testid="backup-password-panel"
+            >
+              <EncryptedBackupCreator
+                createButtonClassName={ONBOARDING_SECURITY_PRIMARY_CTA_CLASS}
+                createButtonPortal={primaryActionSlot}
+                session={session}
+                variant="spotlight"
+                verifyButtonPortal={primaryActionSlot}
+              />
+            </div>
+          </motion.div>
+        </div>
+      </div>
+
+      <OnboardingFooter>
+        <div
+          className="flex justify-center"
+          data-testid={
+            hasCreated ? "onboarding-verify-slot" : "onboarding-create-slot"
+          }
+          ref={setPrimaryActionSlot}
+        />
+        <Button
+          className={
+            hasVerifiedBackup
+              ? ONBOARDING_SECURITY_PRIMARY_CTA_CLASS
+              : ONBOARDING_SECONDARY_CTA_CLASS
+          }
+          data-testid="onboarding-back"
+          onClick={onBack}
+          type="button"
+          variant="ghost"
+        >
+          {hasVerifiedBackup ? "Finish" : hasCreated ? "Skip for now" : "Back"}
+        </Button>
+      </OnboardingFooter>
+    </OnboardingSlideTransition>
+  );
+}
diff --git a/desktop/src/features/onboarding/ui/EncryptedBackupCreator.tsx b/desktop/src/features/onboarding/ui/EncryptedBackupCreator.tsx
new file mode 100644
index 0000000000..bb76166bd7
--- /dev/null
+++ b/desktop/src/features/onboarding/ui/EncryptedBackupCreator.tsx
@@ -0,0 +1,885 @@
+import { AlertTriangle, Eye, EyeOff, RefreshCw } from "lucide-react";
+import * as React from "react";
+import { createPortal } from "react-dom";
+
+import {
+  createNcryptsecBackup,
+  generateBackupPassphrase,
+  saveNcryptsecCopy,
+} from "@/shared/api/tauriIdentity";
+import { cn } from "@/shared/lib/cn";
+import { Button } from "@/shared/ui/button";
+import { Input } from "@/shared/ui/input";
+import { Popover, PopoverAnchor, PopoverContent } from "@/shared/ui/popover";
+import { Spinner } from "@/shared/ui/spinner";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/shared/ui/alert-dialog";
+import {
+  downloadDisabled,
+  passphraseIssue,
+  pendingEncryptPassphrase,
+  encryptedBackupReducer,
+  initialEncryptedBackupState,
+  MIN_PASSPHRASE_LEN,
+  type EncryptedBackupEvent,
+  type EncryptedBackupState,
+} from "../lib/encryptedBackup";
+import {
+  type BackupTestProgress,
+  BackupTestFlow,
+  initialBackupTestProgress,
+} from "./BackupTestFlow";
+import { BackupPasswordTimeline } from "./BackupPasswordTimeline";
+import {
+  ONBOARDING_SECURITY_PRIMARY_CTA_CLASS,
+  ONBOARDING_SECONDARY_CTA_CLASS,
+} from "./OnboardingChrome";
+
+/** Word-count bounds mirroring `key_backup.rs` (Rust clamps regardless). */
+const MIN_GENERATED_WORDS = 3;
+const MAX_GENERATED_WORDS = 10;
+const DEFAULT_GENERATED_WORDS = 3;
+
+const SEPARATOR_OPTIONS = [
+  { label: "Spaces", value: " " },
+  { label: "Hyphens", value: "-" },
+  { label: "Periods", value: "." },
+  { label: "Commas", value: "," },
+] as const;
+
+const DEFAULT_SEPARATOR = SEPARATOR_OPTIONS[0].value;
+
+/**
+ * Pause after the last keystroke before the background KDF starts, so typing
+ * past the minimum length doesn't launch an encryption per character.
+ */
+const ENCRYPT_DEBOUNCE_MS = 400;
+
+const PENDING_TICKER_MESSAGES = [
+  "Downloading once finished",
+  "Encrypting your password",
+  "Just a bit longer...",
+] as const;
+
+/** How long each ticker message holds before sliding to the next. */
+const PENDING_TICKER_INTERVAL_MS = 2500;
+
+/** Matches the `duration-300` slide transition on the ticker column. */
+const PENDING_TICKER_SLIDE_MS = 300;
+
+/**
+ * Vertical ticker for the queued-download button label — cycles through the
+ * pending messages by sliding a stacked column inside a one-line viewport.
+ * The column ends with a clone of the first message, so the wrap-around
+ * slides up from the bottom like every other step; once the clone settles,
+ * the column snaps (transition disabled) back to the real first row. All
+ * lines render at all times, so the button keeps the width of the longest
+ * message instead of resizing on each swap.
+ */
+function PendingDownloadTicker() {
+  // Index into the rendered column (messages + trailing clone of the first).
+  const [position, setPosition] = React.useState(0);
+  const [snap, setSnap] = React.useState(false);
+
+  React.useEffect(() => {
+    const timer = window.setInterval(
+      () => setPosition((current) => current + 1),
+      PENDING_TICKER_INTERVAL_MS,
+    );
+    return () => window.clearInterval(timer);
+  }, []);
+
+  // The clone is visually identical to the first message: once its slide-in
+  // finishes, jump back to the real first row without animating.
+  React.useEffect(() => {
+    if (position !== PENDING_TICKER_MESSAGES.length) return;
+    const timer = window.setTimeout(() => {
+      setSnap(true);
+      setPosition(0);
+    }, PENDING_TICKER_SLIDE_MS);
+    return () => window.clearTimeout(timer);
+  }, [position]);
+
+  // Re-enable the transition one frame after the snap has painted.
+  React.useEffect(() => {
+    if (!snap) return;
+    const raf = window.requestAnimationFrame(() => setSnap(false));
+    return () => window.cancelAnimationFrame(raf);
+  }, [snap]);
+
+  // The clone row duplicates the first message's text, so it carries its own
+  // stable key.
+  const column = [
+    ...PENDING_TICKER_MESSAGES.map((message) => ({ key: message, message })),
+    { key: "wrap-clone", message: PENDING_TICKER_MESSAGES[0] },
+  ];
+
+  return (
+    <span
+      aria-live="polite"
+      className="relative block h-5 overflow-hidden"
+      data-testid="encrypted-backup-pending-ticker"
+    >
+      <span
+        className={cn(
+          "block ease-out",
+          snap
+            ? "transition-none"
+            : "transition-transform duration-300 motion-reduce:transition-none",
+        )}
+        style={{ transform: `translateY(-${position * 1.25}rem)` }}
+      >
+        {column.map((row) => (
+          <span
+            className="flex h-5 items-center justify-center whitespace-nowrap"
+            key={row.key}
+          >
+            {row.message}
+          </span>
+        ))}
+      </span>
+    </span>
+  );
+}
+
+/**
+ * Everything about an in-progress backup that must survive this component
+ * unmounting: the reducer state (short-lived passphrase + encrypted blob), whether the
+ * backup test passed, where the file was saved, the save-once guard, and the
+ * test-flow progress. Hosts that need the state to outlive the creator (the
+ * onboarding flow, where Back unmounts the step) call
+ * `useEncryptedBackupSession` at a longer-lived level and pass it down;
+ * otherwise the creator owns a private session internally.
+ */
+export type EncryptedBackupSession = {
+  state: EncryptedBackupState;
+  dispatch: React.Dispatch<EncryptedBackupEvent>;
+  /**
+   * True once the encrypted payload has been committed AND saved to disk.
+   * Derived so hosts (e.g. DownloadKeyStep) can branch on it without touching
+   * the blob itself — keeping them outside the ncryptsec confinement scan.
+   */
+  created: boolean;
+  /** True once the user has passed the backup test. */
+  verified: boolean;
+  setVerified: React.Dispatch<React.SetStateAction<boolean>>;
+  savedPath: string | null;
+  setSavedPath: React.Dispatch<React.SetStateAction<string | null>>;
+  /** The committed blob a save was already kicked off for (save-once guard). */
+  savedForRef: React.MutableRefObject<string | null>;
+  test: BackupTestProgress;
+  setTest: React.Dispatch<React.SetStateAction<BackupTestProgress>>;
+};
+
+/** Host-side state for `EncryptedBackupCreator` — see `EncryptedBackupSession`. */
+export function useEncryptedBackupSession(): EncryptedBackupSession {
+  const [state, dispatch] = React.useReducer(
+    encryptedBackupReducer,
+    initialEncryptedBackupState,
+  );
+  const [verified, setVerified] = React.useState(false);
+  const [savedPath, setSavedPath] = React.useState<string | null>(null);
+  const savedForRef = React.useRef<string | null>(null);
+  const [test, setTest] = React.useState<BackupTestProgress>(
+    initialBackupTestProgress,
+  );
+  return React.useMemo(
+    () => ({
+      state,
+      dispatch,
+      created: state.ncryptsec !== null && savedPath !== null,
+      verified,
+      setVerified,
+      savedPath,
+      setSavedPath,
+      savedForRef,
+      test,
+      setTest,
+    }),
+    [state, verified, savedPath, test],
+  );
+}
+
+/**
+ * Return to a secure saved-password placeholder. The encrypted blob survives
+ * for instant re-download, while no password or test attempt is retained.
+ */
+export function backupSessionToPasswordEntry(
+  session: EncryptedBackupSession,
+): void {
+  session.dispatch({ type: "back-to-password" });
+  session.setVerified(false);
+  session.setSavedPath(null);
+  session.setTest(initialBackupTestProgress);
+}
+
+/** Discard all backup-creation and verification progress. */
+export function resetEncryptedBackupSession(
+  session: EncryptedBackupSession,
+): void {
+  session.dispatch({ type: "start-new-backup" });
+  session.setVerified(false);
+  session.setSavedPath(null);
+  session.savedForRef.current = null;
+  session.setTest(initialBackupTestProgress);
+}
+
+type EncryptedBackupCreatorProps = {
+  /** "spotlight" is the onboarding treatment; "boxed" fits settings cards. */
+  variant?: "spotlight" | "boxed";
+  /**
+   * When set, the "Download" button is portaled into this element instead of
+   * rendering inline.
+   */
+  createButtonPortal?: HTMLElement | null;
+  /** Optional onboarding footer target for the guided-test verification CTA. */
+  verifyButtonPortal?: HTMLElement | null;
+  /** Extra classes for the "Download" button. */
+  createButtonClassName?: string;
+  /**
+   * Host-owned session so the backup state survives this component
+   * unmounting (onboarding Back navigation). Omitted = private session.
+   */
+  session?: EncryptedBackupSession;
+  /** Fired once the encrypted payload has been created (before saving). */
+  onCreated?: () => void;
+  /** Fired only after the encrypted key file has been saved successfully. */
+  onSaved?: (path: string) => void;
+  /** Whether creation continues into onboarding's guided test ceremony. */
+  guidedTest?: boolean;
+  /** Fired once when the user completes the backup test successfully. */
+  onVerified?: () => void;
+};
+
+/**
+ * 1Password-style memorable-password generator popover with word-count and
+ * separator fields, anchored to a refresh icon inset in the password field
+ * (the anchor assumes a `relative` parent). The first click opens the
+ * popover and generates; further clicks on the icon re-roll while the
+ * popover stays open — only click-outside or Esc closes it. There is no
+ * candidate preview: every generation writes the passphrase straight into
+ * the parent's password field via `onGenerated`.
+ */
+function PassphraseGeneratorPopover({
+  disabled = false,
+  onRequestGenerate,
+  onGenerated,
+  securityTheme = false,
+}: {
+  disabled?: boolean;
+  onRequestGenerate?: () => void;
+  onGenerated: (value: string) => void;
+  securityTheme?: boolean;
+}) {
+  const [open, setOpen] = React.useState(false);
+  const [words, setWords] = React.useState(DEFAULT_GENERATED_WORDS);
+  const [separator, setSeparator] = React.useState<string>(DEFAULT_SEPARATOR);
+  const [error, setError] = React.useState<string | null>(null);
+  const anchorRef = React.useRef<HTMLButtonElement | null>(null);
+  const mountedRef = React.useRef(true);
+  // Read via a ref so `generate` stays reference-stable even though parents
+  // pass an inline `onGenerated`. Otherwise each generated password would
+  // re-render the parent, rebuild `generate`, and re-fire the open/controls
+  // effect below — an infinite generate loop while the popover is open.
+  const onGeneratedRef = React.useRef(onGenerated);
+
+  React.useEffect(() => {
+    onGeneratedRef.current = onGenerated;
+  }, [onGenerated]);
+
+  React.useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const generate = React.useCallback(async (wordCount: number, sep: string) => {
+    setError(null);
+    try {
+      const passphrase = await generateBackupPassphrase({
+        words: wordCount,
+        separator: sep,
+      });
+      if (mountedRef.current) onGeneratedRef.current(passphrase);
+    } catch (err) {
+      if (!mountedRef.current) return;
+      setError(
+        err instanceof Error ? err.message : "Failed to generate a password.",
+      );
+    }
+  }, []);
+
+  // Fill the password field on every open and whenever a control changes.
+  React.useEffect(() => {
+    if (open) void generate(words, separator);
+  }, [open, words, separator, generate]);
+
+  return (
+    <Popover onOpenChange={setOpen} open={open}>
+      {/* Anchor (not Trigger): Radix triggers toggle on click, but repeat
+          clicks here must generate a fresh password while the popover stays
+          open. Only click-outside or Esc closes it. */}
+      <PopoverAnchor asChild>
+        <Button
+          aria-label="Generate a password"
+          className={cn(
+            "absolute right-9 top-1/2 h-8 w-8 -translate-y-1/2 text-muted-foreground hover:text-foreground",
+            securityTheme &&
+              "text-black/55 hover:bg-black/5 hover:text-black/80",
+          )}
+          data-testid="backup-passphrase-generate"
+          disabled={disabled}
+          onClick={() => {
+            // The open effect below generates the first password; later
+            // clicks re-roll with the current controls.
+            if (onRequestGenerate) {
+              onRequestGenerate();
+              return;
+            }
+            if (!open) setOpen(true);
+            else void generate(words, separator);
+          }}
+          ref={anchorRef}
+          size="icon"
+          type="button"
+          variant="ghost"
+        >
+          <RefreshCw className="h-4 w-4" aria-hidden="true" />
+        </Button>
+      </PopoverAnchor>
+      <PopoverContent
+        align="end"
+        className="w-72 space-y-3 text-foreground"
+        onInteractOutside={(event) => {
+          // Clicking the anchor icon is "outside" the content — keep the
+          // popover open so that click re-rolls instead of closing.
+          if (
+            event.target instanceof Node &&
+            anchorRef.current?.contains(event.target)
+          ) {
+            event.preventDefault();
+          }
+        }}
+        onOpenAutoFocus={(event) => event.preventDefault()}
+      >
+        <div className="flex items-center justify-between gap-4">
+          <label
+            className="text-sm text-muted-foreground"
+            htmlFor="backup-passphrase-words"
+          >
+            Words
+          </label>
+          <div className="flex flex-1 items-center justify-end gap-3">
+            <input
+              className="h-1.5 w-full max-w-30 cursor-pointer appearance-none rounded-full bg-foreground/15 accent-primary"
+              id="backup-passphrase-words"
+              data-testid="backup-passphrase-words"
+              max={MAX_GENERATED_WORDS}
+              min={MIN_GENERATED_WORDS}
+              onChange={(event) => setWords(Number(event.target.value))}
+              type="range"
+              value={words}
+            />
+            <span className="w-6 text-right text-sm tabular-nums text-foreground">
+              {words}
+            </span>
+          </div>
+        </div>
+
+        <div className="flex items-center justify-between gap-4">
+          <label
+            className="text-sm text-muted-foreground"
+            htmlFor="backup-passphrase-separator"
+          >
+            Separator
+          </label>
+          <select
+            className="h-8 rounded-lg border border-border bg-background px-2 text-sm text-foreground outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
+            id="backup-passphrase-separator"
+            data-testid="backup-passphrase-separator"
+            onChange={(event) => setSeparator(event.target.value)}
+            value={separator}
+          >
+            {SEPARATOR_OPTIONS.map((option) => (
+              <option key={option.label} value={option.value}>
+                {option.label}
+              </option>
+            ))}
+          </select>
+        </div>
+
+        {error ? (
+          <p
+            className="flex items-start gap-1.5 text-xs text-destructive"
+            data-testid="backup-passphrase-generate-error"
+          >
+            <AlertTriangle className="mt-0.5 h-3.5 w-3.5 shrink-0" />
+            {error}
+          </p>
+        ) : null}
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+/**
+ * Password-first encrypted key download flow shared by onboarding and
+ * Settings. The raw private key never enters this component. Rust creates the
+ * NIP-49 payload locally, then the native save dialog produces the user-owned
+ * file.
+ *
+ * The flow is a single password input; a refresh icon inset in the field
+ * opens a 1Password-style generator popover (word count + separator).
+ * Encryption starts eagerly once the password is valid, so Download usually
+ * opens the save dialog instantly. Background encryption is silent; clicking
+ * mid-encryption reveals the queued-download ticker until the KDF finishes.
+ */
+export function EncryptedBackupCreator({
+  variant = "spotlight",
+  createButtonPortal,
+  verifyButtonPortal,
+  createButtonClassName,
+  session: sessionProp,
+  onCreated,
+  onSaved,
+  guidedTest = true,
+  onVerified,
+}: EncryptedBackupCreatorProps) {
+  // Hosts without a longer-lived session get a private one (settings card).
+  const fallbackSession = useEncryptedBackupSession();
+  const session = sessionProp ?? fallbackSession;
+  const { state, dispatch, savedPath, setSavedPath, savedForRef } = session;
+  const [isRevealed, setIsRevealed] = React.useState(false);
+  const [saveError, setSaveError] = React.useState<string | null>(null);
+  const [isSaving, setIsSaving] = React.useState(false);
+  const [confirmNewPassword, setConfirmNewPassword] = React.useState(false);
+  const mountedRef = React.useRef(true);
+
+  React.useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  // A queued download locks the form — mask the password too so it isn't
+  // left readable on screen while the user waits for the save dialog.
+  React.useEffect(() => {
+    if (state.downloadPending) setIsRevealed(false);
+  }, [state.downloadPending]);
+
+  // Correlate KDF completion by an opaque request id. The password exists only
+  // in this short-lived effect closure and is cleared from reducer state once
+  // Rust returns; stale completions cannot commit.
+  const pendingPassphrase = pendingEncryptPassphrase(state);
+  const skipDebounce = state.downloadPending;
+  React.useEffect(() => {
+    if (!pendingPassphrase) return;
+    let cancelled = false;
+    const requestId = state.nextRequestId;
+    const start = () => {
+      if (cancelled) return;
+      dispatch({ type: "encrypt-started", requestId });
+      void createNcryptsecBackup(pendingPassphrase)
+        .then((ncryptsec) =>
+          dispatch({ type: "encrypt-succeeded", requestId, ncryptsec }),
+        )
+        .catch((err: unknown) =>
+          dispatch({
+            type: "encrypt-failed",
+            requestId,
+            message:
+              err instanceof Error
+                ? err.message
+                : "Failed to encrypt your key.",
+          }),
+        );
+    };
+    const timer = window.setTimeout(
+      start,
+      skipDebounce ? 0 : ENCRYPT_DEBOUNCE_MS,
+    );
+    return () => {
+      cancelled = true;
+      window.clearTimeout(timer);
+    };
+  }, [dispatch, pendingPassphrase, skipDebounce, state.nextRequestId]);
+
+  // Download commit: fires once per committed blob, whether the commit was
+  // instant (encryption already done) or resolved a queued download. The flow
+  // only advances to the test view once the file is actually on disk — a
+  // canceled save dialog or a save failure rolls the commit back to the
+  // password form so "Download backup" can be clicked again.
+  React.useEffect(() => {
+    const ncryptsec = state.ncryptsec;
+    if (!ncryptsec || savedForRef.current === ncryptsec) return;
+    savedForRef.current = ncryptsec;
+    onCreated?.();
+    setIsSaving(true);
+    setSaveError(null);
+    const rollBack = () => {
+      savedForRef.current = null;
+      dispatch({ type: "back-to-password" });
+    };
+    void saveNcryptsecCopy(ncryptsec)
+      .then((path) => {
+        if (path) {
+          setSavedPath(path);
+          onSaved?.(path);
+        } else {
+          // User canceled the native save dialog — nothing was downloaded.
+          rollBack();
+        }
+      })
+      .catch((err: unknown) => {
+        rollBack();
+        if (mountedRef.current)
+          setSaveError(
+            err instanceof Error ? err.message : "Failed to save your key.",
+          );
+      })
+      .finally(() => {
+        if (mountedRef.current) setIsSaving(false);
+      });
+  }, [
+    dispatch,
+    onCreated,
+    onSaved,
+    savedForRef,
+    setSavedPath,
+    state.ncryptsec,
+  ]);
+
+  const handleSaveCopy = React.useCallback(async () => {
+    if (!state.ncryptsec || isSaving) return;
+    setIsSaving(true);
+    setSaveError(null);
+    try {
+      const path = await saveNcryptsecCopy(state.ncryptsec);
+      if (mountedRef.current && path) {
+        setSavedPath(path);
+        onSaved?.(path);
+      }
+    } catch (err) {
+      if (mountedRef.current)
+        setSaveError(
+          err instanceof Error ? err.message : "Failed to save your key.",
+        );
+    } finally {
+      if (mountedRef.current) setIsSaving(false);
+    }
+  }, [isSaving, onSaved, setSavedPath, state.ncryptsec]);
+
+  const { setVerified, test, setTest } = session;
+  const handleVerified = React.useCallback(() => {
+    setVerified(true);
+    onVerified?.();
+  }, [onVerified, setVerified]);
+
+  const issue = passphraseIssue(state.passphrase);
+  const showBackupTimeline =
+    variant === "spotlight" &&
+    !state.savedPassword &&
+    !state.createError &&
+    !saveError;
+
+  // The test view requires a successful save, not just a committed blob —
+  // while the native save dialog is open the password form stays put.
+  if (state.ncryptsec && savedPath && guidedTest) {
+    return (
+      <div data-testid="encrypted-backup-result">
+        <BackupTestFlow
+          isSaving={isSaving}
+          expectedNcryptsec={state.ncryptsec}
+          onProgressChange={setTest}
+          onSaveCopy={() => void handleSaveCopy()}
+          onVerified={handleVerified}
+          progress={test}
+          saveError={saveError}
+          variant={variant}
+          verifyButtonPortal={verifyButtonPortal}
+        />
+      </div>
+    );
+  }
+  // Without the guided test (settings), a completed save keeps the form
+  // visible in its saved-password state: masked input, instant re-download,
+  // and the change-password confirmation guarding any edit.
+
+  return (
+    <div
+      className={cn("mx-auto w-full max-w-[500px] space-y-3 text-left")}
+      data-testid="encrypted-backup-creator"
+    >
+      <div
+        className={cn(
+          "relative",
+          showBackupTimeline && "pb-32 pt-28 [@media(max-height:40rem)]:py-0",
+        )}
+      >
+        {showBackupTimeline ? <BackupPasswordTimeline /> : null}
+        <div className="relative z-10">
+          <Input
+            aria-label="Encryption password"
+            autoComplete="new-password"
+            autoFocus={variant === "spotlight"}
+            className={cn(
+              "font-mono",
+              variant === "spotlight"
+                ? "h-14 rounded-2xl border-black/20 bg-white px-20 text-center text-lg text-black/80 shadow-none placeholder:text-black/55 focus-visible:ring-black/35"
+                : "h-10 bg-background pr-19",
+            )}
+            data-testid="backup-passphrase-input"
+            disabled={state.downloadPending}
+            readOnly={state.savedPassword}
+            aria-describedby={
+              state.savedPassword
+                ? "backup-saved-password-description"
+                : undefined
+            }
+            onBeforeInput={(event) => {
+              if (state.savedPassword) {
+                event.preventDefault();
+                setConfirmNewPassword(true);
+              }
+            }}
+            onPaste={(event) => {
+              if (state.savedPassword) {
+                event.preventDefault();
+                setConfirmNewPassword(true);
+              }
+            }}
+            onChange={(event) =>
+              dispatch({ type: "set-passphrase", value: event.target.value })
+            }
+            onKeyDown={(event) => {
+              if (event.key !== "Enter" || event.nativeEvent.isComposing)
+                return;
+              event.preventDefault();
+              if (downloadDisabled(state) || isSaving) return;
+              if (state.savedPassword && state.ncryptsec) {
+                void handleSaveCopy();
+                return;
+              }
+              dispatch({ type: "download-clicked" });
+            }}
+            placeholder={
+              state.savedPassword
+                ? ""
+                : `Password (min ${MIN_PASSPHRASE_LEN} characters)`
+            }
+            type={isRevealed ? "text" : "password"}
+            value={state.passphrase}
+          />
+          {state.savedPassword ? (
+            <div
+              aria-hidden
+              className={cn(
+                "pointer-events-none absolute inset-y-0 left-3 flex items-center font-mono tracking-widest text-foreground",
+                variant === "spotlight" && "text-black/80",
+              )}
+              data-testid="backup-saved-password-mask"
+            >
+              ••••••••••••••••••••••••••••••••
+            </div>
+          ) : null}
+          {state.savedPassword ? (
+            <span className="sr-only" id="backup-saved-password-description">
+              Backup password saved; hidden for security.
+            </span>
+          ) : null}
+          <Button
+            aria-label={
+              state.savedPassword
+                ? "Change saved backup password"
+                : isRevealed
+                  ? "Hide password"
+                  : "Reveal password"
+            }
+            className={cn(
+              "absolute right-1 top-1/2 h-8 w-8 -translate-y-1/2 text-muted-foreground hover:text-foreground",
+              variant === "spotlight" &&
+                "text-black/55 hover:bg-black/5 hover:text-black/80",
+            )}
+            data-testid="backup-passphrase-reveal-toggle"
+            disabled={state.downloadPending}
+            onClick={() =>
+              state.savedPassword
+                ? setConfirmNewPassword(true)
+                : setIsRevealed((revealed) => !revealed)
+            }
+            size="icon"
+            type="button"
+            variant="ghost"
+          >
+            {isRevealed ? (
+              <EyeOff className="h-4 w-4" aria-hidden="true" />
+            ) : (
+              <Eye className="h-4 w-4" aria-hidden="true" />
+            )}
+          </Button>
+          <PassphraseGeneratorPopover
+            disabled={state.downloadPending}
+            onRequestGenerate={
+              state.savedPassword
+                ? () => setConfirmNewPassword(true)
+                : undefined
+            }
+            onGenerated={(value) => {
+              dispatch({ type: "set-passphrase", value });
+              // A generated password must be visible so the user can save it.
+              setIsRevealed(true);
+            }}
+            securityTheme={variant === "spotlight"}
+          />
+          {issue ? (
+            <p
+              className="absolute left-1 top-full mt-1 animate-in text-xs text-muted-foreground fade-in slide-in-from-top-1 duration-200 motion-reduce:animate-none"
+              data-testid="backup-passphrase-issue"
+            >
+              {issue}
+            </p>
+          ) : null}
+        </div>
+      </div>
+
+      {state.savedPassword && state.ncryptsec && savedPath ? (
+        <div
+          className="space-y-1 text-center"
+          data-testid="encrypted-backup-created"
+        >
+          <p
+            className="text-xs text-muted-foreground"
+            data-testid="encrypted-backup-saved-path"
+          >
+            Backup saved to {savedPath}
+          </p>
+          <p className="text-xs leading-5 text-muted-foreground">
+            Your password isn't kept — download another copy anytime, or start
+            over to choose a new password.
+          </p>
+        </div>
+      ) : null}
+
+      {state.createError ? (
+        <p
+          className="text-center text-sm text-destructive"
+          data-testid="encrypted-backup-create-error"
+        >
+          {state.createError}
+        </p>
+      ) : null}
+
+      {saveError ? (
+        <p
+          className="text-center text-sm text-destructive"
+          data-testid="encrypted-backup-save-error"
+        >
+          {saveError}
+        </p>
+      ) : null}
+
+      {(() => {
+        // A queued download gets an explicit progress treatment. Background
+        // encryption stays silent until the user asks to download.
+        const createButton = (
+          <div className="relative">
+            {state.downloadPending || isSaving ? (
+              <Spinner
+                aria-label="Encrypting your key"
+                className="absolute right-full top-1/2 mr-3 h-4 w-4 -translate-y-1/2 border-2"
+                data-testid="encrypted-backup-encrypting"
+              />
+            ) : null}
+            <Button
+              className={cn("h-9 rounded-full px-6", createButtonClassName)}
+              data-testid="encrypted-backup-create"
+              disabled={downloadDisabled(state) || isSaving}
+              onClick={() =>
+                state.savedPassword && state.ncryptsec
+                  ? void handleSaveCopy()
+                  : dispatch({ type: "download-clicked" })
+              }
+              type="button"
+            >
+              {state.downloadPending ? (
+                <PendingDownloadTicker />
+              ) : state.savedPassword ? (
+                "Download backup again"
+              ) : (
+                "Backup key"
+              )}
+            </Button>
+          </div>
+        );
+        // `undefined` = inline (settings); `null` = slot not mounted yet
+        // (skip a frame rather than flashing the button inline).
+        if (createButtonPortal === undefined)
+          return <div className="flex justify-center">{createButton}</div>;
+        return createButtonPortal
+          ? createPortal(createButton, createButtonPortal)
+          : null;
+      })()}
+      <AlertDialog
+        open={confirmNewPassword}
+        onOpenChange={setConfirmNewPassword}
+      >
+        <AlertDialogContent
+          className={cn(
+            variant === "spotlight" && "buzz-onboarding-security-theme",
+          )}
+          data-testid="backup-change-password-dialog"
+          surface={variant === "spotlight" ? "textured" : "default"}
+          textureSize="compact"
+          textureTone={variant === "spotlight" ? "dark" : "light"}
+        >
+          <AlertDialogHeader>
+            <AlertDialogTitle>Create a new backup password?</AlertDialogTitle>
+            <AlertDialogDescription>
+              Starting over lets you pick a new password and download a fresh
+              backup file. Backups you saved earlier will still work — just use
+              the password you created them with.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel
+              className={
+                variant === "spotlight"
+                  ? ONBOARDING_SECONDARY_CTA_CLASS
+                  : undefined
+              }
+            >
+              Keep current backup
+            </AlertDialogCancel>
+            <AlertDialogAction
+              className={
+                variant === "spotlight"
+                  ? ONBOARDING_SECURITY_PRIMARY_CTA_CLASS
+                  : undefined
+              }
+              data-testid="backup-start-new-password"
+              onClick={() => {
+                dispatch({ type: "start-new-backup" });
+                setSavedPath(null);
+                savedForRef.current = null;
+                setTest(initialBackupTestProgress);
+                setIsRevealed(false);
+              }}
+            >
+              Start with a new password
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </div>
+  );
+}
diff --git a/desktop/src/features/onboarding/ui/KeyringLockedScreen.tsx b/desktop/src/features/onboarding/ui/KeyringLockedScreen.tsx
index 0376fc9709..a6a02f38c0 100644
--- a/desktop/src/features/onboarding/ui/KeyringLockedScreen.tsx
+++ b/desktop/src/features/onboarding/ui/KeyringLockedScreen.tsx
@@ -22,8 +22,8 @@ export function KeyringLockedScreen() {
   }, []);
 
   const handleImport = React.useCallback(
-    async (nsec: string) => {
-      const identity = await importIdentity(nsec);
+    async (nsec: string, password?: string) => {
+      const identity = await importIdentity(nsec, password);
       // Update the identity query cache so useIdentityQuery observers see
       // locked: false. The bootedLocked latch in hooks.ts will then route
       // to RelaunchRequiredScreen via bootedLocked && !identityLocked.
diff --git a/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx b/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
index ca87c76636..cee17c68f8 100644
--- a/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
+++ b/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
@@ -1,20 +1,33 @@
 import * as React from "react";
 import type { QueryClient } from "@tanstack/react-query";
+import { ArrowUp } from "lucide-react";
+import { motion, useReducedMotion } from "motion/react";
 
 import {
   getIdentity,
   importIdentity,
   persistCurrentIdentity,
 } from "@/shared/api/tauriIdentity";
+import type { IdentityStorage } from "@/shared/api/types";
 import { Button } from "@/shared/ui/button";
 import { StartupWindowDragRegion } from "@/shared/ui/StartupWindowDragRegion";
 import { BackupStep } from "./BackupStep";
 import { DefaultConfigStep } from "./DefaultConfigStep";
+import { DownloadKeyStep } from "./DownloadKeyStep";
+import {
+  backupSessionToPasswordEntry,
+  resetEncryptedBackupSession,
+  useEncryptedBackupSession,
+} from "./EncryptedBackupCreator";
 import { IdentityKeyHelpDialog } from "./IdentityKeyHelpDialog";
 import { LandingBees } from "./LandingBees";
-import { NostrKeyImportForm } from "./NostrKeyImportForm";
+import {
+  NostrKeyImportForm,
+  type NostrKeyImportStage,
+} from "./NostrKeyImportForm";
 import {
   ONBOARDING_LANDING_CTA_CLASS,
+  ONBOARDING_SECONDARY_CTA_CLASS,
   OnboardingChrome,
 } from "./OnboardingChrome";
 import { OnboardingFooterProvider } from "./OnboardingFooter";
@@ -28,6 +41,8 @@ export type MachineOnboardingPage =
   | "setup"
   | "config";
 
+type BackupSubview = "created" | "options" | "password";
+
 /** A pending navigation the parent should execute after RouterProvider mounts. */
 export type PostOnboardingNavigation = {
   to: string;
@@ -61,10 +76,27 @@ export function MachineOnboardingFlow({
   const [error, setError] = React.useState<string | null>(null);
   const [isPending, setIsPending] = React.useState(false);
   const [identityWasImported, setIdentityWasImported] = React.useState(false);
+  const [keyImportStage, setKeyImportStage] =
+    React.useState<NostrKeyImportStage>("key-entry");
   const [selectedPubkey, setSelectedPubkey] = React.useState<string | null>(
     null,
   );
+  const [identityStorage, setIdentityStorage] = React.useState<
+    IdentityStorage | undefined
+  >();
   const [readyRuntimeIds, setReadyRuntimeIds] = React.useState<string[]>([]);
+  const [backupSubview, setBackupSubview] =
+    React.useState<BackupSubview>("created");
+  const [backupDirection, setBackupDirection] = React.useState<
+    "forward" | "backward"
+  >("forward");
+  const [returningFromSecurity, setReturningFromSecurity] =
+    React.useState(false);
+  // Owned here so switching between the yellow onboarding view and the dark
+  // security subview keeps the created backup, password, and test progress.
+  const backupSession = useEncryptedBackupSession();
+  const reduceMotion = useReducedMotion() ?? false;
+  const isSecuritySubview = page === "backup" && backupSubview !== "created";
   const handleReadyRuntimeIdsChange = React.useCallback(
     (runtimeIds: readonly string[]) => {
       setReadyRuntimeIds(Array.from(new Set(runtimeIds)));
@@ -79,6 +111,10 @@ export function MachineOnboardingFlow({
       const identity = await getIdentity();
       queryClient.setQueryData(["identity"], identity);
       setSelectedPubkey(identity.pubkey);
+      setIdentityStorage(identity.storage);
+      setBackupDirection("forward");
+      setReturningFromSecurity(false);
+      setBackupSubview("created");
       setPage("backup");
     } catch (cause) {
       setError(
@@ -101,6 +137,10 @@ export function MachineOnboardingFlow({
       const identity = await persistCurrentIdentity();
       queryClient.setQueryData(["identity"], identity);
       setSelectedPubkey(identity.pubkey);
+      setIdentityStorage(identity.storage);
+      setBackupDirection("forward");
+      setReturningFromSecurity(false);
+      setBackupSubview("created");
       setPage("backup");
     } catch (cause) {
       setError(
@@ -112,8 +152,8 @@ export function MachineOnboardingFlow({
   }, [queryClient]);
 
   const importExistingIdentity = React.useCallback(
-    async (nsec: string) => {
-      const identity = await importIdentity(nsec);
+    async (nsec: string, password?: string) => {
+      const identity = await importIdentity(nsec, password);
       continueWithIdentity(identity.pubkey);
       queryClient.setQueryData(["identity"], identity);
       setIdentityWasImported(true);
@@ -126,6 +166,8 @@ export function MachineOnboardingFlow({
   return (
     <div
       className={`buzz-onboarding-neutral-theme buzz-startup-shell flex max-h-dvh items-start justify-center overflow-x-hidden overflow-y-auto px-4 text-foreground ${
+        isSecuritySubview ? "buzz-onboarding-security-theme" : ""
+      } ${
         page === "identity"
           ? "buzz-onboarding-welcome py-8"
           : "pb-28 pt-[106px]"
@@ -134,7 +176,24 @@ export function MachineOnboardingFlow({
     >
       <StartupWindowDragRegion />
       {page === "identity" ? <LandingBees /> : null}
-      {page !== "identity" ? (
+      {isSecuritySubview ? (
+        <div className="fixed inset-x-0 top-8 z-20 flex justify-center px-6">
+          <Button
+            className={`${ONBOARDING_SECONDARY_CTA_CLASS} gap-2 px-5`}
+            data-testid="backup-return-to-onboarding"
+            onClick={() => {
+              setBackupDirection("backward");
+              setReturningFromSecurity(true);
+              setBackupSubview("created");
+            }}
+            type="button"
+            variant="ghost"
+          >
+            <ArrowUp className="h-4 w-4" aria-hidden="true" />
+            Return to onboarding
+          </Button>
+        </div>
+      ) : page !== "identity" ? (
         <OnboardingChrome
           current={page === "config" ? 4 : page === "setup" ? 3 : 2}
         />
@@ -178,9 +237,12 @@ export function MachineOnboardingFlow({
                       : "Create a new identity key"}
                 </Button>
                 <Button
-                  className="h-9 rounded-full bg-foreground/10 px-5 hover:bg-foreground/15"
+                  className={`${ONBOARDING_SECONDARY_CTA_CLASS} px-5`}
                   disabled={isPending}
-                  onClick={() => setPage("key-import")}
+                  onClick={() => {
+                    setKeyImportStage("key-entry");
+                    setPage("key-import");
+                  }}
                   type="button"
                   variant="ghost"
                 >
@@ -198,18 +260,31 @@ export function MachineOnboardingFlow({
               effect="fade"
               transitionKey="machine-key-import"
             >
-              <div className="shrink-0">
+              <motion.div
+                animate={{ opacity: 1, y: 0 }}
+                className="shrink-0"
+                initial={reduceMotion ? false : { opacity: 0, y: 10 }}
+                key={keyImportStage}
+                transition={{
+                  duration: reduceMotion ? 0 : 0.3,
+                  ease: "easeOut",
+                }}
+              >
                 <h1 className="text-title font-normal text-foreground">
-                  {identityLost
-                    ? "Re-import your key"
-                    : "Enter your private key"}
+                  {keyImportStage === "backup-password"
+                    ? "Unlock your account"
+                    : identityLost
+                      ? "Re-import your key"
+                      : "Enter your private key"}
                 </h1>
                 <p className="mt-5 max-w-[440px] text-sm leading-6 text-foreground/80">
-                  {identityLost
-                    ? "Your identity is no longer in the system keyring. Re-import your nsec to restore it."
-                    : "If you already have a Buzz account, enter your private key below to get started."}
+                  {keyImportStage === "backup-password"
+                    ? "Enter your backup password to unlock your key and restore your identity."
+                    : identityLost
+                      ? "Your identity is no longer in the system keyring. Re-import your nsec to restore it."
+                      : "If you already have a Buzz account, enter your private key below to get started."}
                 </p>
-              </div>
+              </motion.div>
               <div className="buzz-onboarding-key-import-position w-full">
                 <NostrKeyImportForm
                   backLabel={identityLost ? "Start new identity" : "Back"}
@@ -219,21 +294,62 @@ export function MachineOnboardingFlow({
                       : () => setPage("identity")
                   }
                   onImport={importExistingIdentity}
+                  onStageChange={setKeyImportStage}
                   variant="spotlight"
                 />
               </div>
             </OnboardingSlideTransition>
           ) : page === "backup" ? (
-            <BackupStep
-              direction="forward"
-              onBack={() => setPage("identity")}
-              onNext={() => setPage("setup")}
-            />
+            backupSubview === "password" ? (
+              <DownloadKeyStep
+                direction={backupDirection}
+                onBack={() => {
+                  resetEncryptedBackupSession(backupSession);
+                  setBackupDirection("backward");
+                  setReturningFromSecurity(false);
+                  setBackupSubview("options");
+                }}
+                session={backupSession}
+              />
+            ) : (
+              <BackupStep
+                direction={backupDirection}
+                identityStorage={identityStorage}
+                onBack={() => setPage("identity")}
+                onNext={() => setPage("setup")}
+                onOpenPasswordBackup={() => {
+                  resetEncryptedBackupSession(backupSession);
+                  setBackupDirection("forward");
+                  setReturningFromSecurity(false);
+                  setBackupSubview("password");
+                }}
+                onShowOptions={() => {
+                  setBackupDirection("forward");
+                  setReturningFromSecurity(false);
+                  setBackupSubview("options");
+                }}
+                optionsExpanded={backupSubview === "options"}
+                returningFromSecurity={returningFromSecurity}
+              />
+            )
           ) : page === "setup" ? (
             <SetupStep
               actions={{
-                back: () =>
-                  setPage(identityWasImported ? "key-import" : "backup"),
+                // Fresh-key users return to whichever identity backup subview
+                // they used to reach setup; imported keys skip backup entirely.
+                back: () => {
+                  if (identityWasImported) {
+                    setKeyImportStage("key-entry");
+                    setPage("key-import");
+                    return;
+                  }
+                  if (backupSubview === "password") {
+                    backupSessionToPasswordEntry(backupSession);
+                  }
+                  setBackupDirection("backward");
+                  setReturningFromSecurity(false);
+                  setPage("backup");
+                },
                 next: (runtimeIds) => {
                   const ids = Array.from(runtimeIds);
                   setReadyRuntimeIds(ids);
diff --git a/desktop/src/features/onboarding/ui/NostrKeyImportForm.tsx b/desktop/src/features/onboarding/ui/NostrKeyImportForm.tsx
index daa3f007e9..59e5bfdb0b 100644
--- a/desktop/src/features/onboarding/ui/NostrKeyImportForm.tsx
+++ b/desktop/src/features/onboarding/ui/NostrKeyImportForm.tsx
@@ -3,21 +3,33 @@ import { Check, Eye, EyeOff, KeyRound } from "lucide-react";
 
 import { cn } from "@/shared/lib/cn";
 import { nsecToNpub } from "@/shared/lib/nostrUtils";
+import {
+  classifyKeyImportInput,
+  isPlausibleNcryptsec,
+  keyImportSubmitEnabled,
+} from "../lib/keyImportInput";
 import { Button } from "@/shared/ui/button";
 import { Card } from "@/shared/ui/card";
 import { Input } from "@/shared/ui/input";
 import { Spinner } from "@/shared/ui/spinner";
-import { ONBOARDING_PRIMARY_CTA_CLASS } from "./OnboardingChrome";
+import {
+  ONBOARDING_PRIMARY_CTA_CLASS,
+  ONBOARDING_SECONDARY_CTA_CLASS,
+} from "./OnboardingChrome";
+import { BackupPasswordTimeline } from "./BackupPasswordTimeline";
 import { OnboardingFooter } from "./OnboardingFooter";
 
 const NOSTR_KEY_FILE_MAX_BYTES = 1024;
 
+export type NostrKeyImportStage = "key-entry" | "backup-password";
+
 type NostrKeyImportFormProps = {
   backLabel?: string;
   disabled?: boolean;
   errorMessage?: string | null;
   onBack: () => void;
-  onImport: (nsec: string) => Promise<void>;
+  onImport: (nsec: string, password?: string) => Promise<void>;
+  onStageChange?: (stage: NostrKeyImportStage) => void;
   /** "spotlight" is the first-launch treatment: glowy centered input, no drop zone, pill buttons. */
   variant?: "default" | "spotlight";
 };
@@ -35,18 +47,24 @@ export function NostrKeyImportForm({
   errorMessage: externalErrorMessage = null,
   onBack,
   onImport,
+  onStageChange,
   variant = "default",
 }: NostrKeyImportFormProps) {
   const [nsecInput, setNsecInput] = React.useState("");
+  const [passphrase, setPassphrase] = React.useState("");
   const [isImporting, setIsImporting] = React.useState(false);
   const [importError, setImportError] = React.useState<string | null>(null);
   const [isDragging, setIsDragging] = React.useState(false);
   const [isRevealed, setIsRevealed] = React.useState(false);
   const inputRef = React.useRef<HTMLInputElement | null>(null);
+  const passphraseInputRef = React.useRef<HTMLInputElement | null>(null);
   const fileInputRef = React.useRef<HTMLInputElement | null>(null);
   const previewNpub = React.useMemo(() => nsecToNpub(nsecInput), [nsecInput]);
   const trimmedInput = nsecInput.trim();
   const hasInput = trimmedInput.length > 0;
+  const inputKind = classifyKeyImportInput(nsecInput);
+  const isEncryptedInput = inputKind === "ncryptsec";
+  const isPasswordStage = isPlausibleNcryptsec(nsecInput);
 
   // Masked-by-default must re-assert whenever the field empties: a sticky
   // reveal from a previous key must never apply to newly pasted content the
@@ -56,14 +74,33 @@ export function NostrKeyImportForm({
       setIsRevealed(false);
     }
   }, [hasInput]);
-  const isValid = previewNpub !== null;
+  // A stale passphrase must never ride along when the input stops being an
+  // encrypted backup (cleared field, or replaced with a raw nsec).
+  React.useEffect(() => {
+    if (!isPasswordStage) {
+      setPassphrase("");
+    }
+  }, [isPasswordStage]);
+  const isValid = keyImportSubmitEnabled(nsecInput, passphrase);
   const isInteractionDisabled = disabled || isImporting;
-  const showInvalidHint = hasInput && !isValid && trimmedInput.length >= 5;
+  const showInvalidHint =
+    hasInput &&
+    !isPasswordStage &&
+    previewNpub === null &&
+    trimmedInput.length >= 5;
   const errorMessage = importError ?? externalErrorMessage;
 
   React.useLayoutEffect(() => {
-    inputRef.current?.focus();
-  }, []);
+    if (isPasswordStage) {
+      passphraseInputRef.current?.focus();
+    } else {
+      inputRef.current?.focus();
+    }
+  }, [isPasswordStage]);
+
+  React.useEffect(() => {
+    onStageChange?.(isPasswordStage ? "backup-password" : "key-entry");
+  }, [isPasswordStage, onStageChange]);
 
   const openFilePicker = React.useCallback(() => {
     if (isInteractionDisabled) {
@@ -81,7 +118,7 @@ export function NostrKeyImportForm({
 
     if (file.size > NOSTR_KEY_FILE_MAX_BYTES) {
       setImportError(
-        "That file is too large to be a key. Drop a .key file or paste your nsec.",
+        "That file is too large to be a key backup or private key. Choose another file.",
       );
       return;
     }
@@ -108,9 +145,13 @@ export function NostrKeyImportForm({
       return;
     }
 
-    if (!previewNpub) {
+    if (!isValid) {
       setImportError(
-        "That doesn't look like a valid nsec. Paste an nsec1 key.",
+        isPasswordStage
+          ? "Enter the password for this key backup."
+          : isEncryptedInput
+            ? "That doesn't look like a complete ncryptsec backup."
+            : "That doesn't look like a valid nsec. Paste an nsec1 key.",
       );
       return;
     }
@@ -119,7 +160,7 @@ export function NostrKeyImportForm({
     setImportError(null);
 
     try {
-      await onImport(trimmedInput);
+      await onImport(trimmedInput, isPasswordStage ? passphrase : undefined);
     } catch (error) {
       setImportError(
         error instanceof Error ? error.message : "Couldn't import this key.",
@@ -127,7 +168,28 @@ export function NostrKeyImportForm({
     } finally {
       setIsImporting(false);
     }
-  }, [isInteractionDisabled, onImport, previewNpub, trimmedInput]);
+  }, [
+    isEncryptedInput,
+    isInteractionDisabled,
+    isPasswordStage,
+    isValid,
+    onImport,
+    passphrase,
+    trimmedInput,
+  ]);
+
+  const handleBack = React.useCallback(() => {
+    if (!isPasswordStage) {
+      onBack();
+      return;
+    }
+
+    setNsecInput("");
+    setPassphrase("");
+    setImportError(null);
+    setIsRevealed(false);
+    onStageChange?.("key-entry");
+  }, [isPasswordStage, onBack, onStageChange]);
 
   return (
     <form
@@ -137,221 +199,296 @@ export function NostrKeyImportForm({
         void handleSubmit();
       }}
     >
-      <div className="space-y-1.5 text-left">
-        <label
-          className={cn(
-            "text-sm font-medium text-foreground",
-            variant === "spotlight" && "sr-only",
-          )}
-          htmlFor="nostr-private-key"
-        >
-          Private key
-        </label>
-        {variant === "spotlight" ? (
-          <Card
-            className="w-full px-8 py-12"
-            data-testid="nostr-import-card"
-            variant="textured"
+      {!isPasswordStage ? (
+        <div className="space-y-1.5 text-left">
+          <label
+            className={cn(
+              "text-sm font-medium text-foreground",
+              variant === "spotlight" && "sr-only",
+            )}
+            htmlFor="nostr-private-key"
           >
-            <div className="relative w-full">
-              <Input
-                autoComplete="off"
-                autoCorrect="off"
-                // Symmetric px reserves the absolutely positioned toggle's
-                // footprint on BOTH sides, so the centered key text never
-                // runs under the eye control and stays optically centered.
-                className="h-[3.6875rem] rounded-none border-0 bg-transparent px-10 text-center font-mono !text-4xl text-[color:var(--buzz-onboarding-backup-ink)] shadow-none placeholder:text-foreground/30 focus-visible:ring-0"
-                data-testid="nostr-import-nsec-input"
-                id="nostr-private-key"
-                onChange={(event) => {
-                  setNsecInput(event.target.value);
-                  setImportError(null);
-                }}
-                placeholder="Enter your key here"
-                ref={inputRef}
-                spellCheck={false}
-                type={isRevealed ? "text" : "password"}
-                value={nsecInput}
-              />
-              {/* Absolutely positioned so appearing/disappearing never resizes
+            Private key
+          </label>
+          {variant === "spotlight" ? (
+            <Card
+              className="w-full px-8 py-12"
+              data-testid="nostr-import-card"
+              variant="textured"
+            >
+              <div className="relative w-full">
+                <Input
+                  autoComplete="off"
+                  autoCorrect="off"
+                  // Symmetric px reserves the absolutely positioned toggle's
+                  // footprint on BOTH sides, so the centered key text never
+                  // runs under the eye control and stays optically centered.
+                  className="h-[3.6875rem] rounded-none border-0 bg-transparent px-10 text-center font-mono !text-4xl text-[color:var(--buzz-onboarding-backup-ink)] shadow-none placeholder:text-foreground/30 focus-visible:ring-0"
+                  data-testid="nostr-import-nsec-input"
+                  id="nostr-private-key"
+                  onChange={(event) => {
+                    setNsecInput(event.target.value);
+                    setImportError(null);
+                  }}
+                  placeholder="Enter your key here"
+                  ref={inputRef}
+                  spellCheck={false}
+                  type={isRevealed ? "text" : "password"}
+                  value={nsecInput}
+                />
+                {/* Absolutely positioned so appearing/disappearing never resizes
                   the input or shifts its centered text; fades with hasInput. */}
-              <Button
-                aria-hidden={!hasInput}
-                aria-label={
-                  isRevealed ? "Hide private key" : "Reveal private key"
-                }
-                className={cn(
-                  "absolute right-8 top-1/2 h-10 w-10 -translate-y-1/2 text-muted-foreground transition-opacity duration-300 hover:bg-foreground/10 hover:text-foreground motion-reduce:transition-none",
-                  hasInput ? "opacity-100" : "pointer-events-none opacity-0",
-                )}
-                data-testid="nostr-import-reveal-toggle"
-                onClick={() => setIsRevealed((current) => !current)}
-                size="icon"
-                tabIndex={hasInput ? 0 : -1}
-                type="button"
-                variant="ghost"
-              >
-                {isRevealed ? (
-                  <EyeOff aria-hidden="true" className="h-6 w-6" />
-                ) : (
-                  <Eye aria-hidden="true" className="h-6 w-6" />
-                )}
-              </Button>
-            </div>
-          </Card>
-        ) : (
-          <Input
-            autoComplete="off"
-            autoCorrect="off"
-            className="h-10 bg-background"
-            data-testid="nostr-import-nsec-input"
-            id="nostr-private-key"
-            onChange={(event) => {
-              setNsecInput(event.target.value);
-              setImportError(null);
-            }}
-            placeholder="nsec1..."
-            ref={inputRef}
-            spellCheck={false}
-            type="password"
-            value={nsecInput}
-          />
-        )}
-      </div>
+                <Button
+                  aria-hidden={!hasInput}
+                  aria-label={
+                    isRevealed ? "Hide private key" : "Reveal private key"
+                  }
+                  className={cn(
+                    "absolute right-8 top-1/2 h-10 w-10 -translate-y-1/2 text-muted-foreground transition-opacity duration-300 hover:bg-foreground/10 hover:text-foreground motion-reduce:transition-none",
+                    hasInput ? "opacity-100" : "pointer-events-none opacity-0",
+                  )}
+                  data-testid="nostr-import-reveal-toggle"
+                  onClick={() => setIsRevealed((current) => !current)}
+                  size="icon"
+                  tabIndex={hasInput ? 0 : -1}
+                  type="button"
+                  variant="ghost"
+                >
+                  {isRevealed ? (
+                    <EyeOff aria-hidden="true" className="h-6 w-6" />
+                  ) : (
+                    <Eye aria-hidden="true" className="h-6 w-6" />
+                  )}
+                </Button>
+              </div>
+            </Card>
+          ) : (
+            <Input
+              autoComplete="off"
+              autoCorrect="off"
+              className="h-10 bg-background"
+              data-testid="nostr-import-nsec-input"
+              id="nostr-private-key"
+              onChange={(event) => {
+                setNsecInput(event.target.value);
+                setImportError(null);
+              }}
+              placeholder="nsec1..."
+              ref={inputRef}
+              spellCheck={false}
+              type="password"
+              value={nsecInput}
+            />
+          )}
+        </div>
+      ) : null}
 
-      {variant === "spotlight" ? null : (
-        <>
-          <input
-            accept=".key,text/plain"
-            className="sr-only"
-            disabled={isInteractionDisabled}
-            onChange={(event) => {
-              void handleFiles(event.currentTarget.files);
-              event.currentTarget.value = "";
-            }}
-            ref={fileInputRef}
-            tabIndex={-1}
-            type="file"
-          />
+      {/* Hidden file input shared by both variants: the default drop zone and
+          the spotlight "Choose a backup file" button both open it. Accepts the
+          .ncryptsec backups our own save flow emits alongside raw .key files. */}
+      <input
+        accept=".key,.ncryptsec,text/plain"
+        className="sr-only"
+        data-testid="nostr-import-file-input"
+        disabled={isInteractionDisabled}
+        onChange={(event) => {
+          void handleFiles(event.currentTarget.files);
+          event.currentTarget.value = "";
+        }}
+        ref={fileInputRef}
+        tabIndex={-1}
+        type="file"
+      />
 
-          <button
-            className={cn(
-              "relative flex h-[120px] flex-col items-center justify-center gap-3 overflow-hidden rounded-xl border border-transparent bg-muted text-foreground transition-[background-color,border-color,box-shadow,color] duration-[250ms] ease-out hover:bg-muted/80 disabled:opacity-60",
-              isDragging &&
-                "border-primary bg-primary/10 text-primary ring-1 ring-primary/35 hover:bg-primary/10",
-            )}
-            data-dragging={isDragging ? "true" : undefined}
-            data-testid="nostr-import-drop"
+      {!isPasswordStage && variant === "spotlight" ? (
+        // First-launch/wiped-identity treatment: no drop zone, but the file
+        // path must still exist — a backup saved through the OS dialog is
+        // exactly what a wiped user returns with.
+        <div className="mt-2 text-center">
+          <Button
+            className={ONBOARDING_SECONDARY_CTA_CLASS}
+            data-testid="nostr-import-file-button"
             disabled={isInteractionDisabled}
             onClick={openFilePicker}
-            onDragEnter={(event) => {
-              event.preventDefault();
-              event.stopPropagation();
-              if (!isInteractionDisabled) {
-                setIsDragging(true);
-              }
-            }}
-            onDragLeave={(event) => {
-              event.preventDefault();
-              event.stopPropagation();
-              if (
-                event.currentTarget.contains(event.relatedTarget as Node | null)
-              ) {
-                return;
-              }
-              setIsDragging(false);
-            }}
-            onDragOver={(event) => {
-              event.preventDefault();
-              event.stopPropagation();
-              if (!isInteractionDisabled) {
-                event.dataTransfer.dropEffect = "copy";
-              }
-            }}
-            onDrop={(event) => {
-              event.preventDefault();
-              event.stopPropagation();
-              setIsDragging(false);
-              if (isInteractionDisabled) {
-                return;
-              }
-              void handleFiles(event.dataTransfer.files);
-            }}
             type="button"
+            variant="ghost"
           >
-            <span
-              aria-hidden="true"
-              className={cn(
-                "pointer-events-none absolute inset-0 rounded-[inherit] bg-primary/10 opacity-0 transition-opacity duration-[250ms] ease-out",
-                isDragging && "opacity-100",
-              )}
-            />
-            <KeyRound
-              className={cn(
-                "relative h-8 w-8 text-muted-foreground transition-colors duration-[250ms] ease-out",
-                isDragging && "text-primary",
-              )}
+            Choose a backup file
+          </Button>
+        </div>
+      ) : !isPasswordStage ? (
+        <button
+          className={cn(
+            "relative flex h-[120px] flex-col items-center justify-center gap-3 overflow-hidden rounded-xl border border-transparent bg-muted text-foreground transition-[background-color,border-color,box-shadow,color] duration-[250ms] ease-out hover:bg-muted/80 disabled:opacity-60",
+            isDragging &&
+              "border-primary bg-primary/10 text-primary ring-1 ring-primary/35 hover:bg-primary/10",
+          )}
+          data-dragging={isDragging ? "true" : undefined}
+          data-testid="nostr-import-drop"
+          disabled={isInteractionDisabled}
+          onClick={openFilePicker}
+          onDragEnter={(event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            if (!isInteractionDisabled) {
+              setIsDragging(true);
+            }
+          }}
+          onDragLeave={(event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            if (
+              event.currentTarget.contains(event.relatedTarget as Node | null)
+            ) {
+              return;
+            }
+            setIsDragging(false);
+          }}
+          onDragOver={(event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            if (!isInteractionDisabled) {
+              event.dataTransfer.dropEffect = "copy";
+            }
+          }}
+          onDrop={(event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            setIsDragging(false);
+            if (isInteractionDisabled) {
+              return;
+            }
+            void handleFiles(event.dataTransfer.files);
+          }}
+          type="button"
+        >
+          <span
+            aria-hidden="true"
+            className={cn(
+              "pointer-events-none absolute inset-0 rounded-[inherit] bg-primary/10 opacity-0 transition-opacity duration-[250ms] ease-out",
+              isDragging && "opacity-100",
+            )}
+          />
+          <KeyRound
+            className={cn(
+              "relative h-8 w-8 text-muted-foreground transition-colors duration-[250ms] ease-out",
+              isDragging && "text-primary",
+            )}
+          />
+          <span
+            className={cn(
+              "relative text-sm font-medium text-muted-foreground transition-colors duration-[250ms] ease-out",
+              isDragging && "text-primary",
+            )}
+          >
+            Drop a key here
+          </span>
+        </button>
+      ) : null}
+
+      {isPasswordStage ? (
+        <div
+          className="relative mx-auto w-full max-w-[500px] pb-32 pt-32 [@media(max-height:40rem)]:py-0"
+          data-testid="nostr-import-passphrase-section"
+        >
+          <BackupPasswordTimeline mode="restore" />
+          <label className="sr-only" htmlFor="nostr-import-passphrase">
+            Backup password
+          </label>
+          <div className="relative z-10">
+            <Input
+              autoComplete="current-password"
+              autoCorrect="off"
+              className="h-14 rounded-2xl border-black/20 bg-white px-12 text-center font-mono text-lg text-black/80 shadow-none placeholder:text-black/55 focus-visible:ring-black/35"
+              data-testid="nostr-import-passphrase"
+              id="nostr-import-passphrase"
+              onChange={(event) => {
+                setPassphrase(event.target.value);
+                setImportError(null);
+              }}
+              placeholder="Backup password"
+              ref={passphraseInputRef}
+              spellCheck={false}
+              type={isRevealed ? "text" : "password"}
+              value={passphrase}
             />
-            <span
-              className={cn(
-                "relative text-sm font-medium text-muted-foreground transition-colors duration-[250ms] ease-out",
-                isDragging && "text-primary",
-              )}
+            <Button
+              aria-label={isRevealed ? "Hide password" : "Reveal password"}
+              className="absolute right-1 top-1/2 h-8 w-8 -translate-y-1/2 text-black/55 hover:bg-black/5 hover:text-black/80"
+              data-testid="nostr-import-passphrase-reveal-toggle"
+              disabled={isInteractionDisabled}
+              onClick={() => setIsRevealed((current) => !current)}
+              size="icon"
+              type="button"
+              variant="ghost"
             >
-              Drop a key here
-            </span>
-          </button>
-        </>
-      )}
+              {isRevealed ? (
+                <EyeOff aria-hidden="true" className="h-4 w-4" />
+              ) : (
+                <Eye aria-hidden="true" className="h-4 w-4" />
+              )}
+            </Button>
+          </div>
+        </div>
+      ) : null}
 
-      <div
-        className={cn("min-h-8", variant === "spotlight" && "mt-6 text-center")}
-        data-testid="nostr-import-feedback"
-      >
-        {previewNpub ? (
-          variant === "spotlight" ? (
-            // Spotlight uses the backup step's quiet caption language:
-            // centered, unboxed, with the npub in the shared olive key ink.
-            <div
-              className="space-y-1 text-sm"
-              data-testid="nostr-import-npub-preview"
-            >
-              <p className="flex items-center justify-center gap-1.5 text-foreground">
-                <Check aria-hidden="true" className="h-4 w-4 shrink-0" />
-                Nostr identity found
-              </p>
-              <p className="break-all font-mono text-[color:var(--buzz-onboarding-backup-ink)]">
-                {previewNpub}
-              </p>
-            </div>
-          ) : (
-            <div
-              className="flex items-start gap-2 rounded-md border border-primary/30 bg-primary/5 px-3 py-2 text-xs"
-              data-testid="nostr-import-npub-preview"
-            >
-              <Check className="mt-0.5 h-4 w-4 shrink-0 text-primary" />
-              <div className="min-w-0 space-y-0.5">
-                <p className="font-medium text-foreground">
-                  This will use this Nostr identity:
+      {!isPasswordStage || errorMessage ? (
+        <div
+          className={cn(
+            "min-h-8",
+            variant === "spotlight" && "mt-6 text-center",
+          )}
+          data-testid="nostr-import-feedback"
+        >
+          {!isPasswordStage && previewNpub ? (
+            variant === "spotlight" ? (
+              // Spotlight uses the backup step's quiet caption language:
+              // centered, unboxed, with the npub in the shared olive key ink.
+              <div
+                className="space-y-1 text-sm"
+                data-testid="nostr-import-npub-preview"
+              >
+                <p className="flex items-center justify-center gap-1.5 text-foreground">
+                  <Check aria-hidden="true" className="h-4 w-4 shrink-0" />
+                  Nostr identity found
                 </p>
-                <p className="break-all font-mono text-2xs text-muted-foreground">
+                <p className="break-all font-mono text-[color:var(--buzz-onboarding-backup-ink)]">
                   {previewNpub}
                 </p>
               </div>
-            </div>
-          )
-        ) : null}
+            ) : (
+              <div
+                className="flex items-start gap-2 rounded-md border border-primary/30 bg-primary/5 px-3 py-2 text-xs"
+                data-testid="nostr-import-npub-preview"
+              >
+                <Check className="mt-0.5 h-4 w-4 shrink-0 text-primary" />
+                <div className="min-w-0 space-y-0.5">
+                  <p className="font-medium text-foreground">
+                    This will use this Nostr identity:
+                  </p>
+                  <p className="break-all font-mono text-2xs text-muted-foreground">
+                    {previewNpub}
+                  </p>
+                </div>
+              </div>
+            )
+          ) : null}
 
-        {showInvalidHint && !errorMessage ? (
-          <p className="text-sm text-muted-foreground">
-            Waiting for a valid nsec1 key
-          </p>
-        ) : null}
+          {showInvalidHint && !errorMessage ? (
+            <p className="text-sm text-muted-foreground">
+              {isEncryptedInput
+                ? "Waiting for a complete ncryptsec backup"
+                : "Waiting for a valid nsec1 key"}
+            </p>
+          ) : null}
 
-        {errorMessage ? (
-          <p className="text-center text-sm text-destructive">{errorMessage}</p>
-        ) : null}
-      </div>
+          {errorMessage ? (
+            <p className="text-center text-sm text-destructive">
+              {errorMessage}
+            </p>
+          ) : null}
+        </div>
+      ) : null}
 
       <OnboardingFooter>
         <Button
@@ -381,15 +518,15 @@ export function NostrKeyImportForm({
         <Button
           className={
             variant === "spotlight"
-              ? "h-9 rounded-full bg-foreground/10 px-6 hover:bg-foreground/15"
+              ? ONBOARDING_SECONDARY_CTA_CLASS
               : "h-10 w-full text-muted-foreground hover:text-accent-foreground"
           }
           disabled={isImporting}
-          onClick={onBack}
+          onClick={handleBack}
           type="button"
           variant="ghost"
         >
-          {backLabel}
+          {isPasswordStage ? "Back" : backLabel}
         </Button>
       </OnboardingFooter>
     </form>
diff --git a/desktop/src/features/onboarding/ui/NsecMaskedDisplay.tsx b/desktop/src/features/onboarding/ui/NsecMaskedDisplay.tsx
index 111bdefd71..26f538da52 100644
--- a/desktop/src/features/onboarding/ui/NsecMaskedDisplay.tsx
+++ b/desktop/src/features/onboarding/ui/NsecMaskedDisplay.tsx
@@ -1,7 +1,23 @@
-import { Check, Copy, Eye, EyeOff } from "lucide-react";
+import { Check, Copy, Eye, EyeOff, MoreHorizontal } from "lucide-react";
 import * as React from "react";
 import { Button } from "@/shared/ui/button";
-import { writeTextToClipboard } from "@/shared/lib/clipboard";
+import {
+  copyTextToClipboard,
+  writeTextToClipboard,
+} from "@/shared/lib/clipboard";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/shared/ui/dropdown-menu";
+
+type NsecAction = {
+  icon?: React.ReactNode;
+  label: string;
+  onSelect: () => void;
+  testId?: string;
+};
 
 type NsecMaskedDisplayProps = {
   nsec: string;
@@ -12,6 +28,8 @@ type NsecMaskedDisplayProps = {
    * a backup (e.g. sign-out) gate on actual interaction with the key.
    */
   onKeyInteraction?: () => void;
+  /** Replaces the copy icon with an overflow menu containing Copy plus these actions. */
+  actions?: readonly NsecAction[];
 };
 
 export const ONBOARDING_KEY_FRAME_CLASS =
@@ -31,6 +49,7 @@ export function NsecMaskedDisplay({
   nsec,
   variant = "boxed",
   onKeyInteraction,
+  actions,
 }: NsecMaskedDisplayProps) {
   const [isRevealed, setIsRevealed] = React.useState(false);
   const [isCopied, setIsCopied] = React.useState(false);
@@ -58,6 +77,11 @@ export function NsecMaskedDisplay({
     copyTimerRef.current = setTimeout(() => setIsCopied(false), 2000);
   }
 
+  function handleMenuCopy() {
+    copyTextToClipboard(nsec);
+    onKeyInteraction?.();
+  }
+
   const isBare = variant === "bare";
   // Mask every character (no plaintext prefix leak), matching the real key's
   // length so toggling reveal never reflows the monospace text (no layout shift).
@@ -121,24 +145,60 @@ export function NsecMaskedDisplay({
               <Eye className={iconSize} aria-hidden="true" />
             )}
           </Button>
-          <Button
-            aria-label="Copy private key"
-            className={`${isBare ? "h-10 w-10" : "h-7 w-7"} text-muted-foreground hover:text-foreground`}
-            data-testid="nsec-copy"
-            onClick={() => void handleCopy()}
-            size="icon"
-            type="button"
-            variant="ghost"
-          >
-            {isCopied ? (
-              <Check
-                className={`${iconSize} text-primary`}
-                aria-hidden="true"
-              />
-            ) : (
-              <Copy className={iconSize} aria-hidden="true" />
-            )}
-          </Button>
+          {actions?.length ? (
+            <DropdownMenu>
+              <DropdownMenuTrigger asChild>
+                <Button
+                  aria-label="Private key actions"
+                  className={`${isBare ? "h-10 w-10" : "h-7 w-7"} text-muted-foreground hover:text-foreground`}
+                  data-testid="nsec-actions"
+                  size="icon"
+                  type="button"
+                  variant="ghost"
+                >
+                  <MoreHorizontal className={iconSize} aria-hidden="true" />
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end" className="min-w-40!">
+                <DropdownMenuItem
+                  data-testid="nsec-copy"
+                  onSelect={handleMenuCopy}
+                >
+                  <Copy aria-hidden="true" />
+                  Copy
+                </DropdownMenuItem>
+                {actions.map((action) => (
+                  <DropdownMenuItem
+                    data-testid={action.testId}
+                    key={action.label}
+                    onSelect={action.onSelect}
+                  >
+                    {action.icon}
+                    {action.label}
+                  </DropdownMenuItem>
+                ))}
+              </DropdownMenuContent>
+            </DropdownMenu>
+          ) : (
+            <Button
+              aria-label="Copy private key"
+              className={`${isBare ? "h-10 w-10" : "h-7 w-7"} text-muted-foreground hover:text-foreground`}
+              data-testid="nsec-copy"
+              onClick={() => void handleCopy()}
+              size="icon"
+              type="button"
+              variant="ghost"
+            >
+              {isCopied ? (
+                <Check
+                  className={`${iconSize} text-primary`}
+                  aria-hidden="true"
+                />
+              ) : (
+                <Copy className={iconSize} aria-hidden="true" />
+              )}
+            </Button>
+          )}
         </div>
       </div>
     </div>
diff --git a/desktop/src/features/onboarding/ui/OnboardingChrome.tsx b/desktop/src/features/onboarding/ui/OnboardingChrome.tsx
index 936313bce0..7a52ae4999 100644
--- a/desktop/src/features/onboarding/ui/OnboardingChrome.tsx
+++ b/desktop/src/features/onboarding/ui/OnboardingChrome.tsx
@@ -2,8 +2,8 @@ import { BuzzMark } from "@/shared/ui/buzz-logo/BuzzMark";
 
 /**
  * Positions in the first-launch flow: landing, identity/key, harness setup,
- * default config, community choice, community profile, meet the team. Used as
- * the default pagination length when a flow doesn't pass an explicit total.
+ * default config, community choice, community profile, meet the team. Password
+ * backup is an optional subview of identity/key, not another position.
  */
 export const TOTAL_ONBOARDING_PAGES = 7;
 
@@ -17,6 +17,9 @@ const ONBOARDING_CTA_SHAPE = "h-[2.375rem] rounded-full px-6";
  */
 export const ONBOARDING_PRIMARY_CTA_CLASS = `${ONBOARDING_CTA_SHAPE} text-[var(--buzz-onboarding-cta-label)]`;
 
+/** Inverted primary action used only on dark backup-security surfaces. */
+export const ONBOARDING_SECURITY_PRIMARY_CTA_CLASS = `${ONBOARDING_CTA_SHAPE} bg-white text-black/80 hover:bg-white/90 hover:text-black`;
+
 /**
  * Primary-CTA styling for the landing screen only: the shared pill with the
  * chartreuse label (`--buzz-welcome-chartreuse`). The blue label is reserved
@@ -24,6 +27,10 @@ export const ONBOARDING_PRIMARY_CTA_CLASS = `${ONBOARDING_CTA_SHAPE} text-[var(-
  */
 export const ONBOARDING_LANDING_CTA_CLASS = `${ONBOARDING_CTA_SHAPE} text-[var(--buzz-welcome-chartreuse)]`;
 
+/** Shared quiet pill for secondary actions throughout onboarding. */
+export const ONBOARDING_SECONDARY_CTA_CLASS =
+  "h-9 rounded-full bg-foreground/10 px-6 text-foreground hover:bg-foreground/15 hover:text-foreground";
+
 /**
  * Icon-control styling for onboarding surfaces that sit on the textured card:
  * olive backup ink (`--buzz-onboarding-backup-ink`) with a plain
@@ -34,6 +41,10 @@ export const ONBOARDING_LANDING_CTA_CLASS = `${ONBOARDING_CTA_SHAPE} text-[var(-
 export const ONBOARDING_INK_ICON_CLASS =
   "text-[color:var(--buzz-onboarding-backup-ink)] hover:bg-transparent hover:text-foreground";
 
+/** Icon controls on the dark noisy backup surfaces stay visually unboxed. */
+export const ONBOARDING_SECURITY_ICON_CLASS =
+  "text-muted-foreground hover:bg-transparent hover:text-foreground";
+
 /**
  * Shared onboarding chrome shown on every page after the landing screen: a
  * static Buzz mark pinned to the top-left, and a centered pagination track that
diff --git a/desktop/src/features/onboarding/ui/OnboardingFlow.tsx b/desktop/src/features/onboarding/ui/OnboardingFlow.tsx
index 01a226e3de..a3653f750f 100644
--- a/desktop/src/features/onboarding/ui/OnboardingFlow.tsx
+++ b/desktop/src/features/onboarding/ui/OnboardingFlow.tsx
@@ -388,8 +388,8 @@ export function OnboardingFlow({
   // key's relay profile reseeds the steps, and a key that already finished
   // onboarding on this machine skips straight into the app.
   const importExistingKey = React.useCallback(
-    async (nsec: string) => {
-      const identity = await importIdentity(nsec);
+    async (nsec: string, password?: string) => {
+      const identity = await importIdentity(nsec, password);
       relayClient.disconnect();
       queryClient.setQueryData(["identity"], identity);
       queryClient.removeQueries({ queryKey: profileQueryKey });
diff --git a/desktop/src/features/onboarding/ui/OnboardingSlideTransition.tsx b/desktop/src/features/onboarding/ui/OnboardingSlideTransition.tsx
index 82d9a0213c..ba5d8b2c87 100644
--- a/desktop/src/features/onboarding/ui/OnboardingSlideTransition.tsx
+++ b/desktop/src/features/onboarding/ui/OnboardingSlideTransition.tsx
@@ -14,6 +14,7 @@ export type OnboardingTransitionDirection = "forward" | "backward";
 export type OnboardingTransitionEffect =
   | "fade"
   | "line-slide"
+  | "mask-reveal-down"
   | "mask-reveal-up"
   | "none";
 
diff --git a/desktop/src/features/onboarding/ui/RuntimeIcon.tsx b/desktop/src/features/onboarding/ui/RuntimeIcon.tsx
index f9c201d115..5b247c31f7 100644
--- a/desktop/src/features/onboarding/ui/RuntimeIcon.tsx
+++ b/desktop/src/features/onboarding/ui/RuntimeIcon.tsx
@@ -17,6 +17,7 @@ const RUNTIME_LOGOS: Record<string, string> = {
 // Public-path logos for bundled presets. Served from /harness-logos/ at runtime.
 // Keys match the preset `id` values emitted by the backend PRESET_HARNESSES.
 export const PRESET_LOGOS: Record<string, string> = {
+  devin: "/harness-logos/devin.svg",
   omp: "/harness-logos/omp.svg",
   grok: "/harness-logos/grok.svg",
   opencode: "/harness-logos/opencode.svg",
diff --git a/desktop/src/features/onboarding/ui/SetupStep.tsx b/desktop/src/features/onboarding/ui/SetupStep.tsx
index 843206aa70..911ddaf362 100644
--- a/desktop/src/features/onboarding/ui/SetupStep.tsx
+++ b/desktop/src/features/onboarding/ui/SetupStep.tsx
@@ -8,6 +8,7 @@ import {
   useConnectAcpRuntimeMutation,
   useInstallAcpRuntimeMutation,
 } from "@/features/agents/hooks";
+import { useInstallOutputLine } from "@/features/agents/lib/useInstallOutputLine";
 import { describeResolvedCommand } from "@/features/agents/ui/agentUi";
 import type { AcpAuthMethod, AcpRuntimeCatalogEntry } from "@/shared/api/types";
 import { getInstallErrorMessage } from "@/shared/lib/installError";
@@ -483,6 +484,7 @@ function RuntimeCard({
   const installMutation = useInstallAcpRuntimeMutation();
   const installError = installResults[runtime.id]?.error ?? null;
   const isInstalling = installMutation.isPending;
+  const installOutputLine = useInstallOutputLine(runtime.id, isInstalling);
   const isAvailable = runtime.availability === "available";
   const isReady = runtimeIsReadyForOnboarding(runtime);
 
@@ -499,7 +501,7 @@ function RuntimeCard({
           [runtime.id]: result.success
             ? { error: null, success: true }
             : {
-                error: getInstallErrorMessage(result.steps),
+                error: getInstallErrorMessage(result),
                 success: false,
               },
         }));
@@ -542,7 +544,18 @@ function RuntimeCard({
           onInstall={handleInstall}
           runtime={runtime}
         />
-        {!isAvailable && runtimeDetailText(runtime) ? (
+        {isInstalling && installOutputLine ? (
+          // Takes the detail text's slot rather than adding a row: the card is
+          // fixed-height, and during an install the live line is the more
+          // useful of the two.
+          <p
+            aria-live="polite"
+            className="max-w-[13rem] truncate font-mono text-2xs leading-4 text-muted-foreground"
+            data-testid={`onboarding-runtime-install-output-${runtime.id}`}
+          >
+            {installOutputLine}
+          </p>
+        ) : !isAvailable && runtimeDetailText(runtime) ? (
           <p
             aria-hidden={installError ? "true" : undefined}
             className={cn(
@@ -685,25 +698,28 @@ function SetupStepContent({
       />
 
       <OnboardingFooter>
-        <Button
-          className={`${ONBOARDING_PRIMARY_CTA_CLASS} text-sm`}
-          data-testid="onboarding-setup-next"
-          disabled={readyRuntimeIds.length === 0}
-          onClick={() => actions.next(readyRuntimeIds)}
-          type="button"
-        >
-          Next
-        </Button>
-
-        <Button
-          className="h-9 rounded-full bg-foreground/10 px-6 text-sm hover:bg-foreground/15"
-          data-testid="onboarding-setup-skip"
-          onClick={() => actions.next([])}
-          type="button"
-          variant="ghost"
-        >
-          Skip for now
-        </Button>
+        {/* Relative row keeps the primary CTA truly centered while Skip
+            hangs off its right edge without shifting the center. */}
+        <div className="relative flex items-center justify-center">
+          <Button
+            className={`${ONBOARDING_PRIMARY_CTA_CLASS} text-sm`}
+            data-testid="onboarding-setup-next"
+            disabled={readyRuntimeIds.length === 0}
+            onClick={() => actions.next(readyRuntimeIds)}
+            type="button"
+          >
+            Next
+          </Button>
+          <Button
+            className="absolute left-full ml-3 h-9 animate-in whitespace-nowrap rounded-full px-6 text-sm fade-in fill-mode-backwards [animation-delay:1000ms] animation-duration-[500ms] hover:bg-foreground/10 motion-reduce:animate-none"
+            data-testid="onboarding-setup-skip"
+            onClick={() => actions.next([])}
+            type="button"
+            variant="ghost"
+          >
+            Skip for now
+          </Button>
+        </div>
 
         <Button
           className="h-9 rounded-full bg-foreground/10 px-6 text-sm hover:bg-foreground/15"
diff --git a/desktop/src/features/onboarding/ui/onboardingFlowSteps.test.mjs b/desktop/src/features/onboarding/ui/onboardingFlowSteps.test.mjs
index fa92214312..622db610aa 100644
--- a/desktop/src/features/onboarding/ui/onboardingFlowSteps.test.mjs
+++ b/desktop/src/features/onboarding/ui/onboardingFlowSteps.test.mjs
@@ -53,29 +53,11 @@ test("currentStep_falls_back_to_1_for_pages_outside_the_step_list", () => {
 });
 
 // ---------------------------------------------------------------------------
-// BackupStep gating: backupNextDisabled() pure helper
+// BackupStep gating: saving a password-protected backup is recommended, not required
 // ---------------------------------------------------------------------------
 
-test("backup_next_disabled_while_loading", () => {
-  // During a slow keychain read, Next must be blocked — user cannot race past
-  // the key display before it is shown.
-  assert.equal(backupNextDisabled({ isLoading: true, loadError: null }), true);
-});
-
-test("backup_next_disabled_on_load_error", () => {
-  // Error state: only the explicit "Skip for now" ghost advances; Next blocked.
-  assert.equal(
-    backupNextDisabled({ isLoading: false, loadError: "IPC error" }),
-    true,
-  );
-});
-
-test("backup_next_enabled_after_clean_load", () => {
-  // Key shown (or backend cleanly returned none) — user may proceed.
-  assert.equal(
-    backupNextDisabled({ isLoading: false, loadError: null }),
-    false,
-  );
+test("backup_next_is_always_enabled", () => {
+  assert.equal(backupNextDisabled(), false);
 });
 
 // ---------------------------------------------------------------------------
diff --git a/desktop/src/features/onboarding/ui/presetLogos.test.mjs b/desktop/src/features/onboarding/ui/presetLogos.test.mjs
index 0ff2193155..7a5df620da 100644
--- a/desktop/src/features/onboarding/ui/presetLogos.test.mjs
+++ b/desktop/src/features/onboarding/ui/presetLogos.test.mjs
@@ -24,15 +24,15 @@ const desktopRoot = path.resolve(
   "../../../..",
 );
 
-const discoveryRs = readFileSync(
-  path.join(desktopRoot, "src-tauri/src/managed_agents/discovery.rs"),
+const presetsRs = readFileSync(
+  path.join(desktopRoot, "src-tauri/src/managed_agents/discovery/presets.rs"),
   "utf8",
 );
 
-const presetBlock = discoveryRs.match(
+const presetBlock = presetsRs.match(
   /const PRESET_HARNESSES: &\[PresetHarness\] = &\[([\s\S]*?)\n\];/,
 );
-assert.ok(presetBlock, "could not locate PRESET_HARNESSES in discovery.rs");
+assert.ok(presetBlock, "could not locate PRESET_HARNESSES in presets.rs");
 
 const presetIds = [...presetBlock[1].matchAll(/^\s{8}id: "([^"]+)",$/gm)].map(
   (match) => match[1],
diff --git a/desktop/src/features/presence/hooks.ts b/desktop/src/features/presence/hooks.ts
index 5ba8683693..04936241df 100644
--- a/desktop/src/features/presence/hooks.ts
+++ b/desktop/src/features/presence/hooks.ts
@@ -11,14 +11,14 @@ import {
   mergePresenceUpdate,
   parseLivePresenceEvent,
   presenceQueryWantsPubkey,
+  PRESENCE_HEARTBEAT_INTERVAL_MS,
+  PRESENCE_TTL_SECONDS,
   resolveAutomaticPresenceStatus,
 } from "@/features/presence/lib/presence";
 import type { PresenceLookup, PresenceStatus } from "@/shared/api/types";
 
-const PRESENCE_HEARTBEAT_INTERVAL_MS = 30_000;
 const PRESENCE_STATUS_TICK_INTERVAL_MS = 30_000;
 const PRESENCE_ACTIVITY_THROTTLE_MS = 1_000;
-const PRESENCE_TTL_SECONDS = 90;
 const PRESENCE_PREFERENCE_STORAGE_KEY = "buzz-presence-preference";
 
 type PresencePreference = "auto" | "away" | "offline" | null;
diff --git a/desktop/src/features/presence/lib/presence.test.mjs b/desktop/src/features/presence/lib/presence.test.mjs
index c202dcb776..90a6ac524b 100644
--- a/desktop/src/features/presence/lib/presence.test.mjs
+++ b/desktop/src/features/presence/lib/presence.test.mjs
@@ -5,7 +5,9 @@ import {
   mergePresenceUpdate,
   parseLivePresenceEvent,
   presenceQueryWantsPubkey,
+  PRESENCE_HEARTBEAT_INTERVAL_MS,
   PRESENCE_IDLE_TIMEOUT_MS,
+  PRESENCE_TTL_SECONDS,
   resolveAutomaticPresenceStatus,
 } from "./presence.ts";
 
@@ -13,6 +15,15 @@ const WILL = "8e39cba681211b3782d0e4483e9343719b9b7be66515252da5491f26421896b1";
 const OTHER =
   "44b8e82baaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
 
+test("presence heartbeat is one minute with a three-window TTL", () => {
+  assert.equal(PRESENCE_HEARTBEAT_INTERVAL_MS, 60_000);
+  assert.equal(PRESENCE_TTL_SECONDS, 180);
+  assert.equal(
+    PRESENCE_TTL_SECONDS,
+    3 * (PRESENCE_HEARTBEAT_INTERVAL_MS / 1000),
+  );
+});
+
 test("merge adds an absent pubkey going online (the core bug)", () => {
   const old = {};
   const next = mergePresenceUpdate(old, WILL, "online");
diff --git a/desktop/src/features/presence/lib/presence.ts b/desktop/src/features/presence/lib/presence.ts
index 34ac4fc353..5b1fdc21c5 100644
--- a/desktop/src/features/presence/lib/presence.ts
+++ b/desktop/src/features/presence/lib/presence.ts
@@ -36,6 +36,12 @@ export function mergePresenceUpdate(
   return { ...old, [pubkey]: status };
 }
 
+// Keep the local optimistic cache and relay expiry at three heartbeat windows.
+// The relay owns the authoritative TTL; deploy its TTL increase before shipping
+// a desktop build with a slower heartbeat.
+export const PRESENCE_HEARTBEAT_INTERVAL_MS = 60_000;
+export const PRESENCE_TTL_SECONDS = 3 * (PRESENCE_HEARTBEAT_INTERVAL_MS / 1000);
+
 // Away means "human not at the machine" (Slack/Discord semantics), never
 // "Buzz is not the focused window". OS-wide idle is authoritative when the
 // platform exposes it; otherwise fall back to in-app activity.
diff --git a/desktop/src/features/profile/ui/SelectedRecipientChip.tsx b/desktop/src/features/profile/ui/SelectedRecipientChip.tsx
index 18bf6d3b8b..bfc2f43167 100644
--- a/desktop/src/features/profile/ui/SelectedRecipientChip.tsx
+++ b/desktop/src/features/profile/ui/SelectedRecipientChip.tsx
@@ -46,7 +46,7 @@ export function SelectedRecipientChip({
   user: UserSearchResult;
 }) {
   return (
-    <div className="inline-flex h-7 max-w-56 items-center gap-1.5 rounded-full bg-muted px-1.5 pr-2.5 text-sm transition-colors hover:bg-muted/80">
+    <div className="inline-flex h-7 max-w-56 items-center gap-1.5 rounded-full bg-muted px-1 pr-2.5 text-sm transition-colors hover:bg-muted/80">
       <button
         aria-label={`Remove ${label}`}
         className={cn(
diff --git a/desktop/src/features/profile/ui/UserProfilePanel.tsx b/desktop/src/features/profile/ui/UserProfilePanel.tsx
index c1f713d230..af30728d6a 100644
--- a/desktop/src/features/profile/ui/UserProfilePanel.tsx
+++ b/desktop/src/features/profile/ui/UserProfilePanel.tsx
@@ -71,8 +71,10 @@ import { UserProfileAgentSettingsMenuSlot } from "@/features/profile/ui/UserProf
 import { useProfileAgentDeletion } from "@/features/profile/ui/UserProfilePanelDeletion";
 import { useProfileFieldBuckets } from "@/features/profile/ui/UserProfilePanelFields";
 import { submitProfilePersonaDialog } from "@/features/profile/ui/UserProfilePanelPersonaSubmit";
-import { UserProfilePersonaDialogs } from "@/features/profile/ui/UserProfilePersonaDialogs";
-import { UserProfileSnapshotExportDialog } from "@/features/profile/ui/UserProfileSnapshotExportDialog";
+import {
+  type CardMintTarget,
+  UserProfilePersonaDialogs,
+} from "@/features/profile/ui/UserProfilePersonaDialogs";
 import {
   deriveProfileChannels,
   type ProfilePanelTab,
@@ -181,6 +183,8 @@ export function UserProfilePanel({
     React.useState<AgentPersona | null>(null);
   const [personaToExportSnapshot, setPersonaToExportSnapshot] =
     React.useState<AgentPersona | null>(null);
+  const [cardMintTarget, setCardMintTarget] =
+    React.useState<CardMintTarget | null>(null);
 
   const personasQuery = usePersonasQuery();
   const managedAgentsQuery = useManagedAgentsQuery({ enabled: true });
@@ -824,6 +828,19 @@ export function UserProfilePanel({
           onOpenInstructions={() => setView("instructions")}
           onTabChange={setTab}
           onOpenDm={onOpenDm}
+          onCreateCard={
+            canManagePersona && resolvedPersona
+              ? () =>
+                  setCardMintTarget({
+                    // Prefer the live instance pubkey; fall back to the
+                    // persona/definition id (same resolution as export).
+                    id: managedAgent?.pubkey ?? resolvedPersona.id,
+                    name: resolvedPersona.displayName,
+                    // Locking needs an instance keypair to encrypt to.
+                    canLock: Boolean(managedAgent?.pubkey),
+                  })
+              : undefined
+          }
           presenceStatus={presenceStatus}
           profile={profile}
           pubkey={effectivePubkey}
@@ -921,6 +938,7 @@ export function UserProfilePanel({
   const personaDialogs = (
     <>
       <UserProfilePersonaDialogs
+        cardMintTarget={cardMintTarget}
         createError={
           createPersonaMutation.error instanceof Error
             ? createPersonaMutation.error
@@ -933,8 +951,11 @@ export function UserProfilePanel({
           updateManagedAgentMutation.isPending ||
           createAgentMutation.isPending
         }
+        linkedAgentPubkey={managedAgent?.pubkey ?? null}
         personaDialogState={personaDialogState}
         personaToDelete={personaToDelete}
+        personaToExportSnapshot={personaToExportSnapshot}
+        resolvedPersona={resolvedPersona}
         runtimes={acpRuntimesQuery.data ?? []}
         runtimesLoading={acpRuntimesQuery.isLoading}
         updateError={
@@ -942,22 +963,16 @@ export function UserProfilePanel({
             ? updatePersonaMutation.error
             : null
         }
+        onCloseCardMint={() => setCardMintTarget(null)}
         onCloseDelete={() => setPersonaToDelete(null)}
         onCloseDialog={() => setPersonaDialogState(null)}
+        onCloseExportSnapshot={() => setPersonaToExportSnapshot(null)}
         onConfirmDelete={(selectedPersona) => {
           void handleConfirmDeletePersona(selectedPersona);
         }}
+        onExportSnapshot={setPersonaToExportSnapshot}
         onSubmit={handleSubmitPersona}
       />
-      {personaToExportSnapshot ? (
-        <UserProfileSnapshotExportDialog
-          linkedAgentPubkey={managedAgent?.pubkey ?? null}
-          onOpenChange={(open) => {
-            if (!open) setPersonaToExportSnapshot(null);
-          }}
-          persona={personaToExportSnapshot}
-        />
-      ) : null}
     </>
   );
   return (
diff --git a/desktop/src/features/profile/ui/UserProfilePanelFields.tsx b/desktop/src/features/profile/ui/UserProfilePanelFields.tsx
index 62f4123c95..cf88919ce6 100644
--- a/desktop/src/features/profile/ui/UserProfilePanelFields.tsx
+++ b/desktop/src/features/profile/ui/UserProfilePanelFields.tsx
@@ -56,7 +56,7 @@ const AGENT_INFO_LABELS = new Set([
 const AGENT_SETTINGS_LABELS = new Set([
   "Runtime",
   "Agent profile",
-  "Respond to",
+  "Who can send instructions",
   "ACP command",
   "MCP command",
   "Start on launch",
@@ -246,9 +246,13 @@ export function buildOwnerFields({
   const fields: ProfileField[] = [];
   const respondTo = managedAgent?.respondTo ?? relayAgent?.respondTo ?? null;
   const respondToDisplayValue = respondTo
-    ? respondTo === "owner-only" && ownerDisplayName
+    ? respondTo === "owner-only"
       ? ownerDisplayName
-      : respondTo.replace(/-/g, " ")
+        ? `Only ${ownerDisplayName} (owner)`
+        : "Only the owner"
+      : respondTo === "allowlist"
+        ? "Selected people"
+        : "Anyone"
     : null;
 
   const ownerClickable = Boolean(onOpenProfile && ownerProfilePubkey);
@@ -386,7 +390,7 @@ export function buildOwnerFields({
     fields.push({
       displayValue: respondToDisplayValue,
       icon: Ear,
-      label: "Respond to",
+      label: "Who can send instructions",
       testId: "user-profile-respond-to",
     });
   }
diff --git a/desktop/src/features/profile/ui/UserProfilePanelSections.tsx b/desktop/src/features/profile/ui/UserProfilePanelSections.tsx
index 4514b62d95..057376a38c 100644
--- a/desktop/src/features/profile/ui/UserProfilePanelSections.tsx
+++ b/desktop/src/features/profile/ui/UserProfilePanelSections.tsx
@@ -1,19 +1,11 @@
 import * as React from "react";
-import type { LucideIcon } from "lucide-react";
 import {
   ArrowUpRight,
   ChevronDown,
   ChevronUp,
   CircleAlert,
-  MessageSquare,
-  Pencil,
-  Play,
-  RefreshCw,
-  Square,
-  UserMinus,
   UserPlus,
 } from "lucide-react";
-import { toast } from "sonner";
 
 import { MemorySection } from "@/features/agent-memory/ui/MemorySection";
 import { useAgentWorking } from "@/features/agents/agentWorkingSignal";
@@ -44,19 +36,20 @@ import {
   STATUS_DOT_MASK_CURVE,
 } from "@/features/profile/ui/MaskedAvatarBadgeFrame";
 import { ProfileAvatar } from "@/features/profile/ui/ProfileAvatar";
+import {
+  ProfilePersonaPrimaryActions,
+  ProfilePrimaryActions,
+} from "@/features/profile/ui/UserProfilePrimaryActions";
 import { StatusEmoji } from "@/features/user-status/ui/StatusEmoji";
 import { BotIdenticon } from "@/features/messages/ui/BotIdenticon";
 import type { ManagedAgent, RelayAgent } from "@/shared/api/types";
-import { Spinner } from "@/shared/ui/spinner";
 import type {
   ProfileChannelLink,
   ProfilePanelTab,
 } from "@/features/profile/ui/UserProfilePanelUtils";
-import { useFeatureEnabled } from "@/shared/features";
 import { cn } from "@/shared/lib/cn";
 import { Alert, AlertDescription, AlertTitle } from "@/shared/ui/alert";
 import { Badge } from "@/shared/ui/badge";
-import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
 
 export { AgentInstructionsFocusedView } from "@/features/profile/ui/UserProfilePanelAgentDetails";
 
@@ -105,6 +98,8 @@ export type ProfileSummaryViewProps = {
   onOpenInstructions: () => void;
   onTabChange: (tab: ProfilePanelTab, options?: { replace?: boolean }) => void;
   onOpenDm?: (pubkeys: string[]) => Promise<void> | void;
+  /** Mint an agent trading card. Present only for owner-managed personas. */
+  onCreateCard?: () => void;
   presenceStatus: "online" | "away" | "offline" | undefined;
   profile: ReturnType<typeof useUserProfileQuery>["data"];
   pubkey: string | null;
@@ -218,6 +213,7 @@ export function ProfileSummaryView({
   onOpenInstructions,
   onTabChange,
   onOpenDm,
+  onCreateCard,
   presenceStatus,
   profile,
   pubkey,
@@ -349,6 +345,7 @@ export function ProfileSummaryView({
         <ProfilePersonaPrimaryActions
           canEditAgent={canEditAgent}
           disabled={isAgentActionPending}
+          onCreateCard={onCreateCard}
           onEditAgent={handleEditAgent}
           onStartAgent={handleInstantiateAgent}
         />
@@ -356,6 +353,7 @@ export function ProfileSummaryView({
         <ProfilePrimaryActions
           canEditAgent={canEditAgent}
           followMutation={followMutation}
+          onCreateCard={onCreateCard}
           onEditAgent={handleEditAgent}
           agentActionDisabled={isAgentActionPending}
           agentActionLabel={
@@ -629,181 +627,6 @@ function ProfileHeroDescription({ about }: { about: string }) {
   );
 }
 
-// ── Primary actions ──────────────────────────────────────────────────────────
-
-function ProfilePrimaryActions({
-  agentActionDisabled,
-  agentActionLabel,
-  agentActionLive,
-  canEditAgent,
-  followMutation,
-  isFollowing,
-  messagePending,
-  onAgentPrimaryAction,
-  onAgentRestart,
-  onEditAgent,
-  onMessage,
-  pubkey,
-  unfollowMutation,
-}: {
-  agentActionDisabled?: boolean;
-  agentActionLabel?: string;
-  agentActionLive?: boolean;
-  canEditAgent: boolean;
-  followMutation: ReturnType<typeof useFollowMutation>;
-  isFollowing: boolean;
-  messagePending?: boolean;
-  onAgentPrimaryAction?: () => void;
-  onAgentRestart?: () => void;
-  onEditAgent: () => void;
-  onMessage?: () => void;
-  pubkey: string;
-  unfollowMutation: ReturnType<typeof useUnfollowMutation>;
-}) {
-  const showFollowAction = useFeatureEnabled("pulse");
-  const followToggleMutation = isFollowing ? unfollowMutation : followMutation;
-
-  const handleFollowClick = () => {
-    followToggleMutation.mutate(pubkey, {
-      onError: (error) =>
-        toast.error(
-          `${isFollowing ? "Unfollow" : "Follow"} failed: ${error.message}`,
-        ),
-    });
-  };
-
-  return (
-    <div className="flex items-center justify-center gap-8">
-      {showFollowAction ? (
-        <ProfileQuickAction
-          active={isFollowing}
-          disabled={followToggleMutation.isPending}
-          icon={isFollowing ? UserMinus : UserPlus}
-          label={isFollowing ? "Unfollow" : "Follow"}
-          onClick={handleFollowClick}
-        />
-      ) : null}
-      {onMessage ? (
-        <ProfileQuickAction
-          disabled={messagePending}
-          icon={MessageSquare}
-          isLoading={messagePending}
-          label="Message"
-          onClick={onMessage}
-          testId="user-profile-message"
-        />
-      ) : null}
-      {canEditAgent ? (
-        <ProfileQuickAction
-          icon={Pencil}
-          label="Edit"
-          onClick={onEditAgent}
-          testId="user-profile-edit-agent"
-        />
-      ) : null}
-      {onAgentPrimaryAction && agentActionLabel ? (
-        <ProfileQuickAction
-          active={agentActionLive}
-          disabled={agentActionDisabled}
-          icon={agentActionLive ? Square : Play}
-          label={agentActionLabel}
-          onClick={onAgentPrimaryAction}
-          testId="user-profile-agent-primary-action"
-        />
-      ) : null}
-      {onAgentRestart ? (
-        <ProfileQuickAction
-          disabled={agentActionDisabled}
-          icon={RefreshCw}
-          label="Restart"
-          onClick={onAgentRestart}
-          testId="user-profile-agent-restart"
-        />
-      ) : null}
-    </div>
-  );
-}
-
-function ProfilePersonaPrimaryActions({
-  canEditAgent,
-  disabled,
-  onEditAgent,
-  onStartAgent,
-}: {
-  canEditAgent: boolean;
-  disabled: boolean;
-  onEditAgent: () => void;
-  onStartAgent: () => void;
-}) {
-  return (
-    <div className="flex items-center justify-center gap-8">
-      <ProfileQuickAction
-        disabled={disabled}
-        icon={Play}
-        label="Start agent"
-        onClick={onStartAgent}
-        testId="user-profile-start-agent"
-      />
-      {canEditAgent ? (
-        <ProfileQuickAction
-          disabled={disabled}
-          icon={Pencil}
-          label="Edit"
-          onClick={onEditAgent}
-          testId="user-profile-edit-agent"
-        />
-      ) : null}
-    </div>
-  );
-}
-
-function ProfileQuickAction({
-  active,
-  disabled,
-  icon: Icon,
-  isLoading,
-  label,
-  onClick,
-  testId,
-}: {
-  active?: boolean;
-  disabled?: boolean;
-  icon: LucideIcon;
-  isLoading?: boolean;
-  label: string;
-  onClick: () => void;
-  testId?: string;
-}) {
-  return (
-    <Tooltip>
-      <TooltipTrigger asChild>
-        <button
-          aria-label={label}
-          className={cn(
-            "flex h-12 w-12 items-center justify-center rounded-full transition-colors disabled:cursor-not-allowed disabled:opacity-50",
-            active
-              ? "bg-foreground text-background hover:bg-foreground/90"
-              : "bg-muted/60 text-foreground hover:bg-muted/80",
-          )}
-          data-testid={testId}
-          disabled={disabled}
-          onClick={onClick}
-          type="button"
-        >
-          {isLoading ? (
-            <Spinner aria-hidden="true" className="h-4 w-4 border-2" />
-          ) : (
-            <Icon className="h-4 w-4" />
-          )}
-        </button>
-      </TooltipTrigger>
-      <TooltipContent align="center" side="top">
-        {label}
-      </TooltipContent>
-    </Tooltip>
-  );
-}
-
 // ── Focused views ────────────────────────────────────────────────────────────
 
 export function MemoryFocusedView({
diff --git a/desktop/src/features/profile/ui/UserProfilePersonaDialogs.tsx b/desktop/src/features/profile/ui/UserProfilePersonaDialogs.tsx
index 5e468b5320..2de2e2f716 100644
--- a/desktop/src/features/profile/ui/UserProfilePersonaDialogs.tsx
+++ b/desktop/src/features/profile/ui/UserProfilePersonaDialogs.tsx
@@ -4,36 +4,59 @@ import type {
   CreatePersonaInput,
   UpdatePersonaInput,
 } from "@/shared/api/types";
+import { AgentCardMintDialog } from "@/features/agents/ui/AgentCardMintDialog";
 import { PersonaDeleteDialog } from "@/features/agents/ui/PersonaDeleteDialog";
 import { AgentDialog } from "@/features/agents/ui/AgentDialog";
 import type { PersonaDialogState } from "@/features/agents/ui/personaDialogState";
+import { UserProfileSnapshotExportDialog } from "@/features/profile/ui/UserProfileSnapshotExportDialog";
+
+/** Agent selected for card minting. */
+export type CardMintTarget = {
+  id: string;
+  name: string;
+  canLock: boolean;
+};
 
 export function UserProfilePersonaDialogs({
+  cardMintTarget,
   createError,
   instanceCount,
   isPending,
+  linkedAgentPubkey,
   personaDialogState,
   personaToDelete,
+  personaToExportSnapshot,
+  resolvedPersona,
   runtimes,
   runtimesLoading,
   updateError,
+  onCloseCardMint,
   onCloseDelete,
   onCloseDialog,
+  onCloseExportSnapshot,
   onConfirmDelete,
+  onExportSnapshot,
   onSubmit,
 }: {
+  cardMintTarget: CardMintTarget | null;
   createError: Error | null;
   /** Number of managed-agent instances backed by the persona being deleted. */
   instanceCount: number;
   isPending: boolean;
+  linkedAgentPubkey: string | null;
   personaDialogState: PersonaDialogState | null;
   personaToDelete: AgentPersona | null;
+  personaToExportSnapshot: AgentPersona | null;
+  resolvedPersona: AgentPersona | undefined;
   runtimes: AcpRuntimeCatalogEntry[];
   runtimesLoading: boolean;
   updateError: Error | null;
+  onCloseCardMint: () => void;
   onCloseDelete: () => void;
   onCloseDialog: () => void;
+  onCloseExportSnapshot: () => void;
   onConfirmDelete: (persona: AgentPersona) => void;
+  onExportSnapshot: (persona: AgentPersona) => void;
   onSubmit: (input: CreatePersonaInput | UpdatePersonaInput) => Promise<void>;
 }) {
   return (
@@ -67,6 +90,35 @@ export function UserProfilePersonaDialogs({
         open={personaToDelete !== null}
         persona={personaToDelete}
       />
+      {personaToExportSnapshot ? (
+        <UserProfileSnapshotExportDialog
+          linkedAgentPubkey={linkedAgentPubkey}
+          onOpenChange={(open) => {
+            if (!open) onCloseExportSnapshot();
+          }}
+          persona={personaToExportSnapshot}
+        />
+      ) : null}
+      {cardMintTarget ? (
+        <AgentCardMintDialog
+          agentId={cardMintTarget.id}
+          agentName={cardMintTarget.name}
+          canLock={cardMintTarget.canLock}
+          onExportInstead={
+            resolvedPersona
+              ? () => {
+                  // Free path: swap the mint dialog for the ordinary
+                  // snapshot export flow (same importable agent, no spend).
+                  onCloseCardMint();
+                  onExportSnapshot(resolvedPersona);
+                }
+              : undefined
+          }
+          onOpenChange={(open) => {
+            if (!open) onCloseCardMint();
+          }}
+        />
+      ) : null}
     </>
   );
 }
diff --git a/desktop/src/features/profile/ui/UserProfilePopover.tsx b/desktop/src/features/profile/ui/UserProfilePopover.tsx
index f2739088a6..da51ab1b88 100644
--- a/desktop/src/features/profile/ui/UserProfilePopover.tsx
+++ b/desktop/src/features/profile/ui/UserProfilePopover.tsx
@@ -260,11 +260,18 @@ export function UserProfilePopover({
   const selfProfileQuery = useProfileQuery(open && showProfileActions);
   const isCurrentUserOwner = ownsAuthorAgent(profile, currentPubkey);
   const viewerIsOwner = isCurrentUserOwner || isOwner === true;
+  const showHuddleAction =
+    showHumanProfileActions ||
+    (showProfileActions &&
+      isBotProfile &&
+      viewerIsOwner &&
+      !isAgentClassificationPending);
   const showMessageAction =
     showProfileActions &&
     !isAgentClassificationPending &&
     (!isBotProfile || viewerIsOwner);
-  const showAnyProfileActions = showHumanProfileActions || showMessageAction;
+  const showAnyProfileActions =
+    showHumanProfileActions || showMessageAction || showHuddleAction;
   const canViewActivity =
     isBotProfile && viewerIsOwner && canOpenAgentActivity(pubkey);
   const presenceStatus = presenceQuery.data?.[pubkey.toLowerCase()];
@@ -356,7 +363,7 @@ export function UserProfilePopover({
   const handleHuddle = React.useCallback(async () => {
     if (
       !showProfileActions ||
-      !showHumanProfileActions ||
+      !showHuddleAction ||
       pendingAction !== null ||
       isStartingHuddle
     ) {
@@ -369,7 +376,7 @@ export function UserProfilePopover({
     try {
       const dm = await openDmMutation.mutateAsync({ pubkeys: [pubkey] });
       await goChannel(dm.id);
-      await startHuddle(dm.id, []);
+      await startHuddle(dm.id, isBotProfile ? [pubkey] : []);
       await queryClient.invalidateQueries({ queryKey: channelsQueryKey });
       if (isMountedRef.current) {
         setOpen(false);
@@ -389,7 +396,8 @@ export function UserProfilePopover({
     pendingAction,
     pubkey,
     queryClient,
-    showHumanProfileActions,
+    isBotProfile,
+    showHuddleAction,
     showProfileActions,
     startHuddle,
   ]);
@@ -722,7 +730,7 @@ export function UserProfilePopover({
                       Message
                     </Button>
                   ) : null}
-                  {showHumanProfileActions ? (
+                  {showHuddleAction ? (
                     <Button
                       className="min-w-0 flex-1"
                       data-testid={`user-profile-popover-huddle-${pubkey}`}
diff --git a/desktop/src/features/profile/ui/UserProfilePrimaryActions.tsx b/desktop/src/features/profile/ui/UserProfilePrimaryActions.tsx
new file mode 100644
index 0000000000..f03635ff18
--- /dev/null
+++ b/desktop/src/features/profile/ui/UserProfilePrimaryActions.tsx
@@ -0,0 +1,217 @@
+import type { LucideIcon } from "lucide-react";
+import {
+  MessageSquare,
+  Pencil,
+  Play,
+  RefreshCw,
+  Sparkles,
+  Square,
+  UserMinus,
+  UserPlus,
+} from "lucide-react";
+import { toast } from "sonner";
+
+import type {
+  useFollowMutation,
+  useUnfollowMutation,
+} from "@/features/profile/hooks";
+import { useFeatureEnabled } from "@/shared/features";
+import { cn } from "@/shared/lib/cn";
+import { Spinner } from "@/shared/ui/spinner";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
+
+// ── Primary actions ──────────────────────────────────────────────────────────
+
+export function ProfilePrimaryActions({
+  agentActionDisabled,
+  agentActionLabel,
+  agentActionLive,
+  canEditAgent,
+  followMutation,
+  isFollowing,
+  messagePending,
+  onAgentPrimaryAction,
+  onAgentRestart,
+  onCreateCard,
+  onEditAgent,
+  onMessage,
+  pubkey,
+  unfollowMutation,
+}: {
+  agentActionDisabled?: boolean;
+  agentActionLabel?: string;
+  agentActionLive?: boolean;
+  canEditAgent: boolean;
+  followMutation: ReturnType<typeof useFollowMutation>;
+  isFollowing: boolean;
+  messagePending?: boolean;
+  onAgentPrimaryAction?: () => void;
+  onAgentRestart?: () => void;
+  onCreateCard?: () => void;
+  onEditAgent: () => void;
+  onMessage?: () => void;
+  pubkey: string;
+  unfollowMutation: ReturnType<typeof useUnfollowMutation>;
+}) {
+  const showFollowAction = useFeatureEnabled("pulse");
+  const followToggleMutation = isFollowing ? unfollowMutation : followMutation;
+
+  const handleFollowClick = () => {
+    followToggleMutation.mutate(pubkey, {
+      onError: (error) =>
+        toast.error(
+          `${isFollowing ? "Unfollow" : "Follow"} failed: ${error.message}`,
+        ),
+    });
+  };
+
+  return (
+    <div className="flex items-center justify-center gap-8">
+      {showFollowAction ? (
+        <ProfileQuickAction
+          active={isFollowing}
+          disabled={followToggleMutation.isPending}
+          icon={isFollowing ? UserMinus : UserPlus}
+          label={isFollowing ? "Unfollow" : "Follow"}
+          onClick={handleFollowClick}
+        />
+      ) : null}
+      {onMessage ? (
+        <ProfileQuickAction
+          disabled={messagePending}
+          icon={MessageSquare}
+          isLoading={messagePending}
+          label="Message"
+          onClick={onMessage}
+          testId="user-profile-message"
+        />
+      ) : null}
+      {canEditAgent ? (
+        <ProfileQuickAction
+          icon={Pencil}
+          label="Edit"
+          onClick={onEditAgent}
+          testId="user-profile-edit-agent"
+        />
+      ) : null}
+      {onAgentPrimaryAction && agentActionLabel ? (
+        <ProfileQuickAction
+          active={agentActionLive}
+          disabled={agentActionDisabled}
+          icon={agentActionLive ? Square : Play}
+          label={agentActionLabel}
+          onClick={onAgentPrimaryAction}
+          testId="user-profile-agent-primary-action"
+        />
+      ) : null}
+      {onAgentRestart ? (
+        <ProfileQuickAction
+          disabled={agentActionDisabled}
+          icon={RefreshCw}
+          label="Restart"
+          onClick={onAgentRestart}
+          testId="user-profile-agent-restart"
+        />
+      ) : null}
+      {onCreateCard ? (
+        <ProfileQuickAction
+          icon={Sparkles}
+          label="Create card"
+          onClick={onCreateCard}
+          testId="user-profile-create-card"
+        />
+      ) : null}
+    </div>
+  );
+}
+
+export function ProfilePersonaPrimaryActions({
+  canEditAgent,
+  disabled,
+  onCreateCard,
+  onEditAgent,
+  onStartAgent,
+}: {
+  canEditAgent: boolean;
+  disabled: boolean;
+  onCreateCard?: () => void;
+  onEditAgent: () => void;
+  onStartAgent: () => void;
+}) {
+  return (
+    <div className="flex items-center justify-center gap-8">
+      <ProfileQuickAction
+        disabled={disabled}
+        icon={Play}
+        label="Start agent"
+        onClick={onStartAgent}
+        testId="user-profile-start-agent"
+      />
+      {canEditAgent ? (
+        <ProfileQuickAction
+          disabled={disabled}
+          icon={Pencil}
+          label="Edit"
+          onClick={onEditAgent}
+          testId="user-profile-edit-agent"
+        />
+      ) : null}
+      {onCreateCard ? (
+        <ProfileQuickAction
+          disabled={disabled}
+          icon={Sparkles}
+          label="Create card"
+          onClick={onCreateCard}
+          testId="user-profile-create-card"
+        />
+      ) : null}
+    </div>
+  );
+}
+
+function ProfileQuickAction({
+  active,
+  disabled,
+  icon: Icon,
+  isLoading,
+  label,
+  onClick,
+  testId,
+}: {
+  active?: boolean;
+  disabled?: boolean;
+  icon: LucideIcon;
+  isLoading?: boolean;
+  label: string;
+  onClick: () => void;
+  testId?: string;
+}) {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button
+          aria-label={label}
+          className={cn(
+            "flex h-12 w-12 items-center justify-center rounded-full transition-colors disabled:cursor-not-allowed disabled:opacity-50",
+            active
+              ? "bg-foreground text-background hover:bg-foreground/90"
+              : "bg-muted/60 text-foreground hover:bg-muted/80",
+          )}
+          data-testid={testId}
+          disabled={disabled}
+          onClick={onClick}
+          type="button"
+        >
+          {isLoading ? (
+            <Spinner aria-hidden="true" className="h-4 w-4 border-2" />
+          ) : (
+            <Icon className="h-4 w-4" />
+          )}
+        </button>
+      </TooltipTrigger>
+      <TooltipContent align="center" side="top">
+        {label}
+      </TooltipContent>
+    </Tooltip>
+  );
+}
diff --git a/desktop/src/features/projects/lib/projectBranchErrors.test.mjs b/desktop/src/features/projects/lib/projectBranchErrors.test.mjs
new file mode 100644
index 0000000000..c1c2a21a28
--- /dev/null
+++ b/desktop/src/features/projects/lib/projectBranchErrors.test.mjs
@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  isNoChannelBindingError,
+  projectBranchErrorMessage,
+} from "./projectBranchErrors.ts";
+
+test("recognizes the relay's stable denial token", () => {
+  // Body produced by the relay push policy (buzz-core
+  // GIT_NO_CHANNEL_BINDING_BODY), as it arrives wrapped in git stderr.
+  assert.ok(
+    isNoChannelBindingError(
+      "remote: no_channel_binding: repository has no channel binding\nerror: failed to push some refs",
+    ),
+  );
+});
+
+test("recognizes the legacy spaced phrase from older relays", () => {
+  assert.ok(isNoChannelBindingError("push denied: no channel binding"));
+});
+
+test("does not match unrelated errors", () => {
+  assert.ok(!isNoChannelBindingError("connection reset by peer"));
+  assert.ok(!isNoChannelBindingError("no channel"));
+});
+
+test("maps binding denials to remediation copy", () => {
+  const message = projectBranchErrorMessage(
+    new Error("remote: no_channel_binding: repository has no channel binding"),
+    "Failed to create branch.",
+  );
+  assert.ok(message.includes("buzz repos bind"));
+});
+
+test("passes through other errors and falls back for non-errors", () => {
+  assert.equal(
+    projectBranchErrorMessage(new Error("boom"), "fallback"),
+    "boom",
+  );
+  assert.equal(projectBranchErrorMessage("boom", "fallback"), "fallback");
+  assert.equal(projectBranchErrorMessage(null, "fallback"), "fallback");
+});
diff --git a/desktop/src/features/projects/lib/projectBranchErrors.ts b/desktop/src/features/projects/lib/projectBranchErrors.ts
new file mode 100644
index 0000000000..2cf990f1af
--- /dev/null
+++ b/desktop/src/features/projects/lib/projectBranchErrors.ts
@@ -0,0 +1,35 @@
+/**
+ * Relay push-policy denial token for a repository with no `buzz-channel`
+ * binding. Declared in Rust as `buzz-core::git_perms::
+ * GIT_NO_CHANNEL_BINDING_TOKEN`; the relay's denial body starts with it
+ * ("no_channel_binding: repository has no channel binding"). The legacy
+ * spaced phrase is kept as a second matcher so this build also recognizes
+ * denials from relays deployed before the token existed.
+ */
+const NO_CHANNEL_BINDING_TOKEN = "no_channel_binding";
+const NO_CHANNEL_BINDING_LEGACY_PHRASE = "no channel binding";
+
+const NO_CHANNEL_BINDING_COPY =
+  "This repository is not linked to a project channel, so the relay cannot " +
+  "authorize access. The repository owner can link it with: " +
+  "buzz repos bind --id <repo> --channel <channel-uuid>";
+
+/** True when a git/relay error text is the unbound-repository denial. */
+export function isNoChannelBindingError(message: string): boolean {
+  return (
+    message.includes(NO_CHANNEL_BINDING_TOKEN) ||
+    message.includes(NO_CHANNEL_BINDING_LEGACY_PHRASE)
+  );
+}
+
+/** Map a thrown branch-operation error to user-facing dialog copy. */
+export function projectBranchErrorMessage(
+  error: unknown,
+  fallback: string,
+): string {
+  if (!(error instanceof Error)) return fallback;
+  if (isNoChannelBindingError(error.message)) {
+    return NO_CHANNEL_BINDING_COPY;
+  }
+  return error.message;
+}
diff --git a/desktop/src/features/projects/ui/ProjectBranchDialogs.tsx b/desktop/src/features/projects/ui/ProjectBranchDialogs.tsx
index 20e8d14e1b..c2bde47355 100644
--- a/desktop/src/features/projects/ui/ProjectBranchDialogs.tsx
+++ b/desktop/src/features/projects/ui/ProjectBranchDialogs.tsx
@@ -5,6 +5,7 @@ import {
   normalizeProjectBranchName,
   projectBranchNameError,
 } from "@/features/projects/lib/projectBranches";
+import { projectBranchErrorMessage } from "@/features/projects/lib/projectBranchErrors";
 import {
   AlertDialog,
   AlertDialogCancel,
@@ -25,14 +26,6 @@ import {
 } from "@/shared/ui/dialog";
 import { Input } from "@/shared/ui/input";
 
-function errorMessage(error: unknown, fallback: string) {
-  if (!(error instanceof Error)) return fallback;
-  if (error.message.includes("no channel binding")) {
-    return "This repository is owned by another identity and is not linked to a project channel.";
-  }
-  return error.message;
-}
-
 export function CreateProjectBranchDialog({
   existingBranches,
   onCreate,
@@ -69,7 +62,9 @@ export function CreateProjectBranchDialog({
       await onCreate(branch);
       onOpenChange(false);
     } catch (error) {
-      setSubmitError(errorMessage(error, "Failed to create branch."));
+      setSubmitError(
+        projectBranchErrorMessage(error, "Failed to create branch."),
+      );
     }
   }
 
@@ -165,7 +160,9 @@ export function DeleteProjectBranchDialog({
       await onDelete();
       onOpenChange(false);
     } catch (error) {
-      setSubmitError(errorMessage(error, "Failed to delete branch."));
+      setSubmitError(
+        projectBranchErrorMessage(error, "Failed to delete branch."),
+      );
     }
   }
 
diff --git a/desktop/src/features/projects/ui/ProjectCards.tsx b/desktop/src/features/projects/ui/ProjectCards.tsx
index 52308f7a05..4f4fef7678 100644
--- a/desktop/src/features/projects/ui/ProjectCards.tsx
+++ b/desktop/src/features/projects/ui/ProjectCards.tsx
@@ -421,7 +421,8 @@ export function ProjectGridCard({
 }: ProjectItemProps) {
   return (
     <Card
-      className="group relative flex min-h-44 flex-col overflow-hidden border-border/60 bg-card shadow-none transition-colors duration-150 hover:bg-muted/20"
+      className="group relative flex min-h-44 flex-col overflow-hidden border-border/60 bg-transparent shadow-none transition-colors duration-150 hover:bg-muted/20"
+      data-projects-grid-card
       data-testid={`project-card-${project.dtag}`}
     >
       <ProjectCardButton onOpen={onOpen} project={project} />
diff --git a/desktop/src/features/projects/ui/ProjectCommitDetailPanel.tsx b/desktop/src/features/projects/ui/ProjectCommitDetailPanel.tsx
index c6122dcfe4..859a769c41 100644
--- a/desktop/src/features/projects/ui/ProjectCommitDetailPanel.tsx
+++ b/desktop/src/features/projects/ui/ProjectCommitDetailPanel.tsx
@@ -10,6 +10,7 @@ import {
 } from "@/features/profile/lib/identity";
 import type { ProjectRepoCommit, ProjectRepoDiff } from "@/shared/api/types";
 import { CopyCommitHashButton } from "./ProjectCommitCopyButton";
+import { PROJECT_DETAIL_PANEL_CLASS } from "./projectPanelStyles";
 import { ProfileIdentityButton } from "./ProjectProfileIdentity";
 import { ProjectDiffFilesPanel } from "./ProjectPullRequestFilesChangedPanel";
 import { ProjectRichContent } from "./ProjectRichContent";
@@ -56,7 +57,10 @@ export function ProjectCommitDetailPanel({
 
   return (
     <div className="space-y-3">
-      <header className="space-y-2 rounded-xl border border-border/60 bg-card p-4">
+      <header
+        className={`space-y-2 p-4 ${PROJECT_DETAIL_PANEL_CLASS}`}
+        data-project-detail-panel
+      >
         <p className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
           <GitCommitHorizontal className="h-3.5 w-3.5" />
           Commit from {authorLabel}
diff --git a/desktop/src/features/projects/ui/ProjectDetailFeedPanels.tsx b/desktop/src/features/projects/ui/ProjectDetailFeedPanels.tsx
index 5396ec5cfa..6676044c86 100644
--- a/desktop/src/features/projects/ui/ProjectDetailFeedPanels.tsx
+++ b/desktop/src/features/projects/ui/ProjectDetailFeedPanels.tsx
@@ -25,6 +25,10 @@ import {
   ProjectFeedRowCluster,
   ProjectFeedRowMonoCell,
 } from "./ProjectFeedRow";
+import {
+  PROJECT_DETAIL_PANEL_CLASS,
+  PROJECT_DETAIL_PANEL_MESSAGE_CLASS,
+} from "./projectPanelStyles";
 import { ProfileIdentityButton } from "./ProjectProfileIdentity";
 
 function pluralize(count: number, singular: string, plural = `${singular}s`) {
@@ -66,14 +70,17 @@ export function ContributorsPanel({
 
   if (rows.length === 0) {
     return (
-      <p className="rounded-xl border border-border/60 bg-card p-4 text-sm text-muted-foreground">
+      <p
+        className={PROJECT_DETAIL_PANEL_MESSAGE_CLASS}
+        data-project-detail-panel
+      >
         No git contributors are available yet.
       </p>
     );
   }
 
   return (
-    <div className="overflow-hidden rounded-xl border border-border/60 bg-card">
+    <div className={PROJECT_DETAIL_PANEL_CLASS} data-project-detail-panel>
       {rows.map((row, index) => (
         <div
           className={cn(
@@ -144,7 +151,10 @@ export function ActivityPanel({
 
   if (isLoading) {
     return (
-      <p className="rounded-xl border border-border/60 bg-card p-4 text-sm text-muted-foreground">
+      <p
+        className={PROJECT_DETAIL_PANEL_MESSAGE_CLASS}
+        data-project-detail-panel
+      >
         Loading activity…
       </p>
     );
@@ -152,7 +162,10 @@ export function ActivityPanel({
 
   if (commits.length === 0) {
     return (
-      <p className="rounded-xl border border-border/60 bg-card p-4 text-sm text-muted-foreground">
+      <p
+        className={PROJECT_DETAIL_PANEL_MESSAGE_CLASS}
+        data-project-detail-panel
+      >
         {error
           ? "Could not load repository activity from git."
           : "No commits are available yet."}
@@ -161,7 +174,7 @@ export function ActivityPanel({
   }
 
   return (
-    <section className="overflow-hidden rounded-xl border border-border/60 bg-card">
+    <section className={PROJECT_DETAIL_PANEL_CLASS} data-project-detail-panel>
       <div className="flex min-h-14 items-center gap-2 border-border/50 border-b px-4 py-3">
         <GitCommitHorizontal className="h-4 w-4 text-muted-foreground" />
         <h3 className="min-w-0 flex-1 truncate text-sm font-medium text-foreground">
diff --git a/desktop/src/features/projects/ui/ProjectOverviewPanel.tsx b/desktop/src/features/projects/ui/ProjectOverviewPanel.tsx
index d64b3081dc..d0e5c76bef 100644
--- a/desktop/src/features/projects/ui/ProjectOverviewPanel.tsx
+++ b/desktop/src/features/projects/ui/ProjectOverviewPanel.tsx
@@ -23,6 +23,7 @@ import {
 } from "@/features/projects/lib/projectLanguages";
 import { normalizePubkey } from "@/shared/lib/pubkey";
 import { UserAvatar } from "@/shared/ui/UserAvatar";
+import { PROJECT_DETAIL_PANEL_CLASS } from "./projectPanelStyles";
 import { ReadmePanel } from "./ProjectReadmePanel";
 import type { RepoSourceHeaderControls } from "./ProjectRepositorySource";
 
@@ -152,7 +153,10 @@ export function ProjectOverviewPanel({
   const latestCommit = snapshot?.latestCommit ?? null;
 
   return (
-    <div className="grid overflow-hidden rounded-xl border border-border/60 bg-card xl:grid-cols-[minmax(0,1fr)_18rem]">
+    <div
+      className={`grid xl:grid-cols-[minmax(0,1fr)_18rem] ${PROJECT_DETAIL_PANEL_CLASS}`}
+      data-project-detail-panel
+    >
       <div className="min-w-0">
         {/* ReadmePanel renders its own "no README" fallback while keeping
             the branch + source controls reachable. */}
diff --git a/desktop/src/features/projects/ui/ProjectPullRequestFilesChangedPanel.tsx b/desktop/src/features/projects/ui/ProjectPullRequestFilesChangedPanel.tsx
index c257457d31..ae41725788 100644
--- a/desktop/src/features/projects/ui/ProjectPullRequestFilesChangedPanel.tsx
+++ b/desktop/src/features/projects/ui/ProjectPullRequestFilesChangedPanel.tsx
@@ -39,6 +39,7 @@ import type { UserProfileLookup } from "@/features/profile/lib/identity";
 import { useIdentityQuery } from "@/shared/api/hooks";
 import { cn } from "@/shared/lib/cn";
 import type { ProjectRepoDiff, ProjectRepoDiffFile } from "@/shared/api/types";
+import { PROJECT_DETAIL_PANEL_CLASS } from "./projectPanelStyles";
 import { ProjectPullRequestInlineCommentThread } from "./ProjectPullRequestInlineComments";
 
 function fileName(path: string) {
@@ -772,9 +773,7 @@ export function ProjectDiffFilesPanel({
   inlineComments?: InlineCommentControls;
   subjectLabel: string;
 }) {
-  const outerBorderClass = embedded
-    ? ""
-    : "rounded-xl border border-border/60 bg-card";
+  const outerBorderClass = embedded ? "" : PROJECT_DETAIL_PANEL_CLASS;
   const [query, setQuery] = React.useState("");
   const [selectedPath, setSelectedPath] = React.useState<string | null>(null);
   const files = diff?.files ?? [];
@@ -818,6 +817,7 @@ export function ProjectDiffFilesPanel({
     return (
       <div
         className={cn("p-4 text-sm text-muted-foreground", outerBorderClass)}
+        data-project-detail-panel={embedded ? undefined : true}
       >
         Loading changed files…
       </div>
@@ -832,6 +832,7 @@ export function ProjectDiffFilesPanel({
           "space-y-1 p-4 text-sm text-muted-foreground",
           outerBorderClass,
         )}
+        data-project-detail-panel={embedded ? undefined : true}
       >
         <p>Could not load changed files for this {subjectLabel}.</p>
         {message ? (
@@ -850,6 +851,7 @@ export function ProjectDiffFilesPanel({
           "p-6 text-center text-sm text-muted-foreground",
           outerBorderClass,
         )}
+        data-project-detail-panel={embedded ? undefined : true}
       >
         No changed files are available for this {subjectLabel} yet.
       </div>
@@ -862,6 +864,7 @@ export function ProjectDiffFilesPanel({
         "grid min-h-0 overflow-hidden lg:grid-cols-[17rem_minmax(0,1fr)]",
         outerBorderClass,
       )}
+      data-project-detail-panel={embedded ? undefined : true}
     >
       <aside className="border-border/50 border-b bg-background/30 lg:border-r lg:border-b-0">
         <div className="space-y-3 p-3">
diff --git a/desktop/src/features/projects/ui/ProjectRepositoryPanel.tsx b/desktop/src/features/projects/ui/ProjectRepositoryPanel.tsx
index 93965b29de..9aa67189f9 100644
--- a/desktop/src/features/projects/ui/ProjectRepositoryPanel.tsx
+++ b/desktop/src/features/projects/ui/ProjectRepositoryPanel.tsx
@@ -34,6 +34,10 @@ import { cn } from "@/shared/lib/cn";
 import { normalizePubkey } from "@/shared/lib/pubkey";
 import { SyntaxHighlightedCode } from "@/shared/ui/markdown";
 import { UserAvatar } from "@/shared/ui/UserAvatar";
+import {
+  PROJECT_DETAIL_PANEL_CLASS,
+  PROJECT_DETAIL_PANEL_MESSAGE_CLASS,
+} from "./projectPanelStyles";
 import {
   type RepoSourceHeaderControls,
   RepoSourceDropdown,
@@ -550,7 +554,7 @@ function FileContentPanel({
   const directorySegments = pathSegments.slice(0, -1);
 
   return (
-    <div className="overflow-hidden rounded-xl border border-border/60 bg-card">
+    <div className={PROJECT_DETAIL_PANEL_CLASS} data-project-detail-panel>
       <div className="flex min-h-14 items-center gap-1 border-border/50 border-b bg-muted/20 px-3 py-3">
         <BreadcrumbButton onClick={() => onOpenPath("")}>
           Files
@@ -687,13 +691,16 @@ export function RepositoryFilesPanel({
   if (stateMessage) {
     if (!sourceControls) {
       return (
-        <div className="rounded-xl border border-border/60 bg-card p-4 text-sm text-muted-foreground">
+        <div
+          className={PROJECT_DETAIL_PANEL_MESSAGE_CLASS}
+          data-project-detail-panel
+        >
           {stateMessage}
         </div>
       );
     }
     return (
-      <div className="overflow-hidden rounded-xl border border-border/60 bg-card">
+      <div className={PROJECT_DETAIL_PANEL_CLASS} data-project-detail-panel>
         <div className="flex min-h-14 min-w-0 items-center gap-1 border-border/50 border-b px-3 py-3">
           <RepoSourceDropdown controls={sourceControls} />
           <RepositoryBranchDropdown
@@ -733,7 +740,7 @@ export function RepositoryFilesPanel({
   }
 
   return (
-    <div className="overflow-hidden rounded-xl border border-border/60 bg-card">
+    <div className={PROJECT_DETAIL_PANEL_CLASS} data-project-detail-panel>
       <div className="flex min-h-14 min-w-0 items-center gap-1 border-border/50 border-b px-3 py-3">
         {sourceControls ? (
           <>
diff --git a/desktop/src/features/projects/ui/ProjectWorkspaceTabs.tsx b/desktop/src/features/projects/ui/ProjectWorkspaceTabs.tsx
index 4dc97635d4..a6fd329907 100644
--- a/desktop/src/features/projects/ui/ProjectWorkspaceTabs.tsx
+++ b/desktop/src/features/projects/ui/ProjectWorkspaceTabs.tsx
@@ -42,6 +42,10 @@ import {
   PullRequestTabsList,
 } from "./ProjectWorkspaceTabList";
 import { ProjectPullRequestFilesChangedPanel } from "./ProjectPullRequestFilesChangedPanel";
+import {
+  PROJECT_DETAIL_PANEL_CLASS,
+  PROJECT_DETAIL_PANEL_MESSAGE_CLASS,
+} from "./projectPanelStyles";
 import { CreatePullRequestDialog } from "./CreatePullRequestDialog";
 import {
   CreateIssueDialog,
@@ -303,7 +307,7 @@ export function WorkspaceTabs({
         ) : null}
       </div>
       {selectedPullRequest ? (
-        <div className="overflow-hidden rounded-xl border border-border/60 bg-card">
+        <div className={PROJECT_DETAIL_PANEL_CLASS} data-project-detail-panel>
           {/* Two full-height columns: the meta rail runs all the way to the
               top of the card, alongside the header and tabs. */}
           <div className="grid xl:grid-cols-[minmax(0,1fr)_18rem]">
@@ -409,7 +413,8 @@ export function WorkspaceTabs({
       </TabsContent>
 
       <TabsContent
-        className="m-0 overflow-hidden rounded-xl border border-border/60 bg-card"
+        className={`m-0 ${PROJECT_DETAIL_PANEL_CLASS}`}
+        data-project-detail-panel
         value="prs"
       >
         <WorkItemListHeader
@@ -437,7 +442,8 @@ export function WorkspaceTabs({
       </TabsContent>
 
       <TabsContent
-        className="m-0 overflow-hidden rounded-xl border border-border/60 bg-card"
+        className={`m-0 ${PROJECT_DETAIL_PANEL_CLASS}`}
+        data-project-detail-panel
         value="issues"
       >
         <WorkItemListHeader
@@ -458,7 +464,10 @@ export function WorkspaceTabs({
       <TabsContent className="m-0" value="files">
         {repoSource === "local" && !localSnapshot && !localSnapshotLoading ? (
           <div className="mb-3">
-            <div className="rounded-xl border border-border/60 bg-card p-4 text-sm text-muted-foreground">
+            <div
+              className={PROJECT_DETAIL_PANEL_MESSAGE_CLASS}
+              data-project-detail-panel
+            >
               No local checkout found.
             </div>
           </div>
diff --git a/desktop/src/features/projects/ui/ProjectsActivityFeed.tsx b/desktop/src/features/projects/ui/ProjectsActivityFeed.tsx
index ba0c15b1c7..011b50a735 100644
--- a/desktop/src/features/projects/ui/ProjectsActivityFeed.tsx
+++ b/desktop/src/features/projects/ui/ProjectsActivityFeed.tsx
@@ -257,9 +257,10 @@ function ActivityCard({
   return (
     <div
       className={cn(
-        "relative block w-full rounded-xl border border-border/60 bg-card text-left transition-colors hover:bg-muted/20",
+        "relative block w-full rounded-xl border border-border/60 bg-transparent text-left transition-colors hover:bg-muted/20",
         compact ? "p-3" : "p-4",
       )}
+      data-testid="projects-activity-card"
     >
       <button
         aria-label={`Open ${item.title} in ${item.target.project.name}`}
diff --git a/desktop/src/features/projects/ui/ProjectsIssuesList.tsx b/desktop/src/features/projects/ui/ProjectsIssuesList.tsx
index 6426277c4a..240d3345d4 100644
--- a/desktop/src/features/projects/ui/ProjectsIssuesList.tsx
+++ b/desktop/src/features/projects/ui/ProjectsIssuesList.tsx
@@ -103,7 +103,10 @@ function IssueGridCard({
   project: Project;
 }) {
   return (
-    <Card className="group relative flex min-h-40 flex-col overflow-hidden border-border/60 bg-card p-4 shadow-none transition-colors duration-150 hover:bg-muted/20">
+    <Card
+      className="group relative flex min-h-40 flex-col overflow-hidden border-border/60 bg-transparent p-4 shadow-none transition-colors duration-150 hover:bg-muted/20"
+      data-projects-grid-card
+    >
       <button
         className="absolute inset-0"
         onClick={() => onOpen(project, issue)}
@@ -279,7 +282,10 @@ export function ProjectsIssuesList({
   return (
     <div className="space-y-3">
       {loadNotice}
-      <div className={PROJECT_LIST_CONTAINER_CLASS}>
+      <div
+        className={PROJECT_LIST_CONTAINER_CLASS}
+        data-testid="projects-list-container"
+      >
         {issues.map(({ project, issue }) => (
           <IssueListRow
             issue={issue}
diff --git a/desktop/src/features/projects/ui/ProjectsOverviewPanel.tsx b/desktop/src/features/projects/ui/ProjectsOverviewPanel.tsx
index 3640af904e..b11e7d1235 100644
--- a/desktop/src/features/projects/ui/ProjectsOverviewPanel.tsx
+++ b/desktop/src/features/projects/ui/ProjectsOverviewPanel.tsx
@@ -50,7 +50,8 @@ function StatPill({
 }) {
   return (
     <button
-      className="flex flex-col rounded-lg border border-border/60 bg-card px-3.5 py-3 text-left transition-colors hover:bg-muted/30"
+      className="flex flex-col rounded-lg border border-border/60 bg-transparent px-3.5 py-3 text-left transition-colors hover:bg-muted/30"
+      data-testid="projects-overview-stat"
       onClick={onClick}
       type="button"
     >
@@ -78,7 +79,7 @@ export function ProjectsOverviewPanel({
   const stats = overviewStats(projects, summaries);
 
   return (
-    <section className="-mx-4 mb-4 bg-card">
+    <section className="-mx-4 mb-4" data-testid="projects-overview-panel">
       <div className="grid xl:grid-cols-[minmax(0,1fr)_18rem] 2xl:grid-cols-[minmax(0,1fr)_24rem]">
         <div className="order-1 grid grid-cols-2 gap-2 p-4 pt-0 sm:gap-3 xl:order-none xl:col-start-1 xl:row-start-1 xl:grid-cols-4">
           <StatPill
diff --git a/desktop/src/features/projects/ui/ProjectsPullRequestsList.tsx b/desktop/src/features/projects/ui/ProjectsPullRequestsList.tsx
index 3b3ae758a1..a1f28254e8 100644
--- a/desktop/src/features/projects/ui/ProjectsPullRequestsList.tsx
+++ b/desktop/src/features/projects/ui/ProjectsPullRequestsList.tsx
@@ -85,7 +85,10 @@ function PullRequestGridCard({
   });
 
   return (
-    <Card className="group relative flex min-h-40 flex-col overflow-hidden border-border/60 bg-card p-4 shadow-none transition-colors duration-150 hover:bg-muted/20">
+    <Card
+      className="group relative flex min-h-40 flex-col overflow-hidden border-border/60 bg-transparent p-4 shadow-none transition-colors duration-150 hover:bg-muted/20"
+      data-projects-grid-card
+    >
       <button
         className="absolute inset-0"
         onClick={() => onOpen(project, pullRequest)}
@@ -305,7 +308,10 @@ export function ProjectsPullRequestsList({
   return (
     <div className="space-y-3">
       {loadNotice}
-      <div className={PROJECT_LIST_CONTAINER_CLASS}>
+      <div
+        className={PROJECT_LIST_CONTAINER_CLASS}
+        data-testid="projects-list-container"
+      >
         {pullRequests.map(({ project, pullRequest }) => (
           <PullRequestListRow
             key={pullRequest.id}
diff --git a/desktop/src/features/projects/ui/ProjectsView.tsx b/desktop/src/features/projects/ui/ProjectsView.tsx
index 2f22bfe0c1..d0a3d2eb9a 100644
--- a/desktop/src/features/projects/ui/ProjectsView.tsx
+++ b/desktop/src/features/projects/ui/ProjectsView.tsx
@@ -481,7 +481,10 @@ export function ProjectsView() {
         })}
       </div>
     ) : (
-      <div className={PROJECT_LIST_CONTAINER_CLASS}>
+      <div
+        className={PROJECT_LIST_CONTAINER_CLASS}
+        data-testid="projects-list-container"
+      >
         {visibleProjects.map((project) => {
           const summary = activitySummariesQuery.data?.[project.repoAddress];
           return (
diff --git a/desktop/src/features/projects/ui/projectListRowStyles.ts b/desktop/src/features/projects/ui/projectListRowStyles.ts
index 97271cbcbe..3a8dad62e2 100644
--- a/desktop/src/features/projects/ui/projectListRowStyles.ts
+++ b/desktop/src/features/projects/ui/projectListRowStyles.ts
@@ -1,6 +1,6 @@
 /** Inbox-aligned spacing and typography for top-level Projects list rows. */
 export const PROJECT_LIST_CONTAINER_CLASS =
-  "divide-y divide-border/60 overflow-hidden rounded-xl border border-border/60 bg-card";
+  "divide-y divide-border/60 overflow-hidden rounded-xl border border-border/60 bg-transparent";
 
 export const PROJECT_LIST_ROW_CLASS =
   "group relative px-3 py-3 transition-colors duration-150 hover:bg-muted/20";
diff --git a/desktop/src/features/projects/ui/projectPanelStyles.ts b/desktop/src/features/projects/ui/projectPanelStyles.ts
index 91ff212d5c..c4cf24ba03 100644
--- a/desktop/src/features/projects/ui/projectPanelStyles.ts
+++ b/desktop/src/features/projects/ui/projectPanelStyles.ts
@@ -1,3 +1,11 @@
 /** Settings-aligned action button used at the right edge of panel headers. */
 export const PROJECT_PANEL_ACTION_BUTTON_CLASS =
   "h-auto shrink-0 gap-1.5 rounded-full border-transparent bg-muted px-3 py-1.5 text-sm font-medium text-foreground shadow-none hover:bg-muted/80";
+
+/** Bordered shell that lets the project page surface show through. */
+export const PROJECT_DETAIL_PANEL_CLASS =
+  "overflow-hidden rounded-xl border border-border/60 bg-transparent";
+
+/** Empty or loading state using the same transparent project panel shell. */
+export const PROJECT_DETAIL_PANEL_MESSAGE_CLASS =
+  "rounded-xl border border-border/60 bg-transparent p-4 text-sm text-muted-foreground";
diff --git a/desktop/src/features/settings/EncryptedBackupProvider.tsx b/desktop/src/features/settings/EncryptedBackupProvider.tsx
new file mode 100644
index 0000000000..7375a85cfb
--- /dev/null
+++ b/desktop/src/features/settings/EncryptedBackupProvider.tsx
@@ -0,0 +1,251 @@
+import * as React from "react";
+import { toast } from "sonner";
+
+import {
+  createNcryptsecBackup,
+  saveNcryptsecCopy,
+} from "@/shared/api/tauriIdentity";
+import {
+  type EncryptedBackupEvent,
+  type EncryptedBackupState,
+  encryptedBackupReducer,
+  initialEncryptedBackupState,
+  pendingEncryptPassphrase,
+} from "./lib/encryptedBackup";
+
+const ENCRYPT_DEBOUNCE_MS = 400;
+/** How long a completed encrypted backup remains available in memory. */
+export const BACKUP_AVAILABILITY_MS = 5 * 60 * 1000;
+const BACKUP_READY_TOAST_ID = "encrypted-key-backup-ready";
+
+type EncryptedBackupContextValue = {
+  state: EncryptedBackupState;
+  dispatch: React.Dispatch<EncryptedBackupEvent>;
+  backupAvailable: boolean;
+  availableUntil: number | null;
+  isSaving: boolean;
+  saveError: string | null;
+  downloadBackup: () => Promise<void>;
+  startNewBackup: () => void;
+};
+
+const EncryptedBackupContext =
+  React.createContext<EncryptedBackupContextValue | null>(null);
+
+export function EncryptedBackupProvider({
+  children,
+  onOpenSettings,
+}: {
+  children: React.ReactNode;
+  onOpenSettings: () => void;
+}) {
+  const [state, dispatch] = React.useReducer(
+    encryptedBackupReducer,
+    initialEncryptedBackupState,
+  );
+  const [availableUntil, setAvailableUntil] = React.useState<number | null>(
+    null,
+  );
+  const [isSaving, setIsSaving] = React.useState(false);
+  const [saveError, setSaveError] = React.useState<string | null>(null);
+  const autoSaveStartedForRef = React.useRef<string | null>(null);
+  const mountedRef = React.useRef(true);
+  const onOpenSettingsRef = React.useRef(onOpenSettings);
+
+  React.useEffect(() => {
+    onOpenSettingsRef.current = onOpenSettings;
+  }, [onOpenSettings]);
+
+  React.useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  React.useEffect(() => {
+    if (availableUntil === null) return;
+    const expiresIn = Math.max(0, availableUntil - Date.now());
+    const timer = window.setTimeout(() => {
+      autoSaveStartedForRef.current = null;
+      setAvailableUntil(null);
+      setSaveError(null);
+      dispatch({ type: "start-new-backup" });
+      toast.dismiss(BACKUP_READY_TOAST_ID);
+    }, expiresIn);
+    return () => window.clearTimeout(timer);
+  }, [availableUntil]);
+
+  const pendingPassphrase = pendingEncryptPassphrase(state);
+  const skipDebounce = state.downloadPending;
+  React.useEffect(() => {
+    if (!pendingPassphrase) return;
+    let started = false;
+    let cancelledBeforeStart = false;
+    const requestId = state.nextRequestId;
+    const start = () => {
+      if (cancelledBeforeStart) return;
+      started = true;
+      dispatch({ type: "encrypt-started", requestId });
+      void createNcryptsecBackup(pendingPassphrase)
+        .then((ncryptsec) => {
+          dispatch({ type: "encrypt-succeeded", requestId, ncryptsec });
+        })
+        .catch((err: unknown) => {
+          dispatch({
+            type: "encrypt-failed",
+            requestId,
+            message:
+              err instanceof Error
+                ? err.message
+                : "Failed to encrypt your key.",
+          });
+        });
+    };
+    const timer = window.setTimeout(
+      start,
+      skipDebounce ? 0 : ENCRYPT_DEBOUNCE_MS,
+    );
+    return () => {
+      if (!started) cancelledBeforeStart = true;
+      window.clearTimeout(timer);
+    };
+  }, [pendingPassphrase, skipDebounce, state.nextRequestId]);
+
+  React.useEffect(() => {
+    if (state.downloadPending) {
+      toast.loading("Preparing backup…", {
+        description: "You can close this window while Buzz finishes.",
+        duration: Number.POSITIVE_INFINITY,
+        id: BACKUP_READY_TOAST_ID,
+      });
+      return;
+    }
+    if (
+      state.createError &&
+      state.passphrase.length === 0 &&
+      !state.ncryptsec
+    ) {
+      toast.error("Couldn’t create backup", {
+        description: state.createError,
+        id: BACKUP_READY_TOAST_ID,
+      });
+    }
+  }, [
+    state.createError,
+    state.downloadPending,
+    state.ncryptsec,
+    state.passphrase.length,
+  ]);
+
+  const showAvailableToast = React.useCallback(
+    (description: string, error = false) => {
+      const options = {
+        action: {
+          label: "Open settings",
+          onClick: () => onOpenSettingsRef.current(),
+        },
+        description,
+        id: BACKUP_READY_TOAST_ID,
+      };
+      if (error) toast.error("Backup ready to download", options);
+      else toast.success("Backup ready to download", options);
+    },
+    [],
+  );
+
+  const saveBackup = React.useCallback(
+    async (ncryptsec: string) => {
+      if (isSaving) return;
+      setIsSaving(true);
+      setSaveError(null);
+      toast("Saving backup…", {
+        description: "The download window will open when it’s ready.",
+        id: BACKUP_READY_TOAST_ID,
+      });
+      try {
+        const path = await saveNcryptsecCopy(ncryptsec);
+        if (mountedRef.current) {
+          showAvailableToast(
+            path === null
+              ? "Your backup will be available to download for 5 minutes."
+              : "You can download another copy for 5 minutes.",
+          );
+        }
+      } catch (err) {
+        if (!mountedRef.current) return;
+        const message =
+          err instanceof Error ? err.message : "Failed to save your key.";
+        setSaveError(message);
+        showAvailableToast(
+          `${message} It will be available to download for 5 minutes.`,
+          true,
+        );
+      } finally {
+        if (mountedRef.current) setIsSaving(false);
+      }
+    },
+    [isSaving, showAvailableToast],
+  );
+
+  React.useEffect(() => {
+    const ncryptsec = state.ncryptsec;
+    if (!ncryptsec || autoSaveStartedForRef.current === ncryptsec) return;
+    autoSaveStartedForRef.current = ncryptsec;
+    setAvailableUntil(Date.now() + BACKUP_AVAILABILITY_MS);
+    void saveBackup(ncryptsec);
+  }, [saveBackup, state.ncryptsec]);
+
+  const downloadBackup = React.useCallback(async () => {
+    if (!state.ncryptsec) return;
+    await saveBackup(state.ncryptsec);
+  }, [saveBackup, state.ncryptsec]);
+
+  const startNewBackup = React.useCallback(() => {
+    autoSaveStartedForRef.current = null;
+    setAvailableUntil(null);
+    setSaveError(null);
+    toast.dismiss(BACKUP_READY_TOAST_ID);
+    dispatch({ type: "start-new-backup" });
+  }, []);
+
+  const value = React.useMemo<EncryptedBackupContextValue>(
+    () => ({
+      state,
+      dispatch,
+      backupAvailable:
+        state.savedPassword &&
+        state.ncryptsec !== null &&
+        availableUntil !== null,
+      availableUntil,
+      isSaving,
+      saveError,
+      downloadBackup,
+      startNewBackup,
+    }),
+    [
+      availableUntil,
+      downloadBackup,
+      isSaving,
+      saveError,
+      startNewBackup,
+      state,
+    ],
+  );
+
+  return (
+    <EncryptedBackupContext.Provider value={value}>
+      {children}
+    </EncryptedBackupContext.Provider>
+  );
+}
+
+export function useEncryptedBackup(): EncryptedBackupContextValue {
+  const value = React.useContext(EncryptedBackupContext);
+  if (!value) {
+    throw new Error(
+      "useEncryptedBackup must be used within EncryptedBackupProvider",
+    );
+  }
+  return value;
+}
diff --git a/desktop/src/features/settings/lib/encryptedBackup.test.mjs b/desktop/src/features/settings/lib/encryptedBackup.test.mjs
new file mode 100644
index 0000000000..306e937ec5
--- /dev/null
+++ b/desktop/src/features/settings/lib/encryptedBackup.test.mjs
@@ -0,0 +1,133 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  MIN_PASSPHRASE_LEN,
+  downloadDisabled,
+  isEncrypting,
+  passphraseIssue,
+  pendingEncryptPassphrase,
+  effectivePassphrase,
+  encryptedBackupReducer,
+  initialEncryptedBackupState,
+} from "./encryptedBackup.ts";
+const reduce = (events, from = initialEncryptedBackupState) =>
+  events.reduce(encryptedBackupReducer, from);
+test("password validation mirrors Rust character counting", () => {
+  assert.equal(passphraseIssue(""), null);
+  assert.match(passphraseIssue("short"), new RegExp(`${MIN_PASSPHRASE_LEN}`));
+  const emoji = "😀".repeat(MIN_PASSPHRASE_LEN);
+  assert.equal(passphraseIssue(emoji), null);
+  assert.equal(
+    effectivePassphrase(reduce([{ type: "set-passphrase", value: emoji }])),
+    emoji,
+  );
+});
+test("valid password requests encryption without copying it into events", () => {
+  const ready = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+  ]);
+  assert.equal(pendingEncryptPassphrase(ready), "one-two-three-four");
+  const started = reduce([{ type: "encrypt-started", requestId: 1 }], ready);
+  assert.equal(isEncrypting(started), true);
+  assert.equal(started.requestId, 1);
+  assert.equal(Object.hasOwn(started, "encryptingPassphrase"), false);
+});
+test("background success retains the password without committing the download", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "encrypt-succeeded", requestId: 1, ncryptsec: "ncryptsec1abc" },
+  ]);
+  assert.equal(state.passphrase, "one-two-three-four");
+  assert.equal(state.encrypted, "ncryptsec1abc");
+  assert.equal(state.ncryptsec, null);
+  assert.equal(state.savedPassword, false);
+  assert.equal(state.requestId, null);
+  assert.equal(downloadDisabled(state), false);
+});
+test("submit commits a completed preload immediately", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "encrypt-succeeded", requestId: 1, ncryptsec: "ncryptsec1abc" },
+    { type: "download-clicked" },
+  ]);
+  assert.equal(state.ncryptsec, "ncryptsec1abc");
+  assert.equal(state.passphrase, "");
+  assert.equal(state.savedPassword, true);
+});
+test("stale async completions cannot replace current request", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "set-passphrase", value: "five-six-seven-eight" },
+    { type: "encrypt-started", requestId: 2 },
+    { type: "encrypt-succeeded", requestId: 1, ncryptsec: "ncryptsec1stale" },
+  ]);
+  assert.equal(state.requestId, 2);
+  assert.equal(state.encrypted, null);
+  assert.equal(state.passphrase, "five-six-seven-eight");
+});
+test("failure clears submitted password", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "download-clicked" },
+    { type: "encrypt-failed", requestId: 1, message: "keychain unavailable" },
+  ]);
+  assert.equal(state.passphrase, "");
+  assert.equal(state.createError, "keychain unavailable");
+  assert.equal(state.downloadPending, false);
+  assert.equal(downloadDisabled(state), true);
+});
+test("background failure stays silent until submit retries encryption", () => {
+  const failed = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "encrypt-failed", requestId: 1, message: "keychain unavailable" },
+  ]);
+  assert.equal(failed.passphrase, "one-two-three-four");
+  assert.equal(failed.createError, "keychain unavailable");
+  assert.equal(pendingEncryptPassphrase(failed), null);
+
+  const retrying = reduce([{ type: "download-clicked" }], failed);
+  assert.equal(retrying.createError, null);
+  assert.equal(retrying.downloadPending, true);
+  assert.equal(pendingEncryptPassphrase(retrying), "one-two-three-four");
+});
+test("queued download commits and clears password", () => {
+  const state = reduce([
+    { type: "set-passphrase", value: "one-two-three-four" },
+    { type: "encrypt-started", requestId: 1 },
+    { type: "download-clicked" },
+    { type: "encrypt-succeeded", requestId: 1, ncryptsec: "ncryptsec1abc" },
+  ]);
+  assert.equal(state.ncryptsec, "ncryptsec1abc");
+  assert.equal(state.passphrase, "");
+  assert.equal(state.savedPassword, true);
+});
+test("starting over discards blob and invalidates late requests", () => {
+  const made = {
+    ...initialEncryptedBackupState,
+    ncryptsec: "ncryptsec1abc",
+    encrypted: "ncryptsec1abc",
+    savedPassword: true,
+    nextRequestId: 3,
+  };
+  const fresh = reduce([{ type: "start-new-backup" }], made);
+  assert.equal(fresh.ncryptsec, null);
+  assert.equal(fresh.nextRequestId, 4);
+  assert.equal(
+    reduce(
+      [
+        {
+          type: "encrypt-succeeded",
+          requestId: 2,
+          ncryptsec: "ncryptsec1stale",
+        },
+      ],
+      fresh,
+    ).ncryptsec,
+    null,
+  );
+});
diff --git a/desktop/src/features/settings/lib/encryptedBackup.ts b/desktop/src/features/settings/lib/encryptedBackup.ts
new file mode 100644
index 0000000000..e54189769a
--- /dev/null
+++ b/desktop/src/features/settings/lib/encryptedBackup.ts
@@ -0,0 +1,143 @@
+/** Pure state model for NIP-49 backup creation. */
+export const MIN_PASSPHRASE_LEN = 12;
+
+export type EncryptedBackupState = {
+  passphrase: string;
+  requestId: number | null;
+  nextRequestId: number;
+  encrypted: string | null;
+  createError: string | null;
+  downloadPending: boolean;
+  ncryptsec: string | null;
+  savedPassword: boolean;
+};
+
+export const initialEncryptedBackupState: EncryptedBackupState = {
+  passphrase: "",
+  requestId: null,
+  nextRequestId: 1,
+  encrypted: null,
+  createError: null,
+  downloadPending: false,
+  ncryptsec: null,
+  savedPassword: false,
+};
+
+export type EncryptedBackupEvent =
+  | { type: "set-passphrase"; value: string }
+  | { type: "encrypt-started"; requestId: number }
+  | { type: "encrypt-succeeded"; requestId: number; ncryptsec: string }
+  | { type: "encrypt-failed"; requestId: number; message: string }
+  | { type: "download-clicked" }
+  | { type: "start-new-backup" };
+
+export function encryptedBackupReducer(
+  state: EncryptedBackupState,
+  event: EncryptedBackupEvent,
+): EncryptedBackupState {
+  switch (event.type) {
+    case "set-passphrase":
+      return {
+        ...state,
+        passphrase: event.value,
+        requestId: null,
+        encrypted: null,
+        createError: null,
+      };
+    case "encrypt-started":
+      return {
+        ...state,
+        requestId: event.requestId,
+        nextRequestId: Math.max(state.nextRequestId, event.requestId + 1),
+        createError: null,
+      };
+    case "encrypt-succeeded":
+      if (event.requestId !== state.requestId) return state;
+      return state.downloadPending
+        ? {
+            ...state,
+            passphrase: "",
+            requestId: null,
+            encrypted: event.ncryptsec,
+            ncryptsec: event.ncryptsec,
+            downloadPending: false,
+            savedPassword: true,
+          }
+        : {
+            ...state,
+            requestId: null,
+            encrypted: event.ncryptsec,
+          };
+    case "encrypt-failed":
+      if (event.requestId !== state.requestId) return state;
+      return state.downloadPending
+        ? {
+            ...state,
+            passphrase: "",
+            requestId: null,
+            createError: event.message,
+            downloadPending: false,
+          }
+        : {
+            ...state,
+            requestId: null,
+            createError: event.message,
+          };
+    case "download-clicked":
+      if (
+        state.ncryptsec ||
+        state.downloadPending ||
+        (!state.encrypted && !effectivePassphrase(state))
+      )
+        return state;
+      return state.encrypted
+        ? {
+            ...state,
+            ncryptsec: state.encrypted,
+            passphrase: "",
+            savedPassword: true,
+          }
+        : { ...state, createError: null, downloadPending: true };
+    case "start-new-backup":
+      return {
+        ...initialEncryptedBackupState,
+        nextRequestId: state.nextRequestId + 1,
+      };
+  }
+}
+
+export function passphraseIssue(passphrase: string): string | null {
+  if (passphrase.length === 0) return null;
+  return [...passphrase].length < MIN_PASSPHRASE_LEN
+    ? `Use at least ${MIN_PASSPHRASE_LEN} characters.`
+    : null;
+}
+export function effectivePassphrase(
+  state: EncryptedBackupState,
+): string | null {
+  return [...state.passphrase].length < MIN_PASSPHRASE_LEN
+    ? null
+    : state.passphrase;
+}
+export function pendingEncryptPassphrase(
+  state: EncryptedBackupState,
+): string | null {
+  if (
+    state.savedPassword ||
+    state.encrypted ||
+    state.requestId !== null ||
+    (state.createError !== null && !state.downloadPending)
+  )
+    return null;
+  return effectivePassphrase(state);
+}
+export function isEncrypting(state: EncryptedBackupState): boolean {
+  return state.requestId !== null;
+}
+export function downloadDisabled(state: EncryptedBackupState): boolean {
+  if (state.savedPassword && state.ncryptsec) return false;
+  return (
+    state.downloadPending ||
+    (!state.encrypted && effectivePassphrase(state) === null)
+  );
+}
diff --git a/desktop/src/features/settings/ui/BackupTestFlow.tsx b/desktop/src/features/settings/ui/BackupTestFlow.tsx
new file mode 100644
index 0000000000..65ef40a98a
--- /dev/null
+++ b/desktop/src/features/settings/ui/BackupTestFlow.tsx
@@ -0,0 +1,459 @@
+import { Check, Eye, EyeOff, FileKey2, FileUp } from "lucide-react";
+import { motion, useReducedMotion } from "motion/react";
+import * as React from "react";
+
+import {
+  verifyNcryptsecBackup,
+  type BackupVerification,
+} from "@/shared/api/tauriIdentity";
+import { Button } from "@/shared/ui/button";
+import { Input } from "@/shared/ui/input";
+import { PubKey } from "@/shared/ui/PubKey";
+import { Spinner } from "@/shared/ui/spinner";
+
+type BackupTestStage = "drop" | "password" | "success";
+
+/**
+ * Progress through the Settings backup-test flow. The password attempt is
+ * deliberately NOT part of this state — it lives only in short-lived
+ * moment it's submitted or the component unmounts.
+ */
+export type BackupTestProgress = {
+  stage: BackupTestStage;
+  /** Name of the accepted file once the drop check passed. */
+  fileName: string | null;
+  /** Contents of the accepted file, pending or past verification. */
+  ncryptsec: string | null;
+  /** The Rust-verified public identity once decryption succeeded. */
+  result: BackupVerification | null;
+};
+
+export const initialBackupTestProgress: BackupTestProgress = {
+  stage: "drop",
+  fileName: null,
+  ncryptsec: null,
+  result: null,
+};
+
+type BackupTestFlowProps = {
+  progress: BackupTestProgress;
+  onProgressChange: React.Dispatch<React.SetStateAction<BackupTestProgress>>;
+};
+
+const BURST_EMOJIS = ["🎉", "✨", "🐝", "🍯", "🔑", "💛"] as const;
+const BURST_PARTICLE_COUNT = 18;
+
+type BurstParticle = {
+  id: number;
+  x: number;
+  y: number;
+  emoji: string;
+  delay: number;
+  scale: number;
+  rotate: number;
+};
+
+/**
+ * One-shot radial emoji burst behind the success badge. Purely decorative —
+ * skipped entirely under reduced motion.
+ */
+function SuccessBurst() {
+  const particles = React.useMemo<BurstParticle[]>(
+    () =>
+      Array.from({ length: BURST_PARTICLE_COUNT }, (_, i) => {
+        const angle =
+          (i / BURST_PARTICLE_COUNT) * Math.PI * 2 + Math.random() * 0.5;
+        const distance = 70 + Math.random() * 80;
+        return {
+          id: i,
+          x: Math.cos(angle) * distance,
+          y: Math.sin(angle) * distance,
+          emoji: BURST_EMOJIS[i % BURST_EMOJIS.length],
+          delay: Math.random() * 0.18,
+          scale: 0.8 + Math.random() * 0.7,
+          rotate: -120 + Math.random() * 240,
+        };
+      }),
+    [],
+  );
+
+  return (
+    <div
+      aria-hidden
+      className="pointer-events-none absolute inset-0 flex items-center justify-center overflow-visible"
+    >
+      {particles.map((particle) => (
+        <motion.span
+          animate={{
+            x: particle.x,
+            y: particle.y,
+            opacity: 0,
+            scale: particle.scale,
+            rotate: particle.rotate,
+          }}
+          className="absolute text-xl"
+          initial={{ x: 0, y: 0, opacity: 1, scale: 0.3, rotate: 0 }}
+          key={particle.id}
+          transition={{
+            duration: 0.9,
+            delay: particle.delay,
+            ease: "easeOut",
+          }}
+        >
+          {particle.emoji}
+        </motion.span>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * "Test your backup" flow: the user drops a backup file onto a large
+ * dropzone, then enters its password. Verification is a real NIP-49 decrypt
+ * in Rust — the submitted password is cleared immediately after the result
+ * and only the derived public identity ever comes back.
+ */
+export function BackupTestFlow({
+  progress,
+  onProgressChange,
+}: BackupTestFlowProps) {
+  const reduceMotion = useReducedMotion() ?? false;
+  const { stage, fileName, ncryptsec, result } = progress;
+  // True while a file drag is anywhere over the window — the drop overlay
+  // takes over the host surface only for the duration of the drag.
+  const [isWindowDragging, setIsWindowDragging] = React.useState(false);
+  const dragDepthRef = React.useRef(0);
+
+  React.useEffect(() => {
+    // dragenter/dragleave fire per nested element, so track depth to know
+    // when the drag has actually left the window.
+    const handleDragEnter = (event: DragEvent) => {
+      if (!event.dataTransfer?.types.includes("Files")) return;
+      dragDepthRef.current += 1;
+      setIsWindowDragging(true);
+    };
+    const handleDragLeave = () => {
+      dragDepthRef.current = Math.max(0, dragDepthRef.current - 1);
+      if (dragDepthRef.current === 0) setIsWindowDragging(false);
+    };
+    const handleDragEnd = () => {
+      dragDepthRef.current = 0;
+      setIsWindowDragging(false);
+    };
+    window.addEventListener("dragenter", handleDragEnter);
+    window.addEventListener("dragleave", handleDragLeave);
+    window.addEventListener("drop", handleDragEnd);
+    window.addEventListener("dragend", handleDragEnd);
+    return () => {
+      window.removeEventListener("dragenter", handleDragEnter);
+      window.removeEventListener("dragleave", handleDragLeave);
+      window.removeEventListener("drop", handleDragEnd);
+      window.removeEventListener("dragend", handleDragEnd);
+    };
+  }, []);
+
+  // The password attempt is component-local, never host state: it is cleared
+  // when verification is submitted and when this component unmounts.
+  const [attempt, setAttempt] = React.useState("");
+  const [error, setError] = React.useState<string | null>(null);
+  const [isVerifying, setIsVerifying] = React.useState(false);
+  const [isRevealed, setIsRevealed] = React.useState(false);
+  const fileInputRef = React.useRef<HTMLInputElement | null>(null);
+  const passwordInputRef = React.useRef<HTMLInputElement | null>(null);
+  const mountedRef = React.useRef(true);
+  // Opaque correlation id so a stale in-flight verification can't commit
+  // after "Use a different file" or unmount.
+  const requestRef = React.useRef(0);
+
+  React.useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      requestRef.current += 1;
+      setAttempt("");
+    };
+  }, []);
+
+  React.useEffect(() => {
+    if (stage === "password") passwordInputRef.current?.focus();
+  }, [stage]);
+
+  const handleFile = React.useCallback(
+    async (file: File) => {
+      let text: string;
+      try {
+        text = (await file.text()).trim();
+      } catch {
+        if (mountedRef.current) setError("Could not read that file.");
+        return;
+      }
+      if (!mountedRef.current) return;
+      if (!text.toLowerCase().startsWith("ncryptsec1")) {
+        setError("That doesn't look like a key backup file.");
+        return;
+      }
+      setError(null);
+      setAttempt("");
+      onProgressChange({
+        stage: "password",
+        fileName: file.name,
+        ncryptsec: text,
+        result: null,
+      });
+    },
+    [onProgressChange],
+  );
+
+  const handleVerify = React.useCallback(async () => {
+    if (!ncryptsec || !attempt || isVerifying) return;
+    const password = attempt;
+    const requestId = ++requestRef.current;
+    setIsVerifying(true);
+    setError(null);
+    setIsRevealed(false);
+    // Clear the attempt the moment it's handed to Rust — success or failure,
+    // the typed password never lingers in the field.
+    setAttempt("");
+    try {
+      const verified = await verifyNcryptsecBackup(ncryptsec, password);
+      if (!mountedRef.current || requestId !== requestRef.current) return;
+      onProgressChange((prev) => ({
+        ...prev,
+        stage: "success",
+        result: verified,
+      }));
+    } catch (err) {
+      if (mountedRef.current && requestId === requestRef.current)
+        setError(
+          err instanceof Error ? err.message : "Could not verify this backup.",
+        );
+    } finally {
+      if (mountedRef.current && requestId === requestRef.current)
+        setIsVerifying(false);
+    }
+  }, [attempt, isVerifying, ncryptsec, onProgressChange]);
+
+  if (stage === "success" && result) {
+    return (
+      <div
+        className="relative flex flex-col items-center gap-4 py-4 text-center"
+        data-testid="backup-test-success"
+      >
+        {reduceMotion ? null : <SuccessBurst />}
+        <motion.div
+          animate={{ scale: 1, opacity: 1 }}
+          className="flex h-16 w-16 items-center justify-center rounded-full bg-primary text-primary-foreground"
+          initial={reduceMotion ? false : { scale: 0, opacity: 0 }}
+          transition={
+            reduceMotion
+              ? { duration: 0 }
+              : { type: "spring", stiffness: 380, damping: 18 }
+          }
+        >
+          <Check aria-hidden="true" className="h-8 w-8" strokeWidth={3} />
+        </motion.div>
+        <motion.div
+          animate={{ opacity: 1, y: 0 }}
+          initial={reduceMotion ? false : { opacity: 0, y: 8 }}
+          transition={
+            reduceMotion ? { duration: 0 } : { delay: 0.15, duration: 0.35 }
+          }
+        >
+          <p className="text-lg font-medium text-foreground">
+            This backup works
+          </p>
+          <p className="mt-1.5 text-sm leading-6 text-muted-foreground">
+            {result.matchesCurrentIdentity
+              ? "It restores your current Buzz identity."
+              : "It restores a different identity than the one signed in here."}
+          </p>
+          <div className="mt-3 flex justify-center">
+            <PubKey
+              pubkey={result.pubkey}
+              testId="backup-test-npub"
+              variant="full"
+            />
+          </div>
+        </motion.div>
+        <Button
+          className="h-8 rounded-full px-4 text-xs text-muted-foreground hover:text-foreground"
+          data-testid="backup-test-another"
+          onClick={() => {
+            setError(null);
+            onProgressChange(initialBackupTestProgress);
+          }}
+          type="button"
+          variant="ghost"
+        >
+          Test another backup
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="mx-auto w-full max-w-125 space-y-4"
+      data-testid="backup-test-flow"
+    >
+      {stage === "drop" ? (
+        <>
+          <input
+            accept=".ncryptsec,text/plain"
+            className="sr-only"
+            data-testid="backup-test-file-input"
+            onChange={(event) => {
+              const file = event.target.files?.[0];
+              // Allow re-selecting the same file after an error.
+              event.target.value = "";
+              if (file) void handleFile(file);
+            }}
+            ref={fileInputRef}
+            tabIndex={-1}
+            type="file"
+          />
+          <button
+            className="mx-auto flex h-9 items-center justify-center rounded-full bg-primary px-6 text-center text-primary-foreground shadow transition-colors hover:bg-primary/90"
+            data-testid="backup-test-dropzone"
+            onClick={() => fileInputRef.current?.click()}
+            type="button"
+          >
+            <span className="text-sm font-medium">Select your backup file</span>
+          </button>
+          {isWindowDragging ? (
+            /*
+             * Composer-style takeover: fills the nearest positioned host
+             * surface (the settings backup row) and is
+             * itself the drop target, so anywhere on that surface accepts
+             * the file.
+             */
+            // biome-ignore lint/a11y/noStaticElementInteractions: pointer-only drop target; the select button is the keyboard-accessible path
+            <div
+              className="absolute inset-2 z-10 mt-0! flex items-center justify-center rounded-2xl border-2 border-dashed border-primary bg-primary/10 backdrop-blur-sm"
+              data-testid="backup-test-drop-overlay"
+              onDragOver={(event) => event.preventDefault()}
+              onDrop={(event) => {
+                event.preventDefault();
+                const file = event.dataTransfer.files?.[0];
+                if (file) void handleFile(file);
+              }}
+            >
+              <span className="flex items-center gap-2 rounded-full bg-foreground px-4 py-2 text-sm font-semibold text-background shadow-sm ring-1 ring-background/15">
+                <FileUp aria-hidden="true" className="size-4" />
+                <span>Drop your backup file here</span>
+              </span>
+            </div>
+          ) : null}
+          {error ? (
+            <p
+              className="text-center text-sm text-destructive"
+              data-testid="backup-test-error"
+              role="alert"
+            >
+              {error}
+            </p>
+          ) : null}
+        </>
+      ) : (
+        <>
+          <div
+            className="flex items-center justify-center gap-2 text-sm text-foreground animate-in fade-in slide-in-from-bottom-1 duration-300 motion-reduce:animate-none"
+            data-testid="backup-test-file-accepted"
+          >
+            <FileKey2
+              aria-hidden="true"
+              className="h-4 w-4 text-muted-foreground"
+            />
+            <span className="max-w-70 truncate font-mono text-xs">
+              {fileName}
+            </span>
+            <Check aria-hidden="true" className="h-4 w-4 text-primary" />
+          </div>
+          <p className="text-center text-sm leading-6 text-muted-foreground">
+            That's the one. Now enter your password to prove you can unlock it.
+          </p>
+          <div className="relative">
+            <Input
+              aria-label="Backup password"
+              autoComplete="off"
+              className="h-10 bg-background pr-10 font-mono"
+              data-testid="backup-test-password"
+              disabled={isVerifying}
+              onChange={(event) => setAttempt(event.target.value)}
+              onKeyDown={(event) => {
+                if (event.key === "Enter") {
+                  event.preventDefault();
+                  void handleVerify();
+                }
+              }}
+              placeholder="Your backup password"
+              ref={passwordInputRef}
+              type={isRevealed ? "text" : "password"}
+              value={attempt}
+            />
+            <Button
+              aria-label={isRevealed ? "Hide password" : "Reveal password"}
+              className="absolute right-1 top-1/2 h-8 w-8 -translate-y-1/2 text-muted-foreground hover:text-foreground"
+              data-testid="backup-test-password-reveal-toggle"
+              disabled={isVerifying}
+              onClick={() => setIsRevealed((revealed) => !revealed)}
+              size="icon"
+              type="button"
+              variant="ghost"
+            >
+              {isRevealed ? (
+                <EyeOff aria-hidden="true" className="h-4 w-4" />
+              ) : (
+                <Eye aria-hidden="true" className="h-4 w-4" />
+              )}
+            </Button>
+            {error ? (
+              <p
+                className="absolute left-1 top-full mt-1 text-xs text-destructive animate-in fade-in duration-200 motion-reduce:animate-none"
+                data-testid="backup-test-error"
+                role="alert"
+              >
+                {error}
+              </p>
+            ) : null}
+          </div>
+          <div className="flex items-center justify-center gap-3 pt-2">
+            <Button
+              className="h-9 rounded-full bg-primary px-6 text-sm font-medium text-primary-foreground shadow transition-colors hover:bg-primary/90"
+              data-testid="backup-test-verify"
+              disabled={!attempt || isVerifying}
+              onClick={() => void handleVerify()}
+              type="button"
+            >
+              {isVerifying ? (
+                <>
+                  <Spinner className="h-4 w-4 border-2" />
+                  Checking…
+                </>
+              ) : (
+                "Verify backup"
+              )}
+            </Button>
+            <Button
+              className="h-7 px-2 text-xs text-muted-foreground hover:text-foreground"
+              data-testid="backup-test-use-different-file"
+              disabled={isVerifying}
+              onClick={() => {
+                requestRef.current += 1;
+                setAttempt("");
+                setError(null);
+                setIsRevealed(false);
+                onProgressChange(initialBackupTestProgress);
+              }}
+              size="sm"
+              type="button"
+              variant="ghost"
+            >
+              Use a different file
+            </Button>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}
diff --git a/desktop/src/features/settings/ui/EncryptedBackupCreator.tsx b/desktop/src/features/settings/ui/EncryptedBackupCreator.tsx
new file mode 100644
index 0000000000..fb20eb9c65
--- /dev/null
+++ b/desktop/src/features/settings/ui/EncryptedBackupCreator.tsx
@@ -0,0 +1,375 @@
+import { AlertTriangle, Eye, EyeOff, RefreshCw } from "lucide-react";
+import * as React from "react";
+
+import { generateBackupPassphrase } from "@/shared/api/tauriIdentity";
+import { useEncryptedBackup } from "@/features/settings/EncryptedBackupProvider";
+import { Button } from "@/shared/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/shared/ui/dialog";
+import { Input } from "@/shared/ui/input";
+import { Popover, PopoverAnchor, PopoverContent } from "@/shared/ui/popover";
+import { downloadDisabled, MIN_PASSPHRASE_LEN } from "../lib/encryptedBackup";
+
+/** Word-count bounds mirroring `key_backup.rs` (Rust clamps regardless). */
+const MIN_GENERATED_WORDS = 3;
+const MAX_GENERATED_WORDS = 10;
+const DEFAULT_GENERATED_WORDS = 3;
+
+const SEPARATOR_OPTIONS = [
+  { label: "Spaces", value: " " },
+  { label: "Hyphens", value: "-" },
+  { label: "Periods", value: "." },
+  { label: "Commas", value: "," },
+] as const;
+
+const DEFAULT_SEPARATOR = SEPARATOR_OPTIONS[0].value;
+
+/**
+ * Indeterminate KDF progress. Scrypt does not expose intermediate progress,
+ * so randomized increments consume a shrinking fraction of the remaining
+ * distance. The bar moves quickly at first and can never reach completion.
+ */
+function FakeKdfProgressBar() {
+  const [progress, setProgress] = React.useState(0);
+
+  React.useEffect(() => {
+    let animationFrame = 0;
+    let nextAdvanceAt = 0;
+    const advance = (now: number) => {
+      if (now >= nextAdvanceAt) {
+        setProgress((current) => {
+          const remaining = 90 - current;
+          const fraction = 0.08 + Math.random() * 0.22;
+          return Math.min(90, current + Math.max(0.25, remaining * fraction));
+        });
+        nextAdvanceAt = now + 180 + Math.random() * 420;
+      }
+      animationFrame = window.requestAnimationFrame(advance);
+    };
+    animationFrame = window.requestAnimationFrame(advance);
+    return () => window.cancelAnimationFrame(animationFrame);
+  }, []);
+
+  return (
+    <div
+      aria-label="Encrypting your key"
+      aria-valuemax={100}
+      aria-valuemin={0}
+      aria-valuenow={Math.round(progress)}
+      className="h-2 w-full overflow-hidden rounded-full bg-muted"
+      data-testid="encrypted-backup-progress"
+      role="progressbar"
+    >
+      <div
+        className="h-full rounded-full bg-primary transition-[width] duration-300 ease-out motion-reduce:transition-none"
+        style={{ width: `${progress}%` }}
+      />
+    </div>
+  );
+}
+
+/**
+ * 1Password-style memorable-password generator popover with word-count and
+ * separator fields, anchored to a refresh icon inset in the password field
+ * (the anchor assumes a `relative` parent). The first click opens the
+ * popover and generates; further clicks on the icon re-roll while the
+ * popover stays open — only click-outside or Esc closes it. There is no
+ * candidate preview: every generation writes the passphrase straight into
+ * the parent's password field via `onGenerated`.
+ */
+function PassphraseGeneratorPopover({
+  disabled = false,
+  onRequestGenerate,
+  onGenerated,
+}: {
+  disabled?: boolean;
+  onRequestGenerate?: () => void;
+  onGenerated: (value: string) => void;
+}) {
+  const [open, setOpen] = React.useState(false);
+  const [words, setWords] = React.useState(DEFAULT_GENERATED_WORDS);
+  const [separator, setSeparator] = React.useState<string>(DEFAULT_SEPARATOR);
+  const [error, setError] = React.useState<string | null>(null);
+  const anchorRef = React.useRef<HTMLButtonElement | null>(null);
+  const mountedRef = React.useRef(true);
+  // Read via a ref so `generate` stays reference-stable even though parents
+  // pass an inline `onGenerated`. Otherwise each generated password would
+  // re-render the parent, rebuild `generate`, and re-fire the open/controls
+  // effect below — an infinite generate loop while the popover is open.
+  const onGeneratedRef = React.useRef(onGenerated);
+
+  React.useEffect(() => {
+    onGeneratedRef.current = onGenerated;
+  }, [onGenerated]);
+
+  React.useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const generate = React.useCallback(async (wordCount: number, sep: string) => {
+    setError(null);
+    try {
+      const passphrase = await generateBackupPassphrase({
+        words: wordCount,
+        separator: sep,
+      });
+      if (mountedRef.current) onGeneratedRef.current(passphrase);
+    } catch (err) {
+      if (!mountedRef.current) return;
+      setError(
+        err instanceof Error ? err.message : "Failed to generate a password.",
+      );
+    }
+  }, []);
+
+  // Fill the password field on every open and whenever a control changes.
+  React.useEffect(() => {
+    if (open) void generate(words, separator);
+  }, [open, words, separator, generate]);
+
+  return (
+    <Popover onOpenChange={setOpen} open={open}>
+      {/* Anchor (not Trigger): Radix triggers toggle on click, but repeat
+          clicks here must generate a fresh password while the popover stays
+          open. Only click-outside or Esc closes it. */}
+      <PopoverAnchor asChild>
+        <Button
+          aria-label="Generate a password"
+          className="absolute right-9 top-1/2 h-8 w-8 -translate-y-1/2 text-muted-foreground hover:text-foreground"
+          data-testid="backup-passphrase-generate"
+          disabled={disabled}
+          onClick={() => {
+            // The open effect below generates the first password; later
+            // clicks re-roll with the current controls.
+            if (onRequestGenerate) {
+              onRequestGenerate();
+              return;
+            }
+            if (!open) setOpen(true);
+            else void generate(words, separator);
+          }}
+          ref={anchorRef}
+          size="icon"
+          type="button"
+          variant="ghost"
+        >
+          <RefreshCw className="h-4 w-4" aria-hidden="true" />
+        </Button>
+      </PopoverAnchor>
+      <PopoverContent
+        align="end"
+        className="w-72 space-y-3"
+        onInteractOutside={(event) => {
+          // Clicking the anchor icon is "outside" the content — keep the
+          // popover open so that click re-rolls instead of closing.
+          if (
+            event.target instanceof Node &&
+            anchorRef.current?.contains(event.target)
+          ) {
+            event.preventDefault();
+          }
+        }}
+        onOpenAutoFocus={(event) => event.preventDefault()}
+      >
+        <div className="flex items-center justify-between gap-4">
+          <label
+            className="text-sm text-muted-foreground"
+            htmlFor="backup-passphrase-words"
+          >
+            Words
+          </label>
+          <div className="flex flex-1 items-center justify-end gap-3">
+            <input
+              className="h-1.5 w-full max-w-30 cursor-pointer appearance-none rounded-full bg-foreground/15 accent-primary"
+              id="backup-passphrase-words"
+              data-testid="backup-passphrase-words"
+              max={MAX_GENERATED_WORDS}
+              min={MIN_GENERATED_WORDS}
+              onChange={(event) => setWords(Number(event.target.value))}
+              type="range"
+              value={words}
+            />
+            <span className="w-6 text-right text-sm tabular-nums text-foreground">
+              {words}
+            </span>
+          </div>
+        </div>
+
+        <div className="flex items-center justify-between gap-4">
+          <label
+            className="text-sm text-muted-foreground"
+            htmlFor="backup-passphrase-separator"
+          >
+            Separator
+          </label>
+          <select
+            className="h-8 rounded-lg border border-border bg-background px-2 text-sm text-foreground outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
+            id="backup-passphrase-separator"
+            data-testid="backup-passphrase-separator"
+            onChange={(event) => setSeparator(event.target.value)}
+            value={separator}
+          >
+            {SEPARATOR_OPTIONS.map((option) => (
+              <option key={option.label} value={option.value}>
+                {option.label}
+              </option>
+            ))}
+          </select>
+        </div>
+
+        {error ? (
+          <p
+            className="flex items-start gap-1.5 text-xs text-destructive"
+            data-testid="backup-passphrase-generate-error"
+          >
+            <AlertTriangle className="mt-0.5 h-3.5 w-3.5 shrink-0" />
+            {error}
+          </p>
+        ) : null}
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+/**
+ * Password-first encrypted key download flow for Settings. The raw private
+ * key never enters this component. Rust creates the
+ * NIP-49 payload locally, then the native save dialog produces the user-owned
+ * file.
+ *
+ * The flow is a single password input; a refresh icon inset in the field
+ * opens a 1Password-style generator popover (word count + separator).
+ * Encryption starts eagerly once the password is valid, so Download usually
+ * opens the save dialog instantly; clicking mid-encryption queues the
+ * download until the KDF finishes.
+ */
+export function EncryptedBackupCreator({
+  onOpenChange,
+  open,
+}: {
+  onOpenChange: (open: boolean) => void;
+  open: boolean;
+}) {
+  const { state, dispatch, isSaving, saveError } = useEncryptedBackup();
+  const [isRevealed, setIsRevealed] = React.useState(false);
+
+  // A queued download hides the form; mask the password before it can return
+  // in any error state.
+  React.useEffect(() => {
+    if (state.downloadPending) setIsRevealed(false);
+  }, [state.downloadPending]);
+
+  React.useEffect(() => {
+    if (state.ncryptsec) onOpenChange(false);
+  }, [onOpenChange, state.ncryptsec]);
+
+  return (
+    <Dialog onOpenChange={onOpenChange} open={open}>
+      <DialogContent className="max-w-lg" data-testid="encrypted-backup-dialog">
+        <DialogHeader className="pr-8">
+          <DialogTitle>Create a key backup</DialogTitle>
+          <DialogDescription>
+            You can close this window while Buzz finishes the backup in the
+            background.
+          </DialogDescription>
+        </DialogHeader>
+        <div
+          className="w-full space-y-3 text-left"
+          data-testid="encrypted-backup-creator"
+        >
+          {state.downloadPending ? (
+            <FakeKdfProgressBar />
+          ) : !state.savedPassword ? (
+            <div className="relative">
+              <Input
+                aria-label="Encryption password"
+                autoComplete="new-password"
+                className="h-10 bg-background pr-19"
+                data-testid="backup-passphrase-input"
+                onChange={(event) =>
+                  dispatch({
+                    type: "set-passphrase",
+                    value: event.target.value,
+                  })
+                }
+                placeholder={`Password (min ${MIN_PASSPHRASE_LEN} characters)`}
+                type={isRevealed ? "text" : "password"}
+                value={state.passphrase}
+              />
+              <Button
+                aria-label={isRevealed ? "Hide password" : "Reveal password"}
+                className="absolute right-1 top-1/2 h-8 w-8 -translate-y-1/2 text-muted-foreground hover:text-foreground"
+                data-testid="backup-passphrase-reveal-toggle"
+                onClick={() => setIsRevealed((revealed) => !revealed)}
+                size="icon"
+                type="button"
+                variant="ghost"
+              >
+                {isRevealed ? (
+                  <EyeOff className="h-4 w-4" aria-hidden="true" />
+                ) : (
+                  <Eye className="h-4 w-4" aria-hidden="true" />
+                )}
+              </Button>
+              <PassphraseGeneratorPopover
+                onGenerated={(value) => {
+                  dispatch({ type: "set-passphrase", value });
+                  // A generated password must be visible so the user can save it.
+                  setIsRevealed(true);
+                }}
+              />
+            </div>
+          ) : null}
+
+          {!state.downloadPending && !state.savedPassword ? (
+            <p className="text-xs leading-5 text-muted-foreground">
+              Keep the file private and save its password somewhere safe — Buzz
+              cannot reset it. Once ready, the backup remains available to
+              download for 5 minutes.
+            </p>
+          ) : null}
+
+          {state.createError && state.passphrase.length === 0 ? (
+            <p
+              className="text-center text-sm text-destructive"
+              data-testid="encrypted-backup-create-error"
+            >
+              {state.createError}
+            </p>
+          ) : null}
+
+          {saveError ? (
+            <p
+              className="text-center text-sm text-destructive"
+              data-testid="encrypted-backup-save-error"
+            >
+              {saveError}
+            </p>
+          ) : null}
+
+          {!state.downloadPending ? (
+            <div className="flex justify-end">
+              <Button
+                className="h-9 rounded-full px-6"
+                data-testid="encrypted-backup-create"
+                disabled={downloadDisabled(state) || isSaving}
+                onClick={() => dispatch({ type: "download-clicked" })}
+                type="button"
+              >
+                Backup key
+              </Button>
+            </div>
+          ) : null}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/desktop/src/features/settings/ui/HarnessCatalogDialog.tsx b/desktop/src/features/settings/ui/HarnessCatalogDialog.tsx
index 2bc689e9e8..8511d26d57 100644
--- a/desktop/src/features/settings/ui/HarnessCatalogDialog.tsx
+++ b/desktop/src/features/settings/ui/HarnessCatalogDialog.tsx
@@ -6,6 +6,7 @@ import {
   useAcpRuntimesQuery,
   useInstallAcpRuntimeMutation,
 } from "@/features/agents/hooks";
+import { useInstallOutputLine } from "@/features/agents/lib/useInstallOutputLine";
 import {
   getRuntimeDisplayLabel,
   RuntimeIcon,
@@ -399,13 +400,14 @@ function CatalogDetail({ entry }: { entry: AcpRuntimeCatalogEntry }) {
   const description = harnessDescription(entry.id);
   const isReady = entry.availability === "available";
   const docsUrl = entry.installInstructionsUrl.trim();
+  const installOutputLine = useInstallOutputLine(entry.id, install.isPending);
 
   function handleInstall() {
     setInstallError(null);
     install.mutate(entry.id, {
       onSuccess: (result) => {
         if (!result.success) {
-          setInstallError(getInstallErrorMessage(result.steps));
+          setInstallError(getInstallErrorMessage(result));
         }
       },
       onError: (error) => {
@@ -502,6 +504,16 @@ function CatalogDetail({ entry }: { entry: AcpRuntimeCatalogEntry }) {
           </div>
         ) : null}
 
+        {install.isPending && installOutputLine ? (
+          <p
+            aria-live="polite"
+            className="truncate rounded-lg border border-border/60 bg-muted/40 px-3 py-1.5 font-mono text-xs text-muted-foreground"
+            data-testid={`harness-catalog-install-output-${entry.id}`}
+          >
+            {installOutputLine}
+          </p>
+        ) : null}
+
         {installError ? (
           <p className="whitespace-pre-line rounded-lg border border-destructive/30 bg-destructive/10 px-3 py-1.5 text-sm text-destructive">
             {installError}
diff --git a/desktop/src/features/settings/ui/HarnessRow.tsx b/desktop/src/features/settings/ui/HarnessRow.tsx
index de6666b8c3..c0feef13cc 100644
--- a/desktop/src/features/settings/ui/HarnessRow.tsx
+++ b/desktop/src/features/settings/ui/HarnessRow.tsx
@@ -10,6 +10,7 @@ import {
   useManagedAgentsQuery,
   usePersonasQuery,
 } from "@/features/agents/hooks";
+import { useInstallOutputLine } from "@/features/agents/lib/useInstallOutputLine";
 import { RuntimeIcon } from "@/features/onboarding/ui/RuntimeIcon";
 import type { AcpAuthMethod, AcpRuntimeCatalogEntry } from "@/shared/api/types";
 import { getInstallErrorMessage } from "@/shared/lib/installError";
@@ -324,6 +325,7 @@ export function HarnessRow({
   }, [resetEpoch]);
   const isInstalling = installMutation.isPending;
   const installError = installResult?.error ?? null;
+  const installOutputLine = useInstallOutputLine(runtime.id, isInstalling);
 
   const del = useDeleteCustomHarnessMutation();
   // Blast-radius data for the delete confirmation — only fetched while the
@@ -348,7 +350,7 @@ export function HarnessRow({
         } else {
           setInstallResult({
             success: false,
-            error: getInstallErrorMessage(result.steps),
+            error: getInstallErrorMessage(result),
           });
         }
       },
@@ -479,6 +481,15 @@ export function HarnessRow({
           </p>
         ) : null}
 
+        {isInstalling && installOutputLine ? (
+          <p
+            aria-live="polite"
+            className="mt-2 truncate rounded-lg border border-border/60 bg-background/60 px-3 py-1.5 font-mono text-xs text-muted-foreground"
+            data-testid={`doctor-runtime-install-output-${runtime.id}`}
+          >
+            {installOutputLine}
+          </p>
+        ) : null}
         {installError ? (
           <p
             className="mt-2 whitespace-pre-line rounded-lg border border-destructive/30 bg-destructive/10 px-3 py-1.5 text-sm text-destructive"
diff --git a/desktop/src/features/settings/ui/PrivateKeyBackupRow.tsx b/desktop/src/features/settings/ui/PrivateKeyBackupRow.tsx
new file mode 100644
index 0000000000..8eb0256a55
--- /dev/null
+++ b/desktop/src/features/settings/ui/PrivateKeyBackupRow.tsx
@@ -0,0 +1,215 @@
+import { Download, Eye, EyeOff, ShieldCheck } from "lucide-react";
+import * as React from "react";
+
+import { NsecMaskedDisplay } from "@/features/onboarding/ui/NsecMaskedDisplay";
+import {
+  BACKUP_AVAILABILITY_MS,
+  useEncryptedBackup,
+} from "@/features/settings/EncryptedBackupProvider";
+import {
+  BackupTestFlow,
+  initialBackupTestProgress,
+} from "@/features/settings/ui/BackupTestFlow";
+import { EncryptedBackupCreator } from "@/features/settings/ui/EncryptedBackupCreator";
+import { getNsec } from "@/shared/api/tauriIdentity";
+import { Button } from "@/shared/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/shared/ui/dialog";
+
+function BackupAvailabilityFill({
+  availableUntil,
+}: {
+  availableUntil: number;
+}) {
+  const [{ durationMs, initialWidth }] = React.useState(() => {
+    const remainingMs = Math.max(0, availableUntil - Date.now());
+    return {
+      durationMs: remainingMs,
+      initialWidth: Math.min(100, (remainingMs / BACKUP_AVAILABILITY_MS) * 100),
+    };
+  });
+  const [width, setWidth] = React.useState(initialWidth);
+
+  React.useEffect(() => {
+    const frame = window.requestAnimationFrame(() => setWidth(0));
+    return () => window.cancelAnimationFrame(frame);
+  }, []);
+
+  return (
+    <span
+      aria-hidden="true"
+      className="pointer-events-none absolute inset-y-0 left-0 bg-primary-foreground/15 transition-[width] ease-linear"
+      data-testid="encrypted-backup-availability-fill"
+      style={{
+        transitionDuration: `${durationMs}ms`,
+        width: `${width}%`,
+      }}
+    />
+  );
+}
+
+/**
+ * Collapsible private-key row with backup actions. The nsec is fetched only
+ * while expanded; encrypted backup state lives in the app-level provider.
+ */
+export function PrivateKeyBackupRow() {
+  const [isOpen, setIsOpen] = React.useState(false);
+  const [nsec, setNsec] = React.useState<string | null>(null);
+  const [isLoading, setIsLoading] = React.useState(false);
+  const [loadError, setLoadError] = React.useState<string | null>(null);
+  const [createOpen, setCreateOpen] = React.useState(false);
+  const [testOpen, setTestOpen] = React.useState(false);
+  const [testProgress, setTestProgress] = React.useState(
+    initialBackupTestProgress,
+  );
+  const {
+    availableUntil,
+    backupAvailable,
+    downloadBackup,
+    isSaving,
+    startNewBackup,
+  } = useEncryptedBackup();
+  const fetchCancelledRef = React.useRef(false);
+
+  React.useEffect(() => {
+    return () => {
+      fetchCancelledRef.current = true;
+      setNsec(null);
+    };
+  }, []);
+
+  async function handleReveal() {
+    if (!isOpen) {
+      fetchCancelledRef.current = false;
+      setIsOpen(true);
+      setIsLoading(true);
+      setLoadError(null);
+      try {
+        const value = await getNsec();
+        if (!fetchCancelledRef.current) setNsec(value);
+      } catch (err) {
+        if (!fetchCancelledRef.current)
+          setLoadError(
+            err instanceof Error
+              ? err.message
+              : "Failed to retrieve private key.",
+          );
+      } finally {
+        if (!fetchCancelledRef.current) setIsLoading(false);
+      }
+      return;
+    }
+
+    fetchCancelledRef.current = true;
+    setNsec(null);
+    setIsOpen(false);
+  }
+
+  function handleCreateBackup() {
+    if (backupAvailable) startNewBackup();
+    setCreateOpen(true);
+  }
+
+  function handleTestOpenChange(open: boolean) {
+    setTestOpen(open);
+    if (!open) setTestProgress(initialBackupTestProgress);
+  }
+
+  return (
+    <>
+      <div className="px-4 py-3" data-testid="profile-private-key-row">
+        <div className="flex items-center justify-between gap-4">
+          <p className="text-sm font-medium">Private key</p>
+          <div className="flex shrink-0 items-center gap-2">
+            {backupAvailable ? (
+              <Button
+                className="relative overflow-hidden rounded-full"
+                data-testid="encrypted-backup-download"
+                disabled={isSaving}
+                onClick={() => void downloadBackup()}
+                type="button"
+              >
+                {availableUntil !== null ? (
+                  <BackupAvailabilityFill availableUntil={availableUntil} />
+                ) : null}
+                <span className="relative z-10">Download backup</span>
+              </Button>
+            ) : null}
+            <Button
+              aria-label={isOpen ? "Hide private key" : "Reveal private key"}
+              className="rounded-full"
+              data-testid="profile-private-key-toggle"
+              onClick={() => void handleReveal()}
+              type="button"
+              variant="secondary"
+            >
+              {isOpen ? (
+                <>
+                  <EyeOff className="h-4 w-4 shrink-0" />
+                  Hide
+                </>
+              ) : (
+                <>
+                  <Eye className="h-4 w-4 shrink-0" />
+                  Reveal
+                </>
+              )}
+            </Button>
+          </div>
+        </div>
+        {isOpen ? (
+          <div className="mt-2">
+            {isLoading ? (
+              <p className="text-sm text-muted-foreground">Loading…</p>
+            ) : loadError ? (
+              <p className="text-sm text-destructive">{loadError}</p>
+            ) : nsec ? (
+              <NsecMaskedDisplay
+                actions={[
+                  {
+                    icon: <Download aria-hidden="true" />,
+                    label: "Create backup",
+                    onSelect: handleCreateBackup,
+                    testId: "private-key-create-backup",
+                  },
+                  {
+                    icon: <ShieldCheck aria-hidden="true" />,
+                    label: "Test backup",
+                    onSelect: () => setTestOpen(true),
+                    testId: "private-key-test-backup",
+                  },
+                ]}
+                nsec={nsec}
+              />
+            ) : null}
+          </div>
+        ) : null}
+      </div>
+      <EncryptedBackupCreator onOpenChange={setCreateOpen} open={createOpen} />
+      <Dialog onOpenChange={handleTestOpenChange} open={testOpen}>
+        <DialogContent className="max-w-lg" data-testid="backup-test-dialog">
+          <DialogHeader className="pr-8">
+            <DialogTitle>Test a key backup</DialogTitle>
+            <DialogDescription>
+              Confirm that a backup file and its password can unlock an
+              identity.
+            </DialogDescription>
+          </DialogHeader>
+          <BackupTestFlow
+            onProgressChange={setTestProgress}
+            progress={testProgress}
+          />
+          <p className="text-xs leading-5 text-muted-foreground">
+            Backups use the standard NIP-49 format, so this works for backups
+            from compatible Nostr apps too.
+          </p>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}
diff --git a/desktop/src/features/settings/ui/ProfileSettingsCard.tsx b/desktop/src/features/settings/ui/ProfileSettingsCard.tsx
index 8a1283b71c..b44abd303f 100644
--- a/desktop/src/features/settings/ui/ProfileSettingsCard.tsx
+++ b/desktop/src/features/settings/ui/ProfileSettingsCard.tsx
@@ -1,4 +1,4 @@
-import { Check, ChevronDown, Copy, Eye, EyeOff, Pencil } from "lucide-react";
+import { Check, ChevronDown, Copy, Pencil } from "lucide-react";
 import {
   AnimatePresence,
   LayoutGroup,
@@ -12,8 +12,6 @@ import {
   useProfileQuery,
   useUpdateProfileMutation,
 } from "@/features/profile/hooks";
-import { NsecMaskedDisplay } from "@/features/onboarding/ui/NsecMaskedDisplay";
-import { getNsec } from "@/shared/api/tauriIdentity";
 import { MaskedAvatarBadgeFrame } from "@/features/profile/ui/MaskedAvatarBadgeFrame";
 import { ProfileAvatar } from "@/features/profile/ui/ProfileAvatar";
 import {
@@ -24,6 +22,7 @@ import { cn } from "@/shared/lib/cn";
 import { Input } from "@/shared/ui/input";
 import { Spinner } from "@/shared/ui/spinner";
 import { Textarea } from "@/shared/ui/textarea";
+import { PrivateKeyBackupRow } from "./PrivateKeyBackupRow";
 import { SettingsSectionHeader } from "./SettingsSectionHeader";
 import { SignOutSection } from "./SignOutSection";
 import { writeTextToClipboard } from "@/shared/lib/clipboard";
@@ -90,92 +89,6 @@ function IdentityRow({
   );
 }
 
-/**
- * Collapsible row that reveals the user's nsec on demand.
- * The nsec is fetched only when first expanded and cleared on collapse.
- */
-function NsecRevealRow() {
-  const [isOpen, setIsOpen] = React.useState(false);
-  const [nsec, setNsec] = React.useState<string | null>(null);
-  const [isLoading, setIsLoading] = React.useState(false);
-  const [loadError, setLoadError] = React.useState<string | null>(null);
-  // Guards against a late-resolving getNsec() repopulating state after Hide
-  // or after the settings panel unmounts.
-  const fetchCancelledRef = React.useRef(false);
-
-  React.useEffect(() => {
-    return () => {
-      fetchCancelledRef.current = true;
-      setNsec(null);
-    };
-  }, []);
-
-  async function handleReveal() {
-    if (!isOpen) {
-      fetchCancelledRef.current = false;
-      setIsOpen(true);
-      setIsLoading(true);
-      setLoadError(null);
-      try {
-        const value = await getNsec();
-        if (!fetchCancelledRef.current) setNsec(value);
-      } catch (err) {
-        if (!fetchCancelledRef.current)
-          setLoadError(
-            err instanceof Error
-              ? err.message
-              : "Failed to retrieve private key.",
-          );
-      } finally {
-        if (!fetchCancelledRef.current) setIsLoading(false);
-      }
-    } else {
-      // Cancel any in-flight fetch before clearing state.
-      fetchCancelledRef.current = true;
-      setNsec(null);
-      setIsOpen(false);
-    }
-  }
-
-  return (
-    <div className="px-4 py-3" data-testid="profile-private-key-row">
-      <div className="flex items-center justify-between gap-4">
-        <p className="text-sm font-medium">Private key</p>
-        <button
-          aria-label={isOpen ? "Hide private key" : "Reveal private key"}
-          className="inline-flex shrink-0 items-center gap-1.5 rounded-full bg-muted px-3 py-1.5 text-sm font-medium text-foreground transition-colors hover:bg-muted/80 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
-          data-testid="profile-private-key-toggle"
-          onClick={() => void handleReveal()}
-          type="button"
-        >
-          {isOpen ? (
-            <>
-              <EyeOff className="h-4 w-4 shrink-0" />
-              Hide
-            </>
-          ) : (
-            <>
-              <Eye className="h-4 w-4 shrink-0" />
-              Reveal
-            </>
-          )}
-        </button>
-      </div>
-      {isOpen ? (
-        <div className="mt-2">
-          {isLoading ? (
-            <p className="text-sm text-muted-foreground">Loading…</p>
-          ) : loadError ? (
-            <p className="text-sm text-destructive">{loadError}</p>
-          ) : nsec ? (
-            <NsecMaskedDisplay nsec={nsec} />
-          ) : null}
-        </div>
-      ) : null}
-    </div>
-  );
-}
-
 function EditProfileMetadataButton({
   label,
   testId,
@@ -883,7 +796,7 @@ export function ProfileSettingsCard({
                                 testId="profile-nip05"
                                 value={nip05Handle}
                               />
-                              <NsecRevealRow />
+                              <PrivateKeyBackupRow />
                             </div>
                           </details>
                         </div>
diff --git a/desktop/src/features/settings/ui/SendFeedbackDialog.tsx b/desktop/src/features/settings/ui/SendFeedbackDialog.tsx
index a0a64da8a9..fa81c34f3a 100644
--- a/desktop/src/features/settings/ui/SendFeedbackDialog.tsx
+++ b/desktop/src/features/settings/ui/SendFeedbackDialog.tsx
@@ -3,6 +3,7 @@ import * as React from "react";
 
 import { cn } from "@/shared/lib/cn";
 import { rewriteRelayUrl } from "@/shared/lib/mediaUrl";
+import { useMediaProxyPort } from "@/shared/lib/useMediaProxyPort";
 import { Button } from "@/shared/ui/button";
 import { Checkbox } from "@/shared/ui/checkbox";
 import {
@@ -83,6 +84,7 @@ export function SendFeedbackDialog({
   open: boolean;
 }) {
   const { burstEmoji } = useEmojiBurst();
+  useMediaProxyPort();
   const resolvedAttachedImageUrl = attachedImageUrl
     ? rewriteRelayUrl(attachedImageUrl)
     : null;
diff --git a/desktop/src/features/settings/ui/SettingsPanels.tsx b/desktop/src/features/settings/ui/SettingsPanels.tsx
index e74d1f3837..5c997efbc4 100644
--- a/desktop/src/features/settings/ui/SettingsPanels.tsx
+++ b/desktop/src/features/settings/ui/SettingsPanels.tsx
@@ -21,6 +21,7 @@ import {
   SunMoon,
   Ticket,
   UserRound,
+  Volume2,
   type LucideIcon,
 } from "lucide-react";
 import type {
@@ -83,10 +84,12 @@ import { SettingsOptionGroup, SettingsOptionRow } from "./SettingsOptionGroup";
 import { ProfileSettingsCard } from "./ProfileSettingsCard";
 import { UpdateChecker } from "../UpdateChecker";
 import { SettingsSectionHeader } from "./SettingsSectionHeader";
+import { VoiceSettingsCard } from "./VoiceSettingsCard";
 
 export type SettingsSection =
   | "profile"
   | "notifications"
+  | "voice"
   | "experimental"
   | "agents"
   | "channel-templates"
@@ -106,6 +109,7 @@ export const DEFAULT_SETTINGS_SECTION: SettingsSection = "profile";
 const SETTINGS_SECTION_VALUES: readonly SettingsSection[] = [
   "profile",
   "notifications",
+  "voice",
   "experimental",
   "agents",
   "channel-templates",
@@ -167,6 +171,11 @@ export const settingsSections: SettingsSectionDescriptor[] = [
     label: "Notifications",
     icon: BellRing,
   },
+  {
+    value: "voice",
+    label: "Voice",
+    icon: Volume2,
+  },
   {
     value: "experimental",
     label: "Experiments",
@@ -807,6 +816,8 @@ export function renderSettingsSection(
           onSetSoundForSlot={props.onSetSoundForSlot}
         />
       );
+    case "voice":
+      return <VoiceSettingsCard />;
     case "experimental":
       return <ExperimentalFeaturesCard />;
     case "agents":
diff --git a/desktop/src/features/settings/ui/SettingsView.tsx b/desktop/src/features/settings/ui/SettingsView.tsx
index 20389b420a..8613880571 100644
--- a/desktop/src/features/settings/ui/SettingsView.tsx
+++ b/desktop/src/features/settings/ui/SettingsView.tsx
@@ -58,6 +58,7 @@ const settingsNavGroups: Array<{
       "profile",
       "appearance",
       "notifications",
+      "voice",
       "shortcuts",
       "custom-emoji",
       "local-archive",
diff --git a/desktop/src/features/settings/ui/SignOutSection.tsx b/desktop/src/features/settings/ui/SignOutSection.tsx
index 8d4dc1c481..500875b6f0 100644
--- a/desktop/src/features/settings/ui/SignOutSection.tsx
+++ b/desktop/src/features/settings/ui/SignOutSection.tsx
@@ -31,13 +31,13 @@ export const SIGNOUT_CONFIRM_PHRASE = "wipe all my data";
  * Signing out wipes the identity key and all local data, so the confirm
  * dialog gates the delete button behind two explicit steps:
  *
- * 1. Back up the key — the nsec is shown inline (masked, with reveal/copy);
- *    the "I have saved my private key" checkbox unlocks only after the user
- *    actually reveals or copies the key.
+ * 1. Confirm recovery — Settings offers a tested password-protected backup;
+ *    the dialog also shows the raw nsec as a last-chance fallback, and the
+ *    user checks a box confirming they can restore their identity.
  * 2. Typed confirmation — the user must type the exact phrase
  *    "wipe all my data".
  *
- * Only when both gates pass does "Delete My Data" become clickable.
+ * Only when both gates pass does "Delete my data" become clickable.
  */
 export function SignOutSection() {
   const [isOpen, setIsOpen] = React.useState(false);
@@ -47,7 +47,6 @@ export function SignOutSection() {
   const [nsec, setNsec] = React.useState<string | null>(null);
   const [nsecError, setNsecError] = React.useState<string | null>(null);
   const [isNsecLoading, setIsNsecLoading] = React.useState(false);
-  const [hasInteractedWithKey, setHasInteractedWithKey] = React.useState(false);
   const [hasConfirmedBackup, setHasConfirmedBackup] = React.useState(false);
   // Guards against a late-resolving getNsec() repopulating state after the
   // dialog closes.
@@ -58,20 +57,13 @@ export function SignOutSection() {
   const isPhraseConfirmed =
     confirmText.trim().toLowerCase() === SIGNOUT_CONFIRM_PHRASE;
 
-  // The backup checkbox unlocks after real interaction with the key
-  // (reveal or copy). If the key cannot be loaded at all there is nothing to
-  // interact with — let the user proceed past the backup step rather than
-  // locking them out of sign-out entirely.
-  const isBackupGateSatisfied = hasConfirmedBackup;
-  const canConfirmBackup = hasInteractedWithKey || nsecError !== null;
-  const canDelete = isBackupGateSatisfied && isPhraseConfirmed && !isPending;
+  const canDelete = hasConfirmedBackup && isPhraseConfirmed && !isPending;
 
   function resetDialogState() {
     fetchCancelledRef.current = true;
     setNsec(null);
     setNsecError(null);
     setIsNsecLoading(false);
-    setHasInteractedWithKey(false);
     setHasConfirmedBackup(false);
     setConfirmText("");
   }
@@ -137,7 +129,8 @@ export function SignOutSection() {
           <h2 className="text-lg font-semibold tracking-tight">Sign out</h2>
           <p className="text-sm text-muted-foreground">
             Removes your identity key and all local app data from this device.
-            Back up your private key (nsec) first — this cannot be undone.
+            Before signing out, create and test a password-protected key backup
+            above — this cannot be undone.
           </p>
         </div>
         <Button
@@ -151,7 +144,7 @@ export function SignOutSection() {
           {isPending ? (
             <Spinner aria-label="Signing out" className="h-4 w-4 border-2" />
           ) : null}
-          {isPending ? "Signing out…" : "Sign Out"}
+          {isPending ? "Signing out…" : "Delete my data"}
         </Button>
       </div>
       <AlertDialog
@@ -175,7 +168,7 @@ export function SignOutSection() {
 
           <div className="space-y-3">
             <p className="text-sm font-medium">
-              1. Back up your private key (nsec)
+              1. Confirm you can restore your identity
             </p>
             {isNsecLoading ? (
               <p className="text-sm text-muted-foreground">Loading…</p>
@@ -187,10 +180,7 @@ export function SignOutSection() {
                 {nsecError}
               </p>
             ) : nsec ? (
-              <NsecMaskedDisplay
-                nsec={nsec}
-                onKeyInteraction={() => setHasInteractedWithKey(true)}
-              />
+              <NsecMaskedDisplay nsec={nsec} />
             ) : null}
             <label
               className="flex cursor-pointer items-start gap-2.5 text-sm has-[button:disabled]:cursor-not-allowed has-[button:disabled]:opacity-60"
@@ -201,19 +191,15 @@ export function SignOutSection() {
                 checked={hasConfirmedBackup}
                 className="mt-0.5"
                 data-testid="signout-backup-confirm"
-                disabled={!canConfirmBackup || isPending}
+                disabled={isPending}
                 id="signout-backup-confirm"
                 onCheckedChange={(checked) =>
                   setHasConfirmedBackup(checked === true)
                 }
               />
               <span>
-                I have saved my private key somewhere safe.
-                {!canConfirmBackup ? (
-                  <span className="block text-xs text-muted-foreground">
-                    Reveal or copy the key above first.
-                  </span>
-                ) : null}
+                I have tested a key backup or saved this private key somewhere
+                safe.
               </span>
             </label>
           </div>
@@ -257,7 +243,7 @@ export function SignOutSection() {
                   className="h-4 w-4 border-2"
                 />
               ) : null}
-              {isPending ? "Signing out…" : "Delete My Data"}
+              {isPending ? "Signing out…" : "Delete my data"}
             </Button>
           </AlertDialogFooter>
         </AlertDialogContent>
diff --git a/desktop/src/features/settings/ui/VoiceSettingsCard.tsx b/desktop/src/features/settings/ui/VoiceSettingsCard.tsx
new file mode 100644
index 0000000000..30d259fece
--- /dev/null
+++ b/desktop/src/features/settings/ui/VoiceSettingsCard.tsx
@@ -0,0 +1,374 @@
+import * as React from "react";
+import { ChevronDown, Play, Trash2, Upload, Volume2 } from "lucide-react";
+
+import { invokeTauri } from "@/shared/api/tauri";
+import { cn } from "@/shared/lib/cn";
+import { Button } from "@/shared/ui/button";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/shared/ui/alert-dialog";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuTrigger,
+} from "@/shared/ui/dropdown-menu";
+import { Switch } from "@/shared/ui/switch";
+import { SettingsOptionGroup, SettingsOptionRow } from "./SettingsOptionGroup";
+import { SettingsSectionHeader } from "./SettingsSectionHeader";
+import {
+  selectedVoiceForBackend,
+  type VoiceRegistryEntry,
+  voiceOptionLabel,
+  voicesForBackend,
+} from "./voiceSettingsLogic";
+
+export type TtsSettings = {
+  version: number;
+  agentTextToSpeech: boolean;
+  voicePreferences: string[];
+};
+
+type TtsVoiceMutation = {
+  settings: TtsSettings;
+  registry: VoiceRegistryEntry[];
+};
+
+export function VoiceSettingsCard() {
+  const [settings, setSettings] = React.useState<TtsSettings | null>(null);
+  const [registry, setRegistry] = React.useState<VoiceRegistryEntry[]>([]);
+  const [busy, setBusy] = React.useState(false);
+  const [previewing, setPreviewing] = React.useState(false);
+  const [deleteCandidate, setDeleteCandidate] =
+    React.useState<VoiceRegistryEntry | null>(null);
+  const [error, setError] = React.useState<string | null>(null);
+
+  React.useEffect(() => {
+    let disposed = false;
+    Promise.all([
+      invokeTauri<TtsSettings>("get_tts_settings"),
+      invokeTauri<VoiceRegistryEntry[]>("list_voice_registry"),
+    ])
+      .then(([nextSettings, nextRegistry]) => {
+        if (!disposed) {
+          setSettings(nextSettings);
+          setRegistry(nextRegistry);
+        }
+      })
+      .catch((loadError) => {
+        if (!disposed) {
+          setError(
+            loadError instanceof Error
+              ? loadError.message
+              : "Voice settings could not be loaded.",
+          );
+        }
+      });
+    return () => {
+      disposed = true;
+    };
+  }, []);
+
+  const saveEnabled = React.useCallback(async (enabled: boolean) => {
+    setBusy(true);
+    setError(null);
+    try {
+      const saved = await invokeTauri<TtsSettings>("set_tts_enabled", {
+        enabled,
+      });
+      setSettings(saved);
+    } catch (saveError) {
+      try {
+        const state = await invokeTauri<{ tts_enabled: boolean }>(
+          "get_huddle_state",
+        );
+        setSettings((current) =>
+          current
+            ? { ...current, agentTextToSpeech: state.tts_enabled }
+            : current,
+        );
+      } catch {
+        // Keep the last confirmed state when native reconciliation is
+        // unavailable; the visible save error makes the failure explicit.
+      }
+      setError(
+        saveError instanceof Error
+          ? saveError.message
+          : "Voice settings could not be saved.",
+      );
+    } finally {
+      setBusy(false);
+    }
+  }, []);
+
+  const savePocketVoice = React.useCallback(async (voiceKey: string) => {
+    setBusy(true);
+    setError(null);
+    try {
+      const saved = await invokeTauri<TtsSettings>("set_pocket_voice", {
+        voiceKey,
+      });
+      setSettings(saved);
+    } catch (saveError) {
+      setError(
+        saveError instanceof Error
+          ? saveError.message
+          : "Voice settings could not be saved.",
+      );
+    } finally {
+      setBusy(false);
+    }
+  }, []);
+
+  const importPocketVoice = React.useCallback(async () => {
+    setBusy(true);
+    setError(null);
+    try {
+      const result = await invokeTauri<TtsVoiceMutation | null>(
+        "import_pocket_voice",
+      );
+      if (result) {
+        setSettings(result.settings);
+        setRegistry(result.registry);
+      }
+    } catch (importError) {
+      setError(
+        importError instanceof Error
+          ? importError.message
+          : "Voice could not be imported.",
+      );
+    } finally {
+      setBusy(false);
+    }
+  }, []);
+
+  const deletePocketVoice = React.useCallback(async (voiceKey: string) => {
+    setBusy(true);
+    setError(null);
+    try {
+      const result = await invokeTauri<TtsVoiceMutation>(
+        "delete_pocket_voice",
+        { voiceKey },
+      );
+      setSettings(result.settings);
+      setRegistry(result.registry);
+      setDeleteCandidate(null);
+    } catch (deleteError) {
+      setError(
+        deleteError instanceof Error
+          ? deleteError.message
+          : "Voice could not be deleted.",
+      );
+    } finally {
+      setBusy(false);
+    }
+  }, []);
+
+  const voices = voicesForBackend(registry, "pocket");
+  const selectedVoice = selectedVoiceForBackend(
+    settings?.voicePreferences ?? [],
+    voices,
+  );
+  const enabled = settings?.agentTextToSpeech ?? true;
+  const controlsDisabled = !settings || busy || !enabled;
+
+  return (
+    <section className="min-w-0" data-testid="settings-voice">
+      <SettingsSectionHeader
+        title="Voice"
+        description="Choose whether Buzz reads new agent responses aloud during an active huddle."
+      />
+
+      <div className="flex flex-col gap-4">
+        <SettingsOptionGroup>
+          <SettingsOptionRow>
+            <div className="min-w-0">
+              <label
+                className="text-sm font-medium"
+                htmlFor="agent-text-to-speech-switch"
+              >
+                Agent text to speech
+              </label>
+              <p className="text-sm text-muted-foreground">
+                Read new agent messages aloud in the order they arrive.
+              </p>
+            </div>
+            <Switch
+              checked={enabled}
+              data-testid="agent-text-to-speech-toggle"
+              disabled={!settings || busy}
+              id="agent-text-to-speech-switch"
+              onCheckedChange={(checked) => {
+                if (settings) void saveEnabled(checked);
+              }}
+            />
+          </SettingsOptionRow>
+        </SettingsOptionGroup>
+
+        <div
+          aria-disabled={!enabled}
+          className={cn(
+            "transition-opacity",
+            !enabled && "pointer-events-none opacity-45",
+          )}
+          data-testid="pocket-voice-controls"
+        >
+          <SettingsOptionGroup>
+            <SettingsOptionRow>
+              <div className="min-w-0">
+                <p className="text-sm font-medium">Pocket TTS voice</p>
+                <p className="text-sm text-muted-foreground">
+                  Voice files stay private on this device.
+                </p>
+              </div>
+
+              <div className="flex shrink-0 items-center gap-2">
+                <DropdownMenu>
+                  <DropdownMenuTrigger asChild>
+                    <Button
+                      aria-label={`Pocket TTS voice: ${selectedVoice?.displayName ?? "Mary"}`}
+                      className="min-w-32 justify-between"
+                      data-testid="pocket-voice-selector"
+                      disabled={controlsDisabled}
+                      variant="outline"
+                    >
+                      {selectedVoice
+                        ? voiceOptionLabel(selectedVoice, voices)
+                        : "Mary"}
+                      <ChevronDown className="h-4 w-4" />
+                    </Button>
+                  </DropdownMenuTrigger>
+                  <DropdownMenuContent
+                    align="end"
+                    className="max-h-80 overflow-y-auto"
+                  >
+                    <DropdownMenuRadioGroup
+                      onValueChange={(voiceKey) => {
+                        if (settings) void savePocketVoice(voiceKey);
+                      }}
+                      value={selectedVoice?.key}
+                    >
+                      {voices.map((voice) => (
+                        <DropdownMenuRadioItem
+                          key={voice.key}
+                          value={voice.key}
+                        >
+                          {voiceOptionLabel(voice, voices)}
+                        </DropdownMenuRadioItem>
+                      ))}
+                    </DropdownMenuRadioGroup>
+                  </DropdownMenuContent>
+                </DropdownMenu>
+                <Button
+                  aria-label={`Preview ${selectedVoice?.displayName ?? "Mary"}`}
+                  data-testid="pocket-voice-preview"
+                  disabled={controlsDisabled || previewing || !selectedVoice}
+                  onClick={() => {
+                    if (!selectedVoice) return;
+                    setPreviewing(true);
+                    setError(null);
+                    void invokeTauri<void>("preview_pocket_voice", {
+                      voiceKey: selectedVoice.key,
+                    })
+                      .catch((previewError) => {
+                        setError(
+                          previewError instanceof Error
+                            ? previewError.message
+                            : "Voice preview could not be played.",
+                        );
+                      })
+                      .finally(() => setPreviewing(false));
+                  }}
+                  size="sm"
+                  variant="outline"
+                >
+                  {previewing ? (
+                    <Volume2 className="h-4 w-4 animate-pulse" />
+                  ) : (
+                    <Play className="h-4 w-4" />
+                  )}
+                  Preview
+                </Button>
+                <Button
+                  data-testid="pocket-voice-import"
+                  disabled={controlsDisabled}
+                  onClick={() => void importPocketVoice()}
+                  size="sm"
+                  variant="outline"
+                >
+                  <Upload className="h-4 w-4" />
+                  Add voice
+                </Button>
+                {selectedVoice?.key.startsWith("pocket:imported:") && (
+                  <Button
+                    aria-label={`Delete ${selectedVoice.displayName}`}
+                    data-testid="pocket-voice-delete"
+                    disabled={controlsDisabled}
+                    onClick={() => setDeleteCandidate(selectedVoice)}
+                    size="icon"
+                    variant="ghost"
+                  >
+                    <Trash2 className="h-4 w-4" />
+                  </Button>
+                )}
+              </div>
+            </SettingsOptionRow>
+          </SettingsOptionGroup>
+        </div>
+
+        {error && (
+          <p
+            className="text-sm text-destructive"
+            data-testid="voice-settings-error"
+            role="alert"
+          >
+            {error}
+          </p>
+        )}
+      </div>
+      <AlertDialog
+        onOpenChange={(open) => {
+          if (!open) setDeleteCandidate(null);
+        }}
+        open={deleteCandidate !== null}
+      >
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Delete imported voice?</AlertDialogTitle>
+            <AlertDialogDescription>
+              {deleteCandidate
+                ? `${deleteCandidate.displayName} and its local audio file will be removed.`
+                : "This imported voice and its local audio file will be removed."}
+              {selectedVoice?.key === deleteCandidate?.key &&
+                " Mary will be selected instead."}
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel disabled={busy}>Cancel</AlertDialogCancel>
+            <AlertDialogAction
+              className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
+              data-testid="confirm-pocket-voice-delete"
+              disabled={busy || !deleteCandidate}
+              onClick={(event) => {
+                event.preventDefault();
+                if (deleteCandidate) {
+                  void deletePocketVoice(deleteCandidate.key);
+                }
+              }}
+            >
+              Delete voice
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </section>
+  );
+}
diff --git a/desktop/src/features/settings/ui/harnessCatalogCopy.ts b/desktop/src/features/settings/ui/harnessCatalogCopy.ts
index 79c55f0148..9a71ff70f9 100644
--- a/desktop/src/features/settings/ui/harnessCatalogCopy.ts
+++ b/desktop/src/features/settings/ui/harnessCatalogCopy.ts
@@ -36,7 +36,7 @@ const HARNESS_DESCRIPTIONS: Record<string, string> = {
   // https://moonshotai.github.io/kimi-cli/en/
   kimi: "A terminal coding agent for software development and command-line tasks.",
   // Sources: https://ampcode.com, https://ampcode.com/manual
-  amp: "A coding agent from Sourcegraph.",
+  amp: "The coding agent and development environment that runs anywhere and everywhere.",
   // Sources: https://github.com/NousResearch/hermes-agent,
   // https://hermes-agent.nousresearch.com/docs/
   hermes: "A general-purpose AI agent from Nous Research.",
diff --git a/desktop/src/features/settings/ui/voiceSettingsLogic.test.mjs b/desktop/src/features/settings/ui/voiceSettingsLogic.test.mjs
new file mode 100644
index 0000000000..8ffc918471
--- /dev/null
+++ b/desktop/src/features/settings/ui/voiceSettingsLogic.test.mjs
@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  selectedVoiceForBackend,
+  voiceOptionLabel,
+  voicesForBackend,
+} from "./voiceSettingsLogic.ts";
+
+const voice = (key, displayName, fallbackKey = "pocket:mary") => ({
+  key,
+  displayName,
+  backend: "pocket",
+  backendName: "Pocket TTS",
+  availability: "bundled",
+  fallbackKey,
+  referenceFile: `${key}.wav`,
+  provenance: {
+    source: "bundled",
+    contentHash: null,
+    license: null,
+    sourceUrl: null,
+  },
+});
+
+test("Pocket-only V1 filters the shared registry by backend", () => {
+  const registry = [
+    voice("pocket:mary", "Mary", null),
+    { ...voice("siri:aaron", "Aaron"), backend: "siri" },
+  ];
+  assert.deepEqual(
+    voicesForBackend(registry, "pocket").map((entry) => entry.key),
+    ["pocket:mary"],
+  );
+});
+
+test("local selection uses the first compatible qualified preference", () => {
+  const voices = [
+    voice("pocket:mary", "Mary", null),
+    voice("pocket:eve", "Eve"),
+  ];
+  assert.equal(
+    selectedVoiceForBackend(["siri:aaron", "pocket:eve", "pocket:mary"], voices)
+      ?.key,
+    "pocket:eve",
+  );
+});
+
+test("duplicate display labels remain distinct by content-derived key", () => {
+  const voices = [
+    voice("pocket:imported:aaa", "Jim"),
+    voice("pocket:imported:bbb", "Jim"),
+  ];
+  assert.equal(
+    selectedVoiceForBackend(["pocket:imported:bbb"], voices)?.key,
+    "pocket:imported:bbb",
+  );
+  assert.equal(voiceOptionLabel(voices[0], voices), "Jim · aaa");
+  assert.equal(voiceOptionLabel(voices[1], voices), "Jim · bbb");
+});
diff --git a/desktop/src/features/settings/ui/voiceSettingsLogic.ts b/desktop/src/features/settings/ui/voiceSettingsLogic.ts
new file mode 100644
index 0000000000..30352f2d0f
--- /dev/null
+++ b/desktop/src/features/settings/ui/voiceSettingsLogic.ts
@@ -0,0 +1,57 @@
+export type VoiceAvailability =
+  | "bundled"
+  | "installed"
+  | "downloadable"
+  | "unavailable";
+
+export type VoiceRegistryEntry = {
+  key: string;
+  displayName: string;
+  backend: string;
+  backendName: string;
+  availability: VoiceAvailability;
+  fallbackKey: string | null;
+  referenceFile: string | null;
+  provenance: {
+    source: string;
+    contentHash: string | null;
+    license: string | null;
+    sourceUrl: string | null;
+  };
+};
+
+export function voicesForBackend(
+  registry: readonly VoiceRegistryEntry[],
+  backend: string,
+): VoiceRegistryEntry[] {
+  return registry.filter(
+    (voice) =>
+      voice.backend === backend &&
+      (voice.availability === "bundled" || voice.availability === "installed"),
+  );
+}
+
+export function selectedVoiceForBackend(
+  preferences: readonly string[],
+  voices: readonly VoiceRegistryEntry[],
+): VoiceRegistryEntry | undefined {
+  for (const key of preferences) {
+    const voice = voices.find((candidate) => candidate.key === key);
+    if (voice) return voice;
+  }
+  return voices.find((voice) => voice.fallbackKey === null) ?? voices[0];
+}
+
+export function voiceOptionLabel(
+  voice: VoiceRegistryEntry,
+  voices: readonly VoiceRegistryEntry[],
+): string {
+  const duplicateLabel = voices.some(
+    (candidate) =>
+      candidate.key !== voice.key &&
+      candidate.displayName === voice.displayName,
+  );
+  if (!duplicateLabel) return voice.displayName;
+  const identitySuffix = voice.key.split(":").at(-1)?.slice(-8) ?? voice.key;
+  return `${voice.displayName} · ${identitySuffix}`;
+}
diff --git a/desktop/src/features/sidebar/ui/SidebarProfileCard.tsx b/desktop/src/features/sidebar/ui/SidebarProfileCard.tsx
index 5db10509bf..9c6ba0f9b6 100644
--- a/desktop/src/features/sidebar/ui/SidebarProfileCard.tsx
+++ b/desktop/src/features/sidebar/ui/SidebarProfileCard.tsx
@@ -100,7 +100,7 @@ export function SidebarProfileCard({
   return (
     // biome-ignore lint/a11y/noStaticElementInteractions lint/a11y/useKeyWithClickEvents: child buttons provide keyboard access; wrapper fills pointer gaps between them.
     <div
-      className="group/profile-card cursor-pointer rounded-xl px-2 py-2 transition-colors hover:bg-sidebar-border/35 dark:hover:bg-sidebar-border/30"
+      className="group/profile-card cursor-pointer rounded-xl px-2 py-2 transition-colors hover:bg-sidebar-border/35"
       data-testid="sidebar-profile-card"
       onClick={handleCardClick}
       ref={profileCardRef}
diff --git a/desktop/src/features/sidebar/ui/useSidebarRelayConnectionCard.ts b/desktop/src/features/sidebar/ui/useSidebarRelayConnectionCard.ts
index f92e1a02e8..11f2bd1064 100644
--- a/desktop/src/features/sidebar/ui/useSidebarRelayConnectionCard.ts
+++ b/desktop/src/features/sidebar/ui/useSidebarRelayConnectionCard.ts
@@ -63,6 +63,7 @@ function isDocumentVisible() {
 export function useSidebarRelayConnectionCard(
   errorMessage?: string,
   relayUrl?: string | null,
+  relayLifecycleKey = relaySuccessKey(relayUrl),
 ) {
   const relayConnectionState = useRelayConnection();
   const hasRelayUnreachableError = errorMessage
@@ -79,7 +80,6 @@ export function useSidebarRelayConnectionCard(
     relayConnectionState === "stalled" ||
     (relayConnectionState === "disconnected" && !hasNonUnreachableError);
   const isRelayConnectionConnected = relayConnectionState === "connected";
-  const isRelayConnectionDisconnected = relayConnectionState === "disconnected";
   const [isDismissed, setIsDismissed] = React.useState(false);
   const hasSuccess = React.useSyncExternalStore(
     subscribeRelayConnectivitySuccess,
@@ -95,6 +95,8 @@ export function useSidebarRelayConnectionCard(
   const isRelayConnectionSuccess = hasSuccess && isRelayConnectionConnected;
   const canShow = isRelayConnectionActuallyDegraded || isRelayConnectionSuccess;
   const show = canShow && !isDismissed;
+  const outageActiveRef = React.useRef(false);
+  const outageRelayLifecycleKeyRef = React.useRef(relayLifecycleKey);
   const wasProblemCardVisibleRef = React.useRef(false);
   const {
     isPending: isReconnectPending,
@@ -111,30 +113,41 @@ export function useSidebarRelayConnectionCard(
     isReconnectPending || connectivityAction === "relay-connection";
 
   React.useEffect(() => {
-    if (!isRelayConnectionActuallyDegraded && !isRelayConnectionSuccess) {
+    if (outageRelayLifecycleKeyRef.current !== relayLifecycleKey) {
+      outageRelayLifecycleKeyRef.current = relayLifecycleKey;
+      outageActiveRef.current = false;
+      wasProblemCardVisibleRef.current = false;
       setIsDismissed(false);
     }
-  }, [isRelayConnectionSuccess, isRelayConnectionActuallyDegraded]);
 
-  React.useEffect(() => {
-    if (isRelayConnectionStateDegraded || isRelayConnectionDisconnected) {
-      setRelayConnectivitySuccess(relayUrl, false);
+    if (relayConnectionState === "idle") {
+      outageActiveRef.current = false;
+      wasProblemCardVisibleRef.current = false;
       setIsDismissed(false);
+      return;
     }
-  }, [isRelayConnectionDisconnected, isRelayConnectionStateDegraded, relayUrl]);
 
-  React.useEffect(() => {
     if (isRelayConnectionActuallyDegraded) {
+      if (!outageActiveRef.current) {
+        outageActiveRef.current = true;
+        setRelayConnectivitySuccess(relayUrl, false);
+        setIsDismissed(false);
+      }
       wasProblemCardVisibleRef.current = show && !isRelayConnectionSuccess;
       return;
     }
 
-    if (wasProblemCardVisibleRef.current && isRelayConnectionConnected) {
-      wasProblemCardVisibleRef.current = false;
-      setRelayConnectivitySuccess(relayUrl, true);
+    if (outageActiveRef.current && isRelayConnectionConnected) {
+      outageActiveRef.current = false;
+      if (wasProblemCardVisibleRef.current) {
+        wasProblemCardVisibleRef.current = false;
+        setRelayConnectivitySuccess(relayUrl, true);
+      }
     }
   }, [
     isRelayConnectionSuccess,
+    relayLifecycleKey,
+    relayConnectionState,
     relayUrl,
     show,
     isRelayConnectionActuallyDegraded,
diff --git a/desktop/src/shared/api/identityTypes.ts b/desktop/src/shared/api/identityTypes.ts
new file mode 100644
index 0000000000..9ae41d3345
--- /dev/null
+++ b/desktop/src/shared/api/identityTypes.ts
@@ -0,0 +1,28 @@
+export type IdentityStorage =
+  | "system-keyring"
+  | "local-file"
+  | "environment"
+  | "ephemeral";
+
+export type Identity = {
+  pubkey: string;
+  displayName: string;
+  /** Durable location of the active identity key. Older/mock bridges may omit
+   * this until they adopt identity storage reporting. */
+  storage?: IdentityStorage;
+  /** True when the app booted in "identity lost" recovery mode — the OS
+   * keyring was empty despite a prior successful migration. The frontend
+   * should route to nsec re-import instead of normal onboarding.
+   * Mutually exclusive with `locked`. */
+  lost?: boolean;
+  /** True when the app booted with an ephemeral key because the OS keyring
+   * holding the real identity is UNREACHABLE (e.g. GNOME Keyring / KWallet
+   * locked). The real key still exists; no in-app recovery is possible —
+   * the user must unlock the keyring externally and relaunch.
+   * Mutually exclusive with `lost`. */
+  locked?: boolean;
+  /** True when the boot-time Phase 2 reset attempted a wipe but verification
+   * failed. Identity resolution was skipped; the sentinel is preserved so
+   * the next relaunch retries the wipe automatically. */
+  resetFailed?: boolean;
+};
diff --git a/desktop/src/shared/api/installTypes.ts b/desktop/src/shared/api/installTypes.ts
new file mode 100644
index 0000000000..34d968b77d
--- /dev/null
+++ b/desktop/src/shared/api/installTypes.ts
@@ -0,0 +1,67 @@
+/**
+ * Result of an ACP runtime install, in both the shape Rust sends and the shape
+ * the UI consumes.
+ */
+
+export type RawInstallStepResult = {
+  step: string;
+  command: string;
+  success: boolean;
+  stdout: string;
+  stderr: string;
+  exit_code: number | null;
+  hint?: string;
+};
+
+export type RawInstallRuntimeResult = {
+  success: boolean;
+  steps: RawInstallStepResult[];
+  restarted_count: number;
+  failed_restart_count: number;
+  /** Absent for a run with no log file — Rust serializes `None` as null. */
+  log_path?: string | null;
+};
+
+export type InstallStepResult = {
+  step: string;
+  command: string;
+  success: boolean;
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  hint?: string;
+};
+
+export type InstallRuntimeResult = {
+  success: boolean;
+  steps: InstallStepResult[];
+  restartedCount: number;
+  failedRestartCount: number;
+  /**
+   * Install log file for this run, when one was written. `steps` carries only
+   * the last attempt of each step; the log holds every attempt, each record
+   * bounded far above the display truncation. Null when no log could be
+   * written — nothing then points at a file that does not exist.
+   */
+  logPath: string | null;
+};
+
+export function fromRawInstallRuntimeResult(
+  raw: RawInstallRuntimeResult,
+): InstallRuntimeResult {
+  return {
+    success: raw.success,
+    steps: raw.steps.map((step) => ({
+      step: step.step,
+      command: step.command,
+      success: step.success,
+      stdout: step.stdout,
+      stderr: step.stderr,
+      exitCode: step.exit_code,
+      hint: step.hint,
+    })),
+    restartedCount: raw.restarted_count,
+    failedRestartCount: raw.failed_restart_count,
+    logPath: raw.log_path ?? null,
+  };
+}
diff --git a/desktop/src/shared/api/readOnlyRelayClient.ts b/desktop/src/shared/api/readOnlyRelayClient.ts
index c7446f4e70..121b00c800 100644
--- a/desktop/src/shared/api/readOnlyRelayClient.ts
+++ b/desktop/src/shared/api/readOnlyRelayClient.ts
@@ -12,7 +12,7 @@ import {
   AUTH_TIMEOUT_MS,
   HISTORY_TIMEOUT_MS,
   PUBLISH_TIMEOUT_MS,
-} from "@/shared/api/relayClientSession";
+} from "@/shared/api/relayClientTimings";
 
 type PendingHistory = {
   events: RelayEvent[];
diff --git a/desktop/src/shared/api/relayChannelFilters.test.mjs b/desktop/src/shared/api/relayChannelFilters.test.mjs
index 3519c82146..503f1a5d58 100644
--- a/desktop/src/shared/api/relayChannelFilters.test.mjs
+++ b/desktop/src/shared/api/relayChannelFilters.test.mjs
@@ -6,6 +6,7 @@ import {
   buildChannelAuxFilter,
   buildChannelReactionAuxFilter,
   buildChannelStructuralAuxFilter,
+  buildHuddleTtsLiveFilter,
 } from "./relayChannelFilters.ts";
 
 const CHANNEL = "36411e44-0e2d-4cfe-bd6e-567eb169db9f";
@@ -14,6 +15,14 @@ const IDS = [
   "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
 ];
 
+test("huddle TTS filter is future-only for both message kinds", () => {
+  assert.deepEqual(buildHuddleTtsLiveFilter(CHANNEL), {
+    kinds: [9, 40002],
+    "#h": [CHANNEL],
+    limit: 0,
+  });
+});
+
 // Regression: reaction (kind:7) and reaction-removal (kind:5) events carry only
 // an `e` tag, no channel `h` tag. An `#h`-scoped aux query never matches them,
 // so removed historical reactions reappear. The aux filters must key on `#e`
diff --git a/desktop/src/shared/api/relayChannelFilters.ts b/desktop/src/shared/api/relayChannelFilters.ts
index d0c7e7938e..0d432d422e 100644
--- a/desktop/src/shared/api/relayChannelFilters.ts
+++ b/desktop/src/shared/api/relayChannelFilters.ts
@@ -6,6 +6,8 @@ import {
   KIND_DELETION,
   KIND_NIP29_DELETE_EVENT,
   KIND_REACTION,
+  KIND_STREAM_MESSAGE,
+  KIND_STREAM_MESSAGE_V2,
   KIND_STREAM_MESSAGE_EDIT,
 } from "@/shared/constants/kinds";
 import type { RelaySubscriptionFilter } from "@/shared/api/relayClientShared";
@@ -40,6 +42,17 @@ export function buildChannelFilter(
   return filter;
 }
 
+/** Strictly live huddle message filter: zero stored rows, future messages only. */
+export function buildHuddleTtsLiveFilter(
+  channelId: string,
+): RelaySubscriptionFilter {
+  return {
+    kinds: [KIND_STREAM_MESSAGE, KIND_STREAM_MESSAGE_V2],
+    "#h": [channelId],
+    limit: 0,
+  };
+}
+
 /**
  * History filter for cold-load and scrollback: message kinds *only*, so the
  * `limit` budget buys visible message depth. Auxiliary events (reactions,
diff --git a/desktop/src/shared/api/relayClientSession.ts b/desktop/src/shared/api/relayClientSession.ts
index 84ee10b68d..53d541ff0f 100644
--- a/desktop/src/shared/api/relayClientSession.ts
+++ b/desktop/src/shared/api/relayClientSession.ts
@@ -49,42 +49,30 @@ import {
   isWebSocketClose,
   shouldRefuseConnect,
   shouldScheduleReconnect,
+  shouldWaitForScheduledReconnect,
 } from "@/shared/api/relayReconnectPolicy";
+import { RelayReconnectWaiters } from "@/shared/api/relayReconnectWaiters";
 import { RelayStallWatchdog } from "@/shared/api/relayStallWatchdog";
+import {
+  AUTH_TIMEOUT_MS,
+  BACKOFF_RESET_STABLE_MS,
+  EVENT_BATCH_MS,
+  HISTORY_TIMEOUT_MS,
+  PUBLISH_TIMEOUT_MS,
+  RECONNECT_BASE_DELAY_MS,
+  RECONNECT_MAX_DELAY_MS,
+  STALL_CHECK_INTERVAL_MS,
+  STALL_IDLE_TIMEOUT_MS,
+} from "@/shared/api/relayClientTimings";
 import { closeWebSocket } from "@/shared/api/relayWebSocketClose";
 import { buildThreadReferenceTags } from "@/features/messages/lib/threading";
-const RECONNECT_BASE_DELAY_MS = 1_000,
-  RECONNECT_MAX_DELAY_MS = 30_000,
-  EVENT_BATCH_MS = 16;
-
-/**
- * Op-level timeout constants. Raised from 8 s to 25 s to survive degraded
- * networks where TLS handshakes and DNS resolution can take 3–10 s.
- */
-export const AUTH_TIMEOUT_MS = 25_000;
-export const HISTORY_TIMEOUT_MS = 25_000;
-export const PUBLISH_TIMEOUT_MS = 25_000;
-
-/**
- * The connection must remain stable for this long after a successful AUTH
- * before the reconnect backoff delay resets to its base value. Stability-
- * gated reset prevents repeated fast reconnects (flapping) from erasing the
- * backoff that throttles them.
- */
-export const BACKOFF_RESET_STABLE_MS = 60_000;
-
-/**
- * Passive liveness check. The relay sends heartbeat pings every 30s; if no
- * inbound frame arrives for two heartbeat windows, treat the socket as stalled.
- */
-const STALL_CHECK_INTERVAL_MS = 10_000;
-const STALL_IDLE_TIMEOUT_MS = 60_000;
 
 export class RelayClient {
   private wsId: number | null = null;
   private relayUrl: string | null = null;
   private connectPromise: Promise<void> | null = null;
   private reconnectTimeout: number | null = null;
+  private reconnectWaiters = new RelayReconnectWaiters();
   private reconnectDelayMs = RECONNECT_BASE_DELAY_MS;
   private keepAliveRequested = false;
   private authRequest: {
@@ -105,16 +93,6 @@ export class RelayClient {
   private stabilityTimer: number | null = null;
   private visibleChannelId: string | null = null;
 
-  /**
-   * Sticky terminal flag. Set when `resetConnection` is called with
-   * `reconnect: false` (today: auth rejection). Acts as a hard guard against
-   * the reconnect-timer / retry-wrapper paths racing back to "reconnecting"
-   * after we've already declared the session dead.
-   *
-   * Cleared only on explicit user re-engagement: `disconnect()` (community
-   * switch — the singleton is being reused for a different community) and
-   * `preconnect()` (caller is asking us to come back up).
-   */
   private terminal = false;
 
   private connectionStateEmitter = new RelayConnectionStateEmitter("idle");
@@ -127,21 +105,10 @@ export class RelayClient {
     },
   });
 
-  /**
-   * Track which channel the user is currently viewing so its subscriptions
-   * are sent first during reconnect replay — reducing visible latency on
-   * degraded networks where the relay REQ storm would otherwise delay all
-   * channels equally.
-   */
   setVisibleChannelId(id: string | null) {
     this.visibleChannelId = id;
   }
 
-  /**
-   * Cleanly tear down the connection without scheduling a reconnect.
-   * Used during community switches to reset the singleton before the
-   * new community applies.
-   */
   disconnect() {
     const error = new Error("Relay disconnected for community switch.");
 
@@ -169,6 +136,7 @@ export class RelayClient {
     }
 
     this.connectPromise = null;
+    this.reconnectWaiters.settle(error);
 
     if (this.authRequest) {
       window.clearTimeout(this.authRequest.timeout);
@@ -247,10 +215,6 @@ export class RelayClient {
     return this.fetchHistory(filter);
   }
 
-  /**
-   * Return the first event matching `filter` as soon as it arrives, without
-   * waiting for EOSE. Resolves to `null` when EOSE arrives before any event.
-   */
   async fetchFirstEvent(
     filter: RelaySubscriptionFilter,
   ): Promise<RelayEvent | null> {
@@ -462,10 +426,24 @@ export class RelayClient {
 
   async preconnect() {
     // Explicit re-engagement. If the session went terminal (auth rejection)
-    // the caller is asking us to try again, so clear the latch.
+    // the caller is asking us to try again, so clear the latch. A manual
+    // reconnect also bypasses the current delay once; ordinary operations do
+    // not, so background traffic cannot continuously defeat backoff.
     this.terminal = false;
     this.keepAliveRequested = true;
-    await this.ensureConnected();
+    if (this.reconnectTimeout !== null) {
+      window.clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+    try {
+      await this.ensureConnected();
+      this.reconnectWaiters.settle();
+    } catch (error) {
+      this.reconnectWaiters.settle(
+        this.normalizeRelayError(error, "Relay reconnect failed."),
+      );
+      throw error;
+    }
   }
 
   subscribeToReconnects(listener: () => void) {
@@ -508,9 +486,15 @@ export class RelayClient {
       return;
     }
 
-    if (this.reconnectTimeout) {
-      window.clearTimeout(this.reconnectTimeout);
-      this.reconnectTimeout = null;
+    if (
+      shouldWaitForScheduledReconnect({
+        hasPendingReconnect: this.reconnectTimeout !== null,
+      })
+    ) {
+      // The reconnect coordinator owns outage pacing. Query, publish, and
+      // subscription callers must wait for its scheduled attempt instead of
+      // clearing the timer and creating an immediate reconnect storm.
+      return this.waitForScheduledReconnect();
     }
 
     const connectPromise = this.connect();
@@ -581,8 +565,8 @@ export class RelayClient {
         this.reconnectDelayMs = RECONNECT_BASE_DELAY_MS;
       }, BACKOFF_RESET_STABLE_MS);
 
-      await this.replayLiveSubscriptions();
       this.connectionStateEmitter.set("connected");
+      await this.replayLiveSubscriptions();
       this.stallWatchdog.start();
       this.emitReconnectIfNeeded();
     } catch (error) {
@@ -964,6 +948,13 @@ export class RelayClient {
     }
   }
 
+  private waitForScheduledReconnect(): Promise<void> {
+    if (this.reconnectTimeout === null) {
+      return this.ensureConnected();
+    }
+    return this.reconnectWaiters.wait();
+  }
+
   private scheduleReconnect() {
     if (
       !shouldScheduleReconnect({
@@ -989,9 +980,14 @@ export class RelayClient {
 
     this.reconnectTimeout = window.setTimeout(() => {
       this.reconnectTimeout = null;
-      void this.ensureConnected().catch(() => {
-        this.scheduleReconnect();
-      });
+      void this.ensureConnected()
+        .then(() => this.reconnectWaiters.settle())
+        .catch((error) => {
+          this.reconnectWaiters.settle(
+            this.normalizeRelayError(error, "Relay reconnect failed."),
+          );
+          this.scheduleReconnect();
+        });
     }, delay);
   }
 
@@ -1049,6 +1045,9 @@ export class RelayClient {
       window.clearTimeout(this.reconnectTimeout);
       this.reconnectTimeout = null;
     }
+    if (options?.reconnect === false) {
+      this.reconnectWaiters.settle(error);
+    }
 
     if (this.wsId !== null) {
       void closeWebSocket(this.wsId, "connection reset");
diff --git a/desktop/src/shared/api/relayClientTimings.ts b/desktop/src/shared/api/relayClientTimings.ts
new file mode 100644
index 0000000000..dbe85a835c
--- /dev/null
+++ b/desktop/src/shared/api/relayClientTimings.ts
@@ -0,0 +1,20 @@
+export const RECONNECT_BASE_DELAY_MS = 1_000;
+export const RECONNECT_MAX_DELAY_MS = 30_000;
+export const EVENT_BATCH_MS = 16;
+
+/**
+ * Op-level timeouts tolerate degraded networks where TLS handshakes and DNS
+ * resolution can take several seconds.
+ */
+export const AUTH_TIMEOUT_MS = 25_000;
+export const HISTORY_TIMEOUT_MS = 25_000;
+export const PUBLISH_TIMEOUT_MS = 25_000;
+
+/**
+ * A stability-gated reset prevents reconnect flapping from erasing backoff.
+ */
+export const BACKOFF_RESET_STABLE_MS = 60_000;
+
+/** Passive liveness thresholds for the relay heartbeat stream. */
+export const STALL_CHECK_INTERVAL_MS = 10_000;
+export const STALL_IDLE_TIMEOUT_MS = 60_000;
diff --git a/desktop/src/shared/api/relayReconnectPolicy.test.mjs b/desktop/src/shared/api/relayReconnectPolicy.test.mjs
index 6f375fb436..e6856ede18 100644
--- a/desktop/src/shared/api/relayReconnectPolicy.test.mjs
+++ b/desktop/src/shared/api/relayReconnectPolicy.test.mjs
@@ -6,6 +6,7 @@ import {
   isWebSocketClose,
   shouldRefuseConnect,
   shouldScheduleReconnect,
+  shouldWaitForScheduledReconnect,
 } from "./relayReconnectPolicy.ts";
 
 // The "happy" baseline that *should* schedule a reconnect: not terminal,
@@ -79,6 +80,17 @@ test("keep-alive alone is enough to schedule", () => {
   );
 });
 
+test("ordinary operations wait for a scheduled reconnect instead of bypassing backoff", () => {
+  assert.equal(
+    shouldWaitForScheduledReconnect({ hasPendingReconnect: true }),
+    true,
+  );
+  assert.equal(
+    shouldWaitForScheduledReconnect({ hasPendingReconnect: false }),
+    false,
+  );
+});
+
 test("shouldRefuseConnect mirrors terminal", () => {
   assert.equal(shouldRefuseConnect({ terminal: false }), false);
   assert.equal(shouldRefuseConnect({ terminal: true }), true);
diff --git a/desktop/src/shared/api/relayReconnectPolicy.ts b/desktop/src/shared/api/relayReconnectPolicy.ts
index a2cf358216..00d8e412bd 100644
--- a/desktop/src/shared/api/relayReconnectPolicy.ts
+++ b/desktop/src/shared/api/relayReconnectPolicy.ts
@@ -37,6 +37,12 @@ export function shouldScheduleReconnect(inputs: RelayReconnectInputs): boolean {
   return true;
 }
 
+export function shouldWaitForScheduledReconnect(inputs: {
+  hasPendingReconnect: boolean;
+}): boolean {
+  return inputs.hasPendingReconnect;
+}
+
 /** Whether `ensureConnected()` should refuse with a terminal error. */
 export function shouldRefuseConnect(inputs: { terminal: boolean }): boolean {
   return inputs.terminal;
diff --git a/desktop/src/shared/api/relayReconnectReplay.test.mjs b/desktop/src/shared/api/relayReconnectReplay.test.mjs
index 54254e89de..59253a459f 100644
--- a/desktop/src/shared/api/relayReconnectReplay.test.mjs
+++ b/desktop/src/shared/api/relayReconnectReplay.test.mjs
@@ -5,6 +5,7 @@ import {
   buildReconnectReplayFilter,
   replayLiveSubscriptions,
   REPLAY_BATCH_SIZE,
+  shouldPageReconnectReplay,
 } from "./relayReconnectReplay.ts";
 import { buildChannelFilter } from "./relayChannelFilters.ts";
 
@@ -113,6 +114,31 @@ test("reconnect replay caps large steady-state limits", () => {
   });
 });
 
+test("reconnect replay preserves the live-only zero-history contract", () => {
+  const filter = {
+    kinds: [9],
+    "#h": ["channel-1"],
+    limit: 0,
+  };
+
+  assert.deepEqual(replayFilter(filter, 123), {
+    kinds: [9],
+    "#h": ["channel-1"],
+    limit: 0,
+    since: 123,
+  });
+});
+
+test("live-only subscriptions do not page reconnect history", () => {
+  const filter = {
+    kinds: [9],
+    "#h": ["channel-1"],
+    limit: 0,
+  };
+
+  assert.equal(shouldPageReconnectReplay(filter), false);
+});
+
 test("reconnect replay keeps the stricter existing since window", () => {
   const filter = {
     kinds: [9],
diff --git a/desktop/src/shared/api/relayReconnectWaiters.test.mjs b/desktop/src/shared/api/relayReconnectWaiters.test.mjs
new file mode 100644
index 0000000000..ddf3244526
--- /dev/null
+++ b/desktop/src/shared/api/relayReconnectWaiters.test.mjs
@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { RelayReconnectWaiters } from "./relayReconnectWaiters.ts";
+
+test("settle releases every operation waiting on a successful reconnect", async () => {
+  const waiters = new RelayReconnectWaiters();
+  const first = waiters.wait();
+  const second = waiters.wait();
+
+  waiters.settle();
+
+  await Promise.all([first, second]);
+});
+
+test("settle rejects every operation after a failed reconnect", async () => {
+  const waiters = new RelayReconnectWaiters();
+  const first = waiters.wait();
+  const second = waiters.wait();
+  const error = new Error("relay unavailable");
+
+  waiters.settle(error);
+
+  await assert.rejects(first, error);
+  await assert.rejects(second, error);
+});
diff --git a/desktop/src/shared/api/relayReconnectWaiters.ts b/desktop/src/shared/api/relayReconnectWaiters.ts
new file mode 100644
index 0000000000..06ad1daa3f
--- /dev/null
+++ b/desktop/src/shared/api/relayReconnectWaiters.ts
@@ -0,0 +1,21 @@
+export class RelayReconnectWaiters {
+  private waiters = new Set<{
+    resolve: () => void;
+    reject: (error: Error) => void;
+  }>();
+
+  wait(): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      this.waiters.add({ resolve, reject });
+    });
+  }
+
+  settle(error?: Error) {
+    const waiters = [...this.waiters];
+    this.waiters.clear();
+    for (const waiter of waiters) {
+      if (error) waiter.reject(error);
+      else waiter.resolve();
+    }
+  }
+}
diff --git a/desktop/src/shared/api/tauri.ts b/desktop/src/shared/api/tauri.ts
index c57525480e..69e2e455ec 100644
--- a/desktop/src/shared/api/tauri.ts
+++ b/desktop/src/shared/api/tauri.ts
@@ -3,6 +3,10 @@ import {
   activateRateLimit,
   parseRateLimitHint,
 } from "@/shared/api/relayRateLimitGate";
+import {
+  fromRawInstallRuntimeResult,
+  type RawInstallRuntimeResult,
+} from "@/shared/api/installTypes";
 import type {
   AddChannelMembersInput,
   AddChannelMembersResult,
@@ -202,22 +206,10 @@ export type RawAcpRuntimeCatalogEntry = {
   definition_env?: Record<string, string>;
 };
 
-export type RawInstallStepResult = {
-  step: string;
-  command: string;
-  success: boolean;
-  stdout: string;
-  stderr: string;
-  exit_code: number | null;
-  hint?: string;
-};
-
-export type RawInstallRuntimeResult = {
-  success: boolean;
-  steps: RawInstallStepResult[];
-  restarted_count: number;
-  failed_restart_count: number;
-};
+export type {
+  RawInstallRuntimeResult,
+  RawInstallStepResult,
+} from "./installTypes";
 
 type RawGitBashPrerequisite = {
   available: boolean;
@@ -772,25 +764,6 @@ export function fromRawAcpRuntimeCatalogEntry(
   };
 }
 
-function fromRawInstallRuntimeResult(
-  raw: RawInstallRuntimeResult,
-): InstallRuntimeResult {
-  return {
-    success: raw.success,
-    steps: raw.steps.map((step) => ({
-      step: step.step,
-      command: step.command,
-      success: step.success,
-      stdout: step.stdout,
-      stderr: step.stderr,
-      exitCode: step.exit_code,
-      hint: step.hint,
-    })),
-    restartedCount: raw.restarted_count,
-    failedRestartCount: raw.failed_restart_count,
-  };
-}
-
 function fromRawCommandAvailability(
   command: RawCommandAvailability,
 ): CommandAvailability {
diff --git a/desktop/src/shared/api/tauriIdentity.ts b/desktop/src/shared/api/tauriIdentity.ts
index e6056a4a58..161f25c211 100644
--- a/desktop/src/shared/api/tauriIdentity.ts
+++ b/desktop/src/shared/api/tauriIdentity.ts
@@ -1,9 +1,10 @@
 import { invokeTauri } from "@/shared/api/tauri";
-import type { Identity } from "@/shared/api/types";
+import type { Identity, IdentityStorage } from "@/shared/api/types";
 
 type RawIdentity = {
   pubkey: string;
   display_name: string;
+  storage?: IdentityStorage;
   lost?: boolean;
   locked?: boolean;
   reset_failed?: boolean;
@@ -13,6 +14,7 @@ function fromRawIdentity(raw: RawIdentity): Identity {
   return {
     pubkey: raw.pubkey,
     displayName: raw.display_name,
+    storage: raw.storage,
     lost: raw.lost === true,
     locked: raw.locked === true,
     resetFailed: raw.reset_failed === true,
@@ -27,9 +29,12 @@ export async function getNsec(): Promise<string> {
   return invokeTauri<string>("get_nsec");
 }
 
-export async function importIdentity(nsec: string): Promise<Identity> {
+export async function importIdentity(
+  nsec: string,
+  password?: string,
+): Promise<Identity> {
   return fromRawIdentity(
-    await invokeTauri<RawIdentity>("import_identity", { nsec }),
+    await invokeTauri<RawIdentity>("import_identity", { nsec, password }),
   );
 }
 
@@ -49,3 +54,52 @@ export async function persistCurrentIdentity(): Promise<Identity> {
 export async function signOut(): Promise<void> {
   await invokeTauri("sign_out");
 }
+
+export type GeneratePassphraseOptions = {
+  /** Word count; Rust clamps to its allowed range (currently 3–10). */
+  words?: number;
+  /** Separator joined between words. Defaults to a space in Rust. */
+  separator?: string;
+};
+
+/** Generate a word passphrase (EFF short wordlist, OS entropy) in Rust. */
+export async function generateBackupPassphrase(
+  options?: GeneratePassphraseOptions,
+): Promise<string> {
+  return invokeTauri<string>("generate_backup_passphrase", {
+    words: options?.words,
+    separator: options?.separator,
+  });
+}
+
+/** Encrypt the current identity as an in-memory NIP-49 backup for native save. */
+export async function createNcryptsecBackup(password: string): Promise<string> {
+  return invokeTauri<string>("create_ncryptsec_backup", { password });
+}
+
+/** Save a portable backup copy. Returns null when the native dialog is cancelled. */
+export async function saveNcryptsecCopy(
+  ncryptsec: string,
+): Promise<string | null> {
+  return (
+    (await invokeTauri<string | null>("save_ncryptsec_copy", { ncryptsec })) ??
+    null
+  );
+}
+
+export type BackupVerification = {
+  pubkey: string;
+  npub: string;
+  matchesCurrentIdentity: boolean;
+};
+
+/** Decrypt locally and return only the backup's public identity and match state. */
+export async function verifyNcryptsecBackup(
+  ncryptsec: string,
+  password: string,
+): Promise<BackupVerification> {
+  return invokeTauri<BackupVerification>("verify_ncryptsec_backup", {
+    ncryptsec,
+    password,
+  });
+}
diff --git a/desktop/src/shared/api/tauriPersonas.ts b/desktop/src/shared/api/tauriPersonas.ts
index 66e07f5e88..36151badbc 100644
--- a/desktop/src/shared/api/tauriPersonas.ts
+++ b/desktop/src/shared/api/tauriPersonas.ts
@@ -240,6 +240,108 @@ export async function encodeAgentSnapshotForSend(
   });
 }
 
+// ── Agent trading cards ───────────────────────────────────────────────────────
+
+/** Result of `mint_agent_card`. */
+export type MintedAgentCard = {
+  /** Final `.agent.png` bytes (chunk-injected, verified), base64-encoded. */
+  cardPngBase64: string;
+  /** Suggested filename, e.g. `eva.agent.png`. */
+  fileName: string;
+  /** Designer commentary emitted alongside the image (may be empty). */
+  designerNotes: string;
+  /** True when the embedded manifest is encrypted to the (owner, agent) pair. */
+  locked: boolean;
+  /** How much memory is embedded in the card's snapshot. */
+  memoryLevel: SnapshotMemoryLevel;
+};
+
+/** Error prefix Rust returns when no OpenAI key is configured. */
+export const NO_OPENAI_KEY_PREFIX = "NO_OPENAI_KEY:";
+
+/**
+ * Check whether an OpenAI key would resolve for a card mint of this agent
+ * (same env layering as the mint itself). Never returns the key.
+ */
+export async function cardMintKeyStatus(id: string): Promise<boolean> {
+  return invokeTauri<boolean>("card_mint_key_status", { id });
+}
+
+/**
+ * Save an OPENAI_API_KEY into the global Agent Defaults env for card minting.
+ *
+ * Narrow seam: validated read-modify-write of the single key against the
+ * latest on-disk config. Unlike the general set_global_agent_config, this
+ * NEVER restarts running agents — the mint re-reads config per call, and a
+ * card setup must not disrupt unrelated agents.
+ */
+export async function cardMintSaveOpenaiKey(key: string): Promise<void> {
+  return invokeTauri<void>("card_mint_save_openai_key", { key });
+}
+
+/**
+ * Mint a trading card for an agent. One long API call (~2–3 minutes).
+ * Reroll = call again; the backend holds no session state.
+ *
+ * When `lock` is true, the embedded manifest is NIP-44-encrypted to the
+ * (owner, agent) pair: only those two keys can import the card. Requires a
+ * linked agent instance.
+ *
+ * `memoryLevel` (default `"none"`) embeds the owner's decrypted memory in
+ * the card's snapshot — same levels as snapshot export. Levels other than
+ * `"none"` require a linked agent instance; Rust derives the memory source
+ * from the resolved instance itself.
+ */
+export async function mintAgentCard(
+  id: string,
+  styleNotes?: string,
+  lock?: boolean,
+  memoryLevel?: SnapshotMemoryLevel,
+): Promise<MintedAgentCard> {
+  return invokeTauri<MintedAgentCard>("mint_agent_card", {
+    id,
+    styleNotes: styleNotes || null,
+    lock: lock ?? null,
+    memoryLevel: memoryLevel ?? null,
+  });
+}
+
+/** Save minted card bytes to disk via the OS save dialog. */
+export async function saveAgentCard(
+  cardPngBase64: string,
+  fileName: string,
+): Promise<boolean> {
+  return invokeTauri<boolean>("save_agent_card", { cardPngBase64, fileName });
+}
+
+/** One archived (previously minted) card, as listed by `list_agent_cards`. */
+export type ArchivedAgentCard = {
+  /** On-disk archive key — pass to `loadAgentCard`. */
+  storedFileName: string;
+  /** Suggested save-as name, e.g. `eva.agent.png`. */
+  fileName: string;
+  agentId: string;
+  agentName: string;
+  designerNotes: string;
+  locked: boolean;
+  /** Memory embedded in the card's snapshot ("none" for pre-field archives). */
+  memoryLevel: SnapshotMemoryLevel;
+  /** ISO-8601 mint timestamp. */
+  mintedAt: string;
+  /** Small JPEG grid preview, base64 (absent if the thumb write failed). */
+  thumbJpegBase64: string | null;
+};
+
+/** List all archived cards, newest first. */
+export async function listAgentCards(): Promise<ArchivedAgentCard[]> {
+  return invokeTauri<ArchivedAgentCard[]>("list_agent_cards");
+}
+
+/** Load one archived card's full PNG bytes (base64) by its archive key. */
+export async function loadAgentCard(storedFileName: string): Promise<string> {
+  return invokeTauri<string>("load_agent_card", { storedFileName });
+}
+
 // ── Snapshot import ───────────────────────────────────────────────────────────
 
 /** Preview returned by `preview_agent_snapshot_import` before any write. */
@@ -258,6 +360,16 @@ export type AgentSnapshotImportPreview = {
   /** True when the snapshot's respond_to_allowlist is non-empty. */
   hasSourceAllowlist: boolean;
   sourceAllowlistCount: number;
+  /** Full source pubkeys shown before import, not only their count. */
+  sourceAllowlist: string[];
+  /** Validated, pretty-printed manifest for full payload disclosure. */
+  manifestJson: string;
+  /**
+   * True when the snapshot came from a locked (encrypted) card this machine
+   * unlocked. Cards that cannot be unlocked fail with a refusal error and
+   * never reach a preview.
+   */
+  locked: boolean;
 };
 
 /** Confirmation sent to `confirm_agent_snapshot_import`. */
diff --git a/desktop/src/shared/api/trayMenu.ts b/desktop/src/shared/api/trayMenu.ts
new file mode 100644
index 0000000000..86581e0cbf
--- /dev/null
+++ b/desktop/src/shared/api/trayMenu.ts
@@ -0,0 +1,6 @@
+import { invokeTauri } from "@/shared/api/tauri";
+
+/** Clears community-scoped agent activity from the native tray menu. */
+export function clearTrayAgentActivity(): Promise<void> {
+  return invokeTauri("clear_tray_agent_activity");
+}
diff --git a/desktop/src/shared/api/types.ts b/desktop/src/shared/api/types.ts
index 689c400b03..3f07e9ad9a 100644
--- a/desktop/src/shared/api/types.ts
+++ b/desktop/src/shared/api/types.ts
@@ -103,25 +103,7 @@ export type AddChannelMembersResult = {
   }>;
 };
 
-export type Identity = {
-  pubkey: string;
-  displayName: string;
-  /** True when the app booted in "identity lost" recovery mode — the OS
-   *  keyring was empty despite a prior successful migration. The frontend
-   *  should route to nsec re-import instead of normal onboarding.
-   *  Mutually exclusive with `locked`. */
-  lost?: boolean;
-  /** True when the app booted with an ephemeral key because the OS keyring
-   *  holding the real identity is UNREACHABLE (e.g. GNOME Keyring / KWallet
-   *  locked). The real key still exists; no in-app recovery is possible —
-   *  the user must unlock the keyring externally and relaunch.
-   *  Mutually exclusive with `lost`. */
-  locked?: boolean;
-  /** True when the boot-time Phase 2 reset attempted a wipe but verification
-   *  failed. Identity resolution was skipped; the sentinel is preserved so
-   *  the next relaunch retries the wipe automatically. */
-  resetFailed?: boolean;
-};
+export type { Identity, IdentityStorage } from "./identityTypes";
 
 export type Profile = {
   pubkey: string;
@@ -571,22 +553,10 @@ export type AcpRuntime = AcpRuntimeCatalogEntry & {
   binaryPath: string;
 };
 
-export type InstallStepResult = {
-  step: string;
-  command: string;
-  success: boolean;
-  stdout: string;
-  stderr: string;
-  exitCode: number | null;
-  hint?: string;
-};
-
-export type InstallRuntimeResult = {
-  success: boolean;
-  steps: InstallStepResult[];
-  restartedCount: number;
-  failedRestartCount: number;
-};
+export type {
+  InstallRuntimeResult,
+  InstallStepResult,
+} from "./installTypes";
 
 export type AcpAuthMethod = {
   id: string;
diff --git a/desktop/src/shared/lib/configNudge.ts b/desktop/src/shared/lib/configNudge.ts
index 82ed8f306a..86c0e16c13 100644
--- a/desktop/src/shared/lib/configNudge.ts
+++ b/desktop/src/shared/lib/configNudge.ts
@@ -32,7 +32,7 @@ export type ConfigNudgeRequirement =
        * Determines which message and CTA the nudge card shows:
        * - "available"         → tooling installed, needs login
        * - "adapter_missing"   → CLI installed but ACP adapter missing
-       * - "adapter_outdated"  → ACP adapter present but from deprecated package; reinstall required
+       * - "adapter_outdated"  → ACP adapter present but unsupported/outdated; reinstall required
        * - "cli_missing"       → ACP adapter installed but CLI missing
        * - "not_installed"     → neither adapter nor CLI found
        */
diff --git a/desktop/src/shared/lib/emojiSearch.test.mjs b/desktop/src/shared/lib/emojiSearch.test.mjs
index 93cb1e286a..01a52293f5 100644
--- a/desktop/src/shared/lib/emojiSearch.test.mjs
+++ b/desktop/src/shared/lib/emojiSearch.test.mjs
@@ -5,6 +5,7 @@ import {
   fuzzyStandardEmoji,
   normalizeShortcode,
   rankByShortcode,
+  rankShortcodeMatchesFirst,
   scoreShortcodeMatch,
 } from "./emojiSearch.ts";
 
@@ -77,6 +78,35 @@ test("rankByShortcode respects the limit", () => {
   assert.equal(ranked.length, 2);
 });
 
+test("exact shortcode matches rank ahead of weaker custom shortcode matches", () => {
+  const items = [
+    { code: "bufo_joy", source: "custom" },
+    { code: "joy", source: "standard" },
+    { code: "joy_cat", source: "custom" },
+    { code: "face_with_tears_of_joy", source: "standard" },
+  ];
+  const ranked = rankShortcodeMatchesFirst("joy", items, (item) => item.code);
+
+  assert.deepEqual(
+    ranked.map((item) => item.code),
+    ["joy", "joy_cat", "bufo_joy", "face_with_tears_of_joy"],
+  );
+});
+
+test("semantic results stay ahead of loose shortcode matches", () => {
+  const items = [
+    { code: "frowning_face", source: "semantic" },
+    { code: "sandwich", source: "custom" },
+    { code: "sad", source: "standard" },
+  ];
+  const ranked = rankShortcodeMatchesFirst("sad", items, (item) => item.code);
+
+  assert.deepEqual(
+    ranked.map((item) => item.code),
+    ["sad", "frowning_face", "sandwich"],
+  );
+});
+
 test("fuzzyStandardEmoji surfaces point_up for `pointup`", () => {
   const hits = fuzzyStandardEmoji("pointup", 8, new Set());
   const ids = hits.map((e) => e.id);
diff --git a/desktop/src/shared/lib/emojiSearch.ts b/desktop/src/shared/lib/emojiSearch.ts
index 2a0d74b9bb..ec4ea529b5 100644
--- a/desktop/src/shared/lib/emojiSearch.ts
+++ b/desktop/src/shared/lib/emojiSearch.ts
@@ -114,6 +114,33 @@ export function rankByShortcode<T>(
   return scored.slice(0, limit).map((s) => s.item);
 }
 
+/**
+ * Place exact and prefix shortcode matches ahead of items that only matched an
+ * emoji name or keyword. This lets an exact standard emoji like `joy` beat a
+ * weaker custom shortcode match such as `bufo_joy`, while retaining emoji-mart's
+ * order for name- and keyword-only results ahead of loose shortcode matches.
+ */
+export function rankShortcodeMatchesFirst<T>(
+  query: string,
+  items: readonly T[],
+  shortcodeOf: (item: T) => string,
+): T[] {
+  const strongShortcodeMatches = rankByShortcode(
+    query,
+    items,
+    shortcodeOf,
+    Number.POSITIVE_INFINITY,
+  ).filter((item) => {
+    const match = scoreShortcodeMatch(query, shortcodeOf(item));
+    return match !== null && match.tier <= TIER_PREFIX;
+  });
+  const matchedItems = new Set(strongShortcodeMatches);
+  return [
+    ...strongShortcodeMatches,
+    ...items.filter((item) => !matchedItems.has(item)),
+  ];
+}
+
 export interface StandardEmoji {
   id: string;
   name: string;
diff --git a/desktop/src/shared/lib/installError.test.mjs b/desktop/src/shared/lib/installError.test.mjs
index c6b51186a8..181d7b802b 100644
--- a/desktop/src/shared/lib/installError.test.mjs
+++ b/desktop/src/shared/lib/installError.test.mjs
@@ -3,84 +3,108 @@ import test from "node:test";
 
 import { getInstallErrorMessage } from "./installError.ts";
 
+/** A failed install result carrying `steps` and, optionally, a log pointer. */
+function failed(steps, logPath = null) {
+  return {
+    success: false,
+    steps,
+    restartedCount: 0,
+    failedRestartCount: 0,
+    logPath,
+  };
+}
+
 test("getInstallErrorMessage: empty steps array returns fallback", () => {
-  assert.equal(getInstallErrorMessage([]), "Install failed with no output.");
+  assert.equal(
+    getInstallErrorMessage(failed([])),
+    "Install failed with no output.",
+  );
 });
 
 test("getInstallErrorMessage: failed step without hint contains step name and stderr", () => {
-  const message = getInstallErrorMessage([
-    {
-      step: "adapter",
-      command: "npm install -g @block/buzz-acp",
-      success: false,
-      stdout: "",
-      stderr: "EACCES: permission denied",
-      exitCode: 1,
-    },
-  ]);
+  const message = getInstallErrorMessage(
+    failed([
+      {
+        step: "adapter",
+        command: "npm install -g @block/buzz-acp",
+        success: false,
+        stdout: "",
+        stderr: "EACCES: permission denied",
+        exitCode: 1,
+      },
+    ]),
+  );
   assert.match(message, /Step "adapter" failed:/);
   assert.match(message, /EACCES: permission denied/);
 });
 
 test("getInstallErrorMessage: failed step without hint does not contain hint-ish text", () => {
-  const message = getInstallErrorMessage([
-    {
-      step: "adapter",
-      command: "npm install -g @block/buzz-acp",
-      success: false,
-      stdout: "",
-      stderr: "EACCES: permission denied",
-      exitCode: 1,
-    },
-  ]);
+  const message = getInstallErrorMessage(
+    failed([
+      {
+        step: "adapter",
+        command: "npm install -g @block/buzz-acp",
+        success: false,
+        stdout: "",
+        stderr: "EACCES: permission denied",
+        exitCode: 1,
+      },
+    ]),
+  );
   assert.doesNotMatch(message, /npm config set prefix/);
 });
 
 test("getInstallErrorMessage: failed step with hint starts with hint and still contains stderr", () => {
   const hint =
     "Fix the npm prefix ownership:\n  sudo chown -R $USER $(npm config get prefix)";
-  const message = getInstallErrorMessage([
-    {
-      step: "adapter",
-      command: "npm install -g @block/buzz-acp",
-      success: false,
-      stdout: "",
-      stderr: "EACCES: permission denied, mkdir '/usr/local/lib'",
-      exitCode: 1,
-      hint,
-    },
-  ]);
+  const message = getInstallErrorMessage(
+    failed([
+      {
+        step: "adapter",
+        command: "npm install -g @block/buzz-acp",
+        success: false,
+        stdout: "",
+        stderr: "EACCES: permission denied, mkdir '/usr/local/lib'",
+        exitCode: 1,
+        hint,
+      },
+    ]),
+  );
   assert.ok(message.startsWith(hint), "message should start with hint");
   assert.match(message, /EACCES: permission denied/);
 });
 
 test("getInstallErrorMessage: failed step with empty stderr falls back to stdout", () => {
-  const message = getInstallErrorMessage([
-    {
-      step: "node",
-      command: "node --version",
-      success: false,
-      stdout: "some stdout output",
-      stderr: "",
-      exitCode: 1,
-    },
-  ]);
+  const message = getInstallErrorMessage(
+    failed([
+      {
+        step: "node",
+        command: "node --version",
+        success: false,
+        stdout: "some stdout output",
+        stderr: "",
+        exitCode: 1,
+      },
+    ]),
+  );
   assert.match(message, /some stdout output/);
 });
 
 test("getInstallErrorMessage: hint and step detail are separated by double newline for whitespace-pre-line rendering", () => {
   const hint = "Git Bash is required. Install it from git-scm.com.";
-  const message = getInstallErrorMessage([
-    {
-      step: "shell",
-      command: "bash -l -c 'npm install'",
-      success: false,
-      stdout: "",
-      stderr: "bash: command not found",
-      exitCode: 127,
-      hint,
-    },
-  ]);
+  const message = getInstallErrorMessage(
+    failed([
+      {
+        step: "shell",
+        command: "bash -l -c 'npm install'",
+        success: false,
+        stdout: "",
+        stderr: "bash: command not found",
+        exitCode: 127,
+        hint,
+      },
+    ]),
+  );
   assert.ok(
     message.includes("\n\n"),
     "hint and step detail should be separated by a blank line",
@@ -89,25 +113,72 @@ test("getInstallErrorMessage: hint and step detail are separated by double newli
 });
 
 test("getInstallErrorMessage: only reports the last (failing) step when multiple steps present", () => {
-  const message = getInstallErrorMessage([
-    {
-      step: "node",
-      command: "node --version",
-      success: true,
-      stdout: "v20.0.0",
-      stderr: "",
-      exitCode: 0,
-    },
-    {
-      step: "adapter",
-      command: "npm install -g @agentclientprotocol/claude-code-acp",
-      success: false,
-      stdout: "",
-      stderr: "npm ERR! code E404",
-      exitCode: 1,
-    },
-  ]);
+  const message = getInstallErrorMessage(
+    failed([
+      {
+        step: "node",
+        command: "node --version",
+        success: true,
+        stdout: "v20.0.0",
+        stderr: "",
+        exitCode: 0,
+      },
+      {
+        step: "adapter",
+        command: "npm install -g @agentclientprotocol/claude-code-acp",
+        success: false,
+        stdout: "",
+        stderr: "npm ERR! code E404",
+        exitCode: 1,
+      },
+    ]),
+  );
   assert.match(message, /Step "adapter" failed:/);
   assert.match(message, /npm ERR! code E404/);
   assert.doesNotMatch(message, /Step "node"/);
 });
+
+test("getInstallErrorMessage: points at the install log when one was written", () => {
+  const message = getInstallErrorMessage(
+    failed(
+      [
+        {
+          step: "cli",
+          command: "curl … | bash",
+          success: false,
+          stdout: "",
+          stderr: "download failed",
+          exitCode: 1,
+        },
+      ],
+      "/logs/install-goose.log",
+    ),
+  );
+  assert.match(message, /download failed/);
+  assert.ok(
+    message.endsWith("\n\nFull log: /logs/install-goose.log"),
+    `log pointer should close the message, got: ${message}`,
+  );
+});
+
+test("getInstallErrorMessage: omits the log pointer when no log was written", () => {
+  const message = getInstallErrorMessage(
+    failed([
+      {
+        step: "cli",
+        command: "curl … | bash",
+        success: false,
+        stdout: "",
+        stderr: "download failed",
+        exitCode: 1,
+      },
+    ]),
+  );
+  assert.doesNotMatch(message, /Full log/);
+});
+
+test("getInstallErrorMessage: a run with no steps at all still points at its log", () => {
+  const message = getInstallErrorMessage(failed([], "/logs/install-goose.log"));
+  assert.match(message, /Install failed with no output\./);
+  assert.match(message, /Full log: \/logs\/install-goose\.log/);
+});
diff --git a/desktop/src/shared/lib/installError.ts b/desktop/src/shared/lib/installError.ts
index bf72c4d3b2..82bcd4a310 100644
--- a/desktop/src/shared/lib/installError.ts
+++ b/desktop/src/shared/lib/installError.ts
@@ -1,15 +1,25 @@
-import type { InstallStepResult } from "@/shared/api/types";
+import type { InstallRuntimeResult } from "@/shared/api/types";
 
 /**
  * Build the user-visible error message for a failed install.
  * When the last step carries an actionable hint, it is shown first,
  * followed by the raw step failure detail.
+ *
+ * The step detail is truncated for display, so the message ends with a pointer
+ * to the install log — which holds every attempt of every step, each record
+ * bounded far above the display truncation — when one was written.
  */
-export function getInstallErrorMessage(steps: InstallStepResult[]): string {
+export function getInstallErrorMessage(result: InstallRuntimeResult): string {
+  const { steps, logPath } = result;
   const lastStep = steps[steps.length - 1];
   if (!lastStep) {
-    return "Install failed with no output.";
+    return withLog("Install failed with no output.", logPath);
   }
   const base = `Step "${lastStep.step}" failed: ${lastStep.stderr || lastStep.stdout || "unknown error"}`;
-  return lastStep.hint ? `${lastStep.hint}\n\n${base}` : base;
+  const detail = lastStep.hint ? `${lastStep.hint}\n\n${base}` : base;
+  return withLog(detail, logPath);
+}
+
+function withLog(message: string, logPath: string | null): string {
+  return logPath ? `${message}\n\nFull log: ${logPath}` : message;
 }
diff --git a/desktop/src/shared/lib/mediaUrl.test.mjs b/desktop/src/shared/lib/mediaUrl.test.mjs
index 9a293e8b3e..96c004ec56 100644
--- a/desktop/src/shared/lib/mediaUrl.test.mjs
+++ b/desktop/src/shared/lib/mediaUrl.test.mjs
@@ -27,6 +27,42 @@ test("mediaProxyUrl: uses the IPv4 loopback literal for the localhost proxy", ()
   );
 });
 
+test("media-proxy port store: resolved port publishes and reset notifies subscribers", async () => {
+  const previousWindow = globalThis.window;
+  let notifications = 0;
+
+  globalThis.window = {
+    __TAURI_INTERNALS__: {
+      invoke(command) {
+        if (command === "get_media_proxy_port") return Promise.resolve(54321);
+        if (command === "get_relay_http_url") {
+          return Promise.resolve("https://relay.example");
+        }
+        return Promise.reject(new Error(`Unexpected command: ${command}`));
+      },
+    },
+  };
+
+  try {
+    const mediaUrl = await import(`./mediaUrl.ts?portStore=${Date.now()}`);
+    const unsubscribe = mediaUrl.subscribeMediaProxyPort(() => notifications++);
+
+    mediaUrl.rewriteRelayUrl(`https://relay.example/media/${HASH}.png`);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    assert.equal(mediaUrl.getCachedMediaProxyPort(), 54321);
+    assert.equal(notifications, 1);
+
+    mediaUrl.resetMediaCaches();
+    assert.equal(mediaUrl.getCachedMediaProxyPort(), null);
+    assert.equal(notifications, 2);
+
+    unsubscribe();
+  } finally {
+    globalThis.window = previousWindow;
+  }
+});
+
 test("relay-origin store: publishes are canonicalized at the store boundary", () => {
   // The store must hold the invariant that `cachedRelayOrigin` is always a
   // canonical URL origin — consumers compare `new URL(src).origin` against it
diff --git a/desktop/src/shared/lib/mediaUrl.ts b/desktop/src/shared/lib/mediaUrl.ts
index 8875920ef2..238ef403eb 100644
--- a/desktop/src/shared/lib/mediaUrl.ts
+++ b/desktop/src/shared/lib/mediaUrl.ts
@@ -63,10 +63,17 @@ let cacheGeneration = 0;
 /** `useSyncExternalStore` listeners for relay-origin changes. */
 const relayOriginListeners = new Set<() => void>();
 
+/** `useSyncExternalStore` listeners for media-proxy port changes. */
+const mediaProxyPortListeners = new Set<() => void>();
+
 function notifyRelayOriginListeners(): void {
   for (const listener of relayOriginListeners) listener();
 }
 
+function notifyMediaProxyPortListeners(): void {
+  for (const listener of mediaProxyPortListeners) listener();
+}
+
 /**
  * Publish a resolved relay origin, but only if `generation` is still current
  * (the fetch wasn't superseded by a workspace switch). The stored snapshot is
@@ -108,6 +115,18 @@ export function subscribeRelayOrigin(listener: () => void): () => void {
   };
 }
 
+/**
+ * Subscribe to media-proxy port changes. Returns a stable unsubscribe function
+ * for `useSyncExternalStore` consumers that need to re-run `rewriteRelayUrl`
+ * once the async Tauri proxy lookup has resolved.
+ */
+export function subscribeMediaProxyPort(listener: () => void): () => void {
+  mediaProxyPortListeners.add(listener);
+  return () => {
+    mediaProxyPortListeners.delete(listener);
+  };
+}
+
 const POLL_INTERVAL_MS = 100;
 const POLL_TIMEOUT_MS = 5000;
 
@@ -188,7 +207,10 @@ async function fetchProxyPort(): Promise<number | null> {
           deadline,
         );
         if (port !== null && port > 0 && generation === cacheGeneration) {
-          cachedPort = port;
+          if (cachedPort !== port) {
+            cachedPort = port;
+            notifyMediaProxyPortListeners();
+          }
         }
       } catch {
         // invoke failed (e.g. Tauri IPC not ready yet) — keep retrying
@@ -227,8 +249,12 @@ if (typeof window !== "undefined") {
  */
 export function resetMediaCaches(): void {
   cacheGeneration += 1;
+  const hadCachedPort = cachedPort !== null;
   cachedPort = null;
   portPromise = null;
+  if (hadCachedPort) {
+    notifyMediaProxyPortListeners();
+  }
   if (cachedRelayOrigin !== null) {
     cachedRelayOrigin = null;
     notifyRelayOriginListeners();
@@ -246,6 +272,14 @@ export function getCachedRelayOrigin(): string | null {
   return cachedRelayOrigin;
 }
 
+/**
+ * The localhost proxy port if it has been resolved, else `null`. Synchronous
+ * best-effort read of the same cache `rewriteRelayUrl` uses.
+ */
+export function getCachedMediaProxyPort(): number | null {
+  return cachedPort;
+}
+
 /**
  * Build the local proxy URL with an IPv4 literal. The Rust proxy binds
  * `127.0.0.1:0`, not `::1`, and some WebViews resolve `localhost` to IPv6
diff --git a/desktop/src/shared/lib/ncryptsecSourceScan.test.mjs b/desktop/src/shared/lib/ncryptsecSourceScan.test.mjs
new file mode 100644
index 0000000000..9ca8b9acf5
--- /dev/null
+++ b/desktop/src/shared/lib/ncryptsecSourceScan.test.mjs
@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+
+// Structural tripwire (plan D4, defense-in-depth): NIP-49 backup material
+// handling in the webview is confined to the identity/backup/import UI and
+// its API wrappers. Anything else in `desktop/src` touching `ncryptsec` is
+// structural drift toward an unguarded egress path and must be reviewed —
+// the runtime guarantee lives in src-tauri's egress guard, this scan only
+// keeps the blob from quietly spreading through the frontend.
+//
+// Mirror of the Rust-side scan in
+// `src-tauri/src/egress_guard_tests.rs::ncryptsec_handling_is_confined_to_allowlisted_files`.
+
+const SRC_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../..",
+);
+
+const ALLOWLIST = [
+  "shared/api/tauriIdentity.ts",
+  "features/onboarding/lib/encryptedBackup.ts",
+  "features/onboarding/lib/encryptedBackup.test.mjs",
+  "features/onboarding/lib/keyImportInput.ts",
+  "features/onboarding/lib/keyImportInput.test.mjs",
+  "features/onboarding/ui/BackupStep.tsx",
+  "features/onboarding/ui/BackupPasswordTimeline.tsx",
+  "features/onboarding/ui/BackupTestFlow.tsx",
+  "features/onboarding/ui/EncryptedBackupCreator.tsx",
+  "features/onboarding/ui/NostrKeyImportForm.tsx",
+  "features/onboarding/ui/NsecMaskedDisplay.tsx",
+  "features/settings/EncryptedBackupProvider.tsx",
+  "features/settings/lib/encryptedBackup.ts",
+  "features/settings/lib/encryptedBackup.test.mjs",
+  "features/settings/ui/BackupTestFlow.tsx",
+  "features/settings/ui/EncryptedBackupCreator.tsx",
+  "features/settings/ui/ProfileSettingsCard.tsx",
+  // e2e-only mock bridge (never in the production bundle):
+  "testing/e2eBridge.ts",
+  // this scan:
+  "shared/lib/ncryptsecSourceScan.test.mjs",
+];
+
+function* walk(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walk(full);
+    } else if (/\.(ts|tsx|mjs|js|jsx)$/.test(entry.name)) {
+      yield full;
+    }
+  }
+}
+
+test("ncryptsec handling is confined to allowlisted frontend files", () => {
+  const violations = [];
+  for (const file of walk(SRC_ROOT)) {
+    const rel = path.relative(SRC_ROOT, file).replaceAll("\\", "/");
+    if (ALLOWLIST.includes(rel)) continue;
+    const content = fs.readFileSync(file, "utf8");
+    if (content.toLowerCase().includes("ncryptsec")) {
+      violations.push(rel);
+    }
+  }
+  assert.deepEqual(
+    violations,
+    [],
+    `NIP-49 material outside allowlisted files — wire it through the ` +
+      `identity layer (and its egress-guarded Rust commands) instead:\n` +
+      violations.join("\n"),
+  );
+});
diff --git a/desktop/src/shared/lib/nostrUtils.ts b/desktop/src/shared/lib/nostrUtils.ts
index b73d46d999..d98c6ee8cf 100644
--- a/desktop/src/shared/lib/nostrUtils.ts
+++ b/desktop/src/shared/lib/nostrUtils.ts
@@ -23,6 +23,34 @@ export function safeNpub(pubkey: string): string | null {
   }
 }
 
+const HEX_PUBKEY_REGEX = /^[0-9a-f]{64}$/;
+
+/**
+ * Parse user-entered public key input — either a 64-character hex pubkey or
+ * a bech32 `npub1…` string — into a lowercase hex pubkey. Returns null for
+ * anything else (does NOT throw — intended for live form validation).
+ *
+ * The input is trimmed first; surrounding whitespace from copy-paste is
+ * tolerated.
+ */
+export function parsePubkeyInput(input: string): string | null {
+  const trimmed = input.trim().toLowerCase();
+  if (HEX_PUBKEY_REGEX.test(trimmed)) {
+    return trimmed;
+  }
+  if (trimmed.startsWith("npub1")) {
+    try {
+      const decoded = decode(trimmed);
+      if (decoded.type === "npub") {
+        return decoded.data;
+      }
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
 /**
  * Decode a bech32 nsec string and derive the matching npub. Returns null if
  * the input is not a syntactically valid `nsec1…` (does NOT throw — this is
diff --git a/desktop/src/shared/lib/parsePubkeyInput.test.mjs b/desktop/src/shared/lib/parsePubkeyInput.test.mjs
new file mode 100644
index 0000000000..f9aa57d87f
--- /dev/null
+++ b/desktop/src/shared/lib/parsePubkeyInput.test.mjs
@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { parsePubkeyInput } from "./nostrUtils.ts";
+
+const HEX = "ea9b4d7a7a78a3e3729e5568b14d764d4962be0e1f20f749bcf8d9dbbf9a9328";
+const NPUB = "npub1a2d567n60z37xu57245tzntkf4yk90swrus0wjdulrvah0u6jv5qusyp60";
+
+describe("parsePubkeyInput", () => {
+  it("accepts a lowercase 64-char hex pubkey", () => {
+    assert.equal(parsePubkeyInput(HEX), HEX);
+  });
+
+  it("lowercases an uppercase hex pubkey", () => {
+    assert.equal(parsePubkeyInput(HEX.toUpperCase()), HEX);
+  });
+
+  it("decodes an npub to its hex pubkey", () => {
+    assert.equal(parsePubkeyInput(NPUB), HEX);
+  });
+
+  it("tolerates surrounding whitespace from copy-paste", () => {
+    assert.equal(parsePubkeyInput(`  ${NPUB}\n`), HEX);
+    assert.equal(parsePubkeyInput(` ${HEX} `), HEX);
+  });
+
+  it("rejects an npub with a corrupted checksum", () => {
+    assert.equal(parsePubkeyInput(`${NPUB.slice(0, -1)}q`), null);
+  });
+
+  it("rejects other bech32 entities such as nsec", () => {
+    assert.equal(
+      parsePubkeyInput(
+        "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+      ),
+      null,
+    );
+  });
+
+  it("rejects hex of the wrong length", () => {
+    assert.equal(parsePubkeyInput(HEX.slice(0, 63)), null);
+    assert.equal(parsePubkeyInput(`${HEX}0`), null);
+  });
+
+  it("rejects non-hex non-npub input", () => {
+    assert.equal(parsePubkeyInput(""), null);
+    assert.equal(parsePubkeyInput("alice"), null);
+    assert.equal(parsePubkeyInput(`z${HEX.slice(1)}`), null);
+  });
+});
diff --git a/desktop/src/shared/lib/useMediaProxyPort.ts b/desktop/src/shared/lib/useMediaProxyPort.ts
new file mode 100644
index 0000000000..4f4e756984
--- /dev/null
+++ b/desktop/src/shared/lib/useMediaProxyPort.ts
@@ -0,0 +1,17 @@
+import * as React from "react";
+
+import { getCachedMediaProxyPort, subscribeMediaProxyPort } from "./mediaUrl";
+
+/**
+ * The resolved localhost media-proxy port, re-rendering when it resolves or
+ * changes. Components that call `rewriteRelayUrl` during render can subscribe
+ * to this so an initial `buzz-media://` fallback is replaced by the loopback
+ * proxy URL as soon as the Tauri backend reports the port.
+ */
+export function useMediaProxyPort(): number | null {
+  return React.useSyncExternalStore(
+    subscribeMediaProxyPort,
+    getCachedMediaProxyPort,
+    () => null,
+  );
+}
diff --git a/desktop/src/shared/styles/globals.css b/desktop/src/shared/styles/globals.css
index fd60621933..704f6e542d 100644
--- a/desktop/src/shared/styles/globals.css
+++ b/desktop/src/shared/styles/globals.css
@@ -1,5 +1,6 @@
 @import "tailwindcss";
 @import "tw-animate-css";
+
 @import "./globals/scrollbars.css";
 @import "./globals/motion.css";
 @import "./globals/animations.css";
@@ -17,3 +18,15 @@
 @import "./globals/progress.css";
 
 @config "../../../tailwind.config.js";
+
+/* Tailwind v4 gates `hover:` behind `@media (hover: hover)`. Some Windows
+   hosts answer that query `false` even with a mouse attached — WebView2 here
+   reports `hover: none`, `any-pointer: fine: false`, `maxTouchPoints: 10` —
+   which leaves every hover-revealed control permanently `visibility: hidden`:
+   member row action menus, sidebar row actions, attachment controls. A bare
+   `&:hover` trusts the actual hover event instead of the capability query;
+   Chromium only fires :hover when a real pointer is present.
+
+   Must stay below every `@import`: CSS requires `@import` to precede other
+   at-rules, so placing this above them silently drops the rest of the sheet. */
+@custom-variant hover (&:hover);
diff --git a/desktop/src/shared/styles/globals/components.css b/desktop/src/shared/styles/globals/components.css
index c21e4a617d..036cf925e0 100644
--- a/desktop/src/shared/styles/globals/components.css
+++ b/desktop/src/shared/styles/globals/components.css
@@ -241,6 +241,54 @@
     --buzz-onboarding-avatar-dialog-shadow: 0 0 0;
   }
 
+  /*
+   * Backup options and password backup intentionally leave the bright
+   * onboarding world for a dark security-focused subview. Keep these semantic
+   * overrides on a reusable class as well as the shell so portaled
+   * popovers/dialogs can opt into the same treatment.
+   */
+  .buzz-onboarding-security-theme {
+    color-scheme: dark;
+    --buzz-onboarding-shell-bottom: #082b49;
+    --buzz-onboarding-cta-label: #f5f5f5;
+    --background: 222 45% 4%;
+    --foreground: 0 0% 96%;
+    --card: 220 14% 11%;
+    --card-foreground: 0 0% 96%;
+    --popover: 220 14% 9%;
+    --popover-foreground: 0 0% 96%;
+    --primary: 0 0% 16%;
+    --primary-foreground: 0 0% 96%;
+    --secondary: 0 0% 12%;
+    --secondary-foreground: 0 0% 96%;
+    --muted: 0 0% 12%;
+    --muted-foreground: 0 0% 72%;
+    --accent: 0 0% 16%;
+    --accent-foreground: 0 0% 96%;
+    --destructive: 0 84% 70%;
+    --destructive-foreground: 0 0% 4%;
+    --border: 0 0% 22%;
+    --input: 0 0% 22%;
+    --ring: 0 0% 84%;
+  }
+
+  .buzz-onboarding-neutral-theme.buzz-startup-shell.buzz-onboarding-security-theme {
+    background-color: #010103;
+    background-image:
+      radial-gradient(circle, rgb(143 211 255 / 0.11) 1px, transparent 1px),
+      radial-gradient(
+        ellipse at 50% 58%,
+        rgb(28 112 196 / 0.24) 0%,
+        rgb(18 76 138 / 0.1) 38%,
+        transparent 66%
+      ),
+      linear-gradient(to bottom, #010103 0%, #040914 46%, #082b49 100%);
+    background-size:
+      24px 24px,
+      auto,
+      auto;
+  }
+
   .buzz-onboarding-key-text {
     @apply w-full break-all [overflow-wrap:anywhere] font-mono text-nsec-key;
 
@@ -376,10 +424,13 @@
     animation-name: buzz-onboarding-line-slide-backward;
   }
 
+  .buzz-onboarding-transition-line[data-onboarding-effect="mask-reveal-down"],
   .buzz-onboarding-transition-line[data-onboarding-effect="mask-reveal-up"] {
     overflow: visible;
   }
 
+  .buzz-onboarding-transition-line[data-onboarding-effect="mask-reveal-down"]
+    > .buzz-onboarding-transition-content,
   .buzz-onboarding-transition-line[data-onboarding-effect="mask-reveal-up"]
     > .buzz-onboarding-transition-content {
     /* `backwards` (not `both`): the reveal ends on an identity transform, so
@@ -387,12 +438,23 @@
        that establishes a containing block and traps `position: fixed`
        descendants (the bottom-docked onboarding footer). Reverting to no
        transform at rest looks identical and frees fixed positioning. */
-    animation: buzz-onboarding-mask-reveal-up 760ms
-      cubic-bezier(0.22, 1, 0.36, 1) backwards;
+    animation-duration: 760ms;
+    animation-fill-mode: backwards;
+    animation-timing-function: cubic-bezier(0.22, 1, 0.36, 1);
     animation-delay: var(--buzz-onboarding-transition-delay, 0ms);
     transform-origin: 50% 70%;
   }
 
+  .buzz-onboarding-transition-line[data-onboarding-effect="mask-reveal-down"]
+    > .buzz-onboarding-transition-content {
+    animation-name: buzz-onboarding-mask-reveal-down;
+  }
+
+  .buzz-onboarding-transition-line[data-onboarding-effect="mask-reveal-up"]
+    > .buzz-onboarding-transition-content {
+    animation-name: buzz-onboarding-mask-reveal-up;
+  }
+
   .buzz-onboarding-name-placeholder-caret {
     animation: buzz-onboarding-caret-blink 1.1s steps(1, end) infinite;
   }
@@ -543,6 +605,25 @@
     }
   }
 
+  @keyframes buzz-onboarding-mask-reveal-down {
+    from {
+      filter: blur(8px);
+      opacity: 0;
+      transform: translate3d(0, -30px, 0) scale(0.985);
+    }
+
+    56% {
+      filter: blur(2px);
+      opacity: 0.86;
+    }
+
+    to {
+      filter: blur(0);
+      opacity: 1;
+      transform: translate3d(0, 0, 0) scale(1);
+    }
+  }
+
   @media (prefers-reduced-motion: reduce) {
     .buzz-onboarding-runtime-check,
     .buzz-onboarding-runtime-checkmark {
diff --git a/desktop/src/shared/styles/globals/theme.css b/desktop/src/shared/styles/globals/theme.css
index 0810a15f0a..13dc724d21 100644
--- a/desktop/src/shared/styles/globals/theme.css
+++ b/desktop/src/shared/styles/globals/theme.css
@@ -481,6 +481,13 @@
   color: var(--buzz-muted-foreground);
 }
 
+/* Match the hover treatment used by inactive channel rows. */
+:root[data-buzz-sidebar]
+  [data-testid="app-sidebar"]
+  [data-testid="sidebar-profile-card"]:hover {
+  background-color: var(--buzz-hover-surface);
+}
+
 /*
  * App and settings sidebar section headings plus secondary footer text use the
  * same tint. Navigation rows keep their normal foreground in both sidebars.
diff --git a/desktop/src/shared/styles/globals/utilities.css b/desktop/src/shared/styles/globals/utilities.css
index 1dd7326e22..a9da737bce 100644
--- a/desktop/src/shared/styles/globals/utilities.css
+++ b/desktop/src/shared/styles/globals/utilities.css
@@ -75,6 +75,15 @@
     );
   }
 
+  .buzz-huddle-drawer .buzz-huddle-control-button[aria-pressed="true"] {
+    background: hsl(var(--primary));
+    color: hsl(var(--primary-foreground));
+  }
+
+  .buzz-huddle-drawer .buzz-huddle-control-button[aria-pressed="true"]:hover {
+    background: hsl(var(--primary) / 90%);
+  }
+
   .buzz-huddle-drawer .buzz-huddle-split-chevron {
     background: hsl(var(--huddle-control-chevron-surface, var(--secondary)));
   }
diff --git a/desktop/src/shared/ui/alert-dialog.tsx b/desktop/src/shared/ui/alert-dialog.tsx
index d4bf93d4b1..97574abbe6 100644
--- a/desktop/src/shared/ui/alert-dialog.tsx
+++ b/desktop/src/shared/ui/alert-dialog.tsx
@@ -5,6 +5,11 @@ import * as AlertDialogPrimitive from "@radix-ui/react-alert-dialog";
 
 import { cn } from "@/shared/lib/cn";
 import { buttonVariants } from "@/shared/ui/button";
+import {
+  type CardTextureSize,
+  type CardTextureTone,
+  texturedSurfaceClasses,
+} from "@/shared/ui/card";
 import { MODAL_BACKDROP_BLUR_CLASS } from "@/shared/ui/modalBackdrop";
 import {
   MODAL_CONTENT_MOTION_CLASS,
@@ -31,25 +36,59 @@ const AlertDialogOverlay = React.forwardRef<
 ));
 AlertDialogOverlay.displayName = AlertDialogPrimitive.Overlay.displayName;
 
+type AlertDialogContentProps = React.ComponentPropsWithoutRef<
+  typeof AlertDialogPrimitive.Content
+> & {
+  surface?: "default" | "textured";
+  textureSize?: CardTextureSize;
+  textureTone?: CardTextureTone;
+};
+
 const AlertDialogContent = React.forwardRef<
   React.ElementRef<typeof AlertDialogPrimitive.Content>,
-  React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Content>
->(({ className, ...props }, ref) => (
-  <AlertDialogPortal>
-    <AlertDialogOverlay />
-    <div className="fixed inset-0 z-50 grid place-items-center overflow-y-auto p-4 pointer-events-none">
-      <AlertDialogPrimitive.Content
+  AlertDialogContentProps
+>(
+  (
+    {
+      className,
+      surface = "default",
+      textureSize = "regular",
+      textureTone = "light",
+      ...props
+    },
+    ref,
+  ) => (
+    <AlertDialogPortal>
+      <AlertDialogOverlay />
+      <div
         className={cn(
-          "pointer-events-auto grid w-[calc(100vw-2rem)] max-w-md gap-4 rounded-3xl bg-background p-6 shadow-2xl outline-hidden",
-          MODAL_CONTENT_MOTION_CLASS,
-          className,
+          "pointer-events-none fixed inset-0 z-50 grid place-items-center overflow-y-auto",
+          surface === "textured"
+            ? textureSize === "compact"
+              ? "p-10"
+              : "p-28 max-sm:p-18"
+            : "p-4",
         )}
-        ref={ref}
-        {...props}
-      />
-    </div>
-  </AlertDialogPortal>
-));
+      >
+        <AlertDialogPrimitive.Content
+          className={cn(
+            "pointer-events-auto grid w-[calc(100vw-2rem)] max-w-md gap-4 outline-hidden",
+            surface === "default" && "rounded-3xl bg-background p-6 shadow-2xl",
+            surface === "textured" &&
+              texturedSurfaceClasses({
+                size: textureSize,
+                tone: textureTone,
+              }),
+            MODAL_CONTENT_MOTION_CLASS,
+            className,
+          )}
+          ref={ref}
+          {...props}
+        />
+      </div>
+    </AlertDialogPortal>
+  ),
+);
 AlertDialogContent.displayName = AlertDialogPrimitive.Content.displayName;
 
 const AlertDialogHeader = ({
diff --git a/desktop/src/shared/ui/assets/card-texture-compact.png b/desktop/src/shared/ui/assets/card-texture-compact.png
new file mode 100644
index 0000000000..5e7de51403
Binary files /dev/null and b/desktop/src/shared/ui/assets/card-texture-compact.png differ
diff --git a/desktop/src/shared/ui/assets/card-texture-dark-compact.png b/desktop/src/shared/ui/assets/card-texture-dark-compact.png
new file mode 100644
index 0000000000..6c26f96951
Binary files /dev/null and b/desktop/src/shared/ui/assets/card-texture-dark-compact.png differ
diff --git a/desktop/src/shared/ui/assets/card-texture-dark.png b/desktop/src/shared/ui/assets/card-texture-dark.png
new file mode 100644
index 0000000000..06cc574185
Binary files /dev/null and b/desktop/src/shared/ui/assets/card-texture-dark.png differ
diff --git a/desktop/src/shared/ui/card-texture.css b/desktop/src/shared/ui/card-texture.css
index 691d4be656..1107615452 100644
--- a/desktop/src/shared/ui/card-texture.css
+++ b/desktop/src/shared/ui/card-texture.css
@@ -7,6 +7,11 @@
  * fixed and repeats edge texture while the white center fills any card size.
  */
 .buzz-card-textured {
+  --buzz-card-textured-source: url("./assets/card-texture.png");
+  --buzz-card-textured-slice: 416;
+  --buzz-card-textured-width: 208px;
+  --buzz-card-textured-outset: 96px;
+  --buzz-card-textured-min-size: 224px;
   /*
    * The asset has three zones, from outside in:
    *   1. transparent powder bleed (outside the layout box, via outset)
@@ -31,11 +36,41 @@
    * into a smaller height with `--buzz-card-textured-min-height` when the
    * center seam is acceptable for that deliberately compressed surface.
    */
-  min-height: var(--buzz-card-textured-min-height, 224px);
-  min-width: 224px;
-  border-image-source: url("./assets/card-texture.png");
-  border-image-slice: 416 fill;
-  border-image-width: 208px;
-  border-image-outset: 96px;
+  min-height: var(
+    --buzz-card-textured-min-height,
+    var(--buzz-card-textured-min-size)
+  );
+  min-width: var(
+    --buzz-card-textured-min-width,
+    var(--buzz-card-textured-min-size)
+  );
+  border-image-source: var(--buzz-card-textured-source);
+  border-image-slice: var(--buzz-card-textured-slice) fill;
+  border-image-width: var(--buzz-card-textured-width);
+  border-image-outset: var(--buzz-card-textured-outset);
   border-image-repeat: repeat;
 }
+
+/* Dark backup surfaces use a separately baked fill so their content stays
+ * bright; applying `filter: brightness()` to the element would dim children. */
+.buzz-card-textured-dark {
+  --buzz-card-textured-source: url("./assets/card-texture-dark.png");
+}
+
+/*
+ * Popovers, confirmations, and compact callouts need the same powder edge
+ * without the full card's 96px bleed or 224px floor. This independently baked
+ * nine-slice keeps the edge legible at overlay scale.
+ */
+.buzz-card-textured-compact {
+  --buzz-card-textured-source: url("./assets/card-texture-compact.png");
+  --buzz-card-textured-slice: 136;
+  --buzz-card-textured-width: 68px;
+  --buzz-card-textured-outset: 24px;
+  --buzz-card-textured-safe-inset: 1.75rem;
+  --buzz-card-textured-min-size: 136px;
+}
+
+.buzz-card-textured-dark.buzz-card-textured-compact {
+  --buzz-card-textured-source: url("./assets/card-texture-dark-compact.png");
+}
diff --git a/desktop/src/shared/ui/card.tsx b/desktop/src/shared/ui/card.tsx
index 0bf826f866..be899fccd6 100644
--- a/desktop/src/shared/ui/card.tsx
+++ b/desktop/src/shared/ui/card.tsx
@@ -5,6 +5,26 @@ import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "@/shared/lib/cn";
 import "./card-texture.css";
 
+export type CardTextureTone = "light" | "dark";
+export type CardTextureSize = "regular" | "compact";
+
+export const TEXTURED_SURFACE_CLASS =
+  "buzz-card-textured relative isolate rounded-none border-0 bg-transparent p-[var(--buzz-card-textured-safe-inset)] shadow-none";
+
+export function texturedSurfaceClasses({
+  size = "regular",
+  tone = "light",
+}: {
+  size?: CardTextureSize;
+  tone?: CardTextureTone;
+} = {}): string {
+  return cn(
+    TEXTURED_SURFACE_CLASS,
+    tone === "dark" && "buzz-card-textured-dark",
+    size === "compact" && "buzz-card-textured-compact",
+  );
+}
+
 /**
  * `variant="textured"` renders the baked nine-slice powder texture
  * (`card-texture.css`). The asset bakes the card surface INTO the image:
@@ -37,7 +57,7 @@ const cardVariants = cva("text-card-foreground", {
         // card-texture.css); when that floor stretches the card beyond its
         // content, the content stays vertically centered instead of pinning
         // to the top padding edge.
-        "buzz-card-textured relative isolate flex flex-col justify-center rounded-none border-0 p-[var(--buzz-card-textured-safe-inset)] shadow-none",
+        `${TEXTURED_SURFACE_CLASS} flex flex-col justify-center`,
     },
   },
   defaultVariants: {
@@ -49,15 +69,35 @@ export interface CardProps
   extends React.HTMLAttributes<HTMLDivElement>,
     VariantProps<typeof cardVariants> {
   asChild?: boolean;
+  textureSize?: CardTextureSize;
+  textureTone?: CardTextureTone;
 }
 
 const Card = React.forwardRef<HTMLDivElement, CardProps>(
-  ({ asChild = false, className, variant, ...props }, ref) => {
+  (
+    {
+      asChild = false,
+      className,
+      textureSize = "regular",
+      textureTone = "light",
+      variant,
+      ...props
+    },
+    ref,
+  ) => {
     const Comp = asChild ? Slot : "div";
     return (
       <Comp
         ref={ref}
-        className={cn(cardVariants({ variant, className }))}
+        className={cn(
+          cardVariants({ variant, className }),
+          variant === "textured" &&
+            textureTone === "dark" &&
+            "buzz-card-textured-dark",
+          variant === "textured" &&
+            textureSize === "compact" &&
+            "buzz-card-textured-compact",
+        )}
         {...props}
       />
     );
diff --git a/desktop/src/shared/ui/popover.tsx b/desktop/src/shared/ui/popover.tsx
index eb67c959e6..4c161efe5d 100644
--- a/desktop/src/shared/ui/popover.tsx
+++ b/desktop/src/shared/ui/popover.tsx
@@ -2,6 +2,11 @@ import * as React from "react";
 import * as PopoverPrimitive from "@radix-ui/react-popover";
 
 import { cn } from "@/shared/lib/cn";
+import {
+  type CardTextureSize,
+  type CardTextureTone,
+  texturedSurfaceClasses,
+} from "@/shared/ui/card";
 import {
   POPOVER_RADIX_MOTION_CLASS,
   POPOVER_RADIX_SIDE_MOTION_CLASS,
@@ -15,27 +20,57 @@ const PopoverTrigger = PopoverPrimitive.Trigger;
 
 const PopoverAnchor = PopoverPrimitive.Anchor;
 
+type PopoverContentProps = React.ComponentPropsWithoutRef<
+  typeof PopoverPrimitive.Content
+> & {
+  surface?: "default" | "textured";
+  textureSize?: CardTextureSize;
+  textureTone?: CardTextureTone;
+};
+
 const PopoverContent = React.forwardRef<
   React.ElementRef<typeof PopoverPrimitive.Content>,
-  React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>
->(({ className, align = "center", sideOffset = 4, style, ...props }, ref) => (
-  <PopoverPrimitive.Portal>
-    <PopoverPrimitive.Content
-      ref={ref}
-      align={align}
-      sideOffset={sideOffset}
-      className={cn(
-        "z-50 w-72 origin-(--radix-popover-content-transform-origin) rounded-xl p-4 outline-hidden",
-        POPOVER_RADIX_MOTION_CLASS,
-        POPOVER_RADIX_SIDE_MOTION_CLASS,
-        POPOVER_SURFACE_CLASS,
-        className,
-      )}
-      style={{ ...POPOVER_SHADOW_STYLE, ...style }}
-      {...props}
-    />
-  </PopoverPrimitive.Portal>
-));
+  PopoverContentProps
+>(
+  (
+    {
+      className,
+      align = "center",
+      sideOffset,
+      style,
+      surface = "default",
+      textureSize = "regular",
+      textureTone = "light",
+      ...props
+    },
+    ref,
+  ) => (
+    <PopoverPrimitive.Portal>
+      <PopoverPrimitive.Content
+        ref={ref}
+        align={align}
+        sideOffset={sideOffset ?? (surface === "textured" ? 24 : 4)}
+        className={cn(
+          "z-50 w-72 origin-(--radix-popover-content-transform-origin) outline-hidden",
+          POPOVER_RADIX_MOTION_CLASS,
+          POPOVER_RADIX_SIDE_MOTION_CLASS,
+          surface === "default" && cn("rounded-xl p-4", POPOVER_SURFACE_CLASS),
+          surface === "textured" &&
+            texturedSurfaceClasses({
+              size: textureSize,
+              tone: textureTone,
+            }),
+          className,
+        )}
+        style={{
+          ...(surface === "default" ? POPOVER_SHADOW_STYLE : {}),
+          ...style,
+        }}
+        {...props}
+      />
+    </PopoverPrimitive.Portal>
+  ),
+);
 PopoverContent.displayName = PopoverPrimitive.Content.displayName;
 
 export { Popover, PopoverTrigger, PopoverContent, PopoverAnchor };
diff --git a/desktop/src/testing/e2eBridge.ts b/desktop/src/testing/e2eBridge.ts
index 7b13273c60..355ccea9fc 100644
--- a/desktop/src/testing/e2eBridge.ts
+++ b/desktop/src/testing/e2eBridge.ts
@@ -1,6 +1,7 @@
 import { bytesToHex, hexToBytes } from "@noble/hashes/utils.js";
+import { emit, listen } from "@tauri-apps/api/event";
 import { mockIPC, mockWindows } from "@tauri-apps/api/mocks";
-import { decode } from "nostr-tools/nip19";
+import { decode, npubEncode, nsecEncode } from "nostr-tools/nip19";
 import { finalizeEvent, getPublicKey } from "nostr-tools/pure";
 import { parse as yamlParse } from "yaml";
 import {
@@ -10,6 +11,7 @@ import {
 } from "./e2eBridgeCustomHarnesses.ts";
 
 import { relayClient } from "@/shared/api/relayClient";
+import { activateRateLimit } from "@/shared/api/relayRateLimitGate";
 import type { ConnectionState } from "@/shared/api/relayClientShared";
 import type { ChannelTemplate, RelayEvent } from "@/shared/api/types";
 import { getMarkdownParseCount } from "@/shared/ui/markdown/nodeCache";
@@ -143,9 +145,29 @@ type MockSearchProfileSeed = {
   isAgent?: boolean;
 };
 
+type MockHuddleMemberSeed = {
+  pubkey: string;
+  role: "owner" | "admin" | "member" | "guest" | "bot";
+};
+
+type MockHuddleSeed = {
+  parentChannelId: string;
+  ephemeralChannelId: string;
+  members: MockHuddleMemberSeed[];
+  transcriptionEnabled?: boolean;
+  isCreator?: boolean;
+};
+
 type E2eConfig = {
   mode?: "mock" | "relay";
   mock?: {
+    ttsSettings?: {
+      version: number;
+      agentTextToSpeech: boolean;
+      voicePreferences: string[];
+    };
+    /** Native picker boundary result for Pocket voice import tests. */
+    pocketVoiceImportResult?: "success" | "cancel" | "invalid";
     /** Advertised HEAD for the first mock project without adding that branch. */
     projectHeadBranch?: string;
     /** Builderlab account returned by hosted-community onboarding. Null/omitted = signed out. */
@@ -203,6 +225,8 @@ type E2eConfig = {
     acpRuntimesCatalogAfterConnect?: RawAcpRuntimeCatalogEntry[];
     activePersonaIds?: string[];
     installAcpRuntimeDelayMs?: number;
+    /** Live output lines the mocked install emits before it settles. */
+    installAcpRuntimeOutputLines?: string[];
     installAcpRuntimeResult?: RawInstallRuntimeResult;
     /** Sequence of results for successive `install_acp_runtime` calls.
      *  Call N returns results[N]; when exhausted the last entry repeats.
@@ -225,6 +249,14 @@ type E2eConfig = {
       mcp?: MockCommandAvailability;
     };
     managedAgents?: MockManagedAgentSeed[];
+    /** Result returned by the mocked `add_agent_to_huddle` command. */
+    addAgentToHuddleResult?: {
+      ephemeral_added: boolean;
+      parent_added: boolean;
+      parent_error: string | null;
+    };
+    /** Delay an invocation-time huddle snapshot to exercise hydration ordering. */
+    huddleStateReadDelayMs?: number;
     /** Per agent+relay runtime rows for the pair-scoped lifecycle commands
      *  (`list/start/stop/restart_managed_agent_runtime`). */
     managedAgentRuntimes?: MockManagedAgentRuntimeSeed[];
@@ -235,6 +267,8 @@ type E2eConfig = {
     personaSharePublicationStatuses?: Array<"published" | "queued">;
     teams?: MockTeamSeed[];
     relayAgents?: MockRelayAgentSeed[];
+    /** Native-like huddle state seeded from authoritative role-bearing membership. */
+    huddle?: MockHuddleSeed;
     agentListDelayMs?: number;
     agentMemory?: RawAgentMemoryListing | Record<string, RawAgentMemoryListing>;
     addChannelMembersDelayMs?: number;
@@ -277,6 +311,8 @@ type E2eConfig = {
     channelWindowDelayMs?: number;
     profileReadDelayMs?: number;
     profileReadError?: string;
+    /** Override whether get_profile reports a real kind:0 event. */
+    profileHasEvent?: boolean;
     profileUpdateError?: string;
     profileUpdateErrors?: string[];
     searchProfiles?: MockSearchProfileSeed[];
@@ -415,6 +451,14 @@ type E2eConfig = {
      *  autosave behaviour while a request is in flight. 0/undefined = instant.
      *  Alias of `globalConfigSaveDelayMs` (kept for onboarding specs). */
     setGlobalAgentConfigDelayMs?: number;
+    /** Errors returned by successive backup verification attempts. Null succeeds. */
+    backupVerificationErrors?: (string | null)[];
+    /** Public identities returned by successive successful backup verifications. */
+    backupVerificationPubkeys?: string[];
+    /** Delay (ms) applied to backup encryption so specs can observe pending UI. */
+    backupEncryptionDelayMs?: number;
+    /** Native paths returned by successive backup saves. */
+    backupSavePaths?: Array<string | null>;
     /**
      * When set, `get_nsec` throws with this message instead of returning the
      * mock nsec string. Use `nsecErrors` for sequenced failure/success.
@@ -913,8 +957,8 @@ function createMockRelayMembershipEvent(): RelayEvent {
  * sets from distinct pubkeys so the e2e exercises the union/collapse path, not
  * a single relay-owned set. `:buzz:` is the stable shortcode exercised by
  * custom-emoji.spec.ts (claimed by BOTH members with different URLs, so the
- * palette must collapse it to one deterministic winner); `:narf:` proves a
- * second member's distinct emoji unions in.
+ * palette must collapse it to one deterministic winner); `:narf:` and
+ * `:bufo_joy:` prove a second member's distinct emoji unions in.
  */
 function createMockCustomEmojiSetEvents(): RelayEvent[] {
   return [
@@ -941,6 +985,7 @@ function createMockCustomEmojiSetEvents(): RelayEvent[] {
         // member B claims :buzz: with a DIFFERENT url — unionCustomEmoji must
         // collapse it to one deterministic winner, never expose two URLs.
         ["emoji", "buzz", "https://example.com/e2e/buzz-b.png"],
+        ["emoji", "bufo_joy", "https://example.com/e2e/bufo-joy.png"],
       ],
       "b".repeat(64),
     ),
@@ -1017,6 +1062,8 @@ declare global {
       mentionPubkeys?: string[];
       extraTags?: string[][];
       createdAt?: number;
+      /** Marks this test-only message as locally pending. */
+      pending?: boolean;
       /** 64-hex id required for the event to be a valid reaction target. */
       id?: string;
     }) => RelayEvent;
@@ -1041,6 +1088,10 @@ declare global {
       command: string,
       payload?: Record<string, unknown>,
     ) => Promise<unknown>;
+    __BUZZ_E2E_SET_MOCK_HUDDLE_SNAPSHOT__?: (input: {
+      members: MockHuddleMemberSeed[];
+      transcriptionEnabled: boolean;
+    }) => Promise<void>;
     __BUZZ_E2E_PUSH_MOCK_FEED_ITEM__?: (item: RawFeedItem) => RawFeedItem;
     /** Replace an existing feed item by id (or push if not found) and fire the updated event. */
     __BUZZ_E2E_REPLACE_MOCK_FEED_ITEM__?: (
@@ -1095,6 +1146,12 @@ declare global {
     __BUZZ_E2E_SET_STALL_WEBSOCKET_SENDS__?: (stall: boolean) => void;
     __BUZZ_E2E_DISCONNECT_MOCK_WEBSOCKETS__?: () => number;
     __BUZZ_E2E_RESTART_MOCK_WEBSOCKETS__?: () => number;
+    __BUZZ_E2E_SET_MOCK_WEBSOCKET_UNAVAILABLE__?: (
+      unavailable: boolean,
+    ) => void;
+    __BUZZ_E2E_GET_WEBSOCKET_CONNECT_ATTEMPTS__?: () => number[];
+    __BUZZ_E2E_ACTIVATE_RELAY_RATE_LIMIT__?: (seconds: number) => void;
+    __BUZZ_E2E_RESET_WEBSOCKET_CONNECT_ATTEMPTS__?: () => void;
     __BUZZ_E2E_SET_MESH__?: (mesh: {
       admitted?: boolean;
       models?: Array<{ id: string; name: string | null }>;
@@ -1239,6 +1296,8 @@ const REACTION_TARGET_CONTENT = "React to me with a custom emoji";
 // REACTION_TARGET_EVENT_ID.
 const SYSTEM_REACTION_TARGET_EVENT_ID = "e".repeat(64);
 const E2E_IDENTITY_OVERRIDE_STORAGE_KEY = "buzz:e2e-identity-override.v1";
+/** Stands in for `tauri.conf.json`'s version, which no mock IPC call can read. */
+const MOCK_APP_VERSION = "0.0.0-e2e";
 const DEFAULT_MOCK_IDENTITY = {
   pubkey: "deadbeef".repeat(8),
   display_name: "npub1mock...",
@@ -2807,6 +2866,8 @@ const mockReminderEvents: RelayEvent[] = [];
 const mockPersonaEvents: RelayEvent[] = [];
 let mockRelayMembers: RawRelayMember[] = [];
 const mockSockets = new Map<number, MockSocket>();
+let mockWebsocketUnavailable = false;
+const relayWebsocketConnectAttemptStarts: number[] = [];
 let mockWebsocketSendMutexWedged = false;
 let mockClosedChannelLiveSubscription = false;
 const realSockets = new Map<number, WebSocket>();
@@ -2887,9 +2948,7 @@ const mockMeshState: {
   servingUsage: MockServingUsage;
 } = {
   admitted: true,
-  models: [
-    { id: "hf://demo/SmolLM2-135M-Instruct-GGUF:Q4_K_M", name: "SmolLM2 135M" },
-  ],
+  models: [{ id: "Gemma-4-E4B-it-Q4_K_M", name: "Gemma 4 E4B" }],
   denyReason: "not a relay member",
   nodeState: "off",
   nodeMode: null,
@@ -2898,9 +2957,7 @@ const mockMeshState: {
 
 function resetMockMesh() {
   mockMeshState.admitted = true;
-  mockMeshState.models = [
-    { id: "hf://demo/SmolLM2-135M-Instruct-GGUF:Q4_K_M", name: "SmolLM2 135M" },
-  ];
+  mockMeshState.models = [{ id: "Gemma-4-E4B-it-Q4_K_M", name: "Gemma 4 E4B" }];
   mockMeshState.denyReason = "not a relay member";
   mockMeshState.nodeState = "off";
   mockMeshState.nodeMode = null;
@@ -2908,8 +2965,85 @@ function resetMockMesh() {
 }
 let mockPersonas: RawPersona[] = [];
 let mockTeams: RawTeam[] = [];
-// Listeners registered via the mock __TAURI_INTERNALS__.listen — keyed by event name.
-const tauriEventListeners = new Map<string, Set<() => void>>();
+
+type MockHuddleState = {
+  phase: "active";
+  parent_channel_id: string;
+  ephemeral_channel_id: string;
+  participants: string[];
+  agent_pubkeys: string[];
+  tts_enabled: boolean;
+  transcription_enabled: boolean;
+  is_creator: boolean;
+  voice_input_mode: "voice_activity";
+};
+
+type PersistedMockHuddle = {
+  members: MockHuddleMemberSeed[];
+  state: MockHuddleState;
+};
+
+const MOCK_HUDDLE_STORAGE_KEY = "buzz.e2e.mock-huddle.v1";
+let mockHuddle: PersistedMockHuddle | null = null;
+
+function persistMockHuddle() {
+  if (mockHuddle) {
+    window.sessionStorage.setItem(
+      MOCK_HUDDLE_STORAGE_KEY,
+      JSON.stringify(mockHuddle),
+    );
+  }
+}
+
+async function emitMockHuddleState() {
+  if (!mockHuddle) return;
+  await emit("huddle-state-changed", structuredClone(mockHuddle.state));
+}
+
+function refreshMockHuddleMembership() {
+  if (!mockHuddle) return;
+  mockHuddle.state.agent_pubkeys = mockHuddle.members
+    .filter((member) => member.role === "bot")
+    .map((member) => member.pubkey);
+  mockHuddle.state.participants = mockHuddle.members.map(
+    (member) => member.pubkey,
+  );
+}
+
+function initializeMockHuddle(seed: MockHuddleSeed | undefined) {
+  mockHuddle = null;
+  if (!seed) {
+    window.sessionStorage.removeItem(MOCK_HUDDLE_STORAGE_KEY);
+    return;
+  }
+
+  const persisted = window.sessionStorage.getItem(MOCK_HUDDLE_STORAGE_KEY);
+  if (persisted) {
+    try {
+      mockHuddle = JSON.parse(persisted) as PersistedMockHuddle;
+      return;
+    } catch {
+      window.sessionStorage.removeItem(MOCK_HUDDLE_STORAGE_KEY);
+    }
+  }
+
+  mockHuddle = {
+    members: structuredClone(seed.members),
+    state: {
+      phase: "active",
+      parent_channel_id: seed.parentChannelId,
+      ephemeral_channel_id: seed.ephemeralChannelId,
+      participants: [],
+      agent_pubkeys: [],
+      tts_enabled: false,
+      transcription_enabled: seed.transcriptionEnabled ?? false,
+      is_creator: seed.isCreator ?? true,
+      voice_input_mode: "voice_activity",
+    },
+  };
+  refreshMockHuddleMembership();
+  persistMockHuddle();
+}
 const openedExternalUrls: string[] = [];
 const defaultMockRelayAgents: RawRelayAgent[] = [
   {
@@ -4013,6 +4147,7 @@ function emitMockChannelMessage(
   mentionPubkeys?: string[],
   extraTags?: string[][],
   createdAt?: number,
+  pending?: boolean,
   id?: string,
 ) {
   const eventKind = kind ?? 9;
@@ -4031,6 +4166,7 @@ function emitMockChannelMessage(
       createdAt,
       id,
     );
+    if (pending) event.pending = true;
     recordMockMessage(channelId, event);
     emitMockLiveEvent(channelId, event);
     return event;
@@ -4063,6 +4199,7 @@ function emitMockChannelMessage(
     createdAt,
     id,
   );
+  if (pending) event.pending = true;
   recordMockMessage(channelId, event);
   emitMockLiveEvent(channelId, event);
   return event;
@@ -5376,6 +5513,13 @@ async function handleGetChannels(config: E2eConfig | undefined) {
 
 async function handleGetProfile(config: E2eConfig | undefined) {
   const identity = getIdentity(config);
+  const forcedHasProfileEvent = config?.mock?.profileHasEvent;
+  if (forcedHasProfileEvent !== undefined) {
+    return {
+      ...cloneProfile(ensureMockProfile(config)),
+      has_profile_event: forcedHasProfileEvent,
+    };
+  }
   if (!identity) {
     const profileReadDelayMs = config?.mock?.profileReadDelayMs ?? 0;
     if (profileReadDelayMs > 0) {
@@ -7193,6 +7337,24 @@ let mockGlobalAgentConfig: {
 
 // Per-page get_nsec call counter for sequenced error testing.
 let nsecCallCount = 0;
+let backupVerificationCallCount = 0;
+let backupSaveCallCount = 0;
+
+const MOCK_NCRYPTSEC =
+  "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+const MOCK_BACKUP_PASSPHRASE = "mock horse battery staple lake orbit";
+const MOCK_PASSPHRASE_WORDS = [
+  "mock",
+  "horse",
+  "battery",
+  "staple",
+  "lake",
+  "orbit",
+  "cedar",
+  "plume",
+  "raven",
+  "tundra",
+];
 
 // Per-page explicit catalog publication outcomes.
 let personaSharePublicationCallCount = 0;
@@ -7200,6 +7362,53 @@ let personaSharePublicationCallCount = 0;
 // Per-page confirm_team_snapshot_import call counter for sequenced error testing.
 let teamSnapshotConfirmCallCount = 0;
 
+// Live-output sequence for the install currently being replayed. The backend
+// counter is per run (`InstallReporter::for_run` starts a fresh one), so this
+// restarts too — a bridge that stayed monotonic across installs would hide a UI
+// that carried a stale sequence number into the next run and rejected all of it.
+let installOutputSeq = 0;
+
+/**
+ * Replay the live output the Rust reporter emits while an install runs: a clear
+ * signal, then one line per entry. `seq` is install-wide and monotonic, matching
+ * the backend contract the UI's ordering depends on.
+ *
+ * The clear and the first line emit synchronously with the install invocation,
+ * exactly as the backend does — the command is invoked from the click handler,
+ * so those events land before React has committed the pending install state.
+ * Delaying them would let a listener that mounts on that state still catch them,
+ * hiding the very race the UI has to survive.
+ *
+ * Later lines are spaced so each is observable rather than collapsing into one
+ * frame with the next.
+ */
+const INSTALL_OUTPUT_REPLAY_GAP_MS = 1000;
+
+async function replayInstallOutput(
+  runtimeId: string,
+  lines: string[],
+): Promise<void> {
+  installOutputSeq = 0;
+  // The leading null is the clear signal the backend sends when an attempt
+  // starts, so this replays a whole attempt rather than only its output.
+  const events: (string | null)[] = [null, ...lines];
+  for (const [index, line] of events.entries()) {
+    // Index 0 and 1 are the clear and the first line: no gap before either.
+    if (index > 1) {
+      await new Promise((resolve) =>
+        window.setTimeout(resolve, INSTALL_OUTPUT_REPLAY_GAP_MS),
+      );
+    }
+    // `emit` reaches listeners registered through the real `listen` API, which
+    // is what the UI hook uses; mockIPC's shouldMockEvents wires the two.
+    await emit("acp-install-output", {
+      runtime_id: runtimeId,
+      seq: installOutputSeq++,
+      line,
+    });
+  }
+}
+
 async function handleInstallAcpRuntime(
   args: {
     runtimeId?: string;
@@ -7207,6 +7416,10 @@ async function handleInstallAcpRuntime(
   config: E2eConfig | undefined,
 ): Promise<RawInstallRuntimeResult> {
   const runtimeId = args.runtimeId ?? "";
+  const outputLines = config?.mock?.installAcpRuntimeOutputLines;
+  if (outputLines && outputLines.length > 0) {
+    await replayInstallOutput(runtimeId, outputLines);
+  }
   const perRuntime = config?.mock?.installAcpRuntimeByRuntime?.[runtimeId];
 
   if (perRuntime) {
@@ -7263,6 +7476,7 @@ async function handleInstallAcpRuntime(
     ],
     restarted_count: 0,
     failed_restart_count: 0,
+    log_path: null,
   };
 }
 
@@ -7441,7 +7655,7 @@ type MockUpdatePersonaInput = {
 async function handleUpdatePersona(args: {
   input: MockUpdatePersonaInput;
 }): Promise<RawPersona> {
-  return { ...applyMockPersonaUpdate(args.input) };
+  return { ...(await applyMockPersonaUpdate(args.input)) };
 }
 
 /**
@@ -7454,7 +7668,9 @@ async function handleUpdatePersona(args: {
  * make a UI that never calls `update_persona_and_publish` look like it kept
  * the "Save and publish" promise.
  */
-function applyMockPersonaUpdate(input: MockUpdatePersonaInput): RawPersona {
+async function applyMockPersonaUpdate(
+  input: MockUpdatePersonaInput,
+): Promise<RawPersona> {
   const persona = mockPersonas.find((candidate) => candidate.id === input.id);
   if (!persona) {
     throw new Error(`agent ${input.id} not found`);
@@ -7472,9 +7688,7 @@ function applyMockPersonaUpdate(input: MockUpdatePersonaInput): RawPersona {
   applyMockPersonaBehavior(persona, input.behavior);
   persona.updated_at = new Date().toISOString();
 
-  for (const callback of tauriEventListeners.get("agents-data-changed") ?? []) {
-    callback();
-  }
+  await emit("agents-data-changed");
   return persona;
 }
 
@@ -7636,7 +7850,10 @@ async function handleUpdatePersonaAndPublish(
   args: { input: MockUpdatePersonaInput },
   config?: E2eConfig,
 ): Promise<MockPersonaPublicationResult> {
-  return publishMockPersonaHead(applyMockPersonaUpdate(args.input), config);
+  return publishMockPersonaHead(
+    await applyMockPersonaUpdate(args.input),
+    config,
+  );
 }
 
 function ensureMockPersonaIsActive(personaId: string) {
@@ -8911,6 +9128,7 @@ async function resolveGetEvent(
 }
 
 async function connectRealSocket(args: { url?: string; onMessage: unknown }) {
+  relayWebsocketConnectAttemptStarts.push(Date.now());
   const wsId = nextSocketId++;
   const ws = new WebSocket(args.url ?? DEFAULT_RELAY_WS_URL);
   const handler = resolveHandler(args.onMessage);
@@ -8939,6 +9157,10 @@ async function connectRealSocket(args: { url?: string; onMessage: unknown }) {
 }
 
 async function connectMockSocket(args: { onMessage: unknown }) {
+  relayWebsocketConnectAttemptStarts.push(Date.now());
+  if (mockWebsocketUnavailable) {
+    throw new Error("mock relay unavailable");
+  }
   const connectError = getConfig()?.mock?.websocketConnectErrors?.shift();
   if (connectError) {
     throw new Error(connectError);
@@ -9384,6 +9606,8 @@ export function maybeInstallE2eTauriMocks() {
   }
 
   mockClosedChannelLiveSubscription = false;
+  mockWebsocketUnavailable = false;
+  relayWebsocketConnectAttemptStarts.length = 0;
   mockGlobalAgentConfig = config.mock?.globalAgentConfig
     ? { ...config.mock.globalAgentConfig }
     : null;
@@ -9399,6 +9623,7 @@ export function maybeInstallE2eTauriMocks() {
   resetMockPersonaCatalogEvents(config);
   resetMockSaveSubscriptions(config);
   resetMockPendingCommunityDeepLinks(config);
+  initializeMockHuddle(config.mock?.huddle);
   mockWebsocketSendMutexWedged = false;
   mockWindows("main");
   window.__BUZZ_E2E_COMMANDS__ = [];
@@ -9406,6 +9631,19 @@ export function maybeInstallE2eTauriMocks() {
   window.__BUZZ_E2E_COMMAND_LOG__ = [];
   window.__BUZZ_E2E_SIGNED_EVENTS__ = [];
   window.__BUZZ_E2E_WEBVIEW_ZOOM__ = 1;
+  window.__BUZZ_E2E_SET_MOCK_HUDDLE_SNAPSHOT__ = async ({
+    members,
+    transcriptionEnabled,
+  }) => {
+    if (!mockHuddle) {
+      throw new Error("No mock huddle is configured.");
+    }
+    mockHuddle.members = structuredClone(members);
+    mockHuddle.state.transcription_enabled = transcriptionEnabled;
+    refreshMockHuddleMembership();
+    persistMockHuddle();
+    await emitMockHuddleState();
+  };
   window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__ = ({
     channelName,
     content,
@@ -9415,6 +9653,7 @@ export function maybeInstallE2eTauriMocks() {
     mentionPubkeys,
     extraTags,
     createdAt,
+    pending,
     id,
   }) => {
     const channel = mockChannels.find(
@@ -9433,6 +9672,7 @@ export function maybeInstallE2eTauriMocks() {
       mentionPubkeys,
       extraTags,
       createdAt,
+      pending,
       id,
     );
   };
@@ -9605,6 +9845,19 @@ export function maybeInstallE2eTauriMocks() {
     }
     return sockets.length;
   };
+  window.__BUZZ_E2E_SET_MOCK_WEBSOCKET_UNAVAILABLE__ = (unavailable) => {
+    mockWebsocketUnavailable = unavailable;
+    if (unavailable) relayWebsocketConnectAttemptStarts.length = 0;
+  };
+  window.__BUZZ_E2E_GET_WEBSOCKET_CONNECT_ATTEMPTS__ = () => [
+    ...relayWebsocketConnectAttemptStarts,
+  ];
+  window.__BUZZ_E2E_ACTIVATE_RELAY_RATE_LIMIT__ = (seconds) => {
+    activateRateLimit(seconds);
+  };
+  window.__BUZZ_E2E_RESET_WEBSOCKET_CONNECT_ATTEMPTS__ = () => {
+    relayWebsocketConnectAttemptStarts.length = 0;
+  };
   // Tests vary mesh admission and models to exercise provider discovery and
   // the managed-agent start preflight.
   window.__BUZZ_E2E_SET_MESH__ = (mesh) => {
@@ -9660,7 +9913,25 @@ export function maybeInstallE2eTauriMocks() {
     deviceId: state === "running" ? "mock-endpoint-id" : null,
     deviceName: state === "running" ? "Mock desktop" : null,
   });
-  const handleMockCommand = async (command: string, payload: unknown) => {
+  let mockImportedVoices: Array<{
+    key: string;
+    displayName: string;
+    backend: string;
+    backendName: string;
+    availability: "installed";
+    fallbackKey: string;
+    referenceFile: string;
+    provenance: {
+      source: string;
+      contentHash: string;
+      license: null;
+      sourceUrl: null;
+    };
+  }> = [];
+  const handleMockCommand = async (
+    command: string,
+    payload: unknown,
+  ): Promise<unknown> => {
     const activeConfig = getConfig();
     const identity = getActiveIdentity(activeConfig);
     window.__BUZZ_E2E_COMMANDS__?.push(command);
@@ -9678,6 +9949,263 @@ export function maybeInstallE2eTauriMocks() {
     window.__BUZZ_E2E_COMMAND_LOG__?.push({ command, payload });
 
     switch (command) {
+      case "get_huddle_state": {
+        const snapshot = mockHuddle ? structuredClone(mockHuddle.state) : null;
+        const delayMs = activeConfig?.mock?.huddleStateReadDelayMs ?? 0;
+        if (delayMs > 0) {
+          await new Promise((resolve) => window.setTimeout(resolve, delayMs));
+        }
+        return snapshot;
+      }
+      case "get_huddle_agent_pubkeys":
+        if (!mockHuddle) return [];
+        return [...mockHuddle.state.agent_pubkeys];
+      case "set_huddle_transcription_enabled":
+        if (!mockHuddle) {
+          throw new Error("No active mock huddle.");
+        }
+        mockHuddle.state.transcription_enabled = Boolean(
+          (payload as { enabled?: boolean }).enabled,
+        );
+        persistMockHuddle();
+        await emitMockHuddleState();
+        return null;
+      case "add_agent_to_huddle": {
+        const result = activeConfig?.mock?.addAgentToHuddleResult;
+        if (!result) {
+          throw new Error("No mock add-agent result configured.");
+        }
+        return structuredClone(result);
+      }
+      case "get_model_status":
+        return { stt: "ready", tts: "ready" };
+      case "get_tts_settings":
+        return (
+          activeConfig?.mock?.ttsSettings ?? {
+            version: 1,
+            agentTextToSpeech: true,
+            voicePreferences: ["pocket:mary"],
+          }
+        );
+      case "list_voice_registry":
+        return [
+          ...[
+            [
+              "anna",
+              "Anna",
+              "anna.wav",
+              "p228_023_enhanced.wav",
+              "0a6de25cf12bf1540beb85979f306a92be81fecc051c547c5395e7e5237a3856",
+            ],
+            [
+              "vera",
+              "Vera",
+              "vera.wav",
+              "p229_023_enhanced.wav",
+              "309cf91a895830f15842b398f69a4962cb1f7e0bfab10e25dd27838e826c204b",
+            ],
+            [
+              "fantine",
+              "Fantine",
+              "fantine.wav",
+              "p244_023_enhanced.wav",
+              "5f07d4e2a3f20a15572aae885156b43ef3fc12ef3812996fd135680d9956448b",
+            ],
+            [
+              "charles",
+              "Charles",
+              "charles.wav",
+              "p254_023_enhanced.wav",
+              "6b681a429198f16e378d53bccb08d06939da7b00144a7696111d4f8f76be7756",
+            ],
+            [
+              "paul",
+              "Paul",
+              "paul.wav",
+              "p259_023_enhanced.wav",
+              "7aba504fe0b3b16478b69ed27ce6007e3cb42b0c1915b5f1c6a6024ae37d679b",
+            ],
+            [
+              "eponine",
+              "Eponine",
+              "eponine.wav",
+              "p262_023_enhanced.wav",
+              "a13c27fb47627b05223691a0ef2974358a18c886e6c2f9d2762ff1d02c20926b",
+            ],
+            [
+              "azelma",
+              "Azelma",
+              "azelma.wav",
+              "p303_023_enhanced.wav",
+              "60e3d26cdf2efdec5df712152c839928f4d5522821e6554ae11fd96c57ab1026",
+            ],
+            [
+              "george",
+              "George",
+              "george.wav",
+              "p315_023_enhanced.wav",
+              "29a41f93bf5236e5b21501091d7774c255d5f3d4e62fa4f9fdf0a92a793c84ae",
+            ],
+            [
+              "mary",
+              "Mary",
+              "reference_sample.wav",
+              "p333_023_enhanced.wav",
+              "a35b0468382218e9f37a9a7494d1e4b74deaf18d7ced22265b4e325bb55c183f",
+            ],
+            [
+              "jane",
+              "Jane",
+              "jane.wav",
+              "p339_023_enhanced.wav",
+              "2f12e7f155eb3118f55425394f1b049e5b1b67bdc9b3932c8ba4521420aeb84a",
+            ],
+            [
+              "michael",
+              "Michael",
+              "michael.wav",
+              "p360_023_enhanced.wav",
+              "b6743e9195e5e3fd34fe9d1633ae93f7ffab787b249e45f6467d7d6f7a6ee6ad",
+            ],
+            [
+              "eve",
+              "Eve",
+              "eve.wav",
+              "p361_023_enhanced.wav",
+              "396e7cbd066b0f3fb6d67fa26e7904076958239d736d4390f15b5fe88feb14cd",
+            ],
+          ].map(
+            ([id, displayName, referenceFile, upstreamFile, contentHash]) => ({
+              key: `pocket:${id}`,
+              displayName,
+              backend: "pocket",
+              backendName: "Pocket TTS",
+              availability: "bundled",
+              fallbackKey: id === "mary" ? null : "pocket:mary",
+              referenceFile,
+              provenance: {
+                source: "bundled",
+                contentHash,
+                license: "CC-BY-4.0",
+                sourceUrl: `https://huggingface.co/kyutai/tts-voices/blob/323332d33f997de8394f24a193e1a76df720e01a/vctk/${upstreamFile}`,
+              },
+            }),
+          ),
+          ...mockImportedVoices,
+        ];
+      case "set_tts_enabled": {
+        const enabled = (payload as { enabled?: boolean })?.enabled;
+        if (typeof enabled !== "boolean")
+          throw new Error("Missing text-to-speech enabled state");
+        const settings = {
+          version: 1,
+          agentTextToSpeech: enabled,
+          voicePreferences: activeConfig?.mock?.ttsSettings
+            ?.voicePreferences ?? ["pocket:mary"],
+        };
+        if (activeConfig) {
+          activeConfig.mock ??= {};
+          activeConfig.mock.ttsSettings = settings;
+        }
+        return settings;
+      }
+      case "set_pocket_voice": {
+        const voiceKey = (payload as { voiceKey?: string })?.voiceKey;
+        if (!voiceKey) throw new Error("Missing Pocket voice key");
+        const current = activeConfig?.mock?.ttsSettings ?? {
+          version: 1,
+          agentTextToSpeech: true,
+          voicePreferences: ["pocket:mary"],
+        };
+        const firstPocketIndex = current.voicePreferences.findIndex((key) =>
+          key.startsWith("pocket:"),
+        );
+        const preferences = current.voicePreferences.filter(
+          (key) => !key.startsWith("pocket:"),
+        );
+        preferences.splice(
+          firstPocketIndex < 0 ? preferences.length : firstPocketIndex,
+          0,
+          voiceKey,
+        );
+        const settings = { ...current, voicePreferences: preferences };
+        if (activeConfig) {
+          activeConfig.mock ??= {};
+          activeConfig.mock.ttsSettings = settings;
+        }
+        return settings;
+      }
+      case "preview_pocket_voice":
+        return null;
+      case "import_pocket_voice": {
+        const importResult =
+          activeConfig?.mock?.pocketVoiceImportResult ?? "success";
+        if (importResult === "cancel") return null;
+        if (importResult === "invalid") {
+          throw new Error("Voice WAV must contain PCM or 32-bit float audio");
+        }
+        const contentHash = "1".repeat(64);
+        const imported = {
+          key: `pocket:imported:${contentHash}`,
+          displayName: "My voice",
+          backend: "pocket",
+          backendName: "Pocket TTS",
+          availability: "installed" as const,
+          fallbackKey: "pocket:mary",
+          referenceFile: `${contentHash}.wav`,
+          provenance: {
+            source: "local import",
+            contentHash,
+            license: null,
+            sourceUrl: null,
+          },
+        };
+        mockImportedVoices = [imported];
+        const current = activeConfig?.mock?.ttsSettings ?? {
+          version: 1,
+          agentTextToSpeech: true,
+          voicePreferences: ["pocket:mary"],
+        };
+        const settings = {
+          ...current,
+          voicePreferences: [imported.key],
+        };
+        if (activeConfig) {
+          activeConfig.mock ??= {};
+          activeConfig.mock.ttsSettings = settings;
+        }
+        return {
+          settings,
+          registry: await handleMockCommand("list_voice_registry", null),
+        };
+      }
+      case "delete_pocket_voice": {
+        const voiceKey = (payload as { voiceKey?: string })?.voiceKey;
+        if (!voiceKey?.startsWith("pocket:imported:"))
+          throw new Error("Missing imported Pocket voice key");
+        mockImportedVoices = mockImportedVoices.filter(
+          (voice) => voice.key !== voiceKey,
+        );
+        const current = activeConfig?.mock?.ttsSettings ?? {
+          version: 1,
+          agentTextToSpeech: true,
+          voicePreferences: ["pocket:mary"],
+        };
+        const settings = {
+          ...current,
+          voicePreferences: current.voicePreferences.includes(voiceKey)
+            ? ["pocket:mary"]
+            : current.voicePreferences,
+        };
+        if (activeConfig) {
+          activeConfig.mock ??= {};
+          activeConfig.mock.ttsSettings = settings;
+        }
+        return {
+          settings,
+          registry: await handleMockCommand("list_voice_registry", null),
+        };
+      }
       case "get_builderlab_auth":
         return activeConfig?.mock?.builderlabAuth ?? null;
       case "start_builderlab_login": {
@@ -9736,6 +10264,25 @@ export function maybeInstallE2eTauriMocks() {
       }
       case "mesh_installed_models":
         return mockMeshState.models;
+      case "mesh_model_catalog":
+        return {
+          gpuName: "Mock Apple GPU",
+          vramDisplay: "32 GB",
+          vramGb: 32,
+          recommended: "Gemma-4-E4B-it-Q4_K_M",
+          entries: [
+            {
+              name: "Gemma-4-E4B-it-Q4_K_M",
+              size: "3.5GB",
+              sizeGb: 3.5,
+              description: "Buzz-curated local agent model",
+              fit: "comfortable",
+              installed: true,
+              recommended: true,
+              curated: true,
+            },
+          ],
+        };
       case "mesh_node_status":
         return meshNodeStatus(mockMeshState.nodeState, mockMeshState.nodeMode);
       case "mesh_serving_usage":
@@ -9811,6 +10358,60 @@ export function maybeInstallE2eTauriMocks() {
         // harness there is nothing to wipe; resolving is enough — specs
         // assert invocation via __BUZZ_E2E_COMMANDS__ and the pending UI.
         return;
+      case "generate_backup_passphrase": {
+        const request = payload as {
+          words?: number;
+          separator?: string;
+        } | null;
+        const wordCount = Math.min(Math.max(request?.words ?? 3, 3), 10);
+        return MOCK_PASSPHRASE_WORDS.slice(0, wordCount).join(
+          request?.separator ?? " ",
+        );
+      }
+      case "create_ncryptsec_backup": {
+        const delayMs = activeConfig?.mock?.backupEncryptionDelayMs ?? 0;
+        if (delayMs > 0) {
+          await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+        return MOCK_NCRYPTSEC;
+      }
+      case "save_ncryptsec_copy": {
+        const paths = activeConfig?.mock?.backupSavePaths ?? [
+          "/tmp/buzz-identity.ncryptsec",
+        ];
+        const index = Math.min(backupSaveCallCount, paths.length - 1);
+        backupSaveCallCount += 1;
+        return paths[index];
+      }
+      case "verify_ncryptsec_backup": {
+        const request = payload as { password?: string } | null;
+        const configuredErrors = activeConfig?.mock?.backupVerificationErrors;
+        const hasConfiguredResult = Boolean(
+          activeConfig?.mock?.backupVerificationPubkeys,
+        );
+        const errors = configuredErrors ?? [
+          hasConfiguredResult || request?.password === MOCK_BACKUP_PASSPHRASE
+            ? null
+            : "wrong backup password or damaged key backup",
+        ];
+        const index = Math.min(backupVerificationCallCount, errors.length - 1);
+        const error = errors[index];
+        if (error) {
+          backupVerificationCallCount += 1;
+          throw new Error(error);
+        }
+        const pubkeys = activeConfig?.mock?.backupVerificationPubkeys ?? [
+          identity?.pubkey ?? DEFAULT_MOCK_IDENTITY.pubkey,
+        ];
+        const pubkey = pubkeys[Math.min(index, pubkeys.length - 1)];
+        backupVerificationCallCount += 1;
+        return {
+          pubkey,
+          npub: npubEncode(pubkey),
+          matchesCurrentIdentity:
+            pubkey === (identity?.pubkey ?? DEFAULT_MOCK_IDENTITY.pubkey),
+        };
+      }
       case "get_nsec": {
         const nsecSequence = activeConfig?.mock?.nsecErrors;
         if (nsecSequence && nsecSequence.length > 0) {
@@ -9843,12 +10444,26 @@ export function maybeInstallE2eTauriMocks() {
           locked: false,
         };
       }
-      case "import_identity":
+      case "import_identity": {
+        const request = payload as { nsec?: string; password?: string } | null;
+        const input = request?.nsec ?? "";
+        if (input.trim().startsWith("ncryptsec1")) {
+          if (
+            input.trim() !== MOCK_NCRYPTSEC ||
+            request?.password !== MOCK_BACKUP_PASSPHRASE
+          ) {
+            throw new Error("Wrong backup password or damaged key backup.");
+          }
+          mockIdentityLostCleared = true;
+          mockIdentityLockedCleared = true;
+          return importMockIdentity(
+            nsecEncode(hexToBytes(DEFAULT_REAL_IDENTITY.privateKey)),
+          );
+        }
         mockIdentityLostCleared = true;
         mockIdentityLockedCleared = true;
-        return importMockIdentity(
-          (payload as { nsec?: string } | null)?.nsec ?? "",
-        );
+        return importMockIdentity(input);
+      }
       case "validate_repos_dir":
         // The browser harness has no host filesystem to validate. Treat the
         // seeded empty/default path as valid so Add Community can continue to
@@ -9865,6 +10480,12 @@ export function maybeInstallE2eTauriMocks() {
         }
         return;
       }
+      case "update_tray_agent_activity":
+      case "clear_tray_agent_activity":
+      case "requeue_tray_actions":
+        return null;
+      case "take_tray_actions":
+        return [];
       case "get_profile":
         return handleGetProfile(activeConfig);
       case "update_profile":
@@ -10535,9 +11156,7 @@ export function maybeInstallE2eTauriMocks() {
           }
         }
         // Mirror the real Rust backend: emit "agents-data-changed" after reconcile.
-        for (const cb of tauriEventListeners.get("agents-data-changed") ?? []) {
-          cb();
-        }
+        await emit("agents-data-changed");
         return undefined;
       }
       case "set_persona_active":
@@ -10663,6 +11282,9 @@ export function maybeInstallE2eTauriMocks() {
           memoryEntryCount: 0,
           hasSourceAllowlist: false,
           sourceAllowlistCount: 0,
+          sourceAllowlist: [],
+          manifestJson: "{}",
+          locked: false,
         };
       }
       case "confirm_agent_snapshot_import": {
@@ -11206,10 +11828,18 @@ export function maybeInstallE2eTauriMocks() {
       case "download_image":
       case "save_png_data_url":
       case "download_file":
+      case "save_agent_card":
         // The save dialog can't run headlessly; report a successful save so the
         // FileCard / image-menu click handlers resolve. Specs assert the
         // command was invoked via `__BUZZ_E2E_COMMANDS__`, not the dialog.
         return true;
+      case "card_mint_key_status":
+        // Cards: pretend a key is configured so the mint form renders.
+        return true;
+      case "list_agent_cards":
+        // Cards archive starts empty in E2E; specs exercising the gallery
+        // can extend this with a seeded config knob when needed.
+        return [];
       case "copy_image_to_clipboard":
         return;
       case "copy_text_to_clipboard":
@@ -11384,9 +12014,6 @@ export function maybeInstallE2eTauriMocks() {
       case "plugin:webview|set_webview_zoom":
         window.__BUZZ_E2E_WEBVIEW_ZOOM__ = (payload as { value: number }).value;
         return;
-      case "plugin:event|listen":
-        // Tauri event system (pairing, huddle) — no-op in e2e, return unlisten fn ID
-        return Math.floor(Math.random() * 1_000_000);
       case "start_pairing": {
         const delayMs = activeConfig?.mock?.pairingStartDelayMs ?? 0;
         if (delayMs > 0) {
@@ -11520,6 +12147,11 @@ export function maybeInstallE2eTauriMocks() {
         return null;
       case "plugin:window|is_fullscreen":
         return false;
+      // Settings reads the app version through the app plugin. Without this the
+      // bridge throws an unhandled page error on every Settings render, which
+      // shows up as noise in unrelated specs.
+      case "plugin:app|version":
+        return MOCK_APP_VERSION;
       case "merge_save_subscription_kinds": {
         // Mirrors `merge_owner_p_kinds`: union `kind` into the owner_p row's
         // kinds, creating the row if it doesn't exist yet.
@@ -11571,26 +12203,21 @@ export function maybeInstallE2eTauriMocks() {
   window.__BUZZ_E2E_INVOKE_MOCK_COMMAND__ = (command, payload) =>
     handleMockCommand(command, payload ?? null);
   mockIPC(handleMockCommand, { shouldMockEvents: true });
-
-  // Wire up __TAURI_INTERNALS__.listen so tests can subscribe to backend-emitted
-  // events (e.g. "agents-data-changed"). mockIPC already ensures __TAURI_INTERNALS__
-  // exists; we just add the listen property without clobbering invoke.
-  (
-    window as unknown as {
+  const tauriInternals = (
+    window as typeof window & {
       __TAURI_INTERNALS__: {
-        listen?: (event: string, cb: () => void) => Promise<() => void>;
+        listen?: (
+          event: string,
+          callback: () => void,
+        ) => Promise<() => Promise<void>>;
       };
     }
-  ).__TAURI_INTERNALS__.listen = async (event: string, cb: () => void) => {
-    let listeners = tauriEventListeners.get(event);
-    if (!listeners) {
-      listeners = new Set();
-      tauriEventListeners.set(event, listeners);
-    }
-    listeners.add(cb);
-    return () => {
-      tauriEventListeners.get(event)?.delete(cb);
-    };
+  ).__TAURI_INTERNALS__;
+  // Page-evaluated E2E specs use this surface; delegate to Tauri's mocked channel
+  // so their listeners observe the same events emitted by application test seams.
+  tauriInternals.listen = async (event, callback) => {
+    const unlisten = await listen(event, () => callback());
+    return async () => unlisten();
   };
 
   installed = true;
diff --git a/desktop/tests/e2e/activity-scope-label-screenshots.spec.ts b/desktop/tests/e2e/activity-scope-label-screenshots.spec.ts
index 0fee5ebf9d..4ed0a211e5 100644
--- a/desktop/tests/e2e/activity-scope-label-screenshots.spec.ts
+++ b/desktop/tests/e2e/activity-scope-label-screenshots.spec.ts
@@ -6,6 +6,8 @@ import { installMockBridge, TEST_IDENTITIES } from "../helpers/bridge";
 const SHOTS = "test-results/activity-scope-label";
 
 const AGENT_PUBKEY = TEST_IDENTITIES.tyler.pubkey;
+const LONG_AGENT_NAME =
+  "Observer Agent With An Exceptionally Long Display Name";
 const AGENTS_CHANNEL_ID = "94a444a4-c0a3-5966-ab05-530c6ddc2301"; // #agents
 
 // Open the activity pane via profile → "View activity" (same ingress the
@@ -57,9 +59,36 @@ test.describe("activity panel scope label", () => {
       "channel-agents",
       "agents",
     );
-    await expect(page.getByTestId("agent-session-scope-label")).toHaveText(
-      "#agents",
+    await expect(page.getByTestId("agent-session-agent-name")).toHaveText(
+      "Observer Agent",
     );
+    await expect(page.getByTestId("agent-session-agent-avatar")).toBeVisible();
+    const scope = page.getByTestId("agent-session-scope-label");
+    await expect(scope).toHaveText("Activity · #agents");
+    const recency = page.getByTestId("agent-session-recency-label");
+    await expect(recency).toHaveText("No updates yet");
+    await expect(recency).toBeVisible();
+
+    // Simulate long-scope pressure deterministically: scope owns truncation
+    // while the independently shrinking recency stays visible.
+    await scope.evaluate((element) => {
+      element.style.width = "5rem";
+      element.style.flex = "none";
+    });
+    expect(
+      await scope.evaluate((element) => element.scrollWidth),
+    ).toBeGreaterThan(await scope.evaluate((element) => element.clientWidth));
+    await expect(recency).toBeVisible();
+
+    await page.getByTestId("agent-session-settings-menu-trigger").click();
+    await page.getByTestId("agent-session-toggle-raw-feed").click();
+    await expect(scope).toHaveText("Raw ACP activity · #agents");
+    expect(
+      await scope.evaluate((element) => element.scrollWidth),
+    ).toBeGreaterThan(await scope.evaluate((element) => element.clientWidth));
+    await expect(recency).toHaveText("No updates yet");
+    await expect(recency).toBeVisible();
+    await page.keyboard.press("Escape");
 
     await waitForAnimations(page);
     await panel.screenshot({ path: `${SHOTS}/01-channel-scoped.png` });
@@ -75,11 +104,18 @@ test.describe("activity panel scope label", () => {
       managedAgents: [
         {
           pubkey: AGENT_PUBKEY,
-          name: "Observer Agent",
+          name: LONG_AGENT_NAME,
           status: "running" as const,
           channelNames: ["random"],
         },
       ],
+      searchProfiles: [
+        {
+          pubkey: AGENT_PUBKEY,
+          displayName: LONG_AGENT_NAME,
+          isAgent: true,
+        },
+      ],
     });
 
     await page.goto(
@@ -90,9 +126,36 @@ test.describe("activity panel scope label", () => {
 
     const panel = page.getByTestId("agent-session-thread-panel");
     await expect(panel).toBeVisible({ timeout: 10_000 });
-    await expect(page.getByTestId("agent-session-scope-label")).toHaveText(
-      "All channels",
+    await expect(page.getByTestId("agent-session-agent-name")).toHaveText(
+      LONG_AGENT_NAME,
+    );
+    const agentName = page.getByTestId("agent-session-agent-name");
+    expect(
+      await agentName.evaluate((element) => element.scrollWidth),
+    ).toBeGreaterThan(
+      await agentName.evaluate((element) => element.clientWidth),
+    );
+    const scope = page.getByTestId("agent-session-scope-label");
+    await expect(scope).toHaveText("Activity · All channels");
+    const recency = page.getByTestId("agent-session-recency-label");
+    await expect(recency).toHaveText("No updates yet");
+    await expect(recency).toBeVisible();
+
+    await page.setViewportSize({ width: 720, height: 700 });
+    await expect(scope).toBeVisible();
+    await expect(recency).toBeVisible();
+    const recencyWidth = await recency.evaluate(
+      (element) => element.clientWidth,
+    );
+
+    await page.getByTestId("agent-session-settings-menu-trigger").click();
+    await page.getByTestId("agent-session-toggle-raw-feed").click();
+    await expect(scope).toHaveText("Raw ACP activity · All channels");
+    await expect(recency).toBeVisible();
+    expect(await recency.evaluate((element) => element.clientWidth)).toBe(
+      recencyWidth,
     );
+    await page.keyboard.press("Escape");
 
     await waitForAnimations(page);
     await panel.screenshot({ path: `${SHOTS}/02-all-channels.png` });
diff --git a/desktop/tests/e2e/agent-access-warning.spec.ts b/desktop/tests/e2e/agent-access-warning.spec.ts
new file mode 100644
index 0000000000..709c5fbbc6
--- /dev/null
+++ b/desktop/tests/e2e/agent-access-warning.spec.ts
@@ -0,0 +1,205 @@
+import { expect, test } from "@playwright/test";
+
+import { waitForAnimations } from "../helpers/animations";
+import { installMockBridge, TEST_IDENTITIES } from "../helpers/bridge";
+
+const SHOTS = "test-results/agent-access-warning";
+
+async function choosePersonaAccess(
+  page: import("@playwright/test").Page,
+  optionName: string,
+) {
+  await page.locator("#agent-respond-to").click();
+  await page.getByRole("menuitemradio", { name: optionName }).click();
+}
+
+async function openAgentAccessDialog(
+  page: import("@playwright/test").Page,
+  agentPubkey: string,
+) {
+  if (!(await page.getByTestId("members-sidebar").isVisible())) {
+    await page.getByTestId("channel-general").click();
+    await page.getByTestId("channel-members-trigger").click();
+    await expect(page.getByTestId("members-sidebar")).toBeVisible();
+  }
+
+  const row = page.getByTestId(`sidebar-member-${agentPubkey}`);
+  const menu = page.getByTestId(`sidebar-member-menu-${agentPubkey}`);
+  await row.hover();
+  await menu.focus();
+  await menu.press("Enter");
+  await page.getByTestId(`sidebar-edit-respond-to-${agentPubkey}`).click();
+
+  await expect(
+    page.getByRole("dialog", { name: "Manage agent access" }),
+  ).toBeVisible();
+}
+
+test("open agent access explains the available access before save", async ({
+  page,
+}) => {
+  const agent = TEST_IDENTITIES.charlie;
+  await installMockBridge(page, {
+    managedAgents: [
+      {
+        pubkey: agent.pubkey,
+        name: "Hack Day Helper",
+        status: "running",
+        channelNames: ["general"],
+        respondTo: "owner-only",
+      },
+    ],
+  });
+  await page.goto("/");
+  await openAgentAccessDialog(page, agent.pubkey);
+
+  const accessSelect = page.getByTestId("agent-respond-to-select");
+  await expect(accessSelect).toHaveValue("owner-only");
+  await expect(page.getByTestId("agent-access-warning")).toHaveCount(0);
+  const saveAccess = page.getByRole("button", { name: "Save access" });
+  await expect(saveAccess).toBeVisible();
+
+  const commandsBeforeSave = await page.evaluate(
+    () => window.__BUZZ_E2E_COMMAND_LOG__?.length ?? 0,
+  );
+  await accessSelect.selectOption("anyone");
+  const warning = page.getByTestId("agent-access-warning");
+  await expect(warning).toBeVisible();
+  await expect(warning).toContainText(
+    "Anyone can use this agent to access your computer, including files, accounts, and connected tools.",
+  );
+
+  await waitForAnimations(page);
+  await page
+    .getByRole("dialog", { name: "Manage agent access" })
+    .screenshot({ path: `${SHOTS}/open-access-warning.png` });
+
+  await saveAccess.click();
+  await expect(
+    page.getByRole("dialog", { name: "Manage agent access" }),
+  ).not.toBeVisible();
+  await expect
+    .poll(async () =>
+      page.evaluate((start) => {
+        const commands = window.__BUZZ_E2E_COMMAND_LOG__ ?? [];
+        return commands
+          .slice(start)
+          .some(
+            (entry) =>
+              entry.command === "update_managed_agent" &&
+              (entry.payload as { input?: { respondTo?: string } })?.input
+                ?.respondTo === "anyone",
+          );
+      }, commandsBeforeSave),
+    )
+    .toBe(true);
+
+  await openAgentAccessDialog(page, agent.pubkey);
+  await expect(accessSelect).toHaveValue("anyone");
+  // Selected people narrows the audience but not the access, so the warning
+  // persists with its own audience phrase.
+  await accessSelect.selectOption("allowlist");
+  await expect(warning).toBeVisible();
+  await expect(warning).toContainText(
+    "Selected people can use this agent to access your computer, including files, accounts, and connected tools.",
+  );
+  const picker = page.getByTestId("agent-respond-to-allowlist");
+  await expect(
+    picker.getByText("Selected people", { exact: true }),
+  ).toBeVisible();
+
+  // The warning sits below the picker so it never blocks the selection the
+  // user came here to make.
+  await waitForAnimations(page);
+  const pickerBox = await picker.boundingBox();
+  const warningBox = await warning.boundingBox();
+  expect(pickerBox?.y).toBeDefined();
+  expect(warningBox?.y).toBeGreaterThan(pickerBox?.y ?? 0);
+  await page
+    .getByRole("dialog", { name: "Manage agent access" })
+    .screenshot({ path: `${SHOTS}/selected-people-warning.png` });
+
+  // Only me shares nothing, so the warning goes away entirely.
+  await accessSelect.selectOption("owner-only");
+  await expect(warning).toHaveCount(0);
+});
+
+test("a provider-backed agent's warning names the server, not this computer", async ({
+  page,
+}) => {
+  const agent = TEST_IDENTITIES.charlie;
+  await installMockBridge(page, {
+    managedAgents: [
+      {
+        pubkey: agent.pubkey,
+        name: "Remote Helper",
+        status: "running",
+        channelNames: ["general"],
+        respondTo: "owner-only",
+        backend: { type: "provider", id: "blox", config: {} },
+      },
+    ],
+  });
+  await page.goto("/");
+  await openAgentAccessDialog(page, agent.pubkey);
+
+  await page.getByTestId("agent-respond-to-select").selectOption("anyone");
+  const warning = page.getByTestId("agent-access-warning");
+  await expect(warning).toContainText(
+    "Anyone can use this agent to access the server it runs on, including any accounts and tools available there.",
+  );
+  // The local wording must not leak into a remote-backed agent.
+  await expect(warning).not.toContainText("your computer");
+});
+
+test("persona-backed edit warns before saving open access", async ({
+  page,
+}) => {
+  const agent = TEST_IDENTITIES.tyler;
+  await installMockBridge(page, {
+    managedAgents: [
+      {
+        pubkey: agent.pubkey,
+        name: "Tyler Agent",
+        status: "stopped",
+        channelNames: ["agents"],
+        respondTo: "owner-only",
+      },
+    ],
+  });
+  await page.goto("/");
+  await page.getByTestId("open-agents-view").click();
+  await page.getByRole("button", { name: "Tyler Agent agent profile" }).click();
+  await page.getByTestId("user-profile-edit-agent").click();
+
+  const dialog = page.getByTestId("edit-agent-dialog");
+  await expect(dialog).toBeVisible();
+  await expect(page.locator("#agent-respond-to")).toHaveText(
+    "Only me (default)",
+  );
+  await choosePersonaAccess(page, "Anyone");
+  await expect(dialog.getByTestId("agent-access-warning")).toContainText(
+    "Anyone can use this agent to access your computer, including files, accounts, and connected tools.",
+  );
+
+  const commandsBeforeSave = await page.evaluate(
+    () => window.__BUZZ_E2E_COMMAND_LOG__?.length ?? 0,
+  );
+  await page.getByTestId("edit-agent-dialog-submit").click();
+  await expect(dialog).not.toBeVisible();
+  await expect
+    .poll(async () =>
+      page.evaluate((start) => {
+        const commands = window.__BUZZ_E2E_COMMAND_LOG__ ?? [];
+        return commands
+          .slice(start)
+          .some(
+            (entry) =>
+              entry.command === "update_managed_agent" &&
+              (entry.payload as { input?: { respondTo?: string } })?.input
+                ?.respondTo === "anyone",
+          );
+      }, commandsBeforeSave),
+    )
+    .toBe(true);
+});
diff --git a/desktop/tests/e2e/agents.spec.ts b/desktop/tests/e2e/agents.spec.ts
index 2e7cdc9e83..3cbe097c05 100644
--- a/desktop/tests/e2e/agents.spec.ts
+++ b/desktop/tests/e2e/agents.spec.ts
@@ -93,10 +93,10 @@ async function sharePersonaToCatalog(
 ) {
   await page.getByLabel(`Open actions for ${displayName}`).click();
   await page.getByRole("menuitem", { name: "Share" }).click();
-  await page.getByTestId("persona-share-catalog-access").click();
-  await page
-    .getByRole("menuitemradio", { name: "Shared", exact: true })
-    .click();
+  const catalogToggle = page.getByTestId("persona-share-catalog-access");
+  await expect(catalogToggle).not.toBeChecked();
+  await catalogToggle.click();
+  await expect(catalogToggle).toBeChecked();
   await page
     .getByTestId("persona-share-dialog")
     .getByRole("button", { name: "Close" })
@@ -416,7 +416,7 @@ test("the new agent card offers create, discover, and import", async ({
   const cardBoxes = await agentCards.evaluateAll((cards) =>
     cards.map((card) => {
       const box = card.getBoundingClientRect();
-      return { right: box.right, top: box.top };
+      return { left: box.left, right: box.right, top: box.top };
     }),
   );
   const firstRowTop = Math.min(...cardBoxes.map(({ top }) => top));
@@ -425,12 +425,16 @@ test("the new agent card offers create, discover, and import", async ({
       .filter(({ top }) => Math.abs(top - firstRowTop) < 1)
       .map(({ right }) => right),
   );
+  const leftmostFirstRowCard = Math.min(
+    ...cardBoxes
+      .filter(({ top }) => Math.abs(top - firstRowTop) < 1)
+      .map(({ left }) => left),
+  );
   expect(headerBox).not.toBeNull();
-  expect(
-    Math.abs(
-      (headerBox?.x ?? 0) + (headerBox?.width ?? 0) - rightmostFirstRowCard,
-    ),
-  ).toBeLessThan(1);
+  expect(Math.abs((headerBox?.x ?? 0) - leftmostFirstRowCard)).toBeLessThan(1);
+  expect(rightmostFirstRowCard).toBeLessThanOrEqual(
+    (headerBox?.x ?? 0) + (headerBox?.width ?? 0) + 1,
+  );
 
   await newAgentCard.click();
   await expect(
@@ -492,6 +496,63 @@ test("the new team card offers create and import", async ({ page }) => {
   ).toBeVisible();
 });
 
+test("team cards follow the agents grid alignment at compact widths", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    personas: [
+      {
+        id: "custom:team-layout",
+        displayName: "Team layout agent",
+        systemPrompt: "A test agent for team layout alignment.",
+      },
+    ],
+    teams: [
+      {
+        id: "team-layout",
+        name: "Team layout",
+        personaIds: ["custom:team-layout"],
+      },
+    ],
+  });
+  await gotoApp(page);
+  await page.getByTestId("open-agents-view").click();
+
+  const agentsContent = page.getByTestId("agents-page-content");
+  const firstAgentCard = page.getByTestId(
+    "persona-agent-row-custom:team-layout",
+  );
+  const firstTeamCard = page.getByTestId("team-card-team-layout");
+  const agentGrid = firstAgentCard.locator("xpath=..");
+  const teamGrid = firstTeamCard.locator("xpath=..");
+  const firstAgentGridCard = agentGrid.locator(":scope > *").first();
+  const firstTeamGridCard = teamGrid.locator(":scope > *").first();
+
+  await agentsContent.evaluate((element) => {
+    (element as HTMLElement).style.width = "650px";
+  });
+  const wideAgentBox = await firstAgentGridCard.boundingBox();
+  const wideTeamBox = await firstTeamGridCard.boundingBox();
+  expect(wideAgentBox).not.toBeNull();
+  expect(wideTeamBox).not.toBeNull();
+  expect(Math.abs((wideAgentBox?.x ?? 0) - (wideTeamBox?.x ?? 0))).toBeLessThan(
+    1,
+  );
+
+  await agentsContent.evaluate((element) => {
+    (element as HTMLElement).style.width = "600px";
+  });
+  await expect
+    .poll(async () => (await firstAgentGridCard.boundingBox())?.x ?? 0)
+    .toBeGreaterThan(wideAgentBox?.x ?? 0);
+
+  const compactAgentBox = await firstAgentGridCard.boundingBox();
+  const compactTeamBox = await firstTeamGridCard.boundingBox();
+  expect(
+    Math.abs((compactAgentBox?.x ?? 0) - (compactTeamBox?.x ?? 0)),
+  ).toBeLessThan(1);
+});
+
 test("team cards use the thread-style overlapping avatar stack", async ({
   page,
 }) => {
@@ -634,6 +695,62 @@ test("unconfigured agent defaults use the setup label", async ({ page }) => {
   );
 });
 
+test("moves agent actions into an overflow menu in a narrow view", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    personas: [
+      {
+        id: "custom:compact-actions",
+        displayName: "Compact actions agent",
+        isActive: true,
+        systemPrompt: "A test agent for compact header actions.",
+      },
+    ],
+    managedAgents: [
+      {
+        name: "Compact actions instance",
+        personaId: "custom:compact-actions",
+        pubkey: "cd".repeat(32),
+        status: "running",
+      },
+    ],
+  });
+  await gotoApp(page);
+  await page.getByTestId("open-agents-view").click();
+  await page.getByTestId("agents-page-content").evaluate((element) => {
+    (element as HTMLElement).style.width = "650px";
+  });
+
+  await expect(page.getByTestId("agent-defaults-button")).toBeVisible();
+  await expect(
+    page.getByText("Set up and manage your agents.", { exact: true }),
+  ).toHaveJSProperty("scrollHeight", 24);
+
+  await page.getByTestId("agents-page-content").evaluate((element) => {
+    (element as HTMLElement).style.width = "600px";
+  });
+  await expect(page.getByTestId("agent-defaults-button")).toBeHidden();
+  await page.getByTestId("agent-actions-menu-trigger").click();
+  await expect(
+    page.getByRole("menuitem", { name: "Set agent defaults" }),
+  ).toBeVisible();
+  await expect(
+    page.getByRole("menuitem", { name: "Stop running agents" }),
+  ).toBeVisible();
+
+  await page.getByRole("menuitem", { name: "Set agent defaults" }).click();
+  await expect(page.getByTestId("agent-ai-defaults-dialog")).toBeVisible();
+
+  await page.getByTestId("agents-page-content").evaluate((element) => {
+    (element as HTMLElement).style.width = "650px";
+  });
+  await expect(page.getByTestId("agent-defaults-button")).toBeVisible();
+  await page.keyboard.press("Escape");
+  await expect(page.getByTestId("agent-ai-defaults-dialog")).toHaveCount(0);
+  await expect(page.getByTestId("agent-defaults-button")).toBeFocused();
+});
+
 test("agent catalog chooser order stays stable when selection changes", async ({
   page,
 }) => {
@@ -862,21 +979,27 @@ test("custom personas share with people and keep export separate", async ({
     page.getByRole("heading", { name: "Share Animation Auditor" }),
   ).toBeVisible();
   await expect(shareDialog.getByText("Added by You")).toHaveCount(0);
-  const sendDescription = shareDialog.getByTestId(
-    "persona-share-send-description",
-  );
-  await expect(sendDescription).toHaveText(
-    "They’ll receive a copy they can add and use. Changes you make later won’t sync.",
-  );
-  await expect(sendDescription).toHaveClass(
-    /text-xs.*text-secondary-foreground\/75/,
+  const shareDescription = shareDialog.getByTestId(
+    "persona-share-share-description",
+  );
+  await expect(shareDescription).toHaveText(
+    "Anyone you share this agent with will receive a copy they can add and use. Changes you make later won’t sync.",
+  );
+  await expect(shareDescription).toHaveClass(/text-sm.*text-muted-foreground/);
+  const shareDescriptionId = await shareDescription.getAttribute("id");
+  expect(shareDescriptionId).toBeTruthy();
+  await expect(shareDialog).toHaveAttribute(
+    "aria-describedby",
+    shareDescriptionId ?? "",
+  );
+  const shareDescriptionMetrics = await shareDescription.evaluate(
+    (element) => ({
+      height: element.getBoundingClientRect().height,
+      lineHeight: Number.parseFloat(getComputedStyle(element).lineHeight),
+    }),
   );
-  const sendDescriptionMetrics = await sendDescription.evaluate((element) => ({
-    height: element.getBoundingClientRect().height,
-    lineHeight: Number.parseFloat(getComputedStyle(element).lineHeight),
-  }));
-  expect(sendDescriptionMetrics.height).toBeLessThanOrEqual(
-    sendDescriptionMetrics.lineHeight + 1,
+  expect(shareDescriptionMetrics.height).toBeLessThanOrEqual(
+    shareDescriptionMetrics.lineHeight * 2 + 1,
   );
   await expect(
     shareDialog.getByRole("heading", { name: "Who has access" }),
@@ -884,57 +1007,49 @@ test("custom personas share with people and keep export separate", async ({
   await expect(shareDialog.getByText("Owner", { exact: true })).toHaveCount(0);
   await expect(shareDialog.getByText("(You)", { exact: true })).toHaveCount(0);
   const linkRow = page.getByTestId("persona-share-link-row");
+  await expect(page.getByTestId("persona-share-copy-link")).toBeVisible();
   await expect(
-    linkRow.getByRole("heading", { name: "Share with a link" }),
-  ).toBeVisible();
+    shareDialog.getByRole("heading", { name: "Share with a link" }),
+  ).toHaveCount(0);
   await expect(
-    linkRow.getByText("Anyone with the link can add and use a copy."),
-  ).toHaveClass(/text-xs.*text-secondary-foreground\/75/);
+    shareDialog.getByText("Anyone with the link can add and use a copy."),
+  ).toHaveCount(0);
   await expect(page.getByTestId("persona-share-send")).toHaveCount(0);
   const copyLinkButton = page.getByTestId("persona-share-copy-link");
-  const linkIcon = page.getByTestId("persona-share-link-icon");
-  const linkCopy = page.getByTestId("persona-share-link-copy");
   const catalogSection = page.getByTestId("persona-share-catalog");
-  const staticShareLevel = page.getByTestId("persona-share-share-level");
-  const shareLevelRow = page.getByTestId("persona-share-share-level-row");
+  const shareMainCard = page.getByTestId("persona-share-main-card");
+  const exportAgentRow = page.getByTestId("persona-share-export");
   await waitForAnimations(page);
   const [
     linkRowBox,
     initialCopyLinkButtonBox,
-    linkIconBox,
-    linkCopyBox,
     catalogSectionBox,
-    staticShareLevelBox,
-    shareLevelRowBox,
+    shareMainCardBox,
+    exportAgentRowBox,
   ] = await Promise.all([
     linkRow.boundingBox(),
     copyLinkButton.boundingBox(),
-    linkIcon.boundingBox(),
-    linkCopy.boundingBox(),
     catalogSection.boundingBox(),
-    staticShareLevel.boundingBox(),
-    shareLevelRow.boundingBox(),
+    shareMainCard.boundingBox(),
+    exportAgentRow.boundingBox(),
   ]);
-  const sendDescriptionBox = await sendDescription.boundingBox();
+  const shareDescriptionBox = await shareDescription.boundingBox();
   const recipientFieldBox = await page
     .getByTestId("persona-share-recipient-field")
     .boundingBox();
-  // Reading order: who → how it goes out → what's included → catalog.
-  expect(sendDescriptionBox?.y ?? 0).toBeGreaterThanOrEqual(
-    (recipientFieldBox?.y ?? 0) + (recipientFieldBox?.height ?? 0),
-  );
-  expect(linkRowBox?.y ?? 0).toBeGreaterThanOrEqual(
-    (sendDescriptionBox?.y ?? 0) + (sendDescriptionBox?.height ?? 0),
+  // Without memories, the recipient field flows directly into the link action.
+  expect(recipientFieldBox?.y ?? 0).toBeGreaterThanOrEqual(
+    (shareDescriptionBox?.y ?? 0) + (shareDescriptionBox?.height ?? 0),
   );
-  expect(shareLevelRowBox?.y ?? 0).toBeGreaterThanOrEqual(
-    (linkRowBox?.y ?? 0) + (linkRowBox?.height ?? 0),
+  await expect(page.getByTestId("persona-share-link-settings")).toHaveCount(0);
+  await expect(page.getByTestId("persona-share-share-level-row")).toHaveCount(
+    0,
   );
-  expect(catalogSectionBox?.y ?? 0).toBeGreaterThanOrEqual(
-    (shareLevelRowBox?.y ?? 0) + (shareLevelRowBox?.height ?? 0),
+  expect(linkRowBox?.y ?? 0).toBeGreaterThanOrEqual(
+    (recipientFieldBox?.y ?? 0) + (recipientFieldBox?.height ?? 0),
   );
-  // Copy link is the link row's own action, not a stranded footer button, so
-  // it rides on that row, vertically centred with the link icon and flush to
-  // the row's right edge.
+  // Copy link stays inside the main card, after the shared settings divider, while catalog and
+  // export are separate rows below it.
   expect(initialCopyLinkButtonBox?.y ?? 0).toBeGreaterThanOrEqual(
     linkRowBox?.y ?? 0,
   );
@@ -942,40 +1057,15 @@ test("custom personas share with people and keep export separate", async ({
     (initialCopyLinkButtonBox?.y ?? 0) +
       (initialCopyLinkButtonBox?.height ?? 0),
   ).toBeLessThanOrEqual((linkRowBox?.y ?? 0) + (linkRowBox?.height ?? 0) + 1);
-  expect(
-    Math.abs(
-      (initialCopyLinkButtonBox?.y ?? 0) +
-        (initialCopyLinkButtonBox?.height ?? 0) / 2 -
-        ((linkIconBox?.y ?? 0) + (linkIconBox?.height ?? 0) / 2),
-    ),
-  ).toBeLessThanOrEqual(1);
-  expect(
-    Math.abs(
-      (linkRowBox?.x ?? 0) +
-        (linkRowBox?.width ?? 0) -
-        ((initialCopyLinkButtonBox?.x ?? 0) +
-          (initialCopyLinkButtonBox?.width ?? 0)),
-    ),
-  ).toBeLessThanOrEqual(1);
-  expect(
-    Math.abs(
-      (linkCopyBox?.y ?? 0) +
-        (linkCopyBox?.height ?? 0) / 2 -
-        ((linkIconBox?.y ?? 0) + (linkIconBox?.height ?? 0) / 2),
-    ),
-  ).toBeLessThanOrEqual(1);
-  await expect(page.getByTestId("persona-share-link-divider")).toHaveCount(0);
-  await expect(page.getByTestId("persona-share-copy-link-footer")).toHaveCount(
-    0,
+  await expect(page.getByTestId("persona-share-link-divider")).toHaveClass(
+    /bg-input\/40/,
+  );
+  expect(catalogSectionBox?.y ?? 0).toBeGreaterThanOrEqual(
+    (shareMainCardBox?.y ?? 0) + (shareMainCardBox?.height ?? 0) + 12,
+  );
+  expect(exportAgentRowBox?.y ?? 0).toBeGreaterThanOrEqual(
+    (catalogSectionBox?.y ?? 0) + (catalogSectionBox?.height ?? 0) + 12,
   );
-  expect(
-    Math.abs(
-      (shareLevelRowBox?.y ?? 0) +
-        (shareLevelRowBox?.height ?? 0) / 2 -
-        ((staticShareLevelBox?.y ?? 0) +
-          (staticShareLevelBox?.height ?? 0) / 2),
-    ),
-  ).toBeLessThanOrEqual(1);
   await expect(copyLinkButton).toHaveClass(
     /border.*bg-background.*border-border/,
   );
@@ -992,12 +1082,7 @@ test("custom personas share with people and keep export separate", async ({
   await expect.poll(copyLinkHasVisibleShadow).toBe(false);
   await copyLinkButton.hover();
   await expect.poll(copyLinkHasVisibleShadow).toBe(false);
-  await expect(page.getByTestId("persona-share-share-level")).toHaveText(
-    "No memories included",
-  );
-  await expect(
-    shareDialog.getByText("No memories included", { exact: true }),
-  ).toHaveCount(1);
+  await expect(page.getByTestId("persona-share-share-level")).toHaveCount(0);
   await expect(page.getByTestId("persona-share-recipient-access")).toHaveCount(
     0,
   );
@@ -1014,20 +1099,10 @@ test("custom personas share with people and keep export separate", async ({
   await expect(
     shareDialog.getByText("File format", { exact: true }),
   ).toHaveCount(0);
-  const shareMainCard = page.getByTestId("persona-share-main-card");
-  const exportAgentRow = page.getByTestId("persona-share-export");
   await expect(exportAgentRow).toHaveText("Export agent");
   await expect(shareMainCard.getByTestId("persona-share-export")).toHaveCount(
     0,
   );
-  await waitForAnimations(page);
-  const shareMainCardBox = await shareMainCard.boundingBox();
-  const exportAgentRowBox = await exportAgentRow.boundingBox();
-  const shareCardGap =
-    (exportAgentRowBox?.y ?? 0) -
-    ((shareMainCardBox?.y ?? 0) + (shareMainCardBox?.height ?? 0));
-  expect(shareCardGap).toBeGreaterThanOrEqual(12);
-  expect(shareCardGap).toBeLessThan(16);
   const [shareMainCardStyles, exportAgentRowStyles] = await Promise.all([
     shareMainCard.evaluate((element) => ({
       borderRadius: getComputedStyle(element).borderRadius,
@@ -1411,9 +1486,9 @@ This deliberately long fenced-code example must not establish the minimum width
   const shareMainCard = shareDialog.getByTestId("persona-share-main-card");
   const copyLinkButton = shareDialog.getByTestId("persona-share-copy-link");
   const catalogSection = shareDialog.getByTestId("persona-share-catalog");
-  await expect(
-    shareMainCard.getByTestId("persona-share-catalog"),
-  ).toBeVisible();
+  await expect(shareMainCard.getByTestId("persona-share-catalog")).toHaveCount(
+    0,
+  );
   await expect(catalogSection).toContainText("Share to catalog");
   await expect(catalogSection).toContainText(
     "Anyone in this community can find and use a copy.",
@@ -1427,26 +1502,18 @@ This deliberately long fenced-code example must not establish the minimum width
       catalogSection.boundingBox(),
       shareMainCard.boundingBox(),
     ]);
-  // Copy link belongs to the link row above, so the catalog is the section
-  // that closes the card rather than trailing an orphaned button.
+  // Catalog is its own card below the sharing controls.
   expect(
     (copyLinkButtonBox?.y ?? 0) + (copyLinkButtonBox?.height ?? 0),
-  ).toBeLessThanOrEqual(catalogSectionBox?.y ?? 0);
-  expect(
-    (catalogSectionBox?.y ?? 0) + (catalogSectionBox?.height ?? 0),
   ).toBeLessThanOrEqual(
     (shareMainCardBox?.y ?? 0) + (shareMainCardBox?.height ?? 0),
   );
-  await expect(catalogAccess).toHaveText("Not shared");
+  expect(catalogSectionBox?.y ?? 0).toBeGreaterThanOrEqual(
+    (shareMainCardBox?.y ?? 0) + (shareMainCardBox?.height ?? 0),
+  );
+  await expect(catalogAccess).not.toBeChecked();
   await catalogAccess.click();
-  await expect(page.getByRole("menuitemradio")).toHaveText([
-    "Not shared",
-    "Shared",
-  ]);
-  await page
-    .getByRole("menuitemradio", { name: "Shared", exact: true })
-    .click();
-  await expect(catalogAccess).toHaveText("Shared");
+  await expect(catalogAccess).toBeChecked();
   const storedPersonas = await invokeTauri<
     Array<{ id: string; shared: boolean }>
   >(page, "list_personas");
@@ -1534,11 +1601,9 @@ This deliberately long fenced-code example must not establish the minimum width
 
   await page.getByLabel("Open actions for Catalog Analyst").click();
   await page.getByRole("menuitem", { name: "Share" }).click();
-  await expect(catalogAccess).toHaveText("Shared");
+  await expect(catalogAccess).toBeChecked();
   await catalogAccess.click();
-  await page
-    .getByRole("menuitemradio", { name: "Not shared", exact: true })
-    .click();
+  await expect(catalogAccess).not.toBeChecked();
   await page
     .getByTestId("persona-share-dialog")
     .getByRole("button", { name: "Close" })
@@ -1570,9 +1635,6 @@ test("a queued catalog share is not presented as relay-published", async ({
   await page.getByLabel("Open actions for Queued Catalog Agent").click();
   await page.getByRole("menuitem", { name: "Share" }).click();
   await page.getByTestId("persona-share-catalog-access").click();
-  await page
-    .getByRole("menuitemradio", { name: "Shared", exact: true })
-    .click();
 
   await expect(
     page.getByText(
@@ -1674,8 +1736,10 @@ test("a community member can discover and add another member's catalog agent", a
   );
   await expect(remoteEntry).toContainText("Alice’s Reviewer");
   await remoteEntry.click();
+  // The detail pane resolves the publisher's display name; 'Community member'
+  // is only the fallback for an unresolvable pubkey.
   await expect(page.getByTestId("persona-catalog-detail-pane")).toContainText(
-    "Added by Community member",
+    "Added by alice",
   );
 
   await page
@@ -1728,11 +1792,57 @@ test("a community member can discover and add another member's catalog agent", a
   expect(await countCommandInvocations(page, "create_persona")).toBe(1);
 });
 
+test("catalog detail shows Community member when the publisher profile cannot be resolved", async ({
+  page,
+}) => {
+  // A pubkey that is not in the mock profile registry — profile resolution
+  // will fail and the detail pane must fall back gracefully.
+  const unknownPubkey =
+    "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+  const personaId = "unresolvable-reviewer";
+  await installMockBridge(page, {
+    personaCatalogEvents: [
+      createCatalogEvent({
+        ownerPubkey: unknownPubkey,
+        sourcePersonaId: personaId,
+        displayName: "Mystery Agent",
+        systemPrompt: "Published by someone whose profile cannot be fetched.",
+      }),
+    ],
+  });
+  await gotoApp(page);
+  await page.getByTestId("open-agents-view").click();
+  await openPersonaCatalog(page);
+
+  await page
+    .getByTestId(
+      `persona-catalog-list-item-catalog:${unknownPubkey}:${personaId}`,
+    )
+    .click();
+  await expect(page.getByTestId("persona-catalog-detail-pane")).toContainText(
+    "Added by Community member",
+  );
+});
+
 test("one share level selector drives both the link and send paths", async ({
   page,
 }) => {
   await page.emulateMedia({ reducedMotion: "no-preference" });
   const linkedAgentPubkey = TEST_IDENTITIES.alice.pubkey;
+  const profileAvatarUrl = "https://mock.relay/media/profile-only-avatar.png";
+  const profileAvatarBytes = Uint8Array.from(
+    atob(
+      "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=",
+    ),
+    (character) => character.charCodeAt(0),
+  );
+  await page.route(profileAvatarUrl, async (route) => {
+    await route.fulfill({
+      body: Buffer.from(profileAvatarBytes),
+      contentType: "image/png",
+      status: 200,
+    });
+  });
   await page.context().grantPermissions(["clipboard-read", "clipboard-write"]);
   await installMockBridge(page, {
     personas: [
@@ -1751,6 +1861,12 @@ test("one share level selector drives both the link and send paths", async ({
       },
     ],
     searchProfiles: [
+      {
+        pubkey: linkedAgentPubkey,
+        displayName: "Animation Auditor",
+        avatarUrl: profileAvatarUrl,
+        isAgent: true,
+      },
       {
         pubkey: TEST_IDENTITIES.charlie.pubkey,
         displayName: "Charlie",
@@ -1781,7 +1897,7 @@ test("one share level selector drives both the link and send paths", async ({
   const shareLevel = shareDialog.getByLabel("What to include", {
     exact: true,
   });
-  const catalogAccess = shareDialog.getByLabel("What to share in the catalog");
+  const catalogAccess = shareDialog.getByLabel("Share to catalog");
   const recipientField = page.getByTestId("persona-share-recipient-field");
   const emptyRecipientFieldBox = await recipientField.boundingBox();
   await expect(shareDialog.getByTestId("persona-share-send")).toHaveCount(0);
@@ -1793,13 +1909,14 @@ test("one share level selector drives both the link and send paths", async ({
   await expect(shareLevel).toHaveCSS("text-decoration-line", "none");
   await expect(shareLevel).toHaveCSS("padding-left", "8px");
   await expect(shareLevel).toHaveCSS("padding-right", "8px");
-  await expect(catalogAccess).toHaveText("Not shared");
-  await catalogAccess.click();
-  await expect(page.getByRole("menuitemradio")).toHaveText([
-    "Not shared",
-    "Shared",
-  ]);
-  await page.keyboard.press("Escape");
+  await expect(catalogAccess).not.toBeChecked();
+  await expect(catalogAccess).toHaveCSS("cursor", "default");
+  await expect(
+    shareDialog.getByTestId("persona-share-link-settings"),
+  ).toContainText("Share settings");
+  await expect(
+    shareDialog.getByText("Share settings", { exact: true }),
+  ).toHaveClass(/text-xs.*text-secondary-foreground\/75/);
   const copyLinkButton = shareDialog.getByTestId("persona-share-copy-link");
   const recipientFieldBox = await recipientField.boundingBox();
   const [shareLevelBox, copyLinkButtonBox, catalogAccessBox] =
@@ -1808,15 +1925,15 @@ test("one share level selector drives both the link and send paths", async ({
       copyLinkButton.boundingBox(),
       catalogAccess.boundingBox(),
     ]);
-  // Reading order: who → how it goes out → what's included → catalog.
-  expect(copyLinkButtonBox?.y ?? 0).toBeGreaterThanOrEqual(
+  // Reading order: who → what's included → copy link → catalog.
+  expect(shareLevelBox?.y ?? 0).toBeGreaterThanOrEqual(
     (recipientFieldBox?.y ?? 0) + (recipientFieldBox?.height ?? 0),
   );
-  expect(shareLevelBox?.y ?? 0).toBeGreaterThanOrEqual(
-    (copyLinkButtonBox?.y ?? 0) + (copyLinkButtonBox?.height ?? 0),
+  expect(copyLinkButtonBox?.y ?? 0).toBeGreaterThanOrEqual(
+    (shareLevelBox?.y ?? 0) + (shareLevelBox?.height ?? 0),
   );
   expect(catalogAccessBox?.y ?? 0).toBeGreaterThanOrEqual(
-    (shareLevelBox?.y ?? 0) + (shareLevelBox?.height ?? 0),
+    (copyLinkButtonBox?.y ?? 0) + (copyLinkButtonBox?.height ?? 0),
   );
   // The memory choice is stated once, governing both delivery actions —
   // neither the recipients row nor the link row carries its own copy.
@@ -1999,6 +2116,9 @@ test("one share level selector drives both the link and send paths", async ({
       expect.objectContaining({
         memoryLevel: "core",
         memorySourcePubkey: linkedAgentPubkey,
+        avatarPngDataUrl: `data:image/png;base64,${Buffer.from(
+          profileAvatarBytes,
+        ).toString("base64")}`,
       }),
       expect.objectContaining({
         memoryLevel: "everything",
diff --git a/desktop/tests/e2e/community-rail.spec.ts b/desktop/tests/e2e/community-rail.spec.ts
index 0c78108190..3b24b87f39 100644
--- a/desktop/tests/e2e/community-rail.spec.ts
+++ b/desktop/tests/e2e/community-rail.spec.ts
@@ -145,6 +145,7 @@ test.describe("community rail", () => {
     await expect(page.getByTestId("community-invite-email-field")).toHaveCount(
       0,
     );
+    await expect(page.getByTestId("member-pubkey-input")).toBeVisible();
     await expect(page.getByTestId("copy-invite-link")).toBeVisible();
   });
 
diff --git a/desktop/tests/e2e/custom-emoji.spec.ts b/desktop/tests/e2e/custom-emoji.spec.ts
index aa345570f9..ae20aaef25 100644
--- a/desktop/tests/e2e/custom-emoji.spec.ts
+++ b/desktop/tests/e2e/custom-emoji.spec.ts
@@ -1,6 +1,9 @@
 import { expect, test } from "@playwright/test";
+import * as fs from "node:fs";
+import * as path from "node:path";
 
 import { installMockBridge } from "../helpers/bridge";
+import { waitForAnimations } from "../helpers/animations";
 
 // Custom-emoji end-to-end guard.
 //
@@ -77,6 +80,55 @@ test("typing a known :shortcode: renders an inline emoji node in the composer",
   await expect(input).not.toContainText(`:${SHORTCODE}:`);
 });
 
+test("emoji autocomplete ranks an exact standard shortcode before a custom substring", async ({
+  page,
+}, testInfo) => {
+  await openGeneral(page);
+
+  const input = page.getByTestId("message-input");
+  await input.click();
+  await input.pressSequentially(":joy");
+
+  const autocomplete = page.getByTestId("emoji-autocomplete");
+  await expect(autocomplete).toBeVisible();
+  const labels = await autocomplete.locator("button").allTextContents();
+  expect(labels[0]).toContain(":joy:");
+  expect(
+    labels.findIndex((label) => label.includes(":bufo_joy:")),
+  ).toBeGreaterThan(0);
+
+  const screenshotDir = path.resolve(
+    "test-results/emoji-autocomplete-screenshots",
+  );
+  fs.mkdirSync(screenshotDir, { recursive: true });
+  const screenshotPath = path.join(
+    screenshotDir,
+    "joy-exact-before-custom-substring.png",
+  );
+  await waitForAnimations(page);
+  await autocomplete.screenshot({ path: screenshotPath });
+  await testInfo.attach("joy-exact-before-custom-substring", {
+    path: screenshotPath,
+    contentType: "image/png",
+  });
+});
+
+test("emoji autocomplete keeps semantic matches ahead of loose shortcode fallbacks", async ({
+  page,
+}) => {
+  await openGeneral(page);
+
+  const input = page.getByTestId("message-input");
+  await input.click();
+  await input.pressSequentially(":sad");
+
+  const autocomplete = page.getByTestId("emoji-autocomplete");
+  await expect(autocomplete).toBeVisible();
+  await expect(autocomplete.locator("button").first()).not.toContainText(
+    ":sandwich:",
+  );
+});
+
 test("custom emoji deletes as a single unit (like a built-in emoji)", async ({
   page,
 }) => {
diff --git a/desktop/tests/e2e/doctor-states.spec.ts b/desktop/tests/e2e/doctor-states.spec.ts
index 77d0fbcb45..2d69a4e0da 100644
--- a/desktop/tests/e2e/doctor-states.spec.ts
+++ b/desktop/tests/e2e/doctor-states.spec.ts
@@ -983,4 +983,91 @@ test.describe("Doctor panel state screenshots", () => {
       path: `${SHOTS}/08-concurrent-installs-and-stale-clear.png`,
     });
   });
+  /**
+   * 09 — install observability: the live output line appears while the install
+   * runs and disappears when it settles, and the failure message points at the
+   * install log rather than only the truncated last step.
+   */
+  test("09-install-output-line-and-log-pointer", async ({ page }) => {
+    await installMockBridge(page, {
+      acpRuntimesCatalog: [
+        GOOSE_AVAILABLE,
+        CLAUDE_AVAILABLE_LOGGED_IN,
+        {
+          ...CODEX_NOT_INSTALLED,
+          can_auto_install: true,
+          node_required: false,
+        },
+        BUZZ_AGENT_AVAILABLE,
+      ],
+      installAcpRuntimeDelayMs: 500,
+      installAcpRuntimeOutputLines: [
+        "npm http fetch GET 200 @zed-industries/codex-acp",
+        "npm warn deprecated a transitive dependency",
+      ],
+      installAcpRuntimeResult: {
+        success: false,
+        steps: [
+          {
+            step: "adapter",
+            command: "npm install -g @zed-industries/codex-acp",
+            success: false,
+            stdout: "",
+            stderr: "npm ERR! code E404",
+            exit_code: 1,
+          },
+        ],
+        log_path: "/tmp/buzz-install-codex.log",
+      },
+    });
+
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await openSettings(page, "agents");
+
+    const row = page.getByTestId("doctor-runtime-codex");
+    await expect(row).toBeVisible({ timeout: 10_000 });
+
+    const installButton = page.getByTestId("doctor-runtime-install-codex");
+    await expect(installButton).toBeEnabled();
+    await installButton.click();
+
+    // The bridge emits the attempt-start clear and the first line synchronously
+    // with the install invocation — before React commits the pending state — so
+    // observing this line proves the listener was already mounted at the click.
+    // A subscription that waited for the install state would have missed both.
+    const outputLine = page.getByTestId("doctor-runtime-install-output-codex");
+    await expect(outputLine).toContainText("npm http fetch", {
+      timeout: 5_000,
+    });
+
+    // Each new line replaces the previous one rather than accumulating.
+    await expect(outputLine).toContainText("npm warn deprecated", {
+      timeout: 5_000,
+    });
+    await expect(outputLine).not.toContainText("npm http fetch");
+
+    // Settled: the line clears, so a finished install leaves no stale output
+    // under a fresh Install button.
+    const installError = page.getByTestId("doctor-runtime-install-error-codex");
+    await expect(installError).toBeVisible({ timeout: 5_000 });
+    await expect(outputLine).toHaveCount(0);
+
+    // The failure points at the log holding bounded output for every attempt.
+    await expect(installError).toContainText("npm ERR! code E404");
+    await expect(installError).toContainText("/tmp/buzz-install-codex.log");
+
+    await row.scrollIntoViewIfNeeded();
+    await waitForAnimations(page);
+    await row.screenshot({
+      path: `${SHOTS}/09-install-output-line-and-log-pointer.png`,
+    });
+
+    // A second install shows its own output. The backend sequence restarts per
+    // run, so a display that kept the previous run's sequence number would
+    // reject every event of this one and show nothing at all.
+    await installButton.click();
+    await expect(outputLine).toContainText("npm http fetch", {
+      timeout: 5_000,
+    });
+  });
 });
diff --git a/desktop/tests/e2e/empty-edit-delete.spec.ts b/desktop/tests/e2e/empty-edit-delete.spec.ts
new file mode 100644
index 0000000000..772506571b
--- /dev/null
+++ b/desktop/tests/e2e/empty-edit-delete.spec.ts
@@ -0,0 +1,120 @@
+import { expect, test } from "@playwright/test";
+
+import { installMockBridge } from "../helpers/bridge";
+
+// The mock identity's own pre-seeded message in #general (authored by
+// DEFAULT_MOCK_IDENTITY.pubkey in e2eBridge.ts). Editing/deleting one's own
+// message is exactly Sam's workflow: "delete a message by clearing its edit."
+const OWN_MESSAGE_ID = "mock-general-welcome";
+const ORIGINAL_CONTENT = "Welcome to #general";
+
+// Open the more-actions menu for a message row and wait for the menu to mount.
+async function openMoreActionsMenu(
+  page: import("@playwright/test").Page,
+  messageId: string,
+) {
+  const row = page.locator(`[data-message-id="${messageId}"]`);
+  await row.hover();
+  await page.getByTestId(`more-actions-${messageId}`).click();
+  await expect(page.locator('[role="menuitem"]').first()).toBeVisible({
+    timeout: 5_000,
+  });
+}
+
+// Enter edit mode for a message, clear it to empty, and submit — the gesture
+// that triggers the empty-edit delete confirmation.
+async function submitEmptyEdit(
+  page: import("@playwright/test").Page,
+  messageId: string,
+) {
+  await openMoreActionsMenu(page, messageId);
+  await page.getByTestId(`edit-message-${messageId}`).click();
+  await expect(page.getByTestId("edit-target")).toBeVisible({ timeout: 5_000 });
+  // Edit mode sets the editor content via Tiptap's async transaction pipeline;
+  // wait for it to populate before we clear it.
+  const input = page.getByTestId("message-input");
+  await expect(input).not.toBeEmpty({ timeout: 5_000 });
+  await input.click();
+  await page.keyboard.press("ControlOrMeta+A");
+  await page.keyboard.press("Backspace");
+  await expect(input).toBeEmpty();
+  await page.keyboard.press("Enter");
+}
+
+test.beforeEach(async ({ page }) => {
+  await installMockBridge(page);
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+});
+
+test("clearing an edit to empty prompts to delete, then deletes on confirm", async ({
+  page,
+}) => {
+  const row = page.locator(`[data-message-id="${OWN_MESSAGE_ID}"]`);
+  await expect(row).toBeVisible({ timeout: 10_000 });
+
+  await submitEmptyEdit(page, OWN_MESSAGE_ID);
+
+  // The same "Delete message?" confirmation the Delete menu action shows — an
+  // empty edit is routed through it, not silently deleted.
+  const dialog = page.getByRole("alertdialog");
+  await expect(dialog).toBeVisible({ timeout: 5_000 });
+  await expect(dialog).toContainText("Delete message?");
+  // Edit mode stays active while the dialog is open — it exits only on confirm.
+  await expect(page.getByTestId("edit-target")).toBeVisible();
+
+  // Confirm → the message row is removed and edit mode has exited.
+  await dialog.getByRole("button", { name: "Delete" }).click();
+  await expect(dialog).toBeHidden({ timeout: 5_000 });
+  await expect(page.getByTestId("edit-target")).toBeHidden();
+  await expect(row).toBeHidden({ timeout: 5_000 });
+});
+
+test("cancelling the empty-edit delete keeps the message", async ({ page }) => {
+  const row = page.locator(`[data-message-id="${OWN_MESSAGE_ID}"]`);
+  await expect(row).toBeVisible({ timeout: 10_000 });
+
+  await submitEmptyEdit(page, OWN_MESSAGE_ID);
+
+  const dialog = page.getByRole("alertdialog");
+  await expect(dialog).toBeVisible({ timeout: 5_000 });
+
+  // Cancel → nothing is deleted, the original message survives, and the user is
+  // left in edit mode (the editing session is preserved, not discarded).
+  await dialog.getByRole("button", { name: "Cancel" }).click();
+  await expect(dialog).toBeHidden({ timeout: 5_000 });
+  await expect(page.getByTestId("edit-target")).toBeVisible();
+  await expect(row).toBeVisible();
+  await expect(page.getByTestId("message-timeline")).toContainText(
+    ORIGINAL_CONTENT,
+  );
+});
+
+test("a non-empty edit still edits and never deletes", async ({ page }) => {
+  const row = page.locator(`[data-message-id="${OWN_MESSAGE_ID}"]`);
+  await expect(row).toBeVisible({ timeout: 10_000 });
+
+  await openMoreActionsMenu(page, OWN_MESSAGE_ID);
+  await page.getByTestId(`edit-message-${OWN_MESSAGE_ID}`).click();
+  await expect(page.getByTestId("edit-target")).toBeVisible({ timeout: 5_000 });
+  const input = page.getByTestId("message-input");
+  await expect(input).not.toBeEmpty({ timeout: 5_000 });
+  const editedContent = `Edited, not deleted ${Date.now()}`;
+
+  await input.click();
+  await page.keyboard.press("ControlOrMeta+A");
+  await page.keyboard.type(editedContent);
+  await page.keyboard.press("Enter");
+
+  // No delete confirmation, edit mode exits, the row survives with new text.
+  await expect(page.getByRole("alertdialog")).toHaveCount(0);
+  await expect(page.getByTestId("edit-target")).toBeHidden({ timeout: 5_000 });
+  await expect(row).toBeVisible();
+  await expect(page.getByTestId("message-timeline")).toContainText(
+    editedContent,
+  );
+  await expect(page.getByTestId("message-timeline")).not.toContainText(
+    ORIGINAL_CONTENT,
+  );
+});
diff --git a/desktop/tests/e2e/harness-management.spec.ts b/desktop/tests/e2e/harness-management.spec.ts
index 50047f8f81..c5b441ad21 100644
--- a/desktop/tests/e2e/harness-management.spec.ts
+++ b/desktop/tests/e2e/harness-management.spec.ts
@@ -21,6 +21,7 @@
 import { expect, test } from "@playwright/test";
 
 import { installMockBridge } from "../helpers/bridge";
+import { passThroughBackupStep } from "../helpers/onboarding";
 
 // ── Shared catalog fixtures ───────────────────────────────────────────────────
 
@@ -668,12 +669,10 @@ test("onboarding setup More-harnesses click navigates to Settings → Agents", a
   });
   await page.goto("/");
 
-  // Reach the setup page: create a new identity key → skip backup step.
+  // Reach setup by creating a new identity key and continuing past the
+  // created-key page without opening the optional backup options.
   await page.getByRole("button", { name: "Create a new identity key" }).click();
-  await expect(page.getByTestId("onboarding-page-backup")).toBeVisible({
-    timeout: 10_000,
-  });
-  await page.getByTestId("onboarding-next").click();
+  await passThroughBackupStep(page);
 
   // Now on the setup page.
   await expect(
diff --git a/desktop/tests/e2e/helpers/twoRelayHarness.ts b/desktop/tests/e2e/helpers/twoRelayHarness.ts
index 98acd86398..43eb458417 100644
--- a/desktop/tests/e2e/helpers/twoRelayHarness.ts
+++ b/desktop/tests/e2e/helpers/twoRelayHarness.ts
@@ -162,6 +162,7 @@ export class TwoRelayHarness {
       BUZZ_METRICS_PORT: String(relay.ports.metrics),
       BUZZ_REQUIRE_AUTH_TOKEN: "false",
       BUZZ_RECONCILE_CHANNELS: "true",
+      BUZZ_AUTO_MIGRATE: "true",
     });
     await this.waitForHealth(relay, child);
   }
diff --git a/desktop/tests/e2e/huddle-transcription.spec.ts b/desktop/tests/e2e/huddle-transcription.spec.ts
new file mode 100644
index 0000000000..5d9d867175
--- /dev/null
+++ b/desktop/tests/e2e/huddle-transcription.spec.ts
@@ -0,0 +1,254 @@
+import { expect, test } from "@playwright/test";
+
+import { installMockBridge, TEST_IDENTITIES } from "../helpers/bridge";
+
+const HUDDLE_CHANNEL_ID = "11111111-1111-4111-8111-111111111111";
+const HUDDLE_PARENT_ID = "9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50";
+
+async function setHuddleSnapshot(
+  page: import("@playwright/test").Page,
+  members: Array<{
+    pubkey: string;
+    role: "member" | "bot";
+  }>,
+  transcriptionEnabled: boolean,
+) {
+  await page.evaluate(
+    async ({ nextMembers, nextTranscriptionEnabled }) => {
+      const setSnapshot = (
+        window as Window & {
+          __BUZZ_E2E_SET_MOCK_HUDDLE_SNAPSHOT__?: (input: {
+            members: Array<{
+              pubkey: string;
+              role: "member" | "bot";
+            }>;
+            transcriptionEnabled: boolean;
+          }) => Promise<void>;
+        }
+      ).__BUZZ_E2E_SET_MOCK_HUDDLE_SNAPSHOT__;
+      if (!setSnapshot) {
+        throw new Error("Mock huddle snapshot control is not installed.");
+      }
+      await setSnapshot({
+        members: nextMembers,
+        transcriptionEnabled: nextTranscriptionEnabled,
+      });
+    },
+    { nextMembers: members, nextTranscriptionEnabled: transcriptionEnabled },
+  );
+}
+
+test("renders authoritative huddle snapshots and sends explicit off once", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members: [
+        { pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" },
+        { pubkey: TEST_IDENTITIES.alice.pubkey, role: "bot" },
+      ],
+      transcriptionEnabled: true,
+    },
+  });
+
+  await page.goto("/");
+
+  const transcriptButton = page.getByRole("button", {
+    name: "Stop transcript",
+  });
+  await expect(transcriptButton).toBeVisible();
+  await expect(transcriptButton).toHaveAttribute("aria-pressed", "true");
+  const activeBackground = await transcriptButton.evaluate(
+    (button) => getComputedStyle(button).backgroundColor,
+  );
+  await page
+    .getByRole("button", { name: "Show huddle participants (2)" })
+    .click();
+  await expect(
+    page.getByRole("button", { name: /Remove .* from huddle/ }),
+  ).toHaveCount(1);
+  await page.keyboard.press("Escape");
+
+  await setHuddleSnapshot(
+    page,
+    [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
+    true,
+  );
+  await expect(
+    page.getByRole("button", { name: "Show huddle participants (1)" }),
+  ).toBeVisible();
+  await expect(transcriptButton).toHaveAttribute("aria-pressed", "true");
+
+  await setHuddleSnapshot(
+    page,
+    [
+      { pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" },
+      { pubkey: TEST_IDENTITIES.alice.pubkey, role: "bot" },
+    ],
+    true,
+  );
+  await expect(transcriptButton).toHaveAttribute("aria-pressed", "true");
+
+  await transcriptButton.click();
+  await expect(
+    page.getByRole("button", { name: "Start transcript" }),
+  ).toHaveAttribute("aria-pressed", "false");
+  const inactiveTranscriptButton = page.getByRole("button", {
+    name: "Start transcript",
+  });
+  await expect
+    .poll(() =>
+      inactiveTranscriptButton.evaluate(
+        (button) => getComputedStyle(button).backgroundColor,
+      ),
+    )
+    .not.toBe(activeBackground);
+
+  const explicitToggleCommands = await page.evaluate(() =>
+    (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
+      (entry) => entry.command === "set_huddle_transcription_enabled",
+    ),
+  );
+  expect(explicitToggleCommands).toEqual([
+    {
+      command: "set_huddle_transcription_enabled",
+      payload: { enabled: false },
+    },
+  ]);
+
+  await page.reload();
+  await expect(
+    page.getByRole("button", { name: "Start transcript" }),
+  ).toHaveAttribute("aria-pressed", "false");
+  await expect(
+    page.getByRole("button", { name: "Show huddle participants (2)" }),
+  ).toBeVisible();
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
+            (entry) => entry.command === "set_huddle_transcription_enabled",
+          ).length,
+      ),
+    )
+    .toBe(0);
+
+  await setHuddleSnapshot(
+    page,
+    [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
+    false,
+  );
+  await expect(
+    page.getByRole("button", { name: "Show huddle participants (1)" }),
+  ).toBeVisible();
+  await expect(
+    page.getByRole("button", { name: "Start transcript" }),
+  ).toHaveAttribute("aria-pressed", "false");
+});
+
+test("keeps a newer huddle event over a delayed hydration snapshot", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members: [
+        { pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" },
+        { pubkey: TEST_IDENTITIES.alice.pubkey, role: "bot" },
+      ],
+      transcriptionEnabled: true,
+    },
+    huddleStateReadDelayMs: 250,
+  });
+  await page.goto("/");
+  await expect
+    .poll(() =>
+      page.evaluate(() =>
+        (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).some(
+          (entry) => entry.command === "get_huddle_state",
+        ),
+      ),
+    )
+    .toBe(true);
+
+  await setHuddleSnapshot(
+    page,
+    [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
+    false,
+  );
+
+  await expect(
+    page.getByRole("button", { name: "Show huddle participants (1)" }),
+  ).toBeVisible();
+  await expect(
+    page.getByRole("button", { name: "Start transcript" }),
+  ).toHaveAttribute("aria-pressed", "false");
+  await page.waitForTimeout(300);
+  await expect(
+    page.getByRole("button", { name: "Show huddle participants (1)" }),
+  ).toBeVisible();
+});
+
+test("starts an agent DM huddle with the agent enrolled", async ({ page }) => {
+  await installMockBridge(page);
+  await page.goto("/");
+  await page.getByTestId("channel-alice-tyler").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("alice-tyler");
+
+  const startButton = page.getByTestId("channel-start-huddle-trigger");
+  await expect(startButton).toBeEnabled();
+  await startButton.click();
+
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).find(
+            (entry) => entry.command === "start_huddle",
+          )?.payload,
+      ),
+    )
+    .toMatchObject({
+      memberPubkeys: [TEST_IDENTITIES.alice.pubkey],
+      parentChannelId: "f48efb06-0c93-5025-aac9-2e646bb6bfa8",
+    });
+});
+
+test("closes add-agent dialog when parent membership is already satisfied", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    addAgentToHuddleResult: {
+      ephemeral_added: true,
+      parent_added: true,
+      parent_error: null,
+    },
+    huddle: {
+      parentChannelId: HUDDLE_PARENT_ID,
+      ephemeralChannelId: HUDDLE_CHANNEL_ID,
+      members: [{ pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" }],
+    },
+    managedAgents: [
+      {
+        pubkey: TEST_IDENTITIES.bob.pubkey,
+        name: "bob",
+        status: "running",
+      },
+    ],
+  });
+  await page.goto("/");
+
+  await page.getByRole("button", { name: "Add agent to huddle" }).click();
+  const dialog = page.getByRole("dialog", { name: "Add Agent to Huddle" });
+  await expect(dialog).toBeVisible();
+  await dialog.getByRole("button", { name: /bob/i }).click();
+
+  await expect(dialog).toHaveCount(0);
+  await expect(
+    page.getByText("Added to huddle, but parent channel failed:"),
+  ).toHaveCount(0);
+});
diff --git a/desktop/tests/e2e/invite-link-copy.spec.ts b/desktop/tests/e2e/invite-link-copy.spec.ts
index 94bc8e26b0..20df59a00c 100644
--- a/desktop/tests/e2e/invite-link-copy.spec.ts
+++ b/desktop/tests/e2e/invite-link-copy.spec.ts
@@ -3,7 +3,10 @@ import { expect, test } from "@playwright/test";
 import { installMockBridge } from "../helpers/bridge";
 import { openSettings } from "../helpers/settings";
 
+let invitePayloads: Record<string, unknown>[];
+
 test.beforeEach(async ({ page }) => {
+  invitePayloads = [];
   await page.context().grantPermissions(["clipboard-read", "clipboard-write"], {
     origin: "http://127.0.0.1:4173",
   });
@@ -11,6 +14,7 @@ test.beforeEach(async ({ page }) => {
     relayRequiresMembership: true,
   });
   await page.route("**/api/invites", async (route) => {
+    invitePayloads.push(route.request().postDataJSON());
     await route.fulfill({
       contentType: "application/json",
       json: {
@@ -31,10 +35,17 @@ test("copies a freshly minted invite link without showing a URL or QR code", asy
   await expect(page.getByTestId("settings-community-members")).toBeVisible();
 
   await page.getByTestId("community-invite-dialog-trigger").click();
+  await expect(page.getByTestId("member-pubkey-input")).toBeVisible();
+  await expect(page.getByTestId("member-role")).toHaveCount(0);
+  await expect(page.getByTestId("confirm-add-member")).toHaveCount(0);
   await expect(page.getByTestId("invite-link-url")).toHaveCount(0);
   await expect(page.getByTestId("invite-link-qr-code")).toHaveCount(0);
+  await expect(page.getByTestId("invite-link-max-uses-trigger")).toHaveText(
+    "No limit",
+  );
   await page.getByTestId("copy-invite-link").click();
   await expect(page.getByTestId("copy-invite-link")).toContainText("Copied");
+  expect(invitePayloads).toEqual([{ ttl_secs: 3 * 24 * 60 * 60 }]);
 
   const payload = await page.evaluate(() => {
     const log = (
@@ -53,3 +64,25 @@ test("copies a freshly minted invite link without showing a URL or QR code", asy
     text: "buzz://join?relay=wss%3A%2F%2Frelay.example.com&code=qr-download-test",
   });
 });
+
+test("sets a selected invite-use limit", async ({ page }) => {
+  await page.goto("/");
+  await openSettings(page, "community-members");
+  await page.getByTestId("community-invite-dialog-trigger").click();
+
+  const maxUsesTrigger = page.getByTestId("invite-link-max-uses-trigger");
+  await maxUsesTrigger.click();
+  await expect(
+    page.getByRole("menuitemradio", { name: "No limit" }),
+  ).toBeVisible();
+  await expect(
+    page.getByRole("menuitemradio", { name: "25 uses" }),
+  ).toBeVisible();
+  await page.getByTestId("invite-link-max-uses-10").click();
+  await expect(maxUsesTrigger).toHaveText("10 uses");
+  await page.getByTestId("copy-invite-link").click();
+  await expect(page.getByTestId("copy-invite-link")).toContainText("Copied");
+  expect(invitePayloads).toEqual([
+    { max_uses: 10, ttl_secs: 3 * 24 * 60 * 60 },
+  ]);
+});
diff --git a/desktop/tests/e2e/invites-settings-screenshots.spec.ts b/desktop/tests/e2e/invites-settings-screenshots.spec.ts
index 654aec56fe..e0856ac400 100644
--- a/desktop/tests/e2e/invites-settings-screenshots.spec.ts
+++ b/desktop/tests/e2e/invites-settings-screenshots.spec.ts
@@ -1,15 +1,25 @@
 import { expect, test } from "@playwright/test";
 
 import { waitForAnimations } from "../helpers/animations";
-import { installMockBridge } from "../helpers/bridge";
+import { TEST_IDENTITIES, installMockBridge } from "../helpers/bridge";
 import { openSettings } from "../helpers/settings";
 
 const OUTDIR = "test-results/invites-settings";
+const DIRECT_ADD_HEX =
+  "ea9b4d7a7a78a3e3729e5568b14d764d4962be0e1f20f749bcf8d9dbbf9a9328";
+const DIRECT_ADD_NPUB =
+  "npub1a2d567n60z37xu57245tzntkf4yk90swrus0wjdulrvah0u6jv5qusyp60";
+const SECOND_DIRECT_ADD_HEX =
+  "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+const SECOND_DIRECT_ADD_NPUB =
+  "npub1424242424242424242424242424242424242424242424242424qamrcaj";
 
-test.beforeEach(async ({ page }) => {
+test.beforeEach(async ({ page }, testInfo) => {
   await installMockBridge(page, {
     relayRequiresMembership: true,
-    relayRole: "owner",
+    relayRole: testInfo.title.includes("admin can add members")
+      ? "admin"
+      : "owner",
   });
   await page.route("**/api/invites", async (route) => {
     await route.fulfill({
@@ -26,6 +36,15 @@ test.beforeEach(async ({ page }) => {
   await openSettings(page, "community-members");
 });
 
+test("opens a profile from a community member avatar", async ({ page }) => {
+  await page.getByRole("button", { name: "Open profile for alice" }).click();
+
+  await expect(page).toHaveURL(
+    new RegExp(`/pulse\\?profile=${TEST_IDENTITIES.alice.pubkey}$`),
+  );
+  await expect(page.getByTestId("user-profile-panel")).toBeVisible();
+});
+
 test("capture: consolidated invites settings", async ({ page }) => {
   const panel = page.getByTestId("settings-panel-community-members");
 
@@ -78,23 +97,133 @@ test("capture: share-style community invite dialog", async ({ page }) => {
   await expect(page.getByTestId("community-invite-email-field")).toHaveCount(0);
   await expect(page.getByPlaceholder("Type an email address")).toHaveCount(0);
   await expect(
-    dialog.getByRole("heading", { name: "Share with a link" }),
+    dialog.getByText(
+      "Add someone directly or share a link they can use to join.",
+    ),
   ).toBeVisible();
+  await expect(
+    dialog.getByRole("heading", { name: "Add someone", exact: true }),
+  ).toHaveCount(0);
+  await expect(
+    dialog.getByText("Or share a link", { exact: true }),
+  ).toHaveCount(0);
+  await expect(
+    dialog.getByText("Link settings", { exact: true }),
+  ).toBeVisible();
+  await expect(page.getByTestId("member-pubkey-input")).toBeVisible();
+  await expect(page.getByTestId("member-role")).toHaveCount(0);
+  await expect(page.getByTestId("confirm-add-member")).toHaveCount(0);
   await expect(page.getByTestId("copy-invite-link")).toHaveText("Copy link");
-  await expect(page.getByTestId("invite-link-qr-code")).toHaveCount(0);
-  await expect(page.getByTestId("invite-link-url")).toHaveCount(0);
+  await expect(page.getByTestId("invite-link-ttl-trigger")).toHaveText(
+    "3 days",
+  );
 
-  const expiryTrigger = page.getByTestId("invite-link-ttl-trigger");
-  await expect(expiryTrigger).toHaveText("3 days");
-  await expiryTrigger.click();
+  await page.getByTestId("member-pubkey-input").fill(DIRECT_ADD_NPUB);
+  await expect(page.getByTestId("member-search-popover")).toBeVisible();
+  await page.getByTestId(`member-search-result-${DIRECT_ADD_HEX}`).click();
+  const memberRole = page.getByTestId("member-role");
+  const selectedChip = page.getByTestId(
+    `member-search-selection-remove-${DIRECT_ADD_HEX}`,
+  );
+  await expect(memberRole).toHaveText("Member");
+  const inviteButton = page.getByTestId("confirm-add-member");
+  await expect(inviteButton).toHaveText("Invite");
+  await waitForAnimations(page);
+  await expect(inviteButton).toHaveCSS("height", "44px");
+  await expect(inviteButton).toHaveJSProperty(
+    "offsetHeight",
+    await page
+      .getByTestId("member-recipient-field")
+      .evaluate((field) => Math.round(field.getBoundingClientRect().height)),
+  );
+  const selectedChipRemoveIcon = selectedChip.locator("span.absolute");
+  await expect(selectedChipRemoveIcon).toHaveCSS("opacity", "0");
+  await selectedChip.hover();
+  await expect(selectedChipRemoveIcon).toHaveCSS("opacity", "1");
+  const memberSearch = page.getByTestId("member-pubkey-input");
+  await expect(memberSearch).toBeFocused();
+  await memberSearch.fill(SECOND_DIRECT_ADD_NPUB);
+  await expect(page.getByTestId("member-search-popover")).toBeVisible();
+  await page
+    .getByTestId(`member-search-result-${SECOND_DIRECT_ADD_HEX}`)
+    .click();
   await expect(
-    page.getByRole("menuitemradio", { name: "1 day" }),
+    page.getByTestId(`member-search-selection-remove-${SECOND_DIRECT_ADD_HEX}`),
   ).toBeVisible();
+  await expect(memberSearch).toBeFocused();
+  await memberRole.click();
   await expect(
-    page.getByRole("menuitemradio", { name: "30 days" }),
+    page.getByRole("menuitemradio", { name: "Admin" }),
   ).toBeVisible();
   await page.keyboard.press("Escape");
-
+  await expect(page.getByTestId("confirm-add-member")).toBeEnabled();
   await waitForAnimations(page);
+  await page.mouse.move(0, 0);
   await dialog.screenshot({ path: `${OUTDIR}/02-invite-dialog.png` });
 });
+
+test("admin can add members but cannot assign the admin role", async ({
+  page,
+}) => {
+  await page.getByTestId("community-invite-dialog-trigger").click();
+
+  await page.getByTestId("member-pubkey-input").fill(DIRECT_ADD_NPUB);
+  await page.getByTestId(`member-search-result-${DIRECT_ADD_HEX}`).click();
+  const memberRole = page.getByTestId("member-role");
+  await expect(memberRole).toHaveText("Member");
+  await memberRole.click();
+  await expect(page.getByRole("menuitemradio", { name: "Admin" })).toHaveCount(
+    0,
+  );
+  await page.keyboard.press("Escape");
+});
+
+test("owner can add multiple admins directly by npub from live Invites UI", async ({
+  page,
+}) => {
+  await page.getByTestId("community-invite-dialog-trigger").click();
+  await page.getByTestId("member-pubkey-input").fill(DIRECT_ADD_NPUB);
+  await page.getByTestId(`member-search-result-${DIRECT_ADD_HEX}`).click();
+  await page.getByTestId("member-pubkey-input").fill(SECOND_DIRECT_ADD_NPUB);
+  await page
+    .getByTestId(`member-search-result-${SECOND_DIRECT_ADD_HEX}`)
+    .click();
+  await page.getByTestId("member-role").click();
+  await page.getByRole("menuitemradio", { name: "Admin" }).click();
+  await page.getByTestId("confirm-add-member").click();
+
+  await expect
+    .poll(async () =>
+      page.evaluate(
+        ({ targetPubkeys, role }) =>
+          targetPubkeys.every((targetPubkey) =>
+            (window.__BUZZ_E2E_COMMAND_PAYLOADS__ ?? []).some((entry) => {
+              if (entry.command !== "plugin:websocket|send") return false;
+              const wireMessage = (
+                entry.payload as {
+                  message?: { data?: unknown };
+                }
+              )?.message?.data;
+              if (typeof wireMessage !== "string") return false;
+              const message = JSON.parse(wireMessage) as unknown[];
+              if (message[0] !== "EVENT") return false;
+              const event = message[1] as
+                | { kind?: number; tags?: string[][] }
+                | undefined;
+              return (
+                event?.kind === 9030 &&
+                event.tags?.some(
+                  (tag) => tag[0] === "p" && tag[1] === targetPubkey,
+                ) &&
+                event.tags.some((tag) => tag[0] === "role" && tag[1] === role)
+              );
+            }),
+          ),
+        {
+          targetPubkeys: [DIRECT_ADD_HEX, SECOND_DIRECT_ADD_HEX],
+          role: "admin",
+        },
+      ),
+    )
+    .toBe(true);
+});
diff --git a/desktop/tests/e2e/mentions.spec.ts b/desktop/tests/e2e/mentions.spec.ts
index 694b5abef5..5e31235a18 100644
--- a/desktop/tests/e2e/mentions.spec.ts
+++ b/desktop/tests/e2e/mentions.spec.ts
@@ -157,7 +157,7 @@ async function waitForTimelineSettled(page: import("@playwright/test").Page) {
   await expect(page.locator("[data-render-pending]")).toHaveCount(0);
 }
 
-async function expectAgentProfileMessageOnly(
+async function expectOwnedAgentProfileActions(
   profilePopover: import("@playwright/test").Locator,
   pubkey: string,
 ) {
@@ -169,7 +169,7 @@ async function expectAgentProfileMessageOnly(
   ).toHaveCount(0);
   await expect(
     profilePopover.getByTestId(`user-profile-popover-huddle-${pubkey}`),
-  ).toHaveCount(0);
+  ).toBeVisible();
 }
 
 async function expectAgentProfileActionsHidden(
@@ -1114,7 +1114,7 @@ test("system add rows use plain names while remove rows retain agent mention sty
   const addedRow = page
     .getByTestId("system-message-row")
     .filter({ hasText: "portal" })
-    .filter({ hasText: "was added by" });
+    .filter({ hasText: "added by" });
   const removedRow = page
     .getByTestId("system-message-row")
     .filter({ hasText: "removed portal from the channel" });
@@ -1178,7 +1178,7 @@ test("groups member additions and joins with hidden names in the standard toolti
 
   const groupedRow = page
     .getByTestId("system-message-row")
-    .filter({ hasText: "was added by Alice Chen" });
+    .filter({ hasText: "added by Alice Chen" });
   for (const visibleName of [
     "Erica Chapman",
     "Peter Griffin",
@@ -1188,9 +1188,9 @@ test("groups member additions and joins with hidden names in the standard toolti
     await expect(groupedRow).toContainText(visibleName);
   }
   await expect(
-    groupedRow.locator("p").filter({ hasText: "was added by" }),
+    groupedRow.locator("p").filter({ hasText: "added by" }),
   ).toContainText(
-    "was added by Alice Chen, along with Peter Griffin, Marcia Thomas, Jordan Lee, and 2 others",
+    "added by Alice Chen, along with Peter Griffin, Marcia Thomas, Jordan Lee, and 2 others",
   );
   await expect(groupedRow.locator("[data-mention]")).toHaveCount(0);
 
@@ -1200,6 +1200,11 @@ test("groups member additions and joins with hidden names in the standard toolti
   await expect(visibleName).toHaveCSS("text-decoration-line", "underline");
 
   const othersTrigger = groupedRow.getByRole("button", { name: "2 others" });
+  // Park the pointer off-target first: the previous hover leaves the mouse at a
+  // fixed viewport point, and any later reflow (new rows, scroll-to-bottom, a
+  // different text wrap) can slide this button under it. Without this the
+  // assertion measures where the mouse happens to be, not the resting style.
+  await page.mouse.move(0, 0);
   await expect(othersTrigger).toHaveCSS("text-decoration-line", "none");
   await othersTrigger.hover();
   await expect(othersTrigger).toHaveCSS("text-decoration-line", "underline");
@@ -1242,13 +1247,20 @@ test("groups member additions and joins with hidden names in the standard toolti
   const joinedOthersTrigger = joinedRow.getByRole("button", {
     name: "2 others",
   });
+  await page.mouse.move(0, 0);
   await expect(joinedOthersTrigger).toHaveCSS("text-decoration-line", "none");
   await joinedOthersTrigger.hover();
-  await expect(page.getByRole("tooltip")).toContainText("Olivia Park");
-  await expect(page.getByRole("tooltip")).toContainText("Sam Rivera");
+  // Scope to the *open* tooltip: the first row's tooltip stays mounted with
+  // data-state="closed" while it animates out, so a bare role=tooltip lookup
+  // matches two elements and trips strict mode.
+  const joinedTooltip = page.locator(
+    '[role="tooltip"]:not([data-state="closed"])',
+  );
+  await expect(joinedTooltip).toContainText("Olivia Park");
+  await expect(joinedTooltip).toContainText("Sam Rivera");
 });
 
-test("system agent profile only exposes message action", async ({ page }) => {
+test("system agent profile exposes owned agent actions", async ({ page }) => {
   await page.goto("/");
   await page.getByTestId("channel-general").click();
   await expect(page.getByTestId("chat-title")).toHaveText("general");
@@ -1277,7 +1289,7 @@ test("system agent profile only exposes message action", async ({ page }) => {
   const joinedRow = page
     .getByTestId("system-message-row")
     .filter({ hasText: "mira" })
-    .filter({ hasText: "was added by" });
+    .filter({ hasText: "added by" });
   const agentName = joinedRow.getByText("mira", { exact: true });
   await expect(agentName).toHaveText("mira");
   await expect(agentName).not.toHaveAttribute("data-mention");
@@ -1287,13 +1299,13 @@ test("system agent profile only exposes message action", async ({ page }) => {
     '[data-testid="user-profile-popover"][data-state="open"]',
   );
   await expect(profilePopover).toBeVisible();
-  await expectAgentProfileMessageOnly(
+  await expectOwnedAgentProfileActions(
     profilePopover,
     PROFILE_ONLY_AGENT_PUBKEY,
   );
 });
 
-test("system agent avatar only exposes message action", async ({ page }) => {
+test("system agent avatar exposes owned agent actions", async ({ page }) => {
   await page.goto("/");
   await page.getByTestId("channel-random").click();
   await expect(page.getByTestId("chat-title")).toHaveText("random");
@@ -1328,7 +1340,7 @@ test("system agent avatar only exposes message action", async ({ page }) => {
     '[data-testid="user-profile-popover"][data-state="open"]',
   );
   await expect(profilePopover).toBeVisible();
-  await expectAgentProfileMessageOnly(
+  await expectOwnedAgentProfileActions(
     profilePopover,
     PROFILE_ONLY_AGENT_PUBKEY,
   );
@@ -1907,7 +1919,9 @@ test("human profile popover does not show an owner", async ({ page }) => {
   ).toHaveCount(0);
 });
 
-test("owned bot profile only exposes message action", async ({ page }) => {
+test("owned bot profile exposes message and huddle actions", async ({
+  page,
+}) => {
   await installMockBridge(page, {
     managedAgents: [
       {
@@ -1931,13 +1945,29 @@ test("owned bot profile only exposes message action", async ({ page }) => {
     '[data-testid="user-profile-popover"][data-state="open"]',
   );
   await expect(profilePopover).toBeVisible();
-  await expectAgentProfileMessageOnly(
+  await expectOwnedAgentProfileActions(
     profilePopover,
     TEST_IDENTITIES.charlie.pubkey,
   );
+
+  await profilePopover
+    .getByTestId(
+      `user-profile-popover-huddle-${TEST_IDENTITIES.charlie.pubkey}`,
+    )
+    .click();
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).find(
+            (entry) => entry.command === "start_huddle",
+          )?.payload,
+      ),
+    )
+    .toMatchObject({ memberPubkeys: [TEST_IDENTITIES.charlie.pubkey] });
 });
 
-test("owned agent mention profile only exposes message action", async ({
+test("owned agent mention profile exposes message and huddle actions", async ({
   page,
 }) => {
   await installMockBridge(page, {
@@ -1970,7 +2000,7 @@ test("owned agent mention profile only exposes message action", async ({
     '[data-testid="user-profile-popover"][data-state="open"]',
   );
   await expect(profilePopover).toBeVisible();
-  await expectAgentProfileMessageOnly(
+  await expectOwnedAgentProfileActions(
     profilePopover,
     TEST_IDENTITIES.charlie.pubkey,
   );
diff --git a/desktop/tests/e2e/mesh-compute.spec.ts b/desktop/tests/e2e/mesh-compute.spec.ts
index 7c360368a2..b2e8fc28a9 100644
--- a/desktop/tests/e2e/mesh-compute.spec.ts
+++ b/desktop/tests/e2e/mesh-compute.spec.ts
@@ -15,7 +15,7 @@ type E2eWindow = Window & {
   }) => void;
 };
 
-test("Share compute has a clear empty state and starts and stops sharing", async ({
+test("Share compute selects the curated default and starts and stops sharing", async ({
   page,
 }) => {
   await installMockBridge(page);
@@ -30,22 +30,32 @@ test("Share compute has a clear empty state and starts and stops sharing", async
   await expect(card).toContainText(
     "Choose a suggested model below, or enter a model reference or local file",
   );
-  await expect(toggle).toBeDisabled();
-
-  await model.fill("hf://demo/SmolLM2-135M-Instruct-GGUF:Q4_K_M");
+  await expect(model).toHaveValue("Gemma-4-E4B-it-Q4_K_M");
+  await expect(toggle).toBeEnabled();
   await expect(card).toContainText(
     "Buzz downloads remote models when sharing starts",
   );
-  await expect(toggle).toBeEnabled();
 
   await toggle.click();
   await expect(toggle).toBeChecked();
-  await expect(card).toContainText("Sharing SmolLM2 135M with relay members");
+  await expect(card).toContainText("Sharing Gemma 4 E4B with relay members");
   await expect
     .poll(() =>
       page.evaluate(() => (window as E2eWindow).__BUZZ_E2E_COMMANDS__ ?? []),
     )
     .toContain("mesh_start_node");
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () => (window as E2eWindow).__BUZZ_E2E_COMMAND_PAYLOADS__ ?? [],
+      ),
+    )
+    .toContainEqual({
+      command: "mesh_start_node",
+      payload: {
+        request: { mode: "serve", modelId: "Gemma-4-E4B-it-Q4_K_M" },
+      },
+    });
 
   await toggle.click();
   await expect(toggle).not.toBeChecked();
diff --git a/desktop/tests/e2e/message-feedback-snapshots.spec.ts b/desktop/tests/e2e/message-feedback-snapshots.spec.ts
new file mode 100644
index 0000000000..18776d7f25
--- /dev/null
+++ b/desktop/tests/e2e/message-feedback-snapshots.spec.ts
@@ -0,0 +1,114 @@
+import { expect, test } from "@playwright/test";
+
+import { waitForAnimations } from "../helpers/animations";
+import { installMockBridge } from "../helpers/bridge";
+
+const SHOTS = "test-results/message-feedback";
+
+async function waitForMockLiveSubscription(
+  page: import("@playwright/test").Page,
+  channelName: string,
+) {
+  await expect
+    .poll(async () => {
+      return page.evaluate(
+        ({ ch }) =>
+          (
+            window as Window & {
+              __BUZZ_E2E_HAS_MOCK_LIVE_SUBSCRIPTION__?: (input: {
+                channelName: string;
+              }) => boolean;
+            }
+          ).__BUZZ_E2E_HAS_MOCK_LIVE_SUBSCRIPTION__?.({ channelName: ch }) ??
+          false,
+        { ch: channelName },
+      );
+    })
+    .toBe(true);
+}
+
+test("pending continuation keeps Sending next to its timestamp", async ({
+  page,
+}) => {
+  await installMockBridge(page);
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+  await waitForMockLiveSubscription(page, "general");
+
+  const sentMessage = `Message before pending state ${Date.now()}`;
+  const pendingMessage = `Pending message status ${Date.now()}`;
+  const createdAt = Math.floor(Date.now() / 1_000);
+  await page.evaluate(
+    ({ firstMessage, secondMessage, timestamp }) => {
+      const emit = (
+        window as Window & {
+          __BUZZ_E2E_EMIT_MOCK_MESSAGE__?: (input: {
+            channelName: string;
+            content: string;
+            createdAt: number;
+            pending?: boolean;
+          }) => unknown;
+        }
+      ).__BUZZ_E2E_EMIT_MOCK_MESSAGE__;
+      emit?.({
+        channelName: "general",
+        content: firstMessage,
+        createdAt: timestamp - 1,
+      });
+      emit?.({
+        channelName: "general",
+        content: secondMessage,
+        createdAt: timestamp,
+        pending: true,
+      });
+    },
+    {
+      firstMessage: sentMessage,
+      secondMessage: pendingMessage,
+      timestamp: createdAt,
+    },
+  );
+
+  const pendingRow = page
+    .getByTestId("message-row")
+    .filter({ hasText: pendingMessage });
+  const status = pendingRow.getByTestId("message-send-status");
+  await expect(status).toHaveText("Sending…");
+  await expect(pendingRow.getByTestId("message-author")).toHaveCount(1);
+
+  const timestamp = status.locator("xpath=../p[1]");
+  const [timestampBox, statusBox] = await Promise.all([
+    timestamp.boundingBox(),
+    status.boundingBox(),
+  ]);
+  expect(timestampBox).not.toBeNull();
+  expect(statusBox).not.toBeNull();
+  if (!timestampBox || !statusBox) {
+    throw new Error("Pending message metadata is missing its inline layout.");
+  }
+  expect(statusBox.x).toBeGreaterThan(timestampBox.x);
+  expect(Math.abs(statusBox.y - timestampBox.y)).toBeLessThanOrEqual(1);
+
+  await waitForAnimations(page);
+  await pendingRow.screenshot({ path: `${SHOTS}/pending-message-inline.png` });
+});
+
+test("profile hover uses the channel hover surface", async ({ page }) => {
+  await installMockBridge(page);
+  await page.goto("/");
+
+  const profile = page.getByTestId("sidebar-profile-card");
+  const channel = page.getByTestId("channel-random");
+  await channel.hover();
+  const channelHoverColor = await channel.evaluate(
+    (element) => getComputedStyle(element).backgroundColor,
+  );
+  await profile.hover();
+  await expect(profile).toHaveCSS("background-color", channelHoverColor);
+
+  await waitForAnimations(page);
+  await page
+    .getByTestId("app-sidebar")
+    .screenshot({ path: `${SHOTS}/profile-hover.png` });
+});
diff --git a/desktop/tests/e2e/messaging.spec.ts b/desktop/tests/e2e/messaging.spec.ts
index 2487dbbf9c..c6f5aefb9b 100644
--- a/desktop/tests/e2e/messaging.spec.ts
+++ b/desktop/tests/e2e/messaging.spec.ts
@@ -734,7 +734,9 @@ test("opens a single-level thread panel with inline expansion", async ({
         return body.scrollHeight - body.clientHeight;
       });
     })
-    .toBeGreaterThanOrEqual(160);
+    // Compact continuation rows intentionally reduce the available overflow;
+    // this test only needs enough space to prove the thread body scrolls.
+    .toBeGreaterThan(0);
 
   await expect(
     timeline.getByTestId("message-row").filter({ hasText: firstReply }),
@@ -916,10 +918,10 @@ test("opens a single-level thread panel with inline expansion", async ({
     `[data-testid="message-thread-summary"][data-thread-head-id="${firstReplyId}"]`,
   );
   await expect(firstReplySummaryRow).toHaveCount(0);
-  const firstReplyBranchRail = threadReplies.locator(
-    `[data-testid="thread-collapse-rail"][data-thread-head-id="${firstReplyId}"]`,
+  const firstReplyBranchGuide = threadReplies.locator(
+    `[data-testid="thread-collapse-guide"][data-thread-head-id="${firstReplyId}"]`,
   );
-  await expect(firstReplyBranchRail).toHaveCount(1);
+  await expect(firstReplyBranchGuide).not.toHaveCount(0);
 
   await expect(rootSummaryRow).toContainText("18 replies");
   await expect(
@@ -939,7 +941,7 @@ test("opens a single-level thread panel with inline expansion", async ({
 
   await expectThreadReplyUnobscured(nestedReplyRow);
 
-  await firstReplyBranchRail.click();
+  await firstReplyBranchGuide.first().click();
   await expect(firstReplySummaryRow).toHaveCount(1);
   await expect(firstReplySummaryRow).toContainText("2 replies");
   await expect(
diff --git a/desktop/tests/e2e/navigation.spec.ts b/desktop/tests/e2e/navigation.spec.ts
index f7a96cd568..18db55a50a 100644
--- a/desktop/tests/e2e/navigation.spec.ts
+++ b/desktop/tests/e2e/navigation.spec.ts
@@ -48,6 +48,37 @@ test("global back and forward move across channel routes", async ({ page }) => {
   await expect(page.getByTestId("chat-title")).toHaveText("random");
 });
 
+test("back/forward keyboard chords work while the composer has focus", async ({
+  page,
+}) => {
+  const backChord = process.platform === "darwin" ? "Meta+[" : "Alt+ArrowLeft";
+  const forwardChord =
+    process.platform === "darwin" ? "Meta+]" : "Alt+ArrowRight";
+
+  await page.goto("/");
+
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+
+  await page.getByTestId("channel-random").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("random");
+
+  // The composer autofocuses on channel switch; make the regression
+  // condition explicit by clicking into it. The chords must still fire
+  // from inside the contenteditable (#3775).
+  await page.getByTestId("message-input").click();
+  await expect(page.getByTestId("message-input")).toBeFocused();
+
+  await page.keyboard.press(backChord);
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+
+  await page.keyboard.press(forwardChord);
+  await expect(page.getByTestId("chat-title")).toHaveText("random");
+
+  // preventDefault kept the chord out of the editor — no stray characters.
+  await expect(page.getByTestId("message-input")).toHaveText("");
+});
+
 // FIXME: the forum post "Back to posts" header renders under the fixed top
 // chrome drag region, which intercepts the click. Pre-existing breakage —
 // this spec file was never registered in playwright.config.ts until now.
diff --git a/desktop/tests/e2e/onboarding-backup.spec.ts b/desktop/tests/e2e/onboarding-backup.spec.ts
index 9b49f8bf18..df3528c8bd 100644
--- a/desktop/tests/e2e/onboarding-backup.spec.ts
+++ b/desktop/tests/e2e/onboarding-backup.spec.ts
@@ -1,6 +1,11 @@
 import { expect, test } from "@playwright/test";
 import { installMockBridge } from "../helpers/bridge";
 import { waitForAnimations } from "../helpers/animations";
+import {
+  dropFileOnTestId,
+  endWindowFileDrag,
+  startWindowFileDrag,
+} from "../helpers/fileDrag";
 
 async function enterMachineBackup(page: import("@playwright/test").Page) {
   await installMockBridge(page, undefined, {
@@ -11,70 +16,312 @@ async function enterMachineBackup(page: import("@playwright/test").Page) {
   await page.getByRole("button", { name: "Create a new identity key" }).click();
 }
 
+async function openBackupOptions(page: import("@playwright/test").Page) {
+  await expect(page.getByTestId("backup-intro-logo")).toHaveCount(0);
+  await page.getByTestId("backup-options-link").click();
+  await expect(
+    page.getByTestId("onboarding-page-backup-options"),
+  ).toBeVisible();
+}
+
+async function openPasswordBackup(page: import("@playwright/test").Page) {
+  await openBackupOptions(page);
+  await page.getByTestId("backup-option-password").click();
+  await expect(page.getByTestId("onboarding-page-download")).toBeVisible();
+}
+
+async function invokedCommands(page: import("@playwright/test").Page) {
+  return page.evaluate(
+    () =>
+      (window as Window & { __BUZZ_E2E_COMMANDS__?: string[] })
+        .__BUZZ_E2E_COMMANDS__ ?? [],
+  );
+}
+
 const SHOTS = "test-results/screenshots-onboarding";
 
+// Mirrors the mock bridge's MOCK_NCRYPTSEC (e2eBridge.ts): the blob the
+// mocked `create_ncryptsec_backup` returns, i.e. the "downloaded file"
+// contents the test-your-backup dropzone expects.
+const MOCK_NCRYPTSEC =
+  "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+
 test("backup step appears on fresh-key path after profile submit", async ({
   page,
 }) => {
   await enterMachineBackup(page);
 
   await expect(page.getByTestId("onboarding-page-backup")).toBeVisible();
+
+  // Perceived-loading intro: the animated logo and "Creating" title show
+  // first, then the finished state replaces them after the hold.
+  await expect(
+    page.getByRole("heading", { name: "Creating your identity key" }),
+  ).toBeVisible();
+  await expect(page.getByTestId("backup-intro-logo")).toBeVisible();
+
   await expect(
     page.getByRole("heading", {
       name: "Your unique identity key has been created",
     }),
   ).toBeVisible();
+  await expect(page.getByTestId("backup-intro-logo")).toHaveCount(0);
 });
 
-test("backup step shows masked nsec from mock bridge", async ({ page }) => {
+// ---------------------------------------------------------------------------
+// Key-created view: masked key with reveal toggle. Backup options open the
+// dark security view; the raw key is fetched only on explicit reveal/copy.
+// ---------------------------------------------------------------------------
+
+test("key view reveals explicitly; options copy explicitly", async ({
+  page,
+}) => {
+  await page.context().grantPermissions(["clipboard-read", "clipboard-write"]);
   await enterMachineBackup(page);
 
+  await expect(page.getByTestId("backup-intro-logo")).toHaveCount(0);
+
+  // Masked by default: decorative mask only, no key material in the DOM.
+  const key = page.getByTestId("backup-key-value");
+  await expect(key).toBeVisible();
+  await expect(key).toHaveClass(/blur/);
+  await expect(key).not.toContainText("nsec1");
+  expect(await invokedCommands(page)).not.toContain("get_nsec");
+
+  // Reveal fetches the key; box must not reflow (same-length monospace mask).
+  await page.getByTestId("backup-key-reveal-toggle").click();
+  await expect(key).toContainText("nsec1mock");
+  await expect(key).toHaveClass(/select-text/);
+
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOTS}/02-backup-chooser-revealed.png` });
+
+  // Hide again.
+  await page.getByTestId("backup-key-reveal-toggle").click();
+  await expect(key).not.toContainText("nsec1");
+
+  // Copy is available only after opening the dark backup-options view.
+  await page.getByTestId("backup-options-link").click();
+  await expect(
+    page.getByTestId("onboarding-page-backup-options"),
+  ).toBeVisible();
+  await expect(page.getByTestId("onboarding-next")).toHaveCount(0);
+  await page.getByTestId("backup-copy-key").click();
+  await expect
+    .poll(async () => invokedCommands(page))
+    .toContain("copy_text_to_clipboard");
+  expect(await invokedCommands(page)).toContain("get_nsec");
+
+  // Return restores the yellow key-created view; its Next skips backup and
+  // continues directly to setup.
+  await page.getByTestId("backup-return-to-onboarding").click();
   await expect(page.getByTestId("onboarding-page-backup")).toBeVisible();
-  const nsecDisplay = page.getByTestId("nsec-value");
-  await expect(nsecDisplay).toBeVisible();
+  await expect(page.getByTestId("onboarding-next")).toBeEnabled();
+  await page.getByTestId("onboarding-next").click();
+  await expect(page.getByTestId("onboarding-page-2")).toBeVisible();
+});
+
+// ---------------------------------------------------------------------------
+// Encrypted download path ("Backup your key" step): password → encrypt
+// locally → native save → saved confirmation. The raw key must never be
+// fetched on this path.
+// ---------------------------------------------------------------------------
+
+test("download happy path: generated password, encrypt, native save, Next", async ({
+  page,
+}) => {
+  await enterMachineBackup(page);
+
+  // Password backup opens from the dark options state without adding an
+  // onboarding progress step.
+  await openPasswordBackup(page);
 
-  // Should start masked (blurred) — reveal button exists and eye icon visible.
-  const revealBtn = page.getByTestId("nsec-reveal-toggle");
-  await expect(revealBtn).toBeVisible();
-  await expect(nsecDisplay).toHaveCSS("filter", /blur/);
+  // The password field starts empty; the create button sits in the footer's
+  // primary slot and stays disabled until a valid password exists.
+  const input = page.getByTestId("backup-passphrase-input");
+  await expect(input).toHaveValue("");
+  await expect(page.getByTestId("encrypted-backup-create")).toBeDisabled();
+  await expect(page.getByTestId("onboarding-next")).toHaveCount(0);
+  await expect(page.getByTestId("backup-return-to-onboarding")).toBeVisible();
+  const passwordPanel = page.getByTestId("backup-password-panel");
+  await expect(passwordPanel).toBeVisible();
+  await expect(passwordPanel).not.toHaveClass(/buzz-card-textured/);
+  await expect(passwordPanel).toHaveCSS("padding-left", "24px");
+
+  // The inset refresh icon opens the generator popover and immediately
+  // fills the field (mock default: 3 words, spaces).
+  await page.getByTestId("backup-passphrase-generate").click();
+  await expect(input).toHaveValue("mock horse battery");
+  const generatorPopover = page.getByRole("dialog");
+  await expect(generatorPopover).toBeVisible();
+  await expect(generatorPopover).not.toHaveClass(/buzz-card-textured/);
+
+  // Popover controls regenerate in place: word count (slider) and separator.
+  await page.getByTestId("backup-passphrase-words").focus();
+  await page.keyboard.press("ArrowRight");
+  await expect(input).toHaveValue("mock horse battery staple");
+  await page
+    .getByTestId("backup-passphrase-separator")
+    .selectOption({ label: "Hyphens" });
+  await expect(input).toHaveValue("mock-horse-battery-staple");
+
+  // Clicking the inset icon again re-rolls without closing the popover.
+  await page.getByTestId("backup-passphrase-generate").click();
+  await expect(page.getByTestId("backup-passphrase-separator")).toBeVisible();
 
-  // Take a screenshot of the masked state. Capture the whole viewport: the CTAs
-  // are portaled into the docked footer outside the step subtree.
   await waitForAnimations(page);
-  await page.screenshot({
-    path: `${SHOTS}/02-backup-step-masked.png`,
-  });
+  await page.screenshot({ path: `${SHOTS}/03-backup-download-passphrase.png` });
+
+  // Encryption may still be running when the user commits the download. The
+  // explicit click queues the native save without exposing the password or
+  // fetching the raw key.
+  await page.keyboard.press("Escape");
+  await expect(page.getByTestId("backup-passphrase-separator")).toHaveCount(0);
 
-  // Reveal and verify the mock nsec appears.
-  await revealBtn.click();
-  await expect(nsecDisplay).not.toHaveCSS("filter", /blur/);
-  await expect(nsecDisplay).toContainText("nsec1mock");
+  // Saving commits the encrypted payload only after this explicit action.
+  await page.getByTestId("encrypted-backup-create").click();
+
+  // Only a successful save (the mock "picks" a path) advances to the
+  // "Optionally, test your backup" flow: a select-file button for the saved file
+  // (a composer-style drop overlay takes over the card while a file drag is
+  // over the window), then the password to unlock it.
+  await expect(
+    page.getByRole("heading", { name: "Optionally, test your backup" }),
+  ).toBeVisible();
+  const dropzone = page.getByTestId("backup-test-dropzone");
+  await expect(dropzone).toBeVisible();
+  await expect(
+    page.getByRole("button", { name: "Re-download backup" }),
+  ).toBeVisible();
+
+  // The optional security subview has no onboarding Next action. Returning to
+  // the yellow key view is the single exit throughout the ceremony.
+  await expect(page.getByTestId("onboarding-next")).toHaveCount(0);
+  await expect(page.getByTestId("backup-return-to-onboarding")).toBeVisible();
 
-  // Take a screenshot of the revealed state.
   await waitForAnimations(page);
-  await page.screenshot({
-    path: `${SHOTS}/03-backup-step-revealed.png`,
+  await page.screenshot({ path: `${SHOTS}/04-backup-test-dropzone.png` });
+
+  // A wrong file is rejected with an inline error; the dropzone stays.
+  await page.getByTestId("backup-test-file-input").setInputFiles({
+    name: "notes.txt",
+    mimeType: "text/plain",
+    buffer: Buffer.from("not a key backup"),
   });
+  await expect(page.getByTestId("backup-test-error")).toBeVisible();
+
+  // A file drag over the window swaps in the drop overlay; leaving without
+  // dropping restores the select button.
+  const dropOverlay = page.getByTestId("backup-test-drop-overlay");
+  await startWindowFileDrag(page);
+  await expect(dropOverlay).toBeVisible();
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOTS}/04b-backup-test-drop-overlay.png` });
+  await endWindowFileDrag(page);
+  await expect(dropOverlay).toHaveCount(0);
+
+  // Dropping the freshly downloaded file on the overlay advances to the
+  // password check.
+  await startWindowFileDrag(page);
+  await expect(dropOverlay).toBeVisible();
+  await dropFileOnTestId(page, "backup-test-drop-overlay", MOCK_NCRYPTSEC);
+  const password = page.getByTestId("backup-test-password");
+  await expect(password).toBeVisible();
+  await expect(dropOverlay).toHaveCount(0);
+
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOTS}/05-backup-test-password.png` });
+
+  // Verification is explicit and clears every submitted attempt.
+  await password.fill("mock-horse-battery-staplX");
+  await page.getByTestId("backup-test-verify").click();
+  await expect(page.getByTestId("backup-test-error")).toBeVisible();
+  await expect(password).toHaveValue("");
+
+  await password.fill("mock horse battery staple lake orbit");
+  await page.getByTestId("backup-test-verify").click();
+  await expect(page.getByTestId("backup-test-success")).toBeVisible();
+
+  // The celebration is driven by motion's rAF loop, which
+  // `waitForAnimations` (WAAPI-only) cannot observe — hold until the badge
+  // and copy have faded in before capturing.
+  await page.waitForTimeout(1200);
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOTS}/06-backup-test-success.png` });
+
+  // The download path must never have fetched the raw key.
+  const commands = await invokedCommands(page);
+  expect(commands).not.toContain("get_nsec");
+  expect(commands).toContain("create_ncryptsec_backup");
+
+  // Completion remains inside the optional security subview. Return to the
+  // yellow key view, whose standard Next action continues onboarding.
+  await expect(page.getByTestId("onboarding-next")).toHaveCount(0);
+  await page.getByTestId("backup-return-to-onboarding").click();
+  await expect(page.getByTestId("onboarding-page-backup")).toBeVisible();
+  await expect(page.getByTestId("onboarding-next")).toBeEnabled();
+  await page.getByTestId("onboarding-next").click();
+  await expect(page.getByTestId("onboarding-page-2")).toBeVisible();
 });
 
-test("backup step Next is enabled once the key is shown", async ({ page }) => {
+test("security view returns to the yellow onboarding view", async ({
+  page,
+}) => {
   await enterMachineBackup(page);
+  await openPasswordBackup(page);
+
+  await expect(page.getByTestId("backup-passphrase-input")).toBeVisible();
+  await expect(page.getByTestId("onboarding-step-dots")).toHaveCount(0);
+  await expect(page.getByTestId("onboarding-next")).toHaveCount(0);
 
+  await page.getByTestId("backup-return-to-onboarding").click();
   await expect(page.getByTestId("onboarding-page-backup")).toBeVisible();
-  await expect(page.getByTestId("nsec-value")).toBeVisible();
-  await expect(page.getByTestId("onboarding-next")).toBeEnabled();
+  await expect(page.getByTestId("backup-key-value")).toBeVisible();
+  await expect(page.getByTestId("onboarding-next")).toBeVisible();
 });
 
-test("backup step advances to machine setup on Next click", async ({
+test("returning to onboarding resets password-backup progress", async ({
   page,
 }) => {
   await enterMachineBackup(page);
+  await openPasswordBackup(page);
 
+  const input = page.getByTestId("backup-passphrase-input");
+  await input.fill("mock-horse-battery-staple");
+  await page.getByTestId("encrypted-backup-create").click();
+  await expect(
+    page.getByRole("heading", { name: "Optionally, test your backup" }),
+  ).toBeVisible();
+
+  await page.getByTestId("backup-return-to-onboarding").click();
   await expect(page.getByTestId("onboarding-page-backup")).toBeVisible();
-  await expect(page.getByTestId("nsec-value")).toBeVisible();
-  await page.getByTestId("onboarding-next").click();
 
-  await expect(page.getByTestId("onboarding-page-2")).toBeVisible();
+  // Re-entering the security flow intentionally starts a fresh optional
+  // backup session so no password or completed state leaks across navigation.
+  await openPasswordBackup(page);
+  await expect(
+    page.getByRole("heading", { name: "Backup your key with a password" }),
+  ).toBeVisible();
+  await expect(page.getByTestId("backup-passphrase-input")).toHaveValue("");
+  await expect(page.getByTestId("encrypted-backup-create")).toBeDisabled();
+});
+
+test("typed password requires 12 characters", async ({ page }) => {
+  await enterMachineBackup(page);
+  await openPasswordBackup(page);
+
+  const create = page.getByTestId("encrypted-backup-create");
+  await expect(create).toBeDisabled(); // empty field
+
+  await page.getByTestId("backup-passphrase-input").fill("short");
+  await expect(page.getByTestId("backup-passphrase-issue")).toBeVisible();
+  await expect(create).toBeDisabled();
+
+  await page
+    .getByTestId("backup-passphrase-input")
+    .fill("a much longer passphrase");
+  await expect(page.getByTestId("backup-passphrase-issue")).toHaveCount(0);
+  await expect(create).toBeEnabled();
 });
 
 test("backup step back button returns to machine identity choice", async ({
@@ -96,10 +343,10 @@ test("backup step back button returns to machine identity choice", async ({
 });
 
 // ---------------------------------------------------------------------------
-// B4: Error path coverage
+// B4: Error path coverage (reveal/copy)
 // ---------------------------------------------------------------------------
 
-test("backup step shows error banner and retry button when get_nsec fails", async ({
+test("reveal shows inline error when get_nsec fails and Next still advances", async ({
   page,
 }) => {
   await installMockBridge(
@@ -111,20 +358,17 @@ test("backup step shows error banner and retry button when get_nsec fails", asyn
   await page.getByRole("button", { name: "Create a new identity key" }).click();
 
   await expect(page.getByTestId("onboarding-page-backup")).toBeVisible();
-  await expect(page.getByTestId("backup-load-error")).toBeVisible();
-  await expect(page.getByTestId("backup-retry")).toBeVisible();
-  // Next is blocked on error; Skip for now ghost is shown instead.
-  await expect(page.getByTestId("onboarding-next")).toBeDisabled();
-  await expect(page.getByTestId("backup-skip")).toBeVisible();
-
-  // Skip for now still advances to machine setup.
-  await page.getByTestId("backup-skip").click();
+  await page.getByTestId("backup-key-reveal-toggle").click();
+
+  await expect(page.getByTestId("backup-copy-error")).toBeVisible();
+  // Keychain failure does not trap the user: Next still skips backup and
+  // advances directly to setup.
+  await expect(page.getByTestId("onboarding-next")).toBeEnabled();
+  await page.getByTestId("onboarding-next").click();
   await expect(page.getByTestId("onboarding-page-2")).toBeVisible();
 });
 
-test("backup step retry succeeds and shows key after initial failure", async ({
-  page,
-}) => {
+test("reveal retry succeeds after initial failure", async ({ page }) => {
   // First call fails, second succeeds (sequenced via nsecErrors).
   await installMockBridge(
     page,
@@ -134,10 +378,11 @@ test("backup step retry succeeds and shows key after initial failure", async ({
   await page.goto("/");
   await page.getByRole("button", { name: "Create a new identity key" }).click();
 
-  await expect(page.getByTestId("backup-load-error")).toBeVisible();
+  await page.getByTestId("backup-key-reveal-toggle").click();
+  await expect(page.getByTestId("backup-copy-error")).toBeVisible();
 
-  // Retry — second call succeeds.
-  await page.getByTestId("backup-retry").click();
-  await expect(page.getByTestId("nsec-value")).toBeVisible();
-  await expect(page.getByTestId("backup-load-error")).not.toBeVisible();
+  // Retry — second call succeeds and clears the error.
+  await page.getByTestId("backup-key-reveal-toggle").click();
+  await expect(page.getByTestId("backup-key-value")).toContainText("nsec1mock");
+  await expect(page.getByTestId("backup-copy-error")).not.toBeVisible();
 });
diff --git a/desktop/tests/e2e/onboarding-docked-cta-screenshots.spec.ts b/desktop/tests/e2e/onboarding-docked-cta-screenshots.spec.ts
index dbb8a92a1f..efae7c3784 100644
--- a/desktop/tests/e2e/onboarding-docked-cta-screenshots.spec.ts
+++ b/desktop/tests/e2e/onboarding-docked-cta-screenshots.spec.ts
@@ -10,6 +10,8 @@ const BLANK_TYLER_IDENTITY = {
 };
 
 const SHOT_DIR = "test-results/onboarding-docked-cta";
+const NCRYPTSEC =
+  "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
 
 test.use({ viewport: { width: 1280, height: 800 } });
 
@@ -46,7 +48,21 @@ test("machine onboarding: landing, backup, setup docked CTAs", async ({
   await waitForAnimations(page);
   await page.screenshot({ path: `${SHOT_DIR}/01b-enter-key.png` });
 
-  await page.getByRole("button", { name: "Back" }).click();
+  await page.getByTestId("nostr-import-nsec-input").fill(NCRYPTSEC);
+  await expect(
+    page.getByRole("heading", { name: "Unlock your account" }),
+  ).toBeVisible();
+  await expect(page.getByTestId("backup-password-timeline")).toBeVisible();
+  await expect(page.getByTestId("restore-ncryptsec-affordance")).toBeVisible();
+  await expect(page.getByTestId("restore-unlock-icon")).toBeVisible();
+  await expect(page.getByTestId("nostr-import-passphrase")).toBeFocused();
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOT_DIR}/01c-restore-backup.png` });
+
+  // The first Back returns to key selection; the second leaves import.
+  await page.getByRole("button", { name: "Back", exact: true }).click();
+  await expect(importCard).toBeVisible();
+  await page.getByRole("button", { name: "Back", exact: true }).click();
   await expect(
     page.getByRole("button", { name: "Create a new identity key" }),
   ).toBeVisible();
@@ -59,12 +75,56 @@ test("machine onboarding: landing, backup, setup docked CTAs", async ({
   await waitForAnimations(page);
   await page.screenshot({ path: `${SHOT_DIR}/02-backup.png` });
 
+  // The key stays masked behind an explicit reveal toggle.
+  await expect(page.getByTestId("backup-key-value")).toBeVisible();
+
   // Reveal the key: box must not reflow (same-length monospace mask).
-  await page.getByTestId("nsec-reveal-toggle").click();
-  await expect(page.getByTestId("nsec-value")).toHaveClass(/select-text/);
+  await page.getByTestId("backup-key-reveal-toggle").click();
+  await expect(page.getByTestId("backup-key-value")).toHaveClass(/select-text/);
   await waitForAnimations(page);
   await page.screenshot({ path: `${SHOT_DIR}/02b-backup-revealed.png` });
 
+  // Backup options leave the yellow flow for the dark security view without
+  // adding a progress step or a generic Next action.
+  await page.getByTestId("backup-options-link").click();
+  await expect(
+    page.getByTestId("onboarding-page-backup-options"),
+  ).toBeVisible();
+  await expect(page.getByTestId("onboarding-next")).toHaveCount(0);
+  const optionPanels = page.getByTestId("backup-option-panel");
+  await expect(optionPanels).toHaveCount(3);
+  await expect(
+    page.getByTestId("backup-options").locator(".buzz-card-textured"),
+  ).toHaveCount(0);
+  await expect(optionPanels.first()).toHaveCSS("padding-left", "24px");
+  const titleTops = await optionPanels
+    .locator("span.text-lg")
+    .evaluateAll((titles) =>
+      titles.map((title) => title.getBoundingClientRect().top),
+    );
+  expect(Math.max(...titleTops) - Math.min(...titleTops)).toBeLessThan(1);
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOT_DIR}/02c-backup-options.png` });
+
+  await page.getByTestId("backup-option-password").click();
+  await expect(page.getByTestId("onboarding-page-download")).toBeVisible();
+  const passwordPanel = page.getByTestId("backup-password-panel");
+  await expect(passwordPanel).toBeVisible();
+  await expect(passwordPanel).not.toHaveClass(/buzz-card-textured/);
+  await expect(passwordPanel).toHaveCSS("padding-left", "24px");
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOT_DIR}/02d-backup-password.png` });
+
+  await page.getByTestId("backup-passphrase-generate").click();
+  const generatorPopover = page.getByRole("dialog");
+  await expect(generatorPopover).toBeVisible();
+  await expect(generatorPopover).not.toHaveClass(/buzz-card-textured/);
+  await waitForAnimations(page);
+  await page.screenshot({ path: `${SHOT_DIR}/02e-backup-generator.png` });
+  await page.keyboard.press("Escape");
+
+  await page.getByTestId("backup-return-to-onboarding").click();
+  await expect(page.getByTestId("onboarding-page-backup")).toBeVisible();
   await page.getByTestId("onboarding-next").click();
   await expect(
     page.getByRole("heading", { name: "Set up your agent harnesses" }),
@@ -115,6 +175,39 @@ test("machine key import remains usable in a short viewport", async ({
   expect(layout.scrollWidth).toBe(layout.clientWidth);
 });
 
+test("backup options keep one-column geometry on narrow windows", async ({
+  page,
+}) => {
+  await page.setViewportSize({ width: 600, height: 700 });
+  await installMockBridge(page, undefined, {
+    skipCommunitySeed: true,
+    skipOnboardingSeed: true,
+  });
+  await page.goto("/");
+  await page.getByRole("button", { name: "Create a new identity key" }).click();
+  await expect(
+    page.getByRole("heading", {
+      name: "Your unique identity key has been created",
+    }),
+  ).toBeVisible();
+  await page.getByTestId("backup-options-link").click();
+
+  const panels = page.getByTestId("backup-option-panel");
+  await expect(panels).toHaveCount(3);
+  const geometry = await panels.evaluateAll((elements) => ({
+    clientWidth: document.documentElement.clientWidth,
+    lefts: elements.map((element) => element.getBoundingClientRect().left),
+    rights: elements.map((element) => element.getBoundingClientRect().right),
+    scrollWidth: document.documentElement.scrollWidth,
+  }));
+  expect(new Set(geometry.lefts.map(Math.round)).size).toBe(1);
+  expect(geometry.lefts.every((left) => left >= 0)).toBe(true);
+  expect(geometry.rights.every((right) => right <= geometry.clientWidth)).toBe(
+    true,
+  );
+  expect(geometry.scrollWidth).toBe(geometry.clientWidth);
+});
+
 test("relay onboarding: profile and avatar docked CTAs", async ({ page }) => {
   await seedActiveIdentity(page, BLANK_TYLER_IDENTITY);
   await installMockBridge(page, undefined, { skipOnboardingSeed: true });
diff --git a/desktop/tests/e2e/onboarding.spec.ts b/desktop/tests/e2e/onboarding.spec.ts
index 0c4d630994..0c98cb411e 100644
--- a/desktop/tests/e2e/onboarding.spec.ts
+++ b/desktop/tests/e2e/onboarding.spec.ts
@@ -621,6 +621,131 @@ test("first-launch key import continues to machine setup", async ({ page }) => {
   await expect(page.getByTestId("app-loading-gate")).toHaveCount(0);
 });
 
+test("first-launch encrypted backup import asks for a passphrase and continues", async ({
+  page,
+}) => {
+  await page.emulateMedia({ reducedMotion: "reduce" });
+  await installMockBridge(page, undefined, {
+    skipCommunitySeed: true,
+    skipOnboardingSeed: true,
+  });
+  await page.goto("/");
+
+  await page.getByRole("button", { name: "Use an existing key" }).click();
+  // Spec-vector blob the mock bridge accepts with the mock passphrase.
+  const mockNcryptsec =
+    "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+  await page
+    .getByTestId("nostr-import-nsec-input")
+    .fill(mockNcryptsec.slice(0, -1));
+  await expect(
+    page.getByRole("heading", { name: "Enter your private key" }),
+  ).toBeVisible();
+  await expect(page.getByTestId("nostr-import-passphrase")).toHaveCount(0);
+
+  await page
+    .getByTestId("nostr-import-nsec-input")
+    .pressSequentially(mockNcryptsec.slice(-1));
+
+  // A complete, checksummed NIP-49 value advances immediately without
+  // submitting. The password stage updates its copy, illustration, and focus.
+  await expect(
+    page.getByRole("heading", { name: "Unlock your account" }),
+  ).toBeVisible();
+  await expect(page.getByTestId("backup-password-timeline")).toBeVisible();
+  await expect(page.getByTestId("restore-ncryptsec-affordance")).toBeVisible();
+  await expect(page.getByTestId("restore-unlock-icon")).toBeVisible();
+  await expect(page.getByTestId("nostr-import-card")).toHaveCount(0);
+  await expect(page.getByTestId("nostr-import-file-button")).toHaveCount(0);
+  await expect(page.getByTestId("nostr-import-passphrase")).toBeFocused();
+  await expect(page.getByTestId("nostr-import-submit")).toBeDisabled();
+
+  // Wrong passphrase surfaces the decrypt error and stays on the form.
+  await page.getByTestId("nostr-import-passphrase").fill("wrong passphrase");
+  await page.getByTestId("nostr-import-submit").click();
+  await expect(page.getByTestId("nostr-import-feedback")).toContainText(
+    /wrong backup password/i,
+  );
+
+  await page
+    .getByTestId("nostr-import-passphrase")
+    .fill("mock horse battery staple lake orbit");
+  await page.getByTestId("nostr-import-submit").click();
+
+  await expect(page.getByTestId("onboarding-page-2")).toBeVisible();
+  await expect(page.getByTestId("machine-onboarding-gate")).toBeVisible();
+});
+
+test("first-launch import accepts an .ncryptsec backup file", async ({
+  page,
+}) => {
+  await installMockBridge(page, undefined, {
+    skipCommunitySeed: true,
+    skipOnboardingSeed: true,
+  });
+  await page.goto("/");
+
+  await page.getByRole("button", { name: "Use an existing key" }).click();
+
+  // The spotlight variant must expose a file path: a wiped user returns with
+  // exactly the identity.ncryptsec our own save dialog produced. The accept
+  // attribute is asserted explicitly because setInputFiles bypasses it — the
+  // OS picker is what filters on it in real use.
+  await expect(page.getByTestId("nostr-import-file-button")).toBeVisible();
+  const fileInput = page.getByTestId("nostr-import-file-input");
+  await expect(fileInput).toHaveAttribute(
+    "accept",
+    ".key,.ncryptsec,text/plain",
+  );
+
+  await fileInput.setInputFiles({
+    buffer: Buffer.alloc(1_025, "x"),
+    mimeType: "text/plain",
+    name: "not-a-backup.txt",
+  });
+  await expect(page.getByTestId("nostr-import-feedback")).toContainText(
+    /too large to be a key backup/i,
+  );
+
+  // Spec-vector blob the mock bridge accepts with the mock passphrase.
+  const mockNcryptsec =
+    "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p";
+  await fileInput.setInputFiles({
+    buffer: Buffer.from(`${mockNcryptsec}\n`),
+    mimeType: "text/plain",
+    name: "identity.ncryptsec",
+  });
+
+  // File contents advance to the same focused password stage as manual input.
+  await expect(
+    page.getByRole("heading", { name: "Unlock your account" }),
+  ).toBeVisible();
+  await expect(page.getByTestId("backup-password-timeline")).toBeVisible();
+  await expect(page.getByTestId("nostr-import-passphrase")).toBeFocused();
+
+  // Back first returns to key/file selection instead of leaving import.
+  await page.getByRole("button", { name: "Back", exact: true }).click();
+  await expect(
+    page.getByRole("heading", { name: "Enter your private key" }),
+  ).toBeVisible();
+  await expect(page.getByTestId("nostr-import-card")).toBeVisible();
+  await expect(page.getByTestId("nostr-import-file-button")).toBeVisible();
+  await expect(page.getByTestId("nostr-import-nsec-input")).toHaveValue("");
+
+  await fileInput.setInputFiles({
+    buffer: Buffer.from(`${mockNcryptsec}\n`),
+    mimeType: "text/plain",
+    name: "identity.ncryptsec",
+  });
+  await page
+    .getByTestId("nostr-import-passphrase")
+    .fill("mock horse battery staple lake orbit");
+  await page.getByTestId("nostr-import-submit").click();
+
+  await expect(page.getByTestId("onboarding-page-2")).toBeVisible();
+  await expect(page.getByTestId("machine-onboarding-gate")).toBeVisible();
+});
+
 test("non-local runtime override keeps community selection without release flag", async ({
   page,
 }) => {
@@ -1280,6 +1405,66 @@ test("first-community direct join reaches profile", async ({ page }) => {
     .toEqual({ communityCount: 1, transactionMatchesOnlyCommunity: true });
 });
 
+test("community onboarding reuses an existing relay profile", async ({
+  page,
+}) => {
+  await seedActiveIdentity(page, BLANK_TYLER_IDENTITY);
+  await page.addInitScript(
+    ({ pubkey, transactionStorageKey }) => {
+      window.localStorage.setItem(
+        `buzz-machine-onboarding-complete.v2:${pubkey}`,
+        "true",
+      );
+      const timestamp = new Date().toISOString();
+      window.localStorage.setItem(
+        transactionStorageKey,
+        JSON.stringify({
+          id: "txn-existing-profile",
+          source: "add-community",
+          stage: "profile",
+          relayUrl: "wss://onboarding.communities.buzz.xyz",
+          communityName: "Onboarding",
+          communityId: "e2e-default-community",
+          createdAt: timestamp,
+          updatedAt: timestamp,
+        }),
+      );
+    },
+    {
+      pubkey: BLANK_TYLER_IDENTITY.pubkey,
+      transactionStorageKey: COMMUNITY_ONBOARDING_TRANSACTION_STORAGE_KEY,
+    },
+  );
+  await installMockBridge(
+    page,
+    { profileHasEvent: true },
+    {
+      relayWsUrl: "wss://onboarding.communities.buzz.xyz",
+      skipOnboardingSeed: true,
+    },
+  );
+  await page.goto("/");
+
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (
+            window as Window & { __BUZZ_E2E_COMMANDS__?: string[] }
+          ).__BUZZ_E2E_COMMANDS__?.filter(
+            (command) => command === "get_profile",
+          ).length ?? 0,
+      ),
+    )
+    .toBeGreaterThan(0);
+  await expect(
+    page.getByRole("heading", { name: "Meet your starter team" }),
+  ).toBeVisible();
+  await expect(
+    page.getByRole("heading", { name: "Build your profile" }),
+  ).toHaveCount(0);
+});
+
 test("first-community direct join cancel returns to request access", async ({
   page,
 }) => {
diff --git a/desktop/tests/e2e/profile-backup-settings.spec.ts b/desktop/tests/e2e/profile-backup-settings.spec.ts
new file mode 100644
index 0000000000..edd66170da
--- /dev/null
+++ b/desktop/tests/e2e/profile-backup-settings.spec.ts
@@ -0,0 +1,259 @@
+import { expect, test, type Page } from "@playwright/test";
+import { npubEncode } from "nostr-tools/nip19";
+
+import { installMockBridge } from "../helpers/bridge";
+import { openSettings } from "../helpers/settings";
+
+const CURRENT_PUBKEY = "deadbeef".repeat(8);
+const DIFFERENT_PUBKEY = "c0ffee00".repeat(8);
+const BACKUP_FILE = {
+  name: "identity.ncryptsec",
+  mimeType: "text/plain",
+  buffer: Buffer.from("ncryptsec1mockbackupmaterial"),
+};
+
+async function openIdentity(page: Page) {
+  const identity = page.getByTestId("profile-identity-card");
+  if (
+    !(await identity.evaluate(
+      (element) => element instanceof HTMLDetailsElement && element.open,
+    ))
+  ) {
+    await page.getByTestId("profile-identity-toggle").click();
+  }
+}
+
+async function openBackupSettings(
+  page: Page,
+  mock?: Parameters<typeof installMockBridge>[1],
+) {
+  await installMockBridge(page, mock);
+  await page.goto("/");
+  await openSettings(page, "profile");
+  await openIdentity(page);
+}
+
+async function openPrivateKeyMenu(page: Page) {
+  const reveal = page.getByTestId("profile-private-key-toggle");
+  if ((await reveal.textContent())?.trim() === "Reveal") {
+    await reveal.click();
+  }
+  await page.getByTestId("nsec-actions").click();
+  await expect(page.getByTestId("private-key-create-backup")).toBeVisible();
+}
+
+async function openCreateBackup(page: Page) {
+  await openPrivateKeyMenu(page);
+  await page.getByTestId("private-key-create-backup").click();
+  const dialog = page.getByTestId("encrypted-backup-dialog");
+  await expect(dialog).toBeVisible();
+  return dialog;
+}
+
+async function openTestBackup(page: Page) {
+  await openPrivateKeyMenu(page);
+  await page.getByTestId("private-key-test-backup").click();
+  const dialog = page.getByTestId("backup-test-dialog");
+  await expect(dialog).toBeVisible();
+  return dialog;
+}
+
+async function selectBackupFile(page: Page) {
+  await page.getByTestId("backup-test-file-input").setInputFiles(BACKUP_FILE);
+  await expect(page.getByTestId("backup-test-file-accepted")).toContainText(
+    BACKUP_FILE.name,
+  );
+}
+
+async function verifyBackup(page: Page, password: string) {
+  await page.getByTestId("backup-test-password").fill(password);
+  await page.getByTestId("backup-test-verify").click();
+}
+
+async function backupSaveCallCount(page: Page) {
+  return page.evaluate(
+    () =>
+      window.__BUZZ_E2E_COMMANDS__?.filter(
+        (command) => command === "save_ncryptsec_copy",
+      ).length ?? 0,
+  );
+}
+
+test("private key menu replaces the backup settings rows", async ({ page }) => {
+  await openBackupSettings(page);
+
+  await expect(page.getByTestId("profile-encrypted-backup-row")).toHaveCount(0);
+  await expect(page.getByTestId("profile-backup-test-row")).toHaveCount(0);
+
+  await openPrivateKeyMenu(page);
+  await expect(page.getByTestId("nsec-copy")).toContainText("Copy");
+  await expect(page.getByTestId("private-key-create-backup")).toHaveText(
+    "Create backup",
+  );
+  await expect(page.getByTestId("private-key-test-backup")).toHaveText(
+    "Test backup",
+  );
+
+  await page.getByTestId("nsec-copy").click();
+  await expect(page.getByText(/clipboard$/i)).toBeVisible();
+  await expect(page.getByTestId("private-key-create-backup")).toHaveCount(0);
+
+  await openPrivateKeyMenu(page);
+  await page.getByTestId("private-key-test-backup").click();
+  const testDialog = page.getByTestId("backup-test-dialog");
+  await expect(testDialog).toContainText("Test a key backup");
+  await expect(testDialog.getByText("Select your backup file")).toBeVisible();
+  await expect(testDialog).toContainText("standard NIP-49 format");
+});
+
+test("creation requires a sufficiently long password and exposes a temporary header download", async ({
+  page,
+}) => {
+  await openBackupSettings(page, {
+    backupSavePaths: [
+      "/Users/test/Downloads/identity.ncryptsec",
+      "/Users/test/Desktop/identity-copy.ncryptsec",
+    ],
+  });
+  const dialog = await openCreateBackup(page);
+
+  const password = dialog.getByTestId("backup-passphrase-input");
+  const submit = dialog.getByTestId("encrypted-backup-create");
+  await expect(password).toHaveAttribute(
+    "placeholder",
+    "Password (min 12 characters)",
+  );
+  await expect(submit).toBeDisabled();
+  await password.fill("short");
+  await expect(submit).toBeDisabled();
+
+  await password.fill("custom password");
+  await expect(submit).toBeEnabled();
+  await submit.click();
+  await expect.poll(() => backupSaveCallCount(page)).toBe(1);
+  await expect(dialog).toBeHidden();
+
+  const keyRow = page.getByTestId("profile-private-key-row");
+  const download = keyRow.getByTestId("encrypted-backup-download");
+  await expect(download).toBeVisible();
+  await expect(download).toHaveText("Download backup");
+  await expect(download).toHaveClass(/bg-primary/);
+  await expect(
+    download.getByTestId("encrypted-backup-availability-fill"),
+  ).toBeVisible();
+  await expect(keyRow.getByTestId("profile-private-key-toggle")).toBeVisible();
+
+  await download.click();
+  await expect.poll(() => backupSaveCallCount(page)).toBe(2);
+});
+
+test("encryption and native save continue after closing the dialog and settings", async ({
+  page,
+}) => {
+  await openBackupSettings(page, {
+    backupEncryptionDelayMs: 750,
+    backupSavePaths: [null],
+  });
+  const dialog = await openCreateBackup(page);
+  await dialog
+    .getByTestId("backup-passphrase-input")
+    .fill("background password");
+  await dialog.getByTestId("encrypted-backup-create").click();
+  await expect(dialog.getByTestId("encrypted-backup-progress")).toBeVisible();
+
+  await dialog.getByRole("button", { name: "Close" }).click();
+  await page.getByTestId("settings-back-to-app").click();
+  await expect(page.getByTestId("settings-back-to-app")).toHaveCount(0);
+  await expect(
+    page.getByText("Preparing backup…", { exact: true }),
+  ).toBeVisible();
+
+  await expect.poll(() => backupSaveCallCount(page)).toBe(1);
+  const readyToast = page.getByText("Backup ready to download", {
+    exact: true,
+  });
+  await expect(readyToast).toBeVisible();
+  await expect(
+    page.getByText("Your backup will be available to download for 5 minutes.", {
+      exact: true,
+    }),
+  ).toBeVisible();
+
+  await page.getByRole("button", { name: "Open settings" }).click();
+  await expect(page.getByTestId("settings-back-to-app")).toBeVisible();
+  await openIdentity(page);
+  await expect(page.getByTestId("encrypted-backup-download")).toBeVisible();
+});
+
+test("the temporary download expires after five minutes", async ({ page }) => {
+  await page.clock.install({ time: new Date("2026-07-29T12:00:00Z") });
+  await openBackupSettings(page);
+  const dialog = await openCreateBackup(page);
+  await dialog.getByTestId("backup-passphrase-input").fill("expiring password");
+  await dialog.getByTestId("encrypted-backup-create").click();
+  await page.clock.fastForward(1);
+
+  await expect.poll(() => backupSaveCallCount(page)).toBe(1);
+  const download = page.getByTestId("encrypted-backup-download");
+  await expect(download).toHaveText("Download backup");
+  await expect(
+    download.getByTestId("encrypted-backup-availability-fill"),
+  ).toBeVisible();
+  await page.clock.fastForward(5 * 60 * 1000 + 1);
+  await expect(page.getByTestId("encrypted-backup-download")).toHaveCount(0);
+});
+
+test("wrong backup password permits a successful retry in the test modal", async ({
+  page,
+}) => {
+  await openBackupSettings(page, {
+    backupVerificationErrors: ["Wrong password.", null],
+  });
+  const dialog = await openTestBackup(page);
+  await selectBackupFile(page);
+
+  await verifyBackup(page, "wrong password");
+  await expect(dialog.getByTestId("backup-test-error")).toHaveText(
+    "Wrong password.",
+  );
+  await expect(dialog.getByTestId("backup-test-password")).toHaveValue("");
+  await expect(dialog.getByTestId("backup-test-verify")).toBeDisabled();
+
+  await verifyBackup(page, "correct password");
+  await expect(dialog.getByTestId("backup-test-success")).toContainText(
+    "It restores your current Buzz identity.",
+  );
+});
+
+for (const identity of [
+  {
+    label: "current",
+    pubkey: CURRENT_PUBKEY,
+    message: "It restores your current Buzz identity.",
+  },
+  {
+    label: "different",
+    pubkey: DIFFERENT_PUBKEY,
+    message: "It restores a different identity than the one signed in here.",
+  },
+]) {
+  test(`successful modal verification identifies the ${identity.label} identity using only its npub`, async ({
+    page,
+  }) => {
+    await openBackupSettings(page, {
+      backupVerificationPubkeys: [identity.pubkey],
+    });
+    const dialog = await openTestBackup(page);
+    await selectBackupFile(page);
+    await verifyBackup(page, "one-time password");
+
+    const success = dialog.getByTestId("backup-test-success");
+    await expect(success).toContainText(identity.message);
+    await expect(success.getByTestId("backup-test-npub")).toContainText(
+      npubEncode(identity.pubkey),
+    );
+    await expect(success).not.toContainText(identity.pubkey);
+    await expect(success).not.toContainText("one-time password");
+    await expect(success).not.toContainText(BACKUP_FILE.buffer.toString());
+  });
+}
diff --git a/desktop/tests/e2e/profile.spec.ts b/desktop/tests/e2e/profile.spec.ts
index 596f9b0d40..3b71ff9dd8 100644
--- a/desktop/tests/e2e/profile.spec.ts
+++ b/desktop/tests/e2e/profile.spec.ts
@@ -1021,7 +1021,7 @@ test("declared owner sees runtime tab for a remote relay agent", async ({
     "Goose",
   );
   await expect(panel.getByTestId("user-profile-respond-to")).toContainText(
-    "anyone",
+    "Anyone",
   );
 
   // Declared ownership grants read visibility only; local-management write UI
diff --git a/desktop/tests/e2e/project-pr-review.spec.ts b/desktop/tests/e2e/project-pr-review.spec.ts
index 9e74846642..cae9a08481 100644
--- a/desktop/tests/e2e/project-pr-review.spec.ts
+++ b/desktop/tests/e2e/project-pr-review.spec.ts
@@ -910,6 +910,114 @@ test("project overview reports aggregate work-item failures", async ({
   );
 });
 
+test("project overview does not paint a background behind its cards", async ({
+  page,
+}) => {
+  await enableProjectsFeature(page);
+  await installMockBridge(page);
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("open-projects-view").click();
+
+  await expect(page.getByTestId("projects-overview-panel")).toHaveCSS(
+    "background-color",
+    "rgba(0, 0, 0, 0)",
+  );
+
+  const stats = page.getByTestId("projects-overview-stat");
+  await expect(stats).toHaveCount(4);
+  for (let index = 0; index < 4; index += 1) {
+    await expect(stats.nth(index)).toHaveCSS(
+      "background-color",
+      "rgba(0, 0, 0, 0)",
+    );
+    await expect(stats.nth(index)).toHaveCSS("border-style", "solid");
+  }
+
+  const activityCards = page.getByTestId("projects-activity-card");
+  await expect(activityCards.first()).toBeVisible();
+  const activityCardCount = await activityCards.count();
+  for (let index = 0; index < activityCardCount; index += 1) {
+    await expect(activityCards.nth(index)).toHaveCSS(
+      "background-color",
+      "rgba(0, 0, 0, 0)",
+    );
+    await expect(activityCards.nth(index)).toHaveCSS("border-style", "solid");
+  }
+});
+
+test("project subsections do not paint backgrounds behind list or grid items", async ({
+  page,
+}) => {
+  await enableProjectsFeature(page);
+  await installMockBridge(page);
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("open-projects-view").click();
+
+  for (const section of ["Repositories", "Pull Requests", "Issues"]) {
+    await page.getByRole("button", { name: section, exact: true }).click();
+    await page.getByRole("button", { name: "List layout" }).click();
+
+    const listContainer = page.getByTestId("projects-list-container");
+    await expect(listContainer).toBeVisible();
+    await expect(listContainer).toHaveCSS(
+      "background-color",
+      "rgba(0, 0, 0, 0)",
+    );
+    await expect(listContainer).toHaveCSS("border-style", "solid");
+
+    await page.getByRole("button", { name: "Grid layout" }).click();
+    const gridCards = page.locator("[data-projects-grid-card]");
+    await expect(gridCards.first()).toBeVisible();
+    const gridCardCount = await gridCards.count();
+    for (let index = 0; index < gridCardCount; index += 1) {
+      await expect(gridCards.nth(index)).toHaveCSS(
+        "background-color",
+        "rgba(0, 0, 0, 0)",
+      );
+      await expect(gridCards.nth(index)).toHaveCSS("border-style", "solid");
+    }
+  }
+});
+
+test("project detail content areas do not paint background fills", async ({
+  page,
+}) => {
+  await enableProjectsFeature(page);
+  await installMockBridge(page);
+  await openBuzzProject(page);
+
+  const expectVisiblePanelsToBeTransparent = async () => {
+    const panels = page.locator("[data-project-detail-panel]:visible");
+    await expect(panels.first()).toBeVisible();
+    const panelCount = await panels.count();
+    for (let index = 0; index < panelCount; index += 1) {
+      await expect(panels.nth(index)).toHaveCSS(
+        "background-color",
+        "rgba(0, 0, 0, 0)",
+      );
+      await expect(panels.nth(index)).toHaveCSS("border-style", "solid");
+    }
+  };
+
+  for (const tab of [
+    "Overview",
+    "Files",
+    "Commits",
+    "Issues",
+    "Pull Request",
+    "Contributors",
+  ]) {
+    await page.getByRole("tab", { name: tab, exact: true }).click();
+    await expectVisiblePanelsToBeTransparent();
+  }
+
+  await page.getByRole("tab", { name: "Pull Request", exact: true }).click();
+  const pullRequest = page.getByTestId("project-pull-request-row").first();
+  await expect(pullRequest).toBeVisible();
+  await pullRequest.getByRole("button", { name: /^#/ }).click();
+  await expectVisiblePanelsToBeTransparent();
+});
+
 test("project without a checkout offers fetch feedback and dropdown cloning", async ({
   page,
 }) => {
diff --git a/desktop/tests/e2e/relay-reconnect.spec.ts b/desktop/tests/e2e/relay-reconnect.spec.ts
index 6240cca0ba..6606d5f04d 100644
--- a/desktop/tests/e2e/relay-reconnect.spec.ts
+++ b/desktop/tests/e2e/relay-reconnect.spec.ts
@@ -49,6 +49,44 @@ async function restartMockWebsockets(page: import("@playwright/test").Page) {
   expect(restarted).toBeGreaterThan(0);
 }
 
+async function setMockWebsocketUnavailable(
+  page: import("@playwright/test").Page,
+  unavailable: boolean,
+) {
+  await page.evaluate((value) => {
+    const setUnavailable = window.__BUZZ_E2E_SET_MOCK_WEBSOCKET_UNAVAILABLE__;
+    if (!setUnavailable) {
+      throw new Error("E2E websocket availability seam is not installed.");
+    }
+    setUnavailable(value);
+  }, unavailable);
+}
+
+async function activateRelayRateLimit(
+  page: import("@playwright/test").Page,
+  seconds: number,
+) {
+  await page.evaluate((duration) => {
+    const activate = window.__BUZZ_E2E_ACTIVATE_RELAY_RATE_LIMIT__;
+    if (!activate) {
+      throw new Error("E2E relay rate-limit seam is not installed.");
+    }
+    activate(duration);
+  }, seconds);
+}
+
+async function getMockWebsocketConnectAttempts(
+  page: import("@playwright/test").Page,
+) {
+  return page.evaluate(() => {
+    const getAttempts = window.__BUZZ_E2E_GET_WEBSOCKET_CONNECT_ATTEMPTS__;
+    if (!getAttempts) {
+      throw new Error("E2E websocket attempt seam is not installed.");
+    }
+    return getAttempts();
+  });
+}
+
 async function emitMockMessages(
   page: import("@playwright/test").Page,
   messages: Array<{ content: string; createdAt: number }>,
@@ -121,6 +159,77 @@ test("failed initial relay dial retries automatically", async ({ page }) => {
   await expect(page.getByTestId("channel-general")).toBeVisible();
 });
 
+test("routine traffic cannot bypass outage backoff and recovery stays automatic", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await expect(page.getByTestId("channel-general")).toBeVisible();
+
+  await setMockWebsocketUnavailable(page, true);
+  await disconnectMockWebsockets(page);
+
+  // Exercise the production query path throughout the outage. Before the
+  // coordinator fix, each rejected query called ensureConnected(), cancelled
+  // the scheduled timer, and dialed immediately. The fixed session keeps these
+  // callers behind its single jittered exponential-backoff attempt.
+  await page.evaluate(async () => {
+    const deadline = Date.now() + 4_200;
+    while (Date.now() < deadline) {
+      await window.__BUZZ_E2E_QUERY_CLIENT__?.invalidateQueries({
+        queryKey: ["channels"],
+      });
+      await new Promise((resolve) => window.setTimeout(resolve, 100));
+    }
+  });
+
+  const attempts = await getMockWebsocketConnectAttempts(page);
+  expect(attempts.length).toBeGreaterThanOrEqual(2);
+  expect(attempts.length).toBeLessThanOrEqual(3);
+  for (let index = 1; index < attempts.length; index += 1) {
+    expect(attempts[index] - attempts[index - 1]).toBeGreaterThanOrEqual(700);
+  }
+
+  await setMockWebsocketUnavailable(page, false);
+  await expect
+    .poll(
+      () =>
+        page.evaluate(() => window.__BUZZ_E2E_GET_RELAY_CONNECTION_STATE__?.()),
+      { timeout: 10_000 },
+    )
+    .toBe("connected");
+
+  const afterRecovery = `automatic outage recovery ${Date.now()}`;
+  await emitMockMessages(page, [
+    { content: afterRecovery, createdAt: Math.floor(Date.now() / 1_000) },
+  ]);
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("message-timeline")).toContainText(
+    afterRecovery,
+  );
+});
+
+test("authenticated reconnect reports connected while replay is rate-limited", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await expect(page.getByTestId("channel-general")).toBeVisible();
+
+  await activateRelayRateLimit(page, 5);
+  await disconnectMockWebsockets(page);
+
+  // Replay remains intentionally blocked behind admission control, but socket
+  // open + successful AUTH is already a healthy connection. The UI must not
+  // claim the relay is unreachable for the rest of the gate window.
+  await expect
+    .poll(
+      () =>
+        page.evaluate(() => window.__BUZZ_E2E_GET_RELAY_CONNECTION_STATE__?.()),
+      { timeout: 3_000 },
+    )
+    .toBe("connected");
+  await expect(page.getByTestId("sidebar-relay-unreachable")).toHaveCount(0);
+});
+
 test("service restart close resets accumulated backoff", async ({ page }) => {
   await installMockBridge(page, {
     websocketConnectErrors: ["down 1", "down 2", "down 3"],
diff --git a/desktop/tests/e2e/relay-restart.live.spec.ts b/desktop/tests/e2e/relay-restart.live.spec.ts
index 057ef46f52..f3c80e69a1 100644
--- a/desktop/tests/e2e/relay-restart.live.spec.ts
+++ b/desktop/tests/e2e/relay-restart.live.spec.ts
@@ -1,8 +1,13 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
 import { expect, test, type Page } from "@playwright/test";
 
-import { installBridge } from "../helpers/bridge";
+import { installBridge, TEST_IDENTITIES } from "../helpers/bridge";
 import { TwoRelayHarness, type RelaySpec } from "./helpers/twoRelayHarness";
 
+const exec = promisify(execFile);
+
 // Live gate: boots a REAL buzz-relay process, points the app at it, SIGTERMs
 // the relay mid-session, restarts it on the same port, and asserts the client
 // converges back to "connected". This proves the full restart story end to
@@ -20,6 +25,55 @@ function required(name: string, value: string | undefined): string {
   return value;
 }
 
+async function runCli(args: string[], relayUrl: string, privateKey: string) {
+  const binary = required("BUZZ_E2E_CLI_BIN", process.env.BUZZ_E2E_CLI_BIN);
+  const { stdout } = await exec(binary, args, {
+    cwd: "..",
+    env: {
+      ...process.env,
+      BUZZ_AUTH_TAG: "",
+      BUZZ_PRIVATE_KEY: privateKey,
+      BUZZ_RELAY_URL: relayUrl,
+    },
+  });
+  return stdout;
+}
+
+async function seedLiveChannel(relayUrl: string) {
+  const name = `reconnect-live-${process.pid}`;
+  const created = JSON.parse(
+    await runCli(
+      [
+        "channels",
+        "create",
+        "--name",
+        name,
+        "--type",
+        "stream",
+        "--visibility",
+        "open",
+      ],
+      relayUrl,
+      TEST_IDENTITIES.alice.privateKey,
+    ),
+  ) as { channel_id: string };
+  await runCli(
+    [
+      "channels",
+      "add-member",
+      "--channel",
+      created.channel_id,
+      "--pubkey",
+      TEST_IDENTITIES.tyler.pubkey,
+      "--role",
+      "member",
+    ],
+    relayUrl,
+    TEST_IDENTITIES.alice.privateKey,
+  );
+  return { id: created.channel_id, name };
+}
+
 async function connectionState(page: Page): Promise<string> {
   return page.evaluate(() => {
     const win = window as Window & {
@@ -29,13 +83,61 @@ async function connectionState(page: Page): Promise<string> {
   });
 }
 
+async function exerciseBackgroundTraffic(page: Page, durationMs: number) {
+  await page.evaluate(async (duration) => {
+    const deadline = Date.now() + duration;
+    while (Date.now() < deadline) {
+      void window.__BUZZ_E2E_QUERY_CLIENT__?.invalidateQueries({
+        queryKey: ["channels"],
+      });
+      await new Promise((resolve) => window.setTimeout(resolve, 100));
+    }
+  }, durationMs);
+}
+
+async function resetConnectAttempts(page: Page) {
+  await page.evaluate(() => {
+    window.__BUZZ_E2E_RESET_WEBSOCKET_CONNECT_ATTEMPTS__?.();
+  });
+}
+
+async function assertConnectAttemptsArePaced(page: Page) {
+  const attempts = await page.evaluate(
+    () => window.__BUZZ_E2E_GET_WEBSOCKET_CONNECT_ATTEMPTS__?.() ?? [],
+  );
+  expect(attempts.length).toBeGreaterThanOrEqual(2);
+  expect(attempts.length).toBeLessThanOrEqual(4);
+  for (let index = 1; index < attempts.length; index += 1) {
+    expect(attempts[index] - attempts[index - 1]).toBeGreaterThanOrEqual(700);
+  }
+}
+
+async function proveLiveDelivery(
+  page: Page,
+  relayUrl: string,
+  channel: { id: string; name: string },
+  label: string,
+) {
+  await page.getByTestId(`channel-${channel.name}`).click();
+  await expect(page.getByTestId("chat-title")).toHaveText(channel.name);
+  const message = `${label} ${Date.now()}`;
+  await runCli(
+    ["messages", "send", "--channel", channel.id, "--content", message],
+    relayUrl,
+    TEST_IDENTITIES.alice.privateKey,
+  );
+  await expect(page.getByTestId("message-timeline")).toContainText(message, {
+    timeout: 30_000,
+  });
+}
+
 test.describe("relay restart live gate", () => {
   test.skip(!enabled, "set BUZZ_E2E_RELAY_RESTART=1 to run live gate");
 
   test("client reconnects after the relay is SIGTERMed and restarted", async ({
     page,
   }) => {
-    test.setTimeout(180_000);
+    test.setTimeout(240_000);
     const portBase = 26_000 + (process.pid % 3_000);
     const spec: RelaySpec = {
       name: "relay-restart",
@@ -56,6 +158,8 @@ test.describe("relay restart live gate", () => {
       await harness.startRelays();
 
       const relayHttpUrl = `http://127.0.0.1:${spec.ports.main}`;
+      const channel = await test.step("seed live channel and membership", () =>
+        seedLiveChannel(relayHttpUrl));
       await installBridge(page, {
         mode: "relay",
         user: "tyler",
@@ -64,28 +168,68 @@ test.describe("relay restart live gate", () => {
       });
       await page.goto("/");
 
-      // Baseline: the app converges to a live authenticated session.
-      await expect
-        .poll(() => connectionState(page), { timeout: 60_000 })
-        .toBe("connected");
+      // Baseline: the app converges to a live authenticated session and sees
+      // the channel created for this fresh database.
+      await test.step("wait for initial authenticated connection", async () => {
+        await expect
+          .poll(() => connectionState(page), { timeout: 60_000 })
+          .toBe("connected");
+        await expect(page.getByTestId(`channel-${channel.name}`)).toBeVisible({
+          timeout: 30_000,
+        });
+      });
 
       // Roll the pod. Graceful drain: readiness 503 → 5s grace → 1012 close
       // broadcast → process exit. The client must observe the close (not a
       // silent stall) and start retrying.
+      await resetConnectAttempts(page);
       await harness.terminateRelayGracefully(spec.name);
       await expect
         .poll(() => connectionState(page), { timeout: 30_000 })
         .not.toBe("connected");
 
+      // Keep the real relay unavailable across several reconnect windows while
+      // ordinary app traffic continues. This is the production-shaped race:
+      // background queries must not bypass the session coordinator's backoff.
+      await exerciseBackgroundTraffic(page, 8_000);
+      await expect.poll(() => connectionState(page)).not.toBe("connected");
+      await assertConnectAttemptsArePaced(page);
+
       // Bring the "new pod" up on the same address, exactly like a k8s
       // restart behind a stable service endpoint.
       await harness.restartRelay(spec.name);
 
       // The client's retry loop must find the fresh relay and converge back
-      // to connected without any user interaction.
+      // to connected without any user interaction, then prove that AUTH and
+      // live-subscription replay finished by receiving an event published by
+      // a second identity through the real CLI/relay boundary.
       await expect
         .poll(() => connectionState(page), { timeout: 60_000 })
         .toBe("connected");
+      await proveLiveDelivery(
+        page,
+        relayHttpUrl,
+        channel,
+        "first automatic recovery",
+      );
+
+      // Flap the fresh pod once more. A second recovery catches stale timer,
+      // waiter, generation, and subscription state that a single cycle cannot.
+      await harness.terminateRelayGracefully(spec.name);
+      await expect
+        .poll(() => connectionState(page), { timeout: 30_000 })
+        .not.toBe("connected");
+      await exerciseBackgroundTraffic(page, 4_000);
+      await harness.restartRelay(spec.name);
+      await expect
+        .poll(() => connectionState(page), { timeout: 60_000 })
+        .toBe("connected");
+      await proveLiveDelivery(
+        page,
+        relayHttpUrl,
+        channel,
+        "second automatic recovery",
+      );
     } catch (error) {
       console.error(await harness.logs());
       throw error;
diff --git a/desktop/tests/e2e/sidebar-relay-card.spec.ts b/desktop/tests/e2e/sidebar-relay-card.spec.ts
index 9505c0f10f..b9903614d2 100644
--- a/desktop/tests/e2e/sidebar-relay-card.spec.ts
+++ b/desktop/tests/e2e/sidebar-relay-card.spec.ts
@@ -84,6 +84,25 @@ async function setRelayConnectionState(
   }, state);
 }
 
+async function emitRelayConnectionState(
+  page: Page,
+  state: RelayConnectionState,
+) {
+  await page.evaluate((nextState) => {
+    const setConnectionState = (
+      window as Window & {
+        __BUZZ_E2E_SET_RELAY_CONNECTION_STATE__?: (
+          state: RelayConnectionState,
+        ) => void;
+      }
+    ).__BUZZ_E2E_SET_RELAY_CONNECTION_STATE__;
+    if (!setConnectionState) {
+      throw new Error("Mock relay connection state helper is not installed.");
+    }
+    setConnectionState(nextState);
+  }, state);
+}
+
 async function expectGenericReconnectCard(page: Page) {
   const card = page.getByTestId("sidebar-relay-unreachable");
   await expect(card).toBeVisible();
@@ -109,6 +128,55 @@ test("sidebar generic relay failures use the reconnect card", async ({
   await expectGenericReconnectCard(page);
 });
 
+test("relay outage notification stays dismissed through retries and re-arms after recovery", async ({
+  page,
+}) => {
+  await installMockBridge(page, { channelsReadError: CONNECT_ERROR });
+  await page.goto("/");
+  await setRelayConnectionState(page, "disconnected");
+
+  const card = await expectGenericReconnectCard(page);
+  await card
+    .getByRole("button", { name: "Dismiss relay notification" })
+    .click({ force: true });
+  await expect(card).toBeHidden();
+
+  // Retry churn is still the same outage: no successful connection occurred.
+  await emitRelayConnectionState(page, "connecting");
+  await emitRelayConnectionState(page, "disconnected");
+  await emitRelayConnectionState(page, "reconnecting");
+  await page.waitForTimeout(2_100);
+  await expect(card).toBeHidden();
+
+  // A successful connection ends the episode and re-arms the next outage.
+  await setChannelsReadError(page, null);
+  await emitRelayConnectionState(page, "connected");
+  await setChannelsReadError(page, CONNECT_ERROR);
+  await emitRelayConnectionState(page, "disconnected");
+  await expectGenericReconnectCard(page);
+});
+
+test("relay outage notification re-arms after same-URL lifecycle teardown", async ({
+  page,
+}) => {
+  await installMockBridge(page, { channelsReadError: CONNECT_ERROR });
+  await page.goto("/");
+  await setRelayConnectionState(page, "disconnected");
+
+  const card = await expectGenericReconnectCard(page);
+  await card
+    .getByRole("button", { name: "Dismiss relay notification" })
+    .click({ force: true });
+  await expect(card).toBeHidden();
+
+  // Community switches and reconnectCommunity() tear down the singleton to
+  // idle before applying the next lifecycle. The next lifecycle may reuse the
+  // same relay URL, so URL identity alone must not preserve the old dismissal.
+  await emitRelayConnectionState(page, "idle");
+  await emitRelayConnectionState(page, "disconnected");
+  await expectGenericReconnectCard(page);
+});
+
 test("sidebar proxy sign-in failures use the reconnect card", async ({
   page,
 }) => {
diff --git a/desktop/tests/e2e/signout-confirmation.spec.ts b/desktop/tests/e2e/signout-confirmation.spec.ts
index b87caf5975..7b6c9b5761 100644
--- a/desktop/tests/e2e/signout-confirmation.spec.ts
+++ b/desktop/tests/e2e/signout-confirmation.spec.ts
@@ -3,7 +3,7 @@
  *
  * Signing out wipes the identity key and all local data, so the dialog gates
  * "Delete My Data" behind two explicit steps:
- *   1. backup — reveal/copy the nsec, then check "I have saved my private key"
+ *   1. backup — check "I have saved my private key"
  *   2. typed confirmation — type the exact phrase "wipe all my data"
  */
 import { expect, type Page, test } from "@playwright/test";
@@ -13,10 +13,6 @@ import { openSettings } from "../helpers/settings";
 
 const CONFIRM_PHRASE = "wipe all my data";
 
-// The mock bridge routes copy_text_to_clipboard through navigator.clipboard,
-// which requires explicit permissions in headless Chromium.
-test.use({ permissions: ["clipboard-read", "clipboard-write"] });
-
 async function openSignOutDialog(page: Page) {
   await openSettings(page, "profile");
   const section = page.getByTestId("settings-signout");
@@ -36,12 +32,8 @@ test("delete button unlocks only after backup + typed phrase", async ({
   const backupCheckbox = page.getByTestId("signout-backup-confirm");
   const phraseInput = page.getByTestId("signout-confirm-phrase");
 
-  // Everything locked initially: no key interaction yet.
+  // Delete is locked initially; the backup checkbox is immediately usable.
   await expect(deleteButton).toBeDisabled();
-  await expect(backupCheckbox).toBeDisabled();
-
-  // Copying the key unlocks the backup checkbox.
-  await page.getByTestId("nsec-copy").click();
   await expect(backupCheckbox).toBeEnabled();
   await backupCheckbox.click();
 
@@ -61,24 +53,11 @@ test("delete button unlocks only after backup + typed phrase", async ({
   await expect(deleteButton).toBeDisabled();
 });
 
-test("reveal also unlocks the backup checkbox", async ({ page }) => {
-  await installMockBridge(page);
-  await page.goto("/");
-  await openSignOutDialog(page);
-
-  const backupCheckbox = page.getByTestId("signout-backup-confirm");
-  await expect(backupCheckbox).toBeDisabled();
-
-  await page.getByTestId("nsec-reveal-toggle").click();
-  await expect(backupCheckbox).toBeEnabled();
-});
-
 test("completing both gates invokes sign_out", async ({ page }) => {
   await installMockBridge(page);
   await page.goto("/");
   await openSignOutDialog(page);
 
-  await page.getByTestId("nsec-copy").click();
   await page.getByTestId("signout-backup-confirm").click();
   await page.getByTestId("signout-confirm-phrase").fill(CONFIRM_PHRASE);
 
@@ -104,16 +83,15 @@ test("cancel resets the gates for the next open", async ({ page }) => {
   await openSignOutDialog(page);
 
   // Satisfy both gates, then cancel.
-  await page.getByTestId("nsec-copy").click();
   await page.getByTestId("signout-backup-confirm").click();
   await page.getByTestId("signout-confirm-phrase").fill(CONFIRM_PHRASE);
   await page.getByRole("button", { name: "Cancel" }).click();
   await expect(page.getByRole("alertdialog")).not.toBeVisible();
 
-  // Reopen — everything must be locked again.
+  // Reopen — everything must be reset again.
   await page.getByTestId("signout-open-dialog").click();
   await expect(page.getByRole("alertdialog")).toBeVisible();
-  await expect(page.getByTestId("signout-backup-confirm")).toBeDisabled();
+  await expect(page.getByTestId("signout-backup-confirm")).not.toBeChecked();
   await expect(page.getByTestId("signout-confirm-phrase")).toHaveValue("");
   await expect(page.getByTestId("signout-confirm")).toBeDisabled();
 });
@@ -125,8 +103,8 @@ test("nsec load failure still allows sign-out (backup step degrades)", async ({
   await page.goto("/");
   await openSignOutDialog(page);
 
-  // Error shown in place of the key; checkbox is usable so the user is not
-  // permanently locked out of signing out.
+  // Error shown in place of the key; checkbox is still usable so the user is
+  // not locked out of signing out.
   await expect(page.getByTestId("signout-nsec-error")).toContainText(
     "Keychain locked",
   );
diff --git a/desktop/tests/e2e/signout-screenshots.spec.ts b/desktop/tests/e2e/signout-screenshots.spec.ts
index 32fc3ed09d..5cf35c70ab 100644
--- a/desktop/tests/e2e/signout-screenshots.spec.ts
+++ b/desktop/tests/e2e/signout-screenshots.spec.ts
@@ -23,7 +23,7 @@ test.describe("signout screenshots", () => {
     });
   });
 
-  test("signout-section — Sign Out card in Settings › Profile", async ({
+  test("signout-section — data deletion card in Settings › Profile", async ({
     page,
   }) => {
     await installMockBridge(page);
@@ -32,6 +32,9 @@ test.describe("signout screenshots", () => {
 
     const section = page.getByTestId("settings-signout");
     await section.scrollIntoViewIfNeeded();
+    await expect(
+      section.getByRole("button", { name: "Delete my data" }),
+    ).toBeVisible();
 
     // Settle animations before capture.
     await page.evaluate(() =>
@@ -59,7 +62,7 @@ test.describe("signout screenshots", () => {
     await expect(dialog).toBeVisible({ timeout: 5_000 });
     await expect(dialog.getByText("Sign out and wipe all data?")).toBeVisible();
     await expect(
-      dialog.getByRole("button", { name: "Delete My Data" }),
+      dialog.getByRole("button", { name: "Delete my data" }),
     ).toBeVisible();
 
     // Settle animations before capture.
diff --git a/desktop/tests/e2e/video-attachment.spec.ts b/desktop/tests/e2e/video-attachment.spec.ts
index 8f4bb0aa4a..458689a5e0 100644
--- a/desktop/tests/e2e/video-attachment.spec.ts
+++ b/desktop/tests/e2e/video-attachment.spec.ts
@@ -53,25 +53,31 @@ function emitMockMessage(
   page: Page,
   channelName: string,
   content: string,
-  options: { extraTags?: string[][] } = {},
+  options: { extraTags?: string[][]; parentEventId?: string } = {},
 ) {
   return page.evaluate(
-    ({ channelName, content, extraTags }) => {
+    ({ channelName, content, extraTags, parentEventId }) => {
       const emit = (
         window as Window & {
           __BUZZ_E2E_EMIT_MOCK_MESSAGE__?: (input: {
             channelName: string;
             content: string;
             extraTags?: string[][];
+            parentEventId?: string;
           }) => unknown;
         }
       ).__BUZZ_E2E_EMIT_MOCK_MESSAGE__;
       if (!emit) {
         throw new Error("Mock message emitter is unavailable.");
       }
-      emit({ channelName, content, extraTags });
+      return emit({ channelName, content, extraTags, parentEventId });
+    },
+    {
+      channelName,
+      content,
+      extraTags: options.extraTags,
+      parentEventId: options.parentEventId,
     },
-    { channelName, content, extraTags: options.extraTags },
   );
 }
 
@@ -765,6 +771,55 @@ test("video upload previews use poster frames and inline videos open review mode
   ).toContainText("Color pass looks right");
 });
 
+test("video replies in threads open the review comments view", async ({
+  page,
+}) => {
+  await installVideoReviewHarness(page);
+
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+  await waitForMockLiveSubscription(page, "general");
+
+  const root = (await emitMockMessage(
+    page,
+    "general",
+    "Can you review this cut?",
+  )) as { id: string };
+  const videoReply = (await emitMockMessage(
+    page,
+    "general",
+    `![video](${VIDEO_URL})`,
+    {
+      parentEventId: root.id,
+    },
+  )) as { id: string };
+  await emitMockMessage(page, "general", "[00:01] Tighten this transition.", {
+    parentEventId: videoReply.id,
+  });
+
+  const threadSummary = page.locator(`[data-thread-head-id="${root.id}"]`);
+  await expect(threadSummary).toBeVisible();
+  await threadSummary.click();
+
+  const threadPanel = page.getByTestId("message-thread-panel");
+  const threadReplies = threadPanel.getByTestId("message-thread-replies");
+  const reviewButton = threadReplies.getByRole("button", {
+    name: "Open video review",
+  });
+  await expect(reviewButton).toBeVisible();
+  await reviewButton.click();
+
+  const reviewDialog = page.getByTestId("video-review-dialog");
+  await expect(
+    reviewDialog.getByTestId("video-review-comments-panel"),
+  ).toBeVisible();
+  await expect(reviewDialog.getByTestId("message-composer")).toBeVisible();
+  await expect(reviewDialog.getByTestId("video-review-comments")).toContainText(
+    "Tighten this transition.",
+  );
+});
+
 test("narrow inline videos hide playback speed control", async ({ page }) => {
   await installVideoReviewHarness(page);
 
diff --git a/desktop/tests/e2e/voice-settings.spec.ts b/desktop/tests/e2e/voice-settings.spec.ts
new file mode 100644
index 0000000000..9bd8742ed7
--- /dev/null
+++ b/desktop/tests/e2e/voice-settings.spec.ts
@@ -0,0 +1,212 @@
+import { expect, test } from "@playwright/test";
+
+import { waitForAnimations } from "../helpers/animations";
+import { installMockBridge } from "../helpers/bridge";
+import { openSettings } from "../helpers/settings";
+
+const SCREENSHOT_PATH = "test-results/voice-settings/pocket-voices.png";
+
+test.describe("Pocket voice settings", () => {
+  test.use({ viewport: { width: 1100, height: 760 } });
+
+  test("selects and retains a bundled voice while text to speech is off", async ({
+    page,
+  }) => {
+    await installMockBridge(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await openSettings(page, "voice");
+
+    const card = page.getByTestId("settings-voice");
+    await expect(card).toBeVisible();
+    await expect(
+      page.getByText("Agent text to speech", { exact: true }),
+    ).toBeVisible();
+    await expect(
+      page.getByText("Pocket TTS voice", { exact: true }),
+    ).toBeVisible();
+    await expect(card).not.toContainText("April INT8");
+
+    await page.getByTestId("pocket-voice-selector").click();
+    await expect(page.getByRole("menuitemradio")).toHaveCount(12);
+    await page.getByRole("menuitemradio", { name: "Eve" }).click();
+    await expect(page.getByTestId("pocket-voice-selector")).toContainText(
+      "Eve",
+    );
+    await expect(
+      page.getByRole("button", { name: "Pocket TTS voice: Eve" }),
+    ).toBeVisible();
+
+    await page.getByTestId("agent-text-to-speech-toggle").click();
+    await expect(
+      page.getByTestId("agent-text-to-speech-toggle"),
+    ).toHaveAttribute("aria-checked", "false");
+    await expect(page.getByTestId("pocket-voice-controls")).toHaveAttribute(
+      "aria-disabled",
+      "true",
+    );
+    await expect(page.getByTestId("pocket-voice-selector")).toContainText(
+      "Eve",
+    );
+
+    const savedCommands = await page.evaluate(() =>
+      (window.__BUZZ_E2E_COMMAND_LOG__ ?? [])
+        .filter((entry) =>
+          ["set_pocket_voice", "set_tts_enabled"].includes(entry.command),
+        )
+        .map((entry) => ({ command: entry.command, payload: entry.payload })),
+    );
+    expect(savedCommands).toEqual([
+      {
+        command: "set_pocket_voice",
+        payload: { voiceKey: "pocket:eve" },
+      },
+      {
+        command: "set_tts_enabled",
+        payload: { enabled: false },
+      },
+    ]);
+  });
+
+  test("captures the complete VCTK preset settings surface", async ({
+    page,
+  }) => {
+    await installMockBridge(page, {
+      ttsSettings: {
+        version: 1,
+        agentTextToSpeech: true,
+        voicePreferences: ["pocket:eve"],
+      },
+    });
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await openSettings(page, "voice");
+
+    const card = page.getByTestId("settings-voice");
+    await expect(card).toBeVisible();
+    await expect(page.getByTestId("pocket-voice-selector")).toContainText(
+      "Eve",
+    );
+    await page.getByTestId("pocket-voice-selector").click();
+    await expect(page.getByRole("menuitemradio")).toHaveCount(12);
+    const menu = page.getByRole("menu");
+    await expect(menu).toBeVisible();
+    await waitForAnimations(page);
+    const cardBox = await card.boundingBox();
+    const menuBox = await menu.boundingBox();
+    const viewport = page.viewportSize();
+    if (!cardBox || !menuBox || !viewport) {
+      throw new Error("Voice settings screenshot bounds are unavailable");
+    }
+    const x = Math.max(0, Math.min(cardBox.x, menuBox.x) - 16);
+    const y = Math.max(0, Math.min(cardBox.y, menuBox.y) - 16);
+    const right = Math.min(
+      viewport.width,
+      Math.max(cardBox.x + cardBox.width, menuBox.x + menuBox.width) + 16,
+    );
+    const bottom = Math.min(
+      viewport.height,
+      Math.max(cardBox.y + cardBox.height, menuBox.y + menuBox.height) + 16,
+    );
+    await page.screenshot({
+      path: SCREENSHOT_PATH,
+      clip: {
+        x: Math.floor(x),
+        y: Math.floor(y),
+        width: Math.ceil(right - x),
+        height: Math.ceil(bottom - y),
+      },
+    });
+  });
+
+  test("imports, selects, and safely deletes a local voice", async ({
+    page,
+  }) => {
+    await installMockBridge(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await openSettings(page, "voice");
+
+    await page.getByTestId("pocket-voice-import").click();
+    await expect(page.getByTestId("pocket-voice-selector")).toContainText(
+      "My voice",
+    );
+    await expect(page.getByTestId("pocket-voice-delete")).toBeVisible();
+    await page.getByRole("button", { name: "Preview" }).click();
+
+    await page.getByTestId("pocket-voice-delete").click();
+    await expect(page.getByText("Delete imported voice?")).toBeVisible();
+    await page.getByTestId("confirm-pocket-voice-delete").click();
+    await expect(page.getByTestId("pocket-voice-selector")).toContainText(
+      "Mary",
+    );
+    await expect(page.getByTestId("pocket-voice-delete")).toBeHidden();
+    await page.getByRole("button", { name: "Preview" }).click();
+
+    const mutations = await page.evaluate(() =>
+      (window.__BUZZ_E2E_COMMAND_LOG__ ?? [])
+        .filter((entry) =>
+          [
+            "import_pocket_voice",
+            "preview_pocket_voice",
+            "delete_pocket_voice",
+          ].includes(entry.command),
+        )
+        .map((entry) => ({ command: entry.command, payload: entry.payload })),
+    );
+    expect(mutations).toEqual([
+      { command: "import_pocket_voice", payload: {} },
+      {
+        command: "preview_pocket_voice",
+        payload: { voiceKey: `pocket:imported:${"1".repeat(64)}` },
+      },
+      {
+        command: "delete_pocket_voice",
+        payload: { voiceKey: `pocket:imported:${"1".repeat(64)}` },
+      },
+      {
+        command: "preview_pocket_voice",
+        payload: { voiceKey: "pocket:mary" },
+      },
+    ]);
+  });
+
+  test("keeps the selected voice unchanged when the native picker is cancelled", async ({
+    page,
+  }) => {
+    await installMockBridge(page, { pocketVoiceImportResult: "cancel" });
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await openSettings(page, "voice");
+
+    await expect(page.getByTestId("pocket-voice-selector")).toContainText(
+      "Mary",
+    );
+    await page.getByTestId("pocket-voice-import").click();
+    await expect(page.getByTestId("pocket-voice-selector")).toContainText(
+      "Mary",
+    );
+    await expect(page.getByTestId("pocket-voice-delete")).toBeHidden();
+    await expect(page.getByTestId("voice-settings-error")).toBeHidden();
+
+    const audioCommands = await page.evaluate(() =>
+      (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter((entry) =>
+        ["preview_pocket_voice", "delete_pocket_voice"].includes(entry.command),
+      ),
+    );
+    expect(audioCommands).toEqual([]);
+  });
+
+  test("surfaces invalid or unsupported WAV errors without changing selection", async ({
+    page,
+  }) => {
+    await installMockBridge(page, { pocketVoiceImportResult: "invalid" });
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await openSettings(page, "voice");
+
+    await page.getByTestId("pocket-voice-import").click();
+    await expect(page.getByTestId("voice-settings-error")).toContainText(
+      "Voice WAV must contain PCM or 32-bit float audio",
+    );
+    await expect(page.getByTestId("pocket-voice-selector")).toContainText(
+      "Mary",
+    );
+    await expect(page.getByTestId("pocket-voice-delete")).toBeHidden();
+  });
+});
diff --git a/desktop/tests/helpers/bridge.ts b/desktop/tests/helpers/bridge.ts
index ca4d62ddd6..8a9ab2be11 100644
--- a/desktop/tests/helpers/bridge.ts
+++ b/desktop/tests/helpers/bridge.ts
@@ -83,6 +83,17 @@ type MockRelayAgentSeed = {
   status?: "online" | "away" | "offline";
 };
 
+type MockHuddleSeed = {
+  parentChannelId: string;
+  ephemeralChannelId: string;
+  members: Array<{
+    pubkey: string;
+    role: "owner" | "admin" | "member" | "guest" | "bot";
+  }>;
+  transcriptionEnabled?: boolean;
+  isCreator?: boolean;
+};
+
 type MockPersonaSeed = {
   id?: string;
   displayName: string;
@@ -131,11 +142,36 @@ export type MockAgentMemoryListing = {
   fetchedAt: number;
 };
 
+/** Result returned by the `install_acp_runtime` mock command. */
+type MockInstallRuntimeResult = {
+  success: boolean;
+  steps: {
+    step: string;
+    command: string;
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    exit_code: number | null;
+    hint?: string;
+  }[];
+  /** Install log the failure message points at. Omitted = no log was written. */
+  log_path?: string | null;
+};
+
 type MockBridgeOptions = {
+  ttsSettings?: {
+    version: number;
+    agentTextToSpeech: boolean;
+    voicePreferences: string[];
+  };
+  /** Native picker boundary result for Pocket voice import tests. */
+  pocketVoiceImportResult?: "success" | "cancel" | "invalid";
   /** Advertised HEAD for the first mock project without adding that branch. */
   projectHeadBranch?: string;
   /** Relay NIP-11 identity used to sign authoritative repository state. */
   relaySelf?: string | null;
+  /** Native-like huddle state seeded from authoritative role-bearing membership. */
+  huddle?: MockHuddleSeed;
   /** Builderlab account returned by hosted-community onboarding. Null/omitted = signed out. */
   builderlabAuth?: { email?: string; name?: string; expiresAt: string } | null;
   /** Optional policy returned by the native join-policy discovery command. */
@@ -171,35 +207,17 @@ type MockBridgeOptions = {
   connectAcpRuntimeDelayMs?: number;
   connectAcpRuntimeError?: string;
   installAcpRuntimeDelayMs?: number;
+  /** Live output lines the mocked install emits before it settles, in order.
+   *  Each arrives as an `acp-install-output` event, preceded by the clear
+   *  signal the backend sends at the start of an attempt. */
+  installAcpRuntimeOutputLines?: string[];
   /** Override the result returned by the `install_acp_runtime` mock command.
    *  Pass `{ success: false, steps: [...] }` to exercise error/Retry states. */
-  installAcpRuntimeResult?: {
-    success: boolean;
-    steps: {
-      step: string;
-      command: string;
-      success: boolean;
-      stdout: string;
-      stderr: string;
-      exit_code: number | null;
-      hint?: string;
-    }[];
-  };
+  installAcpRuntimeResult?: MockInstallRuntimeResult;
   /** Sequence of results for successive `install_acp_runtime` calls. Call N
    *  returns results[N]; when exhausted the last entry repeats. Takes precedence
    *  over `installAcpRuntimeResult`. Use for fail-then-succeed Retry tests. */
-  installAcpRuntimeResults?: Array<{
-    success: boolean;
-    steps: {
-      step: string;
-      command: string;
-      success: boolean;
-      stdout: string;
-      stderr: string;
-      exit_code: number | null;
-      hint?: string;
-    }[];
-  }>;
+  installAcpRuntimeResults?: MockInstallRuntimeResult[];
   activePersonaIds?: string[];
   /**
    * Listing returned by the mocked `get_agent_memory` command. Pass a single
@@ -211,6 +229,14 @@ type MockBridgeOptions = {
     mcp?: MockCommandAvailability;
   };
   managedAgents?: MockManagedAgentSeed[];
+  /** Result returned by the mocked `add_agent_to_huddle` command. */
+  addAgentToHuddleResult?: {
+    ephemeral_added: boolean;
+    parent_added: boolean;
+    parent_error: string | null;
+  };
+  /** Delay an invocation-time huddle snapshot to exercise hydration ordering. */
+  huddleStateReadDelayMs?: number;
   /** Per agent+relay runtime rows for pair-scoped lifecycle commands. */
   managedAgentRuntimes?: Array<{
     pubkey: string;
@@ -268,6 +294,8 @@ type MockBridgeOptions = {
   channelWindowDelayMs?: number;
   profileReadDelayMs?: number;
   profileReadError?: string;
+  /** Override whether get_profile reports a real kind:0 event. */
+  profileHasEvent?: boolean;
   profileUpdateError?: string;
   profileUpdateErrors?: string[];
   searchProfiles?: MockSearchProfileSeed[];
@@ -439,6 +467,14 @@ type MockBridgeOptions = {
   /** Delay (ms) for `set_global_agent_config` — hold saves open in tests.
    *  Alias of `globalConfigSaveDelayMs` (kept for onboarding specs). */
   setGlobalAgentConfigDelayMs?: number;
+  /** Errors returned by successive backup verification attempts. Null succeeds. */
+  backupVerificationErrors?: (string | null)[];
+  /** Public identities returned by successive successful backup verifications. */
+  backupVerificationPubkeys?: string[];
+  /** Delay (ms) applied to backup encryption so specs can observe pending UI. */
+  backupEncryptionDelayMs?: number;
+  /** Native paths returned by successive backup saves. */
+  backupSavePaths?: Array<string | null>;
   /**
    * When set, `get_nsec` throws with this message. For a single always-fail
    * scenario. Use `nsecErrors` for sequenced fail/succeed.
diff --git a/desktop/tests/helpers/fileDrag.ts b/desktop/tests/helpers/fileDrag.ts
new file mode 100644
index 0000000000..3a396ada0f
--- /dev/null
+++ b/desktop/tests/helpers/fileDrag.ts
@@ -0,0 +1,52 @@
+import type { Page } from "@playwright/test";
+
+/**
+ * Simulate a native file drag entering the window. The backup test flow
+ * listens for window-level dragenter with a "Files" payload and swaps in a
+ * composer-style drop overlay over its host surface.
+ */
+export async function startWindowFileDrag(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const dataTransfer = new DataTransfer();
+    dataTransfer.items.add(
+      new File(["x"], "identity.ncryptsec", { type: "text/plain" }),
+    );
+    window.dispatchEvent(
+      new DragEvent("dragenter", { dataTransfer, bubbles: true }),
+    );
+  });
+}
+
+/** Simulate the file drag leaving the window without dropping. */
+export async function endWindowFileDrag(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    window.dispatchEvent(new DragEvent("dragend", { bubbles: true }));
+  });
+}
+
+/** Drop a text file with the given contents onto the element with `testId`. */
+export async function dropFileOnTestId(
+  page: Page,
+  testId: string,
+  contents: string,
+  name = "identity.ncryptsec",
+): Promise<void> {
+  await page.evaluate(
+    ({ testId, contents, name }) => {
+      const dataTransfer = new DataTransfer();
+      dataTransfer.items.add(
+        new File([contents], name, { type: "text/plain" }),
+      );
+      const target = document.querySelector(`[data-testid="${testId}"]`);
+      if (!target) throw new Error(`drop target ${testId} not found`);
+      target.dispatchEvent(
+        new DragEvent("drop", {
+          dataTransfer,
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+    },
+    { testId, contents, name },
+  );
+}
diff --git a/desktop/tests/helpers/onboarding.ts b/desktop/tests/helpers/onboarding.ts
index 61b31e6e5b..d7f61bafe6 100644
--- a/desktop/tests/helpers/onboarding.ts
+++ b/desktop/tests/helpers/onboarding.ts
@@ -16,9 +16,8 @@ export async function seedActiveIdentity(
   );
 }
 
-/** Navigate through the backup step (fresh-key path). */
+/** Continue past the created-key page without opening optional backup options. */
 export async function passThroughBackupStep(page: Page) {
   await expect(page.getByTestId("onboarding-page-backup")).toBeVisible();
-  await expect(page.getByTestId("nsec-value")).toBeVisible();
   await page.getByTestId("onboarding-next").click();
 }
diff --git a/desktop/tests/helpers/settings.ts b/desktop/tests/helpers/settings.ts
index a63b52453e..c26c0e9195 100644
--- a/desktop/tests/helpers/settings.ts
+++ b/desktop/tests/helpers/settings.ts
@@ -3,6 +3,7 @@ import { expect, type Page } from "@playwright/test";
 type SettingsSection =
   | "profile"
   | "notifications"
+  | "voice"
   | "agents"
   | "channel-templates"
   | "compute"
diff --git a/docs/MCP_DRIVEN_HOOKS.md b/docs/MCP_DRIVEN_HOOKS.md
index e510c378e7..6812a5b9a6 100644
--- a/docs/MCP_DRIVEN_HOOKS.md
+++ b/docs/MCP_DRIVEN_HOOKS.md
@@ -65,6 +65,23 @@ These constraints ensure a buggy or malicious hook cannot trap the agent.
 Hooks are **off by default**. The operator must explicitly opt in via
 `MCP_HOOK_SERVERS`.
 
+### Not a hook: the reply guard
+
+`buzz-agent` has one in-process objection at the `_Stop` gate that is **not** an
+MCP hook and exposes no hook tool: the reply guard
+(`BUZZ_AGENT_REQUIRE_REPLY=1`), which reminds the model to publish when a turn is
+about to end with nothing posted to Buzz. There is no `_ReplyGuard` tool to
+implement and no server to allowlist — the env var and the recognition contract
+are documented in
+[crates/buzz-agent/README.md](../crates/buzz-agent/README.md#reply-guard).
+
+It is mentioned here only because it shares this lifecycle point and this
+budget: its reminders count against `BUZZ_AGENT_STOP_MAX_REJECTIONS` like any
+hook objection, and a round carrying both a hook objection and a reminder costs
+one rejection and delivers both texts. Setting the budget to 0 disables both.
+That the gate can carry in-process objections alongside hook output is
+deliberate; hooks see no difference.
+
 ## Implementing a Hook
 
 Any MCP server can expose hooks. Example: a test-runner server that blocks
diff --git a/docs/formal/nip-rs-unread/NOTE.md b/docs/formal/nip-rs-unread/NOTE.md
new file mode 100644
index 0000000000..7472c3dca3
--- /dev/null
+++ b/docs/formal/nip-rs-unread/NOTE.md
@@ -0,0 +1,698 @@
+---
+title: "NIP-RS manual-unread: bounded exhaustive model — candidates A vs B"
+tags: [nostr, nip-rs, read-state, formal-model, buzz]
+status: active
+created: 2026-07-16
+---
+
+# NIP-RS manual-unread encoding model
+
+Bounded exhaustive model comparing two candidate CRDT encodings for a
+manual mark-as-unread override layer within NIP-RS read state.
+
+## Run
+
+```bash
+python3 exhaustive.py
+python3 mutation.py
+```
+
+Both scripts are deterministic and exit 0 on success.
+
+## Context
+
+NIP-RS v1 encodes read state as grow-only `max(timestamp)` frontiers per
+context. Manual mark-as-unread requires a second source of truth (an
+override layer) because the frontier cannot be lowered — a lower value is
+indistinguishable from a stale replica under `max()` merge.
+
+The override layer must converge across devices, survive legacy client
+rewrite cycles, and remain bounded within the existing 32 KiB plaintext
+budget. Two candidate encodings are modeled:
+
+- **A — lexicographic operation register:** per context, one register
+  `{counter, client_tiebreak, op, baseline}` in a NEW top-level field.
+- **B — two grow-only counters + baseline:** per context, `S` (set
+  counter), `C` (clear counter), `B` (frontier-at-set-time) encoded as
+  sibling keys under `contexts`.
+
+## Model universe
+
+- 2 upgraded devices + 1 legacy device
+- 2 contexts (`c0`, `c1`)
+- Actions: mark-unread, mark-read (with frontier advance),
+  advance-frontier, compact, reinstall (client_id loss),
+  deliver (including duplicate/replay)
+- BFS over canonical global states with interleaved actions and deliveries
+  (not phased), depth-bounded
+- All delivery permutations of published blobs at terminal states
+- Multi-slot union (split blob across 2 slots, deliver separately)
+- Directed deep-history check: compact → new local actions (counter
+  reuse) → delayed stale delivery, over a 672-point parameter cube
+  (stale `(S,C,B)` × post-compaction frontier × 7 action sequences ×
+  2 tie policies × 1 delivery shape). The prior 2,016-point count
+  included two duplicate split-delivery shapes (`split_fwd`/`split_rev`)
+  that became semantically identical to `single` once the atomic-grouping
+  rule made a single-context compliant split always whole-register+empty;
+  collapsed to one meaningful shape without loss of register-level
+  coverage.
+- Cross-device compaction transparency check: same tombstone, delivered
+  to an unrelated device with its own live concurrent state, over a
+  312-point parameter cube (stale `(S,C,B)` × post-compaction frontier ×
+  4 fresh-frontier values × 2 tie policies), plus a monotonicity lemma
+  over 1,728 points (2 tie policies × 4×4×3×3 receiving-register/frontier
+  combinations × 6 ceiling values) proving the ceiling can never
+  *strengthen* a receiving register's set-counter standing
+- States explored: 7,129 per tie policy (14,258 total)
+- Published-state merge closure: every override is canonicalized against
+  the device's own effective frontier at serialization time before
+  hitting the wire (mandatory, not optional) — live unchanged, dead
+  folded to the tombstone floor, virgin omitted. Checked over a directed
+  witness (Thufir's exact dead+dead pair) plus a general search: every
+  pairwise join of a bounded cube of 300 independently-dead published
+  states (156 clear-wins + 144 set-wins = 300 total across both tie
+  policies), including a one-hop relay republication to cover
+  delayed/multi-hop delivery — 45,074 pairs checked total (156² + 144²
+  + 2 directed witnesses)
+
+## Invariants checked
+
+| # | Invariant | A | B (clear-wins) | B (set-wins) |
+|---|-----------|---|-----------------|--------------|
+| I1 | Join associative/commutative/idempotent | PASS | PASS | PASS |
+| I2 | Convergence (all delivery orders) | not exercised | PASS | PASS |
+| I3 | No frontier regression | not exercised | PASS | PASS |
+| I4 | Concurrent set/clear winner stable | not exercised | PASS | PASS |
+| I5 | Compaction: no loss, no resurrection (immediate merge-back) | n/a | PASS | PASS |
+| I5c | Deep-history: compact → reuse → delayed stale delivery (same-device replay) | n/a | PASS | PASS |
+| I5d | Cross-device compaction transparency (suppress-only, not zero-divergence) | n/a | PASS | PASS |
+| I5e | Published-state merge closure: dead+dead join stays inactive | n/a | PASS | PASS |
+| I6 | Replay harmless | not exercised | PASS | PASS |
+| I7 | Legacy rewrite safety | **FAIL** (witness) | PASS | PASS |
+| I8 | Bounded key growth (3 keys/ctx live, 1 key/ctx tombstone) | n/a | PASS | PASS |
+| I9 | DeviceA counter absorption | PASS | n/a | n/a |
+
+Note: Candidate A is exercised only for I1, I7, and I9. BFS/convergence,
+frontier-regression, concurrent-winner, and replay tests (I2–I4, I6) are
+Candidate B-only; adding A variants would fail minimalism since A is already
+dead on I7 (legacy-rewrite erasure).
+
+I5 covers the immediate compacted-vs-pre-compaction merge shape (both
+merge orders). I5c is the same-device deep-history property this round
+was originally opened to close: it directly targets the ~9-transition
+history a depth-4 BFS cannot structurally reach (compact → new local
+set/clear → delayed stale delivery, including from a second slot),
+asserting that compaction never resurrects a dead override or drops a
+live one **when the delayed delivery is the compacting device's own
+pre-compaction ancestor** (or an exact copy of it, e.g. a peer that
+never advanced past the original snapshot).
+
+**I5c does not cover, and NOTE.md previously overstated, the
+cross-device case.** Compaction is a storage optimization from the
+compacting device's own point of view — its dead register's baseline
+`B` was frontier-relative to *that device's* history, and dropping `S`
+in favor of the `C` ceiling is safe against replays of *its own* past.
+But once published, the tombstone's `C` ceiling is globally comparable
+via componentwise `max()`, while the baseline-relative death that
+produced it is not. I5d proves the resulting property precisely:
+merging in a tombstone can **suppress** — never resurrect, per the
+`test_tombstone_merge_monotonic` structural lemma — a different
+device's concurrent fresh set whose own counters happen to be at or
+below the tombstone's ceiling, and the suppression always recovers with
+one more local mark-unread (verified replay-stable against the same
+tombstone). This is a one-shot false-negative risk, not a correctness
+violation of the CRDT join (idempotent/commutative/associative still
+hold per I1) and not new: an *uncompacted* stale explicit clear already
+suppresses a fresh concurrent set under clear-wins with no compaction
+anywhere (verified directly — see "Tie policy evidence" below); the
+tombstone extends the same false-negative-preferring shape to
+baseline-dominated dead sets that were never explicitly cleared.
+
+**I5e — published-state merge closure — is a protocol requirement, not
+an optimization.** I5d's suppress-only guarantee assumes the tombstone
+was actually on the wire before the merge. Nothing forces that:
+`compact_b()`/`do_compact` are a local storage-GC transition a device
+may or may not have called before it serializes. Without a mandatory
+canonicalization step, `publish_blob()` can emit a register's *raw*
+`(S, C, B)` — dead by construction (baseline-dominated, clear-dominated,
+or a clear-wins tie) but not yet folded into the tombstone's
+globally-comparable `C` ceiling. Two such raw-dead registers, published
+by two different devices for unrelated reasons, can componentwise-max
+into a **live** join: each register's `S` and `B` came from a different
+device history, and the merge recombines them independent of either
+history's own death cause. This is a distinct hazard from I5d's
+suppression (I5d is a live register losing to a stale dead one; I5e's
+witness is two dead registers producing a live one) but the same root
+cause — components taken from independent histories can be
+recombined in ways neither history's own frontier ever permitted.
+
+**Fix: canonical publication is mandatory, not advisory.**
+`DeviceB.publish_blob()` now canonicalizes every override against the
+device's own effective frontier at serialization time, unconditionally
+— live unchanged (3 keys), dead folded to the tombstone floor `RegB(0,
+max(S,C), 0)` (1 key), virgin omitted (0 keys) — regardless of whether
+`do_compact` was ever called locally first. This is a **spec-amendment
+requirement for any production client implementing this override
+layer**: publication MUST canonicalize before serialization, the same
+way it MUST advance the frontier monotonically. It is load-bearing
+correctness, not a storage optimization a client can opt out of.
+`do_compact` remains available separately to mutate a device's own
+`self.overrides` for local storage-GC purposes; it is no longer a
+prerequisite for correct publication, because publication no longer
+depends on prior local state having been compacted.
+
+**Proof obligation closed:** `exhaustive.py::test_published_merge_closure`
+checks two ways — Thufir's exact witness pair
+(`RegB(3,2,0)`@baseline-dead-50 join `RegB(1,2,100)`@clear-dead-100,
+raw join is live `RegB(3,2,100)`) as a directed case under both tie
+policies, and a general search over every pairwise join of a bounded
+cube of 300 independently-dead published states (156 clear-wins + 144
+set-wins = 300 total across both tie policies), including a one-hop
+relay republication step to cover delayed/multi-hop delivery (a relay
+that receives one operand alone and republishes — re-canonicalizing —
+before forwarding). The 45,074 ordered pairs checked comes from
+156² + 144² + 2 directed witnesses. `mutation.py::mutant_m7` reverts
+`publish_blob` to the pre-fix raw-serialization behavior and reproduces
+Thufir's exact resurrection witness directly, confirming the new
+invariant has teeth.
+
+## Candidate comparison
+
+### Convergence
+
+Both candidates converge under all tested delivery permutations (algebraic
+property).
+Candidate B achieves this with componentwise `max()` merge (a standard
+state-based CRDT join). Candidate A uses a register with lexicographic
+tuple comparison — also convergent, but the register requires a
+client-identity tiebreak field. (Convergence for Candidate B is verified
+by exhaustive BFS over all reachable states; I2–I4 and I6 are exercised
+for Candidate B only — see invariant table.)
+
+### Legacy compatibility matrix
+
+| Scenario | A | B |
+|----------|---|---|
+| Upgraded publishes, legacy reads blob | Legacy drops `overrides` field | Legacy preserves `ov_*` sibling keys |
+| Legacy rewrites same slot | **Overrides erased** (expected-witness confirmed) | Sibling keys survive sanitization |
+| Upgraded reads legacy-rewritten blob | Override state lost | Override state intact |
+| Legacy reads its own frontier | Inert (correct) | Inert (correct) |
+| Legacy frontier advance past baseline | Cannot clear override (erased) | Stale set dominated (correct) |
+
+**Candidate A's legacy erasure is the decisive defect.** The desktop and
+mobile parsers (`readStateFormat.ts:82-108`, `read_state_format.dart:100-141`)
+reconstruct only `{v, client_id, contexts}`. A same-slot legacy rewrite
+drops the top-level `overrides` field entirely and republishes without it.
+There is no safe migration path: any user with a single legacy device
+loses all manual-unread state on the next rewrite cycle.
+
+Candidate B's sibling keys (`ov_s:`, `ov_c:`, `ov_b:`) pass all legacy
+validation gates — keys are <= 256 UTF-8 bytes, values are uint32 —
+and round-trip through legacy rewrite unmodified.
+
+**Legacy carry-through simplification (documented divergence).** Row
+"Legacy preserves `ov_*` sibling keys" is proven two different ways in
+this model, and they are not the same claim:
+
+- `legacy_sanitize_blob` — the byte-sanitization function alone (drop
+  keys >256 UTF-8 bytes or non-uint32 values) — genuinely preserves
+  unknown keys as opaque pass-through, matching production
+  `sanitizeContexts`. `test_legacy_rewrite_b` (I7) exercises exactly
+  this: an upgraded device's blob is sanitized and received by a
+  *second upgraded* device; the sibling keys survive because
+  sanitization never touches keys it doesn't recognize.
+- `DeviceB(is_legacy=True)` — the explorer's legacy *device* object used
+  in the multi-device BFS (`exhaustive.py`) — does **not** carry
+  through `ov_*` keys it receives. `receive_merge` parses them into a
+  local dict but the store step is gated on `not self.is_legacy`
+  (`model.py:268`), so a legacy device's own `publish_blob` only ever
+  republishes its own frontier keys, never sibling keys it received
+  from an upgraded peer. This is a deliberate model simplification, not
+  a claim about production: production's legacy client is a single
+  `sanitizeContexts` pass with no in-memory override model to gate on,
+  so it forwards unknown keys unchanged; the model's `DeviceB` needed an
+  explicit legacy/upgraded split to represent "does not understand or
+  act on overrides" for the BFS explorer's mark-unread/mark-read action
+  space, and that split was implemented as drop-on-receive rather than
+  store-opaque-and-forward.
+- **Why this doesn't hide a defect:** every invariant that asserts
+  sibling-key survival through a legacy hop (I7) is checked via the
+  sanitize function directly, never via a `DeviceB(is_legacy=True)`
+  relay round-trip — the two paths are never conflated in a single
+  assertion. The BFS explorer's own legacy-device transitions are also
+  gated: `enabled_transitions` only enqueues `mark_unread`/`mark_read`/
+  `compact` for a device `if not d.is_legacy` (`exhaustive.py:118-124`),
+  so a legacy device in the BFS never even attempts to act on overrides;
+  `do_mark_unread`/`do_mark_read` (`model.py:210-222`) additionally
+  carry an explicit `if self.is_legacy: return` no-op guard as
+  defense-in-depth for the same property. `do_compact`
+  (`model.py:227-236`) carries no such explicit guard — it is a no-op
+  for a legacy device only *transitively*, because `self.overrides`
+  is never populated for one (every write path into `self.overrides`
+  is already gated on `not self.is_legacy`), so `do_compact` finds
+  `self.overrides.get(ctx)` is always `None` and returns immediately.
+  Either way, the drop-on-receive simplification never
+  changes the BFS's own convergence or compaction verdicts (I2, I3, I5,
+  I5c, I5d) — those are computed only over upgraded devices'
+  `override_is_set`. The one place a real production legacy client
+  *does* matter for override survival — sanitizing an upgraded device's
+  own re-published blob — is I7's scope, and I7 uses the accurate
+  function.
+- **Implication for implementation:** production's `sanitizeContexts`
+  pass-through behavior is correct and required; this note exists so a
+  future reader of `DeviceB.receive_merge` doesn't mistake the model's
+  drop-on-receive simplification for a claim that legacy relaying loses
+  override state in production — it doesn't, per the function-level
+  proof above.
+
+### Identity dependence
+
+- **A requires client_id** for the tiebreak field. After reinstall
+  (new `client_id`), the tiebreak changes. Convergence is preserved only
+  because the counter is strictly higher; a same-counter reinstall would
+  create an ambiguous merge.
+- **B needs no client identity** — componentwise `max()` is
+  identity-free. Confirmed: reinstall with new `client_id` preserves
+  convergence.
+
+### Bytes per manually-unread context
+
+Sizes computed with realistic context IDs. Envelope cost
+(`{"v":1,"client_id":"...","contexts":{}}`) is ~60 bytes and shared
+across all contexts — amortized to near zero per context.
+
+| Context type | Context ID example | ID length | Live override keys (3) | Tombstone key (1) |
+|--------------|-------------------|-----------|------------------------|--------------------|
+| Channel | `b68cd7cb-6f8d-4641-b743-a7349eb4114b` | 36 | 138 bytes | 45 bytes |
+| Message | `msg:` + 64-hex event ID | 68 | 234 bytes | 77 bytes |
+| Thread | `thread:` + 64-hex event ID | 71 | 243 bytes | 80 bytes |
+
+Live-override bytes are unchanged by the reserved-namespace escaping
+(below): every context ID Buzz actually generates (channel UUID,
+`msg:hex64`, `thread:hex64`) is a no-op under `escape_context_key` — none
+begin with `ov_` or `esc:` — so the escape marker costs 0 bytes in the
+common case. Tombstone bytes are new in this revision: canonical
+publication no longer serializes a dead register at 3 keys (see
+"Compaction behavior" below and "Published-state merge closure" above)
+but a single `ov_c:` key with the counter ceiling — this is now the
+literal output of `publish_blob()` for any dead override, not merely
+the output of the optional `do_compact` storage-GC step.
+
+Breakdown for channel context (worst real-world common case, live):
+```
+"ov_s:b68cd7cb-6f8d-4641-b743-a7349eb4114b":1    → 44 chars
+"ov_c:b68cd7cb-6f8d-4641-b743-a7349eb4114b":0    → 44 chars
+"ov_b:b68cd7cb-6f8d-4641-b743-a7349eb4114b":10   → 45 chars
+                                          total  ≈ 138 bytes (+ 2 commas)
+```
+
+Tombstone floor for channel context (dead override after compaction):
+```
+"ov_c:b68cd7cb-6f8d-4641-b743-a7349eb4114b":3    → 45 chars ≈ 45 bytes
+```
+
+Candidate A for comparison: `{"counter":1,"tiebreak":"dev0","op":"SET","baseline":10}`
+≈ 56 bytes per context as a JSON object, plus the top-level `overrides`
+field overhead. However, this is moot since A's top-level field is erased
+by legacy clients.
+
+### Reserved key namespace
+
+NIP-RS v1 context IDs are arbitrary UTF-8 (spec `:89`, `:113-114`), so a
+pre-existing opaque context could legitimately begin with `ov_s:`,
+`ov_c:`, or `ov_b:` and, once flattened into the same `contexts` map,
+be misparsed as a control key for a *different* context.
+
+**Reservation:** the 3-byte stem `ov_` and the escape marker `esc:` are
+reserved at the spec-amendment level. A raw context ID that begins with
+either is escaped on publish by prepending `esc:`, and unescaped on
+receive by stripping exactly one leading `esc:` (`model.py:
+escape_context_key`, `unescape_context_key`). This is a bijection, not
+an idempotent no-op: a context literally named `esc:foo` escapes to
+`esc:esc:foo` on the wire and unescapes back to exactly `esc:foo` on
+receipt — the two operations are inverses, so no collision or data
+loss occurs even for context IDs that already contain the marker.
+
+**Cost:** zero bytes for every context ID Buzz generates today (channel
+UUID, `msg:hex64`, `thread:hex64` — none start with `ov_` or `esc:`).
+Only a context ID that happens to start with the reserved stem pays the
+4-byte `esc:` prefix.
+
+**Backward-compatibility limitation (Thufir's qualification — not a
+collision-safe migration of existing data):** a context published
+*unescaped* by a client that predates this amendment, and that happens
+to start with `ov_` (e.g. an already-published, pre-existing
+`ov_s:evil`-style context), is **not safely migrated** by this scheme.
+Retroactive escaping cannot rewrite a blob the original publisher never
+knew needed escaping — the codec protects contexts generated by
+amendment-aware clients going forward, not history that predates the
+amendment. This is a theoretical concern for the reasons in the
+">256-byte key drop hazard" section: Buzz's own key shapes cannot
+trigger it, and no legacy client is known to generate `ov_`-prefixed
+context IDs. Documented as a residual, unsolved, backward-compatibility
+gap — not modeled further — per the same practical-risk reasoning
+already applied to the 256-byte hazard below.
+
+**Verified:** `exhaustive.py::test_reserved_namespace_collision` — a
+context literally named `ov_s:evil` round-trips through publish/receive
+as frontier state (not misparsed as an override), and a real override on
+a *different* context in the same blob is unaffected.
+
+### Counter headroom (uint32)
+
+Each counter (S, C) is a uint32: 2^32 - 1 = 4,294,967,295. At one
+toggle per second, ~136 years. No practical concern for manual
+right-click actions.
+
+### >256-byte key drop hazard
+
+Legacy `sanitizeContexts` drops any key with `len(key.encode('utf-8')) > 256`.
+Adding the `ov_s:` prefix (5 bytes) to a context key creates a key of
+`len(context_id) + 5` bytes. If the original context key is at or near
+the 256-byte limit, the prefixed override key exceeds it and is silently
+dropped by legacy sanitization.
+
+In practice, context keys are UUIDs (36 bytes), hex event IDs (64-68 bytes),
+or thread IDs (71 bytes) — all well under 256 bytes. The longest common
+override key (`ov_b:thread:` + 64-hex = 76 bytes) has 180 bytes of
+headroom. This hazard is theoretical but should be documented in the spec.
+
+### 10,000-key validation limit
+
+Legacy `isValidBlob` rejects blobs with >10,000 context keys. Live
+override keys consume 3 entries per overridden context; a compacted
+(tombstoned) override consumes 1:
+
+| Overridden contexts | Live override keys | Typical frontier keys | Total | Headroom |
+|--------------------|---------------------|-----------------------|-------|----------|
+| 50 | 150 | ~500 | 650 | 93.5% |
+| 100 | 300 | ~1,000 | 1,300 | 87% |
+| 500 | 1,500 | ~2,000 | 3,500 | 65% |
+| 3,000 | 9,000 | ~1,000 | 10,000 | 0% (limit) |
+
+The 32 KiB byte budget is the binding constraint long before key count.
+
+### Compaction behavior (tombstone-floor, policy-dependent)
+
+**Revision note:** the prior "compacts to zero" design (delete-on-
+dominance: a dead register was dropped entirely, 0 keys) is retracted.
+Thufir's pass-3 review found a stale-replay resurrection: dropping all
+`(S,C)` state made counters reusable, so a new local set/clear pair
+restarting from `S=0,C=0` could be dominated by a delayed stale peer
+snapshot on replay (`RegB(3,0,10)` → compact → `None` → local
+set+clear → `RegB(1,2,20)` → stale replay merges in → `RegB(3,2,20)`,
+`S>C`, resurrected). Fixed by a tombstone floor: any register with
+recorded activity (S>0 or C>0) is *never* fully deleted — dead state
+compacts to `RegB(0, max(S,C), 0)` instead of `None`. Only a virgin
+register (never set, S==0 and C==0) has no ceiling to protect and
+compacts to `None`.
+
+**The compaction rule is now uniform across the dead cases — the
+per-branch table collapses to a single test:**
+
+| Condition | Clear-wins | Set-wins |
+|-----------|-----------|----------|
+| `override_set_b(reg)` is True (live) | Do not compact | Do not compact |
+| `override_set_b(reg)` is False and `S>0 or C>0` (dead, ever-active) | Compact to tombstone floor `RegB(0, max(S,C), 0)` | Compact to tombstone floor (same) |
+| `S == 0, C == 0` (virgin, never set) | Drop entirely (`None`) | Drop entirely (same) |
+
+Because `override_set_b` is already policy-aware, "live" vs. "dead"
+differs by policy exactly where it did before (`S == C, S > 0` is dead
+under clear-wins, live under set-wins) — the tombstone floor rule itself
+does not need to branch on policy; `compact_b` calls `override_set_b`
+once and only tombstones the false branch.
+
+Under clear-wins, a dead override compacts to the ~45-byte tombstone
+(one `ov_c:` key, channel context) — **not** to zero, because `C` must
+persist as the reuse-blocking ceiling. Under set-wins, `S == C` overrides
+remain live and are never compacted (3 keys, ~138 bytes for channel
+contexts) — unchanged from the prior revision.
+
+**Proof obligation closed (same-device replay):**
+`exhaustive.py::test_deep_history_compaction` (672-point parameter
+cube) and `test_tombstone_stale_merge_direct` verify no resurrection
+and no loss of a genuinely-live override across the compact →
+new-action → delayed-stale-delivery shape, for both tie policies.
+`mutation.py::mutant_m4`
+reverts to the old delete-on-dominance rule and reproduces the exact
+resurrection witness (`final_reg=RegB(s=3, c=2, b=20)`,
+`override_is_set=True`) — confirming the suite would have caught the
+defect this round was opened to fix.
+
+**Proof obligation closed (cross-device transparency, requalified —
+suppress-only, not zero-divergence):**
+`exhaustive.py::test_cross_device_compaction_suppression` (312-point
+cube: stale ancestor `(S,C,B)` × post-compaction frontier × 4
+fresh-frontier values on the receiving device × 2 tie policies) proves
+every divergence between "receive the tombstone" and "receive the
+uncompacted ancestor" is a suppression of an unrelated device's live
+set — never a resurrection — and that every suppression recovers with
+one more local mark-unread and stays recovered after re-receiving the
+same tombstone. `test_tombstone_merge_monotonic` proves the direction
+structurally (not just over the bounded cube): merging in a tombstone
+`RegB(0, k, 0)` for any ceiling `k` can only raise the receiving
+register's `C`, never its `S` or `B`, so it can only weaken — never
+strengthen — the receiving register's live/dead standing under
+`override_set_b`. Together these close the compaction-safety proof
+obligation to exactly what it can honestly claim: no resurrection ever,
+one-shot suppression is a known and recoverable false-negative risk
+inherent to the clear-wins/tombstone design, not an unbounded
+correctness gap.
+
+### GC/tombstone behavior
+
+**Override keys with `ov_` prefix (legacy prune):** Legacy
+`pruneStaleContexts` only drops `msg:`/`thread:`-prefixed keys past the
+7-day horizon. Unknown-prefix keys (including `ov_*`) are kept forever:
+
+- **Permanent tombstones:** every override that is ever compacted while
+  dead leaves a permanent `ov_c:` key (~45 bytes, channel context) — this
+  is no longer a "harmless, can shrink to zero" cost; it is a durable
+  floor kept forever to block stale-replay resurrection. This is the
+  direct storage consequence of fixing the CRITICAL above and must be
+  budgeted, not treated as free.
+- **Live overrides:** an override still live (per `override_set_b`)
+  keeps all 3 keys (~138 bytes, channel context) until it becomes dead
+  and is compacted down to the tombstone.
+
+**Alternative: nesting under `msg:`/`thread:` prefixes** — confirmed
+**state-loss hazard**. Legacy prune would delete overrides at the 7-day
+horizon, silently losing active unread markers. Rejected.
+
+### Legacy trim interaction
+
+Legacy `trimContextsToBudget` evicts only `msg:`/`thread:` keys.
+Override `ov_*` keys (including tombstones) are never evicted. Budget
+analysis by context type, worst case (all overrides still live, 3 keys
+each — the tombstone floor only ever *reduces* this cost):
+
+| Overridden contexts | Context type | Live override bytes | With ~10 KiB frontiers | Fits 32 KiB? |
+|--------------------|-------------|----------------|----------------------|-------------|
+| 50 | Channel (UUID) | ~6.9 KiB | ~16.9 KiB | Yes |
+| 100 | Channel (UUID) | ~13.8 KiB | ~23.8 KiB | Yes |
+| 150 | Channel (UUID) | ~20.7 KiB | ~30.7 KiB | Marginal |
+| 50 | Message (hex64) | ~11.9 KiB | ~21.9 KiB | Yes |
+| 100 | Message (hex64) | ~23.7 KiB | ~33.7 KiB | **No** |
+
+At the 100-override cap with every override compacted to its tombstone
+floor instead: ~4.5 KiB (channel contexts, 100 × 45 bytes) — well
+within budget alongside a full frontier set. The permanent-tombstone
+floor from the CRITICAL fix costs storage but is bounded and small; it
+does not change the 32 KiB conclusion below.
+
+**Mitigation:** Upgraded clients should compact aggressively (any dead
+override, not just baseline-dominated ones) and enforce a cap on active
+override count. A cap of 100 channel-context overrides keeps *live*
+override budget under ~14 KiB and *tombstoned* budget under ~4.5 KiB,
+both within the 32 KiB limit alongside a full frontier set.
+
+### Tie policy evidence: clear-wins vs set-wins
+
+Both tie policies pass all invariants. The choice is a product-semantics
+decision:
+
+- **Clear-wins (S == C → read):** If two devices concurrently set and
+  clear the same context, the result is "read." Conservative — no
+  spurious unread badges. Matches the "I already read this" signal being
+  more definitive than the "remind me" signal. Compaction advantage:
+  `S == C` states are compactable.
+- **Set-wins (S == C → unread):** Concurrent set and clear results in
+  "unread." Preserves the reminder intent. Risk: a user who reads on one
+  device while another has a stale mark-unread gets a persistent badge
+  they can't clear without an explicit action. Compaction disadvantage:
+  `S == C` states are live and cannot be compacted.
+
+**Recommendation:** Clear-wins. A false negative (missing badge) is
+recovered by re-marking unread. A false positive (badge that won't clear)
+is more frustrating. This matches Slack's behavior: reading anywhere
+clears everywhere. The compaction advantage further favors clear-wins.
+
+**Pre-existing false-negative risk (independent of compaction).** Under
+clear-wins, a stale explicit clear (`RegB(0,1,0)`, no compaction
+involved) merging into a device with a fresh concurrent set
+(`RegB(1,0,30)`) already produces `RegB(1,1,30)`, tied, suppressed —
+verified directly by evaluating `merge_reg_b`/`override_set_b` on those
+two registers with no `compact_b` call anywhere in the path. The
+cross-device tombstone-suppression finding (I5d, "Compaction behavior"
+above) is the same tie shape reached via a different route: a
+baseline-dominated *dead set* (never explicitly cleared) that gets
+compacted to a `C`-ceiling tombstone, which is then globally comparable
+in a way its pre-compaction, frontier-relative death was not. Compaction
+widens the set of histories that can reach the tie, but clear-wins
+already accepted this one-shot, re-mark-recoverable false-negative shape
+as its stated tradeoff.
+
+### Multi-slot union
+
+Production splits blobs across up to 8 slots (`READ_STATE_MAX_SLOTS`).
+`mergeReadStateEvents` merges all slots with per-context `max()`. Override
+sibling keys are individual context entries and follow the same merge path.
+
+**Atomic slot-grouping rule (spec-amendment requirement):** a context's
+frontier entry and ALL of its `ov_*` sibling entries MUST travel in the
+same slot, including during slot growth/rebalancing. This is the transport
+half of the same closure property as mandatory canonical publication:
+
+- Without it, an observer holding only a slot containing `ov_s:ctx` (but
+  not `ov_b:ctx`) reconstructs `RegB(s=1, c=0, b=0)` — baseline-dead at
+  any nonzero frontier — and canonically publishes tombstone `RegB(0,1,0)`.
+  After full eventual delivery of all original slots plus that transient
+  tombstone, the merged result is `RegB(s=1, c=1, b=10)` — dead under
+  clear-wins — permanently suppressing a live override.
+- With the rule, a receiver always sees either the complete register group
+  or none of it; partial reconstruction is structurally impossible from a
+  compliant publisher's output.
+
+Implementation: amend `splitContextsIntoBudgetedSlots` to round-robin
+per-context groups (frontier key + all `ov_*` sibling keys for that context)
+rather than per-entry. `DeviceB.split_blob_into_slots` in `model.py` models
+this correctly.
+
+**Unescape-before-group rule (corollary — spec-amendment requirement):**
+When grouping context entries, a frontier wire key MUST be unescaped to its
+raw logical context ID before being used as the group key. A raw context ID
+starting with a reserved prefix (e.g. `ov_s:evil`) escapes to
+`esc:ov_s:evil` as its frontier wire key, while its `ov_*` siblings are
+keyed by the raw suffix (`ov_s:evil`). Without unescaping the frontier key
+before grouping, these resolve to different groups and the register splits
+across slots — reproducing the same partial-reconstruction poison across
+publication cycles via old/new slot-coordinate mixtures. Fix: derive group
+identity via `unescape_context_key(wire_key)` for frontier keys.
+`mutation.py::mutant_m9` reverts to escaped-key grouping and confirms
+`test_escaped_context_slot_grouping` catches the witness.
+
+`mutation.py::mutant_m8` reverts to per-entry splitting (M8's split puts
+frontier+`ov_s:` in slot 0 and `ov_b:`+`ov_c:` in slot 1) and confirms
+`test_interleaved_delivery_grouping` catches Thufir's exact witness.
+
+This rule carries the same normative weight as mandatory canonical publication:
+both are protocol requirements for any client implementing this override layer,
+not optional optimizations.
+
+Confirmed: splitting a published blob across 2 grouped slots and delivering
+each separately produces the same final override and frontier state as
+delivering the full blob, regardless of delivery order. Interleaved-delivery
+test (`test_interleaved_delivery_grouping`) additionally verifies that
+receive-one-slot → re-publish → receive-rest permutations, including delayed
+transient delivery to a third observer, preserve the live override verdict.
+
+## Mutation harness
+
+9 mutants, all caught with recorded counterexamples:
+
+| Mutant | Rule dropped | Counterexample |
+|--------|-------------|----------------|
+| M1 | Baseline dominance check | `RegB(1,0,10)` at frontier=100: correct=inactive, mutant=active (stale set persists) |
+| M2 | `max(S,C)+1` counter bump | After set→set→clear: correct `RegB(2,3,10)` (clear wins), mutant `RegB(2,1,10)` (set persists) |
+| M3 | Tie policy | `RegB(1,1,10)` at frontier=10: clear-wins=False, set-wins=True |
+| M4 | Tombstone-floor compaction (delete-on-dominance revert) | `RegB(3,0,10)` at frontier=20 compacts to `None` (vs. tombstone `RegB(0,3,0)`); local set+clear reuses counters from zero; delayed stale replay resurrects — `final_reg=RegB(s=3,c=2,b=20)`, `override_is_set=True` (reproduces Thufir's pass-3 CRITICAL) |
+| M5 | uint32 value range | Value 4,294,967,296 rejected by legacy sanitization |
+| M6 | Componentwise-max merge | LWW delivery-order-dependent: convergence breaks under permutation |
+| M7 | Canonical publication (raw register serialization) | `RegB(3,2,0)`@frontier-50 join `RegB(1,2,100)`@frontier-100 = live `RegB(3,2,100)` (reproduces Thufir's pass-1/2 CRITICAL dead+dead resurrection) |
+| M8 | Atomic slot-grouping rule (per-entry split) | Live `RegB(1,0,10)` at frontier=10 split as `{frontier+ov_s:}` / `{ov_b:+ov_c:}`; partial observer reconstructs `RegB(1,0,0)`, publishes tombstone `RegB(0,1,0)`; final merge = `RegB(1,1,10)` → inactive (reproduces Thufir's pass-2/2 CRITICAL transport witness) |
+| M9 | Unescape-before-group rule (escaped-key grouping) | Live override on raw ctx `ov_s:evil` (frontier wire key `esc:ov_s:evil`); escaped-key grouping splits frontier from `ov_*` siblings; old/new slot-coordinate mixture → `RegB(1,0,0)` → tombstone `RegB(0,1,0)` → final merge = `RegB(1,1,10)` → inactive (reproduces Thufir's round-2 CRITICAL) |
+
+Each mutant is injected into the model via DeviceB subclass (M1, M2, M4,
+M6, M7, M8, M9) or direct function evaluation (M3, M5), then the applicable
+invariant suite is rerun. M4 reverts to the pre-fix delete-on-dominance
+compaction rule and directly reproduces Thufir's pass-3 CRITICAL resurrection
+witness — the exact `RegB(3,0,10)` → `None` → counter-reuse → stale
+replay → `RegB(3,2,20)`,`override_is_set=True` sequence — with a
+fallback to the directed deep-history cube (`test_deep_history_compaction`)
+if the hand-built scenario doesn't trigger under a given tie policy. M7
+reverts `publish_blob` to raw serialization and reproduces Thufir's pass-1/2
+CRITICAL dead+dead resurrection. M8 reverts `split_blob_into_slots` to
+per-entry assignment (frontier+`ov_s:` / `ov_b:`+`ov_c:`) and reproduces
+Thufir's pass-2/2 CRITICAL transport witness via `test_interleaved_delivery_grouping`.
+M9 reverts `split_blob_into_slots` to escaped-key grouping (groups frontier by
+its wire key instead of its unescaped logical ID) and reproduces Thufir's
+round-2 CRITICAL for escaped contexts via `test_escaped_context_slot_grouping`.
+
+## Recommendation
+
+**Candidate B (two grow-only counters + baseline) with clear-wins tie
+policy.**
+
+Evidence:
+
+1. **Legacy safety:** B's sibling keys survive legacy rewrite; A's
+   top-level field is erased. Hard blocker for A — no migration path
+   tolerates a single legacy device.
+2. **Identity-free:** B needs no client_id for correctness; A's
+   tiebreak creates a reinstall fragility.
+3. **CRDT properties:** Candidate B passes all merge invariants (I2–I8) in
+   the exhaustive model. Candidate A's join is also correct algebraically
+   (I1, I9), but I2–I4 and I6 are not exercised for A — A is dead on I7
+   regardless. B's componentwise max is simpler and more standard.
+4. **Bytes:** B at 3 live keys costs 138 bytes/context (channel UUID) to
+   243 bytes/context (thread hex64); a dead override compacts to a single
+   ~45-80 byte tombstone key instead. Cap of 100 overrides stays within
+   32 KiB budget for both live and tombstoned cases.
+5. **Compaction:** B supports safe policy-aware compaction — no
+   resurrection, ever (proved structurally, not just over a bounded
+   cube). Clear-wins allows compacting `S == C` states (set-wins does
+   not). Cross-device delivery of a tombstone can one-shot suppress an
+   unrelated device's concurrent fresh set whose counters are at or
+   below the tombstone's ceiling; this is recoverable by re-marking and
+   is the same false-negative shape clear-wins already accepts for a
+   stale explicit clear with no compaction involved (see "Tie policy
+   evidence").
+6. **Tie policy:** Clear-wins avoids persistent false-positive badges
+   and enables more aggressive compaction.
+
+## Honest limits
+
+- The model enumerates bounded abstract operations, not real encrypted
+  NIP-59 payloads or relay replacement semantics.
+- Counter values in the general BFS explorer are bounded by its exploration
+  depth (max ~4 via BFS depth 4); the directed deep-history cube
+  (`test_deep_history_compaction`) reaches counter values up to the stale
+  parameter range (0-3) plus post-compaction action sequences, covering the
+  ~9-transition witness the BFS explorer cannot structurally reach. Real
+  uint32 overflow/wrap is tested only via the legacy sanitization mutant (M5).
+- The BFS explorer (I5/I5c) checks compaction safety over reachable
+  multi-device histories up to depth 4, but its own terminal-state
+  compaction check (`check_compaction_safety`) only merges a device's
+  compacted register with its *own* pre-compaction snapshot — it does
+  not, by construction, exercise an unrelated device's independently-
+  live concurrent register. `test_cross_device_compaction_suppression`
+  (I5d) covers that shape directly but over a hand-parameterized cube,
+  not the full BFS state space; the accompanying
+  `test_tombstone_merge_monotonic` lemma is what extends the
+  no-resurrection guarantee beyond the cube's specific points.
+- Two contexts are modeled. Production users may have hundreds of contexts,
+  but the CRDT properties are per-context — cross-context interactions are
+  limited to the shared byte budget (tested via trim/prune interaction).
+- Multi-slot behavior is confirmed via split+merge convergence test, and
+  the atomic slot-grouping rule is modeled by `DeviceB.split_blob_into_slots`
+  (including the escaped-context identity fix — `split_blob_into_slots`
+  unescapes frontier keys before grouping). The production TypeScript
+  implementation (`splitContextsIntoBudgetedSlots`) is NOT modeled — only
+  the abstract grouping property is verified here. Implementation-level
+  testing is still needed for slot placement, slot rebalancing, and the
+  production d-tag coordinate assignment.
+- The model assumes eventual delivery (all blobs eventually reach all
+  devices). Permanent message loss is not modeled.
+- Byte sizes are computed from JSON serialization of realistic key names.
+  Actual encrypted blob overhead (NIP-59 envelope, relay metadata) adds
+  to the total but does not affect the 32 KiB plaintext budget.
diff --git a/docs/formal/nip-rs-unread/exhaustive.py b/docs/formal/nip-rs-unread/exhaustive.py
new file mode 100644
index 0000000000..82d54c6b43
--- /dev/null
+++ b/docs/formal/nip-rs-unread/exhaustive.py
@@ -0,0 +1,1486 @@
+"""Bounded transition-system explorer for NIP-RS manual-unread candidates.
+
+BFS over canonical global states. At each depth, enabled transitions are
+local actions and message deliveries, interleaved — not phased.
+
+Universe: 2 upgraded devices + 1 legacy device, 2 contexts.
+Transitions: mark_unread, mark_read (with frontier advance),
+  advance_frontier, compact, reinstall, deliver (including
+  duplicate/replay). Legacy rewrite semantics are exercised through the
+  deliver path (legacy_sanitize_and_publish), not as a separate
+  transition — a legacy device never mutates its own state outside
+  delivery, so a dedicated no-op transition added nothing (see NOTE.md).
+
+Invariants:
+  I1  merge_reg_b associative/commutative/idempotent
+  I2  convergence: all delivery orders -> identical override verdict
+  I3  no frontier regression
+  I4  concurrent set/clear winner stable (order-independent, ancestor-independent)
+  I5  compaction: no loss of live set, no resurrection of dead clear,
+      survives merge with stale pre-compaction state
+  I5c directed deep-history: compact -> new local actions (counter reuse)
+      -> delayed stale delivery does not resurrect a dead override or
+      lose a genuinely-live one. Scope: the compacting device's own
+      pre-compaction ancestor (or an exact copy of it) replayed back to
+      that same device.
+  I5d cross-device compaction transparency (requalified, NOT
+      zero-divergence): a tombstone's counter ceiling can one-shot
+      suppress an unrelated device's concurrent fresh set with no
+      resurrection, and the suppression is always recoverable by one
+      more local action. Proven suppress-only direction via a bounded
+      witness cube plus a structural monotonicity argument.
+  I6  replay harmless
+  I7  legacy rewrite: B sibling keys survive / A overrides erased (witness)
+  I8  bounded key growth per context
+  I9  DeviceA post-receive counter absorption
+"""
+from itertools import permutations
+from copy import deepcopy
+from model import (
+    RegB, merge_reg_b, override_set_b, compact_b,
+    RegA, merge_reg_a,
+    DeviceB, DeviceA,
+    SET, CLEAR,
+    legacy_prune, legacy_trim, legacy_sanitize_blob,
+    escape_context_key, unescape_context_key, ESCAPE_PREFIX,
+)
+
+CONTEXTS = ("c0", "c1")
+FRONTIER_VALS = (10, 20)
+
+
+# ---------------------------------------------------------------------------
+# I1: algebraic properties
+# ---------------------------------------------------------------------------
+
+def test_merge_algebra_b():
+    vals = [0, 1, 2, 3]
+    regs = [RegB(s, c, b) for s in vals for c in vals for b in vals]
+    violations = []
+    for a in regs:
+        if merge_reg_b(a, a) != a:
+            violations.append(("idempotent", a))
+    for a in regs:
+        for b in regs:
+            if merge_reg_b(a, b) != merge_reg_b(b, a):
+                violations.append(("commutative", a, b))
+    for a in regs:
+        for b in regs:
+            for c in regs:
+                if merge_reg_b(merge_reg_b(a, b), c) != merge_reg_b(a, merge_reg_b(b, c)):
+                    violations.append(("associative", a, b, c))
+    return violations
+
+
+def test_merge_algebra_a():
+    vals = [0, 1, 2]
+    tiebreaks = ["a", "b"]
+    ops = [SET, CLEAR]
+    baselines = [0, 10]
+    regs = [RegA(ct, t, o, bl)
+            for ct in vals for t in tiebreaks for o in ops for bl in baselines]
+    violations = []
+    for tie_op in [CLEAR, SET]:
+        for a in regs:
+            if merge_reg_a(a, a, tie_op) != a:
+                violations.append(("idempotent", tie_op, a))
+        for a in regs:
+            for b in regs:
+                if merge_reg_a(a, b, tie_op) != merge_reg_a(b, a, tie_op):
+                    violations.append(("commutative", tie_op, a, b))
+        for a in regs:
+            for b in regs:
+                for c in regs:
+                    ab_c = merge_reg_a(merge_reg_a(a, b, tie_op), c, tie_op)
+                    a_bc = merge_reg_a(a, merge_reg_a(b, c, tie_op), tie_op)
+                    if ab_c != a_bc:
+                        violations.append(("associative", tie_op, a, b, c))
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# BFS state explorer — Candidate B
+# ---------------------------------------------------------------------------
+
+def next_frontier(device, ctx):
+    cur = device.effective_frontier(ctx)
+    for fv in FRONTIER_VALS:
+        if fv > cur:
+            return fv
+    return None
+
+
+def enabled_transitions(devices, tie_policy):
+    """Generate (kind, args) tuples for all enabled transitions."""
+    trans = []
+    for di, d in enumerate(devices):
+        for ctx in CONTEXTS:
+            if not d.is_legacy:
+                trans.append(("mark_unread", di, ctx))
+                fv = next_frontier(d, ctx)
+                if fv is not None:
+                    trans.append(("mark_read", di, ctx, fv))
+                if ctx in d.overrides:
+                    trans.append(("compact", di, ctx))
+            fv = next_frontier(d, ctx)
+            if fv is not None:
+                trans.append(("advance", di, ctx, fv))
+        if not d.is_legacy:
+            trans.append(("reinstall", di))
+    for si in range(len(devices)):
+        for di in range(len(devices)):
+            if si != di:
+                trans.append(("deliver", si, di))
+    return trans
+
+
+def apply_transition(devices, t, tie_policy):
+    kind = t[0]
+    if kind == "mark_unread":
+        devices[t[1]].do_mark_unread(t[2])
+    elif kind == "mark_read":
+        devices[t[1]].do_mark_read(t[2], t[3])
+    elif kind == "advance":
+        devices[t[1]].do_advance_frontier(t[2], t[3])
+    elif kind == "compact":
+        devices[t[1]].do_compact(t[2], tie_policy)
+    elif kind == "reinstall":
+        devices[t[1]].do_reinstall()
+    elif kind == "deliver":
+        src = devices[t[1]]
+        dst = devices[t[2]]
+        if src.is_legacy:
+            blob = src.legacy_sanitize_and_publish(tie_policy)
+        else:
+            blob = src.publish_blob(tie_policy)
+        dst.receive_merge(blob)
+
+
+def state_sig(devices, tie_policy):
+    return tuple(d.state_key(CONTEXTS, tie_policy) for d in devices)
+
+
+def check_convergence(devices, tie_policy, trace, violations):
+    """Publish all blobs, deliver in every order, check upgraded devices
+    converge on override_is_set for each context.
+
+    Tests with latest_ts=5 (below all frontiers) so the override is the
+    sole unread source — no masking by natural unread.
+    """
+    blobs = []
+    for d in devices:
+        if d.is_legacy:
+            blobs.append(d.legacy_sanitize_and_publish(tie_policy))
+        else:
+            blobs.append(d.publish_blob(tie_policy))
+
+    verdicts_per_order = []
+    for perm in permutations(range(len(blobs))):
+        receivers = deepcopy(devices)
+        for idx in perm:
+            for r in receivers:
+                r.receive_merge(blobs[idx])
+        per_device = []
+        for r in receivers:
+            if not r.is_legacy:
+                per_device.append(
+                    tuple(r.override_is_set(ctx, tie_policy) for ctx in CONTEXTS)
+                )
+        verdicts_per_order.append(tuple(per_device))
+
+    if len(set(verdicts_per_order)) > 1:
+        violations.append(("I2-convergence", trace, set(verdicts_per_order)))
+
+
+def check_compaction_safety(devices, tie_policy, trace, violations):
+    """For each upgraded device with overrides:
+    1. Check override_is_set directly (not via verdict/latest_ts).
+    2. Compact and verify override_is_set unchanged.
+    3. Merge compacted state with stale pre-compaction state in both orders.
+       Verify no resurrection and no loss.
+    """
+    for di, d in enumerate(devices):
+        if d.is_legacy:
+            continue
+        for ctx in CONTEXTS:
+            reg = d.overrides.get(ctx)
+            if reg is None:
+                continue
+            front = d.effective_frontier(ctx)
+            ov_before = d._override_set(reg, front, tie_policy)
+            compacted = d._compact(reg, front, tie_policy)
+            ov_after = d._override_set(compacted, front, tie_policy) if compacted else False
+
+            if ov_before and not ov_after:
+                violations.append((
+                    "I5-compaction-lost-set", trace, di, ctx,
+                    reg, compacted, front, tie_policy
+                ))
+            if not ov_before and ov_after:
+                violations.append((
+                    "I5-compaction-resurrection", trace, di, ctx,
+                    reg, compacted, front, tie_policy
+                ))
+
+            if compacted is not None:
+                for merged in [merge_reg_b(compacted, reg), merge_reg_b(reg, compacted)]:
+                    ov_merged = d._override_set(merged, front, tie_policy)
+                    if not ov_before and ov_merged:
+                        violations.append((
+                            "I5-compaction-merge-resurrection", trace, di, ctx,
+                            reg, compacted, merged
+                        ))
+
+
+def explore_b(max_depth=4, tie_policy=CLEAR, device_cls=DeviceB):
+    """BFS over all reachable global states up to max_depth.
+
+    Returns (states_explored, violations).
+    Accepts device_cls for mutation testing via subclassing.
+    """
+    def make_devices():
+        return [
+            device_cls("d0", is_legacy=False),
+            device_cls("d1", is_legacy=False),
+            device_cls("d2", is_legacy=True),
+        ]
+
+    violations = []
+    seen = set()
+    states_explored = 0
+    queue = [(make_devices(), [])]
+
+    while queue:
+        devices, trace = queue.pop(0)
+        sig = state_sig(devices, tie_policy)
+        if sig in seen:
+            continue
+        seen.add(sig)
+        states_explored += 1
+
+        for di, d in enumerate(devices):
+            for ctx in CONTEXTS:
+                prev_front = d.effective_frontier(ctx)
+                if prev_front < 0:
+                    violations.append(("I3-frontier-negative", trace, di, ctx))
+
+        if len(trace) >= max_depth:
+            check_convergence(devices, tie_policy, trace, violations)
+            check_compaction_safety(devices, tie_policy, trace, violations)
+            continue
+
+        for t in enabled_transitions(devices, tie_policy):
+            new_devs = deepcopy(devices)
+            fronts_before = {
+                (di, ctx): d.effective_frontier(ctx)
+                for di, d in enumerate(new_devs) for ctx in CONTEXTS
+            }
+            apply_transition(new_devs, t, tie_policy)
+
+            # Reinstall intentionally wipes local state; frontier regression
+            # is only invalid during merge/delivery/compaction/advance.
+            if t[0] != "reinstall":
+                for (di, ctx), fb in fronts_before.items():
+                    fa = new_devs[di].effective_frontier(ctx)
+                    if fa < fb:
+                        violations.append(("I3-frontier-regression", trace + [t], di, ctx, fb, fa))
+
+            queue.append((new_devs, trace + [t]))
+
+    return states_explored, violations
+
+
+# ---------------------------------------------------------------------------
+# I4: concurrent set/clear winner stable
+# ---------------------------------------------------------------------------
+
+def test_concurrent_stability(device_cls=DeviceB):
+    """Two devices concurrently set and clear from every possible ancestor state.
+    The winner must be the same regardless of delivery order AND ancestor state."""
+    violations = []
+    for tie_policy in [CLEAR, SET]:
+        for pre_s, pre_c in [(0, 0), (1, 0), (0, 1), (2, 1), (1, 2), (1, 1)]:
+            for front in [0, 10]:
+                for ctx in CONTEXTS:
+                    ancestor = RegB(s=pre_s, c=pre_c, b=front)
+
+                    d0 = device_cls("d0")
+                    d0.frontier[ctx] = front
+                    d0.overrides[ctx] = deepcopy(ancestor)
+                    d1 = device_cls("d1")
+                    d1.frontier[ctx] = front
+                    d1.overrides[ctx] = deepcopy(ancestor)
+
+                    d0.do_mark_unread(ctx)
+                    d1.do_mark_read(ctx, front + 10)
+
+                    blob0 = d0.publish_blob(tie_policy)
+                    blob1 = d1.publish_blob(tie_policy)
+
+                    verdicts = set()
+                    for first, second in [(blob0, blob1), (blob1, blob0)]:
+                        r = device_cls("recv")
+                        r.frontier[ctx] = front
+                        r.overrides[ctx] = deepcopy(ancestor)
+                        r.receive_merge(first)
+                        r.receive_merge(second)
+                        verdicts.add(r.override_is_set(ctx, tie_policy))
+
+                    if len(verdicts) > 1:
+                        violations.append((
+                            "I4-unstable", tie_policy, ctx,
+                            pre_s, pre_c, front
+                        ))
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# I5: direct compaction register-level check (all register values x policies)
+# ---------------------------------------------------------------------------
+
+def test_compaction_register_exhaustive():
+    """Exhaustive check over bounded register cube and frontier values.
+    Tests override_is_set directly — no latest_ts masking."""
+    violations = []
+    vals = [0, 1, 2, 3]
+    frontiers = [0, 10, 20]
+    for tie_policy in [CLEAR, SET]:
+        for s in vals:
+            for c in vals:
+                for b in frontiers:
+                    for fv in frontiers:
+                        reg = RegB(s=s, c=c, b=b)
+                        ov_before = override_set_b(reg, fv, tie_policy)
+                        compacted = compact_b(reg, fv, tie_policy)
+                        ov_after = (override_set_b(compacted, fv, tie_policy)
+                                    if compacted else False)
+
+                        if ov_before and not ov_after:
+                            violations.append((
+                                "loss", tie_policy, reg, fv, compacted
+                            ))
+                        if not ov_before and ov_after:
+                            violations.append((
+                                "resurrection", tie_policy, reg, fv, compacted
+                            ))
+
+                        if compacted is not None:
+                            merged_fwd = merge_reg_b(compacted, reg)
+                            merged_rev = merge_reg_b(reg, compacted)
+                            for label, merged in [("fwd", merged_fwd), ("rev", merged_rev)]:
+                                ov_merged = override_set_b(merged, fv, tie_policy)
+                                if not ov_before and ov_merged:
+                                    violations.append((
+                                        f"merge-resurrection-{label}",
+                                        tie_policy, reg, fv, compacted, merged
+                                    ))
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# I5c: directed deep-history — compact -> new actions (counter reuse) ->
+# delayed stale delivery (including split across two slots)
+# ---------------------------------------------------------------------------
+
+def _apply_action_seq(dev, ctx, seq, ts):
+    for a in seq:
+        if a == "set":
+            dev.do_mark_unread(ctx)
+        else:
+            dev.do_mark_read(ctx, ts)
+
+
+def _ancestor_ctx_dict(ctx, reg):
+    return {f"ov_s:{ctx}": reg.s, f"ov_c:{ctx}": reg.c, f"ov_b:{ctx}": reg.b}
+
+
+_DEEP_HISTORY_ACTION_SEQS = [
+    (), ("set",), ("clear",), ("set", "clear"), ("clear", "set"),
+    ("set", "set"), ("clear", "clear"),
+]
+# One delivery shape: single unsplit blob.  The prior "split_fwd"/"split_rev"
+# shapes are no longer distinct — with the atomic-grouping rule a single-
+# context blob's compliant split puts the whole group in one slot and the
+# other empty, making split_fwd and split_rev semantically identical to
+# single.  Keeping only one shape avoids 2/3 duplicate executions (2,016 →
+# 672 meaningful points) while losing zero register-level coverage.
+_DEEP_HISTORY_DELIVERY_SHAPES = ("single",)
+
+
+def test_deep_history_compaction(device_cls=DeviceB):
+    """Directed check over the exact shape a depth-4 BFS structurally
+    cannot reach (~9 transitions): compact -> new local set/clear actions
+    (counter reuse against the tombstone floor) -> delayed delivery of
+    the pre-compaction stale ancestor, including split across 2 slots.
+
+    Oracle: compaction is a storage optimization and must never change
+    the semantic outcome. A reference device that never compacts, given
+    the identical ancestor / frontier advance / action sequence / late
+    ancestor delivery, must reach the same override_is_set verdict as
+    the compacting device. This directly targets Thufir's counterexample
+    (RegB(3,0,10) -> None under delete-on-dominance -> counter reuse ->
+    RegB(3,2,20) resurrection) and requires the tombstone floor from
+    compact_b to hold under it.
+
+    Returns (cube_size, violations).
+    """
+    violations = []
+    cube_size = 0
+    ctx = "c0"
+    stale_vals = (0, 1, 2, 3)
+    baselines = (0, 10)
+    post_frontiers = (10, 20)
+
+    for s0 in stale_vals:
+        for c0 in stale_vals:
+            for b0 in baselines:
+                for f1 in post_frontiers:
+                    if f1 <= b0:
+                        continue  # not a dominance/compaction scenario
+                    ancestor = RegB(s=s0, c=c0, b=b0)
+                    ancestor_blob = _ancestor_ctx_dict(ctx, ancestor)
+                    for seq in _DEEP_HISTORY_ACTION_SEQS:
+                        for tie_policy in (CLEAR, SET):
+                            for shape in _DEEP_HISTORY_DELIVERY_SHAPES:
+                                cube_size += 1
+
+                                dev = device_cls("d0")
+                                dev.frontier[ctx] = b0
+                                dev.overrides[ctx] = ancestor
+                                dev.do_advance_frontier(ctx, f1)
+                                dev.do_compact(ctx, tie_policy)
+                                _apply_action_seq(dev, ctx, seq, f1)
+
+                                if shape == "single":
+                                    dev.receive_merge({"contexts": dict(ancestor_blob)})
+                                ov_after = dev.override_is_set(ctx, tie_policy)
+
+                                ref = device_cls("ref")
+                                ref.frontier[ctx] = b0
+                                ref.overrides[ctx] = ancestor
+                                ref.do_advance_frontier(ctx, f1)
+                                _apply_action_seq(ref, ctx, seq, f1)
+                                ref.receive_merge({"contexts": dict(ancestor_blob)})
+                                ov_ref = ref.override_is_set(ctx, tie_policy)
+
+                                if ov_after != ov_ref:
+                                    violations.append((
+                                        "I5c-deep-history-divergence", tie_policy, shape,
+                                        ancestor, f1, seq,
+                                        f"compacted_path={ov_after}", f"reference={ov_ref}",
+                                    ))
+    return cube_size, violations
+
+
+def test_tombstone_stale_merge_direct():
+    """Tombstone floor merged directly with its own pre-compaction stale
+    ancestor (no intervening local actions) must not resurrect and must
+    not exceed the ancestor's own verdict."""
+    violations = []
+    vals = (0, 1, 2, 3)
+    frontiers = (0, 10, 20)
+    for tie_policy in (CLEAR, SET):
+        for s in vals:
+            for c in vals:
+                for b in frontiers:
+                    for fv in frontiers:
+                        if fv <= b:
+                            continue
+                        reg = RegB(s=s, c=c, b=b)
+                        compacted = compact_b(reg, fv, tie_policy)
+                        if compacted is None:
+                            continue  # virgin register: nothing to tombstone
+                        ov_before = override_set_b(reg, fv, tie_policy)
+                        for merged in (merge_reg_b(compacted, reg), merge_reg_b(reg, compacted)):
+                            ov_merged = override_set_b(merged, fv, tie_policy)
+                            if not ov_before and ov_merged:
+                                violations.append((
+                                    "tombstone-stale-merge-resurrection",
+                                    tie_policy, reg, fv, compacted, merged,
+                                ))
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# I5d: cross-device compaction transparency (requalified — suppress-only,
+# NOT zero-divergence) + re-mark recovery
+# ---------------------------------------------------------------------------
+
+def test_tombstone_merge_monotonic():
+    """Structural lemma: merging in ANY tombstone RegB(0, k, 0) is a
+    monotonically non-increasing function of the ceiling k in
+    override_set_b's boolean output, for a fixed receiving register and
+    frontier. A tombstone only ever adds to C (its S and B are both 0,
+    so max() with any receiving register leaves that register's own S
+    and B untouched) — raising C can only weaken S's relative standing,
+    never strengthen it. This is what makes resurrection structurally
+    impossible and suppression the only possible direction, independent
+    of any bounded cube.
+    """
+    violations = []
+    vals = (0, 1, 2, 3)
+    baselines = (0, 10, 20)
+    ceilings = (0, 1, 2, 3, 4, 5)
+    for tie_policy in (CLEAR, SET):
+        for s in vals:
+            for c in vals:
+                for b in baselines:
+                    for fv in baselines:
+                        x_reg = RegB(s=s, c=c, b=b)
+                        prev = None
+                        for k in ceilings:
+                            merged = merge_reg_b(x_reg, RegB(s=0, c=k, b=0))
+                            cur = override_set_b(merged, fv, tie_policy)
+                            if prev is not None and cur and not prev:
+                                violations.append((
+                                    "I5d-non-monotonic-ceiling", tie_policy,
+                                    x_reg, fv, k, merged,
+                                ))
+                            prev = cur
+    return violations
+
+
+def test_cross_device_compaction_suppression(device_cls=DeviceB):
+    """Compaction is NOT semantically transparent cross-device (I5c only
+    covers the same-device replay shape). A tombstone re-encodes
+    baseline-dominated death — frontier-relative, doesn't transfer
+    across devices — as a clear-counter ceiling — globally comparable —
+    so it can one-shot suppress an unrelated device's concurrent fresh
+    set whose own counters don't exceed that ceiling.
+
+    Witness (Paul's report, illustrative — the cube below tests nearby
+    parameter values `f_x` in `(5, 15, 25, 35)`, not the literal
+    `f_x=30` used in the original report; the shape is the same):
+      Y: mark_unread -> RegB(1,0,0); frontier->10 (dead) -> compact ->
+         tombstone RegB(0,1,0)
+      X: offline, fresh mark_unread at frontier 30 -> RegB(1,0,30), LIVE
+      X merges Y's tombstone -> RegB(1,1,30) -> suppressed (clear-wins)
+      Control (Y publishes the uncompacted RegB(1,0,0) instead): X stays
+      RegB(1,0,30), LIVE — the divergence is caused by compaction, not
+      by the merge itself.
+
+    Proves over a bounded cube, both tie policies: every divergence
+    between "X merges Y's tombstone" and "X merges Y's uncompacted
+    ancestor" is a suppression (never a resurrection — that would
+    contradict test_tombstone_merge_monotonic), and every suppression
+    recovers with one more local mark-unread, stable under tombstone
+    replay.
+
+    Returns (cube_size, suppress_count, violations).
+    """
+    violations = []
+    cube_size = 0
+    suppress_count = 0
+    dead_vals = (0, 1, 2, 3)
+    dead_baselines = (0, 10)
+    dead_post_frontiers = (10, 20)
+    fresh_frontiers = (5, 15, 25, 35)
+
+    for tie_policy in (CLEAR, SET):
+        for s_y in dead_vals:
+            for c_y in dead_vals:
+                for b_y in dead_baselines:
+                    for f_y in dead_post_frontiers:
+                        if f_y <= b_y:
+                            continue
+                        ancestor = RegB(s=s_y, c=c_y, b=b_y)
+                        tomb = compact_b(ancestor, f_y, tie_policy)
+                        if tomb is None or tomb == ancestor:
+                            continue  # virgin, or was live (not compacted)
+
+                        for f_x in fresh_frontiers:
+                            cube_size += 1
+                            x_reg = RegB(s=1, c=0, b=f_x)
+                            x_before = override_set_b(x_reg, f_x, tie_policy)
+                            if not x_before:
+                                violations.append((
+                                    "I5d-setup-not-live", tie_policy, x_reg, f_x,
+                                ))
+                                continue
+
+                            ov_tomb = override_set_b(
+                                merge_reg_b(x_reg, tomb), f_x, tie_policy
+                            )
+                            ov_ancestor = override_set_b(
+                                merge_reg_b(x_reg, ancestor), f_x, tie_policy
+                            )
+
+                            if ov_tomb == ov_ancestor:
+                                continue
+                            if ov_tomb and not ov_ancestor:
+                                violations.append((
+                                    "I5d-resurrection-vs-ancestor", tie_policy,
+                                    ancestor, tomb, x_reg, f_x,
+                                ))
+                                continue
+
+                            suppress_count += 1
+                            dev = device_cls("x")
+                            dev.frontier["c0"] = f_x
+                            dev.overrides["c0"] = merge_reg_b(x_reg, tomb)
+                            dev.do_mark_unread("c0")
+                            if not dev.override_is_set("c0", tie_policy):
+                                violations.append((
+                                    "I5d-recovery-failed", tie_policy,
+                                    ancestor, tomb, x_reg, f_x, dev.overrides["c0"],
+                                ))
+                                continue
+                            dev.receive_merge({"contexts": {
+                                "ov_s:c0": tomb.s, "ov_c:c0": tomb.c, "ov_b:c0": tomb.b,
+                            }})
+                            if not dev.override_is_set("c0", tie_policy):
+                                violations.append((
+                                    "I5d-recovery-not-replay-stable", tie_policy,
+                                    ancestor, tomb, x_reg, f_x, dev.overrides["c0"],
+                                ))
+
+    return cube_size, suppress_count, violations
+
+
+# ---------------------------------------------------------------------------
+# New invariant: published-state merge closure (Paul's fix-scope item 2,
+# generalizing Thufir's pass-1/2 CRITICAL — dead+dead merge resurrection)
+# ---------------------------------------------------------------------------
+
+def _dead_register_points(tie_policy):
+    """Bounded cube of (label, reg, frontier) points independently
+    verified DEAD (inactive) under `tie_policy` by the real
+    `override_set_b` predicate — the death cause (baseline dominance,
+    clear-count dominance, or clear-wins tie) is whatever the predicate
+    actually computes for that point, not asserted by construction.
+    """
+    vals = (0, 1, 2, 3)
+    baselines = (0, 10, 50)
+    frontiers = (0, 20, 60, 100)
+    points = []
+    for s in vals:
+        for c in vals:
+            if s == 0 and c == 0:
+                continue  # virgin: not a "dead override" case
+            for b in baselines:
+                for fv in frontiers:
+                    reg = RegB(s=s, c=c, b=b)
+                    if override_set_b(reg, fv, tie_policy):
+                        continue  # live: out of scope for this invariant
+                    points.append((f"s={s}c={c}b={b}fv={fv}", reg, fv))
+    return points
+
+
+def test_published_merge_closure(device_cls=DeviceB):
+    """Over reachable *published* states: joining any two individually-
+    inactive published states must remain inactive.
+
+    This targets Thufir's pass-1/2 CRITICAL directly: a dead register's
+    death cause is frontier-relative (baseline dominance) or
+    device-local-history-relative (clear-count dominance), but the
+    componentwise-max join recombines each register's `S`/`C`/`B`
+    independent of the history that produced them, so two individually-
+    dead registers could — before canonical publication — recombine
+    into a live join. Canonicalizing every override to `RegB(0,
+    max(S,C), 0)` before serialization (this round's CRITICAL fix)
+    folds every dead cause into a single globally-comparable `C`
+    ceiling with `S=0`, which per `test_tombstone_merge_monotonic` can
+    only ever raise a receiver's `C` — never resurrect.
+
+    Checked two ways:
+    - Directed case: Thufir's exact witness pair — `RegB(3,2,0)`
+      inactive via baseline dominance at frontier 50, `RegB(1,2,100)`
+      inactive via clear dominance at frontier 100 — whose raw
+      componentwise join is `RegB(3,2,100)`, live (`S=3>C=2`,
+      `frontier(100) not> B(100)`). Both tie policies.
+    - General search: every pairwise join of a bounded cube of
+      independently-dead `(reg, frontier)` points (see
+      `_dead_register_points`), delivered to a fresh receiver in both
+      direct orders and via a one-hop relay that itself republishes
+      (re-canonicalizes) what it received before forwarding — covering
+      delayed/multi-hop delivery, not just direct pairwise merge.
+
+    Returns (cube_size, violations).
+    """
+    violations = []
+    cube_size = 0
+
+    def _check_pair(tie_policy, label_a, blob_a, label_b, blob_b, tag):
+        nonlocal cube_size
+        cube_size += 1
+        for first, second in [(blob_a, blob_b), (blob_b, blob_a)]:
+            recv = device_cls("recv")
+            recv.receive_merge(first)
+            recv.receive_merge(second)
+            if recv.override_is_set("c0", tie_policy):
+                violations.append((
+                    tag, tie_policy, label_a, label_b, recv.overrides.get("c0"),
+                ))
+        # Multi-hop: a relay receives blob_a alone, republishes
+        # (re-canonicalizes) before forwarding, then the receiver gets
+        # the relayed form plus blob_b directly, in both orders.
+        relay = device_cls("relay")
+        relay.receive_merge(blob_a)
+        relayed = relay.publish_blob(tie_policy)
+        for first, second in [(relayed, blob_b), (blob_b, relayed)]:
+            recv = device_cls("recv_hop")
+            recv.receive_merge(first)
+            recv.receive_merge(second)
+            if recv.override_is_set("c0", tie_policy):
+                violations.append((
+                    tag + "-multihop", tie_policy, label_a, label_b,
+                    recv.overrides.get("c0"),
+                ))
+
+    # --- Directed case: Thufir's exact witness pair. ---
+    for tie_policy in (CLEAR, SET):
+        reg_a, front_a = RegB(s=3, c=2, b=0), 50
+        reg_b, front_b = RegB(s=1, c=2, b=100), 100
+        assert not override_set_b(reg_a, front_a, tie_policy)
+        assert not override_set_b(reg_b, front_b, tie_policy)
+
+        dev_a = device_cls("a")
+        dev_a.frontier["c0"] = front_a
+        dev_a.overrides["c0"] = reg_a
+        dev_b = device_cls("b")
+        dev_b.frontier["c0"] = front_b
+        dev_b.overrides["c0"] = reg_b
+
+        _check_pair(
+            tie_policy, f"thufir-witness-A={reg_a}@{front_a}",
+            dev_a.publish_blob(tie_policy),
+            f"thufir-witness-B={reg_b}@{front_b}",
+            dev_b.publish_blob(tie_policy),
+            "merge-closure-thufir-witness",
+        )
+
+    # --- General search over a bounded cube of dead published states. ---
+    for tie_policy in (CLEAR, SET):
+        points = _dead_register_points(tie_policy)
+        for label_a, reg_a, front_a in points:
+            dev_a = device_cls("a")
+            dev_a.frontier["c0"] = front_a
+            dev_a.overrides["c0"] = reg_a
+            blob_a = dev_a.publish_blob(tie_policy)
+            for label_b, reg_b, front_b in points:
+                dev_b = device_cls("b")
+                dev_b.frontier["c0"] = front_b
+                dev_b.overrides["c0"] = reg_b
+                blob_b = dev_b.publish_blob(tie_policy)
+                _check_pair(
+                    tie_policy, label_a, blob_a, label_b, blob_b,
+                    "merge-closure-cube",
+                )
+
+    return cube_size, violations
+
+
+# ---------------------------------------------------------------------------
+# I6: replay harmless
+# ---------------------------------------------------------------------------
+
+def test_replay_harmless(device_cls=DeviceB):
+    violations = []
+    for tie_policy in [CLEAR, SET]:
+        for ctx in CONTEXTS:
+            d = device_cls("d0")
+            d.frontier[ctx] = 10
+            d.do_mark_unread(ctx)
+            blob = d.publish_blob(tie_policy)
+            state_before = (
+                dict(d.frontier),
+                {k: v for k, v in d.overrides.items()},
+            )
+            d.receive_merge(blob)
+            d.receive_merge(blob)
+            d.receive_merge(blob)
+            state_after = (
+                dict(d.frontier),
+                {k: v for k, v in d.overrides.items()},
+            )
+            if state_before != state_after:
+                violations.append(("I6-replay", tie_policy, ctx))
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# I7: legacy rewrite
+# ---------------------------------------------------------------------------
+
+def test_legacy_rewrite_b():
+    """B's sibling keys survive legacy sanitization (round-trip)."""
+    violations = []
+    for ctx in CONTEXTS:
+        d = DeviceB("d0")
+        d.frontier[ctx] = 10
+        d.do_mark_unread(ctx)
+        blob = d.publish_blob()
+        sanitized = legacy_sanitize_blob(blob)
+
+        recv_orig = DeviceB("recv1")
+        recv_orig.receive_merge(blob)
+        recv_san = DeviceB("recv2")
+        recv_san.receive_merge(sanitized)
+
+        for c in CONTEXTS:
+            if recv_orig.overrides.get(c) != recv_san.overrides.get(c):
+                violations.append(("I7-B-sanitize-mutated", c,
+                                   recv_orig.overrides.get(c),
+                                   recv_san.overrides.get(c)))
+    return violations
+
+
+def test_legacy_erasure_a():
+    """A's top-level overrides field is erased by legacy rewrite. Expected witness."""
+    d = DeviceA("d0")
+    d.frontier["c0"] = 10
+    d.do_mark_unread("c0")
+    blob = d.publish_blob()
+    assert "overrides" in blob
+    legacy_blob = {"v": 1, "client_id": "legacy", "contexts": dict(blob["contexts"])}
+    return "overrides" not in legacy_blob
+
+
+# ---------------------------------------------------------------------------
+# I8: bounded key growth
+# ---------------------------------------------------------------------------
+
+def test_bounded_growth():
+    """I8: bounded key growth, canonical wire shape. A live override
+    (last action = mark_unread, still within baseline) publishes
+    exactly 3 keys/ctx; a dead override (mark_read past baseline, or
+    C > S under clear-wins) canonicalizes to exactly 1 key/ctx
+    (`ov_c:` tombstone) at publish time — never 0 (virgin-only) or 3
+    (dead-but-uncompacted, which the pre-fix serializer allowed).
+    """
+    violations = []
+    for ctx in CONTEXTS:
+        # Live: 100 set/clear round-trips, ending on a fresh mark_unread
+        # so S > C (live under both tie policies) at publish time.
+        d = DeviceB("d0")
+        d.frontier[ctx] = 10
+        for _ in range(100):
+            d.do_mark_unread(ctx)
+            d.do_mark_read(ctx, d.effective_frontier(ctx) + 1)
+        d.do_mark_unread(ctx)
+        blob = d.publish_blob(CLEAR)
+        ov_keys = [k for k in blob["contexts"] if k.startswith("ov_")]
+        if ov_keys != [f"ov_s:{ctx}", f"ov_c:{ctx}", f"ov_b:{ctx}"]:
+            violations.append(("I8-growth-live", ctx, ov_keys))
+
+        # Dead: advance the frontier past baseline B — override_set_b's
+        # baseline-dominance clause forces S dead regardless of S vs C.
+        d.do_advance_frontier(ctx, d.effective_frontier(ctx) + 100)
+        tomb_blob = d.publish_blob(CLEAR)
+        tomb_keys = [k for k in tomb_blob["contexts"] if k.startswith("ov_")]
+        if tomb_keys != [f"ov_c:{ctx}"]:
+            violations.append(("I8-growth-tombstone", ctx, tomb_keys))
+    return violations
+
+
+def test_wire_shape_exact():
+    """Exact wire-shape regression (Paul's fix-scope item 4): a live
+    override serializes to exactly 3 `ov_*` keys, a dead override to
+    exactly 1 (`ov_c:` only, zero-valued `ov_s`/`ov_b` omitted), and a
+    virgin override to exactly 0. Checked directly against
+    `publish_blob`'s output, independent of `do_compact`.
+    """
+    violations = []
+    for tie_policy in (CLEAR, SET):
+        # Live.
+        d_live = DeviceB("d0")
+        d_live.frontier["c0"] = 10
+        d_live.do_mark_unread("c0")
+        live_blob = d_live.publish_blob(tie_policy)
+        live_keys = sorted(k for k in live_blob["contexts"] if k.startswith("ov_"))
+        if live_keys != ["ov_b:c0", "ov_c:c0", "ov_s:c0"]:
+            violations.append(("wire-shape-live", tie_policy, live_keys))
+
+        # Dead (clear-wins only: S==C>0 is dead under CLEAR, live under
+        # SET — use baseline dominance instead so it's dead under both).
+        d_dead = DeviceB("d0")
+        d_dead.frontier["c0"] = 10
+        d_dead.do_mark_unread("c0")
+        d_dead.do_advance_frontier("c0", 100)
+        dead_blob = d_dead.publish_blob(tie_policy)
+        dead_keys = sorted(k for k in dead_blob["contexts"] if k.startswith("ov_"))
+        if dead_keys != ["ov_c:c0"]:
+            violations.append(("wire-shape-tombstone", tie_policy, dead_keys))
+        if dead_blob["contexts"]["ov_c:c0"] != 1:
+            violations.append((
+                "wire-shape-tombstone-ceiling", tie_policy,
+                dead_blob["contexts"]["ov_c:c0"],
+            ))
+
+        # Virgin: no override ever set for this context.
+        d_virgin = DeviceB("d0")
+        d_virgin.frontier["c0"] = 10
+        d_virgin.overrides["c0"] = RegB(s=0, c=0, b=0)
+        virgin_blob = d_virgin.publish_blob(tie_policy)
+        virgin_keys = [k for k in virgin_blob["contexts"] if k.startswith("ov_")]
+        if virgin_keys:
+            violations.append(("wire-shape-virgin", tie_policy, virgin_keys))
+
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# I9: DeviceA counter absorption
+# ---------------------------------------------------------------------------
+
+def test_a_counter_absorption():
+    """After receiving a blob with counter=10, a local action must use counter>10."""
+    d0 = DeviceA("d0")
+    d0.frontier["c0"] = 10
+    d0.counter = 10
+    d0.do_mark_unread("c0")
+    blob0 = d0.publish_blob()
+
+    d1 = DeviceA("d1")
+    d1.frontier["c0"] = 10
+    d1.receive_merge(blob0)
+    assert d1.counter >= 10, f"counter not absorbed: {d1.counter}"
+
+    d1.do_mark_read("c0", 20)
+    reg = d1.overrides.get("c0")
+    assert reg is not None and reg.counter > 10, \
+        f"post-receive clear at counter {reg.counter} would lose to set at 10"
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Identity-free (B): reinstall convergence
+# ---------------------------------------------------------------------------
+
+def test_b_identity_free(device_cls=DeviceB):
+    violations = []
+    for tie_policy in [CLEAR, SET]:
+        for ctx in CONTEXTS:
+            d = device_cls("d0")
+            d.frontier[ctx] = 10
+            d.do_mark_unread(ctx)
+            blob1 = d.publish_blob(tie_policy)
+
+            d_re = device_cls("d0_reinstalled")
+            d_re.receive_merge(blob1)
+            d_re.do_mark_read(ctx, 20)
+            blob2 = d_re.publish_blob(tie_policy)
+
+            verdicts = set()
+            for first, second in [(blob1, blob2), (blob2, blob1)]:
+                recv = device_cls("recv")
+                recv.receive_merge(first)
+                recv.receive_merge(second)
+                verdicts.add(recv.override_is_set(ctx, tie_policy))
+            if len(verdicts) > 1:
+                violations.append(("identity-free", tie_policy, ctx))
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# Legacy prune/trim interaction
+# ---------------------------------------------------------------------------
+
+def test_legacy_prune_interaction():
+    """ov_ keys survive prune; msg:ov_ nested keys would be pruned (state loss)."""
+    base = {"c0": 50, "msg:m1": 30, "thread:t1": 40}
+    ov = {"ov_s:c0": 1, "ov_c:c0": 0, "ov_b:c0": 10}
+    all_keys = {**base, **ov}
+    pruned = legacy_prune(all_keys, horizon=35)
+    ov_survived = all(k in pruned for k in ov)
+    msg_pruned = "msg:m1" not in pruned
+
+    nested = {"msg:ov_s:c0": 1, "msg:ov_c:c0": 0, "msg:ov_b:c0": 10}
+    pruned_nested = legacy_prune({**base, **nested}, horizon=35)
+    nested_lost = any(k not in pruned_nested for k in nested)
+    return ov_survived, msg_pruned, nested_lost
+
+
+def test_legacy_trim_interaction():
+    """Excess override keys block legacy publish when budget exceeded."""
+    contexts = {"c0": 50}
+    for i in range(1000):
+        contexts[f"ov_s:c{i}"] = 1
+        contexts[f"ov_c:c{i}"] = 0
+        contexts[f"ov_b:c{i}"] = 10
+    _, fits = legacy_trim(contexts, "client1", max_bytes=32768)
+    return not fits
+
+
+# ---------------------------------------------------------------------------
+# Multi-slot union
+# ---------------------------------------------------------------------------
+
+def test_multi_slot_union(device_cls=DeviceB):
+    """Split a published blob across 2 slots using the atomic-grouping rule,
+    deliver each slot separately, verify convergence with delivering the full blob.
+
+    Production: mergeReadStateEvents merges per-slot blobs with per-context
+    max(). Override sibling keys are individual context entries, so they
+    follow the same merge path. The atomic-grouping rule requires that all
+    `ov_*` sibling keys for a context travel with that context's frontier
+    key in the same slot — `split_blob_into_slots` enforces this.
+    """
+    violations = []
+    for tie_policy in [CLEAR, SET]:
+        dev = device_cls("d0")
+        dev.frontier["c0"] = 10
+        dev.frontier["c1"] = 20
+        dev.do_mark_unread("c0")
+        dev.do_mark_read("c1", 30)
+
+        full_blob = dev.publish_blob(tie_policy)
+        slots = dev.split_blob_into_slots(tie_policy, n_slots=2)
+        slot0, slot1 = slots[0], slots[1]
+
+        recv_full = device_cls("recv_full")
+        recv_full.receive_merge(full_blob)
+
+        for first, second in [(slot0, slot1), (slot1, slot0)]:
+            recv_split = device_cls("recv_split")
+            recv_split.receive_merge(first)
+            recv_split.receive_merge(second)
+
+            for ctx in CONTEXTS:
+                ov_full = recv_full.override_is_set(ctx, tie_policy)
+                ov_split = recv_split.override_is_set(ctx, tie_policy)
+                f_full = recv_full.effective_frontier(ctx)
+                f_split = recv_split.effective_frontier(ctx)
+                if ov_full != ov_split:
+                    violations.append(("multi-slot-override", tie_policy, ctx))
+                if f_full != f_split:
+                    violations.append(("multi-slot-frontier", tie_policy, ctx))
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# Interleaved-delivery grouping: Thufir's CRITICAL transport counterexample
+#
+# Without the atomic-grouping rule a compliant publisher would still split
+# ov_s:/ov_c:/ov_b: across slots as independent entries.  M8's per-entry
+# split places frontier+ov_s: in slot 0 and ov_b:+ov_c: in slot 1.  An
+# observer holding only slot 0 reconstructs RegB(1,0,0), judges it
+# baseline-dead (B=0 ≤ frontier=10), and canonically publishes tombstone
+# RegB(0,1,0).  After all slots and that transient tombstone are eventually
+# merged the result is RegB(1,1,10) — dead under clear-wins —
+# permanently suppressing a live override.
+#
+# The atomic-grouping rule closes this: every ov_* entry for a context
+# travels with the context's frontier entry, so a receiver always sees
+# either the complete register or nothing.  This test exercises both:
+# - The PASS path: grouped slots → no false tombstone possible.
+# - The FAIL path (M8): per-entry split → Thufir's exact witness reproduced.
+# ---------------------------------------------------------------------------
+
+def test_interleaved_delivery_grouping(device_cls=DeviceB):
+    """Exercise receive-one-slot → canonical re-publish → receive-rest →
+    re-publish permutations, both slot orders, including delayed delivery
+    of both transient re-publications to a third observer.
+
+    Protocol sequence (exact, per Paul's brief):
+      1. partial_obs receives first_slot → publishes transient_1.
+      2. partial_obs receives second_slot → publishes transient_2.
+      3. Third-party finals receive BOTH source slots AND both transient
+         publications in relevant interleaving orders.
+    Oracle: after eventual delivery of ALL blobs (both source slots +
+    both transients), every observer's override matches source liveness.
+
+    With the atomic-grouping rule (default DeviceB):
+      - The compliant split puts the full register in one slot, the other
+        is empty.  partial_obs after step 1 holds either the complete
+        register (live → transient_1 is live) or nothing (transient_1 is
+        empty/virgin).  Either way, step 2 delivers the remaining (possibly
+        empty) slot.  Final merge of all blobs = source liveness.  PASS.
+    With per-entry splitting (M8):
+      - slot 0 carries frontier + ov_s: (partial → RegB(1,0,0), dead).
+        transient_1 is tombstone RegB(0,1,0).  After step 2 partial_obs
+        holds full register but transient_1 tombstone is already in
+        circulation.  Finals that receive transient_1 get
+        RegB(1,1,10) — dead under clear-wins.  FAIL (Thufir's witness).
+    """
+    violations = []
+
+    # Source: live override RegB(1,0,10) at frontier=10 — Thufir's witness.
+    src_s, src_c, src_b, src_front = 1, 0, 10, 10
+
+    for tie_policy in (CLEAR, SET):
+        src = device_cls("src")
+        src.frontier["c0"] = src_front
+        src.overrides["c0"] = RegB(s=src_s, c=src_c, b=src_b)
+
+        # Confirm source is actually live.
+        assert src.override_is_set("c0", tie_policy), (
+            f"test precondition: source must be live under {tie_policy}"
+        )
+
+        # Produce the source's two slots via the (possibly mutated) split.
+        slots = src.split_blob_into_slots(tie_policy, n_slots=2)
+        slot0, slot1 = slots[0], slots[1]
+        src_live = src.override_is_set("c0", tie_policy)
+
+        for first_slot, second_slot in [(slot0, slot1), (slot1, slot0)]:
+            # Step 1: partial_obs receives first slot, canonically re-publishes.
+            partial_obs = device_cls("partial_obs")
+            partial_obs.receive_merge(first_slot)
+            transient_1 = partial_obs.publish_blob(tie_policy)
+
+            # Step 2: partial_obs receives second slot, publishes again.
+            partial_obs.receive_merge(second_slot)
+            transient_2 = partial_obs.publish_blob(tie_policy)
+
+            # Step 3: third-party finals receive BOTH source slots AND both
+            # transient publications, in several representative interleaving
+            # orders.  All must agree with source liveness.
+            # Representative orders: transient_1 before both slots (most
+            # dangerous under M8), transient_1 after both slots, and
+            # interleaved.  We check 3 explicit orders rather than all 4!
+            # permutations (24) for speed; M8's canonical false-clear path
+            # (transient_1 first, then second_slot only) is order 1.
+            check_orders = [
+                # Most dangerous: transient_1 arrives first, before any source
+                [transient_1, slot0, slot1, transient_2],
+                # Normal: both source slots first, then both transients
+                [slot0, slot1, transient_1, transient_2],
+                # Interleaved: first source, transient_1, second source, transient_2
+                [first_slot, transient_1, second_slot, transient_2],
+            ]
+
+            for order in check_orders:
+                final = device_cls("final")
+                for blob in order:
+                    final.receive_merge(blob)
+                final_live = final.override_is_set("c0", tie_policy)
+                if final_live != src_live:
+                    t1_reg = partial_obs.overrides.get("c0")
+                    violations.append((
+                        "interleaved-delivery-false-clear",
+                        tie_policy,
+                        f"slot_order=(first={list(first_slot['contexts'].keys())[:2]}...)",
+                        f"delivery_order={[list(b['contexts'].keys())[:2] for b in order]}",
+                        f"transient_1_reg={t1_reg}",
+                        f"final_reg={final.overrides.get('c0')}",
+                        f"expected_live={src_live} got_live={final_live}",
+                    ))
+
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# Escaped-context slot-grouping regression
+#
+# Thufir's CRITICAL (round 2): a raw context ID that starts with a
+# reserved prefix (e.g. "ov_s:evil") escapes to "esc:ov_s:evil" as its
+# frontier wire key.  Before the fix, split_blob_into_slots grouped the
+# frontier by its wire key ("esc:ov_s:evil") but the ov_* siblings by
+# the raw suffix ("ov_s:evil") — two identities for one logical context.
+# The frontier and its siblings landed in different slots.
+#
+# Across publication cycles the replaceable slot d-tag coordinates
+# update slot-by-slot.  A relay can therefore serve: new frontier slot
+# (just published, carries esc:ov_s:evil=10) + stale override slot
+# (old coordinate, carries ov_s/ov_c/ov_b at b=0 from the old pub).
+# The reconstructed register is RegB(s=1, c=0, b=0) at frontier=10 —
+# baseline-dead.  Canonical re-publication emits tombstone RegB(0,1,0).
+# Eventually both current slots + the transient merge to RegB(1,1,10) —
+# dead under clear-wins — permanently suppressing a live override.
+#
+# The fix: derive the frontier's group identity via unescape_context_key
+# so it joins the same group as its ov_* siblings.  This test exercises
+# both directions: M9 (reverts to escaped-key grouping) must reproduce
+# the witness, and the correct model must pass.
+# ---------------------------------------------------------------------------
+
+def test_escaped_context_slot_grouping(device_cls=DeviceB):
+    """Regression for escaped-context identity mismatch in split_blob_into_slots.
+
+    Scenario:
+    1. Source has a live override on raw context "ov_s:evil" (escapes to
+       "esc:ov_s:evil" as frontier wire key) — Thufir's exact escaped witness.
+    2. Source publishes twice: first at frontier=0/b=0, then after advancing
+       frontier to 10 and re-marking unread (b=10).  Each publication produces
+       2 slots.  Simulates a relay retaining a stale old-cycle slot under its
+       old replaceable coordinate while only the new-cycle slot for the OTHER
+       half has been updated — the old/new slot-coordinate mixture.
+    3. An observer receives: new-cycle frontier-bearing slot (frontier=10,
+       esc:ov_s:evil=10) + stale old-cycle override slot (ov_s/ov_c/ov_b from
+       first pub where b=0).
+    4. Observer canonically re-publishes (mandatory, per NIP-RS spec).
+    5. A third-party final observer receives both current-cycle source slots
+       plus the transient re-publication.
+    6. Oracle: final observer must see the override as live.
+
+    With the unescape-before-group fix: frontier + ov_* siblings always land
+    in the same slot → no partial register → no false tombstone.  PASS.
+    With M9 (escaped-key grouping): frontier in one slot, siblings in another
+    → partial reconstruction → false tombstone → final merge dead.  FAIL.
+    """
+    violations = []
+    raw_ctx = "ov_s:evil"
+
+    for tie_policy in (CLEAR, SET):
+        # --- Publication cycle 1: initial state, frontier=0 ---
+        src_old = device_cls("src")
+        src_old.frontier[raw_ctx] = 0
+        src_old.do_mark_unread(raw_ctx)  # RegB(s=1, c=0, b=0)
+        old_slots = src_old.split_blob_into_slots(tie_policy, n_slots=2)
+        # old_slots[0] is the "stale old-coordinate slot" a relay may retain.
+
+        # --- Publication cycle 2: frontier advances, re-mark-unread ---
+        src_new = device_cls("src")
+        src_new.frontier[raw_ctx] = 10
+        src_new.do_mark_unread(raw_ctx)  # RegB(s=1, c=0, b=10) — live at frontier=10
+
+        assert src_new.override_is_set(raw_ctx, tie_policy), (
+            f"test precondition: source must be live under {tie_policy}"
+        )
+
+        new_slots = src_new.split_blob_into_slots(tie_policy, n_slots=2)
+
+        # --- Full delivery: both new slots → both current-cycle slot arrive ---
+        recv_full = device_cls("recv_full")
+        recv_full.receive_merge(new_slots[0])
+        recv_full.receive_merge(new_slots[1])
+        if not recv_full.override_is_set(raw_ctx, tie_policy):
+            violations.append((
+                "escaped-ctx-full-delivery-dead", tie_policy,
+                f"full={recv_full.overrides.get(raw_ctx)}",
+            ))
+
+        # --- Mixture: new frontier-bearing slot + stale old override slot ---
+        # Identify which new slot carries the frontier and which carries ov_*,
+        # then pair the frontier slot with the old-cycle override slot.
+        wire_frontier = escape_context_key(raw_ctx)
+
+        new_frontier_slot_idx = 0 if wire_frontier in new_slots[0]["contexts"] else 1
+        new_frontier_slot = new_slots[new_frontier_slot_idx]
+        old_override_slot = old_slots[1 - new_frontier_slot_idx]  # opposite slot
+
+        # Check whether the frontier and ov_* siblings are co-located in new_slots.
+        ov_s_key = f"ov_s:{raw_ctx}"
+        frontier_and_ov_same_slot = (
+            wire_frontier in new_slots[new_frontier_slot_idx]["contexts"] and
+            ov_s_key in new_slots[new_frontier_slot_idx]["contexts"]
+        )
+
+        if frontier_and_ov_same_slot:
+            # Correct grouping: old override slot has nothing relevant, mixture
+            # is safe by construction — the stale slot is just an empty dict.
+            # Verify anyway for defense-in-depth.
+            obs = device_cls("obs")
+            obs.receive_merge(new_frontier_slot)
+            obs.receive_merge(old_override_slot)
+            transient = obs.publish_blob(tie_policy)
+
+            final = device_cls("final")
+            final.receive_merge(new_slots[0])
+            final.receive_merge(new_slots[1])
+            final.receive_merge(transient)
+            if not final.override_is_set(raw_ctx, tie_policy):
+                violations.append((
+                    "escaped-ctx-grouped-mixture-dead", tie_policy,
+                    f"transient={obs.overrides.get(raw_ctx)}",
+                    f"final={final.overrides.get(raw_ctx)}",
+                ))
+        else:
+            # Mismatched grouping (M9 path): frontier and siblings split.
+            # The mixture produces a partial register → false tombstone.
+            obs = device_cls("obs")
+            obs.receive_merge(new_frontier_slot)    # gets frontier=10, no ov_*
+            obs.receive_merge(old_override_slot)    # gets ov_s/ov_c/ov_b at b=0
+            transient = obs.publish_blob(tie_policy)
+
+            # Final observer gets everything: both new slots + transient.
+            for order in [(new_slots[0], new_slots[1]), (new_slots[1], new_slots[0])]:
+                final = device_cls("final")
+                final.receive_merge(order[0])
+                final.receive_merge(order[1])
+                final.receive_merge(transient)
+                if not final.override_is_set(raw_ctx, tie_policy):
+                    violations.append((
+                        "escaped-ctx-mixture-false-clear", tie_policy,
+                        f"obs_reg={obs.overrides.get(raw_ctx)}",
+                        f"transient_reg={transient['contexts']}",
+                        f"final_reg={final.overrides.get(raw_ctx)}",
+                    ))
+
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# Reserved key namespace: adversarial prefix collision
+# ---------------------------------------------------------------------------
+
+def test_reserved_namespace_collision():
+    """A genuine user context whose raw ID begins with the reserved `ov_`
+    stem (e.g. a pre-existing legacy context literally named `ov_s:evil`)
+    must round-trip as frontier state, not be misparsed as a control key
+    for a different context, and must not collide with a real override's
+    sibling keys in the same flattened contexts map.
+
+    Exercises: escape on publish, unescape on receive, and a live
+    override on a DIFFERENT context in the same blob to prove no
+    control-key collision occurs.
+    """
+    violations = []
+    adversarial_raw = "ov_s:evil"  # would misparse as ov_s: control for ctx "evil"
+    real_ctx = "c0"
+
+    # Escaping must be a no-op for every context ID Buzz actually
+    # generates, and must trigger for the adversarial one.
+    for benign in ("b68cd7cb-6f8d-4641-b743-a7349eb4114b",
+                   "msg:" + "a" * 64, "thread:" + "b" * 64):
+        if escape_context_key(benign) != benign:
+            violations.append(("namespace-benign-escaped", benign))
+    if escape_context_key(adversarial_raw) == adversarial_raw:
+        violations.append(("namespace-adversarial-not-escaped", adversarial_raw))
+    if not escape_context_key(adversarial_raw).startswith(ESCAPE_PREFIX):
+        violations.append(("namespace-adversarial-missing-marker", adversarial_raw))
+
+    dev = DeviceB("d0")
+    dev.frontier[adversarial_raw] = 42
+    dev.frontier[real_ctx] = 5
+    dev.do_mark_unread(real_ctx)
+    blob = dev.publish_blob()
+
+    wire_key = escape_context_key(adversarial_raw)
+    if wire_key not in blob["contexts"]:
+        violations.append(("namespace-wire-key-missing", wire_key, blob["contexts"]))
+    if blob["contexts"].get(wire_key) != 42:
+        violations.append(("namespace-value-corrupted", wire_key, blob["contexts"].get(wire_key)))
+
+    recv = DeviceB("recv")
+    recv.receive_merge(blob)
+    if recv.effective_frontier(adversarial_raw) != 42:
+        violations.append((
+            "namespace-roundtrip-failed", adversarial_raw,
+            recv.effective_frontier(adversarial_raw),
+        ))
+    if adversarial_raw in recv.overrides:
+        violations.append(("namespace-misparsed-as-override", adversarial_raw))
+    if recv.overrides.get(real_ctx) is None or recv.overrides[real_ctx].s == 0:
+        violations.append(("namespace-real-override-corrupted", real_ctx, recv.overrides.get(real_ctx)))
+
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# Run all
+# ---------------------------------------------------------------------------
+
+def run_all():
+    print("=" * 60)
+    print("NIP-RS manual-unread exhaustive model")
+    print("=" * 60)
+    total_violations = 0
+
+    def report(name, violations):
+        nonlocal total_violations
+        n = len(violations) if isinstance(violations, list) else 0
+        total_violations += n
+        status = "PASS" if n == 0 else f"FAIL ({n})"
+        print(f"  {name}: {status}")
+        if n > 0:
+            for v in violations[:3]:
+                print(f"    {v}")
+
+    print("\n--- I1: merge algebra (B) ---")
+    report("assoc/commut/idempot", test_merge_algebra_b())
+
+    print("\n--- I1: merge algebra (A) ---")
+    report("assoc/commut/idempot", test_merge_algebra_a())
+
+    print("\n--- I2+I3+I5: BFS explorer (B, clear-wins) ---")
+    n, v = explore_b(max_depth=4, tie_policy=CLEAR)
+    print(f"  states explored: {n}")
+    report("convergence+frontier+compaction", v)
+
+    print("\n--- I2+I3+I5: BFS explorer (B, set-wins) ---")
+    n, v = explore_b(max_depth=4, tie_policy=SET)
+    print(f"  states explored: {n}")
+    report("convergence+frontier+compaction", v)
+
+    print("\n--- I4: concurrent set/clear stability ---")
+    report("stable winner", test_concurrent_stability())
+
+    print("\n--- I5: compaction register-level exhaustive ---")
+    report("all register values x policies", test_compaction_register_exhaustive())
+
+    print("\n--- I5c: directed deep-history (compact -> reuse -> stale delivery) ---")
+    cube_size, deep_v = test_deep_history_compaction()
+    print(f"  parameter cube size: {cube_size}")
+    report("no divergence from never-compact reference", deep_v)
+
+    print("\n--- I5c: tombstone + stale-ancestor merge (direct) ---")
+    report("no resurrection", test_tombstone_stale_merge_direct())
+
+    print("\n--- I5d: tombstone-merge monotonicity (structural lemma) ---")
+    report("ceiling never strengthens S", test_tombstone_merge_monotonic())
+
+    print("\n--- I5d: cross-device compaction transparency (suppress-only) ---")
+    cd_cube, cd_suppress, cd_v = test_cross_device_compaction_suppression()
+    print(f"  parameter cube size: {cd_cube}  suppressions observed: {cd_suppress}")
+    report("suppress-only + recoverable", cd_v)
+
+    print("\n--- Published-state merge closure (canonical publication guarantee) ---")
+    mc_cube, mc_v = test_published_merge_closure()
+    print(f"  pairs checked: {mc_cube}")
+    report("no dead+dead resurrection", mc_v)
+
+    print("\n--- I6: replay harmless ---")
+    report("replay", test_replay_harmless())
+
+    print("\n--- I7: legacy rewrite (B) ---")
+    report("sibling keys survive", test_legacy_rewrite_b())
+
+    print("\n--- I7: legacy erasure (A) — expected witness ---")
+    erased = test_legacy_erasure_a()
+    print(f"  overrides erased by legacy: {'CONFIRMED' if erased else 'NOT FOUND'}")
+    if not erased:
+        total_violations += 1
+
+    print("\n--- I8: bounded growth ---")
+    report("canonical wire shape (3 live / 1 tombstone)", test_bounded_growth())
+
+    print("\n--- I8: exact wire-shape regression ---")
+    report("live=3 keys, tombstone=1 key, virgin=0 keys", test_wire_shape_exact())
+
+    print("\n--- I9: DeviceA counter absorption ---")
+    absorbed = test_a_counter_absorption()
+    print(f"  post-receive counter > received: {'CONFIRMED' if absorbed else 'FAIL'}")
+    if not absorbed:
+        total_violations += 1
+
+    print("\n--- Identity-free (B) ---")
+    report("reinstall convergence", test_b_identity_free())
+
+    print("\n--- Legacy prune interaction ---")
+    ov_ok, msg_ok, nested_lost = test_legacy_prune_interaction()
+    print(f"  ov_ keys survive: {'PASS' if ov_ok else 'FAIL'}")
+    print(f"  msg: pruned at horizon: {'PASS' if msg_ok else 'FAIL'}")
+    print(f"  nested msg:ov_ lost: {'CONFIRMED (hazard)' if nested_lost else 'NOT FOUND'}")
+    if not ov_ok:
+        total_violations += 1
+
+    print("\n--- Legacy trim interaction ---")
+    blocked = test_legacy_trim_interaction()
+    print(f"  excess overrides block publish: {'CONFIRMED (hazard)' if blocked else 'NOT FOUND'}")
+
+    print("\n--- Multi-slot union ---")
+    report("split+merge convergence", test_multi_slot_union())
+
+    print("\n--- Interleaved delivery + atomic grouping rule ---")
+    report("no false clear under slot interleaving", test_interleaved_delivery_grouping())
+
+    print("\n--- Escaped-context slot-grouping regression ---")
+    report("escaped ctx: frontier + ov_* siblings same slot", test_escaped_context_slot_grouping())
+
+    print("\n--- Reserved key namespace: adversarial prefix collision ---")
+    report("escape/unescape + no misparse", test_reserved_namespace_collision())
+
+    print("\n" + "=" * 60)
+    if total_violations == 0:
+        print("ALL INVARIANTS HOLD — 0 violations")
+    else:
+        print(f"VIOLATIONS: {total_violations}")
+    print("=" * 60)
+    return total_violations
+
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(0 if run_all() == 0 else 1)
diff --git a/docs/formal/nip-rs-unread/model.py b/docs/formal/nip-rs-unread/model.py
new file mode 100644
index 0000000000..4400280571
--- /dev/null
+++ b/docs/formal/nip-rs-unread/model.py
@@ -0,0 +1,492 @@
+"""Bounded exhaustive model comparing two NIP-RS manual-unread encodings.
+
+Candidate A: lexicographic operation register
+  Per context: {counter, client_tiebreak, op in {SET,CLEAR}, baseline}
+  in a NEW top-level field beside `contexts`.
+  Merge = max tuple (counter, tiebreak, op-rule on full tie).
+
+Candidate B: two grow-only counters + baseline
+  Per context: S (set counter), C (clear counter), B (frontier-at-set-time)
+  as sibling keys under `contexts` (ov_s:, ov_c:, ov_b: prefixes).
+  Action: own counter := max(S,C)+1; set also writes B := effective frontier.
+  Merge = componentwise max. Tie policy on S == C is a parameter.
+
+Both share:
+  - Frontier: grow-only max() per NIP-RS v1 (unchanged).
+  - Verdict: unread(ctx) = latest > effective_frontier(ctx) OR override_set(ctx).
+  - Mark-read = advance frontier + clear override.
+  - Mark-unread = set override with baseline B = current effective frontier.
+  - Natural frontier advance strictly past B dominates a stale set.
+
+Device simulators use overridable methods (_override_set, _compact, _merge_reg,
+_bump, _sanitize_value) so the mutation harness can inject weakened rules via
+subclassing without monkeypatching.
+"""
+from dataclasses import dataclass
+from typing import Optional
+
+
+SET = "SET"
+CLEAR = "CLEAR"
+
+
+# ---------------------------------------------------------------------------
+# Reserved key namespace + escaping
+#
+# NIP-RS v1 context IDs are arbitrary UTF-8 (spec :89, :113-114), so a
+# pre-existing opaque context could legitimately begin with `ov_s:`,
+# `ov_c:`, or `ov_b:` and collide with a control key for a DIFFERENT
+# context in the same flattened `contexts` map. `ov_` (the shared
+# 3-byte stem) and the escape marker itself are reserved; any raw
+# context ID that would collide is escaped before being used as a
+# plain frontier key. Escaping is a no-op for every context ID Buzz
+# actually generates (channel UUID, `msg:<hex64>`, `thread:<hex64>`
+# — none start with `ov_` or `esc:`), so the common case pays zero
+# bytes. Only a pathological ID pays the 4-byte `esc:` cost.
+#
+# This protects context IDs generated by amendment-aware clients.
+# It does NOT retroactively protect a context that a PRE-EXISTING
+# legacy client already published unescaped before the amendment
+# shipped — that residual hazard is documented, not solved (see
+# NOTE.md "Reserved key namespace").
+# ---------------------------------------------------------------------------
+
+ESCAPE_PREFIX = "esc:"
+_RESERVED_STEM = "ov_"
+
+
+def _needs_escape(raw_key: str) -> bool:
+    return raw_key.startswith(_RESERVED_STEM) or raw_key.startswith(ESCAPE_PREFIX)
+
+
+def escape_context_key(raw_key: str) -> str:
+    return ESCAPE_PREFIX + raw_key if _needs_escape(raw_key) else raw_key
+
+
+def unescape_context_key(wire_key: str) -> str:
+    if wire_key.startswith(ESCAPE_PREFIX):
+        return wire_key[len(ESCAPE_PREFIX):]
+    return wire_key
+
+
+# ---------------------------------------------------------------------------
+# Candidate B — two grow-only counters + baseline
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class RegB:
+    s: int = 0
+    c: int = 0
+    b: int = 0
+
+
+def merge_reg_b(a: Optional[RegB], b: Optional[RegB]) -> Optional[RegB]:
+    if a is None:
+        return b
+    if b is None:
+        return a
+    return RegB(s=max(a.s, b.s), c=max(a.c, b.c), b=max(a.b, b.b))
+
+
+def override_set_b(reg: Optional[RegB], frontier_val: int, tie_policy=CLEAR) -> bool:
+    if reg is None:
+        return False
+    if frontier_val > reg.b and reg.s > 0:
+        return False
+    if reg.s > reg.c:
+        return True
+    if reg.s == reg.c and reg.s > 0:
+        return tie_policy == SET
+    return False
+
+
+def compact_b(reg: RegB, frontier_val: int, tie_policy=CLEAR) -> Optional[RegB]:
+    """Compact override state.
+
+    Tombstone-floor design: a register with any recorded counter
+    activity (S>0 or C>0) is never fully deleted. Its counter
+    high-water-mark is exactly what prevents a stale replica —
+    any (S,C) pair below that ceiling — from dominating a freshly
+    created register after compaction (delete-on-dominance made
+    counters reusable: a dead register dropped entirely, then a new
+    local set/clear pair restarted from S=0/C=0, so a delayed stale
+    peer snapshot with S>0 could out-rank the new state on replay).
+    Only a virgin register (S==0, C==0, no activity ever recorded)
+    has no ceiling to protect and compacts to None.
+
+    A live override (per `override_set_b`, which is already
+    policy-aware) is returned unchanged — compaction only touches dead
+    state. Dead overrides — whether dominated by C>S, tied under
+    clear-wins, or baseline-dominated by frontier advance — compact to
+    the clear-tombstone floor `RegB(s=0, c=max(S,C), b=0)`: S is
+    zeroed (no longer overriding), but C retains the ceiling so both a
+    future local bump (`max(S,C)+1`) and a componentwise-max merge with
+    any pre-compaction stale snapshot start strictly above the
+    historical maximum, never below it.
+    """
+    if reg.s == 0 and reg.c == 0:
+        return None
+    if override_set_b(reg, frontier_val, tie_policy):
+        return reg
+    return RegB(s=0, c=max(reg.s, reg.c), b=0)
+
+
+# ---------------------------------------------------------------------------
+# Candidate A — lexicographic operation register
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class RegA:
+    counter: int = 0
+    tiebreak: str = ""
+    op: str = CLEAR
+    baseline: int = 0
+
+    def as_tuple(self, op_wins):
+        op_val = 1 if self.op == op_wins else 0
+        return (self.counter, self.tiebreak, op_val)
+
+
+def merge_reg_a(a: Optional[RegA], b: Optional[RegA], tie_op=CLEAR) -> Optional[RegA]:
+    if a is None:
+        return b
+    if b is None:
+        return a
+    at = a.as_tuple(tie_op)
+    bt = b.as_tuple(tie_op)
+    if at == bt:
+        return RegA(
+            counter=a.counter, tiebreak=a.tiebreak, op=a.op,
+            baseline=max(a.baseline, b.baseline),
+        )
+    return a if at > bt else b
+
+
+# ---------------------------------------------------------------------------
+# Device simulation — Candidate B
+# ---------------------------------------------------------------------------
+
+class DeviceB:
+    """Simulates one device's NIP-RS read-state blob with manual-unread
+    override layer (candidate B encoding).
+
+    All model operations go through overridable _methods so the mutation
+    harness can inject weakened rules via subclassing.
+    """
+
+    def __init__(self, client_id, is_legacy=False):
+        self.client_id = client_id
+        self.is_legacy = is_legacy
+        self.frontier = {}
+        self.overrides = {}
+
+    def effective_frontier(self, ctx):
+        return self.frontier.get(ctx, 0)
+
+    def _override_set(self, reg, frontier_val, tie_policy):
+        return override_set_b(reg, frontier_val, tie_policy)
+
+    def _compact(self, reg, frontier_val, tie_policy):
+        return compact_b(reg, frontier_val, tie_policy)
+
+    def _merge_reg(self, a, b):
+        return merge_reg_b(a, b)
+
+    def _bump(self, s, c):
+        return max(s, c) + 1
+
+    def _sanitize_value(self, v):
+        return isinstance(v, int) and 0 <= v <= 4294967295
+
+    def override_is_set(self, ctx, tie_policy=CLEAR):
+        return self._override_set(
+            self.overrides.get(ctx), self.effective_frontier(ctx), tie_policy
+        )
+
+    def verdict(self, ctx, latest_ts, tie_policy=CLEAR):
+        return (latest_ts > self.effective_frontier(ctx)
+                or self.override_is_set(ctx, tie_policy))
+
+    def do_mark_unread(self, ctx):
+        if self.is_legacy:
+            return
+        cur = self.overrides.get(ctx, RegB())
+        new_s = self._bump(cur.s, cur.c)
+        self.overrides[ctx] = RegB(s=new_s, c=cur.c, b=self.effective_frontier(ctx))
+
+    def do_mark_read(self, ctx, frontier_ts):
+        self.frontier[ctx] = max(self.frontier.get(ctx, 0), frontier_ts)
+        if not self.is_legacy:
+            cur = self.overrides.get(ctx, RegB())
+            new_c = self._bump(cur.s, cur.c)
+            self.overrides[ctx] = RegB(s=cur.s, c=new_c, b=cur.b)
+
+    def do_advance_frontier(self, ctx, ts):
+        self.frontier[ctx] = max(self.frontier.get(ctx, 0), ts)
+
+    def do_compact(self, ctx, tie_policy=CLEAR):
+        reg = self.overrides.get(ctx)
+        if reg is None:
+            return
+        result = self._compact(reg, self.effective_frontier(ctx), tie_policy)
+        if result is None:
+            if ctx in self.overrides:
+                del self.overrides[ctx]
+        else:
+            self.overrides[ctx] = result
+
+    def do_reinstall(self):
+        self.client_id = self.client_id + "_r"
+        self.frontier = {}
+        self.overrides = {}
+
+    def _canonicalize_for_publish(self, ctx, tie_policy):
+        """Canonical published form of `ctx`'s override register,
+        computed fresh against the current effective frontier —
+        independent of whether `do_compact` was ever called locally.
+        Returns `(is_live, canonical_reg)`; `canonical_reg is None`
+        means virgin (omit from the wire entirely). Reuses the same
+        overridable `_compact`/`_override_set` hooks `do_compact` uses,
+        so a mutation-harness subclass that weakens one weakens both
+        the storage-GC path and the publish path identically.
+        """
+        reg = self.overrides.get(ctx)
+        if reg is None:
+            return False, None
+        front = self.effective_frontier(ctx)
+        canonical = self._compact(reg, front, tie_policy)
+        if canonical is None:
+            return False, None
+        return self._override_set(canonical, front, tie_policy), canonical
+
+    def publish_blob(self, tie_policy=CLEAR):
+        """Serialize this device's read-state blob.
+
+        Every override is canonicalized at serialization time: live ->
+        unchanged (3 keys), dead -> tombstone floor (1 key, `ov_c:`
+        only), virgin -> omitted (0 keys). Canonical publication is a
+        protocol requirement, not an optimization — noncanonical wire
+        output is structurally impossible here, not merely avoided by
+        convention. `do_compact` remains a separate storage-GC
+        transition that mutates `self.overrides`; publication no
+        longer depends on it having been called first.
+
+        **Atomic slot-grouping rule (spec-amendment requirement):**
+        A context's frontier entry and ALL of its `ov_*` sibling entries
+        MUST travel in the same slot. `split_blob_into_slots` below
+        enforces this by round-robining per-context groups, never
+        per-entry. A receiving client that only holds part of a context
+        group and attempts to reconstruct a `RegB` from it would see
+        partial zeroes and might canonically re-publish a false
+        tombstone. Group atomicity makes partial reconstruction
+        structurally impossible from a compliant publisher's output.
+        """
+        blob_ctx = {escape_context_key(k): v for k, v in self.frontier.items()}
+        if not self.is_legacy:
+            for k in self.overrides:
+                is_live, canonical = self._canonicalize_for_publish(k, tie_policy)
+                if canonical is None:
+                    continue  # virgin: omitted from the wire entirely
+                if is_live:
+                    blob_ctx[f"ov_s:{k}"] = canonical.s
+                    blob_ctx[f"ov_c:{k}"] = canonical.c
+                    blob_ctx[f"ov_b:{k}"] = canonical.b
+                else:
+                    blob_ctx[f"ov_c:{k}"] = canonical.c  # tombstone: ceiling only
+        return {"v": 1, "client_id": self.client_id, "contexts": blob_ctx}
+
+    def split_blob_into_slots(self, tie_policy=CLEAR, n_slots=2):
+        """Split this device's blob into `n_slots` compliant slots.
+
+        **Atomic grouping rule:** a context's frontier entry and ALL of
+        its `ov_*` sibling entries travel together in the same slot.
+        Round-robin assignment is per-context group, never per-entry.
+        This matches production `splitContextsIntoBudgetedSlots` when
+        it is amended to group by context instead of by individual entry.
+
+        Returns a list of `n_slots` blobs, each with the same `v` and
+        `client_id` but a disjoint subset of context groups.
+        """
+        blob = self.publish_blob(tie_policy)
+        contexts = blob["contexts"]
+
+        # Gather per-context groups: each group is a list of (key, value) pairs.
+        # A "group" is: the frontier key (escaped ctx) + any ov_* siblings.
+        # Contexts that appear only as ov_* keys (no frontier entry) are
+        # also grouped together.
+        groups = {}  # logical_ctx -> list of (wire_key, value)
+        for wire_key, value in contexts.items():
+            if wire_key.startswith("ov_s:"):
+                ctx = wire_key[5:]
+            elif wire_key.startswith("ov_c:"):
+                ctx = wire_key[5:]
+            elif wire_key.startswith("ov_b:"):
+                ctx = wire_key[5:]
+            else:
+                # Frontier key: may be escaped (e.g. "esc:ov_s:evil").
+                # Derive the logical context ID by unescaping so this
+                # entry joins the same group as its ov_* siblings, which
+                # are keyed by the RAW context ID (e.g. "ov_s:evil" ->
+                # ctx = "evil", but "esc:ov_s:evil" frontier -> ctx =
+                # "ov_s:evil" after unescape).  Without this step an
+                # escaped frontier key and its ov_* siblings would be
+                # treated as two different groups, splitting the register
+                # across slots — reproducing the round-1 partial-
+                # reconstruction poison for escaped context IDs.
+                ctx = unescape_context_key(wire_key)
+            groups.setdefault(ctx, []).append((wire_key, value))
+
+        slots = [{"v": blob["v"], "client_id": blob["client_id"], "contexts": {}}
+                 for _ in range(n_slots)]
+        for i, (_ctx, pairs) in enumerate(sorted(groups.items())):
+            slot = slots[i % n_slots]
+            for wire_key, value in pairs:
+                slot["contexts"][wire_key] = value
+        return slots
+
+    def receive_merge(self, blob):
+        incoming_overrides = {}
+        for k, v in blob.get("contexts", {}).items():
+            if k.startswith("ov_s:"):
+                ctx = k[5:]
+                incoming_overrides.setdefault(ctx, [0, 0, 0])[0] = v
+            elif k.startswith("ov_c:"):
+                ctx = k[5:]
+                incoming_overrides.setdefault(ctx, [0, 0, 0])[1] = v
+            elif k.startswith("ov_b:"):
+                ctx = k[5:]
+                incoming_overrides.setdefault(ctx, [0, 0, 0])[2] = v
+            else:
+                ctx = unescape_context_key(k)
+                self.frontier[ctx] = max(self.frontier.get(ctx, 0), v)
+
+        if not self.is_legacy:
+            for ctx, (s, c, b) in incoming_overrides.items():
+                incoming_reg = RegB(s=s, c=c, b=b)
+                self.overrides[ctx] = self._merge_reg(
+                    self.overrides.get(ctx), incoming_reg
+                )
+
+    def legacy_sanitize_and_publish(self, tie_policy=CLEAR):
+        blob = self.publish_blob(tie_policy)
+        sanitized = {}
+        for k, v in blob["contexts"].items():
+            if len(k.encode("utf-8")) <= 256 and self._sanitize_value(v):
+                sanitized[k] = v
+        return {"v": 1, "client_id": self.client_id, "contexts": sanitized}
+
+    def state_key(self, contexts, tie_policy=CLEAR):
+        parts = []
+        for ctx in sorted(contexts):
+            f = self.effective_frontier(ctx)
+            reg = self.overrides.get(ctx, RegB())
+            ov = self.override_is_set(ctx, tie_policy)
+            parts.append((ctx, f, reg.s, reg.c, reg.b, ov))
+        return (self.client_id, self.is_legacy, tuple(parts))
+
+
+# ---------------------------------------------------------------------------
+# Device simulation — Candidate A
+# ---------------------------------------------------------------------------
+
+class DeviceA:
+    def __init__(self, client_id, is_legacy=False):
+        self.client_id = client_id
+        self.is_legacy = is_legacy
+        self.frontier = {}
+        self.overrides = {}
+        self.counter = 0
+
+    def effective_frontier(self, ctx):
+        return self.frontier.get(ctx, 0)
+
+    def override_is_set(self, ctx):
+        reg = self.overrides.get(ctx)
+        if reg is None or reg.op == CLEAR:
+            return False
+        if self.effective_frontier(ctx) > reg.baseline:
+            return False
+        return True
+
+    def verdict(self, ctx, latest_ts):
+        return latest_ts > self.effective_frontier(ctx) or self.override_is_set(ctx)
+
+    def do_mark_unread(self, ctx):
+        if self.is_legacy:
+            return
+        self.counter += 1
+        self.overrides[ctx] = RegA(
+            counter=self.counter, tiebreak=self.client_id,
+            op=SET, baseline=self.effective_frontier(ctx),
+        )
+
+    def do_mark_read(self, ctx, frontier_ts):
+        self.frontier[ctx] = max(self.frontier.get(ctx, 0), frontier_ts)
+        if not self.is_legacy:
+            self.counter += 1
+            self.overrides[ctx] = RegA(
+                counter=self.counter, tiebreak=self.client_id,
+                op=CLEAR, baseline=0,
+            )
+
+    def do_advance_frontier(self, ctx, ts):
+        self.frontier[ctx] = max(self.frontier.get(ctx, 0), ts)
+
+    def receive_merge(self, blob, tie_op=CLEAR):
+        for ctx, ts in blob.get("contexts", {}).items():
+            self.frontier[ctx] = max(self.frontier.get(ctx, 0), ts)
+        if not self.is_legacy:
+            for ctx, reg in blob.get("overrides", {}).items():
+                self.overrides[ctx] = merge_reg_a(
+                    self.overrides.get(ctx), reg, tie_op
+                )
+                if reg.counter > self.counter:
+                    self.counter = reg.counter
+
+    def publish_blob(self):
+        blob = {"v": 1, "client_id": self.client_id, "contexts": dict(self.frontier)}
+        if not self.is_legacy:
+            blob["overrides"] = dict(self.overrides)
+        return blob
+
+    def legacy_rewrite_and_publish(self):
+        return {"v": 1, "client_id": self.client_id, "contexts": dict(self.frontier)}
+
+
+# ---------------------------------------------------------------------------
+# Legacy pruning/trim model
+# ---------------------------------------------------------------------------
+
+def legacy_prune(contexts, horizon):
+    return {k: v for k, v in contexts.items()
+            if not (k.startswith("msg:") or k.startswith("thread:")) or v >= horizon}
+
+
+def legacy_trim(contexts, client_id, max_bytes=32768):
+    import json
+
+    def size(ctx):
+        return len(json.dumps({"v": 1, "client_id": client_id, "contexts": ctx}).encode())
+
+    if size(contexts) <= max_bytes:
+        return contexts, True
+    evictable = sorted(
+        ((k, v) for k, v in contexts.items()
+         if k.startswith("msg:") or k.startswith("thread:")),
+        key=lambda kv: kv[1],
+    )
+    out = dict(contexts)
+    for k, _ in evictable:
+        del out[k]
+        if size(out) <= max_bytes:
+            return out, True
+    return out, size(out) <= max_bytes
+
+
+def legacy_sanitize_blob(blob):
+    sanitized = {}
+    for k, v in blob.get("contexts", {}).items():
+        if (len(k.encode("utf-8")) <= 256
+                and isinstance(v, int) and 0 <= v <= 4294967295):
+            sanitized[k] = v
+    return {"v": 1, "client_id": blob.get("client_id", ""), "contexts": sanitized}
diff --git a/docs/formal/nip-rs-unread/mutation.py b/docs/formal/nip-rs-unread/mutation.py
new file mode 100644
index 0000000000..4450a99c8f
--- /dev/null
+++ b/docs/formal/nip-rs-unread/mutation.py
@@ -0,0 +1,519 @@
+"""Mutation harness for candidate B (two-counter) model.
+
+Each mutant: subclass DeviceB with a weakened rule, run the BFS explorer,
+require a recorded counterexample. A model that stays green under a real
+weakening is worthless.
+
+Mutants:
+  M1: drop baseline dominance (frontier > B no longer clears stale set)
+  M2: drop max(S,C)+1 bump (use S+1 or C+1 — counter can regress)
+  M3: flip tie policy (verify the model distinguishes them)
+  M4: revert to delete-on-dominance compaction (drops the tombstone floor
+      entirely instead of zeroing S and keeping max(S,C) as C) — reproduces
+      Thufir's pass-3 CRITICAL: stale-replay resurrection after counter reuse
+  M5: uint32 overflow bypass (legacy sanitization disabled)
+  M6: componentwise-max -> last-write-wins merge (convergence breaks)
+  M7: publish without canonicalization (serialize raw registers instead
+      of the compact-at-publish canonical form) — reproduces Thufir's
+      pass-1/2 CRITICAL: dead+dead merge resurrection
+  M8: revert split_blob_into_slots to per-entry splitting (violates the
+      atomic-grouping rule) — reproduces Thufir's pass-2/2 CRITICAL:
+      partial-slot reconstruction of a live RegB creates a false tombstone
+      that permanently suppresses the override after eventual full delivery
+  M9: revert split_blob_into_slots to escaped-key grouping (groups frontier
+      by wire key instead of unescaped logical ID) — reproduces Thufir's
+      round-2 CRITICAL: for a context whose raw ID starts with a reserved
+      prefix (e.g. "ov_s:evil"), the frontier's escaped wire key
+      ("esc:ov_s:evil") and the ov_* siblings (keyed by raw suffix "ov_s:evil")
+      resolve to different groups → register split across slots →
+      old/new slot-coordinate mixture produces partial reconstruction →
+      false tombstone → permanent false clear across publication cycles
+
+Each mutant is injected into the model via DeviceB subclass, then the
+explorer or invariant suite is rerun. The counterexample (first violation)
+is recorded and printed.
+"""
+from copy import deepcopy
+from model import (
+    RegB, merge_reg_b, override_set_b, compact_b,
+    DeviceB, legacy_sanitize_blob,
+    escape_context_key,
+    SET, CLEAR,
+)
+from exhaustive import (
+    explore_b, test_concurrent_stability,
+    test_compaction_register_exhaustive, test_deep_history_compaction,
+    test_published_merge_closure, test_interleaved_delivery_grouping,
+    test_escaped_context_slot_grouping,
+    CONTEXTS,
+)
+
+
+# ---------------------------------------------------------------------------
+# M1: drop baseline dominance
+# ---------------------------------------------------------------------------
+
+class M1_NoBaselineDominance(DeviceB):
+    def _override_set(self, reg, frontier_val, tie_policy):
+        if reg is None:
+            return False
+        if reg.s > reg.c:
+            return True
+        if reg.s == reg.c and reg.s > 0:
+            return tie_policy == SET
+        return False
+
+    def _compact(self, reg, frontier_val, tie_policy):
+        if reg.s == 0 and reg.c == 0:
+            return None
+        if self._override_set(reg, frontier_val, tie_policy):
+            return reg
+        if reg.c > reg.s:
+            return RegB(s=0, c=reg.c, b=0)
+        if reg.c == reg.s and tie_policy == CLEAR:
+            return RegB(s=0, c=reg.c, b=0)
+        return reg
+
+
+def mutant_m1():
+    """M1: without baseline dominance, a stale set persists after frontier
+    advance past baseline. Verify by constructing the scenario directly:
+    mark-unread at frontier=10, then advance frontier to 100. The correct
+    model clears the override; the mutant keeps it live."""
+    violations = []
+    for ctx in CONTEXTS:
+        dev = M1_NoBaselineDominance("d0")
+        dev.frontier[ctx] = 10
+        dev.do_mark_unread(ctx)
+        dev.do_advance_frontier(ctx, 100)
+
+        correct = override_set_b(dev.overrides[ctx], 100, CLEAR)
+        mutant_result = dev.override_is_set(ctx, CLEAR)
+
+        if correct != mutant_result:
+            violations.append((
+                "baseline-dominance-missing", ctx,
+                dev.overrides[ctx], 100,
+                f"correct={correct}", f"mutant={mutant_result}",
+            ))
+
+    if not violations:
+        _, violations = explore_b(max_depth=3, tie_policy=CLEAR,
+                                  device_cls=M1_NoBaselineDominance)
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# M2: drop max(S,C)+1 bump
+# ---------------------------------------------------------------------------
+
+class M2_NoBump(DeviceB):
+    """Each counter bumps only itself: mark_unread does S := S+1,
+    mark_read does C := C+1. When S > C from a prior set, a clear
+    at C+1 can produce C < S even though the clear is causally later."""
+    def do_mark_unread(self, ctx):
+        if self.is_legacy:
+            return
+        cur = self.overrides.get(ctx, RegB())
+        self.overrides[ctx] = RegB(s=cur.s + 1, c=cur.c,
+                                   b=self.effective_frontier(ctx))
+
+    def do_mark_read(self, ctx, frontier_ts):
+        self.frontier[ctx] = max(self.frontier.get(ctx, 0), frontier_ts)
+        if not self.is_legacy:
+            cur = self.overrides.get(ctx, RegB())
+            self.overrides[ctx] = RegB(s=cur.s, c=cur.c + 1, b=cur.b)
+
+
+def mutant_m2():
+    """M2: each counter bumps independently. After set→set→clear at
+    the SAME frontier (no advance past baseline): correct clear has
+    C=3 > S=2, mutant clear has C=1 < S=2 — a causally later clear
+    fails to dominate.
+
+    Use mark_read at the current frontier (not advancing past baseline)
+    so baseline dominance doesn't mask the counter discrepancy.
+    """
+    violations = []
+    for ctx in CONTEXTS:
+        front = 10
+        dev_correct = DeviceB("d0")
+        dev_correct.frontier[ctx] = front
+        dev_correct.do_mark_unread(ctx)
+        dev_correct.do_mark_unread(ctx)
+        dev_correct.do_mark_read(ctx, front)
+
+        dev_mutant = M2_NoBump("d0")
+        dev_mutant.frontier[ctx] = front
+        dev_mutant.do_mark_unread(ctx)
+        dev_mutant.do_mark_unread(ctx)
+        dev_mutant.do_mark_read(ctx, front)
+
+        correct_set = dev_correct.override_is_set(ctx, CLEAR)
+        mutant_set = dev_mutant.override_is_set(ctx, CLEAR)
+
+        if correct_set != mutant_set:
+            violations.append((
+                "bump-independent", ctx,
+                f"correct={dev_correct.overrides[ctx]}",
+                f"mutant={dev_mutant.overrides[ctx]}",
+                f"correct_set={correct_set}", f"mutant_set={mutant_set}",
+            ))
+
+    if not violations:
+        _, violations = explore_b(max_depth=4, tie_policy=CLEAR,
+                                  device_cls=M2_NoBump)
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# M3: tie policy distinguishable
+# ---------------------------------------------------------------------------
+
+def mutant_m3():
+    """M3: tie policy is load-bearing — S==C must produce different verdicts.
+    Not a DeviceB mutation; tests the model function directly."""
+    reg = RegB(s=1, c=1, b=10)
+    frontier = 10
+    v_clear = override_set_b(reg, frontier, CLEAR)
+    v_set = override_set_b(reg, frontier, SET)
+    if v_clear == v_set:
+        return []
+    return [("tie-distinguishable", v_clear, v_set, reg, frontier)]
+
+
+# ---------------------------------------------------------------------------
+# M4: revert to delete-on-dominance compaction (drops the tombstone floor)
+# ---------------------------------------------------------------------------
+
+class M4_DeleteOnDominance(DeviceB):
+    """The pre-fix compaction rule: any dead/dominated register is deleted
+    entirely rather than reduced to the tombstone floor RegB(0, max(S,C), 0).
+    This makes counters reusable — a later local set/clear pair restarts
+    from S=0/C=0, so a delayed stale peer snapshot can dominate it on
+    replay. This is exactly the rule Thufir's pass-3 CRITICAL found live
+    at e453b3945."""
+    def _compact(self, reg, frontier_val, tie_policy):
+        if reg.s == 0 and reg.c == 0:
+            return None
+        if self._override_set(reg, frontier_val, tie_policy):
+            return reg
+        if frontier_val > reg.b:
+            return None
+        if reg.c > reg.s:
+            return RegB(s=0, c=reg.c, b=0)
+        if reg.c == reg.s and tie_policy == CLEAR:
+            return RegB(s=0, c=reg.c, b=0)
+        return reg
+
+
+def mutant_m4():
+    """M4: without the tombstone floor, compaction deletes the counter
+    ceiling instead of preserving it. Reproduce Thufir's exact witness
+    directly: RegB(3,0,10) at frontier=20 compacts to None under the old
+    rule (vs. RegB(0,3,0) under the fix); a subsequent local set+clear
+    reuses counters from zero; the stale ancestor then replays and
+    resurrects (S>C) under both tie policies.
+
+    Then confirm the explorer/deep-history suite also catches it (defense
+    in depth — a mutant that only fails a hand-built scenario would still
+    be a real bug, but the directed check is what's supposed to catch this
+    class per T2/T3)."""
+    violations = []
+    stale = RegB(s=3, c=0, b=10)
+    frontier_after = 20
+
+    for tie_policy in (CLEAR, SET):
+        dev = M4_DeleteOnDominance("d0")
+        dev.frontier["c0"] = 10
+        dev.overrides["c0"] = stale
+        dev.do_advance_frontier("c0", frontier_after)
+        dev.do_compact("c0", tie_policy)
+        if "c0" in dev.overrides:
+            continue  # old rule didn't drop it here; not the witness shape
+
+        dev.do_mark_unread("c0")   # S := 1, B := 20
+        dev.do_mark_read("c0", frontier_after)  # C := 2
+
+        stale_blob = {"contexts": {"ov_s:c0": stale.s, "ov_c:c0": stale.c, "ov_b:c0": stale.b}}
+        dev.receive_merge(stale_blob)
+        resurrected = dev.override_is_set("c0", tie_policy)
+
+        if resurrected:
+            violations.append((
+                "M4-delete-on-dominance-resurrection", tie_policy,
+                f"stale_ancestor={stale}", f"post_compact_reuse=(set,clear)",
+                f"final_reg={dev.overrides['c0']}", f"override_is_set={resurrected}",
+            ))
+
+    if not violations:
+        _, violations = test_deep_history_compaction(device_cls=M4_DeleteOnDominance)
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# M5: uint32 overflow bypass
+# ---------------------------------------------------------------------------
+
+def mutant_m5():
+    """M5: values outside uint32 range must fail legacy sanitization."""
+    blob = {"v": 1, "client_id": "x", "contexts": {
+        "ov_s:c0": 4294967296,
+        "ov_c:c0": 0,
+        "ov_b:c0": 10,
+    }}
+    sanitized = legacy_sanitize_blob(blob)
+    if "ov_s:c0" in sanitized["contexts"]:
+        return []
+    return [("overflow-rejected", blob["contexts"]["ov_s:c0"],
+             sanitized["contexts"])]
+
+
+# ---------------------------------------------------------------------------
+# M6: last-write-wins merge (breaks convergence)
+# ---------------------------------------------------------------------------
+
+class M6_LastWriteWins(DeviceB):
+    def _merge_reg(self, a, b):
+        if a is None:
+            return b
+        if b is None:
+            return a
+        return b
+
+
+def mutant_m6():
+    """M6: replace componentwise max with last-write-wins. Convergence must
+    break — different delivery orders produce different final states."""
+    _, violations = explore_b(max_depth=3, tie_policy=CLEAR,
+                              device_cls=M6_LastWriteWins)
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# M7: publish without canonicalization (reproduces Thufir's pass-1/2
+# CRITICAL — dead+dead merge resurrection)
+# ---------------------------------------------------------------------------
+
+class M7_PublishWithoutCanonicalization(DeviceB):
+    """Reverts `publish_blob` to serialize raw, uncompacted registers —
+    the exact pre-fix behavior Thufir's pass-1/2 CRITICAL exploited:
+    a dead register's baseline-relative death (or clear-count-relative
+    death) never gets folded into a globally-comparable ceiling before
+    hitting the wire, so two individually-dead registers can
+    componentwise-max-merge into a live join."""
+    def publish_blob(self, tie_policy=CLEAR):
+        blob_ctx = {escape_context_key(k): v for k, v in self.frontier.items()}
+        if not self.is_legacy:
+            for k, reg in self.overrides.items():
+                blob_ctx[f"ov_s:{k}"] = reg.s
+                blob_ctx[f"ov_c:{k}"] = reg.c
+                blob_ctx[f"ov_b:{k}"] = reg.b
+        return {"v": 1, "client_id": self.client_id, "contexts": blob_ctx}
+
+
+def mutant_m7():
+    """M7: publish-without-canonicalization must be caught by the
+    published-state merge-closure invariant — proving that invariant
+    has teeth. Reproduce Thufir's exact witness directly first (fast,
+    deterministic); fall back to the full search if the hand-built
+    scenario doesn't trigger under a given tie policy."""
+    violations = []
+    for tie_policy in (CLEAR, SET):
+        dev_a = M7_PublishWithoutCanonicalization("a")
+        dev_a.frontier["c0"] = 50
+        dev_a.overrides["c0"] = RegB(s=3, c=2, b=0)
+        dev_b = M7_PublishWithoutCanonicalization("b")
+        dev_b.frontier["c0"] = 100
+        dev_b.overrides["c0"] = RegB(s=1, c=2, b=100)
+
+        blob_a = dev_a.publish_blob(tie_policy)
+        blob_b = dev_b.publish_blob(tie_policy)
+
+        for first, second in [(blob_a, blob_b), (blob_b, blob_a)]:
+            recv = M7_PublishWithoutCanonicalization("recv")
+            recv.receive_merge(first)
+            recv.receive_merge(second)
+            if recv.override_is_set("c0", tie_policy):
+                violations.append((
+                    "M7-publish-without-canonicalization-resurrection",
+                    tie_policy, blob_a, blob_b, recv.overrides["c0"],
+                ))
+
+    if not violations:
+        _, violations = test_published_merge_closure(
+            device_cls=M7_PublishWithoutCanonicalization
+        )
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# M8: revert split_blob_into_slots to per-entry splitting
+# (violates the atomic-grouping rule — reproduces Thufir's pass-2/2 CRITICAL)
+# ---------------------------------------------------------------------------
+
+class M8_PerEntrySplit(DeviceB):
+    """Reverts `split_blob_into_slots` to a per-entry split that violates the
+    atomic-grouping rule by separating `ov_s:` + frontier from `ov_b:` + `ov_c:`.
+
+    This reproduces Thufir's exact transport witness:
+    - Slot 0: frontier key + `ov_s:` entry (the "partial set" slot)
+    - Slot 1: `ov_c:` + `ov_b:` entries
+
+    An observer receiving only slot 0 reconstructs `RegB(s=1, c=0, b=0)` at
+    `frontier=10`. Because `frontier(10) > b(0)`, the override is baseline-dead.
+    Canonical re-publication emits tombstone `RegB(0, 1, 0)`.  After full
+    eventual delivery (both original slots + transient tombstone), the merged
+    result is `RegB(s=1, c=1, b=10)` — dead under clear-wins — permanently
+    suppressing a live override.
+    """
+
+    def split_blob_into_slots(self, tie_policy=CLEAR, n_slots=2):
+        """Split by key type: frontier + ov_s: in slot 0, ov_b: + ov_c: in slot 1.
+        Violates the atomic-grouping rule by separating ov_s: from ov_b:."""
+        blob = self.publish_blob(tie_policy)
+        slots = [{"v": blob["v"], "client_id": blob["client_id"], "contexts": {}}
+                 for _ in range(n_slots)]
+        for wire_key, value in blob["contexts"].items():
+            if wire_key.startswith("ov_b:") or wire_key.startswith("ov_c:"):
+                # ov_b and ov_c go to slot 1 — separated from their ov_s: sibling
+                slots[1]["contexts"][wire_key] = value
+            else:
+                # frontier keys and ov_s: go to slot 0
+                slots[0]["contexts"][wire_key] = value
+        return slots
+
+
+def mutant_m8():
+    """M8: per-entry splitting must be caught by test_interleaved_delivery_grouping —
+    proving that the new interleaved-delivery test has teeth.
+
+    Reproduce Thufir's exact transport witness directly: source live
+    `RegB(1,0,10)` at frontier=10. Per-entry split puts frontier+`ov_s:c0`
+    in slot 0 and `ov_c:c0`+`ov_b:c0` in slot 1. An observer receiving only
+    slot 0 reconstructs `RegB(1,0,0)`, re-publishes tombstone `RegB(0,1,0)`.
+    Full merge including the transient: `RegB(1,1,10)` → inactive.
+
+    Confirmed by running test_interleaved_delivery_grouping with M8_PerEntrySplit;
+    the witness must be caught before resorting to the full suite."""
+    return test_interleaved_delivery_grouping(device_cls=M8_PerEntrySplit)
+
+
+# ---------------------------------------------------------------------------
+# M9: revert split_blob_into_slots to escaped-key grouping
+# (groups frontier by wire key instead of unescaped logical ID —
+# reproduces Thufir's round-2 CRITICAL)
+# ---------------------------------------------------------------------------
+
+class M9_EscapedKeyGrouping(DeviceB):
+    """Reverts `split_blob_into_slots` to group the frontier key by its
+    ESCAPED wire key rather than the unescaped logical context ID.
+
+    For a normal context like "c0", this is a no-op (escape_context_key("c0")
+    == "c0"), so M9 is identical to the correct model on normal contexts.
+    The defect only manifests when the raw context ID starts with a reserved
+    prefix — e.g. raw "ov_s:evil" escapes to frontier wire key "esc:ov_s:evil".
+    The ov_* sibling keys are keyed by the RAW suffix ("ov_s:evil"), while
+    the frontier is keyed by the escaped wire key ("esc:ov_s:evil") — two
+    identities for one logical context, so they land in different slots.
+
+    This reproduces Thufir's round-2 CRITICAL: across publication cycles an
+    observer can receive the new frontier slot (esc:ov_s:evil=10) plus the
+    stale old-cycle override slot (ov_s/ov_c/ov_b at b=0), reconstructing
+    RegB(s=1,c=0,b=0) at frontier=10 — baseline-dead — and emitting tombstone
+    RegB(0,1,0). Full eventual delivery merges to RegB(1,1,10) — dead under
+    clear-wins — permanently suppressing a live override.
+    """
+
+    def split_blob_into_slots(self, tie_policy=CLEAR, n_slots=2):
+        """Split by original (escaped) wire key identity — does not unescape
+        frontier keys before grouping, so escaped contexts split incorrectly."""
+        blob = self.publish_blob(tie_policy)
+        contexts = blob["contexts"]
+
+        groups = {}  # wire_key -> list of (wire_key, value)
+        for wire_key, value in contexts.items():
+            if wire_key.startswith("ov_s:"):
+                ctx = wire_key[5:]
+            elif wire_key.startswith("ov_c:"):
+                ctx = wire_key[5:]
+            elif wire_key.startswith("ov_b:"):
+                ctx = wire_key[5:]
+            else:
+                ctx = wire_key  # frontier: use escaped wire key as group ID (BUG)
+            groups.setdefault(ctx, []).append((wire_key, value))
+
+        slots = [{"v": blob["v"], "client_id": blob["client_id"], "contexts": {}}
+                 for _ in range(n_slots)]
+        for i, (_ctx, pairs) in enumerate(sorted(groups.items())):
+            slot = slots[i % n_slots]
+            for wire_key, value in pairs:
+                slot["contexts"][wire_key] = value
+        return slots
+
+
+def mutant_m9():
+    """M9: escaped-key grouping must be caught by test_escaped_context_slot_grouping —
+    proving that the escaped-context regression test has teeth.
+
+    For a context whose raw ID starts with a reserved prefix ("ov_s:evil"),
+    the frontier wire key is "esc:ov_s:evil" and the ov_* sibling keys are
+    "ov_s:ov_s:evil", "ov_c:ov_s:evil", "ov_b:ov_s:evil". The escaped-key
+    grouping treats "esc:ov_s:evil" (frontier) and "ov_s:evil" (ov_* suffix)
+    as different groups, splitting the register across slots.
+
+    Old/new slot-coordinate mixture across publication cycles then reproduces
+    the round-1 transport poison: partial reconstruction → false tombstone →
+    permanent false clear of a live override.
+
+    The test is parameterized to route through the "mismatched grouping" path
+    (else branch) when the M9 split puts frontier and siblings in different slots,
+    and the witness must be caught."""
+    return test_escaped_context_slot_grouping(device_cls=M9_EscapedKeyGrouping)
+
+
+# ---------------------------------------------------------------------------
+# Runner
+# ---------------------------------------------------------------------------
+
+def run_mutations():
+    mutants = [
+        ("M1: drop baseline dominance", mutant_m1),
+        ("M2: drop max(S,C)+1 bump", mutant_m2),
+        ("M3: tie policy distinguishable", mutant_m3),
+        ("M4: revert to delete-on-dominance compaction (reproduces pass-3 CRITICAL)", mutant_m4),
+        ("M5: uint32 overflow bypass", mutant_m5),
+        ("M6: last-write-wins merge", mutant_m6),
+        ("M7: publish without canonicalization (reproduces pass-1/2 CRITICAL)", mutant_m7),
+        ("M8: per-entry split violates atomic-grouping rule (reproduces pass-2/2 CRITICAL)", mutant_m8),
+        ("M9: escaped-key grouping splits escaped-ctx register across slots (reproduces round-2 CRITICAL)", mutant_m9),
+    ]
+
+    print("=" * 60)
+    print("Mutation harness — candidate B")
+    print("=" * 60)
+
+    caught = []
+    missed = []
+    for name, fn in mutants:
+        violations = fn()
+        if violations:
+            caught.append(name)
+            v = violations[0]
+            detail = str(v)[:200]
+            print(f"  CAUGHT: {name}")
+            print(f"    counterexample: {detail}")
+        else:
+            missed.append(name)
+            print(f"  MISSED: {name}")
+
+    print(f"\nCaught {len(caught)}/{len(mutants)} mutants")
+    if missed:
+        print(f"MISSED: {missed}")
+    print("=" * 60)
+    return len(missed) == 0
+
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(0 if run_mutations() else 1)
diff --git a/docs/linux-rendering-troubleshooting.md b/docs/linux-rendering-troubleshooting.md
new file mode 100644
index 0000000000..1e09ef1aca
--- /dev/null
+++ b/docs/linux-rendering-troubleshooting.md
@@ -0,0 +1,135 @@
+# Linux Rendering Troubleshooting
+
+This guide covers the most common rendering failures on Linux and how to resolve them. It covers both the AppImage distribution and native package installs (`deb`, `rpm`).
+
+## Symptoms and fixes at a glance
+
+| Symptom | Likely cause | Fix |
+|---------|-------------|-----|
+| Blank or transparent window, then `SIGABRT` with `colrv1_configure_skpaint` in the output | COLRv1 color emoji font (AppImage only) | Upgrade to the latest AppImage (v0.5.2+) |
+| Blank window on startup, no crash output | dmabuf renderer incompatibility (NVIDIA or AppImage) | `WEBKIT_DISABLE_DMABUF_RENDERER=1 ./Buzz.AppImage` or `--safe-rendering` |
+| Blank window on any hardware, no crash output | Unknown GPU/driver combination | `--safe-rendering` flag (see below) |
+
+---
+
+## Crash: `colrv1_configure_skpaint` assertion abort (AppImage)
+
+**Affected distributions:** Fedora 40+ and any distro shipping Google's Noto Color Emoji in COLRv1 format (`Noto-COLRv1.ttf`). Issues [#2548](https://github.com/block/buzz/issues/2548), [#2982](https://github.com/block/buzz/issues/2982).
+
+**Symptom:** Buzz starts, the window appears briefly (or stays blank), then the process aborts with output like:
+
+```
+././/include/c++/12/bits/stl_vector.h:1123: ... colrv1_configure_skpaint ...:
+Assertion '__n < this->size()' failed.
+```
+
+**Root cause:** The AppImage bundles WebKitGTK compiled against FreeType 2.11.1 (Ubuntu 22.04's version), but `libfreetype.so.6` is not bundled — WebKit loads the host's FreeType at runtime instead. FreeType 2.13.0 (2023-02-09) added a field to `FT_ColorStopIterator`, growing the struct from 16 to 20 bytes. On Fedora 40+ hosts (FreeType ≥ 2.13), the struct-layout mismatch corrupts color-stop index arithmetic inside Skia's COLRv1 renderer, producing the assertion abort.
+
+**Fix:** Upgrade to the latest AppImage (v0.5.2+). The build container was bumped to `ubuntu:24.04` ([#3602](https://github.com/block/buzz/pull/3602)), which ships FreeType 2.13.2. The compiled layout now matches every crash-affected host (FreeType ≥ 2.13), eliminating the ABI mismatch.
+
+**AppImage glibc floor (v0.5.2+):** The `ubuntu:24.04` build raises the AppImage's minimum glibc requirement:
+
+| AppImage version | glibc floor | Oldest supported AppImage distro |
+|---|---|---|
+| v0.5.1 and earlier | 2.35 | Ubuntu 22.04 LTS, Debian 12 |
+| v0.5.2+ | 2.39 | Ubuntu 24.04 LTS, Fedora 40+ |
+
+If you are on **Ubuntu 22.04 LTS or Debian 12**, upgrade to the latest **`.deb`/`.rpm`** package instead — native packages use the system WebKit and are unaffected by this change.
+
+**Workaround (before upgrading):** Add a fontconfig override that removes color-format fonts from Buzz's view:
+
+```bash
+mkdir -p ~/.config/buzz-fontconfig
+cat > ~/.config/buzz-fontconfig/fonts.conf <<'XML'
+<?xml version="1.0"?>
+<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
+<fontconfig>
+  <include ignore_missing="yes">/etc/fonts/fonts.conf</include>
+  <selectfont>
+    <rejectfont>
+      <pattern>
+        <patelt name="color"><bool>true</bool></patelt>
+      </pattern>
+    </rejectfont>
+  </selectfont>
+</fontconfig>
+XML
+FONTCONFIG_FILE=~/.config/buzz-fontconfig/fonts.conf ./Buzz_*.AppImage
+```
+
+**Native packages (`deb`/`rpm`):** The COLRv1 crash ([#2548](https://github.com/block/buzz/issues/2548), [#2982](https://github.com/block/buzz/issues/2982)) is AppImage-only — native packages use the system WebKit, which has a consistent FreeType ABI, and are not affected.
+
+---
+
+## Blank window on startup (no crash): dmabuf renderer
+
+**Affected hardware:** NVIDIA GPUs (proprietary and nouveau drivers) and AppImage installs on any GPU. Issue [#2338](https://github.com/block/buzz/issues/2338).
+
+**Symptom:** Buzz launches without any crash or assertion output, but the window is blank or invisible. The process is running (`ps aux | grep buzz`), but nothing renders.
+
+**Root cause:** WebKitGTK's dmabuf zero-copy buffer path is incompatible with some GPU/driver/compositor combinations. The WebKit child process silently fails to paint.
+
+**Fix (shipped automatically starting with the first release containing [#3271](https://github.com/block/buzz/pull/3271) (v0.5.1)):** Buzz sets `WEBKIT_DISABLE_DMABUF_RENDERER=1` automatically before WebKit initializes when it detects an NVIDIA GPU (`/sys/class/drm` vendor ID `0x10de`) or when running as an AppImage. This restores a slightly slower shared-memory rendering path that works universally.
+
+**If automatic detection doesn't help (`--safe-rendering`):** Pass `--safe-rendering` to force both `WEBKIT_DISABLE_DMABUF_RENDERER=1` and `WEBKIT_DISABLE_COMPOSITING_MODE=1` for that launch:
+
+```bash
+./Buzz_*.AppImage --safe-rendering
+# or for a native install:
+buzz-desktop --safe-rendering
+```
+
+`--safe-rendering` is a per-launch flag — it is not remembered between runs. If it fixes your issue, you can make it permanent by setting the env vars yourself:
+
+```bash
+# ~/.bashrc or ~/.profile
+export WEBKIT_DISABLE_DMABUF_RENDERER=1
+```
+
+**Conflict detection:** If you set a WebKit variable in your environment and also pass `--safe-rendering`, Buzz will refuse to start and print exactly which variable conflicts. Unset the conflicting variable or drop the flag.
+
+---
+
+## AMD RDNA4 / transparent window
+
+**Affected hardware:** AMD RDNA4 GPUs (RX 9000 series) with the `radv` driver. Issue [#2643](https://github.com/block/buzz/issues/2643).
+
+**Symptom:** The Buzz window is transparent or renders with graphical corruption on AMD RDNA4 hardware.
+
+**Workaround (verified by reporter):** Set these three variables before launching Buzz:
+
+```bash
+export GDK_BACKEND=x11
+export WEBKIT_DISABLE_DMABUF_RENDERER=1
+export WEBKIT_SKIA_ENABLE_CPU_RENDERING=1
+./Buzz_*.AppImage
+# or for native:
+buzz-desktop
+```
+
+- `WEBKIT_SKIA_ENABLE_CPU_RENDERING=1` forces Skia to use CPU rendering, bypassing the RDNA4 Skia/radv paint failure.
+- `GDK_BACKEND=x11` avoids the blank window that appears when running under a Plasma-Wayland compositor.
+- `WEBKIT_DISABLE_DMABUF_RENDERER=1` prevents post-first-paint transparency from the dmabuf renderer.
+
+A dedicated fix for RDNA4 detection is being tracked in [#2643](https://github.com/block/buzz/issues/2643).
+
+---
+
+## Diagnosing an unrecognised crash
+
+If none of the above match your situation:
+
+1. Run Buzz from a terminal and capture the output:
+   ```bash
+   ./Buzz_*.AppImage 2>&1 | tee buzz-crash.log
+   ```
+
+2. Check for a core dump:
+   ```bash
+   coredumpctl list | tail
+   coredumpctl info <PID>
+   ```
+
+3. Try `--safe-rendering` first — if it resolves the issue, it's a WebKit rendering incompatibility and the crash log will help narrow down which driver is involved.
+
+4. File a [new issue](https://github.com/block/buzz/issues/new) with your distro, GPU, driver version, and the terminal output.
diff --git a/docs/nips/NIP-AP.md b/docs/nips/NIP-AP.md
index b990f55bef..ad23d92282 100644
--- a/docs/nips/NIP-AP.md
+++ b/docs/nips/NIP-AP.md
@@ -10,7 +10,7 @@ This NIP defines `kind:30175` persona events — public, addressable definitions
 
 ## Kind
 
-This NIP claims `kind:30175` for agent persona definitions. It is in the NIP-33 parameterized replaceable range (30000–39999) per [NIP-01](01.md): addressed by `(pubkey, kind, d_tag)`, with only the latest event per address retained.
+This NIP claims `kind:30175` for agent persona definitions and `kind:30178` for the shareable team-catalog projection (see "Team catalog projection: kind:30178"). Both are in the NIP-33 parameterized replaceable range (30000–39999) per [NIP-01](01.md): addressed by `(pubkey, kind, d_tag)`, with only the latest event per address retained.
 
 A dedicated kind (rather than encoding personas as NIP-78 `kind:30078` "Application-specific Data") is taken for the same reasons as [NIP-AE](NIP-AE.md): (1) it isolates this NIP's address space from any other application using the same pubkey — persona slugs cannot collide with another app's `d` tag choices; (2) it lets observers, indexers, and unknown-kind viewers identify persona events from the kind alone, without parsing content as a namespace demultiplexer.
 
@@ -162,6 +162,8 @@ Owners MAY publish [NIP-09](09.md) deletion requests targeting persona events. A
 
 A subsequent write with a later timestamp resurrects the slug under NIP-33 replacement semantics.
 
+The same applies to `kind:30178`: a deletion request SHOULD carry `["k", "30178"]` and the `a`-tag identifier `30178:<pubkey_o>:<team-id>`. Unsharing is distinct from deletion — it is a newer valid head at the same coordinate published *without* the `shared` tag, which keeps the projection readable to its author while retracting it from foreign readers.
+
 ## Relationships to other NIPs
 
 ### NIP-AE (Agent Engrams)
@@ -216,6 +218,29 @@ surface per-event errors.
 
 Agents spawned from a persona carry [NIP-OA](NIP-OA.md) owner attestation — an `auth` tag proving that `pubkey_o` authorized the agent's key. The persona event itself does not contain attestation; it is the *definition* from which attestation is issued at spawn time.
 
+## Team catalog projection: kind:30178
+
+Kind `30178` is the **shareable projection of a team**: owner-authored, parameterized replaceable, addressed by `(pubkey_o, 30178, d)` where `d` is the team's stable local id. Its `content` is a versioned JSON body carrying sanitized team fields plus ordered, *embedded* member definition projections. The content schema is defined by the client that publishes it; this section specifies only the envelope and the relay's contract.
+
+```jsonc
+{
+  "kind": 30178,
+  "pubkey": "<pubkey_o>",
+  "created_at": <unix_seconds>,
+  "tags": [
+    ["d", "<team-id>"],
+    ["shared", "true"]     // optional; presence opts the projection into community reads
+  ],
+  "content": "<json_body>"
+}
+```
+
+**Why a separate kind rather than a `shared` tag on the team event (kind:30176).** A team's members are `kind:30175` definitions, which are author-only unless individually shared — so a foreign reader of a shared team could never hydrate its members. Kind `30178` embeds the member projections instead of referencing them: the share is atomic, it covers built-in members that have no `30175` head at all, it is immune to local-id/`d`-tag divergence, and an unshared `30175` stays private. Kind `30176`'s wire body is untouched, so device sync keeps its contract.
+
+**The `d` tag is a team id, not a persona slug.** It is either a UUID or a built-in identifier such as `builtin-team:welcome`. The colon is illegal under the persona slug grammar, and rewriting ids to fit would break NIP-33 addressing against the team's own `kind:30176` head — so the relay applies a laxer rule (see below) to `30178` than to `30175`.
+
+**Content carries only sanitized fields.** No environment variables, no `respond_to` allowlist pubkeys, no source or local ids, no filesystem paths, no secrets. Sharing a team makes the team's and every member's instructions community-readable plaintext.
+
 ## Relay behavior
 
 ### Ingest validation
@@ -226,10 +251,20 @@ Agents spawned from a persona carry [NIP-OA](NIP-OA.md) owner attestation — an
 - The relay MUST enforce that the `d` tag is non-empty (standard NIP-33 requirement for parameterized replaceable events).
 - The relay MUST enforce shared-tag shape: if a `shared` tag is present, it MUST consist of **exactly two elements** — `["shared", "true"]`. Extra elements (e.g. `["shared","true","extra"]`), wrong values (`["shared","false"]`), missing values (`["shared"]`), or duplicate `shared` tags are all rejected with `invalid:`. The two-element exact-shape constraint is required so that the relay's SQL visibility clause (`tags @> '[["shared","true"]]'`) never matches a stored malformed tag via JSONB containment supersets.
 
+### Ingest validation: kind:30178
+
+Kind `30178` is stored globally and its content is unvalidated, exactly as for `30175`. The envelope rules differ in one respect — the `d` grammar:
+
+- The relay MUST enforce the same `shared`-tag exact shape as `30175`, for the same reason: the read gate and the SQL containment clause must agree on every stored event.
+- The relay MUST enforce **exactly one** `d` tag whose value is non-empty, at most 64 characters, and free of Unicode control characters and whitespace. Tags are counted by their first element, so a valueless `["d"]` counts toward the total and fails the value check on its own — otherwise `["d"]` alongside `["d","<team-id>"]` would pass, and a consumer that reads `["d"]` as an empty-valued first `d` tag would address the event at `""` while this relay addresses it at `<team-id>`. Without the non-empty check, generic NIP-33 storage maps a missing or empty `d` to the empty coordinate, collapsing every team into the single `(pubkey_o, 30178, "")` slot — last-write-wins data loss. The character bound keeps the value usable as a NIP-33 coordinate and as a log field.
+- The relay MUST NOT apply the persona slug grammar to a `30178` `d` tag; team ids legitimately contain characters (notably `:`) that the slug grammar forbids.
+
 ### Access control: author-only-unless-shared
 
 Kind `30175` uses **shared-tag-gated read semantics** to protect system prompts and `respond_to_allowlist` from being visible to all community members as a side-effect of device sync.
 
+The gate is kind-generic: the relay applies it to every kind in `SHARED_GATED_KINDS` (`buzz-core/src/kind.rs`), currently `30175` and the `30178` team-catalog projection described below. The rules and enforcement surfaces are identical for each member kind.
+
 **Rules:**
 
 | Event state | Author reads | Foreign reads |
@@ -239,13 +274,13 @@ Kind `30175` uses **shared-tag-gated read semantics** to protect system prompts
 
 These rules are enforced at the following relay read surfaces (content and event existence are withheld on all of them):
 
-- **REQ historical delivery** — foreign requests silently omit unshared persona events, even in mixed-kind filters (`{kinds:[30175,9]}`). The visibility check is applied **before `ORDER BY … LIMIT`** at the SQL level (`persona_reader` field in `EventQuery`), so a page of newer private personas cannot starve an older shared persona off the candidate set — the catalog's primary all-author query pattern is correctly served.
+- **REQ historical delivery** — foreign requests silently omit unshared persona events, even in mixed-kind filters (`{kinds:[30175,9]}`). The visibility check is applied **before `ORDER BY … LIMIT`** at the SQL level (`shared_gated_reader` field in `EventQuery`), so a page of newer private personas cannot starve an older shared persona off the candidate set — the catalog's primary all-author query pattern is correctly served.
 - **NIP-01 `ids` lookup** — knowing an event id does NOT grant access to an unshared persona. The result gate returns nothing.
 - **Live fan-out** — unshared personas are delivered only to the author's connections. Shared personas fan out community-wide.
-- **COUNT** — the fast SQL `count_events()` path is bypassed when the filter can match `kind:30175`. A per-event fallback applies the shared-tag check, preventing existence-leak via COUNT.
-- **NIP-98 HTTP bridge `/query`** — the same per-event visibility check is applied to the catchall post-processing loop. The SQL-level `persona_reader` clause also applies before `LIMIT`, preventing older shared personas from being starved by newer private ones on paginated catalog queries. A foreign caller POSTing `{kinds:[30175],authors:[victim]}` or a kindless `{ids:[...]}` filter to `/query` receives no unshared persona content.
-- **NIP-98 HTTP bridge `/count`** — `needs_persona_filtering` forces the per-event fallback path for any filter that can match `kind:30175`; the fast SQL `count_events()` path is not used. Both the channel-scoped and unconstrained fallback loops apply `event_visible_to_reader`, preventing existence-leak via COUNT over HTTP.
-- **FTS (NIP-50 search) and `/search`** — kind `30175` is not in the relay's FTS allowlist (migration 8 indexes only kinds `0, 9, 40002, 45001, 45003`); no FTS result can contain an unshared persona. A defense-in-depth check is also present in the bridge search result loop so that a future FTS allowlist change cannot silently reopen the bypass.
+- **COUNT** — the fast SQL `count_events()` path is bypassed when the filter can match a shared-gated kind. A per-event fallback applies the shared-tag check, preventing existence-leak via COUNT.
+- **NIP-98 HTTP bridge `/query`** — the same per-event visibility check is applied to the catchall post-processing loop. The SQL-level `shared_gated_reader` clause also applies before `LIMIT`, preventing older shared personas from being starved by newer private ones on paginated catalog queries. A foreign caller POSTing `{kinds:[30175],authors:[victim]}` or a kindless `{ids:[...]}` filter to `/query` receives no unshared persona content.
+- **NIP-98 HTTP bridge `/count`** — `needs_shared_gate_filtering` forces the per-event fallback path for any filter that can match a shared-gated kind; the fast SQL `count_events()` path is not used. Both the channel-scoped and unconstrained fallback loops apply `event_visible_to_reader`, preventing existence-leak via COUNT over HTTP.
+- **FTS (NIP-50 search) and `/search`** — no shared-gated kind is in the relay's FTS allowlist (migration 8 indexes only kinds `0, 9, 40002, 45001, 45003`); no FTS result can contain an unshared event. A defense-in-depth check is also present in the bridge search result loop so that a future FTS allowlist change cannot silently reopen the bypass.
 
 **Device sync is unaffected.** The sync subscription (`{kinds:[30175], authors:[self]}`) reads the author's own events, which are always returned regardless of shared state.
 
@@ -263,6 +298,7 @@ These rules are enforced at the following relay read surfaces (content and event
 - **Slug collision across pubkeys.** Two different owners can publish personas with the same slug. Clients MUST always scope queries by author pubkey, not just slug.
 - **Metadata exposure.** The `(pubkey, kind:30175, slug)` triple reveals persona existence. Event timestamps reveal edit history.
 - **No owner write authority over agents.** Persona events define *what* an agent should be; they do not grant runtime control over a running agent. The agent consumes the persona at spawn time. Updates to the persona event do not automatically propagate to running agents.
+- **Sharing a team shares every member's instructions.** A `kind:30178` head carrying `["shared","true"]` exposes the team's own fields *and* the embedded projection of every member — including members whose own `kind:30175` heads are unshared and therefore still private. Clients MUST make this explicit at the point of sharing; the relay cannot infer it.
 
 ## Reference test vectors
 
diff --git a/docs/nips/NIP-MP.fixtures.json b/docs/nips/NIP-MP.fixtures.json
new file mode 100644
index 0000000000..cfc570ec65
--- /dev/null
+++ b/docs/nips/NIP-MP.fixtures.json
@@ -0,0 +1,1462 @@
+{
+  "$comment": "NIP-MP conformance fixtures \u2014 the shared ingest contract for the relay validator, the Rust event builder, and the TypeScript event builder. Each case carries an UNSIGNED template: consumers sign it with their own test key, because signing fixes the event id and signature and a stored literal would not survive re-serialization. `expect` is the ingest outcome. `reject_rules` lists the validation rules that may fire; an implementation must reject for one of them, so it cannot pass by rejecting for an unrelated reason. This file covers single-event accept/reject only; the client-side fold has its own oracle in NIP-MP.fold-fixtures.json. Spec: docs/nips/NIP-MP.md.",
+  "version": 1,
+  "kind": 30621,
+  "member_cap": 64,
+  "owners": {
+    "a": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "b": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+  },
+  "cases": [
+    {
+      "name": "valid_minimal",
+      "expect": "accept",
+      "note": "Only the identity tag. A project needs nothing but a `d` tag to be a valid addressable container.",
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "valid_full",
+      "expect": "accept",
+      "note": "Every specified tag present, with two members owned by two different pubkeys \u2014 the cross-owner grouping that motivates the kind.",
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "name",
+            "Platform"
+          ],
+          [
+            "description",
+            "Relay, desktop, and mobile for the platform team."
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+          ],
+          [
+            "a",
+            "30617:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb:buzz-infra"
+          ],
+          [
+            "buzz-channel",
+            "3580ca9b-47b4-4af9-b22a-1068778f26c6"
+          ],
+          [
+            "buzz-visibility",
+            "listed"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "valid_zero_members",
+      "expect": "accept",
+      "note": "Zero-member project. Legal at the protocol layer: it is the natural state after removing a final member and carries only bounded metadata.",
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "name",
+            "Platform"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "valid_unlisted",
+      "expect": "accept",
+      "note": "Explicitly unlisted container. Accepted at ingest; the fold excludes it from listing eligibility, so its member keeps its implicit card.",
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "skunkworks"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+          ],
+          [
+            "buzz-visibility",
+            "unlisted"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "valid_member_cap_boundary",
+      "expect": "accept",
+      "note": "Exactly 64 distinct member `a` tags \u2014 the cap is inclusive. Paired with `invalid_member_cap_exceeded` to pin the boundary from both sides.",
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "wide"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-00"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-01"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-02"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-03"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-04"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-05"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-06"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-07"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-08"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-09"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-10"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-11"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-12"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-13"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-14"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-15"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-16"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-17"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-18"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-19"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-20"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-21"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-22"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-23"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-24"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-25"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-26"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-27"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-28"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-29"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-30"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-31"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-32"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-33"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-34"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-35"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-36"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-37"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-38"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-39"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-40"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-41"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-42"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-43"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-44"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-45"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-46"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-47"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-48"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-49"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-50"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-51"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-52"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-53"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-54"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-55"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-56"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-57"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-58"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-59"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-60"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-61"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-62"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-63"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "valid_same_dtag_two_owners",
+      "expect": "accept",
+      "note": "Two members share a repo `d` segment under different owners (the NIP-34 fork case). Identity is the whole coordinate, so these are not duplicates.",
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "forks"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+          ],
+          [
+            "a",
+            "30617:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb:buzz"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "valid_member_dtag_contains_colon",
+      "expect": "accept",
+      "note": "Repo `d` segment contains a colon. The coordinate splits into at most three parts, so the third part is the repo `d` value verbatim \u2014 `buzz:infra` here. Splitting on every colon instead would make any repo with a colon in its `d` tag unaddressable by a project.",
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz:infra"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "valid_uninterpreted_metadata_values",
+      "expect": "accept",
+      "note": "`buzz-channel` is not a UUID and `buzz-visibility` is an unrecognized token. Ingest bounds metadata cardinality and length but does not interpret these values \u2014 matching how kind:30617 carries the same two tags. Client-side fallbacks for both are normative in the spec's Metadata interpretation section: an unresolvable channel renders the project without one, and an unrecognized visibility is treated as `listed`.",
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "buzz-channel",
+            "not-a-uuid"
+          ],
+          [
+            "buzz-visibility",
+            "chartreuse"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "valid_unknown_tag_ignored",
+      "expect": "accept",
+      "note": "An unrecognized tag is neither rejected nor interpreted \u2014 unknown tags are ignored, not fatal.",
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "future-metadata",
+            "preserve-me"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "valid_member_relay_hint",
+      "expect": "accept",
+      "note": "Member `a` tag carries NIP-01's optional third element, a relay hint. Ingest validates the tag's arity and the coordinate in element 1, so the hint's content is neither parsed nor a rejection cause; a client MAY use it to resolve an otherwise unavailable member.",
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+            "wss://relay.example.com"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "valid_non_empty_content",
+      "expect": "accept",
+      "note": "`content` holds a value. Writers should emit the empty string, but readers and relays must ignore whatever is there \u2014 a non-empty `content` is not a rejection cause and carries no semantics.",
+      "template": {
+        "kind": 30621,
+        "content": "ignored by every consumer",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_d_missing",
+      "expect": "reject",
+      "note": "No `d` tag. Without one the event collapses into the `(pubkey, 30621, \"\")` slot and silently last-write-wins over an unrelated project.",
+      "reject_rules": [
+        "d-cardinality"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "name",
+            "Platform"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_d_multiple",
+      "expect": "reject",
+      "note": "Two `d` tags. Which one addresses the event is reader-dependent; reject rather than pick.",
+      "reject_rules": [
+        "d-cardinality"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "d",
+            "infra"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_d_empty",
+      "expect": "reject",
+      "note": "Present but empty `d`. Same slot-collapse hazard as a missing `d`.",
+      "reject_rules": [
+        "d-empty"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            ""
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_member_duplicate",
+      "expect": "reject",
+      "note": "The same canonical coordinate twice. A signed event cannot be normalized in place, so the relay refuses it rather than store a head every consumer must defensively dedupe.",
+      "reject_rules": [
+        "member-duplicate"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_member_duplicate_differing_relay_hints",
+      "expect": "reject",
+      "note": "The same coordinate twice under different relay hints. Duplicate detection compares the coordinate alone, so differing hints do not make these distinct members; a validator that compares whole tag arrays would wrongly accept this.",
+      "reject_rules": [
+        "member-duplicate"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+            "wss://relay-one.example.com"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+            "wss://relay-two.example.com"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_member_cap_exceeded",
+      "expect": "reject",
+      "note": "65 distinct member `a` tags \u2014 one past the inclusive cap of 64.",
+      "reject_rules": [
+        "member-cap"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "wide"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-00"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-01"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-02"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-03"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-04"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-05"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-06"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-07"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-08"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-09"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-10"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-11"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-12"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-13"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-14"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-15"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-16"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-17"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-18"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-19"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-20"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-21"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-22"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-23"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-24"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-25"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-26"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-27"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-28"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-29"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-30"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-31"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-32"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-33"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-34"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-35"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-36"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-37"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-38"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-39"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-40"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-41"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-42"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-43"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-44"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-45"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-46"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-47"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-48"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-49"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-50"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-51"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-52"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-53"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-54"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-55"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-56"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-57"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-58"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-59"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-60"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-61"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-62"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-63"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-64"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_member_cap_exceeded_by_duplicates",
+      "expect": "reject",
+      "note": "65 member `a` tags naming 33 distinct coordinates. The spec evaluates the cap before the duplicate set is built, so `member-cap` is the required rule even though the event also carries duplicates; a validator that reports `member-duplicate` here has built a set whose size is bounded only by the frame limit.",
+      "reject_rules": [
+        "member-cap"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "wide"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-00"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-00"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-01"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-01"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-02"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-02"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-03"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-03"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-04"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-04"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-05"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-05"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-06"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-06"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-07"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-07"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-08"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-08"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-09"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-09"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-10"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-10"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-11"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-11"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-12"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-12"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-13"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-13"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-14"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-14"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-15"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-15"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-16"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-16"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-17"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-17"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-18"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-18"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-19"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-19"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-20"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-20"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-21"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-21"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-22"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-22"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-23"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-23"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-24"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-24"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-25"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-25"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-26"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-26"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-27"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-27"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-28"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-28"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-29"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-29"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-30"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-30"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-31"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-31"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:repo-32"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_member_tag_arity_four_elements",
+      "expect": "reject",
+      "note": "Member `a` tag carries a fourth element past the relay hint. Its coordinate is valid, so this rejects on tag shape rather than on the coordinate: NIP-01's `a` grammar is two or three elements, and a validator that reads element 1 and ignores the rest would accept unbounded unvalidated data in a position no consumer reads.",
+      "reject_rules": [
+        "member-tag-arity"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+            "wss://relay.example.com",
+            "unexpected"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_member_kind_prefix",
+      "expect": "reject",
+      "note": "Coordinate names kind 30618 (repo state) rather than 30617 (repo announcement). A project groups repositories, not their ref state.",
+      "reject_rules": [
+        "member-coordinate-malformed"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "a",
+            "30618:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_member_owner_not_hex",
+      "expect": "reject",
+      "note": "Owner segment is 64 characters but not hex.",
+      "reject_rules": [
+        "member-coordinate-malformed"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "a",
+            "30617:zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz:buzz"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_member_owner_uppercase",
+      "expect": "reject",
+      "note": "Owner segment is uppercase hex. `#a` tag matching is byte-exact, so an uppercase head is invisible to the lowercase-coordinate queries every reader issues.",
+      "reject_rules": [
+        "member-coordinate-malformed"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "a",
+            "30617:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA:buzz"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_member_owner_wrong_length",
+      "expect": "reject",
+      "note": "Owner segment is 63 hex characters.",
+      "reject_rules": [
+        "member-coordinate-malformed"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_member_dtag_empty",
+      "expect": "reject",
+      "note": "Coordinate has an empty repo `d` segment \u2014 it addresses no announceable repository.",
+      "reject_rules": [
+        "member-coordinate-malformed"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_member_missing_segment",
+      "expect": "reject",
+      "note": "Coordinate has two segments instead of three.",
+      "reject_rules": [
+        "member-coordinate-malformed"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "a",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_metadata_duplicate_name",
+      "expect": "reject",
+      "note": "Two `name` tags. Reader-dependent display name; reject rather than pick.",
+      "reject_rules": [
+        "metadata-cardinality"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "name",
+            "Platform"
+          ],
+          [
+            "name",
+            "Infra"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_metadata_duplicate_channel",
+      "expect": "reject",
+      "note": "Two `buzz-channel` tags. Which channel the project links to would be reader-dependent.",
+      "reject_rules": [
+        "metadata-cardinality"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "buzz-channel",
+            "3580ca9b-47b4-4af9-b22a-1068778f26c6"
+          ],
+          [
+            "buzz-channel",
+            "00000000-0000-0000-0000-000000000000"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_metadata_name_too_long",
+      "expect": "reject",
+      "note": "`name` value exceeds 256 bytes.",
+      "reject_rules": [
+        "metadata-length"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "name",
+            "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_metadata_description_too_long",
+      "expect": "reject",
+      "note": "`description` value exceeds 2048 bytes.",
+      "reject_rules": [
+        "metadata-length"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "description",
+            "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_metadata_channel_too_long",
+      "expect": "reject",
+      "note": "`buzz-channel` value exceeds 256 bytes. Paired with `invalid_metadata_visibility_too_long` so each bound is exercised by an event whose other metadata is valid \u2014 neither check can hide behind the other's rejection.",
+      "reject_rules": [
+        "metadata-length"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "buzz-channel",
+            "ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "invalid_metadata_visibility_too_long",
+      "expect": "reject",
+      "note": "`buzz-visibility` value exceeds 256 bytes. Ingest does not interpret the token, but it must still bound its length.",
+      "reject_rules": [
+        "metadata-length"
+      ],
+      "template": {
+        "kind": 30621,
+        "content": "",
+        "tags": [
+          [
+            "d",
+            "platform"
+          ],
+          [
+            "buzz-visibility",
+            "vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv"
+          ]
+        ]
+      }
+    }
+  ]
+}
diff --git a/docs/nips/NIP-MP.fold-fixtures.json b/docs/nips/NIP-MP.fold-fixtures.json
new file mode 100644
index 0000000000..c036646c34
--- /dev/null
+++ b/docs/nips/NIP-MP.fold-fixtures.json
@@ -0,0 +1,527 @@
+{
+  "$comment": "NIP-MP fold fixtures \u2014 the shared oracle for the client-side fold in docs/nips/NIP-MP.md (\"The fold\" and \"Required fold cases\"). Every case in the spec's required-cases table appears here, keyed by `spec_case`. Inputs are SEMANTIC, not signed envelopes: a repository or project is named by its coordinate plus the fold's inputs (signer, members, `maintainers`, visibility, viewer-hidden, deletion). Signing and envelope validation are the ingest contract and live in NIP-MP.fixtures.json; this file assumes every input is a valid, accepted head and tests only the placement the fold derives from it. `expect.containers` lists each rendered project with the members rendered inside it; `expect.implicit_cards` lists the repositories that additionally render as their own single-repository cards. EVERY collection in `expect` is compared as a set \u2014 the containers, each container's `members`, and the implicit cards alike \u2014 because the fold fixes placement, not order. `render` is `resolved` when the member coordinate resolves to a live head and `unavailable` when it does not. `state` is `live` or `deleted`; `visibility` is `listed` or `unlisted`; a value of `viewer_hidden` is a local, per-viewer decision, not event state.",
+  "version": 1,
+  "project_kind": 30621,
+  "repository_kind": 30617,
+  "pubkeys": {
+    "alice": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "bob": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+    "carol": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+  },
+  "cases": [
+    {
+      "name": "owner_project_claims_own_repository",
+      "spec_case": "Owner's own project lists their repository",
+      "note": "The signer is the member coordinate's owner, so the project claims the repository and step 3 suppresses its implicit card.",
+      "repositories": [
+        {
+          "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "projects": [
+        {
+          "coordinate": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:platform",
+          "signer": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "members": [
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+          ],
+          "visibility": "listed",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "expect": {
+        "containers": [
+          {
+            "project": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:platform",
+            "members": [
+              {
+                "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+                "render": "resolved"
+              }
+            ]
+          }
+        ],
+        "implicit_cards": []
+      }
+    },
+    {
+      "name": "stranger_project_does_not_claim",
+      "spec_case": "Stranger's project lists someone else's repository",
+      "note": "Bob is neither the owner nor a maintainer, so his project renders the member but claims nothing. The repository keeps its own card: an unendorsed grouping cannot pull a repository out of where its owner expects to find it.",
+      "repositories": [
+        {
+          "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "projects": [
+        {
+          "coordinate": "30621:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb:borrowed",
+          "signer": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+          "members": [
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+          ],
+          "visibility": "listed",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "expect": {
+        "containers": [
+          {
+            "project": "30621:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb:borrowed",
+            "members": [
+              {
+                "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+                "render": "resolved"
+              }
+            ]
+          }
+        ],
+        "implicit_cards": [
+          "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+        ]
+      }
+    },
+    {
+      "name": "maintainer_signer_claims",
+      "spec_case": "Project signer is in the member repository's `maintainers` tag",
+      "note": "Claim authority is read from the member repository's own head, not from ownership alone. Carol is listed in `maintainers`, so her project claims the repository exactly as the owner's would.",
+      "repositories": [
+        {
+          "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+          "state": "live",
+          "viewer_hidden": false,
+          "maintainers": [
+            "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+          ]
+        }
+      ],
+      "projects": [
+        {
+          "coordinate": "30621:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc:platform",
+          "signer": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+          "members": [
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+          ],
+          "visibility": "listed",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "expect": {
+        "containers": [
+          {
+            "project": "30621:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc:platform",
+            "members": [
+              {
+                "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+                "render": "resolved"
+              }
+            ]
+          }
+        ],
+        "implicit_cards": []
+      }
+    },
+    {
+      "name": "two_claiming_projects_both_render_member",
+      "spec_case": "Repository is a member of two projects that both claim it",
+      "note": "Multiple membership is not a move. The repository renders inside both containers and has no implicit card, and it appears once per container rather than twice in either.",
+      "repositories": [
+        {
+          "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "projects": [
+        {
+          "coordinate": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:platform",
+          "signer": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "members": [
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+          ],
+          "visibility": "listed",
+          "state": "live",
+          "viewer_hidden": false
+        },
+        {
+          "coordinate": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:infra",
+          "signer": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "members": [
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+          ],
+          "visibility": "listed",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "expect": {
+        "containers": [
+          {
+            "project": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:platform",
+            "members": [
+              {
+                "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+                "render": "resolved"
+              }
+            ]
+          },
+          {
+            "project": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:infra",
+            "members": [
+              {
+                "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+                "render": "resolved"
+              }
+            ]
+          }
+        ],
+        "implicit_cards": []
+      }
+    },
+    {
+      "name": "repository_removed_from_every_project",
+      "spec_case": "Repository removed from every project",
+      "note": "A live project that no longer lists the repository. The container renders empty rather than being hidden, and the unclaimed repository falls back to its own card.",
+      "repositories": [
+        {
+          "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "projects": [
+        {
+          "coordinate": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:platform",
+          "signer": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "members": [],
+          "visibility": "listed",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "expect": {
+        "containers": [
+          {
+            "project": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:platform",
+            "members": []
+          }
+        ],
+        "implicit_cards": [
+          "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+        ]
+      }
+    },
+    {
+      "name": "unlisted_project_absent_member_falls_back",
+      "spec_case": "Project is `unlisted`, or locally hidden",
+      "note": "An unlisted project is not listing eligible, so it claims nothing even though its signer owns the member. The container that would hold the repository is not on screen, so the repository must render as its own card or vanish.",
+      "repositories": [
+        {
+          "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "projects": [
+        {
+          "coordinate": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:skunkworks",
+          "signer": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "members": [
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+          ],
+          "visibility": "unlisted",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "expect": {
+        "containers": [],
+        "implicit_cards": [
+          "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+        ]
+      }
+    },
+    {
+      "name": "locally_hidden_project_absent_member_falls_back",
+      "spec_case": "Project is `unlisted`, or locally hidden",
+      "note": "The second half of the same rule, reached by a different input: hiding a container is a statement about the grouping only. The viewer-hidden project claims nothing and its member returns as an implicit card.",
+      "repositories": [
+        {
+          "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "projects": [
+        {
+          "coordinate": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:platform",
+          "signer": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "members": [
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+          ],
+          "visibility": "listed",
+          "state": "live",
+          "viewer_hidden": true
+        }
+      ],
+      "expect": {
+        "containers": [],
+        "implicit_cards": [
+          "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+        ]
+      }
+    },
+    {
+      "name": "viewer_hidden_repository_absent_everywhere",
+      "spec_case": "Viewer has hidden a member repository",
+      "note": "Hiding a repository hides it everywhere, including inside every project that lists it \u2014 otherwise someone else's grouping could undo the viewer's decision. The sibling member is unaffected.",
+      "repositories": [
+        {
+          "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+          "state": "live",
+          "viewer_hidden": true
+        },
+        {
+          "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz-infra",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "projects": [
+        {
+          "coordinate": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:platform",
+          "signer": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "members": [
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz-infra"
+          ],
+          "visibility": "listed",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "expect": {
+        "containers": [
+          {
+            "project": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:platform",
+            "members": [
+              {
+                "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz-infra",
+                "render": "resolved"
+              }
+            ]
+          }
+        ],
+        "implicit_cards": []
+      }
+    },
+    {
+      "name": "unresolvable_member_renders_unavailable",
+      "spec_case": "Member coordinate resolves to nothing",
+      "note": "No repository answers the coordinate \u2014 never announced, deleted, or absent from this relay. It renders inside its project as explicitly unavailable: dropping it silently would make the project look smaller than its author declared, and promoting it to a standalone card would invent a repository.",
+      "repositories": [],
+      "projects": [
+        {
+          "coordinate": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:platform",
+          "signer": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "members": [
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:ghost"
+          ],
+          "visibility": "listed",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "expect": {
+        "containers": [
+          {
+            "project": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:platform",
+            "members": [
+              {
+                "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:ghost",
+                "render": "unavailable"
+              }
+            ]
+          }
+        ],
+        "implicit_cards": []
+      }
+    },
+    {
+      "name": "deleted_project_absent_member_falls_back",
+      "spec_case": "Project head deleted",
+      "note": "Deletion does not cascade. The container is gone; the member repository, its refs and its channel survive and it falls back to an implicit card.",
+      "repositories": [
+        {
+          "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "projects": [
+        {
+          "coordinate": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:platform",
+          "signer": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "members": [
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+          ],
+          "visibility": "listed",
+          "state": "deleted",
+          "viewer_hidden": false
+        }
+      ],
+      "expect": {
+        "containers": [],
+        "implicit_cards": [
+          "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+        ]
+      }
+    },
+    {
+      "name": "authorized_and_unauthorized_projects_share_member",
+      "spec_case": "One authorized and one unauthorized project both list the same repository",
+      "note": "The discriminating case for step 3's \"at least one\": Alice's claim suppresses the implicit card, and Bob's unauthorized project still renders the member. An implementation that requires every listing project to be authorized would wrongly emit an implicit card here; one that lets any listing project suppress would wrongly emit none in `stranger_project_does_not_claim`.",
+      "repositories": [
+        {
+          "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "projects": [
+        {
+          "coordinate": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:platform",
+          "signer": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "members": [
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+          ],
+          "visibility": "listed",
+          "state": "live",
+          "viewer_hidden": false
+        },
+        {
+          "coordinate": "30621:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb:borrowed",
+          "signer": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+          "members": [
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz"
+          ],
+          "visibility": "listed",
+          "state": "live",
+          "viewer_hidden": false
+        }
+      ],
+      "expect": {
+        "containers": [
+          {
+            "project": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:platform",
+            "members": [
+              {
+                "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+                "render": "resolved"
+              }
+            ]
+          },
+          {
+            "project": "30621:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb:borrowed",
+            "members": [
+              {
+                "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+                "render": "resolved"
+              }
+            ]
+          }
+        ],
+        "implicit_cards": []
+      }
+    },
+    {
+      "name": "exhaustive_enumeration_across_pages_with_tied_timestamps",
+      "spec_case": "More repositories and projects than one page holds, with several sharing one `created_at`",
+      "note": "Exercises step 1 rather than the placement rules: the inputs exceed `enumeration.page_size` and three entities share one `created_at`, so a timestamp-only cursor loses events at the page boundary. Every repository and project must still render. `created_at` is present only on this case, and only because the cursor is what is under test.",
+      "enumeration": {
+        "page_size": 2,
+        "cursor": "composite",
+        "note": "The harness must serve inputs in pages of `page_size`, ordered `(created_at DESC, coordinate ASC)`, and the client under test must page with a composite `(created_at, id)` cursor per the Pagination section. Ordering by coordinate stands in for event id, which unsigned semantic fixtures do not carry."
+      },
+      "repositories": [
+        {
+          "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+          "state": "live",
+          "viewer_hidden": false,
+          "created_at": 1000
+        },
+        {
+          "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz-infra",
+          "state": "live",
+          "viewer_hidden": false,
+          "created_at": 1000
+        },
+        {
+          "coordinate": "30617:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb:buzz-mobile",
+          "state": "live",
+          "viewer_hidden": false,
+          "created_at": 1000
+        }
+      ],
+      "projects": [
+        {
+          "coordinate": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:platform",
+          "signer": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "members": [
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+            "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz-infra"
+          ],
+          "visibility": "listed",
+          "state": "live",
+          "viewer_hidden": false,
+          "created_at": 900
+        },
+        {
+          "coordinate": "30621:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb:mobile",
+          "signer": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+          "members": [
+            "30617:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb:buzz-mobile"
+          ],
+          "visibility": "listed",
+          "state": "live",
+          "viewer_hidden": false,
+          "created_at": 900
+        }
+      ],
+      "expect": {
+        "containers": [
+          {
+            "project": "30621:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:platform",
+            "members": [
+              {
+                "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz",
+                "render": "resolved"
+              },
+              {
+                "coordinate": "30617:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:buzz-infra",
+                "render": "resolved"
+              }
+            ]
+          },
+          {
+            "project": "30621:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb:mobile",
+            "members": [
+              {
+                "coordinate": "30617:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb:buzz-mobile",
+                "render": "resolved"
+              }
+            ]
+          }
+        ],
+        "implicit_cards": []
+      }
+    }
+  ]
+}
diff --git a/docs/nips/NIP-MP.md b/docs/nips/NIP-MP.md
new file mode 100644
index 0000000000..14936d2a7c
--- /dev/null
+++ b/docs/nips/NIP-MP.md
@@ -0,0 +1,331 @@
+NIP-MP
+======
+
+Multi-Repository Projects
+-------------------------
+
+`draft` `optional` `relay`
+
+**Depends on**: NIP-01 (basic event format, addressable events), NIP-34 (git repositories), NIP-09 (event deletion). Interacts with NIP-29 (the channel a project links to) and NIP-OA (owner attestation, for how agents inherit repo push access).
+
+## Abstract
+
+This NIP defines `kind:30621`, an addressable **project** event: a signed, named grouping of NIP-34 repository announcements (`kind:30617`). A project references its member repositories by coordinate, so one project may span repositories owned by different pubkeys, and one repository may belong to several projects.
+
+A project is metadata only. Its signer gains no authority over any member repository — not to edit it, delete it, push to it, or administer it. Membership is an assertion about grouping, not a grant of permission.
+
+## Motivation
+
+Buzz renders one card per `kind:30617`, so "the platform" — a relay, a desktop app, and a mobile app — appears as three unrelated repositories. Real work spans repositories; the model does not.
+
+[VISION_PROJECTS.md](../../VISION_PROJECTS.md) sets the bar as "standard kinds as substrate, custom kinds only where genuinely novel," and every other forge concept in Buzz clears it: repositories, patches, issues, statuses, and ref state are all standard NIP-34 kinds. Multi-repository grouping is the one semantic that cannot be:
+
+- **Per-repository tags cannot express cross-owner grouping.** If membership lived in each `kind:30617`, a project spanning Alice's and Bob's repositories would require *both* Alice and Bob to publish a tag naming the group. Alice cannot enroll Bob's repository; she cannot sign for his key. Grouping would be possible only within a single owner's repositories, and would break the moment a repository changed hands or a fork joined.
+- **Project-level metadata has no owner.** A project name, description, and linked channel describe the *group*, not any one repository. Scattered across per-repository tags they have no single writer, no replacement semantics, and no deletion story: removing a repository from the group means editing an event you may not control.
+- **Existing list kinds do not fit.** NIP-51 sets (`kind:30004` curation sets and friends) are private-or-public user bookmarks over arbitrary content, not a shared, named, addressable container for a forge collection with its own channel binding and visibility. Overloading a curation set would make every project indistinguishable from a user's reading list.
+
+One custom kind, held by one signer, with all group state in one replaceable event, resolves all three. The cost is bounded and stated plainly: `kind:30621` is Buzz-specific, so a third-party NIP-34 client sees the member repositories individually and ignores the grouping. Nothing degrades — the repositories remain standard, portable `kind:30617` events, discoverable and renderable exactly as before.
+
+## Non-Goals
+
+This NIP does not define shared or delegated project editing — a project is replaceable only by its own signer (see [Authority](#authority)).
+This NIP does not define any authorization over member repositories. Membership is not a permission grant, and a project is never consulted by git push policy.
+This NIP does not define project-level branch protection, CI, or workflow configuration.
+This NIP does not define nested projects. A project's members are repositories, never other projects.
+This NIP does not require relays to verify that a member coordinate resolves to an existing repository — a project may reference a repository that does not exist yet, or no longer does.
+
+## Terminology
+
+This document uses MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, and RECOMMENDED as defined in RFC 2119.
+
+- **project**: A `kind:30621` event. Also called the *container*.
+- **member**: A repository referenced by a project, named by an `a` tag holding a repository coordinate.
+- **coordinate**: The NIP-01 address of a repository announcement, `30617:<owner-pubkey-hex>:<repo-d-tag>`.
+- **explicit project**: A project that exists as a `kind:30621` event.
+- **implicit project**: The single-repository card a client renders for a `kind:30617` that no listing-eligible explicit project claims. Not an event — a rendering fallback.
+- **listing eligible**: A project a client is currently rendering in its project collection. See [Listing eligibility](#listing-eligibility).
+
+## Kinds
+
+| Kind | Name | Signer | Class | Purpose |
+|------|------|--------|-------|---------|
+| `30621` | Project | user | addressable | A named grouping of `kind:30617` repository announcements |
+
+`kind:30621` is an addressable event per NIP-01 (`30000 <= n < 40000`), addressed by `(pubkey, 30621, d)`. Two signers may use the same `d` value; those are two distinct projects. Addressable events were formerly specified as "parameterized replaceable events" in NIP-33, which upstream has since folded into NIP-01; this document cites NIP-01 throughout.
+
+### Kind allocation
+
+`30621` sits in the NIP-34 git block (`30617` repository announcement, `30618` repository state), which is where a reader looks for a forge concept. Checks performed before freezing the number:
+
+| Registry | Checked | Result |
+|----------|---------|--------|
+| Upstream nostr NIPs event-kind table (`nostr-protocol/nips` `README.md`, at commit `6d2979b3f503a8539c983efbcdcf901bbcf9ed23`) | `30610`–`30629` | Only `30617` and `30618` are assigned. `30621` is unassigned. |
+| nostrbook.dev kind registry (`https://nostrbook.dev/kinds/<n>`) | `30617`, `30618`, `30620`, `30621`, `30622` | `30617` and `30618` documented (HTTP 200). `30620`, `30621`, `30622` all HTTP 404 — no entry. |
+| This repository (`crates/buzz-core/src/kind.rs`) | full range | `30620` is `KIND_WORKFLOW_DEF`, `30622` is `KIND_DM_VISIBILITY` (NIP-DV). `30621` is the one free number between them. |
+
+Both external registries are advisory, not authoritative allocators: neither reserves numbers, and an unregistered kind may still be in use by an unpublished client. A future upstream assignment of `30621` would be a collision Buzz absorbs the same way it already does for its other custom kinds — the number is Buzz-specific, and interoperability rests on the member `kind:30617` events, which remain standard.
+
+## Event Format
+
+```jsonc
+{
+  "kind": 30621,
+  "pubkey": "<project-signer-pubkey-hex>",
+  "content": "",
+  "tags": [
+    ["d", "platform"],
+    ["name", "Platform"],
+    ["description", "Relay, desktop, and mobile for the platform team."],
+    ["a", "30617:<owner-a-pubkey-hex>:buzz"],
+    ["a", "30617:<owner-b-pubkey-hex>:buzz-infra"],
+    ["buzz-channel", "<channel-uuid>"],
+    ["buzz-visibility", "listed"]
+  ]
+}
+```
+
+| Tag | Cardinality | Meaning |
+|-----|-------------|---------|
+| `d` | exactly 1, non-empty | Project slug. The NIP-01 addressable identifier. |
+| `name` | 0 or 1 | Human-readable display name. Clients fall back to `d` when absent. |
+| `description` | 0 or 1 | Free text describing the project. |
+| `a` | 0 to 64 | One member repository coordinate each. Order is not significant. |
+| `buzz-channel` | 0 or 1 | UUID of the channel this project's discussion lives in. Metadata only — see [Authority](#authority). At most 256 bytes. |
+| `buzz-visibility` | 0 or 1 | `listed` (default) or `unlisted`. Feeds [listing eligibility](#listing-eligibility). At most 256 bytes. |
+
+`content` carries no meaning. Writers SHOULD emit the empty string. Readers and relays MUST ignore whatever it holds: a non-empty `content` is not a rejection cause, and no consumer may parse semantics from it. Reserving it costs nothing and keeps a future writer that fills it from invalidating its events for today's readers.
+
+Unrecognized tags MUST be ignored rather than rejected, so a newer writer can add metadata without invalidating its events for older readers.
+
+### Metadata interpretation
+
+Ingest bounds metadata cardinality and length; it interprets no metadata value. `buzz-channel` and `buzz-visibility` are opaque strings to a relay, exactly as they are on `kind:30617`. Interpretation is a client concern, and every client MUST resolve it the same way:
+
+- `name` absent → clients display the `d` value.
+- `buzz-visibility` absent or holding any value other than `listed` or `unlisted` → treated as `listed`. An unrecognized token MUST NOT hide a project: a typo in a metadata field is not a privacy signal, and treating it as one would make a project vanish for reasons its author cannot see.
+- `buzz-channel` absent, or naming a channel the viewer cannot resolve or read → the project renders without a channel link. It MUST NOT be dropped from the collection, and the unresolvable value MUST NOT be surfaced as a broken link.
+
+### Member coordinates
+
+A member `a` tag follows NIP-01's `a` tag grammar: `["a", "<coordinate>"]` or `["a", "<coordinate>", "<relay-url>"]`. Ingest validates the tag's arity — exactly two or three elements — and the coordinate in element 1. The relay URL is opaque: it is never parsed and never a rejection cause by content. A fourth element has no meaning in this grammar and is rejected rather than ignored, so a writer cannot smuggle unbounded data into a position no consumer reads.
+
+The optional third element is a **relay hint**: a recommended relay where the member announcement may be found. Clients MAY use it when resolving a member that step 6 of [the fold](#the-fold) would otherwise mark unavailable, and MUST treat it as advice rather than authority — a hint is unauthenticated, supplied by the project signer rather than the repository owner, so a resolution through it MUST still verify that the retrieved event is the coordinate's own signed `kind:30617`. A hint MUST NOT be required: a project whose members are all on the reading relay resolves fully without one, and a client that ignores hints entirely is conformant.
+
+A member `a` tag coordinate MUST be exactly `30617:<owner>:<repo-d>` where:
+
+- the kind segment is the literal `30617`. A project groups repository *announcements*; a coordinate naming any other kind (notably `30618` repository state) is malformed.
+- `<owner>` is 64 lowercase hex characters. Uppercase is rejected: `#a` filter matching is byte-exact, so an uppercase-owner head would be invisible to the lowercase-coordinate queries every reader issues.
+- `<repo-d>` is non-empty and is the `d` tag of the member repository announcement, taken **verbatim**.
+
+Parsing splits on the first two colons only; everything after the second colon is `<repo-d>`. A repository whose `d` tag contains a colon is therefore addressable. Splitting on every colon would make such a repository permanently unaddressable by any project.
+
+Buzz-hosted repositories cannot currently produce such a coordinate: their `d` values are validated as `[a-zA-Z0-9._-]{1,64}` (`crates/buzz-relay/src/handlers/side_effects.rs`, `crates/buzz-sdk/src/builders.rs`). The tolerance is for the repositories this NIP does not control — NIP-34 announcements from other clients, and any future relaxation of Buzz's own rule — and it matches how Buzz already parses coordinates in NIP-09 deletion handling, so a project coordinate and a deletion coordinate can never disagree about where a repository's `d` value begins.
+
+Coordinate identity is the whole string. Two members sharing a `<repo-d>` under different owners — the NIP-34 fork case — are distinct members, not duplicates.
+
+A project MAY reference a coordinate that resolves to nothing: a repository not yet announced, deleted, or announced on another relay. Clients render those members as explicitly unavailable ([Client Behavior](#client-behavior), step 6).
+
+## Semantics
+
+### Authority
+
+The project signer's authority begins and ends at the container.
+
+- **Over the container**: total. Only the signer can replace their `(pubkey, 30621, d)` coordinate. Deletion additionally admits the signer's registered NIP-OA owner — see [Deletion](#deletion).
+- **Over member repositories**: none. No edit, no delete, no push, no administration, no ability to change a member repository's own metadata or protections. Adding Bob's repository to Alice's project changes nothing about Bob's repository or who may push to it. It is Alice's signed assertion that the two belong together, and it is attributable to her key.
+
+Clients MUST preserve each member repository's own owner provenance in the UI. A repository rendered inside a project must not appear to be owned or governed by the project signer.
+
+`buzz-channel` on a project is **metadata only**. Git push policy reads the `buzz-channel` of the repository's own `kind:30617` (`crates/buzz-relay/src/api/git/policy.rs`); a project neither overrides that binding nor supplies one to a member that lacks it. A project's channel binding therefore cannot widen or narrow push access to anything.
+
+### Editing model
+
+Editing is **owner-only**: publish a replacement `kind:30621` with the same `d` and a newer `created_at`. Adding, removing, or reordering members and changing metadata are all one operation — replacing the container. This falls out of the addressable-event model with no relay-side permission machinery; NIP-01 replacement already refuses to let one pubkey overwrite another's coordinate.
+
+Delegated or maintainer editing is deliberately out of scope for this version. Adding it later needs no change to this event shape — only a new rule about who may replace a coordinate.
+
+### Zero-member projects
+
+A project with no `a` tags is valid. It is the natural state after removing a final member, and it carries only bounded metadata either way. Deleting the container — with its name, description, and channel binding — because its last repository was removed would be a destructive surprise for a reversible action.
+
+Clients SHOULD require at least one member when *creating* a project, since an empty new project is almost always a mistake, and MUST render an existing empty project as an empty container rather than hiding it or treating it as malformed.
+
+### Multiple membership
+
+A repository may be a member of any number of projects. It renders inside each ([Client Behavior](#client-behavior), step 4). Membership is not exclusive and not a move: nothing about the repository event changes when it joins or leaves a project.
+
+### Deletion
+
+Deleting a project (NIP-09 `kind:5` naming the project coordinate) deletes the `kind:30621` only. Member repositories are untouched — their `kind:30617` events, refs, channels, and protections all survive, and each falls back to an implicit card unless another listing-eligible project claims it.
+
+**Who may delete.** The project signer always may. On the Buzz relay, so may the signer's registered NIP-OA owner: `validate_standard_deletion_event` resolves the deletion's effective author and accepts it when that actor is the target pubkey's registered owner (`crates/buzz-relay/src/handlers/side_effects.rs`). This is a **Buzz relay extension to NIP-09**, applied uniformly to every kind rather than specially to projects — it is what lets a human clean up events published by an agent they own. Vanilla NIP-09 relays accept only the signer, so a project deleted through the owner path on Buzz will still be live on a relay that lacks the extension.
+
+Replacement admits no such widening: it is signer-only on every relay, because NIP-01 keys the coordinate on the pubkey itself rather than on a permission check.
+
+A deletion whose `created_at` precedes the live head does not remove it — see [Relay Processing Algorithm](#relay-processing-algorithm).
+
+There is no cascade, in either direction. Deleting a member repository does not modify the project; the project keeps a coordinate that no longer resolves, and clients render it as unavailable.
+
+## Relay Processing Algorithm
+
+A relay accepting `kind:30621` MUST validate the envelope at ingest. The rule names below are the identifiers the shared fixtures use.
+
+1. **`d-cardinality`** — exactly one `d` tag. Zero or several is rejected. Under NIP-01 a missing `d` is treated as empty, which collapses every such event into the `(pubkey, 30621, "")` slot where unrelated projects silently overwrite each other; several `d` tags make the address reader-dependent.
+2. **`d-empty`** — the `d` value is non-empty. Same collapse hazard. Its length is bounded by the relay's existing generic `d`-tag limit (`buzz_db::event::D_TAG_MAX_LEN`, 1024 bytes); this NIP adds no second bound.
+3. **`member-cap`** — at most 64 member `a` tags, counting **every** `a` tag rather than distinct coordinates. Counting distinct coordinates would leave parse volume bounded only by the relay frame limit (512 KiB by default, `crates/buzz-relay/src/config.rs`), since a duplicate-heavy event could carry thousands of tags naming one coordinate. The cap is inclusive: 64 is accepted, 65 is not.
+4. **`member-tag-arity`** — every member `a` tag has exactly two or three elements, per NIP-01's `a` tag grammar. A one-element tag names no coordinate; a fourth element has no defined meaning, and ignoring it would let a writer park unbounded unvalidated data in a position no consumer reads. This is a separate rule from the next one because the failure is different: the tag's shape is wrong, not the coordinate it holds.
+5. **`member-coordinate-malformed`** — every member `a` tag's coordinate (element 1) parses per [Member coordinates](#member-coordinates). The relay hint in element 3 is not parsed and MUST NOT be a rejection cause by its content.
+6. **`member-duplicate`** — no two member `a` tags hold the same coordinate, compared as exact strings on the canonical form. Comparison is on the coordinate alone, so two tags naming one coordinate with different relay hints are duplicates.
+7. **`metadata-cardinality`** — at most one each of `name`, `description`, `buzz-channel`, `buzz-visibility`. Duplicates would make the effective value reader-dependent.
+8. **`metadata-length`** — `name` at most 256 bytes; `description` at most 2048 bytes; `buzz-channel` at most 256 bytes; `buzz-visibility` at most 256 bytes. The two `buzz-` bounds are generous by design: neither value has a semantic length, and the bound exists only so an unbounded string cannot ride into storage on a tag ingest does not interpret.
+
+Rules 3 through 6 are evaluated in that order, so an oversized tag list is refused on count before any per-tag parse or set proportional to it is built.
+
+The Buzz validator enforces all eight rules. The shared fixtures in [`NIP-MP.fixtures.json`](NIP-MP.fixtures.json) are wired as its test oracle: the relay's unit test suite runs every case against `validate_project_envelope` and asserts each `expect` outcome.
+
+**Duplicates are rejected, never normalized.** A relay cannot dedupe tags inside a signed event: rewriting the tag array changes the event id and invalidates the signature. The choices are reject, or accept and require every present and future consumer to apply a first-wins interpretation rule. Rejecting keeps every stored head canonical and spares all consumers a defensive parse.
+
+**No membership authorization.** The relay MUST NOT check whether the signer owns, maintains, or has any relationship to a member repository. Referencing another owner's repository is legal and is the point of the kind. Because membership grants nothing ([Authority](#authority)), there is nothing to authorize.
+
+**Routing.** `kind:30621` is global-only, like every other NIP-34 kind in Buzz: it is addressed by `(pubkey, kind, d)` and is never channel-scoped. A stray `h` tag MUST NOT scope it to a channel — the `buzz-channel` tag is a metadata reference, not a routing directive.
+
+**Scope.** Writes require the `repos:write` scope, matching `kind:30617` and `kind:30618`. A project is repository metadata; a client authorized to announce repositories is authorized to group them.
+
+**Replacement** follows NIP-01 with no special cases: newest `created_at` wins per `(pubkey, 30621, d)`, and one pubkey can never overwrite another's coordinate.
+
+**Deletion** follows NIP-09 with two Buzz-wide behaviors that are not project-specific:
+
+- A `kind:5` naming the coordinate deletes it when signed by the project signer **or** by that signer's registered NIP-OA owner ([Deletion](#deletion)).
+- The deletion applies only to versions whose `created_at` is at or before the deletion's own, per NIP-09. A delayed or replayed tombstone signed before the current head MUST NOT remove it; the relay MUST compare timestamps at the coordinate (`soft_delete_by_coordinate`, `crates/buzz-db/src/event.rs`, whose inclusive `created_at <= <deletion>` bound is introduced alongside this specification in [#3171](https://github.com/block/buzz/pull/3171)).
+
+## Client Behavior
+
+### Listing eligibility
+
+A project is **listing eligible** for a client when that client is currently rendering it in its project collection. A project is not listing eligible when:
+
+- its `buzz-visibility` is `unlisted`, or
+- the viewer has hidden it locally, or
+- it has been deleted, or its latest head is otherwise not being rendered.
+
+Only listing-eligible projects claim members. This keeps visibility deterministic in the case that otherwise breaks: an unlisted project must not make a repository the viewer can plainly see disappear from the collection, because the container that claims it is not on screen to hold it.
+
+### Claim authority
+
+A project **claims** a member — suppressing that repository's implicit card, per step 3 of the fold — only when the project is listing eligible *and* its signer is authorized by the member repository itself: the signer is the repository's owner (the pubkey in the member coordinate), or is listed in a `maintainers` tag on the repository's own live `kind:30617`.
+
+Authority is therefore read from the member repository's *content*, not merely its existence: a client that has resolved only a coordinate, and not the head it names, cannot yet decide whether a project claims it. `maintainers` is the standard NIP-34 multi-value tag; Buzz's own announcement builder does not emit it today, so in practice every current claim reduces to signer-is-owner, and the `maintainers` clause is what keeps a co-maintained repository working the day that changes.
+
+Without this rule, membership would carry exactly the authority [Authority](#authority) says it does not. Anyone may publish a project naming anyone's repository, so an unauthorized project that suppressed implicit cards would let a stranger pull someone else's repository out of the collection and into a container the owner never consented to — a signed assertion silently becoming control over another owner's discovery surface.
+
+An unauthorized project still renders, and still renders its members inside itself: cross-owner grouping works, which is the entire point of the kind. What it cannot do is *remove* a repository from where its owner expects to find it. The visible consequence is that a repository in a stranger's project renders in both places — inside that project and as its own card — which is the correct reading of an unendorsed grouping claim.
+
+### The fold
+
+Given the set of repositories and projects to render, a client MUST derive the collection as follows.
+
+1. **Enumerate exhaustively when possible.** Retrieve the latest live head of every `kind:30621` and `kind:30617` coordinate, plus the `kind:5` deletions bearing on them, using paginated queries. A fixed `limit` MUST NOT be used: with a limit of 200, repository 201 vanishes from the collection, which is precisely the compatibility guarantee this NIP owes existing repositories. What "to exhaustion" means depends on the cursor the relay offers — see [Pagination](#pagination). On a relay that does not provide an exhaustive mode, a client MUST mark the collection possibly incomplete rather than present a partial result as complete.
+2. **Resolve members.** For each project, resolve each member coordinate to its repository head, and determine whether the project [claims](#claim-authority) each one.
+3. **Suppress claimed implicit cards.** A live repository claimed by at least one project does not also render as an implicit single-repository card.
+4. **Render multiple membership.** A repository belonging to several listing-eligible projects renders inside each of them, claimed or not.
+5. **Fall back.** A repository claimed by no project renders as an implicit single-repository card — including when an unauthorized project also renders it as a member.
+6. **Mark unresolvable members.** A member coordinate that resolves to nothing — never announced, deleted, or not present on this relay — renders inside its project as explicitly unavailable. It MUST NOT become a phantom standalone card, and it MUST NOT be silently dropped: silence makes a project look smaller than its author declared.
+7. **Hiding a container never hides repositories.** Locally hiding a project makes it not listing eligible, so it claims nothing and by step 5 its members return as implicit cards. Hiding a grouping is a statement about the grouping. A repository disappears from the collection only when the viewer hides that repository or it is deleted — and a repository the viewer has hidden is hidden everywhere, including inside every project that lists it, so hiding one cannot be undone by someone else's grouping.
+
+The fold is deterministic: same heads in, same collection out, independent of arrival order or query shape. **Placement, not order, is what the fold fixes** — the collection of containers, the members rendered inside each container, and the implicit cards are all compared as sets, since member order is not significant in the event ([Event Format](#event-format)) and a client is free to sort its own presentation. Every live, unhidden repository renders in at least one place — inside a project that claims it, or as its own card — and no repository renders twice within one container.
+
+### Required fold cases
+
+The fold cannot be expressed as accept/reject of a single event, so it has its own fixture file rather than living in the ingest [conformance fixtures](#conformance-fixtures). A client implementing the fold MUST cover at least these cases, each of which is a distinct branch above:
+
+| Case | Expected collection |
+|------|---------------------|
+| Owner's own project lists their repository | Repository renders inside the project only |
+| Stranger's project lists someone else's repository | Repository renders inside that project *and* as its own card |
+| Project signer is in the member repository's `maintainers` tag | Repository renders inside the project only |
+| Repository is a member of two projects that both claim it | Repository renders inside both; no implicit card |
+| Repository removed from every project | Repository renders as an implicit card |
+| Project is `unlisted`, or locally hidden | Project absent from the collection; its members render as implicit cards |
+| Viewer has hidden a member repository | Repository absent from the collection *and* from inside every project listing it |
+| Member coordinate resolves to nothing | Member renders inside its project as unavailable; no standalone card |
+| Project head deleted | Project absent; its members render as implicit cards |
+| One authorized and one unauthorized project both list the same repository | Repository renders inside both projects; no implicit card, because one claim suffices to suppress it |
+| More repositories and projects than one page holds, with several sharing one `created_at` | Every repository and project renders |
+
+[`NIP-MP.fold-fixtures.json`](NIP-MP.fold-fixtures.json) mechanizes this table — see [Conformance Fixtures](#conformance-fixtures).
+
+### Pagination
+
+Step 1's "to exhaustion" describes the target result, not a single algorithm: what a client must do — and whether it can fully reach it — depends on the cursor its relay offers. Both modes below are conformant; a client MUST implement whichever its relay supports, MUST NOT present a mode-1 loop's output as complete on a mode-2 relay, and on a relay that provides neither mode 1 nor the relay contract below, MUST mark the collection possibly incomplete — presenting that marked partial collection is conformant, not a violation of step 1's enumeration requirement.
+
+**The relay contract both modes rest on.** Every "short response = done" inference — whether from a composite cursor or a drained bucket — is a property of the relay, not of NIP-01, where `limit` is advisory: relays "SHOULD use the `limit` value to guide how many events are returned in the initial response. Returning fewer events is acceptable" (NIP-01). A conforming relay may answer a request for 100 with 50 events and no indication that it withheld the rest, and the client cannot tell that from exhaustion. Exhaustive enumeration is possible only on a relay that satisfies **all three** of these conditions, which a client can evaluate independently:
+
+1. The relay **applies the complete filter before enforcing any limit.** A relay that post-filters after limiting can return a short (even empty) response while older matching events sit beyond the limited window, so short responses carry no exhaustion signal on such a relay.
+2. The relay **exposes the exact effective page limit it enforces.** The effective page limit is the smaller of the requested `limit` and any relay-imposed cap, since a clamped request answered in full is short without being exhausted. If the advertised cap differs from the enforced one, "shorter than the effective limit" is undecidable by the client.
+3. The relay **saturates pages**: after applying the complete filter and cursor, it returns `min(effective page limit, remaining matching events)` events — equivalently, whenever at least the effective limit's worth of matches remain, the page is full, so a short page contains all remaining matches. A cap bounds from above; without saturation, a relay may return fewer than the cap even when matches are still available, and a short page proves nothing. An authoritative relay-provided continuation or end signal computed after complete filtering is an equivalent substitute for this response-length inference.
+
+A relay satisfying any proper subset of these conditions does not provide the guarantee. Absent the guarantee, a client MUST mark the collection possibly incomplete regardless of any response sizes; the modes below serve to reduce silent loss rather than eliminate it. `limit` below means the effective page limit.
+
+**Mode 1 — composite cursor (exhaustive under the relay contract).** On a relay that exposes a keyset cursor over `(created_at, event id)`, a client MUST page by it. As an example of the cursor mechanics, Buzz implements the keyset as `created_at < until OR (created_at = until AND id > before_id)` (`crates/buzz-db/src/event.rs:48-52`), resolving the sort to `(created_at DESC, id ASC)`. Buzz exposes this cursor on its authenticated HTTP bridge endpoint (`crates/buzz-relay/src/api/bridge.rs`); it is not available on the NIP-01 websocket REQ path, where `before_id` is silently discarded — `protocol.rs` deserializes each REQ filter into a standard `nostr::Filter`, whose deserializer drops unknown fields, so a client sending `before_id` on a REQ receives no error and falls back to `until`-only paging without knowing it. A NIP-01 websocket client reading `kind:30621` from Buzz is therefore in mode 2, not mode 1; mode selection requires evaluating the relay contract per transport. Within the relay contract, the uniqueness of the `(created_at, id)` pair means each page resumes exactly where the last ended with no skips or re-reads, and a short page is an unambiguous end signal. Cursor uniqueness adds tie-safety; it does not substitute for the relay contract — a relay that post-filters after limiting can return an empty page under this cursor while older matching events remain beyond the candidate window.
+
+**Mode 2 — `until` only (boundary-bucket drain; exhaustive only under the relay contract).** A vanilla NIP-01 filter offers no id tiebreak, so the only cursor is `until`. Neither naive step is safe: `until = oldest_seen_created_at - 1` skips every unread event in that second, and `until = oldest_seen_created_at` re-requests the whole bucket, which never advances once one `created_at` bucket exceeds the relay's page size. A mode-2 client MUST therefore drain the boundary second explicitly before stepping past it.
+
+1. A page returning fewer than `limit` events means the query is exhausted — stop.
+2. After a **full** page, let `oldest` be the smallest `created_at` it returned. Query that second exactly — `since = until = oldest` — and merge the result into what is already held, deduplicating by event id. That single bucket query has two outcomes.
+3. If it returns `limit` events, second `oldest` may hold more than the relay will return in one response, so the collection MUST be marked possibly incomplete. Count `limit` inclusively: a bucket holding exactly `limit` events is indistinguishable from a larger one, and over-reporting a doubt is the safe direction.
+4. If instead it returns fewer than `limit` events, the second is fully drained. Set `until = oldest - 1` and continue from step 1.
+
+A client that cannot drain a bucket has lost exhaustiveness for that second and MUST keep the collection marked possibly incomplete; it MAY still set `until = oldest - 1` to gather the older events rather than stall, but MUST NOT clear the mark by doing so.
+
+The naive form fails on a page whose oldest second is only partly returned, which a same-`created_at` test on the page as a whole does not see. With `limit = 3` over `(100,a) (99,b) (99,c) (99,d) (98,e)`, the first page is `(100,a) (99,b) (99,c)` — two distinct timestamps, so no all-tied heuristic fires — and advancing to `until = 98` silently drops `(99,d)`. Draining second `99` first retrieves it.
+
+Enumeration is therefore exhaustive when the relay satisfies the contract above and every equal-`created_at` bucket fits in one response; under those conditions truncation is detected exactly rather than guessed at. On detecting it — or on any relay that does not meet the contract — a client MUST mark the collection as possibly incomplete rather than present a partial collection as complete. Silently presenting a truncated collection is the failure this NIP exists to prevent: a repository missing from the list is indistinguishable from one that was never announced.
+
+**Query shapes.** The relay contract applies only where the relay can apply it — and that depends on the query shape. A relay that post-filters some constraints (such as `#a` tag matching applied after the SQL `LIMIT`) cannot guarantee short-response exhaustion for queries that use those constraints. A client MUST therefore issue fold queries in shapes whose full filter the relay applies before limiting. Where a needed constraint is not applied pre-limit on the target relay, the client MUST widen the query to constraints that are — for example, enumerating all `kind:5` events by `kinds` alone, or `kinds` + `authors`, rather than adding an `#a` filter the relay post-applies — and match the remaining criteria client-side. This keeps the relay contract's short-response guarantee intact for every query the fold issues.
+
+### Collection growth
+
+Step 1's exhaustive enumeration is a correctness floor, not a scaling strategy: it says a client MUST NOT silently truncate its collection, because a repository absent from the list is indistinguishable from one that does not exist. It is not a mandate to hold the relay's entire repository set in memory on every load.
+
+At Buzz's current scale (hundreds of repositories per community) exhaustive enumeration is the whole story. Past that, the way out is a narrower question — a server-side collection query, a scoped or searched subset, or resolving a project's members on demand — not a fixed client-side `limit`. Any such surface MUST report its own truncation so a client can say "showing N of M" rather than quietly presenting a partial collection as complete.
+
+### Route resolution
+
+A project route resolves to a container; a repository route resolves to a repository. Every repository-scoped operation — clone, fetch, issues, pull requests, activity, mutation, deletion — MUST take an explicit repository coordinate. None may infer its target from container state, or a two-repository project will silently operate on the wrong member.
+
+Legacy `<owner>:<dtag>` repository routes remain valid and resolve to that repository, presented as a single-repository container.
+
+## Conformance Fixtures
+
+Two fixture files carry the machine-checkable contract. `NIP-MP.fixtures.json` is already wired as the relay ingest consumer; the remaining consumers listed below are Phase 2 work.
+
+### Ingest
+
+[`NIP-MP.fixtures.json`](NIP-MP.fixtures.json) holds the shared valid/invalid case set: 11 accepted and 20 rejected events covering minimal and full projects, zero members, the 64-member boundary from both sides, cross-owner and same-`d`-different-owner members, colon-bearing repository `d` values, relay hints, non-empty `content`, and each rejection rule above.
+
+The relay validator, the Rust builder, and the TypeScript builder are required to test against this one file, so a divergence between them is a test failure rather than a production surprise.
+
+Each case carries an **unsigned** template — `kind`, `content`, `tags`. Consumers sign it with their own test key. Signed literals would be inert: the id and signature are fixed by the exact serialization, so any consumer that re-serializes would need to recompute both anyway. Rejection cases name their `reject_rules`, so an implementation cannot pass by rejecting a bad event for an unrelated reason.
+
+### Fold
+
+[`NIP-MP.fold-fixtures.json`](NIP-MP.fold-fixtures.json) holds the oracle for [the fold](#the-fold): 12 cases covering every row of the [required fold cases](#required-fold-cases) table. Every client implementing the fold is required to test against this one file. The fold is where the [claim authority](#claim-authority) rule lives, so without a shared oracle two clients could each satisfy the prose and still render different collections from identical heads.
+
+Its cases are **semantic, not signed envelopes**. A repository or project is named by its coordinate plus the inputs the fold actually reads — signer, members, `maintainers`, visibility, viewer-hidden, deletion. Signing would test the ingest contract a second time and obscure what is under test: this file assumes every input is an already-accepted head and pins only the placement derived from it. Each case gives `expect.containers` (each rendered project with the members rendered inside it) and `expect.implicit_cards` (the repositories that additionally render as their own cards). Every collection in `expect` is compared as a set — the containers, each container's `members`, and the implicit cards alike — because the fold fixes placement and not order.
+
+## Security Considerations
+
+**Unauthorized grouping claims are the accepted trade.** Anyone may publish a project referencing anyone's repositories. That claim is a signed statement attributable to its author and grants nothing ([Authority](#authority)) — the same trust model as NIP-51 lists, which likewise reference content their author does not own. A client MUST NOT present membership in a stranger's project as endorsement by, or authority over, the member repository's owner, and MUST show the project signer alongside a project it did not author.
+
+**Resolution fan-out is bounded.** Each project resolves at most 64 coordinates, and the cap counts raw tags, so no single event can force unbounded resolution work regardless of how its tag list is shaped.
+
+**Push policy is untouched.** A project cannot grant, widen, or narrow push access to any repository. Push policy reads only the repository's own `kind:30617`. This is a design invariant, not an implementation detail: if a project ever became an input to push authorization, publishing a project naming someone else's repository would become a privilege-escalation primitive.
+
+## Relation to Other NIPs
+
+- **NIP-34**: Supplies the member repositories. Members are `kind:30617` announcements referenced by coordinate; a NIP-34 client that does not know `kind:30621` still discovers and renders each repository normally.
+- **NIP-01**: Supplies the addressable-event class, the `a` tag grammar, addressing, replacement, and the owner-only editing model. Owner-only editing is not enforcement code in Buzz — it is what NIP-01 replacement already means.
+- **NIP-09**: Supplies container deletion, which deletes the container only. Buzz extends it in two ways that are not project-specific: an agent's registered NIP-OA owner may also delete, and a tombstone applies only at or before its own `created_at` ([Deletion](#deletion)).
+- **NIP-29**: Supplies the channel a project's `buzz-channel` names. The reference is metadata; project state is never channel-scoped.
+- **NIP-51**: The closest existing precedent — a signed, addressable list referencing content the author need not own. Not reused because a project is a shared named forge container with its own channel binding and visibility, not a user's private-or-public bookmark set.
+- **NIP-OA**: Consulted for container deletion only — an agent's registered owner may delete the agent's project ([Deletion](#deletion)). Push access is unaffected: agents inherit repository push access from their owner through the repository's own protections, and a project is never consulted.
diff --git a/docs/nips/NIP-RS.md b/docs/nips/NIP-RS.md
index 1ca30ea08f..6a095df60a 100644
--- a/docs/nips/NIP-RS.md
+++ b/docs/nips/NIP-RS.md
@@ -20,15 +20,14 @@ read.
 
 A user running Nostr clients on multiple devices (phone, desktop, web) has no way to share read position across those clients. Each instance independently tracks what has been read, causing already-read content to appear unread on other devices.
 
-This NIP defines a minimal, privacy-preserving protocol for propagating read state across client instances without requiring relay-side logic or coordination between different client implementations.
+This NIP defines a minimal, privacy-preserving protocol for propagating read state across client instances without requiring a new event kind, a new wire message, relay-stored read-state logic, or coordination between different client implementations. It is not free of relay obligations: a relay serving the manual-unread override layer's full-state load must satisfy the ordering, capacity, floor, push, and barrier contract that section enumerates.
 
 ## Non-Goals
 
-This NIP does not define a durable log of all read messages — blobs are best-effort recent activity hints bounded by a time horizon.
+This NIP does not define a durable log of all read messages — frontier blobs are best-effort recent activity hints bounded by a time horizon. Exception: `ov_*` override entries, including tombstone floors, are durable state — they are exempt from age pruning, budget eviction, and horizon-bounded fetching, they live in a single coordinate per installation, and they MUST be carried forward before that coordinate is deleted or abandoned (see Manual-Unread Override Layer — Override State Durability).
 This NIP does not define cross-client interoperability on context ID format — context identifiers are opaque by default and meaningful only within a single client family, except for OPTIONAL well-known schemes defined in this NIP (`thread:<root-event-id>` and `msg:<event-id>`, defined under Read Context Schemes), which are provided for cross-client thread/message-read interoperability.
-This NIP does not define mark-as-unread — the merge rule is monotonic by design.
 This NIP does not guarantee ordering of read events across devices.
-This NIP does not require relay-side logic.
+This NIP does not require relay-stored read-state logic: no new event kind, no new wire message, and nothing a relay must interpret about read state. Clients implementing the manual-unread override layer do depend on relay behaviour their full-state load cannot verify (see Full-State Load).
 This NIP does not define read receipts, seen-by lists, or any mechanism for
 tracking what other users have read.
 
@@ -53,18 +52,26 @@ Clients publish a `kind:30078` addressable event (per [NIP-78](78.md)) with the
 
 #### `d` Tag
 
-The `d` tag MUST be `read-state:<slot-id>`, where `<slot-id>` is a random opaque string (e.g., 32 random hex characters) generated by the client on first launch and persisted locally. The `<slot-id>` has no relationship to the `client_id` — it is solely a unique key for NIP-33 addressable event semantics. Each client instance MUST use a stable, unique `<slot-id>` for the lifetime of that installation.
+The `d` tag MUST be `read-state:<slot-id>`, where `<slot-id>` is exactly 32 lowercase hexadecimal characters (`[0-9a-f]{32}`), generated randomly by the client on first launch and persisted locally. The `<slot-id>` has no relationship to the `client_id` — it is solely a unique key for NIP-33 addressable event semantics. The shape is fixed rather than opaque so that a relay can recognize a read-state coordinate structurally, from the `d` tag alone and without decrypting anything, and apply per-coordinate protections to it; a client that picks some other shape is not merely stylistically different, it forfeits those protections silently.
+
+**Primary coordinate:** a client MUST designate one coordinate as its **primary** and MUST use a single stable, unique `<slot-id>` for it for the lifetime of that installation. The primary `<slot-id>` changes only on a `client_id` conflict (below) or rotation (see Client-ID Rotation).
+
+**Additional frontier-only coordinates:** a client MAY publish additional coordinates under distinct `<slot-id>` values when its primary blob would otherwise exceed the size budget. Additional coordinates MUST NOT contain `ov_*` entries — they carry frontier entries only, and are therefore freely rewritable and freely deletable (see Orphaned Blob Deletion). A client MUST persist the `<slot-id>` values of its additional coordinates locally so that it can rewrite and delete them.
+
+**All `ov_*` entries, and the frontier entries of the contexts they belong to, MUST live in the primary coordinate.** A client implementing the manual-unread override layer MUST NOT distribute `ov_*` entries across coordinates and MUST NOT move them between coordinates: there is exactly one override-bearing coordinate per installation.
 
 If a client fetches its own `d` tag coordinate and the decrypted `client_id` does not match its local `client_id`, the coordinate is conflicted. The client MUST NOT publish to that coordinate and MUST generate a new random `<slot-id>` before the next publish.
 
 Events with zero `d` tags MUST be ignored.
 Events whose `d` tag value does not begin with `read-state:` MUST be ignored.
 Events with more than one `d` tag MUST be ignored.
-The `<slot-id>` MUST be a non-empty ASCII string of 1–64 characters.
+Events whose `<slot-id>` is not exactly 32 lowercase hexadecimal characters MUST be ignored.
+
+Recognizable coordinates also serve the accumulation discipline this NIP depends on: a relay that can identify a read-state coordinate structurally can replace superseded versions outright instead of retaining a tombstone row per publish, which keeps the coordinate count a full-state load must enumerate near one per live installation (see Full-State Load).
 
 #### `t` Tag
 
-Events MUST include exactly one `["t", "read-state"]` tag. This enables relay-side filtering without fetching all `kind:30078` events for the user.
+Events MUST include exactly one `["t", "read-state"]` tag. The tag is a discoverability marker: it lets a client express "read-state events only" in a single filter. It is not a guarantee of relay-side selectivity — a relay MAY apply tag constraints after its result cap, and `kind:30078` is shared with unrelated application data — so clients MUST apply the tag as a correctness filter locally on everything they receive, and MUST NOT infer from a short result that no further coordinates exist. A client performing a full-state load MUST omit the tag from its filter entirely (see Full-State Load).
 
 Events with zero `t` tags with value `read-state`, or more than one `t` tag with value `read-state`, MUST be ignored.
 
@@ -104,6 +111,7 @@ After decryption, clients MUST apply the following validation rules:
 - Events whose `contexts` field is not a JSON object MUST be discarded.
 - Individual context entries whose timestamp is not an integer in the range 0–4294967295 MUST be discarded (the entry is dropped; the rest of the blob is still processed).
 - Individual context entries whose context ID exceeds 256 bytes MUST be discarded.
+- Override counter entries (keys beginning with `ov_s:`, `ov_c:`, or `ov_b:`) MUST be validated as a complete logical group BEFORE any decoding, zero-filling, merging, or canonicalizing. Clients MUST collect all `ov_s:`, `ov_c:`, and `ov_b:` entries for the same `<ctx>` suffix together before processing them. The only accepted wire shapes for an override group are: (a) a complete live group containing exactly the three keys `ov_s:<ctx>`, `ov_c:<ctx>`, and `ov_b:<ctx>` with valid uint32 values, or (b) a tombstone floor containing only `ov_c:<ctx>` with a valid uint32 value. Any other shape (partial group, extra keys, or invalid value in any sibling) MUST cause the entire override group to be rejected; the corresponding frontier entry for `<ctx>` MUST be retained. Applying the generic per-entry discard rule before group collection is prohibited for override entries.
 - Blobs containing more than 10,000 context entries MUST be rejected.
 - If a blob contains duplicate context keys, clients SHOULD use the last value encountered (consistent with RFC 8259 §4).
 - Clients SHOULD ensure the total serialized event does not exceed the relay's maximum event size (commonly 64 KB per NIP-01). Clients receiving events that exceed their configured size limit SHOULD discard them.
@@ -112,6 +120,15 @@ After decryption, clients MUST apply the following validation rules:
 
 Context identifier format is not prescribed by this NIP. Clients choose identifiers appropriate to their context type (e.g., a NIP-28 channel event ID, a NIP-29 group address, a pubkey for DMs). Interoperability between different client implementations on context ID conventions is outside the scope of this NIP.
 
+#### Reserved Namespace
+
+The key prefix stem `ov_` (3 bytes) and the escape marker `esc:` (4 bytes) are reserved for the manual-unread override layer defined below. Clients MUST escape any raw context ID that begins with `ov_` or `esc:` when using it as a frontier key in the `contexts` map:
+
+- **On publish:** prepend `esc:` to any raw context ID beginning with `ov_` or `esc:` before writing it as a frontier key (e.g., raw `ov_s:evil` → wire key `esc:ov_s:evil`; raw `esc:foo` → wire key `esc:esc:foo`).
+- **On receive:** strip exactly one leading `esc:` from any frontier wire key beginning with `esc:` to recover the raw context ID (e.g., wire key `esc:ov_s:evil` → raw `ov_s:evil`; wire key `esc:esc:foo` → raw `esc:foo`). This is a bijection — applying escape then unescape is the identity function. Clients MUST NOT strip more than one `esc:` prefix per receive.
+
+**Backward-compatibility limitation:** a context published *unescaped* by a client predating this amendment, whose raw ID happens to start with `ov_` or `esc:`, is not safely migrated. The scheme protects contexts generated by amendment-aware clients going forward; it does not retroactively rewrite history. This residual hazard is documented as a known limitation. Buzz's own context ID shapes (channel UUID, `msg:hex64`, `thread:hex64`) cannot trigger it.
+
 #### Read Context Schemes (Optional)
 
 This subsection defines OPTIONAL well-known context schemes for tracking read
@@ -281,13 +298,13 @@ Because context timestamps are derived from message `created_at` values — whic
 
 ### Fetching
 
-To load read state, a client MUST fetch all `kind:30078` events for the user within the time horizon using the `#t` filter:
+To load read state, a client MUST fetch all `kind:30078` events for the user. Unless it is performing a full-state load (below), it SHOULD narrow the fetch with the `#t` filter:
 
 ```json
-{"kinds": [30078], "authors": ["<user-pubkey>"], "#t": ["read-state"], "since": <now - horizon>}
+{"kinds": [30078], "authors": ["<user-pubkey>"], "#t": ["read-state"]}
 ```
 
-Clients SHOULD limit the fetch to events with `created_at` within a configurable time horizon (default: 7 days).
+Clients that neither read nor write `ov_*` override state SHOULD limit the fetch to events with `created_at` within a configurable time horizon (default: 7 days) by adding `"since": <now - horizon>`, accepting that frontiers older than the horizon become unknown. Clients that implement the manual-unread override layer MUST NOT filter the fetch by age or by tag, and MUST establish completeness (see Full-State Load below).
 
 After fetching, clients MUST:
 
@@ -295,11 +312,71 @@ After fetching, clients MUST:
 2. Discard blobs that fail validation (see Content Validation).
 3. Identify the blob whose decrypted `client_id` matches the client's own `client_id` — this is the client's own blob.
 
-If multiple blobs decrypt to the same `client_id` (e.g., due to a prior rotation that left an orphaned blob, or a backup/restore that duplicated identifiers), the client MUST treat the blob with the highest `created_at` as its own and merge all others into the read state as if they were from other instances. The client SHOULD delete the stale duplicate(s) via NIP-09 deletion.
+If multiple blobs decrypt to the same `client_id` (e.g., due to a prior rotation that left an orphaned blob, or a backup/restore that duplicated identifiers), the client MUST treat the blob at its own primary coordinate as its own and merge all others into the read state as if they were from other instances. If none of them is at the client's own primary coordinate, the blob with the highest `created_at` is its current reference. Deletion of such a stale duplicate is governed by Orphaned Blob Deletion — a duplicate carrying `ov_*` entries MUST NOT be deleted until its override state has been carried forward.
 
 4. Merge all valid blobs (including the client's own) using the merge rule.
 
-Absence of a context in all fetched blobs means the read state for that context is **unknown** — clients SHOULD treat unknown contexts as unread (conservative default). The horizon is a storage and fetch optimization, not a semantic claim about read status. Contexts that were read but have aged out of the time horizon are indistinguishable from never-read contexts. Clients MAY extend the horizon or maintain a local cache to mitigate this.
+Absence of a context in all fetched blobs means the read state for that context is **unknown** — clients SHOULD treat unknown contexts as unread (conservative default). For clients using a finite horizon, the horizon is a storage and fetch optimization, not a semantic claim about read status: contexts that were read but have aged out of the time horizon are indistinguishable from never-read contexts. Clients MAY extend the horizon or maintain a local cache to mitigate this. Clients implementing the override layer do not filter the fetch by age at all (see above), so for them this ambiguity arises only from write-time frontier pruning.
+
+#### Full-State Load
+
+Clients that implement the manual-unread override layer MUST perform a **full-state load**: they MUST NOT apply a finite `since` filter, and they MUST establish that every one of the user's `read-state` coordinates has been retrieved. Because the payload is encrypted, a relay filter cannot select for override-bearing events: any event-level window can exclude the only coordinate carrying a tombstone floor, which reopens the resurrection witness in Override State Durability regardless of any per-entry exemption. For these clients the time horizon is a *write-time* frontier pruning policy only (see Debounce and Pruning), never a fetch filter.
+
+Removing `since` does not by itself make the result complete. Relays MAY cap the number of events returned for a historical query, MAY cap below the client's requested `limit`, and emit end-of-stored-events after the capped query — so **a single query proves nothing.** End-of-stored-events marks the end of the capped result, not the end of the matching set, and a short result does not establish that no further coordinates exist. Caps typically retain the newest events and drop the oldest, which are precisely the rotation-predecessor and orphaned coordinates whose tombstone floors this layer depends on. A silently truncated load that omits the sole carrier of a floor merges a stale live register unopposed and reports a manually-unread context as read, permanently.
+
+A full-state load MUST therefore be enumerated with no tag constraint in the filter:
+
+```json
+{"kinds": [30078], "authors": ["<user-pubkey>"], "limit": <n>}
+```
+
+A relay MAY deliver fewer events than its result cap selected — for example, by applying tag constraints only after the cap and withholding the events that fail them. Under a tag-constrained filter the number of events the client receives is therefore not the number the cap selected: a delivered page can be short, or empty, while older matching coordinates still exist below it, and no observation the client can make distinguishes the two. `kind:30078` is arbitrary application data whose `d` tag namespace is open to every application that has ever written under the user's key, so this is not a hypothetical — a page can be filled entirely by coordinates unrelated to read state. With the tag constraint omitted, the client asks for exactly what it will accept, and the events the cap selects are the events it receives. Selection moves client-side, which is where the validation rules already place it: collect coordinates only from `d` tags of the form `read-state:<slot-id>` and ignore every other event. The cost is that the client fetches its own application data at that kind rather than a relay-selected subset of it.
+
+A client MUST NOT test completeness by comparing the number of events returned against the `limit` it requested: the effective cap is the relay's, a relay MAY cap below the requested value, and a relay's advertised maximum limit is not necessarily the limit it enforces — so no comparison against the requested `limit` is a valid truncation test. What the client MAY compare is one delivery against another. Let `C` be the largest number of events the relay delivered for any single **preceding** query in this load. The relay demonstrably delivered `C` events at once, so its cap is at least `C`, and a query that delivers fewer than `C` events was not cut short by that cap. Completeness is established by continuation on a strictly decreasing cursor, with each band discharged by that comparison.
+
+`C` yields nothing at the start of a load, and yields nothing for the whole of a load whose entire history at this kind is a single event: one delivery of one event bounds the cap below by one, and no delivery can be smaller than that. The procedure therefore also fixes a floor, `L = 2`, required of relays below. A delivery is bounded by the requested `limit` as well as by the relay's cap, so the floor licenses a conclusion about a delivery only together with step 1's requirement that the requested `limit` be at least `L`: what the client may conclude is that a query it issued for at least `L` events, whose matching set holds at least `L`, delivers at least `L`. A threshold above the requested `limit` would be unreachable by construction, and a test that can never be met declares a truncated page exhausted. It is stated at the smallest value that admits a second event, because a larger floor is a stronger claim about relays that buys nothing further: a relay that will deliver only one event per query cannot express `limit` semantics and cannot serve a user who has two coordinates at all, whereas any floor above two would begin excluding relays this procedure does not need to exclude.
+
+Enumeration descends, so it cannot see a coordinate that moves *up* while it runs. Because these are addressable events, a republish replaces the previous version rather than appending: a coordinate the client already collected at a low `created_at` can be replaced, during the load, by a version above the cursor the client has already passed — and the old version stops existing, so no continuation and no pinned window will ever return either one. If that new version carries a tombstone floor the old one lacked, a load that reported *complete* merged without it.
+
+A full-state load therefore MUST be fenced by a live subscription on the same tag-free filter, established **before** the first enumeration query and held unbroken for the duration of the load. The fence is *established* when the client has received end-of-stored-events for that subscription, not when it sent the request: sending a request is not an observation, and the relay's answer to it is the first point at which the client knows the subscription is registered and that what the relay accepts from then on will be pushed to it. The fence and every enumeration query MUST be issued on the same connection.
+
+Every event the fence delivers is collected exactly as an enumerated event is (step 2), which is what repairs the moved coordinate: the replacing event is itself what the relay pushes. Delivery is necessary but not sufficient — it must be delivery *before the verdict*, and those are different properties. Under push delivery alone, a relay that accepts a replacement, removes the version sitting below the cursor, and pushes the replacement some time later has violated nothing: the enumeration in between finds neither version, the pinned window and the continuation both come back empty, and the load reports *complete* moments before the fence delivers the floor it was missing. Ordering that push ahead of the verdict is what the delivery barrier below requires of the relay. On the client side, the verdict MUST NOT be rendered until end-of-stored-events for the final continuation has been received and every fence delivery received before it has been collected.
+
+If the client did not hold such a subscription for the whole load, or it lapsed or reconnected at any point during it, the load is potentially incomplete regardless of what the enumeration returned. A client MUST NOT publish to its own coordinates while its own load is in progress; a self-inflicted replacement is the same defect with the client on both ends of it.
+
+1. Every query MUST carry the same explicit `limit` `n`, `n` MUST be at least `L`, and no query MUST constrain tags. `C` and the floor are only meaningful across queries that differ solely in their time bounds. `n` SHOULD be substantially larger than `L`: `n` bounds how many events a single band can retrieve, so a small `n` costs round trips without making any verdict safer.
+2. From each delivered event, collect the read-state coordinates — those whose `d` tag has the form `read-state:<slot-id>` — deduplicating by `d` tag value and retaining, of the entries sharing a `d` tag value, the one with the greatest `created_at`, and on equal `created_at` the one with the lexicographically lowest event id. That is the addressable ordering NIP-01 defines, and both halves of it are load-bearing here: a replacement published in the same second as the version it replaces is legal and is the one the relay retains, so a retention rule that only compares `created_at` may keep the superseded version even when the fence delivered its successor perfectly. Ignore the other events, but count them: they are part of what the cap returned. Events the fence delivers are collected the same way, but MUST NOT contribute to `T` or to `C`: they are not a query result, and an event arriving below the cursor would otherwise move it down and skip the band between. Collection is what recovers a moved coordinate; the cursor descends on query results alone.
+3. Let `T` be the lowest `created_at` across **all** events delivered by the queries in this load, not only the read-state ones. The cursor therefore advances on every non-empty page, including one that yielded no coordinate.
+4. Before advancing past `T`, the client MUST query the pinned window `{"since": T, "until": T}` and merge the result. A cap can cut mid-second, leaving events at `T` that a continuation at `"until": T - 1` would skip forever; pinning both bounds to one second removes every event outside that second from contention for the cap.
+5. Second `T` is exhausted only if that pinned query delivered fewer than `max(C, L)` events. If it delivered `max(C, L)` or more, the cap may have bound inside the second, no finer cursor exists on the standard filter surface, and the load is **potentially incomplete** and MUST be reported as such. This verdict is terminal for the load: the client MUST NOT continue to step 6, and no later observation upgrades it. A continuation past an undischarged second can deliver nothing simply because that second was the oldest, so an empty continuation is not evidence that the second above it was exhausted.
+6. Otherwise continue with `"until": T - 1`. Because a bare `until` is inclusive, decrementing guarantees each continuation covers a strictly older band, so the loop makes progress regardless of how the relay caps.
+7. The load is **complete** when a continuation delivers no events at all, every preceding second having been discharged by step 5, the fence having been established before the first query and held unbroken since, and every fence delivery received up to that continuation's end-of-stored-events having been collected. Because the filter constrains nothing the relay applies after its cap, an empty delivery is an empty result — a cap that returns nothing is not a cap.
+8. A load that failed, or whose fence lapsed, on any relay the client publishes to is potentially incomplete (see Read-Before-Write).
+
+This layer places five requirements on every relay a client performs a full-state load against. They are stated normatively, not as background assumptions, because a *complete* verdict rests on them and none of them is verifiable from the responses a client receives:
+
+- **Newest-first prefix delivery.** A capped result MUST consist of the newest events by `created_at` for the filter, ties broken by lowest id — the delivery NIP-01 already specifies for `limit`. A relay that caps by returning some other subset can omit an event lying *above* the cursor the client derives from that same delivery, so the omitted event is never queried at all. Repeating a query cannot recover it, because the same filter with the same bounds is the same request.
+- **Non-decreasing effective cap within a load.** A relay MUST NOT reduce, within a single load, the number of events it will deliver for queries that differ solely in their time bounds. A cap that shrinks between the query establishing `C` and a later pinned window makes that window's short delivery indistinguishable from exhaustion, which converts a truncated second into a discharged one.
+- **The floor `L`.** A relay MUST deliver at least `L` events for a query whose matching set holds at least `L` and whose requested `limit` is at least `L`. `L = 2`, fixed by this NIP; a client MUST NOT derive it from relay-advertised discovery, because an advertised maximum is not necessarily the limit a relay enforces.
+- **Push delivery on an open subscription.** A relay MUST deliver every event it accepts that matches an open subscription's filter to that subscription. The mutation fence in step 2 is exactly this delivery; a relay that accepts a replacement without pushing it gives the client no way to observe a coordinate that moved above the cursor.
+- **The delivery barrier.** Before a relay sends end-of-stored-events for a query, every event it accepted before that query read its stored events, and which matches an open subscription on the same connection, MUST already have been delivered to that subscription. Push delivery alone promises only that the replacement arrives eventually; the barrier is what places it before the verdict that depends on it. Without it, a relay whose accept path and query path proceed independently can answer a query from storage the replacement has already changed while the corresponding push is still pending, and the client discharges the load in the interval between the two.
+
+A client cannot distinguish a relay that violates any of these from one that simply had fewer events to return, so these are conformance preconditions of this layer rather than properties a load establishes. A client MUST NOT perform a full-state load against a relay it knows, or has evidence, to violate them, and MUST treat any load against such a relay as potentially incomplete. Conditioning *complete* on positive proof of these properties instead would be equivalent to never issuing it — no such proof exists on the standard filter surface — which would withdraw the override layer from every client rather than from the non-conforming relays.
+
+The comparison in step 5 fails safe: a pinned window is reported potentially incomplete unless the relay has already shown it will deliver at least that many at once, so an inconclusive result is never mistaken for an exhaustive one. A plateau of more events at a single `created_at` than the relay will deliver for a window pinned to that second is therefore unenumerable, because this NIP defines no finer cursor, and it resolves to *cannot prove complete* rather than to a false *complete*. The comparison is a lower bound on the cap rather than the cap itself, so it is also conservative in the other direction: a load whose oldest second holds as many events as the largest delivery observed so far resolves to *cannot prove complete* even where the relay would have delivered more. Where more than one coordinate exists this is transient, because any later publish moves that coordinate to a different second and separates the two.
+
+The floor is the narrowest of the five requirements and the one that makes the ordinary case reachable at all. A coordinate at a replaceable kind contributes exactly one event no matter how many times it is republished, because a republish replaces the previous version rather than appending to it; a client's event count at this kind therefore does not grow over time, and a single-installation client publishing under one coordinate has one event at one second permanently. Without a floor, `C` for such a client is one, its pinned window delivers one, and step 5 can never be discharged — mark-unread would be permanently unavailable to the most common conforming deployment, and no amount of waiting or republishing would change the observation. `L = 2` discharges it: the pinned window delivers one event, `max(C, L)` is two, `1 < 2`, the second is exhausted, and the continuation below it is empty. That same replacement behaviour is what the fence exists for: the one event a coordinate contributes can move, and it moves by being replaced.
+
+A **potentially incomplete** load MUST NOT be the basis for any of the following, each of which either destroys override state or asserts authority over it:
+
+- canonical compaction of an override register (see Mandatory Canonical Publication),
+- publishing a canonicalized override blob,
+- deleting or abandoning any coordinate (see Orphaned Blob Deletion),
+- reporting an explicit mark-read as successful (see Actions).
+
+Until a complete load succeeds, the client MUST evaluate unread state from its own locally persisted state and MUST report override actions as failed rather than acting on a partial view. The honest terminal states are *complete* and *cannot prove complete*; a client MUST NOT treat the second as the first.
+
+The number of coordinates a full-state load must retrieve is bounded by the number of installations that have ever used the override layer, plus their not-yet-deleted rotation predecessors. It grows with the user's device history, not with elapsed time, and — because a coordinate carrying `ov_*` entries may not be deleted until it has been carried forward (see Client-ID Rotation) — it does not shrink on its own. Clients SHOULD carry forward and delete rotation predecessors promptly so the count stays near one coordinate per live installation.
 
 ### Merge Rule
 
@@ -311,6 +388,8 @@ effective[context] = max(timestamp) across all blobs
 
 This is a grow-only max-register state-based CvRDT with an associative, commutative, idempotent join. Clients MUST NOT lower a read timestamp — only advance it.
 
+The manual-unread override layer (see Manual-Unread Override Layer below) adds per-context set/clear counters merged by the same componentwise `max()` rule. The frontier merge rule is unchanged.
+
 ### Writing
 
 Clients MAY publish read state automatically when read-position sync is part of
@@ -320,28 +399,32 @@ to other users MUST require explicit user consent.
 
 Clients SHOULD publish read state blobs to the same relays they use for general event storage. Clients that implement NIP-65 (relay list metadata) SHOULD publish to their write relays and fetch from their read relays.
 
-Each client instance maintains its own blob (one `kind:30078` event per `<slot-id>`). Writing replaces the previous blob via parameterized replaceable event semantics ([NIP-33](33.md)).
+Each client instance maintains its own primary blob (one `kind:30078` event at its primary coordinate), plus one event per additional frontier-only coordinate if it uses any. Writing replaces the previous blob at each coordinate via parameterized replaceable event semantics ([NIP-33](33.md)).
 
-Clients MUST only update the blob whose decrypted `client_id` matches their own `client_id`. Clients MUST NOT overwrite another instance's blob.
+Clients MUST only update blobs whose decrypted `client_id` matches their own `client_id`. Clients MUST NOT overwrite another instance's blob.
 
-If the client discovers multiple blobs with its own `client_id` during a fetch, it MUST select the one with the highest `created_at` as its active blob and SHOULD delete the others.
+If the client discovers same-`client_id` blobs at coordinates that are neither its primary nor one of its known additional coordinates (e.g., rotation orphans or backup/restore duplicates), it MUST merge them into its own state and MUST NOT delete them until their override state has been carried forward (see Orphaned Blob Deletion). It MUST NOT publish to them: its own writes go to its primary and its known additional coordinates only.
 
 #### Read-Before-Write
 
 Before publishing, a client MUST:
 
-1. Fetch its own current blob from each relay it intends to publish to, and merge all fetched versions.
+1. Fetch its own current blob(s) from each relay it intends to publish to, and merge all fetched versions.
 
-The client fetches its own blob using its known `d` tag value:
+A client fetches its own coordinates using their known `d` tag values — its primary, plus its additional frontier-only coordinates if any — and unions them componentwise:
 
 ```json
-{"kinds": [30078], "authors": ["<user-pubkey>"], "#d": ["read-state:<own-slot-id>"]}
+{"kinds": [30078], "authors": ["<user-pubkey>"], "#d": ["read-state:<own-primary-slot-id>", "read-state:<own-additional-slot-id>", ...]}
 ```
 
-2. Decrypt and merge the fetched blob with local state using `max()` per context.
+A read-before-write fetch of the client's own coordinates is not a full-state load: it cannot discover rotation orphans or duplicates. Before canonicalizing override state or publishing a canonicalized override blob, the client MUST have a complete full-state load (see Full-State Load).
+
+2. Decrypt and merge the fetched blob(s) with local state using `max()` per context.
 3. Publish the merged result.
 
-If a relay is unreachable during the fetch step, the client SHOULD proceed with the data available from reachable relays. The merge rule ensures that data from the unreachable relay will be incorporated on the next successful fetch, provided the relay retains the event. Permanent relay loss or event expiry may result in state loss — this is an accepted property of the best-effort model (see Non-Goals).
+If a relay is unreachable during the fetch step, the client SHOULD proceed with the data available from reachable relays. The merge rule ensures that data from the unreachable relay will be incorporated on the next successful fetch, provided the relay retains the event. Permanent relay loss or event expiry may result in loss of frontier state — this is an accepted property of the best-effort model (see Non-Goals).
+
+That accepted loss does not extend to override state. A client MUST NOT treat a fetch that failed on any relay it publishes to as a complete view of its own override state, and MUST NOT canonicalize, publish canonicalized override state, or delete or abandon any of its own coordinates on the basis of such a partial fetch (see Full-State Load). Clients implementing the override layer SHOULD publish override state to more than one relay so that the loss of a single relay does not erase a tombstone floor.
 
 This read-before-write requirement also applies to re-publishes triggered by incoming blobs from other instances (see Live Subscription and Convergence).
 
@@ -358,12 +441,14 @@ Clients SHOULD subscribe to `kind:30078` events for their own pubkey with `#t: [
 When a blob from another client instance arrives (i.e., its decrypted `client_id` does not match the client's own `client_id`):
 
 1. Merge it into local state using `max()` per context.
-2. If any context timestamp in the incoming blob is greater than the corresponding timestamp in the client's last-published blob (or the context is absent from the last-published blob), perform a read-before-write and re-publish the client's own blob after a debounce delay.
-3. Clients MUST suppress the re-publish if the merged result is identical to the client's last-published blob. A client that has never published treats its last-published blob as empty.
+2. Canonicalize the merged override state against the client's own effective frontier (applying the tombstone floor and live/dead/virgin rules from Mandatory Canonical Publication). If any context entry in the canonical merged result differs from the corresponding entry in the client's last-published canonical blob (or the context is absent from the last-published blob), perform a read-before-write and re-publish the client's own blob after a debounce delay.
+3. Clients MUST suppress the re-publish if the canonical merged result is identical to the canonical form of the client's last-published blob. Comparing canonical-to-canonical prevents a retained live peer blob (which the client has already tombstoned) from triggering an identical write on every replay. A client that has never published treats its last-published blob as empty.
 4. Clients SHOULD limit re-publishes triggered by incoming blobs to at most one per debounce window, regardless of how many blobs arrive during that window.
 
 This drives convergence without a coordination round-trip, assuming eventual relay reachability and event retention.
 
+A live subscription is not a full-state load. A relay MAY return a capped set of stored events before end-of-stored-events on this filter, so a client implementing the override layer MUST NOT treat what the subscription delivers as a complete view of its coordinates (see Full-State Load). Merging an incoming blob into local state (step 1) is always safe, because merge is componentwise `max()`; the canonicalize-and-re-publish in steps 2–3 is a canonical publication and therefore requires a complete full-state load. A client that does not have one MUST defer the re-publish rather than publish a canonical blob derived from a partial view. A subscription is nonetheless a required *component* of a full-state load, serving as its mutation fence, and the fence MUST use the tag-free filter rather than the `#t`-narrowed one above — a replacement it fails to deliver is a replacement the descending enumeration cannot recover.
+
 #### Clock Skew
 
 When publishing, if the client's local clock produces a `created_at` value less than or equal to the maximum `created_at` seen across all fetched blobs for the same `d` tag, the client MUST use `max_fetched_created_at + 1` instead.
@@ -372,17 +457,158 @@ When publishing, if the client's local clock produces a `created_at` value less
 
 Clients SHOULD debounce writes to avoid excessive relay traffic (e.g., flush 5–10 seconds after the last local read-state change, or on app close/background transition). Clients MUST NOT write on every individual read action.
 
-The blob SHOULD contain only contexts the client has explicitly interacted with. Clients SHOULD prune aggressively, prioritizing recently-active contexts, and MAY drop entries older than the time horizon before writing. Clients MUST ensure the published event does not exceed relay event size limits (typically 64 KB content).
+The blob SHOULD contain only contexts the client has explicitly interacted with. Clients SHOULD prune aggressively, prioritizing recently-active contexts, and MAY drop frontier entries older than the time horizon before writing. Clients MUST NOT drop `ov_*` override entries (including tombstone floors) based on age or budget pressure; see Override State Durability in the Manual-Unread Override Layer section. Clients MUST ensure the published event does not exceed relay event size limits (typically 64 KB content).
 
 #### Client-ID Rotation
 
-Clients MAY rotate their `client_id` by generating a new one, generating a new random `<slot-id>`, and publishing a new blob. The old blob becomes orphaned and ages out of the time horizon naturally. Rotation adds one extra blob temporarily. Clients SHOULD keep their `client_id` stable for as long as possible to minimize blob proliferation.
+Clients MAY rotate their `client_id` by generating a new one, generating a new random `<slot-id>` for the primary coordinate, and publishing a new blob. Rotation adds one extra blob temporarily. Clients SHOULD keep their `client_id` stable for as long as possible to minimize blob proliferation.
+
+Rotation is the only event that changes a client's override-bearing coordinate, and it carries the layer's single durability obligation:
+
+**Carry-forward rule.** Before deleting or abandoning its previous primary, a rotating client MUST publish the componentwise `max()` of every override register the old primary holds — every tombstone ceiling included — under its new primary, and MUST confirm acceptance **on every relay from which the old primary will be deleted or allowed to lapse**. If any such relay rejects the publish or is unreachable, the client MUST retain the old primary on that relay and MUST NOT delete it there. Acceptance on one relay does not authorize deletion on another: a relay that never received the replacement would otherwise be left with no local carrier of the floor. The old primary MUST NOT be left to age out while it is the only carrier of an override floor on any relay.
 
-If a device backup or clone results in two installations sharing the same `client_id` and `slot-id`, both will write to the same blob. This is operationally equivalent to a single client and does not corrupt state, but the two installations will overwrite each other's context entries. Clients that detect this condition (e.g., by observing unexpected context changes in their own blob) SHOULD generate a new `client_id` and `slot-id`.
+Additional frontier-only coordinates carry no override state, so rotation may abandon or delete them freely.
+
+If a device backup or clone results in two installations sharing the same `client_id` and primary `<slot-id>`, both will write to the same coordinate. This is operationally equivalent to a single client and does not corrupt state, but the two installations will overwrite each other's context entries. Clients that detect this condition (e.g., by observing unexpected context changes in their own blob) SHOULD generate a new `client_id` and a fresh primary `<slot-id>`, again carrying override state forward per the carry-forward rule.
 
 #### Orphaned Blob Deletion
 
-Clients MAY delete blobs from decommissioned client instances by publishing a `kind:5` deletion event per [NIP-09](09.md) targeting the orphaned event's `a` tag coordinate (`30078:<pubkey>:<d-tag-value>`). This is optional — orphaned blobs are harmless and age out naturally.
+Clients MAY delete blobs from decommissioned client instances by publishing a `kind:5` deletion event per [NIP-09](09.md) targeting the orphaned event's `a` tag coordinate (`30078:<pubkey>:<d-tag-value>`). For blobs carrying no `ov_*` entries — including a client's own additional frontier-only coordinates — this is optional and unconditional: such blobs are harmless and age out naturally.
+
+A blob carrying `ov_*` entries MUST NOT be deleted or abandoned until its override state has been carried forward per the carry-forward rule in Client-ID Rotation. This applies to the client's own previous primary and to same-`client_id` orphans discovered from a prior rotation or a backup/restore. A client's record of its own coordinates MAY be stale — for example restored from a backup taken before a rotation — so an unknown same-`client_id` coordinate MUST be treated as a live carrier of override state, not as a deletable duplicate, until it has been merged and carried forward.
+
+### Manual-Unread Override Layer
+
+This section defines a manual mark-as-unread mechanism as a CRDT override layer within the existing `contexts` map. It does not change the frontier merge rule, event structure, or encryption scheme. Fetching follows the override-specific full-state procedure (see Full-State Load) rather than the horizon-bounded fetch used by clients that do not implement this section. Clients that do not implement this section remain fully interoperable (see Backwards Compatibility).
+
+#### Wire Encoding
+
+For each manually-unread context `<ctx>`, a client publishes up to three sibling keys alongside the existing frontier entry in the `contexts` map:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `ov_s:<ctx>` | uint32 | Set counter S — incremented on each mark-unread |
+| `ov_c:<ctx>` | uint32 | Clear counter C — incremented on each mark-read |
+| `ov_b:<ctx>` | uint32 | Baseline B — the effective frontier value at the time of the most recent mark-unread |
+
+Values MUST be integers in the range 0–4294967295 (same validation range as context timestamps). The `<ctx>` suffix is the raw context ID without any escaping (escaping applies only to the frontier wire key; see Reserved Namespace).
+
+#### Merge Rule (Override Registers)
+
+Override counters are merged by componentwise `max()`, identical to the frontier merge rule:
+
+```
+merged_S[ctx] = max(S) across all blobs
+merged_C[ctx] = max(C) across all blobs
+merged_B[ctx] = max(B) across all blobs
+```
+
+No new wire-level merge logic is required. The same `mergeReadStateEvents` path that joins frontier timestamps joins the counter entries as integer max.
+
+#### Liveness Predicate
+
+A context `ctx` has an active manual-unread override if and only if ALL of the following hold, evaluated against the merged register `(S, C, B)` and the merged effective frontier `F`:
+
+1. `S > 0` — at least one mark-unread action has been recorded.
+2. `F <= B` — the effective frontier has not advanced past the baseline captured at mark-unread time. (A natural frontier advance strictly past `B` dominates a stale set, clearing the override without any explicit clear action.)
+3. `S > C` — set counter exceeds clear counter. (`S == C` is treated as inactive: clear wins on ties — see Tie Policy.)
+
+Formally (clear-wins is the only conforming tie policy — see Tie Policy):
+
+```
+override_active(S, C, B, F) =
+  S > 0
+  AND F <= B
+  AND S > C
+```
+
+The **unread verdict** for a context is:
+
+```
+unread(ctx) = (latest_message_ts > F) OR override_active(S, C, B, F)
+```
+
+where `latest_message_ts` is the `created_at` of the newest message in the context.
+
+#### Actions
+
+Every action below requires a complete full-state load (see Full-State Load); on a potentially incomplete load the client MUST report the action as failed rather than act on a partial view of its own override state.
+
+**Mark-unread:** increment S to `max(S, C) + 1`; set B to the current effective frontier value for the context. C is unchanged. If `max(S, C) == 4294967295` (uint32 maximum), the client MUST refuse the mark-unread action and leave the register unchanged; wrapping or resetting to zero is prohibited.
+
+**Mark-read (explicit):** advance the frontier to cover the context as normal; increment C to `max(S, C) + 1`. S and B are unchanged. If `max(S, C) == 4294967295`, no representable counter increment exists; wrapping or resetting to zero is prohibited. The client MUST then complete the action only if the resulting state satisfies `override_active == false` — i.e. the frontier advance alone deactivates the override, or the override was already inactive. Otherwise the counters MUST be left unchanged and the client MUST report the mark-read as failed; the monotone frontier advance itself is still permitted, but a client MUST NOT report an explicit mark-read as successful while `override_active` remains true.
+
+**Natural read (frontier advance):** advance the frontier past B. No counter update is needed — the liveness predicate's `F <= B` condition automatically deactivates the override when the frontier dominates the baseline.
+
+#### Tombstone Floor
+
+A register where `S > 0` or `C > 0` (ever-active) that evaluates as inactive MUST be compacted to the tombstone floor before publication:
+
+```
+tombstone = RegB(S=0, C=max(S, C), B=0)
+```
+
+This preserves the counter ceiling as a reuse-blocking floor. A register where `S == 0` and `C == 0` (virgin, never activated) MUST be omitted from the wire entirely (0 keys).
+
+#### Mandatory Canonical Publication
+
+Publishers MUST canonicalize every override against their own effective frontier at serialization time before writing to the wire:
+
+- **Live override** (`override_active` is true): publish all three keys (`ov_s:`, `ov_c:`, `ov_b:`) with their current values unchanged.
+- **Dead override** (`override_active` is false, `S > 0` or `C > 0`): publish only the tombstone floor — a single `ov_c:` key with value `max(S, C)`.
+- **Virgin register** (`S == 0` and `C == 0`): omit all three keys from the wire.
+
+This is a protocol requirement, not an optimization. A client that publishes raw (non-canonical) dead registers can cause two independently-dead registers from different devices to produce a live join on merge. See `docs/formal/nip-rs-unread/` for the exhaustive proof and mutation harness.
+
+#### Override Group Co-Location Rule
+
+A context's frontier entry and ALL of its `ov_*` sibling entries MUST travel in the same event, and that event MUST be the primary coordinate. Because all `ov_*` entries live in the primary (see `d` Tag), an override-bearing context has exactly one legal destination for its whole group: a client that splits frontier entries into additional coordinates MUST NOT move the frontier entry of an override-bearing context out of the primary, and MUST NOT place `ov_*` entries anywhere else. Only frontier-only groups — contexts with no `ov_*` entries — may be distributed across additional coordinates.
+
+Implementations that split blobs across coordinates MUST group context entries per logical context — not per individual key — and assign the entire group atomically to one coordinate. Round-robin or other assignment strategies MUST operate on groups, not on individual entries.
+
+**Unescape-before-group rule (corollary):** when grouping, a frontier wire key MUST be unescaped to its raw logical context ID (stripping one leading `esc:` if present) before being used as the group identity. Without this step, a frontier key `esc:ov_s:evil` and its `ov_*` siblings (keyed by the raw suffix `ov_s:evil`) resolve to different groups and the register splits across coordinates, reproducing the partial-reconstruction poison across publication cycles.
+
+**Rationale:** a receiver holding only a partial group (e.g., `ov_s:ctx` without `ov_b:ctx`) reconstructs a register with incorrect baseline and may canonically publish a false tombstone. With atomic grouping, a compliant publisher's output never permits partial reconstruction.
+
+#### Tie Policy
+
+**Clients MUST use clear-wins.** When `S == C` and `S > 0`, the override MUST be treated as inactive, and the register MUST be compacted to the tombstone floor on publication (see Tombstone Floor).
+
+Clear-wins is normative rather than a local implementation choice because the tie verdict is not encoded on the wire. Two conforming clients holding the same merged register `(S, C, B, F) = (1, 1, 10, 10)` would otherwise disagree permanently: a clear-wins client reports read and publishes the single-key tombstone floor, a set-wins client reports unread and publishes all three keys. Further deliveries converge the counters but can never converge either the verdict or the canonical wire form, which defeats cross-device synchronization. Supporting a selectable tie policy would require encoding the policy in the blob plus a separate interoperability design; neither is in scope here.
+
+Clear-wins also matches the product semantics this layer is designed for: a false negative (a missed badge) is recoverable by re-marking unread, while a false positive (a badge that will not clear) is more disruptive. See `docs/formal/nip-rs-unread/NOTE.md` for the policy comparison — both policies satisfy the merge-correctness invariants in isolation, so this is an interoperability requirement, not a merge-safety one.
+
+#### Override State Durability
+
+`ov_*` override entries — especially tombstone floors (`ov_c:` keys) — carry a reuse-blocking counter ceiling that prevents stale override components from resurrecting a dead register. Specifically, if a tombstone floor `(S=0, C=k, B=0)` is dropped and a stale snapshot `(S=k, C=0, B=b)` is later replayed, the merged result `(S=k, C=0, B=b)` would evaluate as live — a resurrection.
+
+Because legacy clients can carry and republish old `ov_*` keys indefinitely (they pass through `sanitizeContexts` as unknown opaque entries), there is no finite time after which all stale override components are guaranteed absent. Therefore:
+
+**Clients MUST NOT drop `ov_*` override entries (including tombstone floors) based on age pruning or budget eviction.** This exemption applies permanently. Age-based pruning applies to frontier entries only. Eviction strategies that respect byte/key budgets MUST apply to frontier and `msg:`/`thread:` entries first and MUST NOT touch `ov_*` entries.
+
+**Durability is a property of retrievable logical state, not of keys within one blob.** An override register survives only if a client that loads its full state can still reach every component. Therefore, in addition to the per-entry rule above:
+
+- Full-state loads by clients implementing this layer MUST NOT be restricted by a finite event-level `since` window, and MUST establish completeness rather than assume it; the containing event must remain reachable, not merely retain its keys (see Full-State Load).
+- No coordinate carrying `ov_*` entries may be deleted or abandoned until the componentwise `max()` of every override register it holds — especially every tombstone ceiling — has been republished under the client's current primary coordinate and accepted on every relay from which the old coordinate will be deleted or allowed to lapse (see Client-ID Rotation, Orphaned Blob Deletion).
+
+**There is no safe finite GC horizon for override state.** Any protocol that proposes to delete tombstone floors after a bounded period requires a separately proved guarantee that no stale override component can re-enter the merge — this amendment does not provide such a guarantee.
+
+#### Bounds and Budget
+
+- **Key growth:** a live override adds 3 entries per context; a tombstoned override adds 1 entry per context. At 100 overridden channel contexts: ~300 live entries or ~100 tombstone entries.
+- **Byte cost (small-counter example, common case):** channel UUID context (36 chars), counters S=1/C=0/B=10 — live override ~138 bytes; tombstone ~45 bytes. **Byte cost at uint32 maximum** (S=4294967295, worst case): live override ~164 bytes; tombstone ~54 bytes.
+- **Hard ceiling on ever-overridden contexts.** Because all `ov_*` entries live in one coordinate (see `d` Tag) and tombstones can never be pruned (see Override State Durability — there is no safe finite GC horizon), the primary blob's plaintext budget is a hard ceiling on the number of contexts a single installation can ever have manually marked unread. Against a 32 KiB plaintext budget: roughly **600** tombstoned contexts at the worst-case ~54 bytes, ~730 at the common ~45 bytes, or ~199 simultaneously live overrides at ~164 bytes — and that is before frontier entries get any room at all.
+- **Terminal behaviour at the ceiling.** When the primary blob cannot accommodate a new override group after all prunable frontier entries have been evicted, the client MUST refuse the mark-unread action and report it as failed. It MUST NOT split override state across coordinates and MUST NOT drop tombstone floors to make room. Likewise, a client whose merged override state — including tombstones merged in from peer installations — no longer fits in its primary blob MUST leave its last-published primary in place, MUST NOT publish a primary that omits merged `ov_*` entries, and MUST report override actions as failed; publishing a truncated override set is budget-driven override loss under another name. No floor is lost in this state, because the installations that originated those floors still carry them; the constrained installation simply stops acting as a replica until it has room. This is the same policy shape as counter exhaustion (see Actions): visible failure, never silent degradation.
+- **10,000-key limit:** override entries count toward the existing per-blob validation limit. Tombstones accumulate permanently with every distinct ever-overridden context; they cannot be pruned. Clients SHOULD compact dead overrides aggressively and MAY enforce an active-live-override cap. Note that a cap on live overrides does not bound the total `ov_*` entry count over an unbounded context lifetime — tombstones from all historical overrides remain. The 32 KiB and 10,000-entry limits are expressed per blob at write time; a client that has overridden many distinct contexts over its lifetime must account for all accumulated tombstones when evaluating budget headroom.
+- **256-byte key limit:** override keys (`ov_s:`, `ov_c:`, `ov_b:` + context ID) count toward the per-entry 256-byte validation limit. Context IDs up to 251 bytes are safe. Buzz's own context ID shapes (UUID 36 bytes, `msg:hex64` 68 bytes, `thread:hex64` 71 bytes) are well within this limit.
+
+#### Verification Artifact
+
+The design was verified by bounded exhaustive model checking prior to this amendment. See `docs/formal/nip-rs-unread/` for the full model (`model.py`, `exhaustive.py`), 9-mutant harness (`mutation.py`), and design notes (`NOTE.md`).
+
+The harness verifies the three load-bearing safety requirements — tombstone floor, mandatory canonical publication, and atomic per-context grouping with unescape-before-group — are necessary: each mutant that drops one of these rules produces a detectable witness of permanent false-clear or resurrection. M3 validates that the clear-wins tie policy produces the intended product-semantics behavior; M5 and M6 witness value-range and convergence failures respectively. Clear-wins is normative for interoperability (see Tie Policy), not because set-wins violates merge safety — the model confirms both tie policies satisfy the merge-correctness invariants when applied uniformly.
+
+**Scope of formal verification:** the bounded model covers the CRDT register algebra, merge/compaction rules, per-context grouping atomicity, and escape/unescape bijection. The model is a broader predecessor of this NIP: its `split_blob_into_slots` permits override groups in any slot, whereas this NIP confines them to one primary coordinate, so the verified atomicity property holds for every arrangement this NIP permits but the converse does not follow. The model does **not** verify the single-primary rule, the full-state-load completeness procedure, the relay conformance requirements or the mutation fence it depends on, or the carry-forward rule; those are normative here and argued, not proved. The model also does NOT cover malformed-group wire validation (the accepted-shape rules in Content Validation). That rule is sound by the partial-group argument (rejecting a partial group leaves a virgin register — a merge no-op — which is strictly safer than zero-filling missing components), but its correctness under parser-level implementation is outside the model's verified scope. Implementation-level tests MUST cover the accepted wire shapes and rejection behavior.
 
 ## Example
 
@@ -504,9 +730,9 @@ The conversation key is `nip44_conversation_key(private_key, public_key)` — EC
 
 ### Conflict Detection Vector
 
-Device A has `slot-id` = `aaa111` and `client_id` = `client-A`. It fetches its own `d` tag coordinate `read-state:aaa111` and decrypts the blob. The decrypted `client_id` is `client-B` (not `client-A`). This is a slot-id conflict — another device has claimed this coordinate.
+Device A has `slot-id` = `aaa111aaa111aaa111aaa111aaa111aa` and `client_id` = `client-A`. It fetches its own `d` tag coordinate `read-state:aaa111aaa111aaa111aaa111aaa111aa` and decrypts the blob. The decrypted `client_id` is `client-B` (not `client-A`). This is a slot-id conflict — another device has claimed this coordinate.
 
-Device A MUST NOT publish to `read-state:aaa111`. Device A MUST generate a new random `slot-id` (e.g., `ccc333`) and publish its blob under `read-state:ccc333`.
+Device A MUST NOT publish to `read-state:aaa111aaa111aaa111aaa111aaa111aa`. Device A MUST generate a new random `slot-id` (e.g., `ccc333ccc333ccc333ccc333ccc333cc`) and publish its blob under `read-state:ccc333ccc333ccc333ccc333ccc333cc`.
 
 ### Clock Skew Vector
 
@@ -541,7 +767,7 @@ Ciphertext length reveals the approximate number of tracked contexts and may cor
 
 Because slot IDs are random and independent of `client_id` values, relay operators cannot directly link blobs to specific devices or client implementations. Timing correlation and write patterns may still allow probabilistic linkage.
 
-Because the merge rule is monotonic, replaying an old event to a relay is harmless — it cannot lower a read timestamp. However, replaying many old events simultaneously could trigger convergence re-publishes from active clients. The debounce window (see Debounce and Pruning) limits this to at most one re-publish per window.
+Because the frontier merge rule is monotonic, replaying an old frontier event to a relay is harmless — it cannot lower a read timestamp. The override layer's counter merge is also monotonic (componentwise max), so replaying an old override event cannot lower a counter; however, a stale override component replayed after a tombstone floor was published could suppress a fresh set for one reconciliation cycle (see Override State Durability). The debounce window (see Debounce and Pruning) limits convergence re-publishes to at most one per window.
 
 Clients supporting multiple Nostr identities SHOULD use distinct `client_id` values and distinct slot IDs per identity. Reusing identifiers across pubkeys allows relay operators to link those identities.
 
@@ -557,10 +783,13 @@ that expose read activity to other users MUST require explicit user consent.
 
 ## Backwards Compatibility
 
-This NIP introduces no changes to existing event kinds or relay behavior. It uses only standard NIP-01 event storage, NIP-33 addressable event semantics, NIP-44 encryption, and NIP-78 application data conventions. Clients that do not implement this NIP are unaffected.
+This NIP introduces no changes to existing event kinds and adds no new kind, wire message, or relay-stored read-state logic. It uses only standard NIP-01 event storage, NIP-33 addressable event semantics, NIP-44 encryption, and NIP-78 application data conventions. Clients that do not implement this NIP are unaffected, as are clients that implement everything but the manual-unread override layer.
+
+The override layer is the exception, and it is a relay-compatibility one rather than a client one. Its full-state load carries the completeness guarantee only against a relay that satisfies the ordering, capacity, floor, push, and barrier requirements enumerated in Full-State Load. Against a relay known or evidenced not to conform, every load resolves to *cannot prove complete* and the actions that depend on a complete load report as failed; against an undetectably nonconforming relay, a load may still return *complete*, and the completeness guarantee does not apply to that verdict. In either case the layer still runs and still merges, and frontier sync is unaffected.
 
 ## References
 
+- [NIP-01](01.md) — Basic Protocol Flow Description (defines filter `limit`, `since`, and `until`)
 - [NIP-09](09.md) — Event Deletion Request
 - [NIP-33](33.md) — Parameterized Replaceable Events
 - [NIP-44](44.md) — Versioned Encryption
diff --git a/docs/remote-agents.md b/docs/remote-agents.md
new file mode 100644
index 0000000000..48ce85f5e5
--- /dev/null
+++ b/docs/remote-agents.md
@@ -0,0 +1,1770 @@
+# Remote Agents and Their Management: A Formal Specification
+
+`draft`
+
+## Abstract
+
+This document specifies the protocol by which Buzz Desktop delegates the
+execution of a managed agent to a **remote substrate** — any compute
+environment other than the local machine — through a **backend provider
+binary**, and specifies the lifecycle contract every provider and every
+remotely-run agent must satisfy. It covers three layers:
+
+1. **The provider protocol** — a zero-registration plugin contract between the
+   desktop and any executable named `buzz-backend-<id>`: discovery, the `info`
+   and `deploy` operations, payload schema, and the security obligations on
+   both sides of that boundary.
+2. **The remote lifecycle model** — how a remote agent is started, observed,
+   stopped, and reaped, given the deliberate design constraint that **the
+   desktop holds no management channel to the remote process**. Relay
+   presence is the sole status signal; shutdown is a relay message; liveness
+   bounds are enforced by the agent harness itself, not by the desktop.
+3. **The Kubernetes binding** — the first conforming provider,
+   `buzz-backend-kubernetes`, which realizes the contract as a bare Pod
+   running the `sprig` image.
+
+We state five invariants — **identity fail-closed**, **no secrets in
+configuration**, **presence-is-status**, **at-most-one-live-instance**, and
+**intentional-termination-is-final** — and argue each from the protocol
+rules.
+
+A scoping note that governs the whole document: the desktop is **one
+launcher among many**. What makes a process a live Buzz agent is a keypair,
+a NIP-OA auth tag, and a relay URL, handed as environment to the `buzz-acp`
+harness; anything that can set that environment and exec the harness — a
+bash script, a systemd unit, a CI job, or this document's provider protocol
+— is a conforming launcher. §Launchers states which obligations bind whom.
+
+As with the git
+specification (`git-on-object-storage.md`), naming the trust boundary is part
+of the claim: a provider binary is arbitrary code that is handed an agent's
+private key, and this document states exactly which properties hold *despite*
+that, which hold only if the provider is honest, and which are explicitly the
+user's acceptance.
+
+## Scope and Non-Goals
+
+This specification defines **management-plane behavior**: how agents get to a
+substrate, how their state is observed, and how their lifetime is bounded. It
+deliberately does **not** specify:
+
+- **Agent conversational behavior.** What the agent does with events is
+  governed by the ACP harness (`buzz-acp`) and the NIPs it implements
+  (NIP-OA, NIP-AE, NIP-AA, …), unchanged by where the harness runs.
+- **Malicious-provider containment.** A provider binary receives the agent's
+  `nsec` by design — that is its job. The protocol *bounds the desktop's
+  exposure* (discovery-only resolution, output caps, secret redaction,
+  anti-secret config validation, an explicit UI trust warning) but cannot make
+  a hostile provider safe. Choosing to run a provider is a trust decision the
+  UI surfaces to the user; this document does not claim otherwise.
+- **Substrate security.** Kubernetes RBAC, namespace isolation, and secret
+  encryption at rest are cluster-operator concerns. The Kubernetes binding
+  states its residual exposure (§K8s Secrets) rather than claiming isolation
+  it does not provide.
+- **Liveness of the substrate.** That a pod schedules, that an image pulls,
+  that a cluster is reachable — empirical, not formal. The protocol specifies
+  only how such failures are *reported* (structured error, redacted,
+  fail-closed).
+
+## System Model
+
+Five principals:
+
+- **Desktop** `D` — the Buzz Desktop app. Holds the agent's identity (nsec in
+  the OS keyring), its configuration record, and the only UI. Trusted.
+- **Provider** `P` — an executable `buzz-backend-<id>` on `D`'s machine.
+  Invoked one process per operation: JSON request on stdin, JSON response on
+  stdout, exit code carrying one bit (zero = output trustworthy, nonzero =
+  failure regardless of stdout — §Invocation). **Untrusted by `D`** for everything except
+  the job it is explicitly given (deploying the agent, which requires the
+  key). All of `P`'s output is treated as hostile (§Provider Output).
+- **Substrate** `S` — the remote compute environment `P` deploys into (a
+  Kubernetes cluster for the binding in this document). Opaque to `D`;
+  `D` never talks to `S`.
+- **Agent** `A` — a `buzz-acp` harness process (plus the ACP agent under it)
+  running on `S`, holding the nsec it was given, connected to the relay.
+- **Relay** `R` — the Buzz relay. The *only* channel that connects `D` to a
+  running `A`. Everything `D` knows about a live remote agent, it learns
+  from `R`.
+
+The defining constraint, stated as a design axiom:
+
+- **(M1) No management channel.** After a successful `deploy`, `D` holds no
+  **persistent management session** to `A` on `S`, and the desktop↔provider
+  protocol contains **no substrate API**: no status query, no exec, no log
+  fetch, no kill. All post-deploy observation and control flows through `R`:
+  status is relay presence (kind:20001), stop is a relay message
+  (`!shutdown`), and reconfiguration is a future re-deploy. The reduction M1
+  buys is **protocol surface, not credential absence**: ambient substrate
+  credentials may well exist on `D`'s machine (the Kubernetes binding uses
+  the user's kubeconfig by design), and `D` can always re-invoke `P`. What
+  M1 guarantees is that nothing in *this protocol* — its persisted records,
+  its wire operations, its stored `backend_agent_id` — constitutes or
+  requires a channel to the substrate. The price is the staleness bounds in
+  §Presence.
+
+An agent's identity is a Nostr keypair. The **agent record** on `D` carries:
+`name`, `relay_url`, the nsec (keyring-hydrated), the NIP-OA `auth` tag
+attesting owner authorization, `agent_command`/`agent_args` (the ACP agent the
+harness spawns — `goose`, `claude-agent-acp`, `codex-acp`, `buzz-agent`, or
+any user-supplied command: this is the **configurable harness** requirement),
+effective `system_prompt`/`model`/`provider`, timeout and parallelism knobs,
+the `respond_to` gate, merged `env_vars`, and a `backend` discriminator:
+`Local` or `Provider { id, config }`.
+
+### Launchers {#launchers}
+
+The five principals above describe the **provider-managed** launch path.
+That path is not the definition of a remote agent, and this section states
+the actual layering, because the obligations in this document do not all
+bind at the same layer. Three contracts, nested:
+
+1. **The agent/harness contract — binds every launcher.** A live Buzz agent
+   is a `buzz-acp` process holding a keypair, a NIP-OA auth tag (or resolved
+   owner pubkey), and a relay URL, delivered as environment. The relay
+   authenticates the keypair and the auth tag — never the launcher. At this
+   layer live: fail-closed identity (I1's property, enforced wherever the
+   env is assembled), presence publication (I3), owner-verified `!shutdown`,
+   and **intentional clean exit is terminal to automatic supervisor
+   restart** (I5). A bash script that exports `BUZZ_PRIVATE_KEY`,
+   `BUZZ_RELAY_URL`, `BUZZ_AUTH_TAG` and execs the harness is a conforming
+   launcher at this layer — today, with no code change.
+2. **The provider/deployer contract — binds provider-managed launches
+   only.** The two operations (`info`/`deploy`), the reconciliation loop,
+   and at-most-one-live-instance *per deploy scope* (I4). Hand-launched
+   agents sit outside it by construction: a launcher that bypasses the
+   provider protocol takes on the uniqueness discipline itself, exactly as
+   the cross-scope boundary in I4 already states. The protocol cannot and
+   does not promise a global singleton across unrelated launchers of the
+   same nsec.
+3. **The binding policy — per substrate.** Fingerprints, fenced deletes and
+   409 discrimination, restart-policy selection, the default idle bound,
+   and the grace budget are Kubernetes-binding policy (§The Kubernetes
+   Binding). A different substrate (the systemd/SSH deployer of PR #3449 is
+   the live example) conforms to layers 1–2 and writes its own layer 3; it
+   is not "non-conforming" for lacking pods.
+
+The desktop is therefore one launcher among many, and the provider protocol
+is the *desktop's* door to substrates, not the only door. §Conformance
+carries one checklist per layer.
+
+## Invariants
+
+The protocol maintains five invariants. Each is stated with the mechanism
+that enforces it and the boundary beyond which it does not hold.
+
+A design obligation governs the whole list: **the complexity budget is
+spent in this document, not in the code**. Every guarantee here was chosen
+because its enforcing mechanism is one small, boring thing — a refusal at
+payload construction (I1), a key-shape validator (I2), an ephemeral event
+the agent already publishes (I3), a deterministic name plus one annotation
+compare (I4), a timer that fires an existing shutdown channel (I5). The
+same rule holds below: the deploy state machine is one loop over seven
+ordered rows; the Secret scheme is "unique name, write first, reference
+exactly"; GC is one label-select with two filters (annotation, same-clock
+age). Where
+a richer property would have demanded machinery — Leases, controllers,
+ownerReferences, a management channel — the spec either found a
+name-and-timestamp argument that makes the machinery unnecessary or
+dropped the property and said so (§Non-Goals, M1). A conforming
+implementation that is not small is evidence of a spec bug; report it as
+one.
+
+- **(I1) Identity fail-closed.** No agent is ever launched with an empty or
+  missing private key: whatever assembles the harness environment — desktop,
+  provider, bash script — MUST refuse rather than launch identityless
+  (§Launchers, layer 1). In the provider path this is enforced at payload
+  construction: if keyring hydration left the nsec empty,
+  `build_deploy_payload` refuses (mirroring local spawn's
+  `spawn_key_refusal`), so no deploy request is ever emitted with an empty
+  key. Boundary: a provider that *discards* the key and launches an
+  identityless pod is a broken provider; the payload rule governs what `D`
+  sends, not what `P` does with it — which is why the property also binds
+  at `P`'s env assembly and at every non-provider launcher.
+
+- **(I2) No secrets in configuration.** `provider_config` — the persisted,
+  schema-rendered, UI-visible settings object — MUST NOT carry secrets.
+  Enforced by validation: flat object, scalar values only, ≤20 fields, ≤64KB,
+  and any key whose word-split contains `secret|password|token|key|credential`
+  is rejected. The match is against key *names*, so it is a lint with false
+  positives: a field like `ssh_key_path` holds a path, not a credential,
+  and is refused anyway — a provider author hitting this MUST rename the
+  field (e.g. `identity_file`), not weaken the validator; the rule's job is
+  making "put the secret in config" fail closed, and cheap false positives
+  are the accepted price. Secrets flow exclusively inside the `deploy` payload
+  (`private_key_nsec`, `auth_tag`, `env_vars`), which is never persisted by
+  `D` and never rendered. Corollary for providers: cluster credentials MUST
+  come from ambient substrate config (e.g. kubeconfig resolution), never from
+  `provider_config`.
+
+- **(I3) Presence is the status.** `D` derives a remote agent's live state
+  exclusively from relay presence events self-signed by the agent key:
+  `online`/`away`/`offline` (kind:20001, ephemeral, WS-published). The
+  deployment axis (`deployed`/`not_deployed`, from the stored
+  `backend_agent_id`) is bookkeeping, not liveness. Staleness bound: presence
+  can be wrong for the window between an abnormal agent death (SIGKILL, node
+  loss) and the relay's presence expiry — **180 seconds**
+  (`PRESENCE_TTL_SECS`, `buzz-pubsub/src/presence.rs:16`; the vision's
+  "a bounded wrong dot, never an indefinite one"), the accepted
+  cost of M1. The specific number is a relay-wide constant, not a
+  remote-agent choice: #3783 raised it from 90s to keep a three-heartbeat
+  expiry window after the desktop heartbeat moved to 60s. What I3 promises
+  is that the window is *bounded*, not its width.
+  The Kubernetes binding minimizes the *avoidable* part of that window by
+  sizing the termination grace period to the harness's full graceful-shutdown
+  path (§K8s Grace). Two consequences the bound imposes: (a) the harness's
+  presence-suppression knob, `BUZZ_ACP_NO_PRESENCE`, MUST join
+  `RESERVED_ENV_KEYS` — locally the knob is cosmetic (the process and UI
+  remain visible), but remotely M1 makes presence the *only* signal, so an
+  unreserved user env var would convert "wrong for ≤180s" into "wrong
+  indefinitely" and silently disarm the one bound in print; (b) presence is
+  scoped to a **community**: the relay derives community from its host, so
+  the deploy-time `relay_url` binds the body to one community for its whole
+  life, and a workspace observing through a different community sees the
+  agent offline while a deploy against it correctly no-ops — a known UX
+  boundary (the cross-scope boundary I4 admits, seen from the status side),
+  stated here so the two honest-but-conflicting readouts are diagnosable.
+
+- **(I4) At most one live instance per agent key per deployment scope.**
+  Within one provider's deployment scope (for Kubernetes: one namespace),
+  there is never more than one Running instance of a given agent pubkey.
+  Enforced by the deploy reconciliation loop (§Deploy State Machine):
+  deploy is keyed on the derived pubkey, a live instance maps to strict
+  no-op, and — because two deploys can race — create/delete conflicts MUST
+  converge (re-read and return the winner) rather than fail; deterministic
+  instance naming makes the substrate itself reject a second live instance.
+  Boundary: the protocol cannot prevent the same nsec being
+  deployed to two different scopes (two namespaces, two clusters, or remote
+  + local simultaneously) — the relay tolerates multiple connections per key,
+  and preventing this would require the global registry M1 forbids. Deploying
+  one key twice is user error with confusing-but-safe results (both instances
+  answer), not a safety violation.
+
+- **(I5) Intentional termination is final.** A remote agent **stops when
+  told, stays down when it stops, and is never silently resurrected**: an
+  instance whose harness is live terminates on owner `!shutdown` or when a
+  configured inactivity bound expires, and no supervisor restarts an
+  instance that exited *intentionally*. "Final" means **terminal to
+  automatic supervisor restart** — the owner may always issue a fresh
+  Start; that is resurrection working as designed, not a violation.
+
+  **Lifetime is owner policy, not law.** The inactivity bound is the
+  harness's opt-in self-stop (§Auto-Stop, default disabled). An owner may
+  always choose **no inactivity bound** — declaring an indefinitely-lived
+  agent. How that choice is expressed is per-binding: the Kubernetes
+  binding opts in with a 2h schema default because a pod is metered
+  compute with nobody watching it, and spells "no bound" as its
+  `inactivity_seconds: 0` field (§Pod shape); a hand launcher simply never
+  sets the reaper env. Either way it is
+  a legitimate, explicit choice, not a conformance failure: the invariant
+  was never "every instance terminates" (a continuously active agent is
+  intentionally unbounded — that is the product); it is "termination, once
+  intended, sticks".
+
+  **Restart policy follows lifetime policy.** The distinction that makes
+  indefinite agents safe is *intent vs accident*: dying on purpose
+  (`!shutdown`, inactivity reap) is final; dying by accident (node
+  eviction, OOM) may restart the body — same key, same agent, the
+  resurrection story working *for* the owner. Stated launcher-neutrally:
+  **if a supervisor exists, its restart policy MAY revive an abnormal
+  death and MUST NOT revive an intentional clean exit.** A launcher with
+  no supervisor at all — a hand-launched process on a VPS — satisfies
+  this vacuously: nothing restarts anything. How bounded vs indefinite
+  lifetime maps onto a concrete supervisor policy is binding policy
+  ([L3]), realized and documented by each binding — this binding's
+  mapping lives in §Pod shape; a systemd binding's in its unit
+  directives. Any revive-on-abnormal-death policy carries a universal
+  precondition: the supervisor can distinguish intent from accident only
+  if the harness formally promises *clean exit = exit code 0* on every
+  intentional path and nonzero otherwise, pinned by test. At `28ae6cd21`
+  that property is emergent, not defended (Known Defect 6);
+  restart-on-failure before the pinned contract is how a refactor
+  silently converts every clean stop into a restart loop with no failing
+  test. Ordering is normative: exit-code contract first,
+  restart-on-failure second — the identical seam in every supervisor that
+  offers the distinction. An always-restart policy remains non-conforming
+  at any layer: it resurrects after a *clean* exit, defeating
+  `!shutdown`.
+
+  Enforcement: the self-stop lives *inside the harness* (the only place
+  that can see activity, per M1) (§Auto-Stop), and each binding makes it
+  effective on its substrate by requiring that harness exit terminates
+  the substrate's unit of execution (this binding's realization — the
+  harness as the container's signal-receiving process — is §Pod shape,
+  [L3]) and that any supervisor's restart policy respects intent as
+  above.
+  Boundaries: (a) the guarantee is conditional on a live harness event
+  loop — a wedged process that cannot run its reaper timer cannot reap
+  itself, and M1 means nothing else will (the mitigation is the substrate
+  operator's, e.g. a namespace-level TTL policy, out of scope per
+  §Non-Goals); (b) restart policy prevents resurrection, it does not prove
+  process exit; (c) I5 bounds *agent* lifetime, not substrate residue —
+  residue (in this binding, a Completed pod object) persists for
+  forensics until the next deploy's GC (§K8s GC).
+
+## Provider Protocol
+
+### Discovery
+
+`D` scans, in order: the directory containing the desktop executable, every
+entry of `PATH`, and `~/.local/bin`, for executables named
+`buzz-backend-<id>`. The suffix after the prefix is the provider id and MUST
+match `[a-z0-9][a-z0-9_-]*`. On Windows, an `.exe`/`.bat`/`.cmd` extension
+MUST be stripped before the id is derived (see §Known Defects — as of
+`28ae6cd21` it is not, so Windows providers probe but cannot deploy). First
+hit per filename wins. Discovery executes nothing.
+
+**Shadowing and invalid candidates are diagnosable, not silent.** First-hit
+wins is the right selection rule (it is kubectl's), but kubectl also warns
+when a later-PATH plugin is shadowed, and Docker's CLI reports invalid
+plugin candidates with reasons. Discovery MUST retain, and the UI and
+deploy-time errors MUST be able to surface: the selected binary's full
+path, any shadowed candidates for the same id (later-PATH duplicates), and
+candidates rejected for malformed names. A deploy error that names which
+binary ran answers the first question a user with two copies of
+`buzz-backend-kubernetes` will ask. (At `28ae6cd21` discovery records only
+the winning path — a desktop change alongside Known Defect 3's.)
+
+**Resolution rule.** Every subsequent operation resolves the provider id
+against the *current* discovery set. A stored binary path on an agent record
+is a cache, revalidated against both the current candidates and the recorded
+id before every use. A record edit can therefore never redirect an operation
+to a binary discovery would not have found.
+
+**Pre-secret negotiation gate (normative).** Declaring `protocol_version`
+is worthless if nothing checks it before the nsec crosses the trust
+boundary — and at `28ae6cd21` nothing does: `provider_deploy` invokes
+`deploy` directly, so a stale UI-time probe (or a binary replaced on PATH
+since that probe) can receive `private_key_nsec` unchecked (Known Defect
+5). The deploy path MUST: resolve the provider id **once**; copy the
+resolved candidate into a desktop-owned, private, non-writable **staging
+file**, computing its digest during the copy; invoke `info` **on the
+staged artifact**; validate an explicit, supported `protocol_version`
+(§Info — absence is an error); invoke `deploy` on the **same staged
+artifact**; delete it afterward. Staged bytes are what "same executable
+identity" means here: the nsec goes to the exact bytes that answered
+`info`. Path-plus-metadata comparison (dev/inode, size, mtime) is NOT an
+acceptable substitute for this guarantee — unchanged metadata can miss an
+in-place content rewrite, and a pathname can be swapped between the check
+and the moment `Command` opens it, which is precisely the
+check-then-exec race the gate exists to close. A UI-time probe result
+MUST NOT satisfy this gate. If a platform makes staged execution
+impossible for some provider (e.g. an executable that only runs from its
+install location due to relative dependencies or signing constraints),
+the implementation MUST NOT silently fall back to metadata and still
+claim this gate: it degrades explicitly to *accidental-replacement
+detection* (path + file-identity compare), surfaces that weaker level in
+the deploy diagnostics, and the spec text for that platform carries the
+narrower claim. Remembered digest-based approval (Terraform-lock style)
+is a stronger follow-up, not a v1 requirement.
+
+### Invocation
+
+One process per operation. `D` spawns `P` with cwd = the agent workdir,
+writes exactly one JSON object to stdin, closes stdin. `P` writes exactly one
+JSON object to stdout and exits. Requirements on `D` (all implemented):
+
+- Bounded reads: stdout capped (1MB), stderr capped (64KB), no `read_to_end`
+  on pipes a daemonizing child could hold open; deadline polling with
+  `try_wait`.
+- **Non-zero exit is failure even if stdout parsed.** Partial output from a
+  crashed operation is never trusted.
+- `{"ok": false, "error": …}` is the in-band failure form.
+- **Environment**: `P` inherits `D`'s environment. On macOS a GUI launch
+  means launchd's minimal PATH; providers whose substrate credentials invoke
+  helper binaries (kubeconfig `exec` plugins) MUST self-augment their PATH
+  (§K8s Auth) rather than assume a login shell.
+
+### Provider Output Is Untrusted
+
+Everything `P` emits — stderr, error strings, the response object — is
+scrubbed before storage or display: every value from the request's
+`env_vars` (longest-first, length ≥4) and every `nsec1…`/`sprt_tok_…` token
+is redacted. Rationale: `P` legitimately holds secrets during deploy; `P`
+echoing them (in a stack trace, a kubectl error, a debug line) must not
+propagate them into `D`'s persisted `last_error` or logs.
+
+### `info`
+
+```
+request:  {"op": "info", "request_id": "<uuid>"}
+response: {"ok": true, "name": str, "version": str,
+           "protocol_version": int, "description": str,
+           "config_schema": <JSON Schema>}
+timeout:  10s
+```
+
+`version` is the provider's *software* version — useful in error reports,
+useless for compatibility. `protocol_version` (this document: `1`) is the
+wire-contract version, following the pattern Docker's CLI plugins
+(`SchemaVersion`) and HashiCorp go-plugin (negotiated protocol version) both
+converged on: the desktop rejects a provider whose `protocol_version` it
+does not speak, with an error naming both versions and the binary path,
+instead of failing later inside a half-understood `deploy`. A missing
+`protocol_version` is an **error, not a presumed `1`**: there is no
+deployed provider population to grandfather, and a gate that infers
+compatibility for exactly the class of binary that never declared any
+defeats its own pre-secret guarantee (§Discovery). Fail closed — it is
+also simpler: no migration clock, no "major cycle" to define.
+
+`config_schema` drives the UI form: `properties[*].default` prefill,
+string/number/boolean coercion, `required` gating. A provider MAY compute
+defaults freshly per call (the Kubernetes binding generates a random
+namespace default this way — §K8s Namespace). The schema's fields are
+subject to I2 validation when the user's values come back in `deploy`.
+
+### `deploy`
+
+```
+request:  {"op": "deploy", "request_id": "<uuid>",
+           "agent": <payload>, "provider_config": {…}}
+response: {"ok": true, "agent_id": str}
+timeout:  600s
+```
+
+The agent payload (field list per
+`commands/agents_deploy.rs: deploy_payload_json` at `28ae6cd21`; the
+`launch` block is a normative addition not yet emitted — Known Defect 3):
+
+| field | meaning |
+|---|---|
+| `name` | display name |
+| `relay_url` | concrete WS URL (workspace fallback materialized — the remote side has no workspace notion) |
+| `private_key_nsec` | **the identity** (I1: never empty) |
+| `auth_tag` | NIP-OA owner attestation |
+| `agent_command`, `agent_args` | the ACP agent under the harness (configurable-harness support). At `28ae6cd21` these are raw record bytes — see Known Defect 3: the normative source is the resolved descriptor in `launch` |
+| `system_prompt`, `model`, `provider` | effective values, live-persona-first resolution |
+| `turn_timeout_seconds`, `idle_timeout_seconds`, `max_turn_duration_seconds` | harness timeout knobs |
+| `parallelism` | concurrent-turn bound |
+| `respond_to`, `respond_to_allowlist` | inbound author gate |
+| `env_vars` | merged user env: global < persona < agent |
+| `launch` | **normative addition** (§Launch data): the desktop-resolved launch contract — `command` (name, not path), normalized `args`, layered `env`, overridable `policy_env`, and `owner_pubkey` |
+
+**Reserved-key rule (normative for providers).** `D` strips
+`BUZZ_PRIVATE_KEY`, `NOSTR_PRIVATE_KEY`, `BUZZ_AUTH_TAG`, `BUZZ_RELAY_URL`,
+and the other reserved keys from `env_vars` before merge. A provider MUST
+construct the agent environment's identity variables from the **top-level**
+payload fields (`private_key_nsec` → `BUZZ_PRIVATE_KEY`/`NOSTR_PRIVATE_KEY`,
+`auth_tag` → `BUZZ_AUTH_TAG`, `relay_url` → `BUZZ_RELAY_URL`); reading
+`env_vars` for them yields an identityless agent. A related hardening `D`
+performs is part of the contract's rationale: env keys are validated as
+POSIX-shaped names before merge, because a key like `BUZZ_AUTH_TAG=x`
+smuggled through `Command::env` would bypass the reserved-key strip
+entirely. A provider materializing `env_vars` into a substrate object
+(e.g. a Kubernetes Secret) MUST likewise never let a user-supplied key
+collide with or reconstruct a reserved key.
+
+`agent_id` is `P`'s stable handle for the deployment (the Kubernetes binding
+returns the pod name). `D` stores it as `backend_agent_id`; its presence is
+the `deployed` axis of I3.
+
+**There is no `undeploy` op in v1.** Deletion of a remote agent from `D`
+orphans the substrate objects; the UI therefore requires an explicit
+`force_remote_delete` confirmation, and the binding's GC + I5 bound the
+orphan's cost (the agent self-stops; the pod residue is reaped on the next
+deploy of the same key, or manually).
+
+### Launch data (`launch`) {#launch-data}
+
+Reproducing the local spawn's launch semantics requires state only the
+desktop can resolve: the runtime-metadata table (`model_env_var`,
+`provider_env_var`, `provider_locked`, `default_env` —
+`discovery.rs:75-207`), the six-layer env resolution, harness-definition
+command/args fallback, team instructions, session title, the respond-to
+gate's legacy owner fallback, and the mesh rewrite. A provider MUST NOT
+reimplement that derivation — it would be a second copy of desktop runtime
+discovery, drifting from the first. Instead the payload carries a typed
+`launch` block that `D` resolves with **the same code paths as local
+spawn**, and the provider applies it mechanically.
+
+```
+"launch": {
+  "command":      str,          // command NAME (e.g. "goose"), never a host path
+  "args":         [str],        // normalized args, definition fallback applied
+  "env":          {str: str},   // layered env: baked → runtime metadata →
+                                // definition → global → persona → agent
+                                // (resolve_effective_harness_descriptor)
+  "policy_env":   {str: str},   // overridable behavior defaults (tier 1, below):
+                                // runtime default_env (e.g. GOOSE_MODE=auto),
+                                // BUZZ_ACP_RELAY_OBSERVER, BUZZ_ACP_LAZY_POOL=true,
+                                // BUZZ_ACP_SESSION_TITLE (resolved),
+                                // BUZZ_ACP_TEAM_INSTRUCTIONS, BUZZ_ACP_MODEL,
+                                // MCP_HOOK_SERVERS=* (mcp_hooks runtimes only)
+  "owner_pubkey": str | null    // resolved workspace owner (hex) — legacy
+                                // BUZZ_ACP_AGENT_OWNER fallback, non-secret
+}
+```
+
+`launch.command`/`launch.args` come from
+`resolve_effective_harness_descriptor` (`readiness.rs:125`) — the same
+resolver local spawn uses — which fixes two silent divergences the raw
+record fields carry: a persona-derived `agent_command` is a blank record
+byte, and definition-provided `agent_args` are lost when the instance's own
+args are empty. `launch.env` is that descriptor's layered env, which is
+where per-runtime model/provider injection lives (`GOOSE_MODEL`/
+`GOOSE_PROVIDER` for goose; nothing for `provider_locked` runtimes like
+Claude; `BUZZ_AGENT_MODEL`/`BUZZ_AGENT_PROVIDER` for buzz-agent). A fixed
+`provider → BUZZ_AGENT_PROVIDER` mapping is wrong for three of the four
+built-in runtimes and is why this block exists.
+
+**What `policy_env` carries — and deliberately does not.** Its irreducible
+wire fields are exactly three scalars plus the metadata-derived defaults —
+plus the four record-derived behavior knobs that would otherwise be
+mis-tiered (below):
+
+- `BUZZ_ACP_TEAM_INSTRUCTIONS` — the only truly non-reconstructible policy
+  value: `effective_team_instructions` (`spawn_hash.rs:41-52`) needs the
+  desktop's `TeamRecord` store, which no pod can reach.
+- `BUZZ_ACP_SESSION_TITLE` — sent **resolved** (`resolve_session_title`,
+  `runtime/metadata.rs:45`), not as its `display_name`/`name` inputs. The
+  resolution strips control characters, and that property transfers: an
+  interior NUL fails a local spawn at the env boundary, and would make the
+  Kubernetes apiserver reject the whole pod spec — a rename must degrade,
+  not turn into a deploy failure.
+- `owner_pubkey` (block-level, not env) — the respond-to gate is otherwise
+  fully reconstructible from payload fields (`build_respond_to_env`,
+  `runtime.rs:380-421`); this is its one irreducible input.
+- Runtime `default_env` (e.g. `GOOSE_MODE=auto`) — computed **from the
+  runtime metadata table only, unconditionally**. The local spawn applies
+  each default only `if std::env::var(key).is_err()` (`runtime.rs:733-737`)
+  — a test of the *desktop's own* ambient environment. That makes "the
+  resolved local env" not a pure function of the record; serializing it
+  verbatim would bake a host accident into the pod. Launch data MUST be
+  computed from record + config alone.
+- `BUZZ_ACP_LAZY_POOL=true` — a **deliberate pick, not a transcription**:
+  the two local paths disagree (manual Start is eager, `runtime.rs:1001`;
+  launch restore is lazy, `restore.rs:333`, precisely to avoid "N idle
+  brains on every launch"). Remote pods take the lazy arm: an idle LLM pool
+  in a cluster is billable waste with no user watching it warm up.
+- `MCP_HOOK_SERVERS=*` when the resolved runtime has `mcp_hooks`
+  (`runtime.rs:594-598`; buzz-agent only at `28ae6cd21`) — gates the
+  `_Stop`/`_PostCompact` hook tools.
+- `BUZZ_ACP_SYSTEM_PROMPT`, `BUZZ_ACP_IDLE_TIMEOUT`,
+  `BUZZ_ACP_MAX_TURN_DURATION`, `BUZZ_ACP_AGENTS` — resolved by the desktop
+  from the record's `system_prompt` / `idle_timeout_seconds` /
+  `max_turn_duration_seconds` / `parallelism` (each omitted when null,
+  matching the local spawn's conditional emission). These are **tier-1 by
+  local fact, not by choice**: the local spawn writes them before the user
+  env layer (`runtime.rs:716-729,763` vs `:860`) and none is in
+  `RESERVED_ENV_KEYS`, so a power user's env override beats them today. A
+  provider that independently mapped the top-level payload copies after
+  `launch.env` would invert that — the structured field silently defeating
+  an override that works locally — which is why the provider MUST NOT remap
+  them (§Entrypoint mapping table).
+
+`BUZZ_ACP_DEDUP` and `BUZZ_ACP_MULTIPLE_EVENT_HANDLING` are **deliberately
+unset**: the local spawn writes `queue`/`steer` (`runtime.rs:730-731`), and
+those are exactly the harness's clap defaults (`config.rs:344,356`) — a pod
+that omits both is behaviorally identical, and adding rows for them would
+imply a divergence that does not exist. `BUZZ_MANAGED_AGENT` is likewise
+deliberately absent remotely: it brands local harness processes so the
+desktop's orphan sweep and instance reaper can prove ownership by scanning
+process env (`orphan_sweep.rs`, `instance_reaper.rs`) — there is no local
+process to sweep.
+
+**Environment precedence (normative) — three tiers, later wins:**
+
+1. **Overridable behavior defaults** — `launch.policy_env`. These keys are
+   deliberately non-reserved (`env_vars.rs:54-57` says so outright: power
+   users may bypass the dedicated UI fields), and locally the user env is
+   written after them (`runtime.rs:860` and its comment). A policy-wins
+   order here would make remote agents ignore overrides local agents honor.
+2. **User/layered env** — `launch.env`. User `env_vars` need no separate
+   slot: the descriptor's layering already merged them (global < persona <
+   agent), so a provider applies `launch.env` and MUST NOT re-merge the
+   legacy `env_vars` field on top.
+3. **Authoritative** — unoverridable at every layer, written last and
+   backed by the reserved-key strip: the identity variables from top-level
+   payload fields (§Reserved-key rule), the respond-to gate values,
+   `BUZZ_ACP_AGENT_OWNER`, the inactivity bound, `BUZZ_ACP_MCP_COMMAND`,
+   and `BUZZ_MANAGED_AGENT_START_NONCE`. For the nonce, the provider MUST
+   set it to the attempt's **generation token** (§K8s Secrets): the harness
+   stamps it into every observer lifecycle frame (`buzz-acp/lib.rs:1501`),
+   so the Secret generation and the lifecycle correlator become one
+   identity instead of an empty string.
+
+**Host-resolved values MUST NOT be forwarded and MUST be re-derived
+in-image.** The local spawn sets several variables to absolute paths on the
+desktop's filesystem; forwarding them into a container is a guaranteed
+failure. The provider/image re-derives:
+
+- the harness and agent binaries: `launch.command` is a *name*, resolved
+  against the image's own `PATH` (`BUZZ_ACP_AGENT_COMMAND`), and
+  `BUZZ_ACP_MCP_COMMAND=buzz-dev-mcp` likewise;
+- `CLAUDE_CODE_EXECUTABLE` — a `resolve_command()` host path
+  (`configure_runtime_cli`, `runtime.rs:424-446`), same class as the
+  command paths: image-local resolution or unset;
+- `PATH` itself (the desktop's augmented PATH is meaningless in the image);
+- git credential/signing helper locations — the relay-URL *scoping* of the
+  credential config is normative (never a global helper), the helper *path*
+  is image-local (§Image);
+- `BUZZ_ACP_SETUP_PAYLOAD` is desktop-computed readiness state and MUST NOT
+  appear in a remote pod.
+
+**Owner resolution (normative):** the provider MUST have either a non-null
+`auth_tag` (→ `BUZZ_AUTH_TAG`) or a non-null `launch.owner_pubkey`
+(→ `BUZZ_ACP_AGENT_OWNER`) before any mutation; if both are null it MUST
+refuse the deploy. Without an owner the harness cannot match `!shutdown`
+(`buzz-acp/src/lib.rs: resolve_agent_owner`, main-loop owner check) and the
+agent answers its own stop command conversationally — §Stop would be
+describing a mechanism that does not work. `BUZZ_ACP_AGENT_OWNER` is a
+reserved key, so this value can only arrive as authoritative launch data,
+never through user env.
+
+**Buzz shared compute (relay-mesh) is non-deployable, and this is forced,
+not chosen.** The mesh rewrite resolves to an OpenAI-compatible transport at
+`http://127.0.0.1:9337/v1` (`relay_mesh.rs: RELAY_MESH_API_BASE_URL`) — a
+loopback proxy on the desktop. Serializing that policy into a pod points the
+agent at its own localhost, where nothing listens. `D` already rejects
+mesh-configured creates on non-local backends
+(`agents.rs: normalize_relay_mesh`); the deploy path MUST equally fail
+closed — before any mutation — when the effective provider resolves to
+`relay-mesh`, rather than passing `relay-mesh` through as if it were a
+runtime provider. Remote mesh transport is a possible v2 (an in-image mesh
+client), not a v1 silent breakage.
+
+**The governing invariant:** a remote agent's environment differs from the
+same record's local spawn **only where the substrate forces it** (paths,
+PATH, readiness). Anyone adding a local behavior knob adds it to the shared
+resolver, and both spawn paths inherit it; there are not two derivations to
+keep in sync.
+
+### Deploy State Machine
+
+`start` on any non-Local agent unconditionally issues `deploy` — the desktop
+does not track substrate state (M1). Deploy is therefore **not** "create": it
+is *converge to at-most-one-live-instance* (I4), implemented as a
+**reconciliation loop** keyed on the agent's identity within the provider's
+scope.
+
+**Step 0 — derive and verify identity.** The payload carries the nsec, not
+the pubkey. Before any substrate read or mutation, the provider MUST parse
+`private_key_nsec` and derive the public key from it; a malformed or
+undecodable key is an immediate in-band error. Every selector, name, and
+comparison below uses the *derived* pubkey — never a caller-supplied one.
+
+**Step 1 — select and authenticate candidates.** Candidate objects are
+selected by the (truncated) identity label, then each candidate's
+**full-pubkey annotation MUST be compared against the derived pubkey**
+before it is treated as belonging to this agent. Truncated selectors are
+collision-*resistant*, not collision-*free*: the annotation check is what
+makes them safe. An object whose annotation does not match MUST NOT be
+no-op'd against, deleted, GC'd, or have its Secret touched; the provider
+MUST either ignore it or fail with an explicit collision error. Only
+annotation-verified objects proceed.
+
+**Auto-repair is fenced to Buzz-authored, positively identified residue
+(normative).** The destructive rows below (delete residue, replace a
+never-started body, GC a Secret) are legitimate *only because* every object
+they touch carries positive **protocol ownership evidence** — and identity
+evidence alone is not ownership evidence. The identity label, the
+full-pubkey annotation, and the create-intent fingerprint prove "matches
+our schema for this public identity"; all three are public, so any cluster
+writer can reproduce them on an object this provider never created. Every
+object this provider creates therefore also carries an explicit
+management marker — `app.kubernetes.io/managed-by: buzz-backend-kubernetes`
+plus a binding schema-version label (§Pod shape) — and **no destructive
+repair or GC action fires unless the marker is present**, on top of the
+annotation check and the UID+`resourceVersion` fence every delete already
+requires. This is protocol evidence, not cryptographic proof: a cluster
+writer can forge metadata by definition, and an actor with write access to
+the namespace can already delete the pod outright — the marker's job is
+making *accidental* schema collisions and third-party objects fail closed,
+not defeating a hostile admin. The vision's rule that a never-started body
+is substrate-operator residue survives with one qualifier: *Buzz-authored*
+create-state (a Secret our provider wrote, a pod carrying our verified
+annotations and marker) is the reconciler's to clear, because it is state
+the user cannot reasonably clear themselves; *substrate* wreckage —
+anything unowned, unmarked, unannotated, or ambiguously identified — still
+fails closed to the operator. A provider that cannot positively identify an
+object as its own output does not repair around it; it reports it.
+
+**Step 2 — reconcile.** Ordered rules, evaluated against the verified
+observation; on any conflict, *re-enter from step 1* rather than fail:
+
+| observed | action | rationale |
+|---|---|---|
+| instance marked for deletion (`deletionTimestamp` set, any phase) | wait for actual disappearance, then re-enter | the user pressed Start and the old instance is unrecoverable; returning the dying instance's id records a success that evaporates. **Note: in Kubernetes there is no `Terminating` phase — a pod being gracefully deleted stays in phase `Running` for its whole grace period.** The deletion mark MUST be checked *before* phase, or this row is mistaken for the no-op row |
+| no instance | create, then verify startup (below) | first deploy / after GC |
+| terminated (Succeeded/Failed) | delete residue, wait for disappearance, re-enter (→ create) | the **normal restart path**: how a user revives a reaped or shut-down agent |
+| live and **started** (harness container running) | **strict no-op; return existing `agent_id`** | Start must never silently kill a live agent mid-turn; "already running" is the honest answer, consistent with I3 |
+| exists but **never started**, provably non-recoverable — referenced Secret confirmed absent (by a consistent read, below), or invalid image reference | delete (preconditioned, below), wait for disappearance, re-enter (→ create) | a pod whose harness never ran is not a live agent: nothing can be killed mid-turn (I3), it never held the identity (I4), auto-stop cannot bound it (I5's reaper lives in the harness), and no-op'ing it would return a permanently inert instance as success on every future Start. "Provably" means the provider verified the referenced object's absence or the spec-level defect itself — never a reason string alone |
+| exists, **never started**, recoverable, **fingerprint matches** current desired create intent (below) — self-healable startup states: `Unschedulable` (scale-from-zero autoscaling), image pull / `ImagePullBackOff`, transient `CreateContainerConfigError` | observe until started or the operation deadline expires, then return the latest redacted condition — **never delete, on this call or any later one** | these states routinely self-heal — an autoscaler provisions the node, the pull retries, the kubelet re-resolves the Secret (it retries a never-created container regardless of `restartPolicy`). And recoverable-timeout MUST stay observational *across calls*: any finite pod-age threshold can collide with the cluster's own pod-age thresholds (Cluster Autoscaler's `--new-pod-scale-up-delay` / per-pod `pod-scale-up-delay` annotation — the FAQ's example is `"600s"`), and delete-recreate resets exactly the age the autoscaler keys on, converting a slow cold start into a livelock in which every individual decision is correct. A later deploy re-reads: started → strict no-op; still recoverable and same intent → observe under the new call's deadline without resetting pod age; provably non-recoverable → the non-recoverable row. Repeated **identical** Starts can therefore never delete anything, whatever the pod's age — a genuinely slow cluster persists until it heals or an operator acts, and M1 already makes substrate residue the operator's boundary |
+| exists, **never started**, recoverable, **fingerprint differs or absent** — the recorded create-intent fingerprint does not match what *this* deploy would create | delete (preconditioned, below), wait for disappearance, re-enter (→ create) | this is not the same generation the user is waiting on — it is a pod built from configuration the user has since *changed*, and without this row the change can never materialize: the pod name is deterministic, GC only reaps terminated pods, Stop needs a live harness, I5's reaper lives in the harness, and there is no `undeploy` — so a never-started pod wedged by its own config (a `memory_request` no node satisfies, a quota-blocked namespace) would swallow every future edit while reporting only "startup not confirmed", indistinguishable from a slow cluster. Divergence is evidence, not a clock — but it has **two** sources, not one: a user config change, and a provider upgrade that moves the baked default image digest (§K8s image; the default is compile-time provider state, so upgrading the provider changes the computed intent with no user action). Both are deliberate: the second is the *only* escape from a wedge caused by a bad baked default (unpullable digest, wrong arch) — a fingerprint blind to the default resolution would hand that wedge back to exactly the population that cannot override `image`. The accepted cost is that a provider upgrade mid-cold-pull discards in-flight startup progress; neither source is clocked to anything the cluster keys on, so no threshold exists to collide with the autoscaler. A **started** pod is never touched by this row: live → strict no-op regardless of divergence (edits reach it via the documented next-generation consequence) |
+
+**Startup is part of create — phase is not readiness.** `Pending` (and even
+`Running` at the pod level) does not mean the harness started: a pod can sit
+in `ImagePullBackOff`, `CreateContainerConfigError` (e.g. a missing
+`envFrom` Secret), or unschedulable `Pending` forever, and I5's inactivity
+reaper cannot bound a harness that never began. Therefore `deploy` MUST NOT
+report success at pod acceptance: it succeeds only when the harness
+container has actually started (container `state.running`), bounded by the
+operation deadline. On failure or deadline expiry it MUST return an in-band
+error carrying the actionable condition (the container waiting `reason` /
+pod condition), not a generic timeout. "Live" in the no-op row above means
+**started**, for the same reason — this is the lesson ephemeral-runner
+controllers learned upstream (inspect container state, not pod phase).
+Classification MUST combine container state, pod conditions,
+referenced-object existence, and the recorded create-intent fingerprint —
+**reason strings alone are not a
+stable fatality taxonomy**, and pod age is never one (age triggers nothing
+destructive; see the recoverable rows and the controlled-view rule below).
+In particular, `Unschedulable` is not fatal: a
+scale-from-zero pod reports it while the autoscaler provisions capacity,
+and the kubelet retries a container that never got a container status
+regardless of `restartPolicy: Never` (`ShouldContainerBeRestarted` returns
+true for a nil status *before* the restart-policy check —
+`kubelet/container/helpers.go`), which is exactly why a briefly-missing
+Secret self-heals. `restartPolicy: Never` suppresses restarting a container
+that ran and died; it says nothing about one that never started.
+A consequence to state plainly: once success includes container start, the
+600s operation deadline **is** the cold-start budget — image pull on a
+fresh node, scale-from-zero scheduling, all of it. But the deadline bounds
+**how long one Start waits synchronously**, nothing more. Deadline expiry
+on a still-progressing startup is reported as "startup not confirmed within
+the deadline", and MUST NOT trigger cleanup or forced recycle — on this
+call *or any later one* (the recoverable rows above — what replaces a
+never-started pod is a *config change*, never a deadline): the next deploy's
+reconciler observes whatever the startup became and takes the matching row,
+preserving the pod's `creationTimestamp` for whatever cluster machinery
+keys on it. Whether ten minutes fits the intended cluster class is a
+product ruling,
+not a correctness one.
+
+**One create attempt per call (normative).** The replacement rows above —
+terminated, never-started provably broken, never-started divergent — exist
+to clear residue from a *previous* life. Once a deploy call has created its
+own pod, a classification that would replace that pod means the attempt this
+call just made has already failed: the harness started, rejected its
+configuration, and exited (the deterministic startup failure), or the pod
+was proven broken. Re-running the identical create against the same cluster
+inside the same call cannot produce a different outcome; what it produces is
+a hot delete/mint/create cycle every poll interval for the whole operation
+deadline, one immutable Secret per cycle (measured live: 107 Secrets in a
+single 600s call), every one younger than §K8s GC's orphan age gate — a
+bounded-call resource DoS and nsec-bearing-Secret amplifier. A binding MUST
+NOT delete-recreate a pod created by the same deploy call: it MUST return
+the in-band error carrying the latest condition (for a terminated container,
+the exit code and reason — never the terminated `message`, which is
+process-composed output under the same redaction rule as pull messages).
+The failed attempt's pod and Secret are deliberately left in place: the pod
+is terminated, so the *next* Start's preflight GC collects the pod and its
+referenced Secret together before that call's own single attempt — retry is
+thereby gated on fresh owner intent, and litter is bounded at one pod plus
+one Secret per press, not per poll. This bounds attempts, not observation:
+the recoverable rows still observe a slow startup for the full deadline, and
+residue from previous lives is still replaced exactly once on the way to
+this call's attempt.
+
+**Destructive decisions come from views you control — reads and writes
+both (normative).** This is one rule with three instances, stated once so
+nobody optimizes an instance away. §K8s GC's same-clock rule is the time
+instance. The other two live here:
+
+- *Reads*: every read whose result can authorize a deletion — the
+  Secret-absence confirmation above, and the candidate list the GC pass
+  filters — MUST use most-recent semantics (`resourceVersion` **unset**,
+  a quorum read). `resourceVersion: "0"` is served from the watch cache,
+  which the Kubernetes API contract explicitly allows to be much older
+  than anything the client has already observed; a stale
+  Secret-absence read would delete a pod whose Secret exists and whose
+  container was about to start — the GC race again, arriving through read
+  consistency instead of a clock.
+- *Writes*: a fresh read is necessary but not sufficient — the kubelet can
+  start the container between observation and delete. Every DELETE
+  authorized by a classification MUST carry `preconditions.uid` **and**
+  `preconditions.resourceVersion` from that exact observation
+  (`metav1.Preconditions` supports both), making the edge a
+  compare-and-delete. A failed precondition is neither an error nor
+  permission to retry the delete: re-enter from step 1 and classify the
+  object that exists now. The full-pubkey annotation check remains — the
+  precondition pins *when*, the annotation pins *whose*.
+
+**The 409 discriminator is `Status.reason`, never the status code
+(normative).** Two rules in this section require *opposite* actions on
+the same HTTP status: a failed delete precondition and a create-conflict
+are **both 409** (`NewConflict` and `NewAlreadyExists` each carry
+`Code: http.StatusConflict` — `apimachinery/pkg/api/errors/errors.go`).
+The discriminator is the Kubernetes API `Status.reason` field:
+`Conflict` → abandon the delete and re-enter from step 1;
+`AlreadyExists` on create → the convergence rule below (clean up only the
+losing attempt's Secret, re-read, adopt the winner). An implementation
+that branches on the code alone will eventually take the adoption path on
+a failed delete or vice versa. This does not contradict the
+reason-strings warning above: API `Status.reason` is a machine-readable
+contract token defined by `metav1.Status`; *container waiting* reasons
+are kubelet-produced strings with no such contract — the spec distrusts
+the latter, not the former.
+
+**Create-intent fingerprint (normative).** The divergence discriminator
+in the never-started rows is a recorded annotation,
+`buzz.block.xyz/create-intent`, written at pod create — the same shape as
+the image-reference and pubkey annotations the pod already carries. Its
+value is an **unkeyed SHA-256** over a canonical serialization of the
+provider's **non-secret create-intent template**, computed *before* the
+create call. The scope rule that makes a plain hash safe: the input
+covers exactly the provider-controlled fields that can affect scheduling
+or container creation — resolved image reference, resource
+requests/limits, service account, PodSpec command/args, volumes/mounts,
+security context, and the provider's other pod-shape knobs — and **never
+Secret data or attempt identity**. Secret *values* cannot cause the
+never-started wedge this discriminator exists to clear (scheduling reads
+pod fields, not Secret values; a bad launch value produces a started
+container that fails at the relay — a different row), so hashing them
+buys nothing and a plain hash over low-entropy secrets published in a
+world-readable annotation would be a dictionary oracle; excluding them
+removes the oracle and with it any need for an HMAC key or nsec-derived
+key material. Two normalization requirements, or every attempt diverges
+by construction: the per-attempt Secret *name* in `envFrom` MUST be
+replaced by a fixed placeholder (or the pre-binding template serialized
+instead of the concrete PodSpec), and API metadata / server- and
+admission-produced output (UID, `resourceVersion`, timestamps, defaulted
+fields, the fingerprint annotation itself) is excluded structurally —
+the serializer never sees it, an invariant checkable by inspection.
+Comparison is always recorded-annotation vs freshly-computed intent,
+**never** a diff against the live pod spec: admission defaulting and
+mutation would make every pod look divergent, which is why the
+fingerprint is computed pre-create. A missing referenced Secret stays
+handled by the most-recent absence check (the non-recoverable row), not
+by fingerprint divergence; and divergence authorizes deletion only
+through the never-started recoverable row — a started pod is strict
+no-op whatever its fingerprint says.
+
+**No-op means zero mutation.** The live-instance row MUST NOT replace or
+patch the Secret, patch metadata, or delete anything belonging to the
+observed live generation. Configuration and environment edits apply only to
+the *next* fresh generation (see the documented consequence below).
+
+**Conflicts converge, never fail.** Two provider processes can concurrently
+observe "no instance" or "terminated" — the deterministic instance name
+prevents two live instances, but one caller loses the race. The provider
+MUST treat create-conflict (already exists) by re-reading and, if the winner
+is an annotation-verified live instance, returning it as the no-op row
+would — cleaning up only its own losing attempt's residue, never the
+winner's (the Kubernetes binding makes this concrete via per-attempt Secret
+names, §K8s Secrets); it MUST treat delete-not-found as success; and it
+MUST loop until a
+stable outcome or the operation deadline (600s) expires. One deliberate
+asymmetry: the **create loser does not apply the fingerprint-divergence
+row to the pod that just beat it**, even when the winner's fingerprint
+differs from its own intent — it adopts or reconciles the elected winner.
+Two contenders with different payloads would otherwise ping-pong deletes
+through the conflict path. A *subsequent* deploy that walks in and
+observes that never-started divergent winner replaces it normally.
+Without this rule,
+"two deploys return an `agent_id`" (the idempotency claim below) is false
+under concurrency.
+
+**Documented consequence.** Because live → no-op, configuration edits to a
+running remote agent do not take effect until it next exits (unlike local
+agents, which re-resolve on every spawn). This is an accepted v1 tradeoff;
+a deliberate "recycle" affordance (stop-then-start) is the v2 path to
+immediate application. [DECISION E, ruled: per-binding policy — this
+binding keeps no-op; the universal property is that no sequence of Starts
+yields two live instances in one scope.] Note the asymmetry is deliberate and points the
+right way: an edit *cannot* reach a started pod until it exits, but it
+*can* reach a never-started one immediately (fingerprint divergence) —
+the never-started pod is the one the user is editing *because* it did not
+start.
+
+Idempotency in the protocol sense: any number of concurrent or sequential
+`deploy`s with the same payload converge to one live instance, and every
+non-erroring call returns an `agent_id` naming it; no sequence of `deploy`s
+can yield two live instances in one scope.
+
+### Stop and Delete
+
+- **Stop** is not a provider operation. `D` publishes `!shutdown` mentioning
+  the agent on `R`; the harness verifies the sender is the owner and exits
+  through its graceful path: agent-pool shutdown, drain of in-flight turns,
+  publish presence `offline`, close relay connection. **The spec does not
+  derive an upper bound for this path from its segment timeouts, because
+  review proved that arithmetic wrong twice**: the visible constants (30s
+  drain, 2s presence, 5s relay close) omit terms that are *variable*, not
+  constant — at `28ae6cd21` the post-drain reap segment
+  (late-arriving reap `lib.rs:2664`, idle-slot reap loop `:2670`, respawn
+  drain `:2684-2688`) runs *outside* the 30s drain timeout (opened at
+  `:2636`, closed at `:2657`) and serially awaits a 5s post-SIGKILL wait
+  per occupied pool slot (`acp.rs:436`). **That segment alone can reach
+  `30 + 5×parallelism + 7` — ~87s at the desktop's default parallelism
+  of 10** (`DEFAULT_AGENT_PARALLELISM`, `types.rs:814`; lowered from 24 by
+  #3038), ~197s at the harness cap of 32 (`config.rs:293`) — already
+  exceeding a 60s grace. And it is a *lower* bound on the tail, not the
+  worst case: the same path runs earlier segments before the prompt drain
+  even opens — a separate 30s wake-task drain (`:2612`) followed by
+  serial shutdown of any awakened pools (`:2620-2624`), whose per-slot
+  `acp.shutdown()` loop (`:3747-3751`) has no timeout of its own. The
+  total tail is not bounded by today's segment timeouts at all.
+  The requirement is therefore stated as a budget, not a sum (Known
+  Defect 7): **the harness MUST bound its total shutdown tail — every
+  post-signal segment, including per-slot reaping — under one shared
+  deadline no greater than the declared grace budget**, and the budget
+  MUST include a **reserved finalization slice** held back for presence
+  `offline` publish and relay close, **no smaller than those finalizers'
+  declared bounds — currently 2s + 5s = 7s** — which child cleanup may
+  never consume: child reaping degrades first (skip remaining per-slot
+  waits, force-kill), because a shared deadline without the reservation
+  can legally spend all 60s reaping children and hit SIGKILL before the
+  one action the grace period exists to protect. The binding declares the
+  budget (§K8s Grace: 60s); anyone re-deriving "~37s" from the segment
+  constants is reading numbers without their variables. The desktop's
+  local stop command rejects remote agents.
+- **Delete** with a live `backend_agent_id` requires `force_remote_delete:
+  true` from the UI's orphan-warning confirmation — a buggy IPC caller
+  cannot silently orphan substrate objects.
+
+### Auto-Stop (Inactivity Self-Termination)
+
+I5's enforcement point. A new harness knob:
+
+```
+--exit-after-inactivity <secs>   /   BUZZ_ACP_EXIT_AFTER_INACTIVITY
+```
+
+- **Default 0 = disabled.** The flag ships in the harness every *local*
+  agent also runs; a reaper bug must not be able to kill a laptop agent.
+  Remote providers opt in (the Kubernetes binding's `inactivity_seconds`
+  config field, schema default 7200 = 2h, feeds this env var directly).
+  **`inactivity_seconds: 0` is likewise a legal, blessed value meaning "no
+  inactivity bound"** — the explicit opt-in to an indefinitely-lived agent
+  (I5's lifetime-is-policy rule); it is not a misconfiguration and MUST NOT
+  be rejected by provider-side validation.
+- **"Inactivity" is defined as**: no events dispatched to the agent and no
+  turns in flight. Raw relay traffic does not count — an agent lurking in a
+  busy channel it never answers is exactly the waste this bounds.
+- **Mechanism**: on expiry of the bound, the harness fires the same shutdown
+  channel `!shutdown` uses — so inactivity exit gets in-flight drain,
+  presence→offline, and graceful relay close identically to an owner stop.
+  **The expiry check MUST NOT depend on pool readiness.** This is a design
+  constraint learned by inspection, not a transcription: the harness's
+  existing 30s maintenance tick is gated on `pool_ready` (`lib.rs:1743`),
+  which under `lazy_pool` starts false (`:1320`) and flips true only on a
+  wake (`:2570`) — and wakes require pending work (`pool_lifecycle.rs:42`).
+  A reaper riding that tick composes with the mandated
+  `BUZZ_ACP_LAZY_POOL=true` (§Launch data) into a deadlock in I5's single
+  most important case: a never-mentioned lazy pod never runs the tick, so
+  the idle agent the reaper exists to kill is exactly the one it can never
+  evaluate. The reaper therefore runs on its own timer, independent of pool
+  state (an idle-pool check needs no pool). Check granularity makes the
+  effective bound `t ∈ [T, T+interval)`, immaterial at T=7200.
+- **Reserved keys**: `BUZZ_ACP_EXIT_AFTER_INACTIVITY` MUST join
+  `RESERVED_ENV_KEYS` (`env_vars.rs`) when it lands — it is tier-3
+  authoritative (§Launch data), and without reservation a user env var
+  could disable the reaper and reopen unbounded lifetime through the front
+  door. `BUZZ_ACP_NO_PRESENCE` (`config.rs:378`) MUST join in the same
+  change, for the same shape of reason at I3 instead of I5: unreserved, it
+  lets user env silently defeat the 180s presence bound (I3). One knob
+  guards "knows when to leave", the other "you can see that it left";
+  both are promises users must not be able to un-make by typo.
+- Distinctness note: this is a **fourth** timeout concept, deliberately named
+  away from the existing three (`--idle-timeout` = per-turn ACP wire silence,
+  900s; `turn_timeout`; `max_turn_duration` = 7200s — numerically equal to
+  the default inactivity bound and semantically unrelated). Sharing a flag or
+  env name with any of them is how the bug ships.
+
+The harness exiting MUST terminate the substrate's unit of execution, and —
+equally load-bearing — the substrate's termination signal MUST reach the
+harness process itself; any wrapper MUST forward it. A wrapper that runs
+the harness as a child without forwarding signals silently voids both I5's
+substrate half *and* the graceful-shutdown budget: the termination signal
+lands on the wrapper, the harness never learns to shut down, and the
+force-kill leaves presence stale-online — exactly the staleness window the
+grace period exists to close. This binding's realization — the harness as
+the container's signal-receiving process (PID 1 or the signal target) — is
+§K8s Entrypoint's `exec` rule and §Pod shape ([L3], L1 item 3 for the
+universal form).
+With the supervisor policy that matches the lifetime policy (this
+binding's [L3] mapping — bounded → `Never`, indefinite → `OnFailure`
+after both prerequisites, §Pod shape; the universal rule is I5's),
+harness exit completes the pod on every intentional path — turning
+agent-level I5 into substrate-level I5.
+
+## The Kubernetes Binding (`buzz-backend-kubernetes`)
+
+The first conforming provider: a Rust crate in `block/buzz`, distributed as a
+standalone binary. Everything above is the contract; this section is its
+realization.
+
+### Cluster auth {#k8s-auth}
+
+Standard kubeconfig resolution (`$KUBECONFIG` → `~/.kube/config`) via
+`kube-rs`. `provider_config` carries **`context`** and **`namespace`** only
+(I2: credentials never transit config). Because kubeconfigs at Block
+near-universally use `exec` credential plugins (`aws eks get-token`,
+`gke-gcloud-auth-plugin`) that resolve via PATH, and the provider inherits a
+Finder-launched desktop's minimal PATH, the provider MUST prepend
+`/opt/homebrew/bin`, `/usr/local/bin`, and `~/.local/bin` to its own PATH
+before building the client, and on exec-plugin failure MUST name the missing
+plugin binary in the error rather than surfacing a kube-rs stack.
+
+### Namespace {#k8s-namespace}
+
+One stable namespace per user-visible choice; the provider emits a freshly
+generated `buzz-agents-<rand6>` as the `namespace` field's schema *default*
+on every `info` call, so the UI prefills a visible, editable random name with
+zero UI changes ("random default" satisfied at the schema layer). If the
+namespace does not exist the provider attempts to create it; on RBAC denial
+it MUST fail with the literal `kubectl create namespace <name>` command to
+run — it MUST NOT fall back to `default`.
+
+### Image
+
+`ghcr.io/block/buzz-sprig`: Alpine base + `bash` (required by the dev-MCP
+shell tool) + `git` + CA certificates + the static musl `sprig` multicall
+binary with its personality links (`buzz-acp`, `buzz-agent`, `buzz-dev-mcp`,
+`rg`, `tree`, `buzz`, `git-credential-nostr`, `git-sign-nostr`) + a baked
+system gitconfig wiring the nostr signing and credential helpers. The baked
+credential-helper config MUST be scoped to the relay's git URL — mirroring
+the local spawn's `credential.<relay-url>/git.helper` scoping — never a
+global `credential.helper`: a global nostr helper would answer for every
+remote, including github.com. ~15–25MB;
+not FROM-scratch (bash and git preclude it). Sprig-only: alternate-harness
+dependencies (node for Claude Code / Codex) come via the `image` override
+field, not a fatter default. Tagging follows the relay image's matrix —
+`sha-<short>` on main, semver on `sprig-v*` tags (the sprig tarball's
+`+git.<sha>` version string is not a legal Docker tag). **The default image
+reference MUST be pinned by digest, not tag**: the provider bakes, at
+compile time, the multi-arch manifest digest of the image built from its
+own commit and defaults `image` to
+`ghcr.io/block/buzz-sprig@sha256:<that-digest>` — a `sha-<git-sha>` *tag*
+is traceable but still movable (registry tags are mutable pointers;
+Kubernetes distinguishes movable tags from immutable digests for exactly
+this reason), and the object holding it runs with an nsec. The provider
+records the reference it used in a pod annotation, and rejects `:latest`.
+User `image` overrides accept tag, digest, or full custom registry
+reference — visibly the user's trust decision, with the resolved image ID
+recorded in the same annotation for post-hoc attribution.
+**An image override MUST contain the runtime ABI** — the `buzz-acp`
+entrypoint and everything §Entrypoint and launch ABI requires — not merely
+alternate-harness dependencies. A conforming custom image is "buzz-sprig
+plus your tools", never "your tools instead".
+
+### Entrypoint and launch ABI {#k8s-entrypoint}
+
+Two conforming implementations must produce interchangeable pods, so the
+launch contract is normative.
+
+**Entrypoint.** The container runs the harness as its signal-receiving
+process. Sprig is a multicall binary with no supervisor personality —
+nothing reaps children or forwards signals — so the entrypoint MUST end in
+`exec`:
+
+```bash
+#!/bin/bash
+set -e
+# nest scaffolding, if DECISION A lands, goes here
+exec buzz-acp   # exec, not a call — buzz-acp must be PID 1
+```
+
+`bash -c "setup && buzz-acp"` (no `exec`) is non-conforming: bash becomes
+PID 1, and a PID-1 bash with no trap never delivers SIGTERM to the harness
+(PID 1 receives kernel-level default-handler signal immunity), so the pod
+rides out the entire grace period and is SIGKILLed with presence still
+online — voiding I5's substrate half and the very staleness window
+`terminationGracePeriodSeconds: 60` was sized to close. The entrypoint
+shape and the grace period are one requirement, not two.
+
+**Payload → environment mapping.** The provider builds the pod environment
+(via the per-agent Secret, §K8s Secrets) by applying the §Launch data
+three-tier precedence — `launch.policy_env` (overridable defaults), then
+`launch.env` (user/layered), then the authoritative tier from top-level
+fields per the reserved-key rule. Only the
+non-`launch` scalars and the substrate-forced re-derivations are mapped
+individually:
+
+| source | env var |
+|---|---|
+| `relay_url` | `BUZZ_RELAY_URL` |
+| `private_key_nsec` | `BUZZ_PRIVATE_KEY` and `NOSTR_PRIVATE_KEY` (the git helpers read the latter) |
+| `auth_tag` | `BUZZ_AUTH_TAG` (omitted when null; then `launch.owner_pubkey` → `BUZZ_ACP_AGENT_OWNER` is REQUIRED — §Launch data owner rule) |
+| `launch.command` | `BUZZ_ACP_AGENT_COMMAND` — the *name*, resolved against the image's own PATH; never a forwarded host path |
+| `launch.args` | `BUZZ_ACP_AGENT_ARGS`, comma-joined |
+| `launch.env`, `launch.policy_env` | verbatim, at their precedence tiers |
+| generation token (§K8s Secrets) | `BUZZ_MANAGED_AGENT_START_NONCE` — the lifecycle-frame correlator and the Secret generation are one identity (§Launch data tier 3) |
+| `system_prompt`, `idle_timeout_seconds`, `max_turn_duration_seconds`, `parallelism` | **not mapped by the provider** — the desktop resolves these into `launch.policy_env` (`BUZZ_ACP_SYSTEM_PROMPT`, `BUZZ_ACP_IDLE_TIMEOUT`, `BUZZ_ACP_MAX_TURN_DURATION`, `BUZZ_ACP_AGENTS`), because they are tier-1 behavior knobs: locally they are written *before* the user env layer and none is reserved (`runtime.rs:716-729,763` vs `:860`; `env_vars.rs:54-57`), so user env beats them. A provider that mapped the top-level copies after `launch.env` would silently defeat an override that works locally. The top-level fields remain as display/bookkeeping inputs only |
+| `turn_timeout_seconds` | not mapped — deprecated upstream and ignored; the local spawn also does not emit it |
+| `respond_to` | `BUZZ_ACP_RESPOND_TO` |
+| `respond_to_allowlist` | `BUZZ_ACP_RESPOND_TO_ALLOWLIST`, comma-joined |
+| — | `BUZZ_ACP_MCP_COMMAND=buzz-dev-mcp` (image-local; the dev-MCP requirement) |
+| `provider_config.inactivity_seconds` | `BUZZ_ACP_EXIT_AFTER_INACTIVITY` (schema default 7200; the I5 opt-in, §Auto-Stop — the config field and this env var are one knob, not two) |
+
+The top-level `model`/`provider` payload fields are display/bookkeeping
+inputs; the *environment* consequence of model and provider selection
+(per-runtime vars, `provider_locked` suppression, `BUZZ_ACP_MODEL`) arrives
+resolved inside `launch.env`/`launch.policy_env`. A provider MUST NOT map
+`provider` to any env var itself — that mapping is per-runtime and lives in
+the desktop's resolver (§Launch data).
+
+**Encoding honesty note.** `BUZZ_ACP_AGENT_ARGS` is comma-delimited by the
+harness's CLI parser, and the desktop's *local* spawn performs the same
+comma-join — an argument containing a comma is unrepresentable in both
+paths. This is a harness interface limitation the binding inherits and
+matches, not one it introduces; a provider MUST NOT invent a private
+escaping scheme the harness would not decode.
+
+**Working directory.** `HOME` is set to a writable path backed by the
+workspace `emptyDir` (e.g. `/home/agent`), and the harness runs with cwd =
+`HOME` — mirroring the local spawn's agent-workdir convention. The baked
+system gitconfig references the nostr helpers by absolute path so it works
+regardless of `HOME`.
+
+### Pod shape
+
+- **Bare Pod; `restartPolicy` follows lifetime policy (I5).** No Job, no
+  controller — controller-grade restart machinery (`Restart=always`-shaped)
+  would resurrect what `!shutdown` and auto-stop terminate, violating I5.
+  Within the bare pod, the policy is selected from `inactivity_seconds`:
+  - **Bounded lifetime (`inactivity_seconds > 0`, the default): `Never`.**
+    The reaper's clean exit must complete the pod; any restart would undo
+    the reap. Accidental death is handled by *intent*, not machinery:
+    eviction → presence `offline` (I3) → user hits Start → the
+    reconciler's terminated arm re-creates. That sequence is
+    rescheduling-after-accident gated on a fresh owner intent — apt for an
+    agent whose owner already accepted "not running" as its default state.
+  - **Indefinite lifetime (`inactivity_seconds: 0`): `OnFailure`** — once
+    the harness exit-code contract is pinned (I5 ordering rule; until
+    then the provider MUST refuse the combination rather than ship
+    `OnFailure` against an undefended exit convention). `OnFailure`
+    restarts the *in-place* abnormal deaths — process crash, container
+    OOM-kill — and honors the intentional ones (clean exit completes the
+    pod): I5's intent-vs-accident distinction, realized. **Second
+    prerequisite — reconciler classification:** `OnFailure` introduces a
+    pod state the deploy state machine's rows do not cover — a
+    crash-looping harness sits in phase `Running` with
+    `state.waiting{reason: CrashLoopBackOff}`, `restartCount > 0`: not
+    deletion-marked, not terminated (the kubelet keeps restarting it),
+    not "live and started" (`state.running` is false), and not
+    never-started (it started, repeatedly) — and it fails the startup
+    success criterion while the kubelet is actively reviving it. Before
+    the binding ships `OnFailure`, the state machine MUST gain a
+    crash-loop classification row and the started-criterion's treatment
+    of `restartCount > 0` MUST be specified; the exit-code contract alone
+    is *not* the green light. **Honest
+    limit:** `restartPolicy` is
+    kubelet-level and cannot survive *node-level* loss — a drain or
+    API-initiated eviction deletes a bare pod outright, and no
+    restart policy reschedules a deleted pod. Full "continuous need"
+    across node loss requires controller-grade machinery this binding
+    deliberately does not use in v1 (the same machinery I5 distrusts);
+    the v1 promise for indefinite agents is restart-on-crash, with
+    node loss surfacing as presence `offline` awaiting a fresh Start.
+- **Naming/labeling — the exact contract** (63-char label-value limit; a hex
+  pubkey is 64 chars, one over):
+  - pod name: `buzz-agent-<first-12-hex-of-pubkey>` — also the returned
+    `agent_id`
+  - label `buzz.block.xyz/agent-pubkey: <first-32-hex>` — the selector key
+    for reconciliation and GC. 128 bits is collision-*resistant*, not
+    collision-free, which is why the annotation check below is normative,
+    not decorative
+  - label `app.kubernetes.io/managed-by: buzz-backend-kubernetes` and label
+    `buzz.block.xyz/binding-version: <schema-version>` — the **management
+    marker** (§Deploy State Machine auto-repair fence): present on every
+    pod and Secret this provider creates, and **required before any
+    destructive repair or GC action**. Identity labels/annotations prove
+    identity; the marker asserts protocol ownership — without it, an object
+    that merely matches our schema fails closed to the operator
+  - annotation `buzz.block.xyz/agent-pubkey-full: <full-64-hex>` —
+    **load-bearing**: per §Deploy State Machine step 1, every label-selected
+    object's annotation MUST equal the derived pubkey before the provider
+    no-ops against it, deletes it, mutates its Secret, or returns its name
+  - annotation `buzz.block.xyz/create-intent: <sha256-of-intent-template>` — the
+    recorded create intent (§Deploy State Machine, create-intent
+    fingerprint), written at pod create; the divergence discriminator for
+    never-started pods
+  - Secret name: `buzz-agent-<first-12-hex>-<gen>`, where `<gen>` is a random
+    per-create-attempt **generation token** — unique, never reused, carrying
+    the same labels (identity + management marker) and annotation. The
+    pod's `envFrom` references this exact
+    Secret name. Deterministic pod name + unique Secret name is what makes
+    payload and Secret atomic at the pod-spec boundary (§K8s Secrets)
+- **Deletion semantics the reconciler must respect.** A Kubernetes `DELETE`
+  returns success immediately while the object still exists; the name stays
+  taken until the kubelet finishes the grace period. Two consequences:
+  (a) a pod being gracefully deleted has `deletionTimestamp` set but remains
+  in phase `Running` — the reconciler MUST check the deletion mark before
+  phase (there is no `Terminating` phase to match on); (b) after deleting a
+  live pod, a naive immediate create gets AlreadyExists for up to the full
+  grace period — the reconciler MUST poll for actual disappearance (GET →
+  404) before creating. The delete call MUST use the object's own grace
+  period (kube-rs: `DeleteParams { grace_period_seconds: None, .. }`); the
+  tempting shortcut of passing `0` to skip the poll is a **force-kill** that
+  discards the 60s shutdown grace pinned below — the poll is mandatory
+  precisely because the fast path is wrong. For *terminal*
+  (Succeeded/Failed) pods — and for **unscheduled** pods (no assigned node:
+  unschedulable or quota-blocked `Pending`, a state users hit while setting
+  up a namespace) — the apiserver
+  zeroes the grace period and deletes immediately, so the normal restart
+  path needs no meaningful wait — do not add a fixed sleep, and do not use
+  zero-grace cleanup as a reason to skip the poll in the live-pod arm.
+- **`terminationGracePeriodSeconds: 60` — a declared budget the harness
+  MUST honor, not a sum the spec derived.** Kubernetes' default 30s grace
+  would SIGKILL the harness mid-drain, leaving presence stale-online — the
+  avoidable half of I3's staleness window — so the binding declares 60s.
+  But the shutdown tail is *variable*, not constant (§Stop: the post-drain
+  reap segment alone reaches ~87s at default parallelism at `28ae6cd21`,
+  and earlier untimed segments precede it — the total is not bounded by
+  today's segment timeouts), so no fixed grace can be proven
+  sufficient by adding segment timeouts. The two halves of the requirement:
+  the binding *declares* the budget here, and the harness *enforces* it —
+  one shared deadline across the entire post-signal path, with a reserved
+  finalization slice (≥ the finalizers' declared bounds, currently 7s) for
+  presence `offline` and relay close, child cleanup
+  degrading first (§Stop, Known Defect 7). Until the harness enforcement
+  lands, 60s is an operational margin that the tail can exceed.
+- **Hardening defaults (normative).** The workload is a prompted coding
+  agent running repository and tool code while holding an nsec; the pod MUST
+  NOT hand it ambient cluster credentials or kernel privilege on top:
+  `automountServiceAccountToken: false` (Kubernetes mounts a ServiceAccount
+  token unless told otherwise — an API-stealable credential the agent never
+  needs), `runAsNonRoot: true` with a fixed nonzero UID/GID,
+  `allowPrivilegeEscalation: false`, capabilities drop-all,
+  `seccompProfile.type: RuntimeDefault`; never privileged, `hostPID`,
+  `hostNetwork`, or `hostPath`. `readOnlyRootFilesystem` is *not* required
+  in v1 — the sprig toolchain writes outside the workspace mount — but is a
+  named candidate once the image's write surface is mapped. The
+  `service_account` config field selects an identity for scheduling/RBAC
+  purposes only; it MUST NOT silently re-enable token mounting — API-token
+  access, if ever wanted, is a separate explicit opt-in, not a side effect
+  of naming an SA.
+- **Resources**: requests 1 cpu / 2Gi, limits 2 cpu / 4Gi, all four
+  configurable (`cargo build` in an agent workspace makes 500m/1Gi requests
+  unrealistic).
+- **Workspace**: `emptyDir`. Checkouts and scratch die with the pod; agent
+  memory is relay-persisted (NIP-AE) and unaffected. PVC support is a
+  deferred knob. [DECISION A — how remote pods get the nest workspace
+  (AGENTS.md etc.) that local agents get from the desktop's `ensure_nest`;
+  current recommendation is a desktop-stated protocol field, not
+  image-side scaffolding — §Open Decisions.]
+
+### Secrets {#k8s-secrets}
+
+Per-agent `Secret` containing the identity variables (built from top-level
+payload fields per the reserved-key rule) plus `env_vars`; consumed via
+`envFrom`.
+
+**Secret creation is per-attempt, immutable, and uniquely named**
+(`buzz-agent-<first-12-hex>-<gen>`, §Pod shape). The rationale is a
+concurrency race a deterministic shared Secret name cannot survive: two
+concurrent deploys carrying *different* payloads would both write the shared
+Secret, the loser's write could land last, and the winner's pod —
+deterministic name, winner's spec — would resolve the **loser's**
+identity/config through `envFrom`. The losing caller would have mutated the
+winning generation despite strict no-op. Unique names close this: each
+create attempt writes its own Secret first, then attempts the deterministic
+pod create with a spec referencing exactly that Secret. Pod creation elects
+the winner; payload and Secret are atomic at the pod-spec boundary, with no
+Lease or CAS machinery.
+
+Lifecycle rules that follow:
+
+- **Winner**: pod + its referenced Secret live together; GC deletes them
+  together.
+- **Losing contender** (create-conflict): annotation-verify the winning pod,
+  return its `agent_id` per the convergence rule, and delete **only its own
+  now-unreferenced Secret** — never the winner's, never any Secret
+  referenced by an *existing* pod. "Existing" deliberately includes
+  not-yet-started pods: an `envFrom` reference from a pod still pulling its
+  image is exactly as load-bearing as one from a running pod.
+- **Live no-op arm**: no Secret is written at all (zero mutation).
+- **GC**: also deletes annotation-verified **orphan Secrets** — those whose
+  generation token no existing pod references — covering contenders that
+  crashed between Secret create and their conflict cleanup. But only when
+  **age-eligible**: see the normative age gate in §K8s GC — "unreferenced"
+  is not "orphaned" while a concurrent attempt may still be between its
+  Secret create and its pod create.
+
+Fresh configuration therefore materializes exactly when a fresh generation
+does. Residual exposure, stated: any principal with
+pod-exec or secret-read in the namespace can read the nsec. This is the
+substrate-security boundary from §Non-Goals — the namespace is the isolation
+unit, and users deploying to shared namespaces accept its ambient RBAC. The
+in-pod narrowing that sprig's dev-MCP shim performs (strips the key from its
+own env, re-materializes as a 0600 keyfile for the git helpers) limits
+accidental leakage into subprocess environments, not hostile cluster access.
+
+### Garbage collection {#k8s-gc}
+
+A **generation** is one pod-create attempt and the uniquely-named Secret it
+references; the Secret's generation token is the generation's identity, and
+the *current* generation is the one referenced by the existing pod's
+`envFrom`.
+
+GC is a **preflight reconciliation pass**, not a post-deploy afterthought:
+on every deploy, after identity derivation and before the state transition,
+the provider deletes terminated pods (and their referenced Secrets) that
+match the pubkey label, **pass the full-pubkey annotation check, and carry
+the management marker** (§Pod shape; the auto-repair fence applies to GC
+identically), plus
+annotation-verified, marker-bearing orphan Secrets whose generation token
+no existing pod
+references (§K8s Secrets). It never touches the current generation.
+Mismatched annotations are never GC'd (§Deploy State Machine step 1), and
+an unmarked object is never GC'd regardless of its labels.
+
+**Orphan-Secret age gate (normative).** An unreferenced Secret is
+GC-eligible only when its server-assigned `creationTimestamp` is older than
+**twice the deploy operation deadline** (2 × 600s). Rationale — without the
+gate, GC composes with per-attempt Secrets into a legal interleaving that
+strands a deploy: attempt A creates Secret A; concurrent attempt B runs its
+preflight GC *before A creates its pod*, sees Secret A unreferenced, and
+deletes it as an "orphan"; A's pod is then accepted referencing a missing
+Secret and sits in `CreateContainerConfigError` until a later deploy
+repairs it by delete-recreate (§Deploy State Machine never-started rows) —
+a stranded deploy either way. Unique Secret
+names made payload↔Secret atomic *at the pod-spec boundary*, but
+Secret-create→pod-create is not atomic against an independent GC pass —
+the standard controller lesson that observations may be stale and
+reconciliation must tolerate in-flight peers. The age bound makes
+"unreferenced" mean "provably abandoned": any attempt that could still
+reference the Secret has exceeded its own deadline. A losing contender's
+immediate cleanup of **its own** Secret is exempt — ownership, not age, is
+its safety argument. (A Lease per agent identity would also close this
+race; the age gate achieves the same with no extra machinery.)
+
+**Same-clock rule (normative).** The age comparison has two operands and
+both MUST come from the apiserver's clock. `creationTimestamp` is
+server-assigned; the comparison instant MUST be derived from the HTTP
+`Date` response header on the very list/get call the GC pass performs
+(RFC 9110 §6.6.1 — origin-server message-origination time), never from the
+provider's local `now()`. The provider runs on a user's desktop, and a
+local clock fast by more than the margin doesn't *race* — it
+deterministically computes every in-flight Secret as expired and deletes
+them all, silently, on every pass, reopening exactly the interleaving the
+gate exists to close. With both operands from one clock, skew cancels.
+(`kube`'s `Client::send` returns the raw `http::Response` with headers, so
+this costs one header read, not a departure from the typed API.) If the
+`Date` header is absent or unparseable, the provider MUST **skip
+orphan-Secret GC for that pass** — never fall back to local time. A
+deferred cleanup is free; a wrong deletion is not.
+
+**Alternative considered — `ownerReferences`, omitted in v1.** Kubernetes'
+native GC (a Secret owned by its attempt's Pod is deleted when the owner is
+verified absent) cannot *replace* the age gate: an ownerReference needs the
+owner's UID, which exists only after pod create, so primary reliance on it
+would flip the ordering to Pod-first-then-Secret. The reason that flip
+loses is **diagnostics, not repairability**: a never-started winner is
+recoverable (the kubelet retries a config-failed container indefinitely,
+and the amended no-op rule lets a later deploy delete-and-recreate it with
+its own payload), but Pod-first routes *every healthy deploy* through
+`CreateContainerConfigError` — the exact condition the startup classifier
+treats as an actionable failure signal — so the classifier could no longer
+believe that reason without waiting out the deadline, on every deploy.
+That trades away normative diagnostics for a cleanup the age gate already
+provides. A *supplementary* post-create attachment (patch the Secret with
+the winning pod's UID; Secret metadata stays patchable when `immutable` and
+`data` are untouched) is sound but adds no required property: the pre-pod
+crash window still needs the age-gated sweep as backstop, so v1 omits it
+under the complexity budget. Any future implementation that adds it MUST
+set `blockOwnerDeletion: false` explicitly (true requires `update` on
+`pods/finalizers` — an RBAC verb nothing else here needs — and a Secret
+should never delay its pod's deletion), MUST keep owner and dependent in
+the same namespace (a cross-namespace owner is treated as *absent*, turning
+the safety net into an immediate-delete instruction), and MUST treat
+attachment failure as non-fatal cleanup, never a deploy error.
+
+Running GC first
+gives concurrency and Secret ownership one unambiguous order: reconcile
+always observes a world with at most one candidate generation *older than
+the gate*. Completed
+pods from the *current* generation are left in place — their logs are the
+only forensics M1 permits. That forensic window is deliberately fragile:
+next-deploy GC, node loss, or namespace deletion erases it, and M1 means
+there is no log operation to reach for. **Cluster-native log shipping is
+therefore a production prerequisite, not an optional nicety** — the
+ephemeral-runner lesson: disposable generations still need durable
+diagnostics, forwarded off the pod by the cluster operator's stack. The
+binding's contribution is correlation, not transport: the pod carries the
+full-pubkey annotation, the generation token (doubling as
+`BUZZ_MANAGED_AGENT_START_NONCE`, so lifecycle frames and pod logs share a
+correlator), the provider version, and the resolved image reference
+(§Image) — enough to attribute any shipped log line to an exact identity,
+generation, and binary, with no secret in any of it. GC on next-deploy
+also self-heals the missing
+`undeploy`: delete-then-recreate converges, and a deleted-forever agent's
+residue is one Completed pod that never restarts (I5) plus one Secret,
+removable with `kubectl delete`.
+
+### `provider_config` v1 fields
+
+`context`, `namespace`, `image`, `cpu_request`, `memory_request`,
+`cpu_limit`, `memory_limit`, `inactivity_seconds`, `service_account` —
+9 of the 20-field validation cap. Node selectors, tolerations, and PVCs are
+deliberately baked out of v1 to preserve budget.
+
+### Distribution
+
+Its own release workflow (macOS arm64/x64 + Linux musl; the sprig workflow's
+ubuntu × musl matrix cannot produce the laptop-side binary), artifacts
+attached to releases, installed to `~/.local/bin` (already on the discovery
+path). v1 ships no Windows binary [DECISION B]; desktop bundling into the
+.app (discovery already prepends the bundle dir) is deferred [DECISION D].
+
+## Conformance
+
+Obligations are split by layer per §Launchers: the **[L1] agent/harness
+contract** binds every launcher; the **[L2] provider/deployer contract**
+binds provider-managed launches; the **[L3] binding policy** here is the
+Kubernetes binding's own. A non-provider launcher (bash script, systemd
+unit) owes only the L1 items; a provider on a different substrate owes
+L1 + L2 and writes its own L3 realization of the generic L3 property.
+
+### [L1] Launcher conformance — every launcher
+
+A launcher — desktop, provider-deployed pod, systemd unit, bash script —
+is conforming iff:
+
+1. It launches the harness with a **valid, nonempty identity**: a
+   parseable private key, a relay URL, and an auth tag or resolved owner
+   pubkey — refusing to launch rather than launching identityless (I1's
+   property, enforced wherever the env is assembled).
+2. It does not suppress the harness's promises on a remote agent:
+   presence stays enabled (`BUZZ_ACP_NO_PRESENCE` never set — remotely,
+   presence is the only signal, I3), and the inactivity knob
+   (`BUZZ_ACP_EXIT_AFTER_INACTIVITY`) carries the owner's *deliberate*
+   lifetime policy, never an accidental passthrough of user env (I5; the
+   reserved-key rule is the provider path's realization of this).
+3. The substrate's **termination signal reaches the harness process**,
+   with enough grace for its full graceful shutdown before force-kill (I3
+   staleness minimization). "Allows" is not enough — a wrapper that
+   swallows the signal conforms to nothing.
+4. Intentional termination (owner `!shutdown`, inactivity reap) exits
+   through the harness's graceful path under the **pinned clean-exit
+   contract** (intentional exit ⇒ exit code 0 — Known Defect 6 until the
+   contract lands).
+5. Any supervisor the launcher configures **never restarts an intentional
+   clean exit** (I5). `Restart=always` and equivalents are non-conforming
+   at this layer no matter what the substrate calls them.
+
+### [L2] Provider conformance — provider-managed launches
+
+A provider is conforming iff, in addition to deploying only L1-conforming
+invocations:
+
+1. `info` and `deploy` implement the wire contract (§Provider
+   Protocol), including one-JSON-in/one-JSON-out and in-band
+   `{"ok": false}` errors. **Exit codes carry exactly one bit** — zero =
+   the operation's output is trustworthy, nonzero = failure regardless of
+   stdout (§Invocation's rule restated from the provider's side): a
+   provider MUST exit nonzero on any crash path and MUST NOT encode
+   structured meaning in nonzero values, because `D` discards partial
+   output rather than interpreting codes.
+2. It never requests or accepts credentials through
+   `provider_config` (I2).
+3. It builds agent identity env from top-level payload fields, never
+   from `env_vars` (reserved-key rule), applies §Launch data mechanically —
+   three-tier precedence, host-resolved re-derivation, no re-merge of
+   legacy `env_vars`, no provider-side model/provider mapping — and refuses
+   a deploy that resolves neither `auth_tag` nor `launch.owner_pubkey`, or
+   whose provider is `relay-mesh`.
+4. `deploy` implements the reconciliation loop (I4), stated
+   substrate-neutrally: identity derived from the nsec before any
+   mutation; candidates verified by **full-identity evidence** before any
+   action; live (= **started**: the harness process confirmed running, not
+   merely the body accepted) → strict no-op (zero mutation); never-started
+   states classified by evidence, not by substrate status strings
+   (provably-broken → fenced replace; recoverable + same recorded create
+   intent → observe, never delete, on this call or any later one;
+   recoverable + divergent intent → fenced replace); every read that can
+   authorize a destruction uses most-recent semantics; every destructive
+   write is **fenced to the exact observation that authorized it**
+   (compare-and-delete — the write fails if the object changed since the
+   read) and touches only objects carrying the provider's **management
+   marker** (the auto-repair fence, §Deploy State Machine);
+   same-status-code conflicts discriminated by a **machine-readable
+   conflict discriminator**, never the status code alone; success only on
+   confirmed harness start; conflicts converge by re-entry;
+   delete-of-absent is success.
+5. It emits no secret material in any output (belt to `D`'s
+   redaction suspenders).
+6. **Generic L3 obligation:** its binding *documents* how it realizes each
+   L2 term on its substrate, and how the owner's lifetime policy (bounded
+   vs indefinite) and clean-exit restart behavior are realized there —
+   stating the properties in its own vocabulary, not skipping them.
+
+### [L3] Kubernetes binding conformance — this binding
+
+The realization the two lists above require, in this binding's vocabulary:
+
+1. Each L2 item-4 term maps to the mechanism in §Deploy State Machine:
+   full-pubkey annotation for identity evidence, container `state.running`
+   for "started", `resourceVersion`-unset quorum reads for most-recent
+   semantics, UID+`resourceVersion` delete preconditions for fencing,
+   `Status.reason` as the 409 discriminator, and the
+   `app.kubernetes.io/managed-by` + binding-version labels as the
+   management marker.
+2. The deployed invocation realizes the lifetime policy the owner chose
+   (I5) through this binding's `inactivity_seconds` field: `> 0` →
+   a working inactivity bound and `restartPolicy: Never`; `0` (the
+   blessed indefinite opt-in) → no bound and `restartPolicy: OnFailure`,
+   **only after both prerequisites land** — the pinned exit-code contract
+   (I5 ordering rule) *and* the crash-loop classification row (§Pod
+   shape); until then the provider MUST refuse the combination.
+3. The harness is the deployed container's **signal-receiving process**
+   (PID 1 or the target of the pod's termination signal — §K8s
+   Entrypoint's `exec` rule), and `terminationGracePeriodSeconds` carries
+   the declared grace budget (§Pod shape).
+
+Conformance is testable without mechanization: a fake-provider harness can
+exercise L2 items 1–3 and 5 over the wire contract — including the pre-secret
+negotiation gate (§Discovery): an incompatible **or absent**
+`protocol_version` MUST be rejected before any request carrying
+`private_key_nsec` is sent; a **same-inode content rewrite** of the
+resolved binary after resolution MUST NOT reach the deploy invocation
+(the staged artifact still carries the bytes that answered `info`); and a
+**pathname swap after validation** — the resolved path re-pointed at a
+different file between the gate's checks and process spawn — likewise
+MUST NOT redirect the nsec (both cases are exactly what path+metadata
+comparison misses) — and an envtest/kind suite
+can drive L2 item 4's reconciler against a real apiserver — concurrent
+deploys, a deletion-marked pod, terminal restart, an annotation-mismatch
+collision, and SIGTERM→presence-offline for the L3 items. Three families of
+cases are mandatory because they were the review-found failure modes:
+**startup discrimination** (slow-but-valid scheduling → poll-then-succeed;
+`Unschedulable` during scale-from-zero → observed until the autoscaler
+provisions capacity, then success — never delete, **including when
+provisioning completes only after the 600s deadline**: the original pod
+identity and `creationTimestamp` survive the expired call and become the
+no-op winner on a later deploy, the case that pins the anti-livelock rule;
+a label-and-annotation-matching object **without the management marker** →
+never deleted, never GC'd, reported (the auto-repair fence under test);
+referenced Secret *confirmed absent* → preconditioned delete-recreate or
+actionable error, never silent success or no-op; a **never-started winner
+is repairable** — pod exists, Secret absent, container never started: a
+later deploy MUST delete-and-recreate rather than no-op, the test that pins
+started-not-phase as the no-op criterion; and the **classification→DELETE
+race** — the container transitions to running between the classifying read
+and the delete: the UID+resourceVersion precondition MUST fail and the
+live agent MUST be preserved) and the **GC/attempt interleaving** (attempt B's
+preflight GC running between attempt A's Secret create and pod create MUST
+NOT delete Secret A — the §K8s GC age gate under test; provider death after
+Secret create → the age gate protects, then a later GC reaps; and a
+**provider local clock fast beyond the margin** MUST NOT delete an
+in-flight Secret — cheap with a fake clock, and the same-clock rule's
+skip-on-absent-`Date` arm is exercised by stripping the header). A third
+family pins the **divergence discriminator and the 409 split**: a failed
+delete precondition (code 409, reason `Conflict`) → re-read and
+re-classify, never the create-conflict cleanup/adoption path; a create
+conflict (code 409, reason `AlreadyExists`) → loser-Secret cleanup and
+winner adoption, never treated as a failed delete; identical desired
+intent + permanently-Pending pod → no delete across arbitrarily many
+Starts, regardless of age; a resource/image correction against a
+never-started pod → fingerprint differs, preconditioned
+delete-and-recreate (the wedge-escape case); same user config but the
+provider's **baked default image digest** changed (provider upgrade)
+against a never-started pod → divergence, replace (the second intent
+source — the only escape from a bad-default-image wedge); the same correction against
+a **started** pod → strict zero-mutation no-op; admission
+defaulting/mutating the live pod → no false divergence (the comparison
+uses the recorded annotation); the fingerprint serializer property,
+asserted structurally — changing only Secret *values* or the generated
+Secret *name* leaves the fingerprint unchanged, changing any
+fingerprinted pod-create field changes it (equivalently: the serializer
+has no access to Secret data or attempt identity); and the
+conflict-path asymmetry — two no-instance contenders with different
+payloads: the create loser adopts the elected winner rather than
+deleting it for divergence, while a subsequent deploy observing that
+never-started divergent winner replaces it. A model checker is
+the wrong tool here: the failure modes found in review were wrong
+*abstractions of Kubernetes* (a nonexistent `Terminating` phase, non-atomic
+delete, phase-as-readiness, non-atomic Secret→pod against GC), which a
+hand-written model would have reproduced convincingly.
+
+## Known Defects (at `28ae6cd21`)
+
+**Citation pin:** every `file:line` reference in this document was verified
+against `28ae6cd21` — the commit at which this spec merged to `main`.
+References are to that tree; a later commit may offset them.
+
+Desktop- and harness-side, discovered during this design:
+
+1. **Windows discovery id pollution**: the `.exe` suffix survives into the
+   provider id, which then fails id validation at deploy — dropdown-visible,
+   probe-fine, deploy-broken. Fix is a suffix strip in discovery. (v1
+   provider scope is macOS+Linux regardless — [DECISION B].)
+2. **Provider env inheritance**: `invoke_provider` passes the desktop's
+   environment through unmodified; combined with launchd's minimal PATH this
+   breaks kubeconfig exec plugins. Mitigated provider-side (§K8s Auth);
+   a desktop-side PATH augmentation would fix the class.
+3. **Deploy payload bypasses the launch resolver** (the prerequisite this
+   spec names for §Launch data — a desktop code change, not spec text).
+   At `28ae6cd21`, `deploy_payload_json` serializes raw record bytes and a
+   three-layer `merged_user_env` where the local spawn uses
+   `resolve_effective_harness_descriptor`'s six-layer resolution. Concrete
+   consequences, each verified in review: (a) no per-runtime model/provider
+   env — a remote goose agent silently ignores the user's model choice, and
+   `provider_locked` runtimes would receive vars the desktop deliberately
+   withholds; (b) persona-derived `agent_command` and definition-provided
+   `agent_args` serialize as blank/empty — a different command line than the
+   identical local agent; (c) no `owner_pubkey` — a null-`auth_tag` agent
+   cannot match `!shutdown` (it *answers* it), stranding §Stop; (d) spawn
+   policy (`BUZZ_ACP_RELAY_OBSERVER`, runtime `default_env` such as
+   `GOOSE_MODE=auto`, team instructions, session title, lazy-pool selection)
+   is absent — remote pods run different observer/approval semantics
+   (`BUZZ_ACP_DEDUP`/`BUZZ_ACP_MULTIPLE_EVENT_HANDLING` are *not* on this
+   list: the local writes match the harness defaults, §Launch data); (e) a
+   mesh-provider agent deploys pointed at a loopback URL that cannot exist
+   in the pod instead of being refused. Until `deploy_payload_json` emits
+   the `launch` block, no provider can conform to §Launch data, and the
+   current payload MUST be treated as insufficient for a
+   semantics-preserving remote launch. **Security follow-through:** once
+   secrets can arrive via `launch.env`, desktop redaction MUST collect
+   candidate values from `launch.env` (and `launch.policy_env`) as well as
+   legacy `agent.env_vars` — at `28ae6cd21`, `env_secrets_from_request`
+   reads only `agent.env_vars` (`backend.rs`), leaving a
+   definition/persona-layer secret outside the literal-value scrub.
+   Conformance: a provider that echoes a launch-only secret into an error
+   must come back redacted.
+4. **The I5 reaper does not exist, and its natural home is a trap**
+   (harness code prerequisite). `BUZZ_ACP_EXIT_AFTER_INACTIVITY` appears
+   nowhere in the harness at `28ae6cd21`; §Auto-Stop is a design, not a
+   description. Worse, the obvious attachment point — the existing 30s
+   maintenance tick — is gated on `pool_ready` (`lib.rs:1743`), which under
+   `lazy_pool` only becomes true when work arrives, so a never-mentioned
+   lazy pod would never evaluate the bound: I5 dead in its most important
+   case (§Auto-Stop mechanism rule). The implementation MUST run the expiry
+   check on a pool-independent timer and MUST add the env var to
+   `RESERVED_ENV_KEYS` in the same change.
+5. **The deploy path never checks `protocol_version`** (desktop code
+   prerequisite). `provider_deploy` (`backend.rs`) sends the nsec-bearing
+   `deploy` request without any preceding `info` on the same resolved
+   executable; §Discovery's pre-secret negotiation gate is a design, not a
+   description, until the deploy command performs
+   resolve-once → stage-and-digest → `info` → explicit-version check →
+   `deploy`, both invocations running the staged bytes.
+6. **The clean-exit contract is emergent, not defended** (harness code
+   prerequisite; gates `OnFailure`). At `28ae6cd21`: the graceful path
+   returns `Ok(())` (`lib.rs:2723`), and owner `!shutdown` (`:2045`),
+   Ctrl-C (`:1635`), and
+   SIGTERM (`:1644`) all route into the same shutdown channel — so clean
+   stops exit 0 *today*, but no distinguished exit code exists and no test
+   pins "intentional exit ⇒ 0"; every `process::exit(1)` in the crate is a
+   startup failure. Until a
+   pinned, tested exit-code contract lands, no supervisor restart policy
+   (`restartPolicy: OnFailure`, systemd `Restart=on-failure`) may be
+   deployed against the harness: a refactor returning `Err` from a drain
+   timeout would silently convert every clean stop into a restart loop —
+   I5 defeated with no failing test (I5 ordering rule).
+7. **The shutdown tail overruns the declared grace budget at default
+   config** (harness code prerequisite). At `28ae6cd21`: the post-drain
+   reap segment
+   (`lib.rs:2664-2688`) runs *after* the 30s drain timeout closes
+   (`:2636,:2657`) and serially awaits a 5s post-SIGKILL wait per occupied
+   slot (`acp.rs:436`) — that segment alone reaches ~87s at the desktop's
+   default parallelism of 10 (`types.rs:814`; #3038 lowered it from 24),
+   ~197s at the harness cap of 32 (`config.rs:293`), against the binding's
+   60s grace; and it is not the whole tail — the wake-task drain
+   (`:2612`) and awakened-pool shutdown (`:2620-2624`, per-slot loop
+   `:3747-3751`, no timeout) precede it (§Stop), so the total is
+   unbounded by today's segment timeouts. The fix is one shared deadline
+   across the entire post-signal
+   path with a reserved finalization slice (≥ the finalizers' declared
+   bounds, currently 2s presence + 5s relay close = 7s) for presence
+   `offline` and
+   relay close, child cleanup degrading first (§Stop); natural home is the
+   same harness change as the I5 reaper (defect 4).
+8. **Cleared numeric config fields ship as strings** (desktop code
+   prerequisite, raised by blessing `0`). `coerceConfigValues`
+   (`desktop/src/features/agents/ui/ProviderConfigFields.tsx:6` at
+   `28ae6cd21`) skips numeric coercion when the value is `""`, so a
+   *cleared* numeric field reaches the provider as a JSON string instead
+   of a number. Blessing `inactivity_seconds: 0` makes clearing that
+   field a legitimate user action, so the empty-string arm now sits on a
+   documented path: the provider receives `""` where the schema says
+   integer, and "0 MUST NOT be rejected" cannot protect a value that
+   never parses as 0. Fix is desktop-side (map cleared numeric →
+   omit-or-default, never `""`); provider-side, a non-numeric value for a
+   numeric field is an in-band error, not a silent default.
+
+## Implementation Correspondence
+
+| spec concept | code |
+|---|---|
+| Discovery, resolution rule | `desktop/src-tauri/src/managed_agents/backend.rs` (`discover_provider_candidates`, `resolve_provider_binary`) |
+| Invocation, output caps, exit rule | `backend.rs` (`invoke_provider`) |
+| Pre-secret negotiation gate | *to be added*: `backend.rs` deploy path — resolve-once → stage-and-digest → `info` → explicit-version check → `deploy` on the staged bytes (Known Defect 5) |
+| Redaction | `backend.rs` (`redact_secrets_with`) |
+| I2 validation | `backend.rs` (`validate_provider_config`) |
+| I1 refusal, payload | `desktop/src-tauri/src/commands/agents_deploy.rs` |
+| Launch resolver (shared with local spawn) | `desktop/src-tauri/src/managed_agents/readiness.rs` (`resolve_effective_harness_descriptor`); `launch` block emission *to be added* to `agents_deploy.rs` (Known Defect 3) |
+| Mesh rewrite (why relay-mesh is non-deployable) | `desktop/src-tauri/src/managed_agents/relay_mesh.rs`; create-time rejection in `commands/agents.rs` (`normalize_relay_mesh`) |
+| Reserved-key strip | `desktop/src-tauri/src/managed_agents/env_vars.rs` (`RESERVED_ENV_KEYS`) |
+| Unconditional deploy on Start | `desktop/src-tauri/src/commands/agents.rs` (`start_managed_agent`) |
+| Presence publish / offline-on-exit | `crates/buzz-acp/src/lib.rs` (`publish_presence`, shutdown path) |
+| `!shutdown` owner check | `crates/buzz-acp/src/lib.rs` (main loop) |
+| Graceful shutdown path (budget enforcement *to be added* — Known Defect 7) | `crates/buzz-acp/src/lib.rs` (pool shutdown, then drain / reap / presence / relay close) |
+| Clean-exit exit-code contract | *to be added*: `crates/buzz-acp` distinguished exit codes + pinning test (Known Defect 6; gates `OnFailure`) |
+| Auto-stop flag | *to be added*: `crates/buzz-acp/src/config.rs` + a pool-independent timer (NOT the `pool_ready`-gated maintenance tick — Known Defect 4) + `RESERVED_ENV_KEYS` entry |
+| Kubernetes binding | *to be added*: `crates/buzz-backend-kubernetes` |
+| Sprig image | *to be added*: `Dockerfile.sprig` + workflow |
+
+## Open Decisions
+
+Marked `[DECISION]` inline; consolidated:
+
+- **A. Nest scaffolding** — should the image entrypoint scaffold the agent
+  workspace (AGENTS.md, RESEARCH/, …) that the desktop's `ensure_nest`
+  provides locally? Recommendation (revised): **workspace becomes a
+  protocol field the desktop states**, not an image-baked behavior — the
+  desktop resolves the nest content it would have written locally and
+  carries it in the launch data, so every substrate materializes the same
+  workspace from the same source of truth and the image stays
+  scaffold-free. An image-side template crate was the earlier
+  recommendation; it loses because it forks the nest definition into a
+  second implementation that drifts from `ensure_nest`.
+- **B. Windows scope** — fix the `.exe` discovery bug in the desktop now;
+  ship Windows provider binaries only on demand. Recommended as stated.
+- **C. Config budget** — the 9-field v1 set above. Recommended as stated.
+- **D. Desktop bundling** — `~/.local/bin` install only for v1. Recommended
+  as stated.
+- **E. Running-pod semantics** — no-op (recommended, both reviewers) vs
+  forcible recycle on Start. Ruled: **per-binding policy**, with one
+  universal property every binding must preserve — no sequence of Starts
+  yields two live instances in one scope (I4). The Kubernetes binding
+  keeps strict no-op in v1; a recycle affordance, if a binding adds one,
+  is stop-then-start, never delete-under-a-live-agent.
+- **F. Mesh deployability** — the spec refuses relay-mesh agents
+  pre-mutation in v1 (§Launch data: the transport is desktop loopback;
+  serializing it fails identically but invisibly). Reviewer consensus is
+  refusal; ratification requested because it makes a visible product cut
+  (shared-compute agents are local-only until an in-image mesh client
+  exists).
+- **G. Remote override semantics** — the spec keeps local semantics: user
+  env continues to beat Buzz behavior defaults remotely (three-tier
+  precedence, §Launch data), because the alternative is a quiet behavior
+  fork between local and remote spawns of the same record. Flagged because
+  it is a policy statement about what power users may do to remote pods.
+- **H. Startup budget** — with deploy success now requiring container start
+  (§Deploy State Machine), the 600s operation deadline is the de facto
+  cold-pull / scale-from-zero budget. The spec fixes the semantics
+  narrowly: the deadline bounds how long one Start waits synchronously —
+  never when anything is destroyed (recoverable startup is observational
+  across calls, so a cluster whose autoscaler `new-pod-scale-up-delay`
+  exceeds 600s degrades to "Start reports unconfirmed, a later Start
+  adopts the now-running pod", not a livelock). The remaining SLO ruling
+  is UX-only: is ten minutes of synchronous waiting the right ceiling for
+  the intended cluster class?
+- **I. Never-started escape hatch** — the create-intent fingerprint
+  (§Deploy State Machine) lets a config *change* replace a never-started
+  pod, closing the config wedge. Ruled on the vision-consistency half:
+  Start-time auto-repair of never-started bodies is legitimate, **fenced
+  to Buzz-authored, positively identified residue** (§Deploy State Machine
+  auto-repair rule) — the vision's "never-started body is operator
+  residue" line gains that qualifier rather than being waived. The
+  remaining product question: does v1 owe users an explicit in-product
+  "clear this stuck deployment" affordance for a never-started pod whose
+  config they have *not* changed (a genuinely slow or broken cluster)?
+  Both reviewers agree on the mechanism; this is the remaining product
+  question layered on top of it.
+
+## Summary
+
+Remote agents extend Buzz's managed-agent model across a deliberately thin
+boundary: one untrusted binary, two JSON operations, and a relay. The
+desktop's obligations end at a well-formed, fail-closed deploy payload; the
+provider's obligations are convergence and honesty about state; the agent's
+obligation is to honor its owner's lifetime choice — bounded by default,
+indefinite by declaration, and in either case final when told to stop.
+Everything else — status, control,
+memory — was already on the relay, which is why the design holds: the relay
+was the management plane all along, and the desktop was only ever one of
+its doors.
diff --git a/lefthook.yml b/lefthook.yml
index 87eaa87c21..75d205722f 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -61,12 +61,12 @@ pre-push:
       glob: ["desktop/**", "pnpm-lock.yaml"]
       exclude: ["desktop/src-tauri/**"]
       run: just desktop-test
-    desktop-tauri-test:
-      # ci.yml:113 — Desktop Core triggers on `rust` OR `desktop-rust`;
-      # desktop/src-tauri path-depends on crates/buzz-core, buzz-persona,
-      # buzz-sdk, buzz-agent (desktop/src-tauri/Cargo.toml:88-91).
+    desktop-tauri-checks:
+      # Keep local lint parity with Desktop Core CI for every path that can
+      # affect the Tauri crate or its path dependencies. Run clippy and tests
+      # serially so parallel pre-push hooks do not contend for Cargo's lock.
       glob: ["desktop/src-tauri/**", "crates/**", "migrations/**", "schema/**", "Cargo.toml", "Cargo.lock", "rust-toolchain.toml", "deny.toml", "scripts/run-tests.sh", "justfile"]
-      run: just desktop-tauri-test
+      run: just desktop-tauri-clippy && just desktop-tauri-test
     mobile-test:
       glob: ["mobile/**"]
       run: just mobile-test
diff --git a/migrations/0026_replica_heartbeat.sql b/migrations/0026_replica_heartbeat.sql
new file mode 100644
index 0000000000..278be4d87a
--- /dev/null
+++ b/migrations/0026_replica_heartbeat.sql
@@ -0,0 +1,38 @@
+-- Replica heartbeat: a portable read-side freshness observation for the
+-- replica fence (see crates/buzz-db/src/replica_fence.rs).
+--
+-- Why: the fence's ordered writer-side proof previously ended in a WAL-LSN
+-- comparison (`pg_last_wal_replay_lsn() >= L`), which Aurora's reader
+-- endpoints do not expose — the fence therefore never opened on Aurora, by
+-- design (fail closed). This table replaces only that read-side observation:
+-- the probe commits a monotonically increasing `token` AFTER the ordered
+-- writer scan (clock sample -> oldest-xact guard), and a reader session that
+-- observes token >= M has, by WAL/storage replay order, also replayed every
+-- commit that preceded M. The commit-time floor guard (migration 0021) and
+-- the writer-side scan remain load-bearing and unchanged.
+--
+-- Shape: exactly one row, enforced by the CHECK'd primary key. Every relay
+-- pod's probe increments the same row; the single-row UPDATE is the
+-- serialization point that makes tokens globally commit-ordered, which is
+-- what lets a pod prove coverage from the greatest token it retained that is
+-- <= the token a reader session observes (multi-pod safety).
+--
+-- `epoch` detects resets: a restore/re-seed that rolls `token` backwards
+-- must never let a stale retained token masquerade as fresh coverage.
+-- Readers validate the observed epoch against the epoch retained with each
+-- token; a mismatch fails closed (route to writer).
+--
+-- Not an events row: exempt from the created_at floor guard by construction,
+-- and deliberately deployment-global (no community_id) — it describes the
+-- replication topology, not tenant data.
+
+CREATE TABLE replica_heartbeat (
+    id    smallint PRIMARY KEY CHECK (id = 1),
+    epoch uuid     NOT NULL DEFAULT gen_random_uuid(),
+    token bigint   NOT NULL DEFAULT 0
+);
+
+INSERT INTO replica_heartbeat (id) VALUES (1);
+
+INSERT INTO _operator_global_tables (table_name, reason) VALUES
+    ('replica_heartbeat', 'single-row replication freshness token; describes deployment topology, never tenant data');
diff --git a/mobile/assets/emoji/emoji-data.json b/mobile/assets/emoji/emoji-data.json
new file mode 100644
index 0000000000..57c5435b9b
--- /dev/null
+++ b/mobile/assets/emoji/emoji-data.json
@@ -0,0 +1 @@
+{"categories":[{"id":"people","emoji":["grinning","smiley","smile","grin","laughing","sweat_smile","rolling_on_the_floor_laughing","joy","slightly_smiling_face","upside_down_face","melting_face","wink","blush","innocent","smiling_face_with_3_hearts","heart_eyes","star-struck","kissing_heart","kissing","relaxed","kissing_closed_eyes","kissing_smiling_eyes","smiling_face_with_tear","yum","stuck_out_tongue","stuck_out_tongue_winking_eye","zany_face","stuck_out_tongue_closed_eyes","money_mouth_face","hugging_face","face_with_hand_over_mouth","face_with_open_eyes_and_hand_over_mouth","face_with_peeking_eye","shushing_face","thinking_face","saluting_face","zipper_mouth_face","face_with_raised_eyebrow","neutral_face","expressionless","no_mouth","dotted_line_face","face_in_clouds","smirk","unamused","face_with_rolling_eyes","grimacing","face_exhaling","lying_face","shaking_face","relieved","pensive","sleepy","drooling_face","sleeping","mask","face_with_thermometer","face_with_head_bandage","nauseated_face","face_vomiting","sneezing_face","hot_face","cold_face","woozy_face","dizzy_face","face_with_spiral_eyes","exploding_head","face_with_cowboy_hat","partying_face","disguised_face","sunglasses","nerd_face","face_with_monocle","confused","face_with_diagonal_mouth","worried","slightly_frowning_face","white_frowning_face","open_mouth","hushed","astonished","flushed","pleading_face","face_holding_back_tears","frowning","anguished","fearful","cold_sweat","disappointed_relieved","cry","sob","scream","confounded","persevere","disappointed","sweat","weary","tired_face","yawning_face","triumph","rage","angry","face_with_symbols_on_mouth","smiling_imp","imp","skull","skull_and_crossbones","hankey","clown_face","japanese_ogre","japanese_goblin","ghost","alien","space_invader","wave","raised_back_of_hand","raised_hand_with_fingers_splayed","hand","spock-hand","rightwards_hand","leftwards_hand","palm_down_hand","palm_up_hand","leftwards_pushing_hand","rightwards_pushing_hand","ok_hand","pinched_fingers","pinching_hand","v","crossed_fingers","hand_with_index_finger_and_thumb_crossed","i_love_you_hand_sign","the_horns","call_me_hand","point_left","point_right","point_up_2","middle_finger","point_down","point_up","index_pointing_at_the_viewer","+1","-1","fist","facepunch","left-facing_fist","right-facing_fist","clap","raised_hands","heart_hands","open_hands","palms_up_together","handshake","pray","writing_hand","nail_care","selfie","muscle","mechanical_arm","mechanical_leg","leg","foot","ear","ear_with_hearing_aid","nose","brain","anatomical_heart","lungs","tooth","bone","eyes","eye","tongue","lips","biting_lip","baby","child","boy","girl","adult","person_with_blond_hair","man","bearded_person","man_with_beard","woman_with_beard","red_haired_man","curly_haired_man","white_haired_man","bald_man","woman","red_haired_woman","red_haired_person","curly_haired_woman","curly_haired_person","white_haired_woman","white_haired_person","bald_woman","bald_person","blond-haired-woman","blond-haired-man","older_adult","older_man","older_woman","person_frowning","man-frowning","woman-frowning","person_with_pouting_face","man-pouting","woman-pouting","no_good","man-gesturing-no","woman-gesturing-no","ok_woman","man-gesturing-ok","woman-gesturing-ok","information_desk_person","man-tipping-hand","woman-tipping-hand","raising_hand","man-raising-hand","woman-raising-hand","deaf_person","deaf_man","deaf_woman","bow","man-bowing","woman-bowing","face_palm","man-facepalming","woman-facepalming","shrug","man-shrugging","woman-shrugging","health_worker","male-doctor","female-doctor","student","male-student","female-student","teacher","male-teacher","female-teacher","judge","male-judge","female-judge","farmer","male-farmer","female-farmer","cook","male-cook","female-cook","mechanic","male-mechanic","female-mechanic","factory_worker","male-factory-worker","female-factory-worker","office_worker","male-office-worker","female-office-worker","scientist","male-scientist","female-scientist","technologist","male-technologist","female-technologist","singer","male-singer","female-singer","artist","male-artist","female-artist","pilot","male-pilot","female-pilot","astronaut","male-astronaut","female-astronaut","firefighter","male-firefighter","female-firefighter","cop","male-police-officer","female-police-officer","sleuth_or_spy","male-detective","female-detective","guardsman","male-guard","female-guard","ninja","construction_worker","male-construction-worker","female-construction-worker","person_with_crown","prince","princess","man_with_turban","man-wearing-turban","woman-wearing-turban","man_with_gua_pi_mao","person_with_headscarf","person_in_tuxedo","man_in_tuxedo","woman_in_tuxedo","bride_with_veil","man_with_veil","woman_with_veil","pregnant_woman","pregnant_man","pregnant_person","breast-feeding","woman_feeding_baby","man_feeding_baby","person_feeding_baby","angel","santa","mrs_claus","mx_claus","superhero","male_superhero","female_superhero","supervillain","male_supervillain","female_supervillain","mage","male_mage","female_mage","fairy","male_fairy","female_fairy","vampire","male_vampire","female_vampire","merperson","merman","mermaid","elf","male_elf","female_elf","genie","male_genie","female_genie","zombie","male_zombie","female_zombie","troll","massage","man-getting-massage","woman-getting-massage","haircut","man-getting-haircut","woman-getting-haircut","walking","man-walking","woman-walking","standing_person","man_standing","woman_standing","kneeling_person","man_kneeling","woman_kneeling","person_with_probing_cane","man_with_probing_cane","woman_with_probing_cane","person_in_motorized_wheelchair","man_in_motorized_wheelchair","woman_in_motorized_wheelchair","person_in_manual_wheelchair","man_in_manual_wheelchair","woman_in_manual_wheelchair","runner","man-running","woman-running","dancer","man_dancing","man_in_business_suit_levitating","dancers","men-with-bunny-ears-partying","women-with-bunny-ears-partying","person_in_steamy_room","man_in_steamy_room","woman_in_steamy_room","person_climbing","man_climbing","woman_climbing","fencer","horse_racing","skier","snowboarder","golfer","man-golfing","woman-golfing","surfer","man-surfing","woman-surfing","rowboat","man-rowing-boat","woman-rowing-boat","swimmer","man-swimming","woman-swimming","person_with_ball","man-bouncing-ball","woman-bouncing-ball","weight_lifter","man-lifting-weights","woman-lifting-weights","bicyclist","man-biking","woman-biking","mountain_bicyclist","man-mountain-biking","woman-mountain-biking","person_doing_cartwheel","man-cartwheeling","woman-cartwheeling","wrestlers","man-wrestling","woman-wrestling","water_polo","man-playing-water-polo","woman-playing-water-polo","handball","man-playing-handball","woman-playing-handball","juggling","man-juggling","woman-juggling","person_in_lotus_position","man_in_lotus_position","woman_in_lotus_position","bath","sleeping_accommodation","people_holding_hands","two_women_holding_hands","man_and_woman_holding_hands","two_men_holding_hands","couplekiss","woman-kiss-man","man-kiss-man","woman-kiss-woman","couple_with_heart","woman-heart-man","man-heart-man","woman-heart-woman","family","man-woman-boy","man-woman-girl","man-woman-girl-boy","man-woman-boy-boy","man-woman-girl-girl","man-man-boy","man-man-girl","man-man-girl-boy","man-man-boy-boy","man-man-girl-girl","woman-woman-boy","woman-woman-girl","woman-woman-girl-boy","woman-woman-boy-boy","woman-woman-girl-girl","man-boy","man-boy-boy","man-girl","man-girl-boy","man-girl-girl","woman-boy","woman-boy-boy","woman-girl","woman-girl-boy","woman-girl-girl","speaking_head_in_silhouette","bust_in_silhouette","busts_in_silhouette","people_hugging","footprints","robot_face","smiley_cat","smile_cat","joy_cat","heart_eyes_cat","smirk_cat","kissing_cat","scream_cat","crying_cat_face","pouting_cat","see_no_evil","hear_no_evil","speak_no_evil","love_letter","cupid","gift_heart","sparkling_heart","heartpulse","heartbeat","revolving_hearts","two_hearts","heart_decoration","heavy_heart_exclamation_mark_ornament","broken_heart","heart_on_fire","mending_heart","heart","pink_heart","orange_heart","yellow_heart","green_heart","blue_heart","light_blue_heart","purple_heart","brown_heart","black_heart","grey_heart","white_heart","kiss","100","anger","boom","dizzy","sweat_drops","dash","hole","speech_balloon","eye-in-speech-bubble","left_speech_bubble","right_anger_bubble","thought_balloon","zzz"]},{"id":"nature","emoji":["monkey_face","monkey","gorilla","orangutan","dog","dog2","guide_dog","service_dog","poodle","wolf","fox_face","raccoon","cat","cat2","black_cat","lion_face","tiger","tiger2","leopard","horse","moose","donkey","racehorse","unicorn_face","zebra_face","deer","bison","cow","ox","water_buffalo","cow2","pig","pig2","boar","pig_nose","ram","sheep","goat","dromedary_camel","camel","llama","giraffe_face","elephant","mammoth","rhinoceros","hippopotamus","mouse","mouse2","rat","hamster","rabbit","rabbit2","chipmunk","beaver","hedgehog","bat","bear","polar_bear","koala","panda_face","sloth","otter","skunk","kangaroo","badger","feet","turkey","chicken","rooster","hatching_chick","baby_chick","hatched_chick","bird","penguin","dove_of_peace","eagle","duck","swan","owl","dodo","feather","flamingo","peacock","parrot","wing","black_bird","goose","frog","crocodile","turtle","lizard","snake","dragon_face","dragon","sauropod","t-rex","whale","whale2","dolphin","seal","fish","tropical_fish","blowfish","shark","octopus","shell","coral","jellyfish","snail","butterfly","bug","ant","bee","beetle","ladybug","cricket","cockroach","spider","spider_web","scorpion","mosquito","fly","worm","microbe","bouquet","cherry_blossom","white_flower","lotus","rosette","rose","wilted_flower","hibiscus","sunflower","blossom","tulip","hyacinth","seedling","potted_plant","evergreen_tree","deciduous_tree","palm_tree","cactus","ear_of_rice","herb","shamrock","four_leaf_clover","maple_leaf","fallen_leaf","leaves","empty_nest","nest_with_eggs","mushroom"]},{"id":"foods","emoji":["grapes","melon","watermelon","tangerine","lemon","banana","pineapple","mango","apple","green_apple","pear","peach","cherries","strawberry","blueberries","kiwifruit","tomato","olive","coconut","avocado","eggplant","potato","carrot","corn","hot_pepper","bell_pepper","cucumber","leafy_green","broccoli","garlic","onion","peanuts","beans","chestnut","ginger_root","pea_pod","bread","croissant","baguette_bread","flatbread","pretzel","bagel","pancakes","waffle","cheese_wedge","meat_on_bone","poultry_leg","cut_of_meat","bacon","hamburger","fries","pizza","hotdog","sandwich","taco","burrito","tamale","stuffed_flatbread","falafel","egg","fried_egg","shallow_pan_of_food","stew","fondue","bowl_with_spoon","green_salad","popcorn","butter","salt","canned_food","bento","rice_cracker","rice_ball","rice","curry","ramen","spaghetti","sweet_potato","oden","sushi","fried_shrimp","fish_cake","moon_cake","dango","dumpling","fortune_cookie","takeout_box","crab","lobster","shrimp","squid","oyster","icecream","shaved_ice","ice_cream","doughnut","cookie","birthday","cake","cupcake","pie","chocolate_bar","candy","lollipop","custard","honey_pot","baby_bottle","glass_of_milk","coffee","teapot","tea","sake","champagne","wine_glass","cocktail","tropical_drink","beer","beers","clinking_glasses","tumbler_glass","pouring_liquid","cup_with_straw","bubble_tea","beverage_box","mate_drink","ice_cube","chopsticks","knife_fork_plate","fork_and_knife","spoon","hocho","jar","amphora"]},{"id":"activity","emoji":["jack_o_lantern","christmas_tree","fireworks","sparkler","firecracker","sparkles","balloon","tada","confetti_ball","tanabata_tree","bamboo","dolls","flags","wind_chime","rice_scene","red_envelope","ribbon","gift","reminder_ribbon","admission_tickets","ticket","medal","trophy","sports_medal","first_place_medal","second_place_medal","third_place_medal","soccer","baseball","softball","basketball","volleyball","football","rugby_football","tennis","flying_disc","bowling","cricket_bat_and_ball","field_hockey_stick_and_ball","ice_hockey_stick_and_puck","lacrosse","table_tennis_paddle_and_ball","badminton_racquet_and_shuttlecock","boxing_glove","martial_arts_uniform","goal_net","golf","ice_skate","fishing_pole_and_fish","diving_mask","running_shirt_with_sash","ski","sled","curling_stone","dart","yo-yo","kite","gun","8ball","crystal_ball","magic_wand","video_game","joystick","slot_machine","game_die","jigsaw","teddy_bear","pinata","mirror_ball","nesting_dolls","spades","hearts","diamonds","clubs","chess_pawn","black_joker","mahjong","flower_playing_cards","performing_arts","frame_with_picture","art","thread","sewing_needle","yarn","knot"]},{"id":"places","emoji":["earth_africa","earth_americas","earth_asia","globe_with_meridians","world_map","japan","compass","snow_capped_mountain","mountain","volcano","mount_fuji","camping","beach_with_umbrella","desert","desert_island","national_park","stadium","classical_building","building_construction","bricks","rock","wood","hut","house_buildings","derelict_house_building","house","house_with_garden","office","post_office","european_post_office","hospital","bank","hotel","love_hotel","convenience_store","school","department_store","factory","japanese_castle","european_castle","wedding","tokyo_tower","statue_of_liberty","church","mosque","hindu_temple","synagogue","shinto_shrine","kaaba","fountain","tent","foggy","night_with_stars","cityscape","sunrise_over_mountains","sunrise","city_sunset","city_sunrise","bridge_at_night","hotsprings","carousel_horse","playground_slide","ferris_wheel","roller_coaster","barber","circus_tent","steam_locomotive","railway_car","bullettrain_side","bullettrain_front","train2","metro","light_rail","station","tram","monorail","mountain_railway","train","bus","oncoming_bus","trolleybus","minibus","ambulance","fire_engine","police_car","oncoming_police_car","taxi","oncoming_taxi","car","oncoming_automobile","blue_car","pickup_truck","truck","articulated_lorry","tractor","racing_car","racing_motorcycle","motor_scooter","manual_wheelchair","motorized_wheelchair","auto_rickshaw","bike","scooter","skateboard","roller_skate","busstop","motorway","railway_track","oil_drum","fuelpump","wheel","rotating_light","traffic_light","vertical_traffic_light","octagonal_sign","construction","anchor","ring_buoy","boat","canoe","speedboat","passenger_ship","ferry","motor_boat","ship","airplane","small_airplane","airplane_departure","airplane_arriving","parachute","seat","helicopter","suspension_railway","mountain_cableway","aerial_tramway","satellite","rocket","flying_saucer","bellhop_bell","luggage","hourglass","hourglass_flowing_sand","watch","alarm_clock","stopwatch","timer_clock","mantelpiece_clock","clock12","clock1230","clock1","clock130","clock2","clock230","clock3","clock330","clock4","clock430","clock5","clock530","clock6","clock630","clock7","clock730","clock8","clock830","clock9","clock930","clock10","clock1030","clock11","clock1130","new_moon","waxing_crescent_moon","first_quarter_moon","moon","full_moon","waning_gibbous_moon","last_quarter_moon","waning_crescent_moon","crescent_moon","new_moon_with_face","first_quarter_moon_with_face","last_quarter_moon_with_face","thermometer","sunny","full_moon_with_face","sun_with_face","ringed_planet","star","star2","stars","milky_way","cloud","partly_sunny","thunder_cloud_and_rain","mostly_sunny","barely_sunny","partly_sunny_rain","rain_cloud","snow_cloud","lightning","tornado","fog","wind_blowing_face","cyclone","rainbow","closed_umbrella","umbrella","umbrella_with_rain_drops","umbrella_on_ground","zap","snowflake","snowman","snowman_without_snow","comet","fire","droplet","ocean"]},{"id":"objects","emoji":["eyeglasses","dark_sunglasses","goggles","lab_coat","safety_vest","necktie","shirt","jeans","scarf","gloves","coat","socks","dress","kimono","sari","one-piece_swimsuit","briefs","shorts","bikini","womans_clothes","folding_hand_fan","purse","handbag","pouch","shopping_bags","school_satchel","thong_sandal","mans_shoe","athletic_shoe","hiking_boot","womans_flat_shoe","high_heel","sandal","ballet_shoes","boot","hair_pick","crown","womans_hat","tophat","mortar_board","billed_cap","military_helmet","helmet_with_white_cross","prayer_beads","lipstick","ring","gem","mute","speaker","sound","loud_sound","loudspeaker","mega","postal_horn","bell","no_bell","musical_score","musical_note","notes","studio_microphone","level_slider","control_knobs","microphone","headphones","radio","saxophone","accordion","guitar","musical_keyboard","trumpet","violin","banjo","drum_with_drumsticks","long_drum","maracas","flute","iphone","calling","phone","telephone_receiver","pager","fax","battery","low_battery","electric_plug","computer","desktop_computer","printer","keyboard","three_button_mouse","trackball","minidisc","floppy_disk","cd","dvd","abacus","movie_camera","film_frames","film_projector","clapper","tv","camera","camera_with_flash","video_camera","vhs","mag","mag_right","candle","bulb","flashlight","izakaya_lantern","diya_lamp","notebook_with_decorative_cover","closed_book","book","green_book","blue_book","orange_book","books","notebook","ledger","page_with_curl","scroll","page_facing_up","newspaper","rolled_up_newspaper","bookmark_tabs","bookmark","label","moneybag","coin","yen","dollar","euro","pound","money_with_wings","credit_card","receipt","chart","email","e-mail","incoming_envelope","envelope_with_arrow","outbox_tray","inbox_tray","package","mailbox","mailbox_closed","mailbox_with_mail","mailbox_with_no_mail","postbox","ballot_box_with_ballot","pencil2","black_nib","lower_left_fountain_pen","lower_left_ballpoint_pen","lower_left_paintbrush","lower_left_crayon","memo","briefcase","file_folder","open_file_folder","card_index_dividers","date","calendar","spiral_note_pad","spiral_calendar_pad","card_index","chart_with_upwards_trend","chart_with_downwards_trend","bar_chart","clipboard","pushpin","round_pushpin","paperclip","linked_paperclips","straight_ruler","triangular_ruler","scissors","card_file_box","file_cabinet","wastebasket","lock","unlock","lock_with_ink_pen","closed_lock_with_key","key","old_key","hammer","axe","pick","hammer_and_pick","hammer_and_wrench","dagger_knife","crossed_swords","bomb","boomerang","bow_and_arrow","shield","carpentry_saw","wrench","screwdriver","nut_and_bolt","gear","compression","scales","probing_cane","link","chains","hook","toolbox","magnet","ladder","alembic","test_tube","petri_dish","dna","microscope","telescope","satellite_antenna","syringe","drop_of_blood","pill","adhesive_bandage","crutch","stethoscope","x-ray","door","elevator","mirror","window","bed","couch_and_lamp","chair","toilet","plunger","shower","bathtub","mouse_trap","razor","lotion_bottle","safety_pin","broom","basket","roll_of_paper","bucket","soap","bubbles","toothbrush","sponge","fire_extinguisher","shopping_trolley","smoking","coffin","headstone","funeral_urn","nazar_amulet","hamsa","moyai","placard","identification_card"]},{"id":"symbols","emoji":["atm","put_litter_in_its_place","potable_water","wheelchair","mens","womens","restroom","baby_symbol","wc","passport_control","customs","baggage_claim","left_luggage","warning","children_crossing","no_entry","no_entry_sign","no_bicycles","no_smoking","do_not_litter","non-potable_water","no_pedestrians","no_mobile_phones","underage","radioactive_sign","biohazard_sign","arrow_up","arrow_upper_right","arrow_right","arrow_lower_right","arrow_down","arrow_lower_left","arrow_left","arrow_upper_left","arrow_up_down","left_right_arrow","leftwards_arrow_with_hook","arrow_right_hook","arrow_heading_up","arrow_heading_down","arrows_clockwise","arrows_counterclockwise","back","end","on","soon","top","place_of_worship","atom_symbol","om_symbol","star_of_david","wheel_of_dharma","yin_yang","latin_cross","orthodox_cross","star_and_crescent","peace_symbol","menorah_with_nine_branches","six_pointed_star","khanda","aries","taurus","gemini","cancer","leo","virgo","libra","scorpius","sagittarius","capricorn","aquarius","pisces","ophiuchus","twisted_rightwards_arrows","repeat","repeat_one","arrow_forward","fast_forward","black_right_pointing_double_triangle_with_vertical_bar","black_right_pointing_triangle_with_double_vertical_bar","arrow_backward","rewind","black_left_pointing_double_triangle_with_vertical_bar","arrow_up_small","arrow_double_up","arrow_down_small","arrow_double_down","double_vertical_bar","black_square_for_stop","black_circle_for_record","eject","cinema","low_brightness","high_brightness","signal_strength","wireless","vibration_mode","mobile_phone_off","female_sign","male_sign","transgender_symbol","heavy_multiplication_x","heavy_plus_sign","heavy_minus_sign","heavy_division_sign","heavy_equals_sign","infinity","bangbang","interrobang","question","grey_question","grey_exclamation","exclamation","wavy_dash","currency_exchange","heavy_dollar_sign","medical_symbol","recycle","fleur_de_lis","trident","name_badge","beginner","o","white_check_mark","ballot_box_with_check","heavy_check_mark","x","negative_squared_cross_mark","curly_loop","loop","part_alternation_mark","eight_spoked_asterisk","eight_pointed_black_star","sparkle","copyright","registered","tm","hash","keycap_star","zero","one","two","three","four","five","six","seven","eight","nine","keycap_ten","capital_abcd","abcd","1234","symbols","abc","a","ab","b","cl","cool","free","information_source","id","m","new","ng","o2","ok","parking","sos","up","vs","koko","sa","u6708","u6709","u6307","ideograph_advantage","u5272","u7121","u7981","accept","u7533","u5408","u7a7a","congratulations","secret","u55b6","u6e80","red_circle","large_orange_circle","large_yellow_circle","large_green_circle","large_blue_circle","large_purple_circle","large_brown_circle","black_circle","white_circle","large_red_square","large_orange_square","large_yellow_square","large_green_square","large_blue_square","large_purple_square","large_brown_square","black_large_square","white_large_square","black_medium_square","white_medium_square","black_medium_small_square","white_medium_small_square","black_small_square","white_small_square","large_orange_diamond","large_blue_diamond","small_orange_diamond","small_blue_diamond","small_red_triangle","small_red_triangle_down","diamond_shape_with_a_dot_inside","radio_button","white_square_button","black_square_button"]},{"id":"flags","emoji":["checkered_flag","cn","crossed_flags","de","es","flag-ac","flag-ad","flag-ae","flag-af","flag-ag","flag-ai","flag-al","flag-am","flag-ao","flag-aq","flag-ar","flag-as","flag-at","flag-au","flag-aw","flag-ax","flag-az","flag-ba","flag-bb","flag-bd","flag-be","flag-bf","flag-bg","flag-bh","flag-bi","flag-bj","flag-bl","flag-bm","flag-bn","flag-bo","flag-bq","flag-br","flag-bs","flag-bt","flag-bv","flag-bw","flag-by","flag-bz","flag-ca","flag-cc","flag-cd","flag-cf","flag-cg","flag-ch","flag-ci","flag-ck","flag-cl","flag-cm","flag-co","flag-cp","flag-cr","flag-cu","flag-cv","flag-cw","flag-cx","flag-cy","flag-cz","flag-dg","flag-dj","flag-dk","flag-dm","flag-do","flag-dz","flag-ea","flag-ec","flag-ee","flag-eg","flag-eh","flag-england","flag-er","flag-et","flag-eu","flag-fi","flag-fj","flag-fk","flag-fm","flag-fo","flag-ga","flag-gd","flag-ge","flag-gf","flag-gg","flag-gh","flag-gi","flag-gl","flag-gm","flag-gn","flag-gp","flag-gq","flag-gr","flag-gs","flag-gt","flag-gu","flag-gw","flag-gy","flag-hk","flag-hm","flag-hn","flag-hr","flag-ht","flag-hu","flag-ic","flag-id","flag-ie","flag-il","flag-im","flag-in","flag-io","flag-iq","flag-ir","flag-is","flag-je","flag-jm","flag-jo","flag-ke","flag-kg","flag-kh","flag-ki","flag-km","flag-kn","flag-kp","flag-kw","flag-ky","flag-kz","flag-la","flag-lb","flag-lc","flag-li","flag-lk","flag-lr","flag-ls","flag-lt","flag-lu","flag-lv","flag-ly","flag-ma","flag-mc","flag-md","flag-me","flag-mf","flag-mg","flag-mh","flag-mk","flag-ml","flag-mm","flag-mn","flag-mo","flag-mp","flag-mq","flag-mr","flag-ms","flag-mt","flag-mu","flag-mv","flag-mw","flag-mx","flag-my","flag-mz","flag-na","flag-nc","flag-ne","flag-nf","flag-ng","flag-ni","flag-nl","flag-no","flag-np","flag-nr","flag-nu","flag-nz","flag-om","flag-pa","flag-pe","flag-pf","flag-pg","flag-ph","flag-pk","flag-pl","flag-pm","flag-pn","flag-pr","flag-ps","flag-pt","flag-pw","flag-py","flag-qa","flag-re","flag-ro","flag-rs","flag-rw","flag-sa","flag-sb","flag-sc","flag-scotland","flag-sd","flag-se","flag-sg","flag-sh","flag-si","flag-sj","flag-sk","flag-sl","flag-sm","flag-sn","flag-so","flag-sr","flag-ss","flag-st","flag-sv","flag-sx","flag-sy","flag-sz","flag-ta","flag-tc","flag-td","flag-tf","flag-tg","flag-th","flag-tj","flag-tk","flag-tl","flag-tm","flag-tn","flag-to","flag-tr","flag-tt","flag-tv","flag-tw","flag-tz","flag-ua","flag-ug","flag-um","flag-un","flag-uy","flag-uz","flag-va","flag-vc","flag-ve","flag-vg","flag-vi","flag-vn","flag-vu","flag-wales","flag-wf","flag-ws","flag-xk","flag-ye","flag-yt","flag-za","flag-zm","flag-zw","fr","gb","it","jp","kr","pirate_flag","rainbow-flag","ru","transgender_flag","triangular_flag_on_post","us","waving_black_flag","waving_white_flag"]}],"emoji":{"100":{"n":"Hundred Points","u":["💯"],"k":["100","score","perfect","numbers","century","exam","quiz","test","pass"]},"1234":{"n":"Input Numbers","u":["🔢"],"k":["1234","blue","square","1","2","3","4"]},"grinning":{"n":"Grinning Face","u":["😀"],"k":["smile","happy","joy",":D","grin"]},"smiley":{"n":"Grinning Face with Big Eyes","u":["😃"],"k":["smiley","happy","joy","haha",":D",":)","smile","funny"]},"smile":{"n":"Grinning Face with Smiling Eyes","u":["😄"],"k":["smile","happy","joy","funny","haha","laugh","like",":D",":)"]},"grin":{"n":"Beaming Face with Smiling Eyes","u":["😁"],"k":["grin","happy","smile","joy","kawaii"]},"laughing":{"n":"Grinning Squinting Face","u":["😆"],"k":["laughing","satisfied","happy","joy","lol","haha","glad","XD","laugh"]},"sweat_smile":{"n":"Grinning Face with Sweat","u":["😅"],"k":["smile","hot","happy","laugh","relief"]},"rolling_on_the_floor_laughing":{"n":"Rolling on the Floor Laughing","u":["🤣"],"k":["face","lol","haha","rofl"]},"joy":{"n":"Face with Tears of Joy","u":["😂"],"k":["cry","weep","happy","happytears","haha"]},"slightly_smiling_face":{"n":"Slightly Smiling Face","u":["🙂"],"k":["smile"]},"upside_down_face":{"n":"Upside-Down Face","u":["🙃"],"k":["upside","down","flipped","silly","smile"]},"melting_face":{"n":"Melting Face","u":["🫠"],"k":["hot","heat"]},"wink":{"n":"Winking Face","u":["😉"],"k":["wink","happy","mischievous","secret",";)","smile","eye"]},"blush":{"n":"Smiling Face with Smiling Eyes","u":["😊"],"k":["blush","smile","happy","flushed","crush","embarrassed","shy","joy"]},"innocent":{"n":"Smiling Face with Halo","u":["😇"],"k":["innocent","angel","heaven"]},"smiling_face_with_3_hearts":{"n":"Smiling Face with Hearts","u":["🥰"],"k":["3","love","like","affection","valentines","infatuation","crush","adore"]},"heart_eyes":{"n":"Smiling Face with Heart-Eyes","u":["😍"],"k":["heart","eyes","love","like","affection","valentines","infatuation","crush"]},"star-struck":{"n":"Star-Struck","u":["🤩"],"k":["star","struck","grinning","face","with","eyes","smile","starry"]},"kissing_heart":{"n":"Face Blowing a Kiss","u":["😘"],"k":["kissing","heart","love","like","affection","valentines","infatuation"]},"kissing":{"n":"Kissing Face","u":["😗"],"k":["love","like","3","valentines","infatuation","kiss"]},"relaxed":{"n":"Smiling Face","u":["☺️"],"k":["relaxed","blush","massage","happiness"]},"kissing_closed_eyes":{"n":"Kissing Face with Closed Eyes","u":["😚"],"k":["love","like","affection","valentines","infatuation","kiss"]},"kissing_smiling_eyes":{"n":"Kissing Face with Smiling Eyes","u":["😙"],"k":["affection","valentines","infatuation","kiss"]},"smiling_face_with_tear":{"n":"Smiling Face with Tear","u":["🥲"],"k":["sad","cry","pretend"]},"yum":{"n":"Face Savoring Food","u":["😋"],"k":["yum","happy","joy","tongue","smile","silly","yummy","nom","delicious","savouring"]},"stuck_out_tongue":{"n":"Face with Tongue","u":["😛"],"k":["stuck","out","prank","childish","playful","mischievous","smile"]},"stuck_out_tongue_winking_eye":{"n":"Winking Face with Tongue","u":["😜"],"k":["stuck","out","eye","prank","childish","playful","mischievous","smile","wink"]},"zany_face":{"n":"Zany Face","u":["🤪"],"k":["grinning","with","one","large","and","small","eye","goofy","crazy"]},"stuck_out_tongue_closed_eyes":{"n":"Squinting Face with Tongue","u":["😝"],"k":["stuck","out","closed","eyes","prank","playful","mischievous","smile"]},"money_mouth_face":{"n":"Money-Mouth Face","u":["🤑"],"k":["money","mouth","rich","dollar"]},"hugging_face":{"n":"Hugging Face","u":["🤗"],"k":["smile","hug"]},"face_with_hand_over_mouth":{"n":"Face with Hand over Mouth","u":["🤭"],"k":["smiling","eyes","and","covering","whoops","shock","surprise"]},"face_with_open_eyes_and_hand_over_mouth":{"n":"Face with Open Eyes and Hand over Mouth","u":["🫢"],"k":["silence","secret","shock","surprise"]},"face_with_peeking_eye":{"n":"Face with Peeking Eye","u":["🫣"],"k":["scared","frightening","embarrassing","shy"]},"shushing_face":{"n":"Shushing Face","u":["🤫"],"k":["with","finger","covering","closed","lips","quiet","shhh"]},"thinking_face":{"n":"Thinking Face","u":["🤔"],"k":["hmmm","think","consider"]},"saluting_face":{"n":"Saluting Face","u":["🫡"],"k":["respect","salute"]},"zipper_mouth_face":{"n":"Zipper-Mouth Face","u":["🤐"],"k":["zipper","mouth","sealed","secret"]},"face_with_raised_eyebrow":{"n":"Face with Raised Eyebrow","u":["🤨"],"k":["one","distrust","scepticism","disapproval","disbelief","surprise"]},"neutral_face":{"n":"Neutral Face","u":["😐"],"k":["indifference","meh",":",""]},"expressionless":{"n":"Expressionless Face","u":["😑"],"k":["indifferent","-","","meh","deadpan"]},"no_mouth":{"n":"Face Without Mouth","u":["😶"],"k":["no","hellokitty"]},"dotted_line_face":{"n":"Dotted Line Face","u":["🫥"],"k":["invisible","lonely","isolation","depression"]},"face_in_clouds":{"n":"Face in Clouds","u":["😶‍🌫️"],"k":["shower","steam","dream"]},"smirk":{"n":"Smirking Face","u":["😏"],"k":["smirk","smile","mean","prank","smug","sarcasm"]},"unamused":{"n":"Unamused Face","u":["😒"],"k":["indifference","bored","straight","serious","sarcasm","unimpressed","skeptical","dubious","side","eye"]},"face_with_rolling_eyes":{"n":"Face with Rolling Eyes","u":["🙄"],"k":["eyeroll","frustrated"]},"grimacing":{"n":"Grimacing Face","u":["😬"],"k":["grimace","teeth"]},"face_exhaling":{"n":"Face Exhaling","u":["😮‍💨"],"k":["relieve","relief","tired","sigh"]},"lying_face":{"n":"Lying Face","u":["🤥"],"k":["lie","pinocchio"]},"shaking_face":{"n":"Shaking Face","u":["🫨"],"k":["dizzy","shock","blurry","earthquake"]},"relieved":{"n":"Relieved Face","u":["😌"],"k":["relaxed","phew","massage","happiness"]},"pensive":{"n":"Pensive Face","u":["😔"],"k":["sad","depressed","upset"]},"sleepy":{"n":"Sleepy Face","u":["😪"],"k":["tired","rest","nap"]},"drooling_face":{"n":"Drooling Face","u":["🤤"],"k":[]},"sleeping":{"n":"Sleeping Face","u":["😴"],"k":["tired","sleepy","night","zzz"]},"mask":{"n":"Face with Medical Mask","u":["😷"],"k":["sick","ill","disease","covid"]},"face_with_thermometer":{"n":"Face with Thermometer","u":["🤒"],"k":["sick","temperature","cold","fever","covid"]},"face_with_head_bandage":{"n":"Face with Head-Bandage","u":["🤕"],"k":["head","bandage","injured","clumsy","hurt"]},"nauseated_face":{"n":"Nauseated Face","u":["🤢"],"k":["vomit","gross","green","sick","throw","up","ill"]},"face_vomiting":{"n":"Face Vomiting","u":["🤮"],"k":["with","open","mouth","sick"]},"sneezing_face":{"n":"Sneezing Face","u":["🤧"],"k":["gesundheit","sneeze","sick","allergy"]},"hot_face":{"n":"Hot Face","u":["🥵"],"k":["feverish","heat","red","sweating"]},"cold_face":{"n":"Cold Face","u":["🥶"],"k":["blue","freezing","frozen","frostbite","icicles"]},"woozy_face":{"n":"Woozy Face","u":["🥴"],"k":["dizzy","intoxicated","tipsy","wavy"]},"dizzy_face":{"n":"Dizzy Face","u":["😵"],"k":["spent","unconscious","xox"]},"face_with_spiral_eyes":{"n":"Face with Spiral Eyes","u":["😵‍💫"],"k":["sick","ill","confused","nauseous","nausea"]},"exploding_head":{"n":"Exploding Head","u":["🤯"],"k":["shocked","face","with","mind","blown"]},"face_with_cowboy_hat":{"n":"Cowboy Hat Face","u":["🤠"],"k":["with","cowgirl"]},"partying_face":{"n":"Partying Face","u":["🥳"],"k":["celebration","woohoo"]},"disguised_face":{"n":"Disguised Face","u":["🥸"],"k":["pretent","brows","glasses","moustache"]},"sunglasses":{"n":"Smiling Face with Sunglasses","u":["😎"],"k":["cool","smile","summer","beach","sunglass"]},"nerd_face":{"n":"Nerd Face","u":["🤓"],"k":["nerdy","geek","dork"]},"face_with_monocle":{"n":"Face with Monocle","u":["🧐"],"k":["stuffy","wealthy"]},"confused":{"n":"Confused Face","u":["😕"],"k":["indifference","huh","weird","hmmm",":/"]},"face_with_diagonal_mouth":{"n":"Face with Diagonal Mouth","u":["🫤"],"k":["skeptic","confuse","frustrated","indifferent"]},"worried":{"n":"Worried Face","u":["😟"],"k":["concern","nervous",":("]},"slightly_frowning_face":{"n":"Slightly Frowning Face","u":["🙁"],"k":["disappointed","sad","upset"]},"white_frowning_face":{"n":"Frowning Face","u":["☹️"],"k":["white","sad","upset","frown"]},"open_mouth":{"n":"Face with Open Mouth","u":["😮"],"k":["surprise","impressed","wow","whoa",":O"]},"hushed":{"n":"Hushed Face","u":["😯"],"k":["woo","shh"]},"astonished":{"n":"Astonished Face","u":["😲"],"k":["xox","surprised","poisoned"]},"flushed":{"n":"Flushed Face","u":["😳"],"k":["blush","shy","flattered"]},"pleading_face":{"n":"Pleading Face","u":["🥺"],"k":["begging","mercy","cry","tears","sad","grievance"]},"face_holding_back_tears":{"n":"Face Holding Back Tears","u":["🥹"],"k":["touched","gratitude","cry"]},"frowning":{"n":"Frowning Face with Open Mouth","u":["😦"],"k":["aw","what"]},"anguished":{"n":"Anguished Face","u":["😧"],"k":["stunned","nervous"]},"fearful":{"n":"Fearful Face","u":["😨"],"k":["scared","terrified","nervous"]},"cold_sweat":{"n":"Anxious Face with Sweat","u":["😰"],"k":["cold","nervous"]},"disappointed_relieved":{"n":"Sad but Relieved Face","u":["😥"],"k":["disappointed","phew","sweat","nervous"]},"cry":{"n":"Crying Face","u":["😢"],"k":["cry","tears","sad","depressed","upset",":'("]},"sob":{"n":"Loudly Crying Face","u":["😭"],"k":["sob","cry","tears","sad","upset","depressed"]},"scream":{"n":"Face Screaming in Fear","u":["😱"],"k":["scream","munch","scared","omg"]},"confounded":{"n":"Confounded Face","u":["😖"],"k":["confused","sick","unwell","oops",":S"]},"persevere":{"n":"Persevering Face","u":["😣"],"k":["persevere","sick","no","upset","oops"]},"disappointed":{"n":"Disappointed Face","u":["😞"],"k":["sad","upset","depressed",":("]},"sweat":{"n":"Face with Cold Sweat","u":["😓"],"k":["downcast","hot","sad","tired","exercise"]},"weary":{"n":"Weary Face","u":["😩"],"k":["tired","sleepy","sad","frustrated","upset"]},"tired_face":{"n":"Tired Face","u":["😫"],"k":["sick","whine","upset","frustrated"]},"yawning_face":{"n":"Yawning Face","u":["🥱"],"k":["tired","sleepy"]},"triumph":{"n":"Face with Look of Triumph","u":["😤"],"k":["steam","from","nose","gas","phew","proud","pride"]},"rage":{"n":"Pouting Face","u":["😡"],"k":["rage","angry","mad","hate","despise"]},"angry":{"n":"Angry Face","u":["😠"],"k":["mad","annoyed","frustrated"]},"face_with_symbols_on_mouth":{"n":"Face with Symbols on Mouth","u":["🤬"],"k":["serious","covering","swearing","cursing","cussing","profanity","expletive"]},"smiling_imp":{"n":"Smiling Face with Horns","u":["😈"],"k":["imp","devil"]},"imp":{"n":"Imp","u":["👿"],"k":["angry","face","with","horns","devil"]},"skull":{"n":"Skull","u":["💀"],"k":["dead","skeleton","creepy","death"]},"skull_and_crossbones":{"n":"Skull and Crossbones","u":["☠️"],"k":["poison","danger","deadly","scary","death","pirate","evil"]},"hankey":{"n":"Pile of Poo","u":["💩"],"k":["hankey","poop","shit","shitface","fail","turd"]},"clown_face":{"n":"Clown Face","u":["🤡"],"k":[]},"japanese_ogre":{"n":"Ogre","u":["👹"],"k":["japanese","monster","red","mask","halloween","scary","creepy","devil","demon"]},"japanese_goblin":{"n":"Goblin","u":["👺"],"k":["japanese","red","evil","mask","monster","scary","creepy"]},"ghost":{"n":"Ghost","u":["👻"],"k":["halloween","spooky","scary"]},"alien":{"n":"Alien","u":["👽"],"k":["UFO","paul","weird","outer","space"]},"space_invader":{"n":"Alien Monster","u":["👾"],"k":["space","invader","game","arcade","play"]},"wave":{"n":"Waving Hand","u":["👋","👋🏻","👋🏼","👋🏽","👋🏾","👋🏿"],"k":["wave","hands","gesture","goodbye","solong","farewell","hello","hi","palm"]},"raised_back_of_hand":{"n":"Raised Back of Hand","u":["🤚","🤚🏻","🤚🏼","🤚🏽","🤚🏾","🤚🏿"],"k":["fingers","backhand"]},"raised_hand_with_fingers_splayed":{"n":"Hand with Fingers Splayed","u":["🖐️","🖐🏻","🖐🏼","🖐🏽","🖐🏾","🖐🏿"],"k":["raised","palm"]},"hand":{"n":"Raised Hand","u":["✋","✋🏻","✋🏼","✋🏽","✋🏾","✋🏿"],"k":["fingers","stop","highfive","high","five","palm","ban"]},"spock-hand":{"n":"Vulcan Salute","u":["🖖","🖖🏻","🖖🏼","🖖🏽","🖖🏾","🖖🏿"],"k":["spock","hand","fingers","star","trek"]},"rightwards_hand":{"n":"Rightwards Hand","u":["🫱","🫱🏻","🫱🏼","🫱🏽","🫱🏾","🫱🏿"],"k":["palm","offer"]},"leftwards_hand":{"n":"Leftwards Hand","u":["🫲","🫲🏻","🫲🏼","🫲🏽","🫲🏾","🫲🏿"],"k":["palm","offer"]},"palm_down_hand":{"n":"Palm Down Hand","u":["🫳","🫳🏻","🫳🏼","🫳🏽","🫳🏾","🫳🏿"],"k":["drop"]},"palm_up_hand":{"n":"Palm Up Hand","u":["🫴","🫴🏻","🫴🏼","🫴🏽","🫴🏾","🫴🏿"],"k":["lift","offer","demand"]},"leftwards_pushing_hand":{"n":"Leftwards Pushing Hand","u":["🫷","🫷🏻","🫷🏼","🫷🏽","🫷🏾","🫷🏿"],"k":["highfive","high","five","pressing","stop"]},"rightwards_pushing_hand":{"n":"Rightwards Pushing Hand","u":["🫸","🫸🏻","🫸🏼","🫸🏽","🫸🏾","🫸🏿"],"k":["highfive","high","five","pressing","stop"]},"ok_hand":{"n":"Ok Hand","u":["👌","👌🏻","👌🏼","👌🏽","👌🏾","👌🏿"],"k":["fingers","limbs","perfect","okay"]},"pinched_fingers":{"n":"Pinched Fingers","u":["🤌","🤌🏻","🤌🏼","🤌🏽","🤌🏾","🤌🏿"],"k":["size","tiny","small"]},"pinching_hand":{"n":"Pinching Hand","u":["🤏","🤏🏻","🤏🏼","🤏🏽","🤏🏾","🤏🏿"],"k":["tiny","small","size"]},"v":{"n":"Victory Hand","u":["✌️","✌🏻","✌🏼","✌🏽","✌🏾","✌🏿"],"k":["v","fingers","ohyeah","peace","two"]},"crossed_fingers":{"n":"Crossed Fingers","u":["🤞","🤞🏻","🤞🏼","🤞🏽","🤞🏾","🤞🏿"],"k":["hand","with","index","and","middle","good","lucky"]},"hand_with_index_finger_and_thumb_crossed":{"n":"Hand with Index Finger and Thumb Crossed","u":["🫰","🫰🏻","🫰🏼","🫰🏽","🫰🏾","🫰🏿"],"k":["heart","love","money","expensive"]},"i_love_you_hand_sign":{"n":"Love-You Gesture","u":["🤟","🤟🏻","🤟🏼","🤟🏽","🤟🏾","🤟🏿"],"k":["i","love","you","hand","sign","fingers"]},"the_horns":{"n":"Sign of the Horns","u":["🤘","🤘🏻","🤘🏼","🤘🏽","🤘🏾","🤘🏿"],"k":["hand","fingers","evil","eye","rock","on"]},"call_me_hand":{"n":"Call Me Hand","u":["🤙","🤙🏻","🤙🏼","🤙🏽","🤙🏾","🤙🏿"],"k":["hands","gesture","shaka"]},"point_left":{"n":"Backhand Index Pointing Left","u":["👈","👈🏻","👈🏼","👈🏽","👈🏾","👈🏿"],"k":["point","direction","fingers","hand"]},"point_right":{"n":"Backhand Index Pointing Right","u":["👉","👉🏻","👉🏼","👉🏽","👉🏾","👉🏿"],"k":["point","fingers","hand","direction"]},"point_up_2":{"n":"Backhand Index Pointing Up","u":["👆","👆🏻","👆🏼","👆🏽","👆🏾","👆🏿"],"k":["point","2","fingers","hand","direction"]},"middle_finger":{"n":"Middle Finger","u":["🖕","🖕🏻","🖕🏼","🖕🏽","🖕🏾","🖕🏿"],"k":["reversed","hand","with","extended","fingers","rude","flipping"]},"point_down":{"n":"Backhand Index Pointing Down","u":["👇","👇🏻","👇🏼","👇🏽","👇🏾","👇🏿"],"k":["point","fingers","hand","direction"]},"point_up":{"n":"Index Pointing Up","u":["☝️","☝🏻","☝🏼","☝🏽","☝🏾","☝🏿"],"k":["point","hand","fingers","direction"]},"index_pointing_at_the_viewer":{"n":"Index Pointing at the Viewer","u":["🫵","🫵🏻","🫵🏼","🫵🏽","🫵🏾","🫵🏿"],"k":["you","recruit"]},"+1":{"n":"Thumbs Up","u":["👍","👍🏻","👍🏼","👍🏽","👍🏾","👍🏿"],"k":["+1","thumbsup","yes","awesome","good","agree","accept","cool","hand","like"]},"-1":{"n":"Thumbs Down","u":["👎","👎🏻","👎🏼","👎🏽","👎🏾","👎🏿"],"k":["-1","thumbsdown","no","dislike","hand"]},"fist":{"n":"Raised Fist","u":["✊","✊🏻","✊🏼","✊🏽","✊🏾","✊🏿"],"k":["fingers","hand","grasp"]},"facepunch":{"n":"Oncoming Fist","u":["👊","👊🏻","👊🏼","👊🏽","👊🏾","👊🏿"],"k":["facepunch","punch","angry","violence","hit","attack","hand"]},"left-facing_fist":{"n":"Left-Facing Fist","u":["🤛","🤛🏻","🤛🏼","🤛🏽","🤛🏾","🤛🏿"],"k":["left","facing","hand","fistbump"]},"right-facing_fist":{"n":"Right-Facing Fist","u":["🤜","🤜🏻","🤜🏼","🤜🏽","🤜🏾","🤜🏿"],"k":["right","facing","hand","fistbump"]},"clap":{"n":"Clapping Hands","u":["👏","👏🏻","👏🏼","👏🏽","👏🏾","👏🏿"],"k":["clap","praise","applause","congrats","yay"]},"raised_hands":{"n":"Raising Hands","u":["🙌","🙌🏻","🙌🏼","🙌🏽","🙌🏾","🙌🏿"],"k":["raised","gesture","hooray","yea","celebration"]},"heart_hands":{"n":"Heart Hands","u":["🫶","🫶🏻","🫶🏼","🫶🏽","🫶🏾","🫶🏿"],"k":["love","appreciation","support"]},"open_hands":{"n":"Open Hands","u":["👐","👐🏻","👐🏼","👐🏽","👐🏾","👐🏿"],"k":["fingers","butterfly"]},"palms_up_together":{"n":"Palms Up Together","u":["🤲","🤲🏻","🤲🏼","🤲🏽","🤲🏾","🤲🏿"],"k":["hands","gesture","cupped","prayer"]},"handshake":{"n":"Handshake","u":["🤝","🤝🏻","🤝🏼","🤝🏽","🤝🏾","🤝🏿"],"k":["agreement","shake"]},"pray":{"n":"Folded Hands","u":["🙏","🙏🏻","🙏🏼","🙏🏽","🙏🏾","🙏🏿"],"k":["pray","please","hope","wish","namaste","highfive","high","five","thank","you","thanks","appreciate"]},"writing_hand":{"n":"Writing Hand","u":["✍️","✍🏻","✍🏼","✍🏽","✍🏾","✍🏿"],"k":["lower","left","ballpoint","pen","stationery","write","compose"]},"nail_care":{"n":"Nail Polish","u":["💅","💅🏻","💅🏼","💅🏽","💅🏾","💅🏿"],"k":["care","beauty","manicure","finger","fashion"]},"selfie":{"n":"Selfie","u":["🤳","🤳🏻","🤳🏼","🤳🏽","🤳🏾","🤳🏿"],"k":["camera","phone"]},"muscle":{"n":"Flexed Biceps","u":["💪","💪🏻","💪🏼","💪🏽","💪🏾","💪🏿"],"k":["muscle","arm","flex","hand","summer","strong"]},"mechanical_arm":{"n":"Mechanical Arm","u":["🦾"],"k":["accessibility"]},"mechanical_leg":{"n":"Mechanical Leg","u":["🦿"],"k":["accessibility"]},"leg":{"n":"Leg","u":["🦵","🦵🏻","🦵🏼","🦵🏽","🦵🏾","🦵🏿"],"k":["kick","limb"]},"foot":{"n":"Foot","u":["🦶","🦶🏻","🦶🏼","🦶🏽","🦶🏾","🦶🏿"],"k":["kick","stomp"]},"ear":{"n":"Ear","u":["👂","👂🏻","👂🏼","👂🏽","👂🏾","👂🏿"],"k":["face","hear","sound","listen"]},"ear_with_hearing_aid":{"n":"Ear with Hearing Aid","u":["🦻","🦻🏻","🦻🏼","🦻🏽","🦻🏾","🦻🏿"],"k":["accessibility"]},"nose":{"n":"Nose","u":["👃","👃🏻","👃🏼","👃🏽","👃🏾","👃🏿"],"k":["smell","sniff"]},"brain":{"n":"Brain","u":["🧠"],"k":["smart","intelligent"]},"anatomical_heart":{"n":"Anatomical Heart","u":["🫀"],"k":["health","heartbeat"]},"lungs":{"n":"Lungs","u":["🫁"],"k":["breathe"]},"tooth":{"n":"Tooth","u":["🦷"],"k":["teeth","dentist"]},"bone":{"n":"Bone","u":["🦴"],"k":["skeleton"]},"eyes":{"n":"Eyes","u":["👀"],"k":["look","watch","stalk","peek","see"]},"eye":{"n":"Eye","u":["👁️"],"k":["face","look","see","watch","stare"]},"tongue":{"n":"Tongue","u":["👅"],"k":["mouth","playful"]},"lips":{"n":"Mouth","u":["👄"],"k":["lips","kiss"]},"biting_lip":{"n":"Biting Lip","u":["🫦"],"k":["flirt","sexy","pain","worry"]},"baby":{"n":"Baby","u":["👶","👶🏻","👶🏼","👶🏽","👶🏾","👶🏿"],"k":["child","boy","girl","toddler"]},"child":{"n":"Child","u":["🧒","🧒🏻","🧒🏼","🧒🏽","🧒🏾","🧒🏿"],"k":["gender","neutral","young"]},"boy":{"n":"Boy","u":["👦","👦🏻","👦🏼","👦🏽","👦🏾","👦🏿"],"k":["man","male","guy","teenager"]},"girl":{"n":"Girl","u":["👧","👧🏻","👧🏼","👧🏽","👧🏾","👧🏿"],"k":["female","woman","teenager"]},"adult":{"n":"Adult","u":["🧑","🧑🏻","🧑🏼","🧑🏽","🧑🏾","🧑🏿"],"k":["person","gender","neutral"]},"person_with_blond_hair":{"n":"Person Blond Hair","u":["👱","👱🏻","👱🏼","👱🏽","👱🏾","👱🏿"],"k":["with","hairstyle"]},"man":{"n":"Man","u":["👨","👨🏻","👨🏼","👨🏽","👨🏾","👨🏿"],"k":["mustache","father","dad","guy","classy","sir","moustache"]},"bearded_person":{"n":"Person Beard","u":["🧔","🧔🏻","🧔🏼","🧔🏽","🧔🏾","🧔🏿"],"k":["bearded","man","bewhiskered"]},"man_with_beard":{"n":"Man: Beard","u":["🧔‍♂️","🧔🏻‍♂️","🧔🏼‍♂️","🧔🏽‍♂️","🧔🏾‍♂️","🧔🏿‍♂️"],"k":["man","with","facial","hair"]},"woman_with_beard":{"n":"Woman: Beard","u":["🧔‍♀️","🧔🏻‍♀️","🧔🏼‍♀️","🧔🏽‍♀️","🧔🏾‍♀️","🧔🏿‍♀️"],"k":["woman","with","facial","hair"]},"red_haired_man":{"n":"Man: Red Hair","u":["👨‍🦰","👨🏻‍🦰","👨🏼‍🦰","👨🏽‍🦰","👨🏾‍🦰","👨🏿‍🦰"],"k":["haired","man","hairstyle"]},"curly_haired_man":{"n":"Man: Curly Hair","u":["👨‍🦱","👨🏻‍🦱","👨🏼‍🦱","👨🏽‍🦱","👨🏾‍🦱","👨🏿‍🦱"],"k":["haired","man","hairstyle"]},"white_haired_man":{"n":"Man: White Hair","u":["👨‍🦳","👨🏻‍🦳","👨🏼‍🦳","👨🏽‍🦳","👨🏾‍🦳","👨🏿‍🦳"],"k":["haired","man","old","elder"]},"bald_man":{"n":"Man: Bald","u":["👨‍🦲","👨🏻‍🦲","👨🏼‍🦲","👨🏽‍🦲","👨🏾‍🦲","👨🏿‍🦲"],"k":["man","hairless"]},"woman":{"n":"Woman","u":["👩","👩🏻","👩🏼","👩🏽","👩🏾","👩🏿"],"k":["female","girls","lady"]},"red_haired_woman":{"n":"Woman: Red Hair","u":["👩‍🦰","👩🏻‍🦰","👩🏼‍🦰","👩🏽‍🦰","👩🏾‍🦰","👩🏿‍🦰"],"k":["haired","woman","hairstyle"]},"red_haired_person":{"n":"Person: Red Hair","u":["🧑‍🦰","🧑🏻‍🦰","🧑🏼‍🦰","🧑🏽‍🦰","🧑🏾‍🦰","🧑🏿‍🦰"],"k":["haired","person","hairstyle"]},"curly_haired_woman":{"n":"Woman: Curly Hair","u":["👩‍🦱","👩🏻‍🦱","👩🏼‍🦱","👩🏽‍🦱","👩🏾‍🦱","👩🏿‍🦱"],"k":["haired","woman","hairstyle"]},"curly_haired_person":{"n":"Person: Curly Hair","u":["🧑‍🦱","🧑🏻‍🦱","🧑🏼‍🦱","🧑🏽‍🦱","🧑🏾‍🦱","🧑🏿‍🦱"],"k":["haired","person","hairstyle"]},"white_haired_woman":{"n":"Woman: White Hair","u":["👩‍🦳","👩🏻‍🦳","👩🏼‍🦳","👩🏽‍🦳","👩🏾‍🦳","👩🏿‍🦳"],"k":["haired","woman","old","elder"]},"white_haired_person":{"n":"Person: White Hair","u":["🧑‍🦳","🧑🏻‍🦳","🧑🏼‍🦳","🧑🏽‍🦳","🧑🏾‍🦳","🧑🏿‍🦳"],"k":["haired","person","elder","old"]},"bald_woman":{"n":"Woman: Bald","u":["👩‍🦲","👩🏻‍🦲","👩🏼‍🦲","👩🏽‍🦲","👩🏾‍🦲","👩🏿‍🦲"],"k":["woman","hairless"]},"bald_person":{"n":"Person: Bald","u":["🧑‍🦲","🧑🏻‍🦲","🧑🏼‍🦲","🧑🏽‍🦲","🧑🏾‍🦲","🧑🏿‍🦲"],"k":["person","hairless"]},"blond-haired-woman":{"n":"Woman: Blond Hair","u":["👱‍♀️","👱🏻‍♀️","👱🏼‍♀️","👱🏽‍♀️","👱🏾‍♀️","👱🏿‍♀️"],"k":["haired-woman","woman","female","girl","blonde","person"]},"blond-haired-man":{"n":"Man: Blond Hair","u":["👱‍♂️","👱🏻‍♂️","👱🏼‍♂️","👱🏽‍♂️","👱🏾‍♂️","👱🏿‍♂️"],"k":["haired-man","man","male","boy","blonde","guy","person"]},"older_adult":{"n":"Older Adult","u":["🧓","🧓🏻","🧓🏼","🧓🏽","🧓🏾","🧓🏿"],"k":["person","human","elder","senior","gender","neutral"]},"older_man":{"n":"Old Man","u":["👴","👴🏻","👴🏼","👴🏽","👴🏾","👴🏿"],"k":["older","human","male","men","elder","senior"]},"older_woman":{"n":"Old Woman","u":["👵","👵🏻","👵🏼","👵🏽","👵🏾","👵🏿"],"k":["older","human","female","women","lady","elder","senior"]},"person_frowning":{"n":"Person Frowning","u":["🙍","🙍🏻","🙍🏼","🙍🏽","🙍🏾","🙍🏿"],"k":["worried"]},"man-frowning":{"n":"Man Frowning","u":["🙍‍♂️","🙍🏻‍♂️","🙍🏼‍♂️","🙍🏽‍♂️","🙍🏾‍♂️","🙍🏿‍♂️"],"k":["male","boy","sad","depressed","discouraged","unhappy"]},"woman-frowning":{"n":"Woman Frowning","u":["🙍‍♀️","🙍🏻‍♀️","🙍🏼‍♀️","🙍🏽‍♀️","🙍🏾‍♀️","🙍🏿‍♀️"],"k":["female","girl","sad","depressed","discouraged","unhappy"]},"person_with_pouting_face":{"n":"Person Pouting","u":["🙎","🙎🏻","🙎🏼","🙎🏽","🙎🏾","🙎🏿"],"k":["with","face","upset"]},"man-pouting":{"n":"Man Pouting","u":["🙎‍♂️","🙎🏻‍♂️","🙎🏼‍♂️","🙎🏽‍♂️","🙎🏾‍♂️","🙎🏿‍♂️"],"k":["male","boy"]},"woman-pouting":{"n":"Woman Pouting","u":["🙎‍♀️","🙎🏻‍♀️","🙎🏼‍♀️","🙎🏽‍♀️","🙎🏾‍♀️","🙎🏿‍♀️"],"k":["female","girl"]},"no_good":{"n":"Person Gesturing No","u":["🙅","🙅🏻","🙅🏼","🙅🏽","🙅🏾","🙅🏿"],"k":["good","decline"]},"man-gesturing-no":{"n":"Man Gesturing No","u":["🙅‍♂️","🙅🏻‍♂️","🙅🏼‍♂️","🙅🏽‍♂️","🙅🏾‍♂️","🙅🏿‍♂️"],"k":["gesturing-no","male","boy","nope"]},"woman-gesturing-no":{"n":"Woman Gesturing No","u":["🙅‍♀️","🙅🏻‍♀️","🙅🏼‍♀️","🙅🏽‍♀️","🙅🏾‍♀️","🙅🏿‍♀️"],"k":["gesturing-no","female","girl","nope"]},"ok_woman":{"n":"Person Gesturing Ok","u":["🙆","🙆🏻","🙆🏼","🙆🏽","🙆🏾","🙆🏿"],"k":["woman","agree"]},"man-gesturing-ok":{"n":"Man Gesturing Ok","u":["🙆‍♂️","🙆🏻‍♂️","🙆🏼‍♂️","🙆🏽‍♂️","🙆🏾‍♂️","🙆🏿‍♂️"],"k":["gesturing-ok","men","boy","male","blue","human"]},"woman-gesturing-ok":{"n":"Woman Gesturing Ok","u":["🙆‍♀️","🙆🏻‍♀️","🙆🏼‍♀️","🙆🏽‍♀️","🙆🏾‍♀️","🙆🏿‍♀️"],"k":["gesturing-ok","women","girl","female","pink","human"]},"information_desk_person":{"n":"Person Tipping Hand","u":["💁","💁🏻","💁🏼","💁🏽","💁🏾","💁🏿"],"k":["information","desk"]},"man-tipping-hand":{"n":"Man Tipping Hand","u":["💁‍♂️","💁🏻‍♂️","💁🏼‍♂️","💁🏽‍♂️","💁🏾‍♂️","💁🏿‍♂️"],"k":["tipping-hand","male","boy","human","information"]},"woman-tipping-hand":{"n":"Woman Tipping Hand","u":["💁‍♀️","💁🏻‍♀️","💁🏼‍♀️","💁🏽‍♀️","💁🏾‍♀️","💁🏿‍♀️"],"k":["tipping-hand","female","girl","human","information"]},"raising_hand":{"n":"Person Raising Hand","u":["🙋","🙋🏻","🙋🏼","🙋🏽","🙋🏾","🙋🏿"],"k":["question"]},"man-raising-hand":{"n":"Man Raising Hand","u":["🙋‍♂️","🙋🏻‍♂️","🙋🏼‍♂️","🙋🏽‍♂️","🙋🏾‍♂️","🙋🏿‍♂️"],"k":["raising-hand","male","boy"]},"woman-raising-hand":{"n":"Woman Raising Hand","u":["🙋‍♀️","🙋🏻‍♀️","🙋🏼‍♀️","🙋🏽‍♀️","🙋🏾‍♀️","🙋🏿‍♀️"],"k":["raising-hand","female","girl"]},"deaf_person":{"n":"Deaf Person","u":["🧏","🧏🏻","🧏🏼","🧏🏽","🧏🏾","🧏🏿"],"k":["accessibility"]},"deaf_man":{"n":"Deaf Man","u":["🧏‍♂️","🧏🏻‍♂️","🧏🏼‍♂️","🧏🏽‍♂️","🧏🏾‍♂️","🧏🏿‍♂️"],"k":["accessibility"]},"deaf_woman":{"n":"Deaf Woman","u":["🧏‍♀️","🧏🏻‍♀️","🧏🏼‍♀️","🧏🏽‍♀️","🧏🏾‍♀️","🧏🏿‍♀️"],"k":["accessibility"]},"bow":{"n":"Person Bowing","u":["🙇","🙇🏻","🙇🏼","🙇🏽","🙇🏾","🙇🏿"],"k":["bow","respectiful"]},"man-bowing":{"n":"Man Bowing","u":["🙇‍♂️","🙇🏻‍♂️","🙇🏼‍♂️","🙇🏽‍♂️","🙇🏾‍♂️","🙇🏿‍♂️"],"k":["male","boy"]},"woman-bowing":{"n":"Woman Bowing","u":["🙇‍♀️","🙇🏻‍♀️","🙇🏼‍♀️","🙇🏽‍♀️","🙇🏾‍♀️","🙇🏿‍♀️"],"k":["female","girl"]},"face_palm":{"n":"Face Palm","u":["🤦","🤦🏻","🤦🏼","🤦🏽","🤦🏾","🤦🏿"],"k":["person","facepalming","disappointed"]},"man-facepalming":{"n":"Man Facepalming","u":["🤦‍♂️","🤦🏻‍♂️","🤦🏼‍♂️","🤦🏽‍♂️","🤦🏾‍♂️","🤦🏿‍♂️"],"k":["male","boy","disbelief"]},"woman-facepalming":{"n":"Woman Facepalming","u":["🤦‍♀️","🤦🏻‍♀️","🤦🏼‍♀️","🤦🏽‍♀️","🤦🏾‍♀️","🤦🏿‍♀️"],"k":["female","girl","disbelief"]},"shrug":{"n":"Shrug","u":["🤷","🤷🏻","🤷🏼","🤷🏽","🤷🏾","🤷🏿"],"k":["person","shrugging","regardless"]},"man-shrugging":{"n":"Man Shrugging","u":["🤷‍♂️","🤷🏻‍♂️","🤷🏼‍♂️","🤷🏽‍♂️","🤷🏾‍♂️","🤷🏿‍♂️"],"k":["male","boy","confused","indifferent","doubt"]},"woman-shrugging":{"n":"Woman Shrugging","u":["🤷‍♀️","🤷🏻‍♀️","🤷🏼‍♀️","🤷🏽‍♀️","🤷🏾‍♀️","🤷🏿‍♀️"],"k":["female","girl","confused","indifferent","doubt"]},"health_worker":{"n":"Health Worker","u":["🧑‍⚕️","🧑🏻‍⚕️","🧑🏼‍⚕️","🧑🏽‍⚕️","🧑🏾‍⚕️","🧑🏿‍⚕️"],"k":["hospital"]},"male-doctor":{"n":"Man Health Worker","u":["👨‍⚕️","👨🏻‍⚕️","👨🏼‍⚕️","👨🏽‍⚕️","👨🏾‍⚕️","👨🏿‍⚕️"],"k":["male","doctor","nurse","therapist","healthcare","human"]},"female-doctor":{"n":"Woman Health Worker","u":["👩‍⚕️","👩🏻‍⚕️","👩🏼‍⚕️","👩🏽‍⚕️","👩🏾‍⚕️","👩🏿‍⚕️"],"k":["female","doctor","nurse","therapist","healthcare","human"]},"student":{"n":"Student","u":["🧑‍🎓","🧑🏻‍🎓","🧑🏼‍🎓","🧑🏽‍🎓","🧑🏾‍🎓","🧑🏿‍🎓"],"k":["learn"]},"male-student":{"n":"Man Student","u":["👨‍🎓","👨🏻‍🎓","👨🏼‍🎓","👨🏽‍🎓","👨🏾‍🎓","👨🏿‍🎓"],"k":["male","graduate","human"]},"female-student":{"n":"Woman Student","u":["👩‍🎓","👩🏻‍🎓","👩🏼‍🎓","👩🏽‍🎓","👩🏾‍🎓","👩🏿‍🎓"],"k":["female","graduate","human"]},"teacher":{"n":"Teacher","u":["🧑‍🏫","🧑🏻‍🏫","🧑🏼‍🏫","🧑🏽‍🏫","🧑🏾‍🏫","🧑🏿‍🏫"],"k":["professor"]},"male-teacher":{"n":"Man Teacher","u":["👨‍🏫","👨🏻‍🏫","👨🏼‍🏫","👨🏽‍🏫","👨🏾‍🏫","👨🏿‍🏫"],"k":["male","instructor","professor","human"]},"female-teacher":{"n":"Woman Teacher","u":["👩‍🏫","👩🏻‍🏫","👩🏼‍🏫","👩🏽‍🏫","👩🏾‍🏫","👩🏿‍🏫"],"k":["female","instructor","professor","human"]},"judge":{"n":"Judge","u":["🧑‍⚖️","🧑🏻‍⚖️","🧑🏼‍⚖️","🧑🏽‍⚖️","🧑🏾‍⚖️","🧑🏿‍⚖️"],"k":["law"]},"male-judge":{"n":"Man Judge","u":["👨‍⚖️","👨🏻‍⚖️","👨🏼‍⚖️","👨🏽‍⚖️","👨🏾‍⚖️","👨🏿‍⚖️"],"k":["male","justice","court","human"]},"female-judge":{"n":"Woman Judge","u":["👩‍⚖️","👩🏻‍⚖️","👩🏼‍⚖️","👩🏽‍⚖️","👩🏾‍⚖️","👩🏿‍⚖️"],"k":["female","justice","court","human"]},"farmer":{"n":"Farmer","u":["🧑‍🌾","🧑🏻‍🌾","🧑🏼‍🌾","🧑🏽‍🌾","🧑🏾‍🌾","🧑🏿‍🌾"],"k":["crops"]},"male-farmer":{"n":"Man Farmer","u":["👨‍🌾","👨🏻‍🌾","👨🏼‍🌾","👨🏽‍🌾","👨🏾‍🌾","👨🏿‍🌾"],"k":["male","rancher","gardener","human"]},"female-farmer":{"n":"Woman Farmer","u":["👩‍🌾","👩🏻‍🌾","👩🏼‍🌾","👩🏽‍🌾","👩🏾‍🌾","👩🏿‍🌾"],"k":["female","rancher","gardener","human"]},"cook":{"n":"Cook","u":["🧑‍🍳","🧑🏻‍🍳","🧑🏼‍🍳","🧑🏽‍🍳","🧑🏾‍🍳","🧑🏿‍🍳"],"k":["food","kitchen","culinary"]},"male-cook":{"n":"Man Cook","u":["👨‍🍳","👨🏻‍🍳","👨🏼‍🍳","👨🏽‍🍳","👨🏾‍🍳","👨🏿‍🍳"],"k":["male","chef","human"]},"female-cook":{"n":"Woman Cook","u":["👩‍🍳","👩🏻‍🍳","👩🏼‍🍳","👩🏽‍🍳","👩🏾‍🍳","👩🏿‍🍳"],"k":["female","chef","human"]},"mechanic":{"n":"Mechanic","u":["🧑‍🔧","🧑🏻‍🔧","🧑🏼‍🔧","🧑🏽‍🔧","🧑🏾‍🔧","🧑🏿‍🔧"],"k":["worker","technician"]},"male-mechanic":{"n":"Man Mechanic","u":["👨‍🔧","👨🏻‍🔧","👨🏼‍🔧","👨🏽‍🔧","👨🏾‍🔧","👨🏿‍🔧"],"k":["male","plumber","human","wrench"]},"female-mechanic":{"n":"Woman Mechanic","u":["👩‍🔧","👩🏻‍🔧","👩🏼‍🔧","👩🏽‍🔧","👩🏾‍🔧","👩🏿‍🔧"],"k":["female","plumber","human","wrench"]},"factory_worker":{"n":"Factory Worker","u":["🧑‍🏭","🧑🏻‍🏭","🧑🏼‍🏭","🧑🏽‍🏭","🧑🏾‍🏭","🧑🏿‍🏭"],"k":["labor"]},"male-factory-worker":{"n":"Man Factory Worker","u":["👨‍🏭","👨🏻‍🏭","👨🏼‍🏭","👨🏽‍🏭","👨🏾‍🏭","👨🏿‍🏭"],"k":["male","factory-worker","assembly","industrial","human"]},"female-factory-worker":{"n":"Woman Factory Worker","u":["👩‍🏭","👩🏻‍🏭","👩🏼‍🏭","👩🏽‍🏭","👩🏾‍🏭","👩🏿‍🏭"],"k":["female","factory-worker","assembly","industrial","human"]},"office_worker":{"n":"Office Worker","u":["🧑‍💼","🧑🏻‍💼","🧑🏼‍💼","🧑🏽‍💼","🧑🏾‍💼","🧑🏿‍💼"],"k":["business"]},"male-office-worker":{"n":"Man Office Worker","u":["👨‍💼","👨🏻‍💼","👨🏼‍💼","👨🏽‍💼","👨🏾‍💼","👨🏿‍💼"],"k":["male","office-worker","business","manager","human"]},"female-office-worker":{"n":"Woman Office Worker","u":["👩‍💼","👩🏻‍💼","👩🏼‍💼","👩🏽‍💼","👩🏾‍💼","👩🏿‍💼"],"k":["female","office-worker","business","manager","human"]},"scientist":{"n":"Scientist","u":["🧑‍🔬","🧑🏻‍🔬","🧑🏼‍🔬","🧑🏽‍🔬","🧑🏾‍🔬","🧑🏿‍🔬"],"k":["chemistry"]},"male-scientist":{"n":"Man Scientist","u":["👨‍🔬","👨🏻‍🔬","👨🏼‍🔬","👨🏽‍🔬","👨🏾‍🔬","👨🏿‍🔬"],"k":["male","biologist","chemist","engineer","physicist","human"]},"female-scientist":{"n":"Woman Scientist","u":["👩‍🔬","👩🏻‍🔬","👩🏼‍🔬","👩🏽‍🔬","👩🏾‍🔬","👩🏿‍🔬"],"k":["female","biologist","chemist","engineer","physicist","human"]},"technologist":{"n":"Technologist","u":["🧑‍💻","🧑🏻‍💻","🧑🏼‍💻","🧑🏽‍💻","🧑🏾‍💻","🧑🏿‍💻"],"k":["computer"]},"male-technologist":{"n":"Man Technologist","u":["👨‍💻","👨🏻‍💻","👨🏼‍💻","👨🏽‍💻","👨🏾‍💻","👨🏿‍💻"],"k":["male","coder","developer","engineer","programmer","software","human","laptop","computer"]},"female-technologist":{"n":"Woman Technologist","u":["👩‍💻","👩🏻‍💻","👩🏼‍💻","👩🏽‍💻","👩🏾‍💻","👩🏿‍💻"],"k":["female","coder","developer","engineer","programmer","software","human","laptop","computer"]},"singer":{"n":"Singer","u":["🧑‍🎤","🧑🏻‍🎤","🧑🏼‍🎤","🧑🏽‍🎤","🧑🏾‍🎤","🧑🏿‍🎤"],"k":["song","artist","performer"]},"male-singer":{"n":"Man Singer","u":["👨‍🎤","👨🏻‍🎤","👨🏼‍🎤","👨🏽‍🎤","👨🏾‍🎤","👨🏿‍🎤"],"k":["male","rockstar","entertainer","human"]},"female-singer":{"n":"Woman Singer","u":["👩‍🎤","👩🏻‍🎤","👩🏼‍🎤","👩🏽‍🎤","👩🏾‍🎤","👩🏿‍🎤"],"k":["female","rockstar","entertainer","human"]},"artist":{"n":"Artist","u":["🧑‍🎨","🧑🏻‍🎨","🧑🏼‍🎨","🧑🏽‍🎨","🧑🏾‍🎨","🧑🏿‍🎨"],"k":["painting","draw","creativity"]},"male-artist":{"n":"Man Artist","u":["👨‍🎨","👨🏻‍🎨","👨🏼‍🎨","👨🏽‍🎨","👨🏾‍🎨","👨🏿‍🎨"],"k":["male","painter","human"]},"female-artist":{"n":"Woman Artist","u":["👩‍🎨","👩🏻‍🎨","👩🏼‍🎨","👩🏽‍🎨","👩🏾‍🎨","👩🏿‍🎨"],"k":["female","painter","human"]},"pilot":{"n":"Pilot","u":["🧑‍✈️","🧑🏻‍✈️","🧑🏼‍✈️","🧑🏽‍✈️","🧑🏾‍✈️","🧑🏿‍✈️"],"k":["fly","plane","airplane"]},"male-pilot":{"n":"Man Pilot","u":["👨‍✈️","👨🏻‍✈️","👨🏼‍✈️","👨🏽‍✈️","👨🏾‍✈️","👨🏿‍✈️"],"k":["male","aviator","plane","human"]},"female-pilot":{"n":"Woman Pilot","u":["👩‍✈️","👩🏻‍✈️","👩🏼‍✈️","👩🏽‍✈️","👩🏾‍✈️","👩🏿‍✈️"],"k":["female","aviator","plane","human"]},"astronaut":{"n":"Astronaut","u":["🧑‍🚀","🧑🏻‍🚀","🧑🏼‍🚀","🧑🏽‍🚀","🧑🏾‍🚀","🧑🏿‍🚀"],"k":["outerspace"]},"male-astronaut":{"n":"Man Astronaut","u":["👨‍🚀","👨🏻‍🚀","👨🏼‍🚀","👨🏽‍🚀","👨🏾‍🚀","👨🏿‍🚀"],"k":["male","space","rocket","human"]},"female-astronaut":{"n":"Woman Astronaut","u":["👩‍🚀","👩🏻‍🚀","👩🏼‍🚀","👩🏽‍🚀","👩🏾‍🚀","👩🏿‍🚀"],"k":["female","space","rocket","human"]},"firefighter":{"n":"Firefighter","u":["🧑‍🚒","🧑🏻‍🚒","🧑🏼‍🚒","🧑🏽‍🚒","🧑🏾‍🚒","🧑🏿‍🚒"],"k":["fire"]},"male-firefighter":{"n":"Man Firefighter","u":["👨‍🚒","👨🏻‍🚒","👨🏼‍🚒","👨🏽‍🚒","👨🏾‍🚒","👨🏿‍🚒"],"k":["male","fireman","human"]},"female-firefighter":{"n":"Woman Firefighter","u":["👩‍🚒","👩🏻‍🚒","👩🏼‍🚒","👩🏽‍🚒","👩🏾‍🚒","👩🏿‍🚒"],"k":["female","fireman","human"]},"cop":{"n":"Police Officer","u":["👮","👮🏻","👮🏼","👮🏽","👮🏾","👮🏿"],"k":["cop"]},"male-police-officer":{"n":"Man Police Officer","u":["👮‍♂️","👮🏻‍♂️","👮🏼‍♂️","👮🏽‍♂️","👮🏾‍♂️","👮🏿‍♂️"],"k":["male","police-officer","law","legal","enforcement","arrest","911"]},"female-police-officer":{"n":"Woman Police Officer","u":["👮‍♀️","👮🏻‍♀️","👮🏼‍♀️","👮🏽‍♀️","👮🏾‍♀️","👮🏿‍♀️"],"k":["female","police-officer","law","legal","enforcement","arrest","911"]},"sleuth_or_spy":{"n":"Detective","u":["🕵️","🕵🏻","🕵🏼","🕵🏽","🕵🏾","🕵🏿"],"k":["sleuth","or","spy","human"]},"male-detective":{"n":"Man Detective","u":["🕵️‍♂️","🕵🏻‍♂️","🕵🏼‍♂️","🕵🏽‍♂️","🕵🏾‍♂️","🕵🏿‍♂️"],"k":["male","crime"]},"female-detective":{"n":"Woman Detective","u":["🕵️‍♀️","🕵🏻‍♀️","🕵🏼‍♀️","🕵🏽‍♀️","🕵🏾‍♀️","🕵🏿‍♀️"],"k":["female","human","spy"]},"guardsman":{"n":"Guard","u":["💂","💂🏻","💂🏼","💂🏽","💂🏾","💂🏿"],"k":["guardsman","protect"]},"male-guard":{"n":"Man Guard","u":["💂‍♂️","💂🏻‍♂️","💂🏼‍♂️","💂🏽‍♂️","💂🏾‍♂️","💂🏿‍♂️"],"k":["male","uk","gb","british","guy","royal"]},"female-guard":{"n":"Woman Guard","u":["💂‍♀️","💂🏻‍♀️","💂🏼‍♀️","💂🏽‍♀️","💂🏾‍♀️","💂🏿‍♀️"],"k":["female","uk","gb","british","royal"]},"ninja":{"n":"Ninja","u":["🥷","🥷🏻","🥷🏼","🥷🏽","🥷🏾","🥷🏿"],"k":["ninjutsu","skills","japanese"]},"construction_worker":{"n":"Construction Worker","u":["👷","👷🏻","👷🏼","👷🏽","👷🏾","👷🏿"],"k":["labor","build"]},"male-construction-worker":{"n":"Man Construction Worker","u":["👷‍♂️","👷🏻‍♂️","👷🏼‍♂️","👷🏽‍♂️","👷🏾‍♂️","👷🏿‍♂️"],"k":["male","construction-worker","human","wip","guy","build","labor"]},"female-construction-worker":{"n":"Woman Construction Worker","u":["👷‍♀️","👷🏻‍♀️","👷🏼‍♀️","👷🏽‍♀️","👷🏾‍♀️","👷🏿‍♀️"],"k":["female","construction-worker","human","wip","build","labor"]},"person_with_crown":{"n":"Person with Crown","u":["🫅","🫅🏻","🫅🏼","🫅🏽","🫅🏾","🫅🏿"],"k":["royalty","power"]},"prince":{"n":"Prince","u":["🤴","🤴🏻","🤴🏼","🤴🏽","🤴🏾","🤴🏿"],"k":["boy","man","male","crown","royal","king"]},"princess":{"n":"Princess","u":["👸","👸🏻","👸🏼","👸🏽","👸🏾","👸🏿"],"k":["girl","woman","female","blond","crown","royal","queen"]},"man_with_turban":{"n":"Man with Turban","u":["👳","👳🏻","👳🏼","👳🏽","👳🏾","👳🏿"],"k":["person","wearing","headdress"]},"man-wearing-turban":{"n":"Man Wearing Turban","u":["👳‍♂️","👳🏻‍♂️","👳🏼‍♂️","👳🏽‍♂️","👳🏾‍♂️","👳🏿‍♂️"],"k":["wearing-turban","male","indian","hinduism","arabs"]},"woman-wearing-turban":{"n":"Woman Wearing Turban","u":["👳‍♀️","👳🏻‍♀️","👳🏼‍♀️","👳🏽‍♀️","👳🏾‍♀️","👳🏿‍♀️"],"k":["wearing-turban","female","indian","hinduism","arabs"]},"man_with_gua_pi_mao":{"n":"Man with Gua Pi Mao","u":["👲","👲🏻","👲🏼","👲🏽","👲🏾","👲🏿"],"k":["skullcap","male","boy","chinese"]},"person_with_headscarf":{"n":"Woman with Headscarf","u":["🧕","🧕🏻","🧕🏼","🧕🏽","🧕🏾","🧕🏿"],"k":["person","female","hijab","mantilla","tichel"]},"person_in_tuxedo":{"n":"Man in Tuxedo","u":["🤵","🤵🏻","🤵🏼","🤵🏽","🤵🏾","🤵🏿"],"k":["person","couple","marriage","wedding","groom"]},"man_in_tuxedo":{"n":"Man in Tuxedo","u":["🤵‍♂️","🤵🏻‍♂️","🤵🏼‍♂️","🤵🏽‍♂️","🤵🏾‍♂️","🤵🏿‍♂️"],"k":["formal","fashion"]},"woman_in_tuxedo":{"n":"Woman in Tuxedo","u":["🤵‍♀️","🤵🏻‍♀️","🤵🏼‍♀️","🤵🏽‍♀️","🤵🏾‍♀️","🤵🏿‍♀️"],"k":["formal","fashion"]},"bride_with_veil":{"n":"Bride with Veil","u":["👰","👰🏻","👰🏼","👰🏽","👰🏾","👰🏿"],"k":["couple","marriage","wedding","woman"]},"man_with_veil":{"n":"Man with Veil","u":["👰‍♂️","👰🏻‍♂️","👰🏼‍♂️","👰🏽‍♂️","👰🏾‍♂️","👰🏿‍♂️"],"k":["wedding","marriage"]},"woman_with_veil":{"n":"Woman with Veil","u":["👰‍♀️","👰🏻‍♀️","👰🏼‍♀️","👰🏽‍♀️","👰🏾‍♀️","👰🏿‍♀️"],"k":["wedding","marriage"]},"pregnant_woman":{"n":"Pregnant Woman","u":["🤰","🤰🏻","🤰🏼","🤰🏽","🤰🏾","🤰🏿"],"k":["baby"]},"pregnant_man":{"n":"Pregnant Man","u":["🫃","🫃🏻","🫃🏼","🫃🏽","🫃🏾","🫃🏿"],"k":["baby","belly"]},"pregnant_person":{"n":"Pregnant Person","u":["🫄","🫄🏻","🫄🏼","🫄🏽","🫄🏾","🫄🏿"],"k":["baby","belly"]},"breast-feeding":{"n":"Breast-Feeding","u":["🤱","🤱🏻","🤱🏼","🤱🏽","🤱🏾","🤱🏿"],"k":["breast","feeding","nursing","baby"]},"woman_feeding_baby":{"n":"Woman Feeding Baby","u":["👩‍🍼","👩🏻‍🍼","👩🏼‍🍼","👩🏽‍🍼","👩🏾‍🍼","👩🏿‍🍼"],"k":["birth","food"]},"man_feeding_baby":{"n":"Man Feeding Baby","u":["👨‍🍼","👨🏻‍🍼","👨🏼‍🍼","👨🏽‍🍼","👨🏾‍🍼","👨🏿‍🍼"],"k":["birth","food"]},"person_feeding_baby":{"n":"Person Feeding Baby","u":["🧑‍🍼","🧑🏻‍🍼","🧑🏼‍🍼","🧑🏽‍🍼","🧑🏾‍🍼","🧑🏿‍🍼"],"k":["birth","food"]},"angel":{"n":"Baby Angel","u":["👼","👼🏻","👼🏼","👼🏽","👼🏾","👼🏿"],"k":["heaven","wings","halo"]},"santa":{"n":"Santa Claus","u":["🎅","🎅🏻","🎅🏼","🎅🏽","🎅🏾","🎅🏿"],"k":["festival","man","male","xmas","father","christmas"]},"mrs_claus":{"n":"Mrs. Claus","u":["🤶","🤶🏻","🤶🏼","🤶🏽","🤶🏾","🤶🏿"],"k":["mrs","mother","christmas","woman","female","xmas"]},"mx_claus":{"n":"Mx Claus","u":["🧑‍🎄","🧑🏻‍🎄","🧑🏼‍🎄","🧑🏽‍🎄","🧑🏾‍🎄","🧑🏿‍🎄"],"k":["christmas"]},"superhero":{"n":"Superhero","u":["🦸","🦸🏻","🦸🏼","🦸🏽","🦸🏾","🦸🏿"],"k":["marvel"]},"male_superhero":{"n":"Man Superhero","u":["🦸‍♂️","🦸🏻‍♂️","🦸🏼‍♂️","🦸🏽‍♂️","🦸🏾‍♂️","🦸🏿‍♂️"],"k":["male","good","hero","superpowers"]},"female_superhero":{"n":"Woman Superhero","u":["🦸‍♀️","🦸🏻‍♀️","🦸🏼‍♀️","🦸🏽‍♀️","🦸🏾‍♀️","🦸🏿‍♀️"],"k":["female","good","heroine","superpowers"]},"supervillain":{"n":"Supervillain","u":["🦹","🦹🏻","🦹🏼","🦹🏽","🦹🏾","🦹🏿"],"k":["marvel"]},"male_supervillain":{"n":"Man Supervillain","u":["🦹‍♂️","🦹🏻‍♂️","🦹🏼‍♂️","🦹🏽‍♂️","🦹🏾‍♂️","🦹🏿‍♂️"],"k":["male","evil","bad","criminal","hero","superpowers"]},"female_supervillain":{"n":"Woman Supervillain","u":["🦹‍♀️","🦹🏻‍♀️","🦹🏼‍♀️","🦹🏽‍♀️","🦹🏾‍♀️","🦹🏿‍♀️"],"k":["female","evil","bad","criminal","heroine","superpowers"]},"mage":{"n":"Mage","u":["🧙","🧙🏻","🧙🏼","🧙🏽","🧙🏾","🧙🏿"],"k":["magic"]},"male_mage":{"n":"Man Mage","u":["🧙‍♂️","🧙🏻‍♂️","🧙🏼‍♂️","🧙🏽‍♂️","🧙🏾‍♂️","🧙🏿‍♂️"],"k":["male","sorcerer"]},"female_mage":{"n":"Woman Mage","u":["🧙‍♀️","🧙🏻‍♀️","🧙🏼‍♀️","🧙🏽‍♀️","🧙🏾‍♀️","🧙🏿‍♀️"],"k":["female","witch"]},"fairy":{"n":"Fairy","u":["🧚","🧚🏻","🧚🏼","🧚🏽","🧚🏾","🧚🏿"],"k":["wings","magical"]},"male_fairy":{"n":"Man Fairy","u":["🧚‍♂️","🧚🏻‍♂️","🧚🏼‍♂️","🧚🏽‍♂️","🧚🏾‍♂️","🧚🏿‍♂️"],"k":["male"]},"female_fairy":{"n":"Woman Fairy","u":["🧚‍♀️","🧚🏻‍♀️","🧚🏼‍♀️","🧚🏽‍♀️","🧚🏾‍♀️","🧚🏿‍♀️"],"k":["female"]},"vampire":{"n":"Vampire","u":["🧛","🧛🏻","🧛🏼","🧛🏽","🧛🏾","🧛🏿"],"k":["blood","twilight"]},"male_vampire":{"n":"Man Vampire","u":["🧛‍♂️","🧛🏻‍♂️","🧛🏼‍♂️","🧛🏽‍♂️","🧛🏾‍♂️","🧛🏿‍♂️"],"k":["male","dracula"]},"female_vampire":{"n":"Woman Vampire","u":["🧛‍♀️","🧛🏻‍♀️","🧛🏼‍♀️","🧛🏽‍♀️","🧛🏾‍♀️","🧛🏿‍♀️"],"k":["female"]},"merperson":{"n":"Merperson","u":["🧜","🧜🏻","🧜🏼","🧜🏽","🧜🏾","🧜🏿"],"k":["sea"]},"merman":{"n":"Merman","u":["🧜‍♂️","🧜🏻‍♂️","🧜🏼‍♂️","🧜🏽‍♂️","🧜🏾‍♂️","🧜🏿‍♂️"],"k":["man","male","triton"]},"mermaid":{"n":"Mermaid","u":["🧜‍♀️","🧜🏻‍♀️","🧜🏼‍♀️","🧜🏽‍♀️","🧜🏾‍♀️","🧜🏿‍♀️"],"k":["woman","female","merwoman","ariel"]},"elf":{"n":"Elf","u":["🧝","🧝🏻","🧝🏼","🧝🏽","🧝🏾","🧝🏿"],"k":["magical"]},"male_elf":{"n":"Man Elf","u":["🧝‍♂️","🧝🏻‍♂️","🧝🏼‍♂️","🧝🏽‍♂️","🧝🏾‍♂️","🧝🏿‍♂️"],"k":["male"]},"female_elf":{"n":"Woman Elf","u":["🧝‍♀️","🧝🏻‍♀️","🧝🏼‍♀️","🧝🏽‍♀️","🧝🏾‍♀️","🧝🏿‍♀️"],"k":["female"]},"genie":{"n":"Genie","u":["🧞"],"k":["magical","wishes"]},"male_genie":{"n":"Man Genie","u":["🧞‍♂️"],"k":["male"]},"female_genie":{"n":"Woman Genie","u":["🧞‍♀️"],"k":["female"]},"zombie":{"n":"Zombie","u":["🧟"],"k":["dead"]},"male_zombie":{"n":"Man Zombie","u":["🧟‍♂️"],"k":["male","dracula","undead","walking","dead"]},"female_zombie":{"n":"Woman Zombie","u":["🧟‍♀️"],"k":["female","undead","walking","dead"]},"troll":{"n":"Troll","u":["🧌"],"k":["mystical","monster"]},"massage":{"n":"Face Massage","u":["💆","💆🏻","💆🏼","💆🏽","💆🏾","💆🏿"],"k":["person","getting","relax"]},"man-getting-massage":{"n":"Man Getting Massage","u":["💆‍♂️","💆🏻‍♂️","💆🏼‍♂️","💆🏽‍♂️","💆🏾‍♂️","💆🏿‍♂️"],"k":["getting-massage","male","boy","head"]},"woman-getting-massage":{"n":"Woman Getting Massage","u":["💆‍♀️","💆🏻‍♀️","💆🏼‍♀️","💆🏽‍♀️","💆🏾‍♀️","💆🏿‍♀️"],"k":["getting-massage","female","girl","head"]},"haircut":{"n":"Haircut","u":["💇","💇🏻","💇🏼","💇🏽","💇🏾","💇🏿"],"k":["person","getting","hairstyle"]},"man-getting-haircut":{"n":"Man Getting Haircut","u":["💇‍♂️","💇🏻‍♂️","💇🏼‍♂️","💇🏽‍♂️","💇🏾‍♂️","💇🏿‍♂️"],"k":["getting-haircut","male","boy"]},"woman-getting-haircut":{"n":"Woman Getting Haircut","u":["💇‍♀️","💇🏻‍♀️","💇🏼‍♀️","💇🏽‍♀️","💇🏾‍♀️","💇🏿‍♀️"],"k":["getting-haircut","female","girl"]},"walking":{"n":"Pedestrian","u":["🚶","🚶🏻","🚶🏼","🚶🏽","🚶🏾","🚶🏿"],"k":["walking","person","move"]},"man-walking":{"n":"Man Walking","u":["🚶‍♂️","🚶🏻‍♂️","🚶🏼‍♂️","🚶🏽‍♂️","🚶🏾‍♂️","🚶🏿‍♂️"],"k":["human","feet","steps"]},"woman-walking":{"n":"Woman Walking","u":["🚶‍♀️","🚶🏻‍♀️","🚶🏼‍♀️","🚶🏽‍♀️","🚶🏾‍♀️","🚶🏿‍♀️"],"k":["human","feet","steps","female"]},"standing_person":{"n":"Standing Person","u":["🧍","🧍🏻","🧍🏼","🧍🏽","🧍🏾","🧍🏿"],"k":["still"]},"man_standing":{"n":"Man Standing","u":["🧍‍♂️","🧍🏻‍♂️","🧍🏼‍♂️","🧍🏽‍♂️","🧍🏾‍♂️","🧍🏿‍♂️"],"k":["still"]},"woman_standing":{"n":"Woman Standing","u":["🧍‍♀️","🧍🏻‍♀️","🧍🏼‍♀️","🧍🏽‍♀️","🧍🏾‍♀️","🧍🏿‍♀️"],"k":["still"]},"kneeling_person":{"n":"Kneeling Person","u":["🧎","🧎🏻","🧎🏼","🧎🏽","🧎🏾","🧎🏿"],"k":["pray","respectful"]},"man_kneeling":{"n":"Man Kneeling","u":["🧎‍♂️","🧎🏻‍♂️","🧎🏼‍♂️","🧎🏽‍♂️","🧎🏾‍♂️","🧎🏿‍♂️"],"k":["pray","respectful"]},"woman_kneeling":{"n":"Woman Kneeling","u":["🧎‍♀️","🧎🏻‍♀️","🧎🏼‍♀️","🧎🏽‍♀️","🧎🏾‍♀️","🧎🏿‍♀️"],"k":["respectful","pray"]},"person_with_probing_cane":{"n":"Person with White Cane","u":["🧑‍🦯","🧑🏻‍🦯","🧑🏼‍🦯","🧑🏽‍🦯","🧑🏾‍🦯","🧑🏿‍🦯"],"k":["probing","blind"]},"man_with_probing_cane":{"n":"Man with White Cane","u":["👨‍🦯","👨🏻‍🦯","👨🏼‍🦯","👨🏽‍🦯","👨🏾‍🦯","👨🏿‍🦯"],"k":["probing","blind"]},"woman_with_probing_cane":{"n":"Woman with White Cane","u":["👩‍🦯","👩🏻‍🦯","👩🏼‍🦯","👩🏽‍🦯","👩🏾‍🦯","👩🏿‍🦯"],"k":["probing","blind"]},"person_in_motorized_wheelchair":{"n":"Person in Motorized Wheelchair","u":["🧑‍🦼","🧑🏻‍🦼","🧑🏼‍🦼","🧑🏽‍🦼","🧑🏾‍🦼","🧑🏿‍🦼"],"k":["disability","accessibility"]},"man_in_motorized_wheelchair":{"n":"Man in Motorized Wheelchair","u":["👨‍🦼","👨🏻‍🦼","👨🏼‍🦼","👨🏽‍🦼","👨🏾‍🦼","👨🏿‍🦼"],"k":["disability","accessibility"]},"woman_in_motorized_wheelchair":{"n":"Woman in Motorized Wheelchair","u":["👩‍🦼","👩🏻‍🦼","👩🏼‍🦼","👩🏽‍🦼","👩🏾‍🦼","👩🏿‍🦼"],"k":["disability","accessibility"]},"person_in_manual_wheelchair":{"n":"Person in Manual Wheelchair","u":["🧑‍🦽","🧑🏻‍🦽","🧑🏼‍🦽","🧑🏽‍🦽","🧑🏾‍🦽","🧑🏿‍🦽"],"k":["disability","accessibility"]},"man_in_manual_wheelchair":{"n":"Man in Manual Wheelchair","u":["👨‍🦽","👨🏻‍🦽","👨🏼‍🦽","👨🏽‍🦽","👨🏾‍🦽","👨🏿‍🦽"],"k":["disability","accessibility"]},"woman_in_manual_wheelchair":{"n":"Woman in Manual Wheelchair","u":["👩‍🦽","👩🏻‍🦽","👩🏼‍🦽","👩🏽‍🦽","👩🏾‍🦽","👩🏿‍🦽"],"k":["disability","accessibility"]},"runner":{"n":"Runner","u":["🏃","🏃🏻","🏃🏼","🏃🏽","🏃🏾","🏃🏿"],"k":["running","person","move"]},"man-running":{"n":"Man Running","u":["🏃‍♂️","🏃🏻‍♂️","🏃🏼‍♂️","🏃🏽‍♂️","🏃🏾‍♂️","🏃🏿‍♂️"],"k":["walking","exercise","race"]},"woman-running":{"n":"Woman Running","u":["🏃‍♀️","🏃🏻‍♀️","🏃🏼‍♀️","🏃🏽‍♀️","🏃🏾‍♀️","🏃🏿‍♀️"],"k":["walking","exercise","race","female"]},"dancer":{"n":"Dancer","u":["💃","💃🏻","💃🏼","💃🏽","💃🏾","💃🏿"],"k":["woman","dancing","female","girl","fun"]},"man_dancing":{"n":"Man Dancing","u":["🕺","🕺🏻","🕺🏼","🕺🏽","🕺🏾","🕺🏿"],"k":["male","boy","fun","dancer"]},"man_in_business_suit_levitating":{"n":"Person in Suit Levitating","u":["🕴️","🕴🏻","🕴🏼","🕴🏽","🕴🏾","🕴🏿"],"k":["man","business","levitate","hover","jump"]},"dancers":{"n":"Woman with Bunny Ears","u":["👯"],"k":["dancers","people","perform","costume"]},"men-with-bunny-ears-partying":{"n":"Men with Bunny Ears","u":["👯‍♂️"],"k":["with-bunny-ears-partying","man","male","boys"]},"women-with-bunny-ears-partying":{"n":"Women with Bunny Ears","u":["👯‍♀️"],"k":["with-bunny-ears-partying","woman","female","girls"]},"person_in_steamy_room":{"n":"Person in Steamy Room","u":["🧖","🧖🏻","🧖🏼","🧖🏽","🧖🏾","🧖🏿"],"k":["relax","spa"]},"man_in_steamy_room":{"n":"Man in Steamy Room","u":["🧖‍♂️","🧖🏻‍♂️","🧖🏼‍♂️","🧖🏽‍♂️","🧖🏾‍♂️","🧖🏿‍♂️"],"k":["male","spa","steamroom","sauna"]},"woman_in_steamy_room":{"n":"Woman in Steamy Room","u":["🧖‍♀️","🧖🏻‍♀️","🧖🏼‍♀️","🧖🏽‍♀️","🧖🏾‍♀️","🧖🏿‍♀️"],"k":["female","spa","steamroom","sauna"]},"person_climbing":{"n":"Person Climbing","u":["🧗","🧗🏻","🧗🏼","🧗🏽","🧗🏾","🧗🏿"],"k":["sport"]},"man_climbing":{"n":"Man Climbing","u":["🧗‍♂️","🧗🏻‍♂️","🧗🏼‍♂️","🧗🏽‍♂️","🧗🏾‍♂️","🧗🏿‍♂️"],"k":["sports","hobby","male","rock"]},"woman_climbing":{"n":"Woman Climbing","u":["🧗‍♀️","🧗🏻‍♀️","🧗🏼‍♀️","🧗🏽‍♀️","🧗🏾‍♀️","🧗🏿‍♀️"],"k":["sports","hobby","female","rock"]},"fencer":{"n":"Fencer","u":["🤺"],"k":["person","fencing","sports","sword"]},"horse_racing":{"n":"Horse Racing","u":["🏇","🏇🏻","🏇🏼","🏇🏽","🏇🏾","🏇🏿"],"k":["animal","betting","competition","gambling","luck"]},"skier":{"n":"Skier","u":["⛷️"],"k":["sports","winter","snow"]},"snowboarder":{"n":"Snowboarder","u":["🏂","🏂🏻","🏂🏼","🏂🏽","🏂🏾","🏂🏿"],"k":["sports","winter"]},"golfer":{"n":"Person Golfing","u":["🏌️","🏌🏻","🏌🏼","🏌🏽","🏌🏾","🏌🏿"],"k":["golfer","sports","business"]},"man-golfing":{"n":"Man Golfing","u":["🏌️‍♂️","🏌🏻‍♂️","🏌🏼‍♂️","🏌🏽‍♂️","🏌🏾‍♂️","🏌🏿‍♂️"],"k":["sport"]},"woman-golfing":{"n":"Woman Golfing","u":["🏌️‍♀️","🏌🏻‍♀️","🏌🏼‍♀️","🏌🏽‍♀️","🏌🏾‍♀️","🏌🏿‍♀️"],"k":["sports","business","female"]},"surfer":{"n":"Surfer","u":["🏄","🏄🏻","🏄🏼","🏄🏽","🏄🏾","🏄🏿"],"k":["person","surfing","sport","sea"]},"man-surfing":{"n":"Man Surfing","u":["🏄‍♂️","🏄🏻‍♂️","🏄🏼‍♂️","🏄🏽‍♂️","🏄🏾‍♂️","🏄🏿‍♂️"],"k":["sports","ocean","sea","summer","beach"]},"woman-surfing":{"n":"Woman Surfing","u":["🏄‍♀️","🏄🏻‍♀️","🏄🏼‍♀️","🏄🏽‍♀️","🏄🏾‍♀️","🏄🏿‍♀️"],"k":["sports","ocean","sea","summer","beach","female"]},"rowboat":{"n":"Rowboat","u":["🚣","🚣🏻","🚣🏼","🚣🏽","🚣🏾","🚣🏿"],"k":["person","rowing","boat","sport","move"]},"man-rowing-boat":{"n":"Man Rowing Boat","u":["🚣‍♂️","🚣🏻‍♂️","🚣🏼‍♂️","🚣🏽‍♂️","🚣🏾‍♂️","🚣🏿‍♂️"],"k":["rowing-boat","sports","hobby","water","ship"]},"woman-rowing-boat":{"n":"Woman Rowing Boat","u":["🚣‍♀️","🚣🏻‍♀️","🚣🏼‍♀️","🚣🏽‍♀️","🚣🏾‍♀️","🚣🏿‍♀️"],"k":["rowing-boat","sports","hobby","water","ship","female"]},"swimmer":{"n":"Swimmer","u":["🏊","🏊🏻","🏊🏼","🏊🏽","🏊🏾","🏊🏿"],"k":["person","swimming","sport","pool"]},"man-swimming":{"n":"Man Swimming","u":["🏊‍♂️","🏊🏻‍♂️","🏊🏼‍♂️","🏊🏽‍♂️","🏊🏾‍♂️","🏊🏿‍♂️"],"k":["sports","exercise","human","athlete","water","summer"]},"woman-swimming":{"n":"Woman Swimming","u":["🏊‍♀️","🏊🏻‍♀️","🏊🏼‍♀️","🏊🏽‍♀️","🏊🏾‍♀️","🏊🏿‍♀️"],"k":["sports","exercise","human","athlete","water","summer","female"]},"person_with_ball":{"n":"Person Bouncing Ball","u":["⛹️","⛹🏻","⛹🏼","⛹🏽","⛹🏾","⛹🏿"],"k":["with","sports","human"]},"man-bouncing-ball":{"n":"Man Bouncing Ball","u":["⛹️‍♂️","⛹🏻‍♂️","⛹🏼‍♂️","⛹🏽‍♂️","⛹🏾‍♂️","⛹🏿‍♂️"],"k":["bouncing-ball","sport"]},"woman-bouncing-ball":{"n":"Woman Bouncing Ball","u":["⛹️‍♀️","⛹🏻‍♀️","⛹🏼‍♀️","⛹🏽‍♀️","⛹🏾‍♀️","⛹🏿‍♀️"],"k":["bouncing-ball","sports","human","female"]},"weight_lifter":{"n":"Person Lifting Weights","u":["🏋️","🏋🏻","🏋🏼","🏋🏽","🏋🏾","🏋🏿"],"k":["weight","lifter","sports","training","exercise"]},"man-lifting-weights":{"n":"Man Lifting Weights","u":["🏋️‍♂️","🏋🏻‍♂️","🏋🏼‍♂️","🏋🏽‍♂️","🏋🏾‍♂️","🏋🏿‍♂️"],"k":["lifting-weights","sport"]},"woman-lifting-weights":{"n":"Woman Lifting Weights","u":["🏋️‍♀️","🏋🏻‍♀️","🏋🏼‍♀️","🏋🏽‍♀️","🏋🏾‍♀️","🏋🏿‍♀️"],"k":["lifting-weights","sports","training","exercise","female"]},"bicyclist":{"n":"Bicyclist","u":["🚴","🚴🏻","🚴🏼","🚴🏽","🚴🏾","🚴🏿"],"k":["person","biking","sport","move"]},"man-biking":{"n":"Man Biking","u":["🚴‍♂️","🚴🏻‍♂️","🚴🏼‍♂️","🚴🏽‍♂️","🚴🏾‍♂️","🚴🏿‍♂️"],"k":["sports","bike","exercise","hipster"]},"woman-biking":{"n":"Woman Biking","u":["🚴‍♀️","🚴🏻‍♀️","🚴🏼‍♀️","🚴🏽‍♀️","🚴🏾‍♀️","🚴🏿‍♀️"],"k":["sports","bike","exercise","hipster","female"]},"mountain_bicyclist":{"n":"Mountain Bicyclist","u":["🚵","🚵🏻","🚵🏼","🚵🏽","🚵🏾","🚵🏿"],"k":["person","biking","sport","move"]},"man-mountain-biking":{"n":"Man Mountain Biking","u":["🚵‍♂️","🚵🏻‍♂️","🚵🏼‍♂️","🚵🏽‍♂️","🚵🏾‍♂️","🚵🏿‍♂️"],"k":["mountain-biking","transportation","sports","human","race","bike"]},"woman-mountain-biking":{"n":"Woman Mountain Biking","u":["🚵‍♀️","🚵🏻‍♀️","🚵🏼‍♀️","🚵🏽‍♀️","🚵🏾‍♀️","🚵🏿‍♀️"],"k":["mountain-biking","transportation","sports","human","race","bike","female"]},"person_doing_cartwheel":{"n":"Person Cartwheeling","u":["🤸","🤸🏻","🤸🏼","🤸🏽","🤸🏾","🤸🏿"],"k":["doing","cartwheel","sport","gymnastic"]},"man-cartwheeling":{"n":"Man Cartwheeling","u":["🤸‍♂️","🤸🏻‍♂️","🤸🏼‍♂️","🤸🏽‍♂️","🤸🏾‍♂️","🤸🏿‍♂️"],"k":["gymnastics"]},"woman-cartwheeling":{"n":"Woman Cartwheeling","u":["🤸‍♀️","🤸🏻‍♀️","🤸🏼‍♀️","🤸🏽‍♀️","🤸🏾‍♀️","🤸🏿‍♀️"],"k":["gymnastics"]},"wrestlers":{"n":"Wrestlers","u":["🤼"],"k":["people","wrestling","sport"]},"man-wrestling":{"n":"Men Wrestling","u":["🤼‍♂️"],"k":["man","sports","wrestlers"]},"woman-wrestling":{"n":"Women Wrestling","u":["🤼‍♀️"],"k":["woman","sports","wrestlers"]},"water_polo":{"n":"Water Polo","u":["🤽","🤽🏻","🤽🏼","🤽🏽","🤽🏾","🤽🏿"],"k":["person","playing","sport"]},"man-playing-water-polo":{"n":"Man Playing Water Polo","u":["🤽‍♂️","🤽🏻‍♂️","🤽🏼‍♂️","🤽🏽‍♂️","🤽🏾‍♂️","🤽🏿‍♂️"],"k":["playing-water-polo","sports","pool"]},"woman-playing-water-polo":{"n":"Woman Playing Water Polo","u":["🤽‍♀️","🤽🏻‍♀️","🤽🏼‍♀️","🤽🏽‍♀️","🤽🏾‍♀️","🤽🏿‍♀️"],"k":["playing-water-polo","sports","pool"]},"handball":{"n":"Handball","u":["🤾","🤾🏻","🤾🏼","🤾🏽","🤾🏾","🤾🏿"],"k":["person","playing","sport"]},"man-playing-handball":{"n":"Man Playing Handball","u":["🤾‍♂️","🤾🏻‍♂️","🤾🏼‍♂️","🤾🏽‍♂️","🤾🏾‍♂️","🤾🏿‍♂️"],"k":["playing-handball","sports"]},"woman-playing-handball":{"n":"Woman Playing Handball","u":["🤾‍♀️","🤾🏻‍♀️","🤾🏼‍♀️","🤾🏽‍♀️","🤾🏾‍♀️","🤾🏿‍♀️"],"k":["playing-handball","sports"]},"juggling":{"n":"Juggling","u":["🤹","🤹🏻","🤹🏼","🤹🏽","🤹🏾","🤹🏿"],"k":["person","performance","balance"]},"man-juggling":{"n":"Man Juggling","u":["🤹‍♂️","🤹🏻‍♂️","🤹🏼‍♂️","🤹🏽‍♂️","🤹🏾‍♂️","🤹🏿‍♂️"],"k":["juggle","balance","skill","multitask"]},"woman-juggling":{"n":"Woman Juggling","u":["🤹‍♀️","🤹🏻‍♀️","🤹🏼‍♀️","🤹🏽‍♀️","🤹🏾‍♀️","🤹🏿‍♀️"],"k":["juggle","balance","skill","multitask"]},"person_in_lotus_position":{"n":"Person in Lotus Position","u":["🧘","🧘🏻","🧘🏼","🧘🏽","🧘🏾","🧘🏿"],"k":["meditate"]},"man_in_lotus_position":{"n":"Man in Lotus Position","u":["🧘‍♂️","🧘🏻‍♂️","🧘🏼‍♂️","🧘🏽‍♂️","🧘🏾‍♂️","🧘🏿‍♂️"],"k":["male","meditation","yoga","serenity","zen","mindfulness"]},"woman_in_lotus_position":{"n":"Woman in Lotus Position","u":["🧘‍♀️","🧘🏻‍♀️","🧘🏼‍♀️","🧘🏽‍♀️","🧘🏾‍♀️","🧘🏿‍♀️"],"k":["female","meditation","yoga","serenity","zen","mindfulness"]},"bath":{"n":"Bath","u":["🛀","🛀🏻","🛀🏼","🛀🏽","🛀🏾","🛀🏿"],"k":["person","taking","clean","shower","bathroom"]},"sleeping_accommodation":{"n":"Person in Bed","u":["🛌","🛌🏻","🛌🏼","🛌🏽","🛌🏾","🛌🏿"],"k":["sleeping","accommodation","rest"]},"people_holding_hands":{"n":"People Holding Hands","u":["🧑‍🤝‍🧑","🧑🏻‍🤝‍🧑🏻","🧑🏼‍🤝‍🧑🏼","🧑🏽‍🤝‍🧑🏽","🧑🏾‍🤝‍🧑🏾","🧑🏿‍🤝‍🧑🏿"],"k":["friendship"]},"two_women_holding_hands":{"n":"Women Holding Hands","u":["👭","👭🏻","👭🏼","👭🏽","👭🏾","👭🏿"],"k":["two","pair","friendship","couple","love","like","female","people","human"]},"man_and_woman_holding_hands":{"n":"Man and Woman Holding Hands","u":["👫","👫🏻","👫🏼","👫🏽","👫🏾","👫🏿"],"k":["couple","pair","people","human","love","date","dating","like","affection","valentines","marriage"]},"two_men_holding_hands":{"n":"Men Holding Hands","u":["👬","👬🏻","👬🏼","👬🏽","👬🏾","👬🏿"],"k":["two","pair","couple","love","like","bromance","friendship","people","human"]},"couplekiss":{"n":"Kiss","u":["💏","💏🏻","💏🏼","💏🏽","💏🏾","💏🏿"],"k":["couplekiss","pair","valentines","love","like","dating","marriage"]},"woman-kiss-man":{"n":"Kiss: Woman, Man","u":["👩‍❤️‍💋‍👨","👩🏻‍❤️‍💋‍👨🏻","👩🏼‍❤️‍💋‍👨🏼","👩🏽‍❤️‍💋‍👨🏽","👩🏾‍❤️‍💋‍👨🏾","👩🏿‍❤️‍💋‍👨🏿"],"k":["woman","kiss-man","kiss","love"]},"man-kiss-man":{"n":"Kiss: Man, Man","u":["👨‍❤️‍💋‍👨","👨🏻‍❤️‍💋‍👨🏻","👨🏼‍❤️‍💋‍👨🏼","👨🏽‍❤️‍💋‍👨🏽","👨🏾‍❤️‍💋‍👨🏾","👨🏿‍❤️‍💋‍👨🏿"],"k":["kiss-man","kiss","pair","valentines","love","like","dating","marriage"]},"woman-kiss-woman":{"n":"Kiss: Woman, Woman","u":["👩‍❤️‍💋‍👩","👩🏻‍❤️‍💋‍👩🏻","👩🏼‍❤️‍💋‍👩🏼","👩🏽‍❤️‍💋‍👩🏽","👩🏾‍❤️‍💋‍👩🏾","👩🏿‍❤️‍💋‍👩🏿"],"k":["kiss-woman","kiss","pair","valentines","love","like","dating","marriage"]},"couple_with_heart":{"n":"Couple with Heart","u":["💑","💑🏻","💑🏼","💑🏽","💑🏾","💑🏿"],"k":["pair","love","like","affection","human","dating","valentines","marriage"]},"woman-heart-man":{"n":"Couple with Heart: Woman, Man","u":["👩‍❤️‍👨","👩🏻‍❤️‍👨🏻","👩🏼‍❤️‍👨🏼","👩🏽‍❤️‍👨🏽","👩🏾‍❤️‍👨🏾","👩🏿‍❤️‍👨🏿"],"k":["woman","heart-man","heart","love"]},"man-heart-man":{"n":"Couple with Heart: Man, Man","u":["👨‍❤️‍👨","👨🏻‍❤️‍👨🏻","👨🏼‍❤️‍👨🏼","👨🏽‍❤️‍👨🏽","👨🏾‍❤️‍👨🏾","👨🏿‍❤️‍👨🏿"],"k":["heart-man","heart","pair","love","like","affection","human","dating","valentines","marriage"]},"woman-heart-woman":{"n":"Couple with Heart: Woman, Woman","u":["👩‍❤️‍👩","👩🏻‍❤️‍👩🏻","👩🏼‍❤️‍👩🏼","👩🏽‍❤️‍👩🏽","👩🏾‍❤️‍👩🏾","👩🏿‍❤️‍👩🏿"],"k":["heart-woman","heart","pair","love","like","affection","human","dating","valentines","marriage"]},"family":{"n":"Family","u":["👪"],"k":["home","parents","child","mom","dad","father","mother","people","human"]},"man-woman-boy":{"n":"Family: Man, Woman, Boy","u":["👨‍👩‍👦"],"k":["man","woman-boy","family","woman","love"]},"man-woman-girl":{"n":"Family: Man, Woman, Girl","u":["👨‍👩‍👧"],"k":["man","woman-girl","family","woman","home","parents","people","human","child"]},"man-woman-girl-boy":{"n":"Family: Man, Woman, Girl, Boy","u":["👨‍👩‍👧‍👦"],"k":["man","woman-girl-boy","family","woman","girl","home","parents","people","human","children"]},"man-woman-boy-boy":{"n":"Family: Man, Woman, Boy, Boy","u":["👨‍👩‍👦‍👦"],"k":["man","woman-boy-boy","family","woman","home","parents","people","human","children"]},"man-woman-girl-girl":{"n":"Family: Man, Woman, Girl, Girl","u":["👨‍👩‍👧‍👧"],"k":["man","woman-girl-girl","family","woman","home","parents","people","human","children"]},"man-man-boy":{"n":"Family: Man, Man, Boy","u":["👨‍👨‍👦"],"k":["man","man-boy","family","home","parents","people","human","children"]},"man-man-girl":{"n":"Family: Man, Man, Girl","u":["👨‍👨‍👧"],"k":["man","man-girl","family","home","parents","people","human","children"]},"man-man-girl-boy":{"n":"Family: Man, Man, Girl, Boy","u":["👨‍👨‍👧‍👦"],"k":["man","man-girl-boy","family","girl","home","parents","people","human","children"]},"man-man-boy-boy":{"n":"Family: Man, Man, Boy, Boy","u":["👨‍👨‍👦‍👦"],"k":["man","man-boy-boy","family","home","parents","people","human","children"]},"man-man-girl-girl":{"n":"Family: Man, Man, Girl, Girl","u":["👨‍👨‍👧‍👧"],"k":["man","man-girl-girl","family","home","parents","people","human","children"]},"woman-woman-boy":{"n":"Family: Woman, Woman, Boy","u":["👩‍👩‍👦"],"k":["woman","woman-boy","family","home","parents","people","human","children"]},"woman-woman-girl":{"n":"Family: Woman, Woman, Girl","u":["👩‍👩‍👧"],"k":["woman","woman-girl","family","home","parents","people","human","children"]},"woman-woman-girl-boy":{"n":"Family: Woman, Woman, Girl, Boy","u":["👩‍👩‍👧‍👦"],"k":["woman","woman-girl-boy","family","girl","home","parents","people","human","children"]},"woman-woman-boy-boy":{"n":"Family: Woman, Woman, Boy, Boy","u":["👩‍👩‍👦‍👦"],"k":["woman","woman-boy-boy","family","home","parents","people","human","children"]},"woman-woman-girl-girl":{"n":"Family: Woman, Woman, Girl, Girl","u":["👩‍👩‍👧‍👧"],"k":["woman","woman-girl-girl","family","home","parents","people","human","children"]},"man-boy":{"n":"Family: Man, Boy","u":["👨‍👦"],"k":["man","family","home","parent","people","human","child"]},"man-boy-boy":{"n":"Family: Man, Boy, Boy","u":["👨‍👦‍👦"],"k":["man","boy-boy","family","home","parent","people","human","children"]},"man-girl":{"n":"Family: Man, Girl","u":["👨‍👧"],"k":["man","family","home","parent","people","human","child"]},"man-girl-boy":{"n":"Family: Man, Girl, Boy","u":["👨‍👧‍👦"],"k":["man","girl-boy","family","girl","home","parent","people","human","children"]},"man-girl-girl":{"n":"Family: Man, Girl, Girl","u":["👨‍👧‍👧"],"k":["man","girl-girl","family","home","parent","people","human","children"]},"woman-boy":{"n":"Family: Woman, Boy","u":["👩‍👦"],"k":["woman","family","home","parent","people","human","child"]},"woman-boy-boy":{"n":"Family: Woman, Boy, Boy","u":["👩‍👦‍👦"],"k":["woman","boy-boy","family","home","parent","people","human","children"]},"woman-girl":{"n":"Family: Woman, Girl","u":["👩‍👧"],"k":["woman","family","home","parent","people","human","child"]},"woman-girl-boy":{"n":"Family: Woman, Girl, Boy","u":["👩‍👧‍👦"],"k":["woman","girl-boy","family","girl","home","parent","people","human","children"]},"woman-girl-girl":{"n":"Family: Woman, Girl, Girl","u":["👩‍👧‍👧"],"k":["woman","girl-girl","family","home","parent","people","human","children"]},"speaking_head_in_silhouette":{"n":"Speaking Head","u":["🗣️"],"k":["in","silhouette","user","person","human","sing","say","talk"]},"bust_in_silhouette":{"n":"Bust in Silhouette","u":["👤"],"k":["user","person","human"]},"busts_in_silhouette":{"n":"Busts in Silhouette","u":["👥"],"k":["user","person","human","group","team"]},"people_hugging":{"n":"People Hugging","u":["🫂"],"k":["care"]},"footprints":{"n":"Footprints","u":["👣"],"k":["feet","tracking","walking","beach"]},"robot_face":{"n":"Robot","u":["🤖"],"k":["face","computer","machine","bot"]},"smiley_cat":{"n":"Grinning Cat","u":["😺"],"k":["smiley","animal","cats","happy","smile"]},"smile_cat":{"n":"Grinning Cat with Smiling Eyes","u":["😸"],"k":["smile","animal","cats"]},"joy_cat":{"n":"Cat with Tears of Joy","u":["😹"],"k":["animal","cats","haha","happy"]},"heart_eyes_cat":{"n":"Smiling Cat with Heart-Eyes","u":["😻"],"k":["heart","eyes","animal","love","like","affection","cats","valentines"]},"smirk_cat":{"n":"Cat with Wry Smile","u":["😼"],"k":["smirk","animal","cats"]},"kissing_cat":{"n":"Kissing Cat","u":["😽"],"k":["animal","cats","kiss"]},"scream_cat":{"n":"Weary Cat","u":["🙀"],"k":["scream","animal","cats","munch","scared"]},"crying_cat_face":{"n":"Crying Cat","u":["😿"],"k":["face","animal","tears","weep","sad","cats","upset","cry"]},"pouting_cat":{"n":"Pouting Cat","u":["😾"],"k":["animal","cats"]},"see_no_evil":{"n":"See-No-Evil Monkey","u":["🙈"],"k":["see","no","evil","animal","nature","haha"]},"hear_no_evil":{"n":"Hear-No-Evil Monkey","u":["🙉"],"k":["hear","no","evil","animal","nature"]},"speak_no_evil":{"n":"Speak-No-Evil Monkey","u":["🙊"],"k":["speak","no","evil","animal","nature","omg"]},"love_letter":{"n":"Love Letter","u":["💌"],"k":["email","like","affection","envelope","valentines"]},"cupid":{"n":"Heart with Arrow","u":["💘"],"k":["cupid","love","like","affection","valentines"]},"gift_heart":{"n":"Heart with Ribbon","u":["💝"],"k":["gift","love","valentines"]},"sparkling_heart":{"n":"Sparkling Heart","u":["💖"],"k":["love","like","affection","valentines"]},"heartpulse":{"n":"Growing Heart","u":["💗"],"k":["heartpulse","like","love","affection","valentines","pink"]},"heartbeat":{"n":"Beating Heart","u":["💓"],"k":["heartbeat","love","like","affection","valentines","pink"]},"revolving_hearts":{"n":"Revolving Hearts","u":["💞"],"k":["love","like","affection","valentines"]},"two_hearts":{"n":"Two Hearts","u":["💕"],"k":["love","like","affection","valentines","heart"]},"heart_decoration":{"n":"Heart Decoration","u":["💟"],"k":["purple","square","love","like"]},"heavy_heart_exclamation_mark_ornament":{"n":"Heart Exclamation","u":["❣️"],"k":["heavy","mark","ornament","decoration","love"]},"broken_heart":{"n":"Broken Heart","u":["💔"],"k":["sad","sorry","break","heartbreak"]},"heart_on_fire":{"n":"Heart on Fire","u":["❤️‍🔥"],"k":["passionate","enthusiastic"]},"mending_heart":{"n":"Mending Heart","u":["❤️‍🩹"],"k":["broken","bandage","wounded"]},"heart":{"n":"Red Heart","u":["❤️"],"k":["love","like","valentines"]},"pink_heart":{"n":"Pink Heart","u":["🩷"],"k":["valentines"]},"orange_heart":{"n":"Orange Heart","u":["🧡"],"k":["love","like","affection","valentines"]},"yellow_heart":{"n":"Yellow Heart","u":["💛"],"k":["love","like","affection","valentines"]},"green_heart":{"n":"Green Heart","u":["💚"],"k":["love","like","affection","valentines"]},"blue_heart":{"n":"Blue Heart","u":["💙"],"k":["love","like","affection","valentines"]},"light_blue_heart":{"n":"Light Blue Heart","u":["🩵"],"k":["ice","baby"]},"purple_heart":{"n":"Purple Heart","u":["💜"],"k":["love","like","affection","valentines"]},"brown_heart":{"n":"Brown Heart","u":["🤎"],"k":["coffee"]},"black_heart":{"n":"Black Heart","u":["🖤"],"k":["evil"]},"grey_heart":{"n":"Grey Heart","u":["🩶"],"k":["silver","monochrome"]},"white_heart":{"n":"White Heart","u":["🤍"],"k":["pure"]},"kiss":{"n":"Kiss Mark","u":["💋"],"k":["face","lips","love","like","affection","valentines"]},"anger":{"n":"Anger Symbol","u":["💢"],"k":["angry","mad"]},"boom":{"n":"Collision","u":["💥"],"k":["boom","bomb","explode","explosion","blown"]},"dizzy":{"n":"Dizzy","u":["💫"],"k":["star","sparkle","shoot","magic"]},"sweat_drops":{"n":"Sweat Droplets","u":["💦"],"k":["drops","water","drip","oops"]},"dash":{"n":"Dash Symbol","u":["💨"],"k":["dashing","away","wind","air","fast","shoo","fart","smoke","puff"]},"hole":{"n":"Hole","u":["🕳️"],"k":["embarrassing"]},"speech_balloon":{"n":"Speech Balloon","u":["💬"],"k":["bubble","words","message","talk","chatting"]},"eye-in-speech-bubble":{"n":"Eye in Speech Bubble","u":["👁️‍🗨️"],"k":["in-speech-bubble","info"]},"left_speech_bubble":{"n":"Left Speech Bubble","u":["🗨️"],"k":["words","message","talk","chatting"]},"right_anger_bubble":{"n":"Right Anger Bubble","u":["🗯️"],"k":["caption","speech","thinking","mad"]},"thought_balloon":{"n":"Thought Balloon","u":["💭"],"k":["bubble","cloud","speech","thinking","dream"]},"zzz":{"n":"Zzz","u":["💤"],"k":["sleepy","tired","dream"]},"monkey_face":{"n":"Monkey Face","u":["🐵"],"k":["animal","nature","circus"]},"monkey":{"n":"Monkey","u":["🐒"],"k":["animal","nature","banana","circus"]},"gorilla":{"n":"Gorilla","u":["🦍"],"k":["animal","nature","circus"]},"orangutan":{"n":"Orangutan","u":["🦧"],"k":["animal"]},"dog":{"n":"Dog Face","u":["🐶"],"k":["animal","friend","nature","woof","puppy","pet","faithful"]},"dog2":{"n":"Dog","u":["🐕"],"k":["dog2","animal","nature","friend","doge","pet","faithful"]},"guide_dog":{"n":"Guide Dog","u":["🦮"],"k":["animal","blind"]},"service_dog":{"n":"Service Dog","u":["🐕‍🦺"],"k":["blind","animal"]},"poodle":{"n":"Poodle","u":["🐩"],"k":["dog","animal","101","nature","pet"]},"wolf":{"n":"Wolf","u":["🐺"],"k":["animal","nature","wild"]},"fox_face":{"n":"Fox","u":["🦊"],"k":["face","animal","nature"]},"raccoon":{"n":"Raccoon","u":["🦝"],"k":["animal","nature"]},"cat":{"n":"Cat Face","u":["🐱"],"k":["animal","meow","nature","pet","kitten"]},"cat2":{"n":"Cat","u":["🐈"],"k":["cat2","animal","meow","pet","cats"]},"black_cat":{"n":"Black Cat","u":["🐈‍⬛"],"k":["superstition","luck"]},"lion_face":{"n":"Lion","u":["🦁"],"k":["face","animal","nature"]},"tiger":{"n":"Tiger Face","u":["🐯"],"k":["animal","cat","danger","wild","nature","roar"]},"tiger2":{"n":"Tiger","u":["🐅"],"k":["tiger2","animal","nature","roar"]},"leopard":{"n":"Leopard","u":["🐆"],"k":["animal","nature"]},"horse":{"n":"Horse Face","u":["🐴"],"k":["animal","brown","nature"]},"moose":{"n":"Moose","u":["🫎"],"k":["shrek","canada","sweden","sven","cool"]},"donkey":{"n":"Donkey","u":["🫏"],"k":["eeyore","mule"]},"racehorse":{"n":"Horse","u":["🐎"],"k":["racehorse","animal","gamble","luck"]},"unicorn_face":{"n":"Unicorn","u":["🦄"],"k":["face","animal","nature","mystical"]},"zebra_face":{"n":"Zebra","u":["🦓"],"k":["face","animal","nature","stripes","safari"]},"deer":{"n":"Deer","u":["🦌"],"k":["animal","nature","horns","venison"]},"bison":{"n":"Bison","u":["🦬"],"k":["ox"]},"cow":{"n":"Cow Face","u":["🐮"],"k":["beef","ox","animal","nature","moo","milk"]},"ox":{"n":"Ox","u":["🐂"],"k":["animal","cow","beef"]},"water_buffalo":{"n":"Water Buffalo","u":["🐃"],"k":["animal","nature","ox","cow"]},"cow2":{"n":"Cow","u":["🐄"],"k":["cow2","beef","ox","animal","nature","moo","milk"]},"pig":{"n":"Pig Face","u":["🐷"],"k":["animal","oink","nature"]},"pig2":{"n":"Pig","u":["🐖"],"k":["pig2","animal","nature"]},"boar":{"n":"Boar","u":["🐗"],"k":["animal","nature"]},"pig_nose":{"n":"Pig Nose","u":["🐽"],"k":["animal","oink"]},"ram":{"n":"Ram","u":["🐏"],"k":["animal","sheep","nature"]},"sheep":{"n":"Ewe","u":["🐑"],"k":["sheep","animal","nature","wool","shipit"]},"goat":{"n":"Goat","u":["🐐"],"k":["animal","nature"]},"dromedary_camel":{"n":"Camel","u":["🐪"],"k":["dromedary","animal","hot","desert","hump"]},"camel":{"n":"Bactrian Camel","u":["🐫"],"k":["two","hump","animal","nature","hot","desert"]},"llama":{"n":"Llama","u":["🦙"],"k":["animal","nature","alpaca"]},"giraffe_face":{"n":"Giraffe","u":["🦒"],"k":["face","animal","nature","spots","safari"]},"elephant":{"n":"Elephant","u":["🐘"],"k":["animal","nature","nose","th","circus"]},"mammoth":{"n":"Mammoth","u":["🦣"],"k":["elephant","tusks"]},"rhinoceros":{"n":"Rhinoceros","u":["🦏"],"k":["animal","nature","horn"]},"hippopotamus":{"n":"Hippopotamus","u":["🦛"],"k":["animal","nature"]},"mouse":{"n":"Mouse Face","u":["🐭"],"k":["animal","nature","cheese","wedge","rodent"]},"mouse2":{"n":"Mouse","u":["🐁"],"k":["mouse2","animal","nature","rodent"]},"rat":{"n":"Rat","u":["🐀"],"k":["animal","mouse","rodent"]},"hamster":{"n":"Hamster","u":["🐹"],"k":["animal","nature"]},"rabbit":{"n":"Rabbit Face","u":["🐰"],"k":["animal","nature","pet","spring","magic","bunny"]},"rabbit2":{"n":"Rabbit","u":["🐇"],"k":["rabbit2","animal","nature","pet","magic","spring"]},"chipmunk":{"n":"Chipmunk","u":["🐿️"],"k":["animal","nature","rodent","squirrel"]},"beaver":{"n":"Beaver","u":["🦫"],"k":["animal","rodent"]},"hedgehog":{"n":"Hedgehog","u":["🦔"],"k":["animal","nature","spiny"]},"bat":{"n":"Bat","u":["🦇"],"k":["animal","nature","blind","vampire"]},"bear":{"n":"Bear","u":["🐻"],"k":["animal","nature","wild"]},"polar_bear":{"n":"Polar Bear","u":["🐻‍❄️"],"k":["animal","arctic"]},"koala":{"n":"Koala","u":["🐨"],"k":["animal","nature"]},"panda_face":{"n":"Panda","u":["🐼"],"k":["face","animal","nature"]},"sloth":{"n":"Sloth","u":["🦥"],"k":["animal"]},"otter":{"n":"Otter","u":["🦦"],"k":["animal"]},"skunk":{"n":"Skunk","u":["🦨"],"k":["animal"]},"kangaroo":{"n":"Kangaroo","u":["🦘"],"k":["animal","nature","australia","joey","hop","marsupial"]},"badger":{"n":"Badger","u":["🦡"],"k":["animal","nature","honey"]},"feet":{"n":"Paw Prints","u":["🐾"],"k":["feet","animal","tracking","footprints","dog","cat","pet"]},"turkey":{"n":"Turkey","u":["🦃"],"k":["animal","bird"]},"chicken":{"n":"Chicken","u":["🐔"],"k":["animal","cluck","nature","bird"]},"rooster":{"n":"Rooster","u":["🐓"],"k":["animal","nature","chicken"]},"hatching_chick":{"n":"Hatching Chick","u":["🐣"],"k":["animal","chicken","egg","born","baby","bird"]},"baby_chick":{"n":"Baby Chick","u":["🐤"],"k":["animal","chicken","bird"]},"hatched_chick":{"n":"Front-Facing Baby Chick","u":["🐥"],"k":["hatched","front","facing","animal","chicken","bird"]},"bird":{"n":"Bird","u":["🐦"],"k":["animal","nature","fly","tweet","spring"]},"penguin":{"n":"Penguin","u":["🐧"],"k":["animal","nature"]},"dove_of_peace":{"n":"Dove","u":["🕊️"],"k":["of","peace","animal","bird"]},"eagle":{"n":"Eagle","u":["🦅"],"k":["animal","nature","bird"]},"duck":{"n":"Duck","u":["🦆"],"k":["animal","nature","bird","mallard"]},"swan":{"n":"Swan","u":["🦢"],"k":["animal","nature","bird"]},"owl":{"n":"Owl","u":["🦉"],"k":["animal","nature","bird","hoot"]},"dodo":{"n":"Dodo","u":["🦤"],"k":["animal","bird"]},"feather":{"n":"Feather","u":["🪶"],"k":["bird","fly"]},"flamingo":{"n":"Flamingo","u":["🦩"],"k":["animal"]},"peacock":{"n":"Peacock","u":["🦚"],"k":["animal","nature","peahen","bird"]},"parrot":{"n":"Parrot","u":["🦜"],"k":["animal","nature","bird","pirate","talk"]},"wing":{"n":"Wing","u":["🪽"],"k":["angel","birds","flying"]},"black_bird":{"n":"Black Bird","u":["🐦‍⬛"],"k":["crow"]},"goose":{"n":"Goose","u":["🪿"],"k":["silly","jemima","goosebumps"]},"frog":{"n":"Frog","u":["🐸"],"k":["animal","nature","croak","toad"]},"crocodile":{"n":"Crocodile","u":["🐊"],"k":["animal","nature","reptile","lizard","alligator"]},"turtle":{"n":"Turtle","u":["🐢"],"k":["animal","slow","nature","tortoise"]},"lizard":{"n":"Lizard","u":["🦎"],"k":["animal","nature","reptile"]},"snake":{"n":"Snake","u":["🐍"],"k":["animal","evil","nature","hiss","python"]},"dragon_face":{"n":"Dragon Face","u":["🐲"],"k":["animal","myth","nature","chinese","green"]},"dragon":{"n":"Dragon","u":["🐉"],"k":["animal","myth","nature","chinese","green"]},"sauropod":{"n":"Sauropod","u":["🦕"],"k":["animal","nature","dinosaur","brachiosaurus","brontosaurus","diplodocus","extinct"]},"t-rex":{"n":"T-Rex","u":["🦖"],"k":["t","rex","animal","nature","dinosaur","tyrannosaurus","extinct"]},"whale":{"n":"Spouting Whale","u":["🐳"],"k":["animal","nature","sea","ocean"]},"whale2":{"n":"Whale","u":["🐋"],"k":["whale2","animal","nature","sea","ocean"]},"dolphin":{"n":"Dolphin","u":["🐬"],"k":["flipper","animal","nature","fish","sea","ocean","fins","beach"]},"seal":{"n":"Seal","u":["🦭"],"k":["animal","creature","sea"]},"fish":{"n":"Fish","u":["🐟"],"k":["animal","food","nature"]},"tropical_fish":{"n":"Tropical Fish","u":["🐠"],"k":["animal","swim","ocean","beach","nemo"]},"blowfish":{"n":"Blowfish","u":["🐡"],"k":["animal","nature","food","sea","ocean"]},"shark":{"n":"Shark","u":["🦈"],"k":["animal","nature","fish","sea","ocean","jaws","fins","beach"]},"octopus":{"n":"Octopus","u":["🐙"],"k":["animal","creature","ocean","sea","nature","beach"]},"shell":{"n":"Spiral Shell","u":["🐚"],"k":["nature","sea","beach"]},"coral":{"n":"Coral","u":["🪸"],"k":["ocean","sea","reef"]},"jellyfish":{"n":"Jellyfish","u":["🪼"],"k":["sting","tentacles"]},"snail":{"n":"Snail","u":["🐌"],"k":["slow","animal","shell"]},"butterfly":{"n":"Butterfly","u":["🦋"],"k":["animal","insect","nature","caterpillar"]},"bug":{"n":"Bug","u":["🐛"],"k":["animal","insect","nature","worm"]},"ant":{"n":"Ant","u":["🐜"],"k":["animal","insect","nature","bug"]},"bee":{"n":"Honeybee","u":["🐝"],"k":["bee","animal","insect","nature","bug","spring","honey"]},"beetle":{"n":"Beetle","u":["🪲"],"k":["insect"]},"ladybug":{"n":"Lady Beetle","u":["🐞"],"k":["ladybug","animal","insect","nature"]},"cricket":{"n":"Cricket","u":["🦗"],"k":["animal","chirp"]},"cockroach":{"n":"Cockroach","u":["🪳"],"k":["insect","pests"]},"spider":{"n":"Spider","u":["🕷️"],"k":["animal","arachnid"]},"spider_web":{"n":"Spider Web","u":["🕸️"],"k":["animal","insect","arachnid","silk"]},"scorpion":{"n":"Scorpion","u":["🦂"],"k":["animal","arachnid"]},"mosquito":{"n":"Mosquito","u":["🦟"],"k":["animal","nature","insect","malaria"]},"fly":{"n":"Fly","u":["🪰"],"k":["insect"]},"worm":{"n":"Worm","u":["🪱"],"k":["animal"]},"microbe":{"n":"Microbe","u":["🦠"],"k":["amoeba","bacteria","germs","virus","covid"]},"bouquet":{"n":"Bouquet","u":["💐"],"k":["flowers","nature","spring"]},"cherry_blossom":{"n":"Cherry Blossom","u":["🌸"],"k":["nature","plant","spring","flower"]},"white_flower":{"n":"White Flower","u":["💮"],"k":["japanese","spring"]},"lotus":{"n":"Lotus","u":["🪷"],"k":["flower","calm","meditation"]},"rosette":{"n":"Rosette","u":["🏵️"],"k":["flower","decoration","military"]},"rose":{"n":"Rose","u":["🌹"],"k":["flowers","valentines","love","spring"]},"wilted_flower":{"n":"Wilted Flower","u":["🥀"],"k":["plant","nature","rose"]},"hibiscus":{"n":"Hibiscus","u":["🌺"],"k":["plant","vegetable","flowers","beach"]},"sunflower":{"n":"Sunflower","u":["🌻"],"k":["nature","plant","fall"]},"blossom":{"n":"Blossom","u":["🌼"],"k":["nature","flowers","yellow"]},"tulip":{"n":"Tulip","u":["🌷"],"k":["flowers","plant","nature","summer","spring"]},"hyacinth":{"n":"Hyacinth","u":["🪻"],"k":["flower","lavender"]},"seedling":{"n":"Seedling","u":["🌱"],"k":["plant","nature","grass","lawn","spring"]},"potted_plant":{"n":"Potted Plant","u":["🪴"],"k":["greenery","house"]},"evergreen_tree":{"n":"Evergreen Tree","u":["🌲"],"k":["plant","nature"]},"deciduous_tree":{"n":"Deciduous Tree","u":["🌳"],"k":["plant","nature"]},"palm_tree":{"n":"Palm Tree","u":["🌴"],"k":["plant","vegetable","nature","summer","beach","mojito","tropical"]},"cactus":{"n":"Cactus","u":["🌵"],"k":["vegetable","plant","nature"]},"ear_of_rice":{"n":"Ear of Rice","u":["🌾"],"k":["sheaf","nature","plant"]},"herb":{"n":"Herb","u":["🌿"],"k":["vegetable","plant","medicine","weed","grass","lawn"]},"shamrock":{"n":"Shamrock","u":["☘️"],"k":["vegetable","plant","nature","irish","clover"]},"four_leaf_clover":{"n":"Four Leaf Clover","u":["🍀"],"k":["vegetable","plant","nature","lucky","irish"]},"maple_leaf":{"n":"Maple Leaf","u":["🍁"],"k":["nature","plant","vegetable","ca","fall"]},"fallen_leaf":{"n":"Fallen Leaf","u":["🍂"],"k":["nature","plant","vegetable","leaves"]},"leaves":{"n":"Leaf Fluttering in Wind","u":["🍃"],"k":["leaves","nature","plant","tree","vegetable","grass","lawn","spring"]},"empty_nest":{"n":"Empty Nest","u":["🪹"],"k":["bird"]},"nest_with_eggs":{"n":"Nest with Eggs","u":["🪺"],"k":["bird"]},"mushroom":{"n":"Mushroom","u":["🍄"],"k":["plant","vegetable"]},"grapes":{"n":"Grapes","u":["🍇"],"k":["fruit","food","wine"]},"melon":{"n":"Melon","u":["🍈"],"k":["fruit","nature","food"]},"watermelon":{"n":"Watermelon","u":["🍉"],"k":["fruit","food","picnic","summer"]},"tangerine":{"n":"Tangerine","u":["🍊"],"k":["food","fruit","nature","orange"]},"lemon":{"n":"Lemon","u":["🍋"],"k":["fruit","nature"]},"banana":{"n":"Banana","u":["🍌"],"k":["fruit","food","monkey"]},"pineapple":{"n":"Pineapple","u":["🍍"],"k":["fruit","nature","food"]},"mango":{"n":"Mango","u":["🥭"],"k":["fruit","food","tropical"]},"apple":{"n":"Red Apple","u":["🍎"],"k":["fruit","mac","school"]},"green_apple":{"n":"Green Apple","u":["🍏"],"k":["fruit","nature"]},"pear":{"n":"Pear","u":["🍐"],"k":["fruit","nature","food"]},"peach":{"n":"Peach","u":["🍑"],"k":["fruit","nature","food"]},"cherries":{"n":"Cherries","u":["🍒"],"k":["food","fruit"]},"strawberry":{"n":"Strawberry","u":["🍓"],"k":["fruit","food","nature"]},"blueberries":{"n":"Blueberries","u":["🫐"],"k":["fruit"]},"kiwifruit":{"n":"Kiwifruit","u":["🥝"],"k":["kiwi","fruit","food"]},"tomato":{"n":"Tomato","u":["🍅"],"k":["fruit","vegetable","nature","food"]},"olive":{"n":"Olive","u":["🫒"],"k":["fruit"]},"coconut":{"n":"Coconut","u":["🥥"],"k":["fruit","nature","food","palm"]},"avocado":{"n":"Avocado","u":["🥑"],"k":["fruit","food"]},"eggplant":{"n":"Eggplant","u":["🍆"],"k":["vegetable","nature","food","aubergine"]},"potato":{"n":"Potato","u":["🥔"],"k":["food","tuber","vegatable","starch"]},"carrot":{"n":"Carrot","u":["🥕"],"k":["vegetable","food","orange"]},"corn":{"n":"Ear of Corn","u":["🌽"],"k":["food","vegetable","plant"]},"hot_pepper":{"n":"Hot Pepper","u":["🌶️"],"k":["food","spicy","chilli","chili"]},"bell_pepper":{"n":"Bell Pepper","u":["🫑"],"k":["fruit","plant"]},"cucumber":{"n":"Cucumber","u":["🥒"],"k":["fruit","food","pickle"]},"leafy_green":{"n":"Leafy Green","u":["🥬"],"k":["food","vegetable","plant","bok","choy","cabbage","kale","lettuce"]},"broccoli":{"n":"Broccoli","u":["🥦"],"k":["fruit","food","vegetable"]},"garlic":{"n":"Garlic","u":["🧄"],"k":["food","spice","cook"]},"onion":{"n":"Onion","u":["🧅"],"k":["cook","food","spice"]},"peanuts":{"n":"Peanuts","u":["🥜"],"k":["food","nut"]},"beans":{"n":"Beans","u":["🫘"],"k":["food"]},"chestnut":{"n":"Chestnut","u":["🌰"],"k":["food","squirrel"]},"ginger_root":{"n":"Ginger Root","u":["🫚"],"k":["spice","yellow","cooking","gingerbread"]},"pea_pod":{"n":"Pea Pod","u":["🫛"],"k":["cozy","green"]},"bread":{"n":"Bread","u":["🍞"],"k":["food","wheat","breakfast","toast"]},"croissant":{"n":"Croissant","u":["🥐"],"k":["food","bread","french"]},"baguette_bread":{"n":"Baguette Bread","u":["🥖"],"k":["food","french","france","bakery"]},"flatbread":{"n":"Flatbread","u":["🫓"],"k":["flour","food","bakery"]},"pretzel":{"n":"Pretzel","u":["🥨"],"k":["food","bread","twisted","germany","bakery"]},"bagel":{"n":"Bagel","u":["🥯"],"k":["food","bread","bakery","schmear","jewish"]},"pancakes":{"n":"Pancakes","u":["🥞"],"k":["food","breakfast","flapjacks","hotcakes","brunch"]},"waffle":{"n":"Waffle","u":["🧇"],"k":["food","breakfast","brunch"]},"cheese_wedge":{"n":"Cheese Wedge","u":["🧀"],"k":["food","chadder","swiss"]},"meat_on_bone":{"n":"Meat on Bone","u":["🍖"],"k":["good","food","drumstick"]},"poultry_leg":{"n":"Poultry Leg","u":["🍗"],"k":["food","meat","drumstick","bird","chicken","turkey"]},"cut_of_meat":{"n":"Cut of Meat","u":["🥩"],"k":["food","cow","chop","lambchop","porkchop"]},"bacon":{"n":"Bacon","u":["🥓"],"k":["food","breakfast","pork","pig","meat","brunch"]},"hamburger":{"n":"Hamburger","u":["🍔"],"k":["meat","fast","food","beef","cheeseburger","mcdonalds","burger","king"]},"fries":{"n":"French Fries","u":["🍟"],"k":["chips","snack","fast","food","potato"]},"pizza":{"n":"Pizza","u":["🍕"],"k":["food","party","italy"]},"hotdog":{"n":"Hot Dog","u":["🌭"],"k":["hotdog","food","frankfurter","america"]},"sandwich":{"n":"Sandwich","u":["🥪"],"k":["food","lunch","bread","toast","bakery"]},"taco":{"n":"Taco","u":["🌮"],"k":["food","mexican"]},"burrito":{"n":"Burrito","u":["🌯"],"k":["food","mexican"]},"tamale":{"n":"Tamale","u":["🫔"],"k":["food","masa"]},"stuffed_flatbread":{"n":"Stuffed Flatbread","u":["🥙"],"k":["food","gyro","mediterranean"]},"falafel":{"n":"Falafel","u":["🧆"],"k":["food","mediterranean"]},"egg":{"n":"Egg","u":["🥚"],"k":["food","chicken","breakfast"]},"fried_egg":{"n":"Cooking","u":["🍳"],"k":["fried","egg","food","breakfast","kitchen","skillet"]},"shallow_pan_of_food":{"n":"Shallow Pan of Food","u":["🥘"],"k":["cooking","casserole","paella","skillet"]},"stew":{"n":"Pot of Food","u":["🍲"],"k":["stew","meat","soup","hot"]},"fondue":{"n":"Fondue","u":["🫕"],"k":["cheese","pot","food"]},"bowl_with_spoon":{"n":"Bowl with Spoon","u":["🥣"],"k":["food","breakfast","cereal","oatmeal","porridge"]},"green_salad":{"n":"Green Salad","u":["🥗"],"k":["food","healthy","lettuce","vegetable"]},"popcorn":{"n":"Popcorn","u":["🍿"],"k":["food","movie","theater","films","snack","drama"]},"butter":{"n":"Butter","u":["🧈"],"k":["food","cook"]},"salt":{"n":"Salt","u":["🧂"],"k":["condiment","shaker"]},"canned_food":{"n":"Canned Food","u":["🥫"],"k":["soup","tomatoes"]},"bento":{"n":"Bento Box","u":["🍱"],"k":["food","japanese","lunch"]},"rice_cracker":{"n":"Rice Cracker","u":["🍘"],"k":["food","japanese","snack"]},"rice_ball":{"n":"Rice Ball","u":["🍙"],"k":["food","japanese"]},"rice":{"n":"Cooked Rice","u":["🍚"],"k":["food","asian"]},"curry":{"n":"Curry Rice","u":["🍛"],"k":["food","spicy","hot","indian"]},"ramen":{"n":"Steaming Bowl","u":["🍜"],"k":["ramen","food","japanese","noodle","chopsticks"]},"spaghetti":{"n":"Spaghetti","u":["🍝"],"k":["food","italian","pasta","noodle"]},"sweet_potato":{"n":"Roasted Sweet Potato","u":["🍠"],"k":["food","nature","plant"]},"oden":{"n":"Oden","u":["🍢"],"k":["food","japanese"]},"sushi":{"n":"Sushi","u":["🍣"],"k":["food","fish","japanese","rice"]},"fried_shrimp":{"n":"Fried Shrimp","u":["🍤"],"k":["food","animal","appetizer","summer"]},"fish_cake":{"n":"Fish Cake with Swirl","u":["🍥"],"k":["food","japan","sea","beach","narutomaki","pink","kamaboko","surimi","ramen"]},"moon_cake":{"n":"Moon Cake","u":["🥮"],"k":["food","autumn","dessert"]},"dango":{"n":"Dango","u":["🍡"],"k":["food","dessert","sweet","japanese","barbecue","meat"]},"dumpling":{"n":"Dumpling","u":["🥟"],"k":["food","empanada","pierogi","potsticker","gyoza"]},"fortune_cookie":{"n":"Fortune Cookie","u":["🥠"],"k":["food","prophecy","dessert"]},"takeout_box":{"n":"Takeout Box","u":["🥡"],"k":["food","leftovers"]},"crab":{"n":"Crab","u":["🦀"],"k":["animal","crustacean"]},"lobster":{"n":"Lobster","u":["🦞"],"k":["animal","nature","bisque","claws","seafood"]},"shrimp":{"n":"Shrimp","u":["🦐"],"k":["animal","ocean","nature","seafood"]},"squid":{"n":"Squid","u":["🦑"],"k":["animal","nature","ocean","sea"]},"oyster":{"n":"Oyster","u":["🦪"],"k":["food"]},"icecream":{"n":"Soft Ice Cream","u":["🍦"],"k":["icecream","food","hot","dessert","summer"]},"shaved_ice":{"n":"Shaved Ice","u":["🍧"],"k":["hot","dessert","summer"]},"ice_cream":{"n":"Ice Cream","u":["🍨"],"k":["food","hot","dessert"]},"doughnut":{"n":"Doughnut","u":["🍩"],"k":["food","dessert","snack","sweet","donut"]},"cookie":{"n":"Cookie","u":["🍪"],"k":["food","snack","oreo","chocolate","sweet","dessert"]},"birthday":{"n":"Birthday Cake","u":["🎂"],"k":["food","dessert"]},"cake":{"n":"Shortcake","u":["🍰"],"k":["cake","food","dessert"]},"cupcake":{"n":"Cupcake","u":["🧁"],"k":["food","dessert","bakery","sweet"]},"pie":{"n":"Pie","u":["🥧"],"k":["food","dessert","pastry"]},"chocolate_bar":{"n":"Chocolate Bar","u":["🍫"],"k":["food","snack","dessert","sweet"]},"candy":{"n":"Candy","u":["🍬"],"k":["snack","dessert","sweet","lolly"]},"lollipop":{"n":"Lollipop","u":["🍭"],"k":["food","snack","candy","sweet"]},"custard":{"n":"Custard","u":["🍮"],"k":["dessert","food"]},"honey_pot":{"n":"Honey Pot","u":["🍯"],"k":["bees","sweet","kitchen"]},"baby_bottle":{"n":"Baby Bottle","u":["🍼"],"k":["food","container","milk"]},"glass_of_milk":{"n":"Glass of Milk","u":["🥛"],"k":["beverage","drink","cow"]},"coffee":{"n":"Hot Beverage","u":["☕"],"k":["coffee","caffeine","latte","espresso","mug"]},"teapot":{"n":"Teapot","u":["🫖"],"k":["drink","hot"]},"tea":{"n":"Teacup Without Handle","u":["🍵"],"k":["tea","drink","bowl","breakfast","green","british"]},"sake":{"n":"Sake","u":["🍶"],"k":["wine","drink","drunk","beverage","japanese","alcohol","booze"]},"champagne":{"n":"Bottle with Popping Cork","u":["🍾"],"k":["champagne","drink","wine","celebration"]},"wine_glass":{"n":"Wine Glass","u":["🍷"],"k":["drink","beverage","drunk","alcohol","booze"]},"cocktail":{"n":"Cocktail Glass","u":["🍸"],"k":["drink","drunk","alcohol","beverage","booze","mojito"]},"tropical_drink":{"n":"Tropical Drink","u":["🍹"],"k":["beverage","cocktail","summer","beach","alcohol","booze","mojito"]},"beer":{"n":"Beer Mug","u":["🍺"],"k":["relax","beverage","drink","drunk","party","pub","summer","alcohol","booze"]},"beers":{"n":"Clinking Beer Mugs","u":["🍻"],"k":["beers","relax","beverage","drink","drunk","party","pub","summer","alcohol","booze"]},"clinking_glasses":{"n":"Clinking Glasses","u":["🥂"],"k":["beverage","drink","party","alcohol","celebrate","cheers","wine","champagne","toast"]},"tumbler_glass":{"n":"Tumbler Glass","u":["🥃"],"k":["drink","beverage","drunk","alcohol","liquor","booze","bourbon","scotch","whisky","shot"]},"pouring_liquid":{"n":"Pouring Liquid","u":["🫗"],"k":["cup","water"]},"cup_with_straw":{"n":"Cup with Straw","u":["🥤"],"k":["drink","soda"]},"bubble_tea":{"n":"Bubble Tea","u":["🧋"],"k":["taiwan","boba","milk","straw"]},"beverage_box":{"n":"Beverage Box","u":["🧃"],"k":["drink"]},"mate_drink":{"n":"Mate","u":["🧉"],"k":["drink","tea","beverage"]},"ice_cube":{"n":"Ice","u":["🧊"],"k":["cube","water","cold"]},"chopsticks":{"n":"Chopsticks","u":["🥢"],"k":["food"]},"knife_fork_plate":{"n":"Fork and Knife with Plate","u":["🍽️"],"k":["food","eat","meal","lunch","dinner","restaurant"]},"fork_and_knife":{"n":"Fork and Knife","u":["🍴"],"k":["cutlery","kitchen"]},"spoon":{"n":"Spoon","u":["🥄"],"k":["cutlery","kitchen","tableware"]},"hocho":{"n":"Hocho","u":["🔪"],"k":["knife","kitchen","blade","cutlery","weapon"]},"jar":{"n":"Jar","u":["🫙"],"k":["container","sauce"]},"amphora":{"n":"Amphora","u":["🏺"],"k":["vase","jar"]},"jack_o_lantern":{"n":"Jack-O-Lantern","u":["🎃"],"k":["jack","o","lantern","halloween","light","pumpkin","creepy","fall"]},"christmas_tree":{"n":"Christmas Tree","u":["🎄"],"k":["festival","vacation","december","xmas","celebration"]},"fireworks":{"n":"Fireworks","u":["🎆"],"k":["photo","festival","carnival","congratulations"]},"sparkler":{"n":"Sparkler","u":["🎇"],"k":["stars","night","shine"]},"firecracker":{"n":"Firecracker","u":["🧨"],"k":["dynamite","boom","explode","explosion","explosive"]},"sparkles":{"n":"Sparkles","u":["✨"],"k":["stars","shine","shiny","cool","awesome","good","magic"]},"balloon":{"n":"Balloon","u":["🎈"],"k":["party","celebration","birthday","circus"]},"tada":{"n":"Party Popper","u":["🎉"],"k":["tada","congratulations","birthday","magic","circus","celebration"]},"confetti_ball":{"n":"Confetti Ball","u":["🎊"],"k":["festival","party","birthday","circus"]},"tanabata_tree":{"n":"Tanabata Tree","u":["🎋"],"k":["plant","nature","branch","summer","bamboo","wish","star","festival","tanzaku"]},"bamboo":{"n":"Pine Decoration","u":["🎍"],"k":["bamboo","japanese","plant","nature","vegetable","panda","new","years"]},"dolls":{"n":"Japanese Dolls","u":["🎎"],"k":["toy","kimono"]},"flags":{"n":"Carp Streamer","u":["🎏"],"k":["flags","fish","japanese","koinobori","banner"]},"wind_chime":{"n":"Wind Chime","u":["🎐"],"k":["nature","ding","spring","bell"]},"rice_scene":{"n":"Moon Viewing Ceremony","u":["🎑"],"k":["rice","scene","photo","japan","asia","tsukimi"]},"red_envelope":{"n":"Red Envelope","u":["🧧"],"k":["gift"]},"ribbon":{"n":"Ribbon","u":["🎀"],"k":["decoration","pink","girl","bowtie"]},"gift":{"n":"Wrapped Gift","u":["🎁"],"k":["present","birthday","christmas","xmas"]},"reminder_ribbon":{"n":"Reminder Ribbon","u":["🎗️"],"k":["sports","cause","support","awareness"]},"admission_tickets":{"n":"Admission Tickets","u":["🎟️"],"k":["sports","concert","entrance"]},"ticket":{"n":"Ticket","u":["🎫"],"k":["event","concert","pass"]},"medal":{"n":"Military Medal","u":["🎖️"],"k":["award","winning","army"]},"trophy":{"n":"Trophy","u":["🏆"],"k":["win","award","contest","place","ftw","ceremony"]},"sports_medal":{"n":"Sports Medal","u":["🏅"],"k":["award","winning"]},"first_place_medal":{"n":"1st Place Medal","u":["🥇"],"k":["first","award","winning"]},"second_place_medal":{"n":"2nd Place Medal","u":["🥈"],"k":["second","award"]},"third_place_medal":{"n":"3rd Place Medal","u":["🥉"],"k":["third","award"]},"soccer":{"n":"Soccer Ball","u":["⚽"],"k":["sports","football"]},"baseball":{"n":"Baseball","u":["⚾"],"k":["sports","balls"]},"softball":{"n":"Softball","u":["🥎"],"k":["sports","balls"]},"basketball":{"n":"Basketball","u":["🏀"],"k":["sports","balls","NBA"]},"volleyball":{"n":"Volleyball","u":["🏐"],"k":["sports","balls"]},"football":{"n":"American Football","u":["🏈"],"k":["sports","balls","NFL"]},"rugby_football":{"n":"Rugby Football","u":["🏉"],"k":["sports","team"]},"tennis":{"n":"Tennis","u":["🎾"],"k":["sports","balls","green"]},"flying_disc":{"n":"Flying Disc","u":["🥏"],"k":["sports","frisbee","ultimate"]},"bowling":{"n":"Bowling","u":["🎳"],"k":["sports","fun","play"]},"cricket_bat_and_ball":{"n":"Cricket Game","u":["🏏"],"k":["bat","and","ball","sports"]},"field_hockey_stick_and_ball":{"n":"Field Hockey","u":["🏑"],"k":["stick","and","ball","sports"]},"ice_hockey_stick_and_puck":{"n":"Ice Hockey","u":["🏒"],"k":["stick","and","puck","sports"]},"lacrosse":{"n":"Lacrosse","u":["🥍"],"k":["sports","ball","stick"]},"table_tennis_paddle_and_ball":{"n":"Ping Pong","u":["🏓"],"k":["table","tennis","paddle","and","ball","sports","pingpong"]},"badminton_racquet_and_shuttlecock":{"n":"Badminton","u":["🏸"],"k":["racquet","and","shuttlecock","sports"]},"boxing_glove":{"n":"Boxing Glove","u":["🥊"],"k":["sports","fighting"]},"martial_arts_uniform":{"n":"Martial Arts Uniform","u":["🥋"],"k":["judo","karate","taekwondo"]},"goal_net":{"n":"Goal Net","u":["🥅"],"k":["sports"]},"golf":{"n":"Flag in Hole","u":["⛳"],"k":["golf","sports","business","summer"]},"ice_skate":{"n":"Ice Skate","u":["⛸️"],"k":["sports"]},"fishing_pole_and_fish":{"n":"Fishing Pole","u":["🎣"],"k":["and","fish","food","hobby","summer"]},"diving_mask":{"n":"Diving Mask","u":["🤿"],"k":["sport","ocean"]},"running_shirt_with_sash":{"n":"Running Shirt","u":["🎽"],"k":["with","sash","play","pageant"]},"ski":{"n":"Skis","u":["🎿"],"k":["ski","sports","winter","cold","snow"]},"sled":{"n":"Sled","u":["🛷"],"k":["sleigh","luge","toboggan"]},"curling_stone":{"n":"Curling Stone","u":["🥌"],"k":["sports"]},"dart":{"n":"Bullseye","u":["🎯"],"k":["dart","direct","hit","game","play","bar","target"]},"yo-yo":{"n":"Yo-Yo","u":["🪀"],"k":["yo","toy"]},"kite":{"n":"Kite","u":["🪁"],"k":["wind","fly"]},"gun":{"n":"Pistol","u":["🔫"],"k":["gun","violence","weapon","revolver"]},"8ball":{"n":"Billiards","u":["🎱"],"k":["8ball","pool","8","ball","hobby","game","luck","magic"]},"crystal_ball":{"n":"Crystal Ball","u":["🔮"],"k":["disco","party","magic","circus","fortune","teller"]},"magic_wand":{"n":"Magic Wand","u":["🪄"],"k":["supernature","power"]},"video_game":{"n":"Video Game","u":["🎮"],"k":["play","console","PS4","controller"]},"joystick":{"n":"Joystick","u":["🕹️"],"k":["game","play"]},"slot_machine":{"n":"Slot Machine","u":["🎰"],"k":["bet","gamble","vegas","fruit","luck","casino"]},"game_die":{"n":"Game Die","u":["🎲"],"k":["dice","random","tabletop","play","luck"]},"jigsaw":{"n":"Puzzle Piece","u":["🧩"],"k":["jigsaw","interlocking"]},"teddy_bear":{"n":"Teddy Bear","u":["🧸"],"k":["plush","stuffed"]},"pinata":{"n":"Pinata","u":["🪅"],"k":["mexico","candy","celebration"]},"mirror_ball":{"n":"Mirror Ball","u":["🪩"],"k":["disco","dance","party"]},"nesting_dolls":{"n":"Nesting Dolls","u":["🪆"],"k":["matryoshka","toy"]},"spades":{"n":"Spade Suit","u":["♠️"],"k":["spades","poker","cards","suits","magic"]},"hearts":{"n":"Heart Suit","u":["♥️"],"k":["hearts","poker","cards","magic","suits"]},"diamonds":{"n":"Diamond Suit","u":["♦️"],"k":["diamonds","poker","cards","magic","suits"]},"clubs":{"n":"Club Suit","u":["♣️"],"k":["clubs","poker","cards","magic","suits"]},"chess_pawn":{"n":"Chess Pawn","u":["♟️"],"k":["expendable"]},"black_joker":{"n":"Joker","u":["🃏"],"k":["black","poker","cards","game","play","magic"]},"mahjong":{"n":"Mahjong Red Dragon","u":["🀄"],"k":["game","play","chinese","kanji"]},"flower_playing_cards":{"n":"Flower Playing Cards","u":["🎴"],"k":["game","sunset","red"]},"performing_arts":{"n":"Performing Arts","u":["🎭"],"k":["acting","theater","drama"]},"frame_with_picture":{"n":"Framed Picture","u":["🖼️"],"k":["frame","with","photography"]},"art":{"n":"Artist Palette","u":["🎨"],"k":["art","design","paint","draw","colors"]},"thread":{"n":"Thread","u":["🧵"],"k":["needle","sewing","spool","string"]},"sewing_needle":{"n":"Sewing Needle","u":["🪡"],"k":["stitches"]},"yarn":{"n":"Yarn","u":["🧶"],"k":["ball","crochet","knit"]},"knot":{"n":"Knot","u":["🪢"],"k":["rope","scout"]},"earth_africa":{"n":"Earth Globe Europe-Africa","u":["🌍"],"k":["africa","showing","europe","world","international"]},"earth_americas":{"n":"Earth Globe Americas","u":["🌎"],"k":["showing","world","USA","international"]},"earth_asia":{"n":"Earth Globe Asia-Australia","u":["🌏"],"k":["asia","showing","australia","world","east","international"]},"globe_with_meridians":{"n":"Globe with Meridians","u":["🌐"],"k":["earth","international","world","internet","interweb","i18n"]},"world_map":{"n":"World Map","u":["🗺️"],"k":["location","direction"]},"japan":{"n":"Map of Japan","u":["🗾"],"k":["nation","country","japanese","asia"]},"compass":{"n":"Compass","u":["🧭"],"k":["magnetic","navigation","orienteering"]},"snow_capped_mountain":{"n":"Snow-Capped Mountain","u":["🏔️"],"k":["snow","capped","photo","nature","environment","winter","cold"]},"mountain":{"n":"Mountain","u":["⛰️"],"k":["photo","nature","environment"]},"volcano":{"n":"Volcano","u":["🌋"],"k":["photo","nature","disaster"]},"mount_fuji":{"n":"Mount Fuji","u":["🗻"],"k":["photo","mountain","nature","japanese"]},"camping":{"n":"Camping","u":["🏕️"],"k":["photo","outdoors","tent"]},"beach_with_umbrella":{"n":"Beach with Umbrella","u":["🏖️"],"k":["weather","summer","sunny","sand","mojito"]},"desert":{"n":"Desert","u":["🏜️"],"k":["photo","warm","saharah"]},"desert_island":{"n":"Desert Island","u":["🏝️"],"k":["photo","tropical","mojito"]},"national_park":{"n":"National Park","u":["🏞️"],"k":["photo","environment","nature"]},"stadium":{"n":"Stadium","u":["🏟️"],"k":["photo","place","sports","concert","venue"]},"classical_building":{"n":"Classical Building","u":["🏛️"],"k":["art","culture","history"]},"building_construction":{"n":"Building Construction","u":["🏗️"],"k":["wip","working","progress"]},"bricks":{"n":"Brick","u":["🧱"],"k":["bricks"]},"rock":{"n":"Rock","u":["🪨"],"k":["stone"]},"wood":{"n":"Wood","u":["🪵"],"k":["nature","timber","trunk"]},"hut":{"n":"Hut","u":["🛖"],"k":["house","structure"]},"house_buildings":{"n":"Houses","u":["🏘️"],"k":["house","buildings","photo"]},"derelict_house_building":{"n":"Derelict House","u":["🏚️"],"k":["building","abandon","evict","broken"]},"house":{"n":"House","u":["🏠"],"k":["building","home"]},"house_with_garden":{"n":"House with Garden","u":["🏡"],"k":["home","plant","nature"]},"office":{"n":"Office Building","u":["🏢"],"k":["bureau","work"]},"post_office":{"n":"Japanese Post Office","u":["🏣"],"k":["building","envelope","communication"]},"european_post_office":{"n":"Post Office","u":["🏤"],"k":["european","building","email"]},"hospital":{"n":"Hospital","u":["🏥"],"k":["building","health","surgery","doctor"]},"bank":{"n":"Bank","u":["🏦"],"k":["building","money","sales","cash","business","enterprise"]},"hotel":{"n":"Hotel","u":["🏨"],"k":["building","accomodation","checkin"]},"love_hotel":{"n":"Love Hotel","u":["🏩"],"k":["like","affection","dating"]},"convenience_store":{"n":"Convenience Store","u":["🏪"],"k":["building","shopping","groceries"]},"school":{"n":"School","u":["🏫"],"k":["building","student","education","learn","teach"]},"department_store":{"n":"Department Store","u":["🏬"],"k":["building","shopping","mall"]},"factory":{"n":"Factory","u":["🏭"],"k":["building","industry","pollution","smoke"]},"japanese_castle":{"n":"Japanese Castle","u":["🏯"],"k":["photo","building"]},"european_castle":{"n":"Castle","u":["🏰"],"k":["european","building","royalty","history"]},"wedding":{"n":"Wedding","u":["💒"],"k":["love","like","affection","couple","marriage","bride","groom"]},"tokyo_tower":{"n":"Tokyo Tower","u":["🗼"],"k":["photo","japanese"]},"statue_of_liberty":{"n":"Statue of Liberty","u":["🗽"],"k":["american","newyork"]},"church":{"n":"Church","u":["⛪"],"k":["building","religion","christ"]},"mosque":{"n":"Mosque","u":["🕌"],"k":["islam","worship","minaret"]},"hindu_temple":{"n":"Hindu Temple","u":["🛕"],"k":["religion"]},"synagogue":{"n":"Synagogue","u":["🕍"],"k":["judaism","worship","temple","jewish"]},"shinto_shrine":{"n":"Shinto Shrine","u":["⛩️"],"k":["temple","japan","kyoto"]},"kaaba":{"n":"Kaaba","u":["🕋"],"k":["mecca","mosque","islam"]},"fountain":{"n":"Fountain","u":["⛲"],"k":["photo","summer","water","fresh"]},"tent":{"n":"Tent","u":["⛺"],"k":["photo","camping","outdoors"]},"foggy":{"n":"Foggy","u":["🌁"],"k":["photo","mountain"]},"night_with_stars":{"n":"Night with Stars","u":["🌃"],"k":["evening","city","downtown"]},"cityscape":{"n":"Cityscape","u":["🏙️"],"k":["photo","night","life","urban"]},"sunrise_over_mountains":{"n":"Sunrise over Mountains","u":["🌄"],"k":["view","vacation","photo"]},"sunrise":{"n":"Sunrise","u":["🌅"],"k":["morning","view","vacation","photo"]},"city_sunset":{"n":"Cityscape at Dusk","u":["🌆"],"k":["city","sunset","photo","evening","sky","buildings"]},"city_sunrise":{"n":"Sunset","u":["🌇"],"k":["city","sunrise","photo","good","morning","dawn"]},"bridge_at_night":{"n":"Bridge at Night","u":["🌉"],"k":["photo","sanfrancisco"]},"hotsprings":{"n":"Hot Springs","u":["♨️"],"k":["hotsprings","bath","warm","relax"]},"carousel_horse":{"n":"Carousel Horse","u":["🎠"],"k":["photo","carnival"]},"playground_slide":{"n":"Playground Slide","u":["🛝"],"k":["fun","park"]},"ferris_wheel":{"n":"Ferris Wheel","u":["🎡"],"k":["photo","carnival","londoneye"]},"roller_coaster":{"n":"Roller Coaster","u":["🎢"],"k":["carnival","playground","photo","fun"]},"barber":{"n":"Barber Pole","u":["💈"],"k":["hair","salon","style"]},"circus_tent":{"n":"Circus Tent","u":["🎪"],"k":["festival","carnival","party"]},"steam_locomotive":{"n":"Locomotive","u":["🚂"],"k":["steam","transportation","vehicle","train"]},"railway_car":{"n":"Railway Car","u":["🚃"],"k":["transportation","vehicle"]},"bullettrain_side":{"n":"High-Speed Train","u":["🚄"],"k":["bullettrain","side","high","speed","transportation","vehicle"]},"bullettrain_front":{"n":"Bullet Train","u":["🚅"],"k":["bullettrain","front","transportation","vehicle","speed","fast","public","travel"]},"train2":{"n":"Train","u":["🚆"],"k":["train2","transportation","vehicle"]},"metro":{"n":"Metro","u":["🚇"],"k":["transportation","blue","square","mrt","underground","tube"]},"light_rail":{"n":"Light Rail","u":["🚈"],"k":["transportation","vehicle"]},"station":{"n":"Station","u":["🚉"],"k":["transportation","vehicle","public"]},"tram":{"n":"Tram","u":["🚊"],"k":["transportation","vehicle"]},"monorail":{"n":"Monorail","u":["🚝"],"k":["transportation","vehicle"]},"mountain_railway":{"n":"Mountain Railway","u":["🚞"],"k":["transportation","vehicle"]},"train":{"n":"Tram Car","u":["🚋"],"k":["train","transportation","vehicle","carriage","public","travel"]},"bus":{"n":"Bus","u":["🚌"],"k":["car","vehicle","transportation"]},"oncoming_bus":{"n":"Oncoming Bus","u":["🚍"],"k":["vehicle","transportation"]},"trolleybus":{"n":"Trolleybus","u":["🚎"],"k":["bart","transportation","vehicle"]},"minibus":{"n":"Minibus","u":["🚐"],"k":["vehicle","car","transportation"]},"ambulance":{"n":"Ambulance","u":["🚑"],"k":["health","911","hospital"]},"fire_engine":{"n":"Fire Engine","u":["🚒"],"k":["transportation","cars","vehicle"]},"police_car":{"n":"Police Car","u":["🚓"],"k":["vehicle","cars","transportation","law","legal","enforcement"]},"oncoming_police_car":{"n":"Oncoming Police Car","u":["🚔"],"k":["vehicle","law","legal","enforcement","911"]},"taxi":{"n":"Taxi","u":["🚕"],"k":["uber","vehicle","cars","transportation"]},"oncoming_taxi":{"n":"Oncoming Taxi","u":["🚖"],"k":["vehicle","cars","uber"]},"car":{"n":"Automobile","u":["🚗"],"k":["car","red","transportation","vehicle"]},"oncoming_automobile":{"n":"Oncoming Automobile","u":["🚘"],"k":["car","vehicle","transportation"]},"blue_car":{"n":"Recreational Vehicle","u":["🚙"],"k":["blue","car","sport","utility","transportation"]},"pickup_truck":{"n":"Pickup Truck","u":["🛻"],"k":["car","transportation"]},"truck":{"n":"Delivery Truck","u":["🚚"],"k":["cars","transportation"]},"articulated_lorry":{"n":"Articulated Lorry","u":["🚛"],"k":["vehicle","cars","transportation","express"]},"tractor":{"n":"Tractor","u":["🚜"],"k":["vehicle","car","farming","agriculture"]},"racing_car":{"n":"Racing Car","u":["🏎️"],"k":["sports","race","fast","formula","f1"]},"racing_motorcycle":{"n":"Motorcycle","u":["🏍️"],"k":["racing","race","sports","fast"]},"motor_scooter":{"n":"Motor Scooter","u":["🛵"],"k":["vehicle","vespa","sasha"]},"manual_wheelchair":{"n":"Manual Wheelchair","u":["🦽"],"k":["accessibility"]},"motorized_wheelchair":{"n":"Motorized Wheelchair","u":["🦼"],"k":["accessibility"]},"auto_rickshaw":{"n":"Auto Rickshaw","u":["🛺"],"k":["move","transportation"]},"bike":{"n":"Bicycle","u":["🚲"],"k":["bike","sports","exercise","hipster"]},"scooter":{"n":"Scooter","u":["🛴"],"k":["kick","vehicle","razor"]},"skateboard":{"n":"Skateboard","u":["🛹"],"k":["board"]},"roller_skate":{"n":"Roller Skate","u":["🛼"],"k":["footwear","sports"]},"busstop":{"n":"Bus Stop","u":["🚏"],"k":["busstop","transportation","wait"]},"motorway":{"n":"Motorway","u":["🛣️"],"k":["road","cupertino","interstate","highway"]},"railway_track":{"n":"Railway Track","u":["🛤️"],"k":["train","transportation"]},"oil_drum":{"n":"Oil Drum","u":["🛢️"],"k":["barrell"]},"fuelpump":{"n":"Fuel Pump","u":["⛽"],"k":["fuelpump","gas","station","petroleum"]},"wheel":{"n":"Wheel","u":["🛞"],"k":["car","transport"]},"rotating_light":{"n":"Police Car Light","u":["🚨"],"k":["rotating","ambulance","911","emergency","alert","error","pinged","law","legal"]},"traffic_light":{"n":"Horizontal Traffic Light","u":["🚥"],"k":["transportation","signal"]},"vertical_traffic_light":{"n":"Vertical Traffic Light","u":["🚦"],"k":["transportation","driving"]},"octagonal_sign":{"n":"Stop Sign","u":["🛑"],"k":["octagonal"]},"construction":{"n":"Construction","u":["🚧"],"k":["wip","progress","caution","warning"]},"anchor":{"n":"Anchor","u":["⚓"],"k":["ship","ferry","sea","boat"]},"ring_buoy":{"n":"Ring Buoy","u":["🛟"],"k":["life","saver","preserver"]},"boat":{"n":"Sailboat","u":["⛵"],"k":["boat","ship","summer","transportation","water","sailing"]},"canoe":{"n":"Canoe","u":["🛶"],"k":["boat","paddle","water","ship"]},"speedboat":{"n":"Speedboat","u":["🚤"],"k":["ship","transportation","vehicle","summer"]},"passenger_ship":{"n":"Passenger Ship","u":["🛳️"],"k":["yacht","cruise","ferry"]},"ferry":{"n":"Ferry","u":["⛴️"],"k":["boat","ship","yacht"]},"motor_boat":{"n":"Motor Boat","u":["🛥️"],"k":["ship"]},"ship":{"n":"Ship","u":["🚢"],"k":["transportation","titanic","deploy"]},"airplane":{"n":"Airplane","u":["✈️"],"k":["vehicle","transportation","flight","fly"]},"small_airplane":{"n":"Small Airplane","u":["🛩️"],"k":["flight","transportation","fly","vehicle"]},"airplane_departure":{"n":"Airplane Departure","u":["🛫"],"k":["airport","flight","landing"]},"airplane_arriving":{"n":"Airplane Arrival","u":["🛬"],"k":["arriving","airport","flight","boarding"]},"parachute":{"n":"Parachute","u":["🪂"],"k":["fly","glide"]},"seat":{"n":"Seat","u":["💺"],"k":["sit","airplane","transport","bus","flight","fly"]},"helicopter":{"n":"Helicopter","u":["🚁"],"k":["transportation","vehicle","fly"]},"suspension_railway":{"n":"Suspension Railway","u":["🚟"],"k":["vehicle","transportation"]},"mountain_cableway":{"n":"Mountain Cableway","u":["🚠"],"k":["transportation","vehicle","ski"]},"aerial_tramway":{"n":"Aerial Tramway","u":["🚡"],"k":["transportation","vehicle","ski"]},"satellite":{"n":"Satellite","u":["🛰️"],"k":["communication","gps","orbit","spaceflight","NASA","ISS"]},"rocket":{"n":"Rocket","u":["🚀"],"k":["launch","ship","staffmode","NASA","outer","space","fly"]},"flying_saucer":{"n":"Flying Saucer","u":["🛸"],"k":["transportation","vehicle","ufo"]},"bellhop_bell":{"n":"Bellhop Bell","u":["🛎️"],"k":["service"]},"luggage":{"n":"Luggage","u":["🧳"],"k":["packing","travel"]},"hourglass":{"n":"Hourglass","u":["⌛"],"k":["done","time","clock","oldschool","limit","exam","quiz","test"]},"hourglass_flowing_sand":{"n":"Hourglass Not Done","u":["⏳"],"k":["flowing","sand","oldschool","time","countdown"]},"watch":{"n":"Watch","u":["⌚"],"k":["time","accessories"]},"alarm_clock":{"n":"Alarm Clock","u":["⏰"],"k":["time","wake"]},"stopwatch":{"n":"Stopwatch","u":["⏱️"],"k":["time","deadline"]},"timer_clock":{"n":"Timer Clock","u":["⏲️"],"k":["alarm"]},"mantelpiece_clock":{"n":"Mantelpiece Clock","u":["🕰️"],"k":["time"]},"clock12":{"n":"Twelve O’clock","u":["🕛"],"k":["clock12","o","clock","12","00:00","0000","12:00","1200","time","noon","midnight","midday","late","early","schedule"]},"clock1230":{"n":"Twelve-Thirty","u":["🕧"],"k":["clock1230","twelve","thirty","00:30","0030","12:30","1230","time","late","early","schedule"]},"clock1":{"n":"One O’clock","u":["🕐"],"k":["clock1","o","clock","1","1:00","100","13:00","1300","time","late","early","schedule"]},"clock130":{"n":"One-Thirty","u":["🕜"],"k":["clock130","one","thirty","1:30","130","13:30","1330","time","late","early","schedule"]},"clock2":{"n":"Two O’clock","u":["🕑"],"k":["clock2","o","clock","2","2:00","200","14:00","1400","time","late","early","schedule"]},"clock230":{"n":"Two-Thirty","u":["🕝"],"k":["clock230","two","thirty","2:30","230","14:30","1430","time","late","early","schedule"]},"clock3":{"n":"Three O’clock","u":["🕒"],"k":["clock3","o","clock","3","3:00","300","15:00","1500","time","late","early","schedule"]},"clock330":{"n":"Three-Thirty","u":["🕞"],"k":["clock330","three","thirty","3:30","330","15:30","1530","time","late","early","schedule"]},"clock4":{"n":"Four O’clock","u":["🕓"],"k":["clock4","o","clock","4","4:00","400","16:00","1600","time","late","early","schedule"]},"clock430":{"n":"Four-Thirty","u":["🕟"],"k":["clock430","four","thirty","4:30","430","16:30","1630","time","late","early","schedule"]},"clock5":{"n":"Five O’clock","u":["🕔"],"k":["clock5","o","clock","5","5:00","500","17:00","1700","time","late","early","schedule"]},"clock530":{"n":"Five-Thirty","u":["🕠"],"k":["clock530","five","thirty","5:30","530","17:30","1730","time","late","early","schedule"]},"clock6":{"n":"Six O’clock","u":["🕕"],"k":["clock6","o","clock","6","6:00","600","18:00","1800","time","late","early","schedule","dawn","dusk"]},"clock630":{"n":"Six-Thirty","u":["🕡"],"k":["clock630","six","thirty","6:30","630","18:30","1830","time","late","early","schedule"]},"clock7":{"n":"Seven O’clock","u":["🕖"],"k":["clock7","o","clock","7","7:00","700","19:00","1900","time","late","early","schedule"]},"clock730":{"n":"Seven-Thirty","u":["🕢"],"k":["clock730","seven","thirty","7:30","730","19:30","1930","time","late","early","schedule"]},"clock8":{"n":"Eight O’clock","u":["🕗"],"k":["clock8","o","clock","8","8:00","800","20:00","2000","time","late","early","schedule"]},"clock830":{"n":"Eight-Thirty","u":["🕣"],"k":["clock830","eight","thirty","8:30","830","20:30","2030","time","late","early","schedule"]},"clock9":{"n":"Nine O’clock","u":["🕘"],"k":["clock9","o","clock","9","9:00","900","21:00","2100","time","late","early","schedule"]},"clock930":{"n":"Nine-Thirty","u":["🕤"],"k":["clock930","nine","thirty","9:30","930","21:30","2130","time","late","early","schedule"]},"clock10":{"n":"Ten O’clock","u":["🕙"],"k":["clock10","o","clock","10","10:00","1000","22:00","2200","time","late","early","schedule"]},"clock1030":{"n":"Ten-Thirty","u":["🕥"],"k":["clock1030","ten","thirty","10:30","1030","22:30","2230","time","late","early","schedule"]},"clock11":{"n":"Eleven O’clock","u":["🕚"],"k":["clock11","o","clock","11","11:00","1100","23:00","2300","time","late","early","schedule"]},"clock1130":{"n":"Eleven-Thirty","u":["🕦"],"k":["clock1130","eleven","thirty","11:30","1130","23:30","2330","time","late","early","schedule"]},"new_moon":{"n":"New Moon","u":["🌑"],"k":["nature","twilight","planet","space","night","evening","sleep"]},"waxing_crescent_moon":{"n":"Waxing Crescent Moon","u":["🌒"],"k":["nature","twilight","planet","space","night","evening","sleep"]},"first_quarter_moon":{"n":"First Quarter Moon","u":["🌓"],"k":["nature","twilight","planet","space","night","evening","sleep"]},"moon":{"n":"Waxing Gibbous Moon","u":["🌔"],"k":["nature","night","sky","gray","twilight","planet","space","evening","sleep"]},"full_moon":{"n":"Full Moon","u":["🌕"],"k":["nature","yellow","twilight","planet","space","night","evening","sleep"]},"waning_gibbous_moon":{"n":"Waning Gibbous Moon","u":["🌖"],"k":["nature","twilight","planet","space","night","evening","sleep","waxing"]},"last_quarter_moon":{"n":"Last Quarter Moon","u":["🌗"],"k":["nature","twilight","planet","space","night","evening","sleep"]},"waning_crescent_moon":{"n":"Waning Crescent Moon","u":["🌘"],"k":["nature","twilight","planet","space","night","evening","sleep"]},"crescent_moon":{"n":"Crescent Moon","u":["🌙"],"k":["night","sleep","sky","evening","magic"]},"new_moon_with_face":{"n":"New Moon Face","u":["🌚"],"k":["with","nature","twilight","planet","space","night","evening","sleep"]},"first_quarter_moon_with_face":{"n":"First Quarter Moon Face","u":["🌛"],"k":["with","nature","twilight","planet","space","night","evening","sleep"]},"last_quarter_moon_with_face":{"n":"Last Quarter Moon Face","u":["🌜"],"k":["with","nature","twilight","planet","space","night","evening","sleep"]},"thermometer":{"n":"Thermometer","u":["🌡️"],"k":["weather","temperature","hot","cold"]},"sunny":{"n":"Sun","u":["☀️"],"k":["sunny","weather","nature","brightness","summer","beach","spring"]},"full_moon_with_face":{"n":"Full Moon Face","u":["🌝"],"k":["with","nature","twilight","planet","space","night","evening","sleep"]},"sun_with_face":{"n":"Sun with Face","u":["🌞"],"k":["nature","morning","sky"]},"ringed_planet":{"n":"Ringed Planet","u":["🪐"],"k":["outerspace"]},"star":{"n":"Star","u":["⭐"],"k":["night","yellow"]},"star2":{"n":"Glowing Star","u":["🌟"],"k":["star2","night","sparkle","awesome","good","magic"]},"stars":{"n":"Shooting Star","u":["🌠"],"k":["stars","night","photo"]},"milky_way":{"n":"Milky Way","u":["🌌"],"k":["photo","space","stars"]},"cloud":{"n":"Cloud","u":["☁️"],"k":["weather","sky"]},"partly_sunny":{"n":"Sun Behind Cloud","u":["⛅"],"k":["partly","sunny","weather","nature","cloudy","morning","fall","spring"]},"thunder_cloud_and_rain":{"n":"Cloud with Lightning and Rain","u":["⛈️"],"k":["thunder","weather"]},"mostly_sunny":{"n":"Sun Behind Small Cloud","u":["🌤️"],"k":["mostly","sunny","weather"]},"barely_sunny":{"n":"Sun Behind Large Cloud","u":["🌥️"],"k":["barely","sunny","weather"]},"partly_sunny_rain":{"n":"Sun Behind Rain Cloud","u":["🌦️"],"k":["partly","sunny","weather"]},"rain_cloud":{"n":"Cloud with Rain","u":["🌧️"],"k":["weather"]},"snow_cloud":{"n":"Cloud with Snow","u":["🌨️"],"k":["weather"]},"lightning":{"n":"Cloud with Lightning","u":["🌩️"],"k":["weather","thunder"]},"tornado":{"n":"Tornado","u":["🌪️"],"k":["cloud","weather","cyclone","twister"]},"fog":{"n":"Fog","u":["🌫️"],"k":["weather"]},"wind_blowing_face":{"n":"Wind Face","u":["🌬️"],"k":["blowing","gust","air"]},"cyclone":{"n":"Cyclone","u":["🌀"],"k":["weather","swirl","blue","cloud","vortex","spiral","whirlpool","spin","tornado","hurricane","typhoon"]},"rainbow":{"n":"Rainbow","u":["🌈"],"k":["nature","happy","unicorn","face","photo","sky","spring"]},"closed_umbrella":{"n":"Closed Umbrella","u":["🌂"],"k":["weather","rain","drizzle"]},"umbrella":{"n":"Umbrella","u":["☂️"],"k":["weather","spring"]},"umbrella_with_rain_drops":{"n":"Umbrella with Rain Drops","u":["☔"],"k":["rainy","weather","spring"]},"umbrella_on_ground":{"n":"Umbrella on Ground","u":["⛱️"],"k":["weather","summer"]},"zap":{"n":"High Voltage","u":["⚡"],"k":["zap","thunder","weather","lightning","bolt","fast"]},"snowflake":{"n":"Snowflake","u":["❄️"],"k":["winter","season","cold","weather","christmas","xmas"]},"snowman":{"n":"Snowman","u":["☃️"],"k":["winter","season","cold","weather","christmas","xmas","frozen"]},"snowman_without_snow":{"n":"Snowman Without Snow","u":["⛄"],"k":["winter","season","cold","weather","christmas","xmas","frozen"]},"comet":{"n":"Comet","u":["☄️"],"k":["space"]},"fire":{"n":"Fire","u":["🔥"],"k":["hot","cook","flame"]},"droplet":{"n":"Droplet","u":["💧"],"k":["water","drip","faucet","spring"]},"ocean":{"n":"Water Wave","u":["🌊"],"k":["ocean","sea","nature","tsunami","disaster"]},"eyeglasses":{"n":"Glasses","u":["👓"],"k":["eyeglasses","fashion","accessories","eyesight","nerdy","dork","geek"]},"dark_sunglasses":{"n":"Sunglasses","u":["🕶️"],"k":["dark","face","cool","accessories"]},"goggles":{"n":"Goggles","u":["🥽"],"k":["eyes","protection","safety"]},"lab_coat":{"n":"Lab Coat","u":["🥼"],"k":["doctor","experiment","scientist","chemist"]},"safety_vest":{"n":"Safety Vest","u":["🦺"],"k":["protection"]},"necktie":{"n":"Necktie","u":["👔"],"k":["shirt","suitup","formal","fashion","cloth","business"]},"shirt":{"n":"T-Shirt","u":["👕"],"k":["shirt","tshirt","t","fashion","cloth","casual","tee"]},"jeans":{"n":"Jeans","u":["👖"],"k":["fashion","shopping"]},"scarf":{"n":"Scarf","u":["🧣"],"k":["neck","winter","clothes"]},"gloves":{"n":"Gloves","u":["🧤"],"k":["hands","winter","clothes"]},"coat":{"n":"Coat","u":["🧥"],"k":["jacket"]},"socks":{"n":"Socks","u":["🧦"],"k":["stockings","clothes"]},"dress":{"n":"Dress","u":["👗"],"k":["clothes","fashion","shopping"]},"kimono":{"n":"Kimono","u":["👘"],"k":["dress","fashion","women","female","japanese"]},"sari":{"n":"Sari","u":["🥻"],"k":["dress"]},"one-piece_swimsuit":{"n":"One-Piece Swimsuit","u":["🩱"],"k":["one","piece","fashion"]},"briefs":{"n":"Briefs","u":["🩲"],"k":["clothing"]},"shorts":{"n":"Shorts","u":["🩳"],"k":["clothing"]},"bikini":{"n":"Bikini","u":["👙"],"k":["swimming","female","woman","girl","fashion","beach","summer"]},"womans_clothes":{"n":"Womans Clothes","u":["👚"],"k":["woman","s","fashion","shopping","bags","female"]},"folding_hand_fan":{"n":"Folding Hand Fan","u":["🪭"],"k":["flamenco","hot"]},"purse":{"n":"Purse","u":["👛"],"k":["fashion","accessories","money","sales","shopping"]},"handbag":{"n":"Handbag","u":["👜"],"k":["fashion","accessory","accessories","shopping"]},"pouch":{"n":"Pouch","u":["👝"],"k":["clutch","bag","accessories","shopping"]},"shopping_bags":{"n":"Shopping Bags","u":["🛍️"],"k":["mall","buy","purchase"]},"school_satchel":{"n":"Backpack","u":["🎒"],"k":["school","satchel","student","education","bag"]},"thong_sandal":{"n":"Thong Sandal","u":["🩴"],"k":["footwear","summer"]},"mans_shoe":{"n":"Mans Shoe","u":["👞"],"k":["man","s","fashion","male"]},"athletic_shoe":{"n":"Running Shoe","u":["👟"],"k":["athletic","shoes","sports","sneakers"]},"hiking_boot":{"n":"Hiking Boot","u":["🥾"],"k":["backpacking","camping"]},"womans_flat_shoe":{"n":"Flat Shoe","u":["🥿"],"k":["womans","ballet","slip","on","slipper"]},"high_heel":{"n":"High-Heeled Shoe","u":["👠"],"k":["high","heel","heeled","fashion","shoes","female","pumps","stiletto"]},"sandal":{"n":"Womans Sandal","u":["👡"],"k":["woman","s","shoes","fashion","flip","flops"]},"ballet_shoes":{"n":"Ballet Shoes","u":["🩰"],"k":["dance"]},"boot":{"n":"Womans Boots","u":["👢"],"k":["boot","woman","s","shoes","fashion"]},"hair_pick":{"n":"Hair Pick","u":["🪮"],"k":["afro","comb"]},"crown":{"n":"Crown","u":["👑"],"k":["king","kod","leader","royalty","lord"]},"womans_hat":{"n":"Womans Hat","u":["👒"],"k":["woman","s","fashion","accessories","female","lady","spring"]},"tophat":{"n":"Top Hat","u":["🎩"],"k":["tophat","magic","gentleman","classy","circus"]},"mortar_board":{"n":"Graduation Cap","u":["🎓"],"k":["mortar","board","school","college","degree","university","hat","legal","learn","education"]},"billed_cap":{"n":"Billed Cap","u":["🧢"],"k":["baseball"]},"military_helmet":{"n":"Military Helmet","u":["🪖"],"k":["army","protection"]},"helmet_with_white_cross":{"n":"Rescue Worker’s Helmet","u":["⛑️"],"k":["with","white","cross","worker","s","construction","build"]},"prayer_beads":{"n":"Prayer Beads","u":["📿"],"k":["dhikr","religious"]},"lipstick":{"n":"Lipstick","u":["💄"],"k":["female","girl","fashion","woman"]},"ring":{"n":"Ring","u":["💍"],"k":["wedding","propose","marriage","valentines","diamond","fashion","jewelry","gem","engagement"]},"gem":{"n":"Gem Stone","u":["💎"],"k":["blue","ruby","diamond","jewelry"]},"mute":{"n":"Muted Speaker","u":["🔇"],"k":["mute","sound","volume","silence","quiet"]},"speaker":{"n":"Speaker","u":["🔈"],"k":["low","volume","sound","silence","broadcast"]},"sound":{"n":"Speaker Medium Volume","u":["🔉"],"k":["sound","broadcast"]},"loud_sound":{"n":"Speaker High Volume","u":["🔊"],"k":["loud","sound","noise","noisy","broadcast"]},"loudspeaker":{"n":"Loudspeaker","u":["📢"],"k":["volume","sound"]},"mega":{"n":"Megaphone","u":["📣"],"k":["mega","sound","speaker","volume"]},"postal_horn":{"n":"Postal Horn","u":["📯"],"k":["instrument","music"]},"bell":{"n":"Bell","u":["🔔"],"k":["sound","notification","christmas","xmas","chime"]},"no_bell":{"n":"Bell with Slash","u":["🔕"],"k":["no","sound","volume","mute","quiet","silent"]},"musical_score":{"n":"Musical Score","u":["🎼"],"k":["treble","clef","compose"]},"musical_note":{"n":"Musical Note","u":["🎵"],"k":["score","tone","sound"]},"notes":{"n":"Musical Notes","u":["🎶"],"k":["music","score"]},"studio_microphone":{"n":"Studio Microphone","u":["🎙️"],"k":["sing","recording","artist","talkshow"]},"level_slider":{"n":"Level Slider","u":["🎚️"],"k":["scale"]},"control_knobs":{"n":"Control Knobs","u":["🎛️"],"k":["dial"]},"microphone":{"n":"Microphone","u":["🎤"],"k":["sound","music","PA","sing","talkshow"]},"headphones":{"n":"Headphone","u":["🎧"],"k":["headphones","music","score","gadgets"]},"radio":{"n":"Radio","u":["📻"],"k":["communication","music","podcast","program"]},"saxophone":{"n":"Saxophone","u":["🎷"],"k":["music","instrument","jazz","blues"]},"accordion":{"n":"Accordion","u":["🪗"],"k":["music"]},"guitar":{"n":"Guitar","u":["🎸"],"k":["music","instrument"]},"musical_keyboard":{"n":"Musical Keyboard","u":["🎹"],"k":["piano","instrument","compose"]},"trumpet":{"n":"Trumpet","u":["🎺"],"k":["music","brass"]},"violin":{"n":"Violin","u":["🎻"],"k":["music","instrument","orchestra","symphony"]},"banjo":{"n":"Banjo","u":["🪕"],"k":["music","instructment"]},"drum_with_drumsticks":{"n":"Drum","u":["🥁"],"k":["with","drumsticks","music","instrument","snare"]},"long_drum":{"n":"Long Drum","u":["🪘"],"k":["music"]},"maracas":{"n":"Maracas","u":["🪇"],"k":["music","instrument","percussion"]},"flute":{"n":"Flute","u":["🪈"],"k":["bamboo","music","instrument","pied","piper"]},"iphone":{"n":"Mobile Phone","u":["📱"],"k":["iphone","technology","apple","gadgets","dial"]},"calling":{"n":"Mobile Phone with Arrow","u":["📲"],"k":["calling","iphone","incoming"]},"phone":{"n":"Telephone","u":["☎️"],"k":["phone","technology","communication","dial"]},"telephone_receiver":{"n":"Telephone Receiver","u":["📞"],"k":["technology","communication","dial"]},"pager":{"n":"Pager","u":["📟"],"k":["bbcall","oldschool","90s"]},"fax":{"n":"Fax Machine","u":["📠"],"k":["communication","technology"]},"battery":{"n":"Battery","u":["🔋"],"k":["power","energy","sustain"]},"low_battery":{"n":"Low Battery","u":["🪫"],"k":["drained","dead"]},"electric_plug":{"n":"Electric Plug","u":["🔌"],"k":["charger","power"]},"computer":{"n":"Laptop","u":["💻"],"k":["computer","technology","screen","display","monitor"]},"desktop_computer":{"n":"Desktop Computer","u":["🖥️"],"k":["technology","computing","screen"]},"printer":{"n":"Printer","u":["🖨️"],"k":["paper","ink"]},"keyboard":{"n":"Keyboard","u":["⌨️"],"k":["technology","computer","type","input","text"]},"three_button_mouse":{"n":"Computer Mouse","u":["🖱️"],"k":["three","button","click"]},"trackball":{"n":"Trackball","u":["🖲️"],"k":["technology","trackpad"]},"minidisc":{"n":"Minidisc","u":["💽"],"k":["computer","disk","technology","record","data","90s"]},"floppy_disk":{"n":"Floppy Disk","u":["💾"],"k":["oldschool","technology","save","90s","80s"]},"cd":{"n":"Optical Disc","u":["💿"],"k":["cd","disk","technology","dvd","90s"]},"dvd":{"n":"Dvd","u":["📀"],"k":["cd","disk","disc"]},"abacus":{"n":"Abacus","u":["🧮"],"k":["calculation"]},"movie_camera":{"n":"Movie Camera","u":["🎥"],"k":["film","record"]},"film_frames":{"n":"Film Frames","u":["🎞️"],"k":["movie"]},"film_projector":{"n":"Film Projector","u":["📽️"],"k":["video","tape","record","movie"]},"clapper":{"n":"Clapper Board","u":["🎬"],"k":["movie","film","record"]},"tv":{"n":"Television","u":["📺"],"k":["tv","technology","program","oldschool","show"]},"camera":{"n":"Camera","u":["📷"],"k":["gadgets","photography"]},"camera_with_flash":{"n":"Camera with Flash","u":["📸"],"k":["photography","gadgets"]},"video_camera":{"n":"Video Camera","u":["📹"],"k":["film","record"]},"vhs":{"n":"Videocassette","u":["📼"],"k":["vhs","record","video","oldschool","90s","80s"]},"mag":{"n":"Magnifying Glass Tilted Left","u":["🔍"],"k":["mag","search","zoom","find","detective"]},"mag_right":{"n":"Magnifying Glass Tilted Right","u":["🔎"],"k":["mag","search","zoom","find","detective"]},"candle":{"n":"Candle","u":["🕯️"],"k":["fire","wax"]},"bulb":{"n":"Light Bulb","u":["💡"],"k":["electricity","idea"]},"flashlight":{"n":"Flashlight","u":["🔦"],"k":["dark","camping","sight","night"]},"izakaya_lantern":{"n":"Izakaya Lantern","u":["🏮"],"k":["red","paper","light","halloween","spooky"]},"diya_lamp":{"n":"Diya Lamp","u":["🪔"],"k":["lighting"]},"notebook_with_decorative_cover":{"n":"Notebook with Decorative Cover","u":["📔"],"k":["classroom","notes","record","paper","study"]},"closed_book":{"n":"Closed Book","u":["📕"],"k":["read","library","knowledge","textbook","learn"]},"book":{"n":"Open Book","u":["📖"],"k":["read","library","knowledge","literature","learn","study"]},"green_book":{"n":"Green Book","u":["📗"],"k":["read","library","knowledge","study"]},"blue_book":{"n":"Blue Book","u":["📘"],"k":["read","library","knowledge","learn","study"]},"orange_book":{"n":"Orange Book","u":["📙"],"k":["read","library","knowledge","textbook","study"]},"books":{"n":"Books","u":["📚"],"k":["literature","library","study"]},"notebook":{"n":"Notebook","u":["📓"],"k":["stationery","record","notes","paper","study"]},"ledger":{"n":"Ledger","u":["📒"],"k":["notes","paper"]},"page_with_curl":{"n":"Page with Curl","u":["📃"],"k":["documents","office","paper"]},"scroll":{"n":"Scroll","u":["📜"],"k":["documents","ancient","history","paper"]},"page_facing_up":{"n":"Page Facing Up","u":["📄"],"k":["documents","office","paper","information"]},"newspaper":{"n":"Newspaper","u":["📰"],"k":["press","headline"]},"rolled_up_newspaper":{"n":"Rolled-Up Newspaper","u":["🗞️"],"k":["rolled","up","press","headline"]},"bookmark_tabs":{"n":"Bookmark Tabs","u":["📑"],"k":["favorite","save","order","tidy"]},"bookmark":{"n":"Bookmark","u":["🔖"],"k":["favorite","label","save"]},"label":{"n":"Label","u":["🏷️"],"k":["sale","tag"]},"moneybag":{"n":"Money Bag","u":["💰"],"k":["moneybag","dollar","payment","coins","sale"]},"coin":{"n":"Coin","u":["🪙"],"k":["money","currency"]},"yen":{"n":"Yen Banknote","u":["💴"],"k":["money","sales","japanese","dollar","currency"]},"dollar":{"n":"Dollar Banknote","u":["💵"],"k":["money","sales","bill","currency"]},"euro":{"n":"Euro Banknote","u":["💶"],"k":["money","sales","dollar","currency"]},"pound":{"n":"Pound Banknote","u":["💷"],"k":["british","sterling","money","sales","bills","uk","england","currency"]},"money_with_wings":{"n":"Money with Wings","u":["💸"],"k":["dollar","bills","payment","sale"]},"credit_card":{"n":"Credit Card","u":["💳"],"k":["money","sales","dollar","bill","payment","shopping"]},"receipt":{"n":"Receipt","u":["🧾"],"k":["accounting","expenses"]},"chart":{"n":"Chart Increasing with Yen","u":["💹"],"k":["green","square","graph","presentation","stats"]},"email":{"n":"Envelope","u":["✉️"],"k":["email","letter","postal","inbox","communication"]},"e-mail":{"n":"E-Mail","u":["📧"],"k":["e","mail","communication","inbox"]},"incoming_envelope":{"n":"Incoming Envelope","u":["📨"],"k":["email","inbox"]},"envelope_with_arrow":{"n":"Envelope with Arrow","u":["📩"],"k":["email","communication"]},"outbox_tray":{"n":"Outbox Tray","u":["📤"],"k":["inbox","email"]},"inbox_tray":{"n":"Inbox Tray","u":["📥"],"k":["email","documents"]},"package":{"n":"Package","u":["📦"],"k":["mail","gift","cardboard","box","moving"]},"mailbox":{"n":"Closed Mailbox with Raised Flag","u":["📫"],"k":["email","inbox","communication"]},"mailbox_closed":{"n":"Closed Mailbox with Lowered Flag","u":["📪"],"k":["email","communication","inbox"]},"mailbox_with_mail":{"n":"Open Mailbox with Raised Flag","u":["📬"],"k":["mail","email","inbox","communication"]},"mailbox_with_no_mail":{"n":"Open Mailbox with Lowered Flag","u":["📭"],"k":["no","mail","email","inbox"]},"postbox":{"n":"Postbox","u":["📮"],"k":["email","letter","envelope"]},"ballot_box_with_ballot":{"n":"Ballot Box with Ballot","u":["🗳️"],"k":["election","vote"]},"pencil2":{"n":"Pencil","u":["✏️"],"k":["pencil2","stationery","write","paper","writing","school","study"]},"black_nib":{"n":"Black Nib","u":["✒️"],"k":["pen","stationery","writing","write"]},"lower_left_fountain_pen":{"n":"Fountain Pen","u":["🖋️"],"k":["lower","left","stationery","writing","write"]},"lower_left_ballpoint_pen":{"n":"Pen","u":["🖊️"],"k":["lower","left","ballpoint","stationery","writing","write"]},"lower_left_paintbrush":{"n":"Paintbrush","u":["🖌️"],"k":["lower","left","drawing","creativity","art"]},"lower_left_crayon":{"n":"Crayon","u":["🖍️"],"k":["lower","left","drawing","creativity"]},"memo":{"n":"Memo","u":["📝"],"k":["pencil","write","documents","stationery","paper","writing","legal","exam","quiz","test","study","compose"]},"briefcase":{"n":"Briefcase","u":["💼"],"k":["business","documents","work","law","legal","job","career"]},"file_folder":{"n":"File Folder","u":["📁"],"k":["documents","business","office"]},"open_file_folder":{"n":"Open File Folder","u":["📂"],"k":["documents","load"]},"card_index_dividers":{"n":"Card Index Dividers","u":["🗂️"],"k":["organizing","business","stationery"]},"date":{"n":"Calendar","u":["📅"],"k":["date","schedule"]},"calendar":{"n":"Tear-off Calendar","u":["📆"],"k":["tear","off","schedule","date","planning"]},"spiral_note_pad":{"n":"Spiral Notepad","u":["🗒️"],"k":["note","pad","memo","stationery"]},"spiral_calendar_pad":{"n":"Spiral Calendar","u":["🗓️"],"k":["pad","date","schedule","planning"]},"card_index":{"n":"Card Index","u":["📇"],"k":["business","stationery"]},"chart_with_upwards_trend":{"n":"Chart Increasing","u":["📈"],"k":["with","upwards","trend","graph","presentation","stats","recovery","business","economics","money","sales","good","success"]},"chart_with_downwards_trend":{"n":"Chart Decreasing","u":["📉"],"k":["with","downwards","trend","graph","presentation","stats","recession","business","economics","money","sales","bad","failure"]},"bar_chart":{"n":"Bar Chart","u":["📊"],"k":["graph","presentation","stats"]},"clipboard":{"n":"Clipboard","u":["📋"],"k":["stationery","documents"]},"pushpin":{"n":"Pushpin","u":["📌"],"k":["stationery","mark","here"]},"round_pushpin":{"n":"Round Pushpin","u":["📍"],"k":["stationery","location","map","here"]},"paperclip":{"n":"Paperclip","u":["📎"],"k":["documents","stationery"]},"linked_paperclips":{"n":"Linked Paperclips","u":["🖇️"],"k":["documents","stationery"]},"straight_ruler":{"n":"Straight Ruler","u":["📏"],"k":["stationery","calculate","length","math","school","drawing","architect","sketch"]},"triangular_ruler":{"n":"Triangular Ruler","u":["📐"],"k":["stationery","math","architect","sketch"]},"scissors":{"n":"Scissors","u":["✂️"],"k":["stationery","cut"]},"card_file_box":{"n":"Card File Box","u":["🗃️"],"k":["business","stationery"]},"file_cabinet":{"n":"File Cabinet","u":["🗄️"],"k":["filing","organizing"]},"wastebasket":{"n":"Wastebasket","u":["🗑️"],"k":["bin","trash","rubbish","garbage","toss"]},"lock":{"n":"Lock","u":["🔒"],"k":["locked","security","password","padlock"]},"unlock":{"n":"Unlocked","u":["🔓"],"k":["unlock","privacy","security"]},"lock_with_ink_pen":{"n":"Locked with Pen","u":["🔏"],"k":["lock","ink","security","secret"]},"closed_lock_with_key":{"n":"Locked with Key","u":["🔐"],"k":["closed","lock","security","privacy"]},"key":{"n":"Key","u":["🔑"],"k":["lock","door","password"]},"old_key":{"n":"Old Key","u":["🗝️"],"k":["lock","door","password"]},"hammer":{"n":"Hammer","u":["🔨"],"k":["tools","build","create"]},"axe":{"n":"Axe","u":["🪓"],"k":["tool","chop","cut"]},"pick":{"n":"Pick","u":["⛏️"],"k":["tools","dig"]},"hammer_and_pick":{"n":"Hammer and Pick","u":["⚒️"],"k":["tools","build","create"]},"hammer_and_wrench":{"n":"Hammer and Wrench","u":["🛠️"],"k":["tools","build","create"]},"dagger_knife":{"n":"Dagger","u":["🗡️"],"k":["knife","weapon"]},"crossed_swords":{"n":"Crossed Swords","u":["⚔️"],"k":["weapon"]},"bomb":{"n":"Bomb","u":["💣"],"k":["boom","explode","explosion","terrorism"]},"boomerang":{"n":"Boomerang","u":["🪃"],"k":["weapon"]},"bow_and_arrow":{"n":"Bow and Arrow","u":["🏹"],"k":["sports"]},"shield":{"n":"Shield","u":["🛡️"],"k":["protection","security"]},"carpentry_saw":{"n":"Carpentry Saw","u":["🪚"],"k":["cut","chop"]},"wrench":{"n":"Wrench","u":["🔧"],"k":["tools","diy","ikea","fix","maintainer"]},"screwdriver":{"n":"Screwdriver","u":["🪛"],"k":["tools"]},"nut_and_bolt":{"n":"Nut and Bolt","u":["🔩"],"k":["handy","tools","fix"]},"gear":{"n":"Gear","u":["⚙️"],"k":["cog"]},"compression":{"n":"Clamp","u":["🗜️"],"k":["compression","tool"]},"scales":{"n":"Balance Scale","u":["⚖️"],"k":["scales","law","fairness","weight"]},"probing_cane":{"n":"White Cane","u":["🦯"],"k":["probing","accessibility"]},"link":{"n":"Link","u":["🔗"],"k":["rings","url"]},"chains":{"n":"Chains","u":["⛓️"],"k":["lock","arrest"]},"hook":{"n":"Hook","u":["🪝"],"k":["tools"]},"toolbox":{"n":"Toolbox","u":["🧰"],"k":["tools","diy","fix","maintainer","mechanic"]},"magnet":{"n":"Magnet","u":["🧲"],"k":["attraction","magnetic"]},"ladder":{"n":"Ladder","u":["🪜"],"k":["tools"]},"alembic":{"n":"Alembic","u":["⚗️"],"k":["distilling","science","experiment","chemistry"]},"test_tube":{"n":"Test Tube","u":["🧪"],"k":["chemistry","experiment","lab","science"]},"petri_dish":{"n":"Petri Dish","u":["🧫"],"k":["bacteria","biology","culture","lab"]},"dna":{"n":"Dna","u":["🧬"],"k":["biologist","genetics","life"]},"microscope":{"n":"Microscope","u":["🔬"],"k":["laboratory","experiment","zoomin","science","study"]},"telescope":{"n":"Telescope","u":["🔭"],"k":["stars","space","zoom","science","astronomy"]},"satellite_antenna":{"n":"Satellite Antenna","u":["📡"],"k":["communication","future","radio","space"]},"syringe":{"n":"Syringe","u":["💉"],"k":["health","hospital","drugs","blood","medicine","needle","doctor","nurse"]},"drop_of_blood":{"n":"Drop of Blood","u":["🩸"],"k":["period","hurt","harm","wound"]},"pill":{"n":"Pill","u":["💊"],"k":["health","medicine","doctor","pharmacy","drug"]},"adhesive_bandage":{"n":"Adhesive Bandage","u":["🩹"],"k":["heal"]},"crutch":{"n":"Crutch","u":["🩼"],"k":["accessibility","assist"]},"stethoscope":{"n":"Stethoscope","u":["🩺"],"k":["health"]},"x-ray":{"n":"X-Ray","u":["🩻"],"k":["x","ray","skeleton","medicine"]},"door":{"n":"Door","u":["🚪"],"k":["house","entry","exit"]},"elevator":{"n":"Elevator","u":["🛗"],"k":["lift"]},"mirror":{"n":"Mirror","u":["🪞"],"k":["reflection"]},"window":{"n":"Window","u":["🪟"],"k":["scenery"]},"bed":{"n":"Bed","u":["🛏️"],"k":["sleep","rest"]},"couch_and_lamp":{"n":"Couch and Lamp","u":["🛋️"],"k":["read","chill"]},"chair":{"n":"Chair","u":["🪑"],"k":["sit","furniture"]},"toilet":{"n":"Toilet","u":["🚽"],"k":["restroom","wc","washroom","bathroom","potty"]},"plunger":{"n":"Plunger","u":["🪠"],"k":["toilet"]},"shower":{"n":"Shower","u":["🚿"],"k":["clean","water","bathroom"]},"bathtub":{"n":"Bathtub","u":["🛁"],"k":["clean","shower","bathroom"]},"mouse_trap":{"n":"Mouse Trap","u":["🪤"],"k":["cheese"]},"razor":{"n":"Razor","u":["🪒"],"k":["cut"]},"lotion_bottle":{"n":"Lotion Bottle","u":["🧴"],"k":["moisturizer","sunscreen"]},"safety_pin":{"n":"Safety Pin","u":["🧷"],"k":["diaper"]},"broom":{"n":"Broom","u":["🧹"],"k":["cleaning","sweeping","witch"]},"basket":{"n":"Basket","u":["🧺"],"k":["laundry"]},"roll_of_paper":{"n":"Roll of Paper","u":["🧻"],"k":[]},"bucket":{"n":"Bucket","u":["🪣"],"k":["water","container"]},"soap":{"n":"Soap","u":["🧼"],"k":["bar","bathing","cleaning","lather"]},"bubbles":{"n":"Bubbles","u":["🫧"],"k":["soap","fun","carbonation","sparkling"]},"toothbrush":{"n":"Toothbrush","u":["🪥"],"k":["hygiene","dental"]},"sponge":{"n":"Sponge","u":["🧽"],"k":["absorbing","cleaning","porous"]},"fire_extinguisher":{"n":"Fire Extinguisher","u":["🧯"],"k":["quench"]},"shopping_trolley":{"n":"Shopping Cart","u":["🛒"],"k":["trolley"]},"smoking":{"n":"Cigarette","u":["🚬"],"k":["smoking","kills","tobacco","joint","smoke"]},"coffin":{"n":"Coffin","u":["⚰️"],"k":["vampire","dead","die","death","rip","graveyard","cemetery","casket","funeral","box"]},"headstone":{"n":"Headstone","u":["🪦"],"k":["death","rip","grave"]},"funeral_urn":{"n":"Funeral Urn","u":["⚱️"],"k":["dead","die","death","rip","ashes"]},"nazar_amulet":{"n":"Nazar Amulet","u":["🧿"],"k":["bead","charm"]},"hamsa":{"n":"Hamsa","u":["🪬"],"k":["religion","protection"]},"moyai":{"n":"Moai","u":["🗿"],"k":["moyai","rock","easter","island"]},"placard":{"n":"Placard","u":["🪧"],"k":["announcement"]},"identification_card":{"n":"Identification Card","u":["🪪"],"k":["document"]},"atm":{"n":"Atm Sign","u":["🏧"],"k":["money","sales","cash","blue","square","payment","bank"]},"put_litter_in_its_place":{"n":"Litter in Bin Sign","u":["🚮"],"k":["put","its","place","blue","square","human","info"]},"potable_water":{"n":"Potable Water","u":["🚰"],"k":["blue","square","liquid","restroom","cleaning","faucet"]},"wheelchair":{"n":"Wheelchair Symbol","u":["♿"],"k":["blue","square","disabled","accessibility"]},"mens":{"n":"Men’s Room","u":["🚹"],"k":["mens","men","s","toilet","restroom","wc","blue","square","gender","male"]},"womens":{"n":"Women’s Room","u":["🚺"],"k":["womens","women","s","purple","square","woman","female","toilet","loo","restroom","gender"]},"restroom":{"n":"Restroom","u":["🚻"],"k":["blue","square","toilet","refresh","wc","gender"]},"baby_symbol":{"n":"Baby Symbol","u":["🚼"],"k":["orange","square","child"]},"wc":{"n":"Water Closet","u":["🚾"],"k":["wc","toilet","restroom","blue","square"]},"passport_control":{"n":"Passport Control","u":["🛂"],"k":["custom","blue","square"]},"customs":{"n":"Customs","u":["🛃"],"k":["passport","border","blue","square"]},"baggage_claim":{"n":"Baggage Claim","u":["🛄"],"k":["blue","square","airport","transport"]},"left_luggage":{"n":"Left Luggage","u":["🛅"],"k":["blue","square","travel"]},"warning":{"n":"Warning","u":["⚠️"],"k":["exclamation","wip","alert","error","problem","issue"]},"children_crossing":{"n":"Children Crossing","u":["🚸"],"k":["school","warning","danger","sign","driving","yellow","diamond"]},"no_entry":{"n":"No Entry","u":["⛔"],"k":["limit","security","privacy","bad","denied","stop","circle"]},"no_entry_sign":{"n":"Prohibited","u":["🚫"],"k":["no","entry","sign","forbid","stop","limit","denied","disallow","circle"]},"no_bicycles":{"n":"No Bicycles","u":["🚳"],"k":["cyclist","prohibited","circle"]},"no_smoking":{"n":"No Smoking","u":["🚭"],"k":["cigarette","blue","square","smell","smoke"]},"do_not_litter":{"n":"No Littering","u":["🚯"],"k":["do","not","litter","trash","bin","garbage","circle"]},"non-potable_water":{"n":"Non-Potable Water","u":["🚱"],"k":["non","potable","drink","faucet","tap","circle"]},"no_pedestrians":{"n":"No Pedestrians","u":["🚷"],"k":["rules","crossing","walking","circle"]},"no_mobile_phones":{"n":"No Mobile Phones","u":["📵"],"k":["iphone","mute","circle"]},"underage":{"n":"No One Under Eighteen","u":["🔞"],"k":["underage","18","drink","pub","night","minor","circle"]},"radioactive_sign":{"n":"Radioactive","u":["☢️"],"k":["sign","nuclear","danger"]},"biohazard_sign":{"n":"Biohazard","u":["☣️"],"k":["sign","danger"]},"arrow_up":{"n":"Up Arrow","u":["⬆️"],"k":["blue","square","continue","top","direction"]},"arrow_upper_right":{"n":"Up-Right Arrow","u":["↗️"],"k":["upper","right","up","blue","square","point","direction","diagonal","northeast"]},"arrow_right":{"n":"Right Arrow","u":["➡️"],"k":["blue","square","next"]},"arrow_lower_right":{"n":"South East Arrow","u":["↘️"],"k":["lower","right","down","blue","square","direction","diagonal","southeast"]},"arrow_down":{"n":"Down Arrow","u":["⬇️"],"k":["blue","square","direction","bottom"]},"arrow_lower_left":{"n":"Down-Left Arrow","u":["↙️"],"k":["lower","left","down","blue","square","direction","diagonal","southwest"]},"arrow_left":{"n":"Left Arrow","u":["⬅️"],"k":["blue","square","previous","back"]},"arrow_upper_left":{"n":"Up-Left Arrow","u":["↖️"],"k":["upper","left","up","blue","square","point","direction","diagonal","northwest"]},"arrow_up_down":{"n":"Up Down Arrow","u":["↕️"],"k":["blue","square","direction","way","vertical"]},"left_right_arrow":{"n":"Left Right Arrow","u":["↔️"],"k":["shape","direction","horizontal","sideways"]},"leftwards_arrow_with_hook":{"n":"Right Arrow Curving Left","u":["↩️"],"k":["leftwards","with","hook","back","return","blue","square","undo","enter"]},"arrow_right_hook":{"n":"Left Arrow Curving Right","u":["↪️"],"k":["hook","blue","square","return","rotate","direction"]},"arrow_heading_up":{"n":"Right Arrow Curving Up","u":["⤴️"],"k":["heading","blue","square","direction","top"]},"arrow_heading_down":{"n":"Right Arrow Curving Down","u":["⤵️"],"k":["heading","blue","square","direction","bottom"]},"arrows_clockwise":{"n":"Clockwise Vertical Arrows","u":["🔃"],"k":["sync","cycle","round","repeat"]},"arrows_counterclockwise":{"n":"Counterclockwise Arrows Button","u":["🔄"],"k":["blue","square","sync","cycle"]},"back":{"n":"Back Arrow","u":["🔙"],"k":["words","return"]},"end":{"n":"End Arrow","u":["🔚"],"k":["words"]},"on":{"n":"On! Arrow","u":["🔛"],"k":["on","words"]},"soon":{"n":"Soon Arrow","u":["🔜"],"k":["words"]},"top":{"n":"Top Arrow","u":["🔝"],"k":["words","blue","square"]},"place_of_worship":{"n":"Place of Worship","u":["🛐"],"k":["religion","church","temple","prayer"]},"atom_symbol":{"n":"Atom Symbol","u":["⚛️"],"k":["science","physics","chemistry"]},"om_symbol":{"n":"Om","u":["🕉️"],"k":["symbol","hinduism","buddhism","sikhism","jainism"]},"star_of_david":{"n":"Star of David","u":["✡️"],"k":["judaism"]},"wheel_of_dharma":{"n":"Wheel of Dharma","u":["☸️"],"k":["hinduism","buddhism","sikhism","jainism"]},"yin_yang":{"n":"Yin Yang","u":["☯️"],"k":["balance"]},"latin_cross":{"n":"Latin Cross","u":["✝️"],"k":["christianity"]},"orthodox_cross":{"n":"Orthodox Cross","u":["☦️"],"k":["suppedaneum","religion"]},"star_and_crescent":{"n":"Star and Crescent","u":["☪️"],"k":["islam"]},"peace_symbol":{"n":"Peace Symbol","u":["☮️"],"k":["hippie"]},"menorah_with_nine_branches":{"n":"Menorah","u":["🕎"],"k":["with","nine","branches","hanukkah","candles","jewish"]},"six_pointed_star":{"n":"Dotted Six-Pointed Star","u":["🔯"],"k":["six","pointed","purple","square","religion","jewish","hexagram"]},"khanda":{"n":"Khanda","u":["🪯"],"k":["Sikhism","religion"]},"aries":{"n":"Aries","u":["♈"],"k":["sign","purple","square","zodiac","astrology"]},"taurus":{"n":"Taurus","u":["♉"],"k":["purple","square","sign","zodiac","astrology"]},"gemini":{"n":"Gemini","u":["♊"],"k":["sign","zodiac","purple","square","astrology"]},"cancer":{"n":"Cancer","u":["♋"],"k":["sign","zodiac","purple","square","astrology"]},"leo":{"n":"Leo","u":["♌"],"k":["sign","purple","square","zodiac","astrology"]},"virgo":{"n":"Virgo","u":["♍"],"k":["sign","zodiac","purple","square","astrology"]},"libra":{"n":"Libra","u":["♎"],"k":["sign","purple","square","zodiac","astrology"]},"scorpius":{"n":"Scorpio","u":["♏"],"k":["scorpius","sign","zodiac","purple","square","astrology"]},"sagittarius":{"n":"Sagittarius","u":["♐"],"k":["sign","zodiac","purple","square","astrology"]},"capricorn":{"n":"Capricorn","u":["♑"],"k":["sign","zodiac","purple","square","astrology"]},"aquarius":{"n":"Aquarius","u":["♒"],"k":["sign","purple","square","zodiac","astrology"]},"pisces":{"n":"Pisces","u":["♓"],"k":["purple","square","sign","zodiac","astrology"]},"ophiuchus":{"n":"Ophiuchus","u":["⛎"],"k":["sign","purple","square","constellation","astrology"]},"twisted_rightwards_arrows":{"n":"Shuffle Tracks Button","u":["🔀"],"k":["twisted","rightwards","arrows","blue","square","music","random"]},"repeat":{"n":"Repeat Button","u":["🔁"],"k":["loop","record"]},"repeat_one":{"n":"Repeat Single Button","u":["🔂"],"k":["one","blue","square","loop"]},"arrow_forward":{"n":"Play Button","u":["▶️"],"k":["arrow","forward","blue","square","right","direction"]},"fast_forward":{"n":"Fast-Forward Button","u":["⏩"],"k":["fast","forward","blue","square","play","speed","continue"]},"black_right_pointing_double_triangle_with_vertical_bar":{"n":"Next Track Button","u":["⏭️"],"k":["black","right","pointing","double","triangle","with","vertical","bar","forward","blue","square"]},"black_right_pointing_triangle_with_double_vertical_bar":{"n":"Play or Pause Button","u":["⏯️"],"k":["black","right","pointing","triangle","with","double","vertical","bar","blue","square"]},"arrow_backward":{"n":"Reverse Button","u":["◀️"],"k":["arrow","backward","blue","square","left","direction"]},"rewind":{"n":"Fast Reverse Button","u":["⏪"],"k":["rewind","play","blue","square"]},"black_left_pointing_double_triangle_with_vertical_bar":{"n":"Last Track Button","u":["⏮️"],"k":["black","left","pointing","double","triangle","with","vertical","bar","backward"]},"arrow_up_small":{"n":"Upwards Button","u":["🔼"],"k":["arrow","up","small","blue","square","triangle","direction","point","forward","top"]},"arrow_double_up":{"n":"Fast Up Button","u":["⏫"],"k":["arrow","double","blue","square","direction","top"]},"arrow_down_small":{"n":"Downwards Button","u":["🔽"],"k":["arrow","down","small","blue","square","direction","bottom"]},"arrow_double_down":{"n":"Fast Down Button","u":["⏬"],"k":["arrow","double","blue","square","direction","bottom"]},"double_vertical_bar":{"n":"Pause Button","u":["⏸️"],"k":["double","vertical","bar","blue","square"]},"black_square_for_stop":{"n":"Stop Button","u":["⏹️"],"k":["black","square","for","blue"]},"black_circle_for_record":{"n":"Record Button","u":["⏺️"],"k":["black","circle","for","blue","square"]},"eject":{"n":"Eject Button","u":["⏏️"],"k":["blue","square"]},"cinema":{"n":"Cinema","u":["🎦"],"k":["blue","square","record","film","movie","curtain","stage","theater"]},"low_brightness":{"n":"Dim Button","u":["🔅"],"k":["low","brightness","sun","afternoon","warm","summer"]},"high_brightness":{"n":"Bright Button","u":["🔆"],"k":["high","brightness","sun","light"]},"signal_strength":{"n":"Antenna Bars","u":["📶"],"k":["signal","strength","blue","square","reception","phone","internet","connection","wifi","bluetooth"]},"wireless":{"n":"Wireless","u":["🛜"],"k":["wifi","internet","contactless","signal"]},"vibration_mode":{"n":"Vibration Mode","u":["📳"],"k":["orange","square","phone"]},"mobile_phone_off":{"n":"Mobile Phone off","u":["📴"],"k":["mute","orange","square","silence","quiet"]},"female_sign":{"n":"Female Sign","u":["♀️"],"k":["woman","women","lady","girl"]},"male_sign":{"n":"Male Sign","u":["♂️"],"k":["man","boy","men"]},"transgender_symbol":{"n":"Transgender Symbol","u":["⚧️"],"k":["lgbtq"]},"heavy_multiplication_x":{"n":"Multiply","u":["✖️"],"k":["heavy","multiplication","x","sign","math","calculation"]},"heavy_plus_sign":{"n":"Plus","u":["➕"],"k":["heavy","sign","math","calculation","addition","more","increase"]},"heavy_minus_sign":{"n":"Minus","u":["➖"],"k":["heavy","sign","math","calculation","subtract","less"]},"heavy_division_sign":{"n":"Divide","u":["➗"],"k":["heavy","division","sign","math","calculation"]},"heavy_equals_sign":{"n":"Heavy Equals Sign","u":["🟰"],"k":["math"]},"infinity":{"n":"Infinity","u":["♾️"],"k":["forever"]},"bangbang":{"n":"Double Exclamation Mark","u":["‼️"],"k":["bangbang","surprise"]},"interrobang":{"n":"Exclamation Question Mark","u":["⁉️"],"k":["interrobang","wat","punctuation","surprise"]},"question":{"n":"Red Question Mark","u":["❓"],"k":["doubt","confused"]},"grey_question":{"n":"White Question Mark","u":["❔"],"k":["grey","doubts","gray","huh","confused"]},"grey_exclamation":{"n":"White Exclamation Mark","u":["❕"],"k":["grey","surprise","punctuation","gray","wow","warning"]},"exclamation":{"n":"Red Exclamation Mark","u":["❗"],"k":["heavy","danger","surprise","punctuation","wow","warning"]},"wavy_dash":{"n":"Wavy Dash","u":["〰️"],"k":["draw","line","moustache","mustache","squiggle","scribble"]},"currency_exchange":{"n":"Currency Exchange","u":["💱"],"k":["money","sales","dollar","travel"]},"heavy_dollar_sign":{"n":"Heavy Dollar Sign","u":["💲"],"k":["money","sales","payment","currency","buck"]},"medical_symbol":{"n":"Medical Symbol","u":["⚕️"],"k":["staff","of","aesculapius","health","hospital"]},"recycle":{"n":"Recycling Symbol","u":["♻️"],"k":["recycle","arrow","environment","garbage","trash"]},"fleur_de_lis":{"n":"Fleur-De-Lis","u":["⚜️"],"k":["fleur","de","lis","decorative","scout"]},"trident":{"n":"Trident Emblem","u":["🔱"],"k":["weapon","spear"]},"name_badge":{"n":"Name Badge","u":["📛"],"k":["fire","forbid"]},"beginner":{"n":"Japanese Symbol for Beginner","u":["🔰"],"k":["badge","shield"]},"o":{"n":"Hollow Red Circle","u":["⭕"],"k":["o","round"]},"white_check_mark":{"n":"Check Mark Button","u":["✅"],"k":["white","green","square","ok","agree","vote","election","answer","tick"]},"ballot_box_with_check":{"n":"Check Box with Check","u":["☑️"],"k":["ballot","ok","agree","confirm","black","square","vote","election","yes","tick"]},"heavy_check_mark":{"n":"Check Mark","u":["✔️"],"k":["heavy","ok","nike","answer","yes","tick"]},"x":{"n":"Cross Mark","u":["❌"],"k":["x","no","delete","remove","cancel","red"]},"negative_squared_cross_mark":{"n":"Cross Mark Button","u":["❎"],"k":["negative","squared","x","green","square","no","deny"]},"curly_loop":{"n":"Curly Loop","u":["➰"],"k":["scribble","draw","shape","squiggle"]},"loop":{"n":"Double Curly Loop","u":["➿"],"k":["tape","cassette"]},"part_alternation_mark":{"n":"Part Alternation Mark","u":["〽️"],"k":["graph","presentation","stats","business","economics","bad"]},"eight_spoked_asterisk":{"n":"Eight Spoked Asterisk","u":["✳️"],"k":["star","sparkle","green","square"]},"eight_pointed_black_star":{"n":"Eight-Pointed Star","u":["✴️"],"k":["eight","pointed","black","orange","square","shape","polygon"]},"sparkle":{"n":"Sparkle","u":["❇️"],"k":["stars","green","square","awesome","good","fireworks"]},"copyright":{"n":"Copyright","u":["©️"],"k":["ip","license","circle","law","legal"]},"registered":{"n":"Registered","u":["®️"],"k":["alphabet","circle"]},"tm":{"n":"Trade Mark","u":["™️"],"k":["tm","trademark","brand","law","legal"]},"hash":{"n":"Hash Key","u":["#️⃣"],"k":["keycap","","symbol","blue","square","twitter"]},"keycap_star":{"n":"Keycap: *","u":["*️⃣"],"k":["keycap","star",""]},"zero":{"n":"Keycap 0","u":["0️⃣"],"k":["zero","numbers","blue","square","null"]},"one":{"n":"Keycap 1","u":["1️⃣"],"k":["one","blue","square","numbers"]},"two":{"n":"Keycap 2","u":["2️⃣"],"k":["two","numbers","prime","blue","square"]},"three":{"n":"Keycap 3","u":["3️⃣"],"k":["three","numbers","prime","blue","square"]},"four":{"n":"Keycap 4","u":["4️⃣"],"k":["four","numbers","blue","square"]},"five":{"n":"Keycap 5","u":["5️⃣"],"k":["five","numbers","blue","square","prime"]},"six":{"n":"Keycap 6","u":["6️⃣"],"k":["six","numbers","blue","square"]},"seven":{"n":"Keycap 7","u":["7️⃣"],"k":["seven","numbers","blue","square","prime"]},"eight":{"n":"Keycap 8","u":["8️⃣"],"k":["eight","blue","square","numbers"]},"nine":{"n":"Keycap 9","u":["9️⃣"],"k":["nine","blue","square","numbers"]},"keycap_ten":{"n":"Keycap 10","u":["🔟"],"k":["ten","numbers","blue","square"]},"capital_abcd":{"n":"Input Latin Uppercase","u":["🔠"],"k":["capital","abcd","alphabet","words","blue","square"]},"abcd":{"n":"Input Latin Lowercase","u":["🔡"],"k":["abcd","blue","square","alphabet"]},"symbols":{"n":"Input Symbols","u":["🔣"],"k":["blue","square","music","note","ampersand","percent","glyphs","characters"]},"abc":{"n":"Input Latin Letters","u":["🔤"],"k":["abc","blue","square","alphabet"]},"a":{"n":"A Button (blood Type)","u":["🅰️"],"k":["red","square","alphabet","letter"]},"ab":{"n":"Negative Squared Ab","u":["🆎"],"k":["button","red","square","alphabet"]},"b":{"n":"B Button (blood Type)","u":["🅱️"],"k":["red","square","alphabet","letter"]},"cl":{"n":"Cl Button","u":["🆑"],"k":["alphabet","words","red","square"]},"cool":{"n":"Cool Button","u":["🆒"],"k":["words","blue","square"]},"free":{"n":"Free Button","u":["🆓"],"k":["blue","square","words"]},"information_source":{"n":"Information","u":["ℹ️"],"k":["source","blue","square","alphabet","letter"]},"id":{"n":"Id Button","u":["🆔"],"k":["purple","square","words"]},"m":{"n":"Circled M","u":["Ⓜ️"],"k":["alphabet","blue","circle","letter"]},"new":{"n":"New Button","u":["🆕"],"k":["blue","square","words","start"]},"ng":{"n":"Ng Button","u":["🆖"],"k":["blue","square","words","shape","icon"]},"o2":{"n":"O Button (blood Type)","u":["🅾️"],"k":["o2","alphabet","red","square","letter"]},"ok":{"n":"Ok Button","u":["🆗"],"k":["good","agree","yes","blue","square"]},"parking":{"n":"P Button","u":["🅿️"],"k":["parking","cars","blue","square","alphabet","letter"]},"sos":{"n":"Sos Button","u":["🆘"],"k":["help","red","square","words","emergency","911"]},"up":{"n":"Up! Button","u":["🆙"],"k":["up","blue","square","above","high"]},"vs":{"n":"Vs Button","u":["🆚"],"k":["words","orange","square"]},"koko":{"n":"Squared Katakana Koko","u":["🈁"],"k":["japanese","here","button","blue","square","destination"]},"sa":{"n":"Squared Katakana Sa","u":["🈂️"],"k":["japanese","service","charge","button","blue","square"]},"u6708":{"n":"Japanese “monthly Amount” Button","u":["🈷️"],"k":["u6708","monthly","amount","chinese","month","moon","orange","square","kanji"]},"u6709":{"n":"Squared Cjk Unified Ideograph-6709","u":["🈶"],"k":["u6709","japanese","not","free","of","charge","button","orange","square","chinese","have","kanji"]},"u6307":{"n":"Japanese “reserved” Button","u":["🈯"],"k":["u6307","reserved","chinese","point","green","square","kanji"]},"ideograph_advantage":{"n":"Japanese “bargain” Button","u":["🉐"],"k":["ideograph","advantage","bargain","chinese","kanji","obtain","get","circle"]},"u5272":{"n":"Japanese “discount” Button","u":["🈹"],"k":["u5272","discount","cut","divide","chinese","kanji","pink","square"]},"u7121":{"n":"Japanese “free of Charge” Button","u":["🈚"],"k":["u7121","free","charge","nothing","chinese","kanji","orange","square"]},"u7981":{"n":"Japanese “prohibited” Button","u":["🈲"],"k":["u7981","prohibited","kanji","chinese","forbidden","limit","restricted","red","square"]},"accept":{"n":"Circled Ideograph Accept","u":["🉑"],"k":["japanese","acceptable","button","ok","good","chinese","kanji","agree","yes","orange","circle"]},"u7533":{"n":"Japanese “application” Button","u":["🈸"],"k":["u7533","application","chinese","kanji","orange","square"]},"u5408":{"n":"Japanese “passing Grade” Button","u":["🈴"],"k":["u5408","passing","grade","chinese","join","kanji","red","square"]},"u7a7a":{"n":"Japanese “vacancy” Button","u":["🈳"],"k":["u7a7a","vacancy","kanji","chinese","empty","sky","blue","square"]},"congratulations":{"n":"Circled Ideograph Congratulation","u":["㊗️"],"k":["congratulations","japanese","button","chinese","kanji","red","circle"]},"secret":{"n":"Circled Ideograph Secret","u":["㊙️"],"k":["japanese","button","privacy","chinese","sshh","kanji","red","circle"]},"u55b6":{"n":"Squared Cjk Unified Ideograph-55b6","u":["🈺"],"k":["u55b6","japanese","open","for","business","button","opening","hours","orange","square"]},"u6e80":{"n":"Japanese “no Vacancy” Button","u":["🈵"],"k":["u6e80","no","vacancy","full","chinese","red","square","kanji"]},"red_circle":{"n":"Red Circle","u":["🔴"],"k":["shape","error","danger"]},"large_orange_circle":{"n":"Orange Circle","u":["🟠"],"k":["large","round"]},"large_yellow_circle":{"n":"Yellow Circle","u":["🟡"],"k":["large","round"]},"large_green_circle":{"n":"Green Circle","u":["🟢"],"k":["large","round"]},"large_blue_circle":{"n":"Blue Circle","u":["🔵"],"k":["large","shape","icon","button"]},"large_purple_circle":{"n":"Purple Circle","u":["🟣"],"k":["large","round"]},"large_brown_circle":{"n":"Brown Circle","u":["🟤"],"k":["large","round"]},"black_circle":{"n":"Black Circle","u":["⚫"],"k":["shape","button","round"]},"white_circle":{"n":"White Circle","u":["⚪"],"k":["shape","round"]},"large_red_square":{"n":"Red Square","u":["🟥"],"k":["large"]},"large_orange_square":{"n":"Orange Square","u":["🟧"],"k":["large"]},"large_yellow_square":{"n":"Yellow Square","u":["🟨"],"k":["large"]},"large_green_square":{"n":"Green Square","u":["🟩"],"k":["large"]},"large_blue_square":{"n":"Blue Square","u":["🟦"],"k":["large"]},"large_purple_square":{"n":"Purple Square","u":["🟪"],"k":["large"]},"large_brown_square":{"n":"Brown Square","u":["🟫"],"k":["large"]},"black_large_square":{"n":"Black Large Square","u":["⬛"],"k":["shape","icon","button"]},"white_large_square":{"n":"White Large Square","u":["⬜"],"k":["shape","icon","stone","button"]},"black_medium_square":{"n":"Black Medium Square","u":["◼️"],"k":["shape","button","icon"]},"white_medium_square":{"n":"White Medium Square","u":["◻️"],"k":["shape","stone","icon"]},"black_medium_small_square":{"n":"Black Medium Small Square","u":["◾"],"k":["icon","shape","button"]},"white_medium_small_square":{"n":"White Medium Small Square","u":["◽"],"k":["shape","stone","icon","button"]},"black_small_square":{"n":"Black Small Square","u":["▪️"],"k":["shape","icon"]},"white_small_square":{"n":"White Small Square","u":["▫️"],"k":["shape","icon"]},"large_orange_diamond":{"n":"Large Orange Diamond","u":["🔶"],"k":["shape","jewel","gem"]},"large_blue_diamond":{"n":"Large Blue Diamond","u":["🔷"],"k":["shape","jewel","gem"]},"small_orange_diamond":{"n":"Small Orange Diamond","u":["🔸"],"k":["shape","jewel","gem"]},"small_blue_diamond":{"n":"Small Blue Diamond","u":["🔹"],"k":["shape","jewel","gem"]},"small_red_triangle":{"n":"Red Triangle Pointed Up","u":["🔺"],"k":["small","shape","direction","top"]},"small_red_triangle_down":{"n":"Red Triangle Pointed Down","u":["🔻"],"k":["small","shape","direction","bottom"]},"diamond_shape_with_a_dot_inside":{"n":"Diamond with a Dot","u":["💠"],"k":["shape","inside","jewel","blue","gem","crystal","fancy"]},"radio_button":{"n":"Radio Button","u":["🔘"],"k":["input","old","music","circle"]},"white_square_button":{"n":"White Square Button","u":["🔳"],"k":["shape","input"]},"black_square_button":{"n":"Black Square Button","u":["🔲"],"k":["shape","input","frame"]},"checkered_flag":{"n":"Chequered Flag","u":["🏁"],"k":["checkered","contest","finishline","race","gokart"]},"cn":{"n":"China Flag","u":["🇨🇳"],"k":["cn","chinese","prc","country","nation","banner"]},"crossed_flags":{"n":"Crossed Flags","u":["🎌"],"k":["japanese","nation","country","border"]},"de":{"n":"Germany Flag","u":["🇩🇪"],"k":["de","german","nation","country","banner"]},"es":{"n":"Spain Flag","u":["🇪🇸"],"k":["es","nation","country","banner"]},"flag-ac":{"n":"Ascension Island Flag","u":["🇦🇨"],"k":["ac"]},"flag-ad":{"n":"Andorra Flag","u":["🇦🇩"],"k":["ad","nation","country","banner"]},"flag-ae":{"n":"United Arab Emirates Flag","u":["🇦🇪"],"k":["ae","nation","country","banner"]},"flag-af":{"n":"Afghanistan Flag","u":["🇦🇫"],"k":["af","nation","country","banner"]},"flag-ag":{"n":"Antigua & Barbuda Flag","u":["🇦🇬"],"k":["ag","nation","country","banner"]},"flag-ai":{"n":"Anguilla Flag","u":["🇦🇮"],"k":["ai","nation","country","banner"]},"flag-al":{"n":"Albania Flag","u":["🇦🇱"],"k":["al","nation","country","banner"]},"flag-am":{"n":"Armenia Flag","u":["🇦🇲"],"k":["am","nation","country","banner"]},"flag-ao":{"n":"Angola Flag","u":["🇦🇴"],"k":["ao","nation","country","banner"]},"flag-aq":{"n":"Antarctica Flag","u":["🇦🇶"],"k":["aq","nation","country","banner"]},"flag-ar":{"n":"Argentina Flag","u":["🇦🇷"],"k":["ar","nation","country","banner"]},"flag-as":{"n":"American Samoa Flag","u":["🇦🇸"],"k":["as","ws","nation","country","banner"]},"flag-at":{"n":"Austria Flag","u":["🇦🇹"],"k":["at","nation","country","banner"]},"flag-au":{"n":"Australia Flag","u":["🇦🇺"],"k":["au","nation","country","banner"]},"flag-aw":{"n":"Aruba Flag","u":["🇦🇼"],"k":["aw","nation","country","banner"]},"flag-ax":{"n":"Åland Islands Flag","u":["🇦🇽"],"k":["ax","aland","Aland","nation","country","banner"]},"flag-az":{"n":"Azerbaijan Flag","u":["🇦🇿"],"k":["az","nation","country","banner"]},"flag-ba":{"n":"Bosnia & Herzegovina Flag","u":["🇧🇦"],"k":["ba","nation","country","banner"]},"flag-bb":{"n":"Barbados Flag","u":["🇧🇧"],"k":["bb","nation","country","banner"]},"flag-bd":{"n":"Bangladesh Flag","u":["🇧🇩"],"k":["bd","nation","country","banner"]},"flag-be":{"n":"Belgium Flag","u":["🇧🇪"],"k":["be","nation","country","banner"]},"flag-bf":{"n":"Burkina Faso Flag","u":["🇧🇫"],"k":["bf","nation","country","banner"]},"flag-bg":{"n":"Bulgaria Flag","u":["🇧🇬"],"k":["bg","nation","country","banner"]},"flag-bh":{"n":"Bahrain Flag","u":["🇧🇭"],"k":["bh","nation","country","banner"]},"flag-bi":{"n":"Burundi Flag","u":["🇧🇮"],"k":["bi","nation","country","banner"]},"flag-bj":{"n":"Benin Flag","u":["🇧🇯"],"k":["bj","nation","country","banner"]},"flag-bl":{"n":"St. Barthélemy Flag","u":["🇧🇱"],"k":["bl","st","barthelemy","saint","nation","country","banner"]},"flag-bm":{"n":"Bermuda Flag","u":["🇧🇲"],"k":["bm","nation","country","banner"]},"flag-bn":{"n":"Brunei Flag","u":["🇧🇳"],"k":["bn","darussalam","nation","country","banner"]},"flag-bo":{"n":"Bolivia Flag","u":["🇧🇴"],"k":["bo","nation","country","banner"]},"flag-bq":{"n":"Caribbean Netherlands Flag","u":["🇧🇶"],"k":["bq","bonaire","nation","country","banner"]},"flag-br":{"n":"Brazil Flag","u":["🇧🇷"],"k":["br","nation","country","banner"]},"flag-bs":{"n":"Bahamas Flag","u":["🇧🇸"],"k":["bs","nation","country","banner"]},"flag-bt":{"n":"Bhutan Flag","u":["🇧🇹"],"k":["bt","nation","country","banner"]},"flag-bv":{"n":"Bouvet Island Flag","u":["🇧🇻"],"k":["bv","norway"]},"flag-bw":{"n":"Botswana Flag","u":["🇧🇼"],"k":["bw","nation","country","banner"]},"flag-by":{"n":"Belarus Flag","u":["🇧🇾"],"k":["by","nation","country","banner"]},"flag-bz":{"n":"Belize Flag","u":["🇧🇿"],"k":["bz","nation","country","banner"]},"flag-ca":{"n":"Canada Flag","u":["🇨🇦"],"k":["ca","nation","country","banner"]},"flag-cc":{"n":"Cocos (keeling) Islands Flag","u":["🇨🇨"],"k":["cc","keeling","nation","country","banner"]},"flag-cd":{"n":"Congo - Kinshasa Flag","u":["🇨🇩"],"k":["cd","democratic","republic","nation","country","banner"]},"flag-cf":{"n":"Central African Republic Flag","u":["🇨🇫"],"k":["cf","nation","country","banner"]},"flag-cg":{"n":"Congo - Brazzaville Flag","u":["🇨🇬"],"k":["cg","nation","country","banner"]},"flag-ch":{"n":"Switzerland Flag","u":["🇨🇭"],"k":["ch","nation","country","banner"]},"flag-ci":{"n":"Côte D’ivoire Flag","u":["🇨🇮"],"k":["ci","cote","d","ivoire","ivory","coast","nation","country","banner"]},"flag-ck":{"n":"Cook Islands Flag","u":["🇨🇰"],"k":["ck","nation","country","banner"]},"flag-cl":{"n":"Chile Flag","u":["🇨🇱"],"k":["cl","nation","country","banner"]},"flag-cm":{"n":"Cameroon Flag","u":["🇨🇲"],"k":["cm","nation","country","banner"]},"flag-co":{"n":"Colombia Flag","u":["🇨🇴"],"k":["co","nation","country","banner"]},"flag-cp":{"n":"Clipperton Island Flag","u":["🇨🇵"],"k":["cp"]},"flag-cr":{"n":"Costa Rica Flag","u":["🇨🇷"],"k":["cr","nation","country","banner"]},"flag-cu":{"n":"Cuba Flag","u":["🇨🇺"],"k":["cu","nation","country","banner"]},"flag-cv":{"n":"Cape Verde Flag","u":["🇨🇻"],"k":["cv","cabo","nation","country","banner"]},"flag-cw":{"n":"Curaçao Flag","u":["🇨🇼"],"k":["cw","curacao","nation","country","banner"]},"flag-cx":{"n":"Christmas Island Flag","u":["🇨🇽"],"k":["cx","nation","country","banner"]},"flag-cy":{"n":"Cyprus Flag","u":["🇨🇾"],"k":["cy","nation","country","banner"]},"flag-cz":{"n":"Czechia Flag","u":["🇨🇿"],"k":["cz","nation","country","banner"]},"flag-dg":{"n":"Diego Garcia Flag","u":["🇩🇬"],"k":["dg"]},"flag-dj":{"n":"Djibouti Flag","u":["🇩🇯"],"k":["dj","nation","country","banner"]},"flag-dk":{"n":"Denmark Flag","u":["🇩🇰"],"k":["dk","nation","country","banner"]},"flag-dm":{"n":"Dominica Flag","u":["🇩🇲"],"k":["dm","nation","country","banner"]},"flag-do":{"n":"Dominican Republic Flag","u":["🇩🇴"],"k":["do","nation","country","banner"]},"flag-dz":{"n":"Algeria Flag","u":["🇩🇿"],"k":["dz","nation","country","banner"]},"flag-ea":{"n":"Ceuta & Melilla Flag","u":["🇪🇦"],"k":["ea"]},"flag-ec":{"n":"Ecuador Flag","u":["🇪🇨"],"k":["ec","nation","country","banner"]},"flag-ee":{"n":"Estonia Flag","u":["🇪🇪"],"k":["ee","nation","country","banner"]},"flag-eg":{"n":"Egypt Flag","u":["🇪🇬"],"k":["eg","nation","country","banner"]},"flag-eh":{"n":"Western Sahara Flag","u":["🇪🇭"],"k":["eh","nation","country","banner"]},"flag-england":{"n":"England Flag","u":["🏴󠁧󠁢󠁥󠁮󠁧󠁿"],"k":["english"]},"flag-er":{"n":"Eritrea Flag","u":["🇪🇷"],"k":["er","nation","country","banner"]},"flag-et":{"n":"Ethiopia Flag","u":["🇪🇹"],"k":["et","nation","country","banner"]},"flag-eu":{"n":"European Union Flag","u":["🇪🇺"],"k":["eu","banner"]},"flag-fi":{"n":"Finland Flag","u":["🇫🇮"],"k":["fi","nation","country","banner"]},"flag-fj":{"n":"Fiji Flag","u":["🇫🇯"],"k":["fj","nation","country","banner"]},"flag-fk":{"n":"Falkland Islands Flag","u":["🇫🇰"],"k":["fk","malvinas","nation","country","banner"]},"flag-fm":{"n":"Micronesia Flag","u":["🇫🇲"],"k":["fm","federated","states","nation","country","banner"]},"flag-fo":{"n":"Faroe Islands Flag","u":["🇫🇴"],"k":["fo","nation","country","banner"]},"flag-ga":{"n":"Gabon Flag","u":["🇬🇦"],"k":["ga","nation","country","banner"]},"flag-gd":{"n":"Grenada Flag","u":["🇬🇩"],"k":["gd","nation","country","banner"]},"flag-ge":{"n":"Georgia Flag","u":["🇬🇪"],"k":["ge","nation","country","banner"]},"flag-gf":{"n":"French Guiana Flag","u":["🇬🇫"],"k":["gf","nation","country","banner"]},"flag-gg":{"n":"Guernsey Flag","u":["🇬🇬"],"k":["gg","nation","country","banner"]},"flag-gh":{"n":"Ghana Flag","u":["🇬🇭"],"k":["gh","nation","country","banner"]},"flag-gi":{"n":"Gibraltar Flag","u":["🇬🇮"],"k":["gi","nation","country","banner"]},"flag-gl":{"n":"Greenland Flag","u":["🇬🇱"],"k":["gl","nation","country","banner"]},"flag-gm":{"n":"Gambia Flag","u":["🇬🇲"],"k":["gm","nation","country","banner"]},"flag-gn":{"n":"Guinea Flag","u":["🇬🇳"],"k":["gn","nation","country","banner"]},"flag-gp":{"n":"Guadeloupe Flag","u":["🇬🇵"],"k":["gp","nation","country","banner"]},"flag-gq":{"n":"Equatorial Guinea Flag","u":["🇬🇶"],"k":["gq","gn","nation","country","banner"]},"flag-gr":{"n":"Greece Flag","u":["🇬🇷"],"k":["gr","nation","country","banner"]},"flag-gs":{"n":"South Georgia & South Sandwich Islands Flag","u":["🇬🇸"],"k":["gs","nation","country","banner"]},"flag-gt":{"n":"Guatemala Flag","u":["🇬🇹"],"k":["gt","nation","country","banner"]},"flag-gu":{"n":"Guam Flag","u":["🇬🇺"],"k":["gu","nation","country","banner"]},"flag-gw":{"n":"Guinea-Bissau Flag","u":["🇬🇼"],"k":["gw","guinea","bissau","nation","country","banner"]},"flag-gy":{"n":"Guyana Flag","u":["🇬🇾"],"k":["gy","nation","country","banner"]},"flag-hk":{"n":"Hong Kong Sar China Flag","u":["🇭🇰"],"k":["hk","nation","country","banner"]},"flag-hm":{"n":"Heard & Mcdonald Islands Flag","u":["🇭🇲"],"k":["hm"]},"flag-hn":{"n":"Honduras Flag","u":["🇭🇳"],"k":["hn","nation","country","banner"]},"flag-hr":{"n":"Croatia Flag","u":["🇭🇷"],"k":["hr","nation","country","banner"]},"flag-ht":{"n":"Haiti Flag","u":["🇭🇹"],"k":["ht","nation","country","banner"]},"flag-hu":{"n":"Hungary Flag","u":["🇭🇺"],"k":["hu","nation","country","banner"]},"flag-ic":{"n":"Canary Islands Flag","u":["🇮🇨"],"k":["ic","nation","country","banner"]},"flag-id":{"n":"Indonesia Flag","u":["🇮🇩"],"k":["id","nation","country","banner"]},"flag-ie":{"n":"Ireland Flag","u":["🇮🇪"],"k":["ie","nation","country","banner"]},"flag-il":{"n":"Israel Flag","u":["🇮🇱"],"k":["il","nation","country","banner"]},"flag-im":{"n":"Isle of Man Flag","u":["🇮🇲"],"k":["im","nation","country","banner"]},"flag-in":{"n":"India Flag","u":["🇮🇳"],"k":["in","nation","country","banner"]},"flag-io":{"n":"British Indian Ocean Territory Flag","u":["🇮🇴"],"k":["io","nation","country","banner"]},"flag-iq":{"n":"Iraq Flag","u":["🇮🇶"],"k":["iq","nation","country","banner"]},"flag-ir":{"n":"Iran Flag","u":["🇮🇷"],"k":["ir","islamic","republic","nation","country","banner"]},"flag-is":{"n":"Iceland Flag","u":["🇮🇸"],"k":["is","nation","country","banner"]},"flag-je":{"n":"Jersey Flag","u":["🇯🇪"],"k":["je","nation","country","banner"]},"flag-jm":{"n":"Jamaica Flag","u":["🇯🇲"],"k":["jm","nation","country","banner"]},"flag-jo":{"n":"Jordan Flag","u":["🇯🇴"],"k":["jo","nation","country","banner"]},"flag-ke":{"n":"Kenya Flag","u":["🇰🇪"],"k":["ke","nation","country","banner"]},"flag-kg":{"n":"Kyrgyzstan Flag","u":["🇰🇬"],"k":["kg","nation","country","banner"]},"flag-kh":{"n":"Cambodia Flag","u":["🇰🇭"],"k":["kh","nation","country","banner"]},"flag-ki":{"n":"Kiribati Flag","u":["🇰🇮"],"k":["ki","nation","country","banner"]},"flag-km":{"n":"Comoros Flag","u":["🇰🇲"],"k":["km","nation","country","banner"]},"flag-kn":{"n":"St. Kitts & Nevis Flag","u":["🇰🇳"],"k":["kn","st","saint","nation","country","banner"]},"flag-kp":{"n":"North Korea Flag","u":["🇰🇵"],"k":["kp","nation","country","banner"]},"flag-kw":{"n":"Kuwait Flag","u":["🇰🇼"],"k":["kw","nation","country","banner"]},"flag-ky":{"n":"Cayman Islands Flag","u":["🇰🇾"],"k":["ky","nation","country","banner"]},"flag-kz":{"n":"Kazakhstan Flag","u":["🇰🇿"],"k":["kz","nation","country","banner"]},"flag-la":{"n":"Laos Flag","u":["🇱🇦"],"k":["la","lao","democratic","republic","nation","country","banner"]},"flag-lb":{"n":"Lebanon Flag","u":["🇱🇧"],"k":["lb","nation","country","banner"]},"flag-lc":{"n":"St. Lucia Flag","u":["🇱🇨"],"k":["lc","st","saint","nation","country","banner"]},"flag-li":{"n":"Liechtenstein Flag","u":["🇱🇮"],"k":["li","nation","country","banner"]},"flag-lk":{"n":"Sri Lanka Flag","u":["🇱🇰"],"k":["lk","nation","country","banner"]},"flag-lr":{"n":"Liberia Flag","u":["🇱🇷"],"k":["lr","nation","country","banner"]},"flag-ls":{"n":"Lesotho Flag","u":["🇱🇸"],"k":["ls","nation","country","banner"]},"flag-lt":{"n":"Lithuania Flag","u":["🇱🇹"],"k":["lt","nation","country","banner"]},"flag-lu":{"n":"Luxembourg Flag","u":["🇱🇺"],"k":["lu","nation","country","banner"]},"flag-lv":{"n":"Latvia Flag","u":["🇱🇻"],"k":["lv","nation","country","banner"]},"flag-ly":{"n":"Libya Flag","u":["🇱🇾"],"k":["ly","nation","country","banner"]},"flag-ma":{"n":"Morocco Flag","u":["🇲🇦"],"k":["ma","nation","country","banner"]},"flag-mc":{"n":"Monaco Flag","u":["🇲🇨"],"k":["mc","nation","country","banner"]},"flag-md":{"n":"Moldova Flag","u":["🇲🇩"],"k":["md","republic","nation","country","banner"]},"flag-me":{"n":"Montenegro Flag","u":["🇲🇪"],"k":["me","nation","country","banner"]},"flag-mf":{"n":"St. Martin Flag","u":["🇲🇫"],"k":["mf","st"]},"flag-mg":{"n":"Madagascar Flag","u":["🇲🇬"],"k":["mg","nation","country","banner"]},"flag-mh":{"n":"Marshall Islands Flag","u":["🇲🇭"],"k":["mh","nation","country","banner"]},"flag-mk":{"n":"North Macedonia Flag","u":["🇲🇰"],"k":["mk","nation","country","banner"]},"flag-ml":{"n":"Mali Flag","u":["🇲🇱"],"k":["ml","nation","country","banner"]},"flag-mm":{"n":"Myanmar (burma) Flag","u":["🇲🇲"],"k":["mm","nation","country","banner"]},"flag-mn":{"n":"Mongolia Flag","u":["🇲🇳"],"k":["mn","nation","country","banner"]},"flag-mo":{"n":"Macao Sar China Flag","u":["🇲🇴"],"k":["mo","nation","country","banner"]},"flag-mp":{"n":"Northern Mariana Islands Flag","u":["🇲🇵"],"k":["mp","nation","country","banner"]},"flag-mq":{"n":"Martinique Flag","u":["🇲🇶"],"k":["mq","nation","country","banner"]},"flag-mr":{"n":"Mauritania Flag","u":["🇲🇷"],"k":["mr","nation","country","banner"]},"flag-ms":{"n":"Montserrat Flag","u":["🇲🇸"],"k":["ms","nation","country","banner"]},"flag-mt":{"n":"Malta Flag","u":["🇲🇹"],"k":["mt","nation","country","banner"]},"flag-mu":{"n":"Mauritius Flag","u":["🇲🇺"],"k":["mu","nation","country","banner"]},"flag-mv":{"n":"Maldives Flag","u":["🇲🇻"],"k":["mv","nation","country","banner"]},"flag-mw":{"n":"Malawi Flag","u":["🇲🇼"],"k":["mw","nation","country","banner"]},"flag-mx":{"n":"Mexico Flag","u":["🇲🇽"],"k":["mx","nation","country","banner"]},"flag-my":{"n":"Malaysia Flag","u":["🇲🇾"],"k":["my","nation","country","banner"]},"flag-mz":{"n":"Mozambique Flag","u":["🇲🇿"],"k":["mz","nation","country","banner"]},"flag-na":{"n":"Namibia Flag","u":["🇳🇦"],"k":["na","nation","country","banner"]},"flag-nc":{"n":"New Caledonia Flag","u":["🇳🇨"],"k":["nc","nation","country","banner"]},"flag-ne":{"n":"Niger Flag","u":["🇳🇪"],"k":["ne","nation","country","banner"]},"flag-nf":{"n":"Norfolk Island Flag","u":["🇳🇫"],"k":["nf","nation","country","banner"]},"flag-ng":{"n":"Nigeria Flag","u":["🇳🇬"],"k":["ng","nation","country","banner"]},"flag-ni":{"n":"Nicaragua Flag","u":["🇳🇮"],"k":["ni","nation","country","banner"]},"flag-nl":{"n":"Netherlands Flag","u":["🇳🇱"],"k":["nl","nation","country","banner"]},"flag-no":{"n":"Norway Flag","u":["🇳🇴"],"k":["no","nation","country","banner"]},"flag-np":{"n":"Nepal Flag","u":["🇳🇵"],"k":["np","nation","country","banner"]},"flag-nr":{"n":"Nauru Flag","u":["🇳🇷"],"k":["nr","nation","country","banner"]},"flag-nu":{"n":"Niue Flag","u":["🇳🇺"],"k":["nu","nation","country","banner"]},"flag-nz":{"n":"New Zealand Flag","u":["🇳🇿"],"k":["nz","nation","country","banner"]},"flag-om":{"n":"Oman Flag","u":["🇴🇲"],"k":["om","symbol","nation","country","banner"]},"flag-pa":{"n":"Panama Flag","u":["🇵🇦"],"k":["pa","nation","country","banner"]},"flag-pe":{"n":"Peru Flag","u":["🇵🇪"],"k":["pe","nation","country","banner"]},"flag-pf":{"n":"French Polynesia Flag","u":["🇵🇫"],"k":["pf","nation","country","banner"]},"flag-pg":{"n":"Papua New Guinea Flag","u":["🇵🇬"],"k":["pg","nation","country","banner"]},"flag-ph":{"n":"Philippines Flag","u":["🇵🇭"],"k":["ph","nation","country","banner"]},"flag-pk":{"n":"Pakistan Flag","u":["🇵🇰"],"k":["pk","nation","country","banner"]},"flag-pl":{"n":"Poland Flag","u":["🇵🇱"],"k":["pl","nation","country","banner"]},"flag-pm":{"n":"St. Pierre & Miquelon Flag","u":["🇵🇲"],"k":["pm","st","saint","nation","country","banner"]},"flag-pn":{"n":"Pitcairn Islands Flag","u":["🇵🇳"],"k":["pn","nation","country","banner"]},"flag-pr":{"n":"Puerto Rico Flag","u":["🇵🇷"],"k":["pr","nation","country","banner"]},"flag-ps":{"n":"Palestinian Territories Flag","u":["🇵🇸"],"k":["ps","palestine","nation","country","banner"]},"flag-pt":{"n":"Portugal Flag","u":["🇵🇹"],"k":["pt","nation","country","banner"]},"flag-pw":{"n":"Palau Flag","u":["🇵🇼"],"k":["pw","nation","country","banner"]},"flag-py":{"n":"Paraguay Flag","u":["🇵🇾"],"k":["py","nation","country","banner"]},"flag-qa":{"n":"Qatar Flag","u":["🇶🇦"],"k":["qa","nation","country","banner"]},"flag-re":{"n":"Réunion Flag","u":["🇷🇪"],"k":["re","reunion","nation","country","banner"]},"flag-ro":{"n":"Romania Flag","u":["🇷🇴"],"k":["ro","nation","country","banner"]},"flag-rs":{"n":"Serbia Flag","u":["🇷🇸"],"k":["rs","nation","country","banner"]},"flag-rw":{"n":"Rwanda Flag","u":["🇷🇼"],"k":["rw","nation","country","banner"]},"flag-sa":{"n":"Saudi Arabia Flag","u":["🇸🇦"],"k":["sa","nation","country","banner"]},"flag-sb":{"n":"Solomon Islands Flag","u":["🇸🇧"],"k":["sb","nation","country","banner"]},"flag-sc":{"n":"Seychelles Flag","u":["🇸🇨"],"k":["sc","nation","country","banner"]},"flag-scotland":{"n":"Scotland Flag","u":["🏴󠁧󠁢󠁳󠁣󠁴󠁿"],"k":["scottish"]},"flag-sd":{"n":"Sudan Flag","u":["🇸🇩"],"k":["sd","nation","country","banner"]},"flag-se":{"n":"Sweden Flag","u":["🇸🇪"],"k":["se","nation","country","banner"]},"flag-sg":{"n":"Singapore Flag","u":["🇸🇬"],"k":["sg","nation","country","banner"]},"flag-sh":{"n":"St. Helena Flag","u":["🇸🇭"],"k":["sh","st","saint","ascension","tristan","cunha","nation","country","banner"]},"flag-si":{"n":"Slovenia Flag","u":["🇸🇮"],"k":["si","nation","country","banner"]},"flag-sj":{"n":"Svalbard & Jan Mayen Flag","u":["🇸🇯"],"k":["sj"]},"flag-sk":{"n":"Slovakia Flag","u":["🇸🇰"],"k":["sk","nation","country","banner"]},"flag-sl":{"n":"Sierra Leone Flag","u":["🇸🇱"],"k":["sl","nation","country","banner"]},"flag-sm":{"n":"San Marino Flag","u":["🇸🇲"],"k":["sm","nation","country","banner"]},"flag-sn":{"n":"Senegal Flag","u":["🇸🇳"],"k":["sn","nation","country","banner"]},"flag-so":{"n":"Somalia Flag","u":["🇸🇴"],"k":["so","nation","country","banner"]},"flag-sr":{"n":"Suriname Flag","u":["🇸🇷"],"k":["sr","nation","country","banner"]},"flag-ss":{"n":"South Sudan Flag","u":["🇸🇸"],"k":["ss","sd","nation","country","banner"]},"flag-st":{"n":"São Tomé & Príncipe Flag","u":["🇸🇹"],"k":["st","sao","tome","principe","nation","country","banner"]},"flag-sv":{"n":"El Salvador Flag","u":["🇸🇻"],"k":["sv","nation","country","banner"]},"flag-sx":{"n":"Sint Maarten Flag","u":["🇸🇽"],"k":["sx","dutch","nation","country","banner"]},"flag-sy":{"n":"Syria Flag","u":["🇸🇾"],"k":["sy","syrian","arab","republic","nation","country","banner"]},"flag-sz":{"n":"Eswatini Flag","u":["🇸🇿"],"k":["sz","nation","country","banner"]},"flag-ta":{"n":"Tristan Da Cunha Flag","u":["🇹🇦"],"k":["ta"]},"flag-tc":{"n":"Turks & Caicos Islands Flag","u":["🇹🇨"],"k":["tc","nation","country","banner"]},"flag-td":{"n":"Chad Flag","u":["🇹🇩"],"k":["td","nation","country","banner"]},"flag-tf":{"n":"French Southern Territories Flag","u":["🇹🇫"],"k":["tf","nation","country","banner"]},"flag-tg":{"n":"Togo Flag","u":["🇹🇬"],"k":["tg","nation","country","banner"]},"flag-th":{"n":"Thailand Flag","u":["🇹🇭"],"k":["th","nation","country","banner"]},"flag-tj":{"n":"Tajikistan Flag","u":["🇹🇯"],"k":["tj","nation","country","banner"]},"flag-tk":{"n":"Tokelau Flag","u":["🇹🇰"],"k":["tk","nation","country","banner"]},"flag-tl":{"n":"Timor-Leste Flag","u":["🇹🇱"],"k":["tl","timor","leste","nation","country","banner"]},"flag-tm":{"n":"Turkmenistan Flag","u":["🇹🇲"],"k":["tm","nation","country","banner"]},"flag-tn":{"n":"Tunisia Flag","u":["🇹🇳"],"k":["tn","nation","country","banner"]},"flag-to":{"n":"Tonga Flag","u":["🇹🇴"],"k":["to","nation","country","banner"]},"flag-tr":{"n":"Turkey Flag","u":["🇹🇷"],"k":["tr","nation","country","banner"]},"flag-tt":{"n":"Trinidad & Tobago Flag","u":["🇹🇹"],"k":["tt","nation","country","banner"]},"flag-tv":{"n":"Tuvalu Flag","u":["🇹🇻"],"k":["tv","nation","country","banner"]},"flag-tw":{"n":"Taiwan Flag","u":["🇹🇼"],"k":["tw","nation","country","banner"]},"flag-tz":{"n":"Tanzania Flag","u":["🇹🇿"],"k":["tz","united","republic","nation","country","banner"]},"flag-ua":{"n":"Ukraine Flag","u":["🇺🇦"],"k":["ua","nation","country","banner"]},"flag-ug":{"n":"Uganda Flag","u":["🇺🇬"],"k":["ug","nation","country","banner"]},"flag-um":{"n":"U.s. Outlying Islands Flag","u":["🇺🇲"],"k":["um","u","s"]},"flag-un":{"n":"United Nations Flag","u":["🇺🇳"],"k":["un","banner"]},"flag-uy":{"n":"Uruguay Flag","u":["🇺🇾"],"k":["uy","nation","country","banner"]},"flag-uz":{"n":"Uzbekistan Flag","u":["🇺🇿"],"k":["uz","nation","country","banner"]},"flag-va":{"n":"Vatican City Flag","u":["🇻🇦"],"k":["va","nation","country","banner"]},"flag-vc":{"n":"St. Vincent & Grenadines Flag","u":["🇻🇨"],"k":["vc","st","saint","nation","country","banner"]},"flag-ve":{"n":"Venezuela Flag","u":["🇻🇪"],"k":["ve","bolivarian","republic","nation","country","banner"]},"flag-vg":{"n":"British Virgin Islands Flag","u":["🇻🇬"],"k":["vg","bvi","nation","country","banner"]},"flag-vi":{"n":"U.s. Virgin Islands Flag","u":["🇻🇮"],"k":["vi","u","s","us","nation","country","banner"]},"flag-vn":{"n":"Vietnam Flag","u":["🇻🇳"],"k":["vn","viet","nam","nation","country","banner"]},"flag-vu":{"n":"Vanuatu Flag","u":["🇻🇺"],"k":["vu","nation","country","banner"]},"flag-wales":{"n":"Wales Flag","u":["🏴󠁧󠁢󠁷󠁬󠁳󠁿"],"k":["welsh"]},"flag-wf":{"n":"Wallis & Futuna Flag","u":["🇼🇫"],"k":["wf","nation","country","banner"]},"flag-ws":{"n":"Samoa Flag","u":["🇼🇸"],"k":["ws","nation","country","banner"]},"flag-xk":{"n":"Kosovo Flag","u":["🇽🇰"],"k":["xk","nation","country","banner"]},"flag-ye":{"n":"Yemen Flag","u":["🇾🇪"],"k":["ye","nation","country","banner"]},"flag-yt":{"n":"Mayotte Flag","u":["🇾🇹"],"k":["yt","nation","country","banner"]},"flag-za":{"n":"South Africa Flag","u":["🇿🇦"],"k":["za","nation","country","banner"]},"flag-zm":{"n":"Zambia Flag","u":["🇿🇲"],"k":["zm","nation","country","banner"]},"flag-zw":{"n":"Zimbabwe Flag","u":["🇿🇼"],"k":["zw","nation","country","banner"]},"fr":{"n":"France Flag","u":["🇫🇷"],"k":["fr","banner","nation","french","country"]},"gb":{"n":"United Kingdom Flag","u":["🇬🇧"],"k":["gb","uk","great","britain","northern","ireland","nation","country","banner","british","UK","english","england","union","jack"]},"it":{"n":"Italy Flag","u":["🇮🇹"],"k":["it","nation","country","banner"]},"jp":{"n":"Japan Flag","u":["🇯🇵"],"k":["jp","japanese","nation","country","banner","ja"]},"kr":{"n":"South Korea Flag","u":["🇰🇷"],"k":["kr","nation","country","banner"]},"pirate_flag":{"n":"Pirate Flag","u":["🏴‍☠️"],"k":["skull","crossbones","banner"]},"rainbow-flag":{"n":"Rainbow Flag","u":["🏳️‍🌈"],"k":["pride","gay","lgbt","glbt","queer","homosexual","lesbian","bisexual","transgender"]},"ru":{"n":"Russia Flag","u":["🇷🇺"],"k":["ru","russian","federation","nation","country","banner"]},"transgender_flag":{"n":"Transgender Flag","u":["🏳️‍⚧️"],"k":["lgbtq"]},"triangular_flag_on_post":{"n":"Triangular Flag","u":["🚩"],"k":["on","post","mark","milestone","place"]},"us":{"n":"United States Flag","u":["🇺🇸"],"k":["us","america","nation","country","banner"]},"waving_black_flag":{"n":"Black Flag","u":["🏴"],"k":["waving","pirate"]},"waving_white_flag":{"n":"White Flag","u":["🏳️"],"k":["waving","losing","loser","lost","surrender","give","up","fail"]}}}
diff --git a/mobile/ios/Runner/InlinePhotoPicker.swift b/mobile/ios/Runner/InlinePhotoPicker.swift
index 4b8d1365df..05a576323f 100644
--- a/mobile/ios/Runner/InlinePhotoPicker.swift
+++ b/mobile/ios/Runner/InlinePhotoPicker.swift
@@ -3,6 +3,14 @@ import PhotosUI
 import UIKit
 import UniformTypeIdentifiers
 
+enum EmbeddedPhotoPickerLayout {
+  static func applyPreferredScale(_ zoomIn: () -> Void) {
+    UIView.performWithoutAnimation {
+      zoomIn()
+    }
+  }
+}
+
 final class InlinePhotoPickerFactory: NSObject, FlutterPlatformViewFactory {
   private let messenger: FlutterBinaryMessenger
   private weak var parentViewController: UIViewController?
@@ -68,6 +76,7 @@ final class InlinePhotoPickerPlatformView: NSObject, FlutterPlatformView {
     }
 
     containerView.backgroundColor = .clear
+    containerView.clipsToBounds = true
     if #available(iOS 17.0, *) {
       installPicker()
     }
@@ -120,6 +129,10 @@ final class InlinePhotoPickerPlatformView: NSObject, FlutterPlatformView {
       picker.didMove(toParent: parentViewController)
     }
     pickerViewController = picker
+    containerView.layoutIfNeeded()
+    EmbeddedPhotoPickerLayout.applyPreferredScale {
+      picker.zoomIn()
+    }
   }
 
   private func exportPickerResult(_ result: PHPickerResult) async throws -> String {
diff --git a/mobile/ios/Runner/NativeAttachmentPopover.swift b/mobile/ios/Runner/NativeAttachmentPopover.swift
index bb49ca6e46..f2f6c01df8 100644
--- a/mobile/ios/Runner/NativeAttachmentPopover.swift
+++ b/mobile/ios/Runner/NativeAttachmentPopover.swift
@@ -17,12 +17,12 @@ final class NativeAttachmentPopoverViewController:
     case camera
   }
 
+  private typealias ContentPreparation = (@escaping () -> Void) -> Void
+
   private let channel: FlutterMethodChannel
   private let expandedWidth: CGFloat
-  private let menuSize = CGSize(width: 176, height: 208)
-  private let expandedHeight: CGFloat = 372
-  private let expandedHorizontalOffset: CGFloat = 10
-  private let expandedVerticalOffset: CGFloat = 40
+  private let maximumMenuHeight: CGFloat
+  private let expandedHeight = NativeAttachmentMenuLayout.maximumHeight
   private let contentHost = UIView()
   private let cameraSession = AVCaptureSession()
   private let cameraOutput = AVCapturePhotoOutput()
@@ -50,14 +50,31 @@ final class NativeAttachmentPopoverViewController:
   private var activeCameraCaptureID: Int64?
   private var isFinishing = false
   private var didNotifyDismissal = false
+  private var keyboardDismissalOffset: CGFloat = 0
+  private var menuStackHeightConstraint: NSLayoutConstraint?
 
   var onDismiss: (() -> Void)?
 
-  init(channel: FlutterMethodChannel, expandedWidth: CGFloat) {
+  private var menuSize: CGSize {
+    NativeAttachmentMenuLayout.size(
+      compatibleWith: traitCollection,
+      maximumHeight: maximumMenuHeight
+    )
+  }
+
+  init(
+    channel: FlutterMethodChannel,
+    expandedWidth: CGFloat,
+    maximumMenuHeight: CGFloat = NativeAttachmentMenuLayout.maximumHeight
+  ) {
     self.channel = channel
     self.expandedWidth = expandedWidth
+    self.maximumMenuHeight = maximumMenuHeight
     super.init(nibName: nil, bundle: nil)
-    preferredContentSize = menuSize
+    preferredContentSize = NativeAttachmentMenuLayout.size(
+      compatibleWith: .current,
+      maximumHeight: maximumMenuHeight
+    )
   }
 
   @available(*, unavailable)
@@ -106,6 +123,20 @@ final class NativeAttachmentPopoverViewController:
     stopCamera()
   }
 
+  override func traitCollectionDidChange(
+    _ previousTraitCollection: UITraitCollection?
+  ) {
+    super.traitCollectionDidChange(previousTraitCollection)
+    guard
+      previousTraitCollection?.preferredContentSizeCategory
+        != traitCollection.preferredContentSizeCategory
+    else {
+      return
+    }
+
+    updateMenuLayout()
+  }
+
   func adaptivePresentationStyle(
     for controller: UIPresentationController
   ) -> UIModalPresentationStyle {
@@ -122,16 +153,45 @@ final class NativeAttachmentPopoverViewController:
     let container = UIView()
     container.translatesAutoresizingMaskIntoConstraints = false
 
+    let scrollView = UIScrollView()
+    scrollView.alwaysBounceVertical = false
+    scrollView.translatesAutoresizingMaskIntoConstraints = false
+    container.addSubview(scrollView)
+
     let stack = UIStackView()
     stack.axis = .vertical
     stack.distribution = .fillEqually
+    stack.spacing = NativeAttachmentMenuLayout.itemSpacing
     stack.translatesAutoresizingMaskIntoConstraints = false
-    container.addSubview(stack)
+    scrollView.addSubview(stack)
+    let stackHeightConstraint = stack.heightAnchor.constraint(
+      equalToConstant: NativeAttachmentMenuLayout.itemsHeight(
+        compatibleWith: traitCollection
+      )
+    )
+    menuStackHeightConstraint = stackHeightConstraint
     NSLayoutConstraint.activate([
-      stack.leadingAnchor.constraint(equalTo: container.leadingAnchor),
-      stack.trailingAnchor.constraint(equalTo: container.trailingAnchor),
-      stack.topAnchor.constraint(equalTo: container.topAnchor, constant: 8),
-      stack.bottomAnchor.constraint(equalTo: container.bottomAnchor, constant: -8),
+      scrollView.leadingAnchor.constraint(equalTo: container.leadingAnchor),
+      scrollView.trailingAnchor.constraint(equalTo: container.trailingAnchor),
+      scrollView.topAnchor.constraint(equalTo: container.topAnchor),
+      scrollView.bottomAnchor.constraint(equalTo: container.bottomAnchor),
+      stack.leadingAnchor.constraint(
+        equalTo: scrollView.frameLayoutGuide.leadingAnchor,
+        constant: NativeAttachmentMenuLayout.contentPadding
+      ),
+      stack.trailingAnchor.constraint(
+        equalTo: scrollView.frameLayoutGuide.trailingAnchor,
+        constant: -NativeAttachmentMenuLayout.contentPadding
+      ),
+      stack.topAnchor.constraint(
+        equalTo: scrollView.contentLayoutGuide.topAnchor,
+        constant: NativeAttachmentMenuLayout.contentPadding
+      ),
+      stack.bottomAnchor.constraint(
+        equalTo: scrollView.contentLayoutGuide.bottomAnchor,
+        constant: -NativeAttachmentMenuLayout.contentPadding
+      ),
+      stackHeightConstraint,
     ])
 
     stack.addArrangedSubview(
@@ -169,8 +229,19 @@ final class NativeAttachmentPopoverViewController:
     return container
   }
 
+  private func updateMenuLayout() {
+    menuStackHeightConstraint?.constant =
+      NativeAttachmentMenuLayout.itemsHeight(
+        compatibleWith: traitCollection
+      )
+    if surface == .menu {
+      preferredContentSize = menuSize
+    }
+  }
+
   private func showPhotos() {
     guard surface != .photos else { return }
+    prepareForExpandedSurface()
     stopCamera()
 
     var configuration = PHPickerConfiguration(photoLibrary: .shared())
@@ -192,16 +263,14 @@ final class NativeAttachmentPopoverViewController:
 
     let container = UIView()
     container.backgroundColor = .clear
+    container.clipsToBounds = true
     addChild(picker)
     picker.view.translatesAutoresizingMaskIntoConstraints = false
     container.addSubview(picker.view)
     NSLayoutConstraint.activate([
       picker.view.leadingAnchor.constraint(equalTo: container.leadingAnchor),
       picker.view.trailingAnchor.constraint(equalTo: container.trailingAnchor),
-      picker.view.topAnchor.constraint(
-        equalTo: container.topAnchor,
-        constant: -8
-      ),
+      picker.view.topAnchor.constraint(equalTo: container.topAnchor),
       picker.view.bottomAnchor.constraint(equalTo: container.bottomAnchor),
     ])
     picker.didMove(toParent: self)
@@ -227,11 +296,32 @@ final class NativeAttachmentPopoverViewController:
       trailing: actionButton
     )
 
-    transition(to: .photos, content: container)
+    transition(
+      to: .photos,
+      content: container,
+      preparation: { [weak picker] reveal in
+        guard let picker else {
+          reveal()
+          return
+        }
+        // PHPicker ignores scale changes while its remote grid is still
+        // adapting to the compact menu bounds. Give it one main-loop turn at
+        // the final popover size, apply the scale offscreen, then reveal it.
+        DispatchQueue.main.async {
+          picker.view.layoutIfNeeded()
+          EmbeddedPhotoPickerLayout.applyPreferredScale {
+            picker.zoomIn()
+            picker.view.layoutIfNeeded()
+          }
+          DispatchQueue.main.async(execute: reveal)
+        }
+      }
+    )
   }
 
   private func showCamera() {
     guard surface != .camera else { return }
+    prepareForExpandedSurface()
     removePhotoPicker()
 
     let container = UIView()
@@ -288,9 +378,26 @@ final class NativeAttachmentPopoverViewController:
     stopCamera()
 
     let menu = makeMenuView()
-    transition(to: .menu, content: menu) { [weak self] in
-      self?.removePhotoPicker()
+    transition(
+      to: .menu,
+      content: menu,
+      completion: { [weak self] in
+        self?.removePhotoPicker()
+      }
+    )
+  }
+
+  private func prepareForExpandedSurface() {
+    if let sourceHost = popoverPresentationController?.sourceView?.superview {
+      keyboardDismissalOffset = max(
+        keyboardDismissalOffset,
+        NativeAttachmentExpandedSurfaceBehavior.keyboardOverlap(
+          containerBounds: sourceHost.bounds,
+          keyboardLayoutFrame: sourceHost.keyboardLayoutGuide.layoutFrame
+        )
+      )
     }
+    NativeAttachmentExpandedSurfaceBehavior.dismissKeyboard(in: view.window)
   }
 
   private func installContent(_ content: UIView) {
@@ -308,6 +415,7 @@ final class NativeAttachmentPopoverViewController:
   private func transition(
     to nextSurface: Surface,
     content nextView: UIView,
+    preparation: ContentPreparation? = nil,
     completion: (() -> Void)? = nil
   ) {
     let previousView = visibleContentView
@@ -327,50 +435,61 @@ final class NativeAttachmentPopoverViewController:
     ])
     contentHost.layoutIfNeeded()
 
-    let direction: CGFloat = isExpanding ? 34 : -34
-    nextView.alpha = UIAccessibility.isReduceMotionEnabled ? 0 : 0.01
-    nextView.transform =
-      UIAccessibility.isReduceMotionEnabled
-      ? .identity
-      : CGAffineTransform(translationX: direction, y: 0).scaledBy(
-        x: 0.97,
-        y: 0.97
-      )
+    let shouldAnimate = !UIAccessibility.isReduceMotionEnabled
+    // Do not expose embedded surfaces while the popover changes size. In
+    // particular, PHPicker visibly reflows its grid from the compact menu
+    // width to the expanded width if it is allowed to paint during this step.
+    nextView.alpha = 0
     visibleContentView = nextView
     surface = nextSurface
 
-    let duration = UIAccessibility.isReduceMotionEnabled ? 0.16 : 0.36
+    let duration = shouldAnimate ? (isExpanding ? 0.24 : 0.2) : 0
     UIView.animate(
       withDuration: duration,
       delay: 0,
-      usingSpringWithDamping: 0.86,
-      initialSpringVelocity: 0.18,
-      options: [.beginFromCurrentState, .allowUserInteraction]
+      options: [
+        .beginFromCurrentState,
+        .allowUserInteraction,
+        .curveEaseInOut,
+      ]
     ) {
       self.preferredContentSize = targetSize
       if let popover = self.popoverPresentationController,
         let sourceView = popover.sourceView
       {
-        popover.sourceRect = sourceView.bounds.offsetBy(
-          dx: isExpanding ? self.expandedHorizontalOffset : 0,
-          dy: isExpanding ? self.expandedVerticalOffset : 0
+        popover.sourceRect = NativeAttachmentPopoverAnchorLayout.sourceRect(
+          anchorBounds: sourceView.bounds,
+          keyboardDismissalOffset: self.keyboardDismissalOffset,
+          isExpanded: isExpanding
         )
       }
       previousView?.alpha = 0
-      previousView?.transform =
-        UIAccessibility.isReduceMotionEnabled
-        ? .identity
-        : CGAffineTransform(translationX: -direction, y: 0).scaledBy(
-          x: 0.97,
-          y: 0.97
-        )
-      nextView.alpha = 1
-      nextView.transform = .identity
       self.view.layoutIfNeeded()
     } completion: { _ in
       previousView?.removeFromSuperview()
-      previousView?.transform = .identity
-      completion?()
+      self.view.layoutIfNeeded()
+
+      let reveal = {
+        UIView.animate(
+          withDuration: shouldAnimate ? 0.14 : 0,
+          delay: 0,
+          options: [
+            .beginFromCurrentState,
+            .allowUserInteraction,
+            .curveEaseOut,
+          ]
+        ) {
+          nextView.alpha = 1
+        } completion: { _ in
+          completion?()
+        }
+      }
+
+      if let preparation {
+        preparation(reveal)
+      } else {
+        reveal()
+      }
     }
   }
 
@@ -917,6 +1036,7 @@ final class NativeAttachmentPopoverViewController:
       Self.removeTemporaryFiles(temporaryPaths)
       return
     }
+    NativeAttachmentExpandedSurfaceBehavior.dismissKeyboard(in: view.window)
     isFinishing = true
     view.isUserInteractionEnabled = false
     selectionGeneration += 1
diff --git a/mobile/ios/Runner/NativeAttachmentPopoverCoordinator.swift b/mobile/ios/Runner/NativeAttachmentPopoverCoordinator.swift
index 4b9c32ffcd..73559d7c2b 100644
--- a/mobile/ios/Runner/NativeAttachmentPopoverCoordinator.swift
+++ b/mobile/ios/Runner/NativeAttachmentPopoverCoordinator.swift
@@ -1,6 +1,71 @@
 import Flutter
 import UIKit
 
+enum NativeAttachmentExpandedSurfaceBehavior {
+  @MainActor
+  static func dismissKeyboard(in window: UIWindow?) {
+    window?.endEditing(true)
+  }
+
+  static func keyboardOverlap(
+    containerBounds: CGRect,
+    keyboardLayoutFrame: CGRect
+  ) -> CGFloat {
+    guard
+      !keyboardLayoutFrame.isNull,
+      !keyboardLayoutFrame.isInfinite,
+      keyboardLayoutFrame.minY < containerBounds.maxY
+    else {
+      return 0
+    }
+    return max(0, containerBounds.maxY - keyboardLayoutFrame.minY)
+  }
+}
+
+enum NativeAttachmentPopoverAnchorLayout {
+  static let expandedVerticalOffset: CGFloat = 40
+
+  static func sourceRect(
+    anchorBounds: CGRect,
+    keyboardDismissalOffset: CGFloat,
+    isExpanded: Bool
+  ) -> CGRect {
+    anchorBounds.offsetBy(
+      dx: 0,
+      dy: keyboardDismissalOffset
+        + (isExpanded ? expandedVerticalOffset : 0)
+    )
+  }
+}
+
+enum NativeAttachmentPopoverPresentationLayout {
+  static func keyboardDismissalOffset(
+    sourceRect: CGRect,
+    containerBounds: CGRect,
+    safeAreaInsets: UIEdgeInsets,
+    keyboardLayoutFrame: CGRect,
+    menuHeight: CGFloat
+  ) -> CGFloat {
+    let keyboardOverlap =
+      NativeAttachmentExpandedSurfaceBehavior.keyboardOverlap(
+        containerBounds: containerBounds,
+        keyboardLayoutFrame: keyboardLayoutFrame
+      )
+    guard keyboardOverlap > 0 else { return 0 }
+
+    let availableHeight =
+      sourceRect.minY - (containerBounds.minY + safeAreaInsets.top)
+    return availableHeight >= menuHeight ? 0 : keyboardOverlap
+  }
+
+  static func sourceRect(
+    _ sourceRect: CGRect,
+    keyboardDismissalOffset: CGFloat
+  ) -> CGRect {
+    sourceRect.offsetBy(dx: 0, dy: keyboardDismissalOffset)
+  }
+}
+
 final class NativeAttachmentPopoverCoordinator: NSObject {
   private let channel: FlutterMethodChannel
   private weak var parentViewController: UIViewController?
@@ -90,13 +155,36 @@ final class NativeAttachmentPopoverCoordinator: NSObject {
     }
 
     let sourceView = presenter.view
-    let convertedRect: CGRect
+    var convertedRect: CGRect
     if let window = sourceView?.window {
       convertedRect = sourceView?.convert(sourceRect, from: window) ?? sourceRect
     } else {
       convertedRect = sourceRect
     }
 
+    if let sourceView {
+      let keyboardDismissalOffset =
+        NativeAttachmentPopoverPresentationLayout.keyboardDismissalOffset(
+          sourceRect: convertedRect,
+          containerBounds: sourceView.bounds,
+          safeAreaInsets: sourceView.safeAreaInsets,
+          keyboardLayoutFrame: sourceView.keyboardLayoutGuide.layoutFrame,
+          menuHeight: NativeAttachmentMenuLayout.size(
+            compatibleWith: sourceView.traitCollection
+          ).height
+        )
+      if keyboardDismissalOffset > 0 {
+        NativeAttachmentExpandedSurfaceBehavior.dismissKeyboard(
+          in: sourceView.window
+        )
+        convertedRect =
+          NativeAttachmentPopoverPresentationLayout.sourceRect(
+            convertedRect,
+            keyboardDismissalOffset: keyboardDismissalOffset
+          )
+      }
+    }
+
     let anchorView = makeSourceAnchor(frame: convertedRect)
     sourceView?.addSubview(anchorView)
     sourceAnchorView = anchorView
@@ -175,6 +263,56 @@ final class NativeAttachmentPopoverCoordinator: NSObject {
   }
 }
 
+enum NativeAttachmentMenuLayout {
+  static let itemCount: CGFloat = 4
+  static let contentPadding: CGFloat = 16
+  static let minimumItemHeight: CGFloat = 52
+  static let itemSpacing: CGFloat = 8
+  static let itemVerticalPadding: CGFloat = 8
+  static let maximumHeight: CGFloat = 372
+  static let width: CGFloat = 216
+  static let labelTextStyle: UIFont.TextStyle = .title3
+
+  static func itemHeight(
+    compatibleWith traitCollection: UITraitCollection
+  ) -> CGFloat {
+    let labelHeight = UIFont.preferredFont(
+      forTextStyle: labelTextStyle,
+      compatibleWith: traitCollection
+    ).lineHeight
+    return max(
+      minimumItemHeight,
+      ceil(labelHeight + (itemVerticalPadding * 2))
+    )
+  }
+
+  static func itemsHeight(
+    compatibleWith traitCollection: UITraitCollection
+  ) -> CGFloat {
+    (itemHeight(compatibleWith: traitCollection) * itemCount)
+      + (itemSpacing * (itemCount - 1))
+  }
+
+  static func contentHeight(
+    compatibleWith traitCollection: UITraitCollection
+  ) -> CGFloat {
+    (contentPadding * 2) + itemsHeight(compatibleWith: traitCollection)
+  }
+
+  static func size(
+    compatibleWith traitCollection: UITraitCollection,
+    maximumHeight: CGFloat = NativeAttachmentMenuLayout.maximumHeight
+  ) -> CGSize {
+    CGSize(
+      width: width,
+      height: min(
+        contentHeight(compatibleWith: traitCollection),
+        maximumHeight
+      )
+    )
+  }
+}
+
 func makeNativeAttachmentMenuButton(
   title: String,
   symbol: String,
@@ -200,7 +338,9 @@ func makeNativeAttachmentMenuButton(
   let titleLabel = UILabel()
   titleLabel.text = title
   titleLabel.textColor = .label
-  titleLabel.font = .preferredFont(forTextStyle: .body)
+  titleLabel.font = .preferredFont(
+    forTextStyle: NativeAttachmentMenuLayout.labelTextStyle
+  )
   titleLabel.adjustsFontForContentSizeCategory = true
   titleLabel.textAlignment = .left
   titleLabel.translatesAutoresizingMaskIntoConstraints = false
@@ -208,7 +348,10 @@ func makeNativeAttachmentMenuButton(
   button.addSubview(iconView)
   button.addSubview(titleLabel)
   NSLayoutConstraint.activate([
-    iconView.leadingAnchor.constraint(equalTo: button.leadingAnchor, constant: 14),
+    iconView.leadingAnchor.constraint(
+      equalTo: button.leadingAnchor,
+      constant: 8
+    ),
     iconView.centerYAnchor.constraint(equalTo: button.centerYAnchor),
     iconView.widthAnchor.constraint(equalToConstant: 26),
     titleLabel.leadingAnchor.constraint(
@@ -217,7 +360,7 @@ func makeNativeAttachmentMenuButton(
     ),
     titleLabel.trailingAnchor.constraint(
       equalTo: button.trailingAnchor,
-      constant: -14
+      constant: -8
     ),
     titleLabel.centerYAnchor.constraint(equalTo: button.centerYAnchor),
   ])
diff --git a/mobile/ios/RunnerTests/RunnerTests.swift b/mobile/ios/RunnerTests/RunnerTests.swift
index a174c78684..c5333cfdf2 100644
--- a/mobile/ios/RunnerTests/RunnerTests.swift
+++ b/mobile/ios/RunnerTests/RunnerTests.swift
@@ -6,6 +6,179 @@ import XCTest
 
 class RunnerTests: XCTestCase {
 
+  @MainActor
+  func testExpandedAttachmentSurfaceDismissesKeyboard() {
+    let window = KeyboardDismissalSpyWindow()
+
+    NativeAttachmentExpandedSurfaceBehavior.dismissKeyboard(in: window)
+
+    XCTAssertTrue(window.didForceEndEditing)
+  }
+
+  func testExpandedAttachmentSurfaceMeasuresKeyboardOverlap() {
+    XCTAssertEqual(
+      NativeAttachmentExpandedSurfaceBehavior.keyboardOverlap(
+        containerBounds: CGRect(x: 0, y: 0, width: 390, height: 844),
+        keyboardLayoutFrame: CGRect(
+          x: 0,
+          y: 544,
+          width: 390,
+          height: 300
+        )
+      ),
+      300
+    )
+    XCTAssertEqual(
+      NativeAttachmentExpandedSurfaceBehavior.keyboardOverlap(
+        containerBounds: CGRect(x: 0, y: 0, width: 390, height: 844),
+        keyboardLayoutFrame: CGRect(x: 0, y: 844, width: 390, height: 0)
+      ),
+      0
+    )
+  }
+
+  func testAttachmentMenuReturnsToKeyboardDismissedAnchor() {
+    let anchorBounds = CGRect(x: 0, y: 0, width: 44, height: 44)
+
+    XCTAssertEqual(
+      NativeAttachmentPopoverAnchorLayout.sourceRect(
+        anchorBounds: anchorBounds,
+        keyboardDismissalOffset: 300,
+        isExpanded: true
+      ),
+      anchorBounds.offsetBy(dx: 0, dy: 340)
+    )
+    XCTAssertEqual(
+      NativeAttachmentPopoverAnchorLayout.sourceRect(
+        anchorBounds: anchorBounds,
+        keyboardDismissalOffset: 300,
+        isExpanded: false
+      ),
+      anchorBounds.offsetBy(dx: 0, dy: 300)
+    )
+  }
+
+  func testAttachmentMenuKeepsKeyboardWhenMenuFitsAboveTrigger() {
+    XCTAssertEqual(
+      NativeAttachmentPopoverPresentationLayout.keyboardDismissalOffset(
+        sourceRect: CGRect(x: 320, y: 480, width: 44, height: 44),
+        containerBounds: CGRect(x: 0, y: 0, width: 390, height: 844),
+        safeAreaInsets: UIEdgeInsets(top: 59, left: 0, bottom: 34, right: 0),
+        keyboardLayoutFrame: CGRect(
+          x: 0,
+          y: 544,
+          width: 390,
+          height: 300
+        ),
+        menuHeight: NativeAttachmentMenuLayout.size(
+          compatibleWith: UITraitCollection(
+            preferredContentSizeCategory: .large
+          )
+        ).height
+      ),
+      0
+    )
+  }
+
+  func testAttachmentMenuDismissesKeyboardAndRepositionsInCompactHeight() {
+    let sourceRect = CGRect(x: 760, y: 168, width: 44, height: 44)
+    let keyboardDismissalOffset =
+      NativeAttachmentPopoverPresentationLayout.keyboardDismissalOffset(
+        sourceRect: sourceRect,
+        containerBounds: CGRect(x: 0, y: 0, width: 844, height: 390),
+        safeAreaInsets: UIEdgeInsets(top: 0, left: 59, bottom: 21, right: 59),
+        keyboardLayoutFrame: CGRect(
+          x: 0,
+          y: 228,
+          width: 844,
+          height: 162
+        ),
+        menuHeight: NativeAttachmentMenuLayout.size(
+          compatibleWith: UITraitCollection(
+            preferredContentSizeCategory: .large
+          )
+        ).height
+      )
+
+    XCTAssertEqual(keyboardDismissalOffset, 162)
+    XCTAssertEqual(
+      NativeAttachmentPopoverPresentationLayout.sourceRect(
+        sourceRect,
+        keyboardDismissalOffset: keyboardDismissalOffset
+      ),
+      sourceRect.offsetBy(dx: 0, dy: 162)
+    )
+  }
+
+  func testAttachmentMenuDoesNotMoveWithoutSoftwareKeyboard() {
+    XCTAssertEqual(
+      NativeAttachmentPopoverPresentationLayout.keyboardDismissalOffset(
+        sourceRect: CGRect(x: 760, y: 168, width: 44, height: 44),
+        containerBounds: CGRect(x: 0, y: 0, width: 844, height: 390),
+        safeAreaInsets: UIEdgeInsets(top: 0, left: 59, bottom: 21, right: 59),
+        keyboardLayoutFrame: CGRect(x: 0, y: 390, width: 844, height: 0),
+        menuHeight: NativeAttachmentMenuLayout.size(
+          compatibleWith: UITraitCollection(
+            preferredContentSizeCategory: .large
+          )
+        ).height
+      ),
+      0
+    )
+  }
+
+  func testEmbeddedPhotoPickerAppliesOneZoomInStepWithoutAnimation() {
+    var zoomInCalls = 0
+    var animationsWereEnabled = true
+
+    EmbeddedPhotoPickerLayout.applyPreferredScale {
+      zoomInCalls += 1
+      animationsWereEnabled = UIView.areAnimationsEnabled
+    }
+
+    XCTAssertEqual(zoomInCalls, 1)
+    XCTAssertFalse(animationsWereEnabled)
+  }
+
+  func testNativeAttachmentMenuUsesRoomyRowsAndInsets() {
+    let traits = UITraitCollection(preferredContentSizeCategory: .large)
+    let size = NativeAttachmentMenuLayout.size(compatibleWith: traits)
+
+    XCTAssertEqual(size.width, 216)
+    XCTAssertEqual(size.height, 264)
+    XCTAssertEqual(NativeAttachmentMenuLayout.contentPadding, 16)
+    XCTAssertEqual(
+      NativeAttachmentMenuLayout.itemHeight(compatibleWith: traits),
+      52
+    )
+    XCTAssertEqual(NativeAttachmentMenuLayout.itemSpacing, 8)
+    XCTAssertEqual(NativeAttachmentMenuLayout.labelTextStyle, .title3)
+  }
+
+  func testNativeAttachmentMenuGrowsAndScrollsForAccessibilityText() {
+    let traits = UITraitCollection(
+      preferredContentSizeCategory: .accessibilityExtraExtraExtraLarge
+    )
+    let itemHeight = NativeAttachmentMenuLayout.itemHeight(
+      compatibleWith: traits
+    )
+    let contentHeight = NativeAttachmentMenuLayout.contentHeight(
+      compatibleWith: traits
+    )
+    let size = NativeAttachmentMenuLayout.size(compatibleWith: traits)
+
+    XCTAssertGreaterThan(itemHeight, 52)
+    XCTAssertGreaterThan(contentHeight, 264)
+    XCTAssertEqual(
+      size.height,
+      min(contentHeight, NativeAttachmentMenuLayout.maximumHeight)
+    )
+    XCTAssertLessThanOrEqual(
+      size.height,
+      NativeAttachmentMenuLayout.maximumHeight
+    )
+  }
+
   func testDynamicIslandQrScannerRecognizesTallSafeAreas() {
     for safeAreaTopInset in [51, 59, 62] {
       XCTAssertTrue(
@@ -228,6 +401,15 @@ class RunnerTests: XCTestCase {
   }
 }
 
+private final class KeyboardDismissalSpyWindow: UIWindow {
+  private(set) var didForceEndEditing = false
+
+  override func endEditing(_ force: Bool) -> Bool {
+    didForceEndEditing = force
+    return true
+  }
+}
+
 private enum RelayImagePolicyError: Error {
   case invalidPng
   case invalidJpeg
diff --git a/mobile/lib/app.dart b/mobile/lib/app.dart
index 5b266c93f9..0538215109 100644
--- a/mobile/lib/app.dart
+++ b/mobile/lib/app.dart
@@ -14,6 +14,7 @@ import 'features/profile/settings_profile_header.dart';
 import 'features/settings/settings_page.dart';
 import 'shared/auth/auth.dart';
 import 'shared/deeplink/pending_deep_link_provider.dart';
+import 'shared/emoji/emoji_burst.dart';
 import 'shared/relay/relay.dart';
 import 'shared/theme/theme.dart';
 import 'shared/widgets/buzz_loading_indicator.dart';
@@ -89,6 +90,11 @@ class App extends HookConsumerWidget {
         topSectionGradient: buzzDarkGradient,
       ),
       themeMode: effectiveMode,
+      // Above the navigator, so a burst keeps playing over a pushed thread page
+      // or a modal sheet — the same reason desktop pins its canvas to the
+      // viewport rather than to the message row.
+      builder: (context, child) =>
+          EmojiBurstOverlay(child: child ?? const SizedBox.shrink()),
       home: authState.when(
         loading: () => const _SplashScreen(),
         error: (_, _) => const PairingPage(),
diff --git a/mobile/lib/features/activity/activity_page.dart b/mobile/lib/features/activity/activity_page.dart
index d5ea8d1c53..aecef6329c 100644
--- a/mobile/lib/features/activity/activity_page.dart
+++ b/mobile/lib/features/activity/activity_page.dart
@@ -1,16 +1,17 @@
 import 'dart:async';
-import 'dart:math' as math;
-import 'dart:ui' show SemanticsRole;
 
 import 'package:flutter/material.dart';
 import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
 
+import '../../shared/mentions/agent_identity_provider.dart';
+import '../../shared/mentions/mention_tags.dart';
 import '../../shared/relay/relay.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/utils/string_utils.dart';
 import '../../shared/widgets/avatar_image.dart';
+import '../../shared/widgets/anchored_popover_menu.dart';
 import '../../shared/widgets/buzz_loading_indicator.dart';
 import '../../shared/widgets/frosted_app_bar.dart';
 import '../../shared/widgets/frosted_scaffold.dart';
@@ -34,7 +35,6 @@ import 'reminders_provider.dart';
 part 'activity_page/header_actions.dart';
 part 'activity_page/inbox_row.dart';
 part 'activity_page/lists.dart';
-part 'activity_page/popover_menu.dart';
 part 'activity_page/status_views.dart';
 
 /// Conversation-oriented Activity inbox.
@@ -89,8 +89,16 @@ class ActivityPage extends HookConsumerWidget {
     ];
 
     // Preload sender profiles for visible rows.
-    final pubkeys = visibleItems.map((i) => i.item.pubkey).toSet().toList();
-    ref.read(userCacheProvider.notifier).preload(pubkeys);
+    final preloadPubkeys = {
+      for (final item in visibleItems) item.item.pubkey.toLowerCase(),
+      for (final item in visibleItems)
+        ...mentionedPubkeysFromTags(item.item.tags),
+    }.toList()..sort();
+    final preloadPubkeysKey = preloadPubkeys.join('\u0000');
+    useEffect(() {
+      ref.read(userCacheProvider.notifier).preload(preloadPubkeys);
+      return null;
+    }, [preloadPubkeysKey]);
 
     final unreadVisibleCount = visibleItems.where((i) => !isDone(i)).length;
 
@@ -284,6 +292,7 @@ class ActivityPage extends HookConsumerWidget {
     }
 
     return FrostedScaffold(
+      backgroundColor: Colors.transparent,
       appBar: FrostedAppBar(
         gradient: context.appColors.topSectionGradient,
         automaticallyImplyLeading: false,
diff --git a/mobile/lib/features/activity/activity_page/header_actions.dart b/mobile/lib/features/activity/activity_page/header_actions.dart
index 1aab78e622..56592e2e69 100644
--- a/mobile/lib/features/activity/activity_page/header_actions.dart
+++ b/mobile/lib/features/activity/activity_page/header_actions.dart
@@ -33,10 +33,10 @@ class _FilterMenuButton extends StatelessWidget {
         key: const ValueKey('activity-filter-menu'),
         borderRadius: BorderRadius.circular(Radii.md),
         onTap: () async {
-          final selected = await _showActivityPopover<InboxFilter>(
+          final selected = await showAnchoredPopover<InboxFilter>(
             context: buttonContext,
             width: 240,
-            alignment: _ActivityPopoverAlignment.start,
+            alignment: AnchoredPopoverAlignment.start,
             offset: const Offset(0, Grid.half),
             menuPadding: const EdgeInsets.symmetric(vertical: Grid.half),
             color: context.colors.surface.withValues(alpha: 0.98),
@@ -179,10 +179,10 @@ class _InboxOptionsButton extends StatelessWidget {
         tooltip: 'Activity options',
         icon: const Icon(LucideIcons.ellipsis, size: 20),
         onPressed: () async {
-          final selected = await _showActivityPopover<String>(
+          final selected = await showAnchoredPopover<String>(
             context: buttonContext,
             width: 216,
-            alignment: _ActivityPopoverAlignment.end,
+            alignment: AnchoredPopoverAlignment.end,
             color: context.colors.surface,
             elevation: 4,
             shadowColor: context.colors.shadow.withValues(alpha: 0.18),
diff --git a/mobile/lib/features/activity/activity_page/inbox_row.dart b/mobile/lib/features/activity/activity_page/inbox_row.dart
index fb267c03be..9dd8b6ddfa 100644
--- a/mobile/lib/features/activity/activity_page/inbox_row.dart
+++ b/mobile/lib/features/activity/activity_page/inbox_row.dart
@@ -61,6 +61,28 @@ class _InboxRow extends ConsumerWidget {
     final userCache = ref.watch(userCacheProvider);
     final profile = userCache[item.item.pubkey.toLowerCase()];
     final senderLabel = profile?.displayName ?? shortPubkey(item.item.pubkey);
+    final profileMentionNames = {
+      for (final pubkey in mentionedPubkeysFromTags(item.item.tags))
+        if (userCache[pubkey]?.displayName?.trim().isNotEmpty == true)
+          pubkey: userCache[pubkey]!.displayName!.trim(),
+    };
+    final mentionPubkeys = mentionedPubkeysFromTags(item.item.tags);
+    final knownAgentPubkeys = channel == null
+        ? ref.watch(knownAgentPubkeysProvider)
+        : ref.watch(agentMentionPubkeysProvider(channel!.id));
+    final agentMentionPubkeys = agentPubkeysWithProfileOwners(
+      knownAgentPubkeys: knownAgentPubkeys,
+      profileOwnedAgentPubkeys: [
+        for (final profile in userCache.values)
+          if (profile.ownerPubkey != null) profile.pubkey,
+      ],
+    );
+    final mentionNames = mentionNamesWithDirectoryLabels(
+      mentionPubkeys: mentionPubkeys,
+      profileMentionNames: profileMentionNames,
+      directoryDisplayNames: ref.watch(agentDirectoryDisplayNamesProvider),
+      agentMentionPubkeys: agentMentionPubkeys,
+    );
 
     final isDm = channel?.isDm ?? false;
     final channelName = channel != null && !isDm
@@ -172,6 +194,8 @@ class _InboxRow extends ConsumerWidget {
                   // Message preview.
                   MessageContent(
                     content: item.item.displayContent,
+                    mentionNames: mentionNames,
+                    agentMentionPubkeys: agentMentionPubkeys,
                     tags: item.item.tags,
                     maxLines: 2,
                     baseStyle: activityPreviewTextStyle.copyWith(
diff --git a/mobile/lib/features/activity/compose_drafts_provider.dart b/mobile/lib/features/activity/compose_drafts_provider.dart
index b9a079e9a8..b5755f19c8 100644
--- a/mobile/lib/features/activity/compose_drafts_provider.dart
+++ b/mobile/lib/features/activity/compose_drafts_provider.dart
@@ -79,7 +79,13 @@ class ComposeDraftsNotifier extends Notifier<List<ComposeDraft>> {
     _prefsKey = '$_draftsPrefsKey:${config.baseUrl}:$pubkey';
 
     final prefs = ref.read(savedPrefsProvider);
-    final raw = prefs.getString(_prefsKey);
+    final raw = readMigratedPref<String>(
+      prefs,
+      canonicalKey: _prefsKey,
+      legacyKey: '$_draftsPrefsKey:${config.storedOrigin}:$pubkey',
+      read: prefs.getString,
+      write: prefs.setString,
+    );
     if (raw == null) return const [];
     try {
       final decoded = jsonDecode(raw);
diff --git a/mobile/lib/features/channels/agent_activity/working_bots_provider.dart b/mobile/lib/features/channels/agent_activity/working_bots_provider.dart
index 179ea0d4f3..8730908ada 100644
--- a/mobile/lib/features/channels/agent_activity/working_bots_provider.dart
+++ b/mobile/lib/features/channels/agent_activity/working_bots_provider.dart
@@ -8,21 +8,20 @@ import '../channel_typing_provider.dart';
 ///
 /// Used by both the members button badge and the members sheet to avoid
 /// duplicating the bot-typing cross-reference logic.
-final workingBotPubkeysProvider = Provider.family<Set<String>, String>((
-  ref,
-  channelId,
-) {
-  final typingEntries = ref.watch(channelTypingProvider(channelId));
-  final membersAsync = ref.watch(channelMembersProvider(channelId));
-  final allMembers = membersAsync.asData?.value ?? const <ChannelMember>[];
+final workingBotPubkeysProvider = Provider.autoDispose
+    .family<Set<String>, String>((ref, channelId) {
+      final typingEntries = ref.watch(channelTypingProvider(channelId));
+      final membersAsync = ref.watch(channelMembersProvider(channelId));
+      final allMembers = membersAsync.asData?.value ?? const <ChannelMember>[];
 
-  final botPubkeys = <String>{
-    for (final m in allMembers)
-      if (m.isBot) m.pubkey.toLowerCase(),
-  };
+      final botPubkeys = <String>{
+        for (final m in allMembers)
+          if (m.isBot) m.pubkey.toLowerCase(),
+      };
 
-  return <String>{
-    for (final e in typingEntries)
-      if (botPubkeys.contains(e.pubkey.toLowerCase())) e.pubkey.toLowerCase(),
-  };
-});
+      return <String>{
+        for (final e in typingEntries)
+          if (botPubkeys.contains(e.pubkey.toLowerCase()))
+            e.pubkey.toLowerCase(),
+      };
+    });
diff --git a/mobile/lib/features/channels/channel_detail_page.dart b/mobile/lib/features/channels/channel_detail_page.dart
index 6bbb60c0d1..a24b6c07ee 100644
--- a/mobile/lib/features/channels/channel_detail_page.dart
+++ b/mobile/lib/features/channels/channel_detail_page.dart
@@ -8,12 +8,14 @@ import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
 import 'package:scrollable_positioned_list/scrollable_positioned_list.dart';
 
+import '../../shared/mentions/agent_identity_provider.dart';
 import '../../shared/relay/relay.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
 import '../../shared/widgets/buzz_loading_indicator.dart';
 import '../../shared/widgets/frosted_app_bar.dart';
 import '../../shared/widgets/frosted_scaffold.dart';
+import '../../shared/widgets/keyboard_dismiss_on_drag.dart';
 import '../../shared/widgets/message_author_meta.dart';
 import '../../shared/widgets/skeleton.dart';
 import '../profile/presence_cache_provider.dart';
@@ -27,6 +29,7 @@ import 'agent_activity/working_bots_provider.dart';
 import 'channel_management_provider.dart';
 import 'channel_messages_provider.dart';
 import 'channel_typing_provider.dart';
+import 'channel_typing_indicator.dart';
 import 'channels_provider.dart';
 import 'compose_bar.dart';
 import 'date_formatters.dart';
@@ -37,7 +40,6 @@ import 'manage_channel_sheet.dart';
 import 'members_sheet.dart';
 import 'message_actions.dart';
 import 'message_content.dart';
-import 'mentions/mention_candidates_provider.dart';
 import 'read_state/deferred_read_state_update.dart';
 import 'read_state/read_state_provider.dart';
 import 'read_state/read_state_time.dart';
@@ -186,6 +188,11 @@ class ChannelDetailPage extends HookConsumerWidget {
       messagesState: messagesState,
     );
 
+    useEffect(() {
+      final session = ref.read(relaySessionProvider.notifier);
+      return session.registerVisibleChannel(channel.id);
+    }, [channel.id]);
+
     // Preload channel member profiles so @mentions resolve correctly.
     useEffect(() {
       _preloadMembers(ref, channel.id);
@@ -368,8 +375,17 @@ class ChannelDetailPage extends HookConsumerWidget {
                     ),
                   ),
           ),
-          if (!resolvedChannel.isForum && typingEntries.isNotEmpty)
-            _TypingIndicator(entries: typingEntries),
+          if (!resolvedChannel.isForum)
+            AnimatedSize(
+              duration: MediaQuery.disableAnimationsOf(context)
+                  ? Duration.zero
+                  : const Duration(milliseconds: 180),
+              curve: Curves.easeOutCubic,
+              alignment: Alignment.bottomCenter,
+              child: typingEntries.isEmpty
+                  ? const SizedBox.shrink()
+                  : ChannelTypingIndicator(entries: typingEntries),
+            ),
           if (!resolvedChannel.isForum &&
               resolvedChannel.isMember &&
               !resolvedChannel.isArchived)
diff --git a/mobile/lib/features/channels/channel_detail_page/app_bar.dart b/mobile/lib/features/channels/channel_detail_page/app_bar.dart
index fbf5abfb3b..406d68b4f5 100644
--- a/mobile/lib/features/channels/channel_detail_page/app_bar.dart
+++ b/mobile/lib/features/channels/channel_detail_page/app_bar.dart
@@ -19,70 +19,6 @@ double _dmAppBarTitleContentHeight(BuildContext context) {
   return textHeight > 30 ? textHeight : 30;
 }
 
-class _TypingIndicator extends ConsumerWidget {
-  final List<TypingEntry> entries;
-
-  const _TypingIndicator({required this.entries});
-
-  @override
-  Widget build(BuildContext context, WidgetRef ref) {
-    final userCache = ref.watch(userCacheProvider);
-    final names = entries.map((e) {
-      final profile =
-          userCache[e.pubkey.toLowerCase()] ??
-          ref.read(userCacheProvider.notifier).get(e.pubkey.toLowerCase());
-      return profile?.label ?? shortPubkey(e.pubkey);
-    }).toList();
-    final text = switch (names.length) {
-      1 => '${names[0]} is typing…',
-      2 => '${names[0]} and ${names[1]} are typing…',
-      _ => '${names[0]} and ${names.length - 1} others are typing…',
-    };
-
-    final visibleEntries = entries.take(3).toList();
-    final avatarCount = visibleEntries.length;
-
-    return Container(
-      width: double.infinity,
-      padding: const EdgeInsets.symmetric(
-        horizontal: Grid.gutter,
-        vertical: Grid.quarter + 2,
-      ),
-      child: Row(
-        children: [
-          SizedBox(
-            width: 20.0 + (avatarCount - 1) * 12.0,
-            height: 20,
-            child: Stack(
-              children: [
-                for (var i = 0; i < avatarCount; i++)
-                  Positioned(
-                    left: i * 12.0,
-                    child: SmallAvatar(
-                      pubkey: visibleEntries[i].pubkey,
-                      userCache: userCache,
-                    ),
-                  ),
-              ],
-            ),
-          ),
-          const SizedBox(width: Grid.xxs),
-          Flexible(
-            child: Text(
-              text,
-              style: context.textTheme.labelSmall?.copyWith(
-                color: context.colors.outline,
-                fontStyle: FontStyle.italic,
-              ),
-              overflow: TextOverflow.ellipsis,
-            ),
-          ),
-        ],
-      ),
-    );
-  }
-}
-
 class _MembersButton extends ConsumerWidget {
   final String channelId;
   final Channel channel;
diff --git a/mobile/lib/features/channels/channel_detail_page/message_bubble.dart b/mobile/lib/features/channels/channel_detail_page/message_bubble.dart
index 8e7ac95644..cb6ab67065 100644
--- a/mobile/lib/features/channels/channel_detail_page/message_bubble.dart
+++ b/mobile/lib/features/channels/channel_detail_page/message_bubble.dart
@@ -36,8 +36,14 @@ class _MessageBubble extends ConsumerWidget {
 
     // Build mention names map from event p-tags.
     final userCache = ref.watch(userCacheProvider);
-    final knownAgentPubkeys = ref.watch(
-      mentionAgentPubkeysProvider(currentChannelId),
+    final knownAgentPubkeys = agentPubkeysWithProfileOwners(
+      knownAgentPubkeys: ref.watch(
+        agentMentionPubkeysProvider(currentChannelId),
+      ),
+      profileOwnedAgentPubkeys: [
+        for (final profile in userCache.values)
+          if (profile.ownerPubkey != null) profile.pubkey,
+      ],
     );
     final mentionNames = <String, String>{};
     final agentMentionPubkeys = <String>{};
@@ -51,154 +57,197 @@ class _MessageBubble extends ConsumerWidget {
         agentMentionPubkeys.add(normalizedPubkey);
       }
     }
+    final resolvedMentionNames = mentionNamesWithDirectoryLabels(
+      mentionPubkeys: message.mentionPubkeys,
+      profileMentionNames: mentionNames,
+      directoryDisplayNames: ref.watch(agentDirectoryDisplayNamesProvider),
+      agentMentionPubkeys: agentMentionPubkeys,
+    );
 
-    return Material(
-      color: Colors.transparent,
-      borderRadius: BorderRadius.circular(Radii.md),
-      clipBehavior: Clip.antiAlias,
-      child: InkWell(
-        key: ValueKey('message-row-${message.id}'),
+    return Padding(
+      padding: EdgeInsets.only(top: showAuthor ? Grid.xs : 0),
+      child: Material(
+        color: Colors.transparent,
         borderRadius: BorderRadius.circular(Radii.md),
-        highlightColor: context.colors.primary.withValues(alpha: 0.1),
-        onLongPress: () => showMessageActions(
-          context: context,
-          ref: ref,
-          message: message,
-          channelId: currentChannelId,
-          canManageMessage: canManageMessage,
-          allMessages: allMessages,
-          currentPubkey: currentPubkey,
-          isMember: isMember,
-          isArchived: isArchived,
-        ),
-        child: Padding(
-          padding: EdgeInsets.only(
-            top: showAuthor ? Grid.xs : Grid.xxs,
-            bottom: showAuthor ? 0 : Grid.xxs,
+        // The media carousel intentionally continues through the list's trailing
+        // gutter. InkWell still clips its ink to [borderRadius], while leaving
+        // overflowing message content visible.
+        clipBehavior: Clip.none,
+        child: InkWell(
+          key: ValueKey('message-row-${message.id}'),
+          borderRadius: BorderRadius.circular(Radii.md),
+          highlightColor: context.colors.primary.withValues(alpha: 0.1),
+          // Tap opens the thread; long-press still opens the action sheet.
+          // MessageContent handles mention, channel-link, and media taps.
+          onTap: allMessages == null
+              ? null
+              : () => Navigator.of(context).push(
+                  MaterialPageRoute<void>(
+                    builder: (_) => ThreadDetailPage(
+                      threadHead: message,
+                      allMessages: allMessages!,
+                      channelId: currentChannelId,
+                      currentPubkey: currentPubkey,
+                      isMember: isMember,
+                      isArchived: isArchived,
+                    ),
+                  ),
+                ),
+          onLongPress: () => showMessageActions(
+            context: context,
+            ref: ref,
+            message: message,
+            channelId: currentChannelId,
+            canManageMessage: canManageMessage,
+            allMessages: allMessages,
+            currentPubkey: currentPubkey,
+            isMember: isMember,
+            isArchived: isArchived,
           ),
-          child: Row(
-            crossAxisAlignment: CrossAxisAlignment.start,
-            children: [
-              if (showAuthor)
-                GestureDetector(
-                  onTap: () => showUserProfileSheet(context, message.pubkey),
-                  child: _UserAvatar(profile: profile, pubkey: message.pubkey),
-                )
-              else
-                const SizedBox(width: messageAvatarSize),
-              const SizedBox(width: messageAvatarContentGap),
-              Expanded(
-                child: Transform.translate(
-                  offset: Offset(0, showAuthor ? -Grid.quarter : 0),
-                  child: Column(
-                    crossAxisAlignment: CrossAxisAlignment.start,
-                    children: [
-                      if (showAuthor)
-                        Padding(
-                          padding: const EdgeInsets.only(bottom: Grid.quarter),
-                          child: Row(
-                            children: [
-                              Expanded(
-                                child: MessageAuthorMeta(
-                                  displayName: displayName,
-                                  username: messageUsernameLabel(profile),
-                                  timestamp: formatMessageTime(
-                                    message.createdAt,
-                                  ),
-                                  nameColor: context.colors.onSurface,
-                                  metadataColor:
-                                      context.colors.onSurfaceVariant,
-                                  onAuthorTap: () => showUserProfileSheet(
-                                    context,
-                                    message.pubkey,
-                                  ),
-                                  displayNameKey: ValueKey(
-                                    'message-author-${message.id}',
-                                  ),
-                                  usernameKey: ValueKey(
-                                    'message-username-${message.id}',
-                                  ),
-                                  timestampKey: ValueKey(
-                                    'message-timestamp-${message.id}',
+          child: Padding(
+            padding: EdgeInsets.only(
+              top: showAuthor ? 0 : Grid.xxs,
+              bottom: showAuthor ? 0 : Grid.xxs,
+            ),
+            child: Row(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: [
+                if (showAuthor)
+                  GestureDetector(
+                    onTap: () => showUserProfileSheet(context, message.pubkey),
+                    child: _UserAvatar(
+                      profile: profile,
+                      pubkey: message.pubkey,
+                    ),
+                  )
+                else
+                  const SizedBox(width: messageAvatarSize),
+                const SizedBox(width: messageAvatarContentGap),
+                Expanded(
+                  child: Padding(
+                    padding: EdgeInsets.only(top: showAuthor ? Grid.half : 0),
+                    child: Column(
+                      crossAxisAlignment: CrossAxisAlignment.start,
+                      children: [
+                        if (showAuthor)
+                          Padding(
+                            padding: const EdgeInsets.only(
+                              bottom: Grid.quarter,
+                            ),
+                            child: Row(
+                              children: [
+                                Expanded(
+                                  child: MessageAuthorMeta(
+                                    displayName: displayName,
+                                    username: messageUsernameLabel(profile),
+                                    timestamp: formatMessageTime(
+                                      message.createdAt,
+                                    ),
+                                    nameColor: context.colors.onSurface,
+                                    metadataColor:
+                                        context.colors.onSurfaceVariant,
+                                    onAuthorTap: () => showUserProfileSheet(
+                                      context,
+                                      message.pubkey,
+                                    ),
+                                    displayNameKey: ValueKey(
+                                      'message-author-${message.id}',
+                                    ),
+                                    usernameKey: ValueKey(
+                                      'message-username-${message.id}',
+                                    ),
+                                    timestampKey: ValueKey(
+                                      'message-timestamp-${message.id}',
+                                    ),
                                   ),
                                 ),
-                              ),
-                              if (message.edited) ...[
-                                const SizedBox(width: Grid.half),
-                                Text(
-                                  '(edited)',
-                                  style: context.textTheme.labelSmall?.copyWith(
-                                    color: context.colors.onSurfaceVariant,
-                                    fontStyle: FontStyle.italic,
+                                if (message.edited) ...[
+                                  const SizedBox(width: Grid.half),
+                                  Text(
+                                    '(edited)',
+                                    style: context.textTheme.labelSmall
+                                        ?.copyWith(
+                                          color:
+                                              context.colors.onSurfaceVariant,
+                                          fontStyle: FontStyle.italic,
+                                        ),
                                   ),
-                                ),
+                                ],
                               ],
-                            ],
+                            ),
                           ),
-                        ),
-                      MessageContent(
-                        content: message.content,
-                        mentionNames: mentionNames,
-                        agentMentionPubkeys: agentMentionPubkeys,
-                        channelNames: channelNames,
-                        tags: message.tags,
-                        baseStyle: messageBodyTextStyle.copyWith(
-                          color: context.colors.onSurface,
-                        ),
-                        mediaCarouselTrailingOverflow: Grid.gutter,
-                        onMediaReply: allMessages == null
-                            ? null
-                            : () {
-                                if (!context.mounted) return;
-                                Navigator.of(context).push(
-                                  MaterialPageRoute<void>(
-                                    builder: (_) => ThreadDetailPage(
-                                      threadHead: message,
-                                      allMessages: allMessages!,
-                                      channelId: currentChannelId,
-                                      currentPubkey: currentPubkey,
-                                      isMember: isMember,
-                                      isArchived: isArchived,
+                        MessageContent(
+                          content: message.content,
+                          mentionNames: resolvedMentionNames,
+                          agentMentionPubkeys: agentMentionPubkeys,
+                          channelNames: channelNames,
+                          tags: message.tags,
+                          baseStyle: messageBodyTextStyle.copyWith(
+                            color: context.colors.onSurface,
+                          ),
+                          scaleEmojiOnly: true,
+                          mediaCarouselTrailingOverflow: Grid.gutter,
+                          onMediaReply: allMessages == null
+                              ? null
+                              : () {
+                                  if (!context.mounted) return;
+                                  Navigator.of(context).push(
+                                    MaterialPageRoute<void>(
+                                      builder: (_) => ThreadDetailPage(
+                                        threadHead: message,
+                                        allMessages: allMessages!,
+                                        channelId: currentChannelId,
+                                        currentPubkey: currentPubkey,
+                                        isMember: isMember,
+                                        isArchived: isArchived,
+                                      ),
                                     ),
-                                  ),
-                                );
-                              },
-                        onMediaMore: (viewerContext, imageUrl) =>
-                            showImageActions(
-                              context: viewerContext,
+                                  );
+                                },
+                          onMediaMore: (viewerContext, imageUrl) =>
+                              showImageActions(
+                                context: viewerContext,
+                                ref: ref,
+                                message: message,
+                                channelId: currentChannelId,
+                                imageUrl: imageUrl,
+                                canManageMessage: canManageMessage,
+                                onDeleted: () {
+                                  if (viewerContext.mounted) {
+                                    Navigator.of(viewerContext).maybePop();
+                                  }
+                                },
+                              ),
+                          onChannelTap: (channelId) {
+                            openChannelLink(
+                              context: context,
+                              ref: ref,
+                              channelId: channelId,
+                              currentChannelId: currentChannelId,
+                            );
+                          },
+                          onMentionTap: (pubkey) =>
+                              showUserProfileSheet(context, pubkey),
+                        ),
+                        if (message.reactions.isNotEmpty)
+                          ReactionRow(
+                            messageId: message.id,
+                            reactions: message.reactions,
+                            onToggle: (emoji) =>
+                                toggleReaction(ref, message, emoji),
+                            showAddButton: isMember && !isArchived,
+                            onAddReaction: () => showAddReactionPicker(
+                              context: context,
                               ref: ref,
                               message: message,
-                              channelId: currentChannelId,
-                              imageUrl: imageUrl,
-                              canManageMessage: canManageMessage,
-                              onDeleted: () {
-                                if (viewerContext.mounted) {
-                                  Navigator.of(viewerContext).maybePop();
-                                }
-                              },
                             ),
-                        onChannelTap: (channelId) {
-                          openChannelLink(
-                            context: context,
-                            ref: ref,
-                            channelId: channelId,
-                            currentChannelId: currentChannelId,
-                          );
-                        },
-                        onMentionTap: (pubkey) =>
-                            showUserProfileSheet(context, pubkey),
-                      ),
-                      if (message.reactions.isNotEmpty)
-                        ReactionRow(
-                          reactions: message.reactions,
-                          onToggle: (emoji) =>
-                              toggleReaction(ref, message, emoji),
-                        ),
-                    ],
+                          ),
+                      ],
+                    ),
                   ),
                 ),
-              ),
-            ],
+              ],
+            ),
           ),
         ),
       ),
diff --git a/mobile/lib/features/channels/channel_detail_page/message_list.dart b/mobile/lib/features/channels/channel_detail_page/message_list.dart
index 6a77069bea..eacba5856e 100644
--- a/mobile/lib/features/channels/channel_detail_page/message_list.dart
+++ b/mobile/lib/features/channels/channel_detail_page/message_list.dart
@@ -84,8 +84,11 @@ class _MessageList extends HookConsumerWidget {
 
     bool latestIsAtBoundary() {
       // In this reversed list, item 0's leading edge is the bottom boundary.
+      // Being merely visible is not enough: a user who has pulled a tall
+      // newest row away from the boundary must not snap back on live updates.
       return itemPositionsListener.itemPositions.value.any(
-        (position) => position.index == 0 && position.itemLeadingEdge >= 0,
+        (position) =>
+            position.index == 0 && position.itemLeadingEdge.abs() < 0.01,
       );
     }
 
@@ -243,106 +246,110 @@ class _MessageList extends HookConsumerWidget {
             }
             return false;
           },
-          child: ScrollablePositionedList.builder(
-            key: const ValueKey('channel-message-list'),
-            itemScrollController: itemScrollController,
-            itemPositionsListener: itemPositionsListener,
-            reverse: true,
-            padding: EdgeInsets.only(
-              left: Grid.gutter,
-              right: Grid.gutter,
-              top: frostedAppBarHeight(
-                context,
-                titleContentHeight: appBarTitleContentHeight,
+          child: KeyboardDismissOnDrag(
+            child: ScrollablePositionedList.builder(
+              key: const ValueKey('channel-message-list'),
+              itemScrollController: itemScrollController,
+              itemPositionsListener: itemPositionsListener,
+              reverse: true,
+              padding: EdgeInsets.only(
+                left: Grid.gutter,
+                right: Grid.gutter,
+                top: frostedAppBarHeight(
+                  context,
+                  titleContentHeight: appBarTitleContentHeight,
+                ),
+                bottom: 0,
               ),
-              bottom: 0,
-            ),
-            itemCount: displayEntries.length + (isLoadingOlder.value ? 1 : 0),
-            itemBuilder: (context, index) {
-              // Loading indicator at the top (last index in reversed list).
-              if (index >= displayEntries.length) {
-                return const Padding(
-                  padding: EdgeInsets.symmetric(vertical: Grid.xs),
-                  child: Center(
-                    child: BuzzLoadingIndicator(
-                      size: 24,
-                      semanticLabel: 'Loading older messages',
+              itemCount: displayEntries.length + (isLoadingOlder.value ? 1 : 0),
+              itemBuilder: (context, index) {
+                // Loading indicator at the top (last index in reversed list).
+                if (index >= displayEntries.length) {
+                  return const Padding(
+                    padding: EdgeInsets.symmetric(vertical: Grid.xs),
+                    child: Center(
+                      child: BuzzLoadingIndicator(
+                        size: 24,
+                        semanticLabel: 'Loading older messages',
+                      ),
                     ),
-                  ),
-                );
-              }
+                  );
+                }
 
-              // Reversed list: index 0 = newest (bottom of screen).
-              final chronIdx = displayEntries.length - 1 - index;
-              final entryGroup = displayEntries[chronIdx];
-              final entry = entryGroup.first;
-              final message = entry.message;
+                // Reversed list: index 0 = newest (bottom of screen).
+                final chronIdx = displayEntries.length - 1 - index;
+                final entryGroup = displayEntries[chronIdx];
+                final entry = entryGroup.first;
+                final message = entry.message;
 
-              // Day boundary check — applies to all messages including system.
-              final prevEntry = chronIdx > 0
-                  ? displayEntries[chronIdx - 1].last
-                  : null;
-              final prevMessage = prevEntry?.message;
-              final showDayDivider =
-                  prevMessage == null ||
-                  !isSameDay(prevMessage.createdAt, message.createdAt);
+                // Day boundary check — applies to all messages including system.
+                final prevEntry = chronIdx > 0
+                    ? displayEntries[chronIdx - 1].last
+                    : null;
+                final prevMessage = prevEntry?.message;
+                final showDayDivider =
+                    prevMessage == null ||
+                    !isSameDay(prevMessage.createdAt, message.createdAt);
 
-              final showAuthor =
-                  !message.isSystem &&
-                  (message.hasAttachments ||
-                      prevMessage == null ||
-                      prevMessage.isSystem ||
-                      showDayDivider ||
-                      prevMessage.pubkey.toLowerCase() !=
-                          message.pubkey.toLowerCase() ||
-                      (message.createdAt - prevMessage.createdAt) > 300);
+                final showAuthor =
+                    !message.isSystem &&
+                    (message.hasAttachments ||
+                        prevMessage == null ||
+                        prevMessage.isSystem ||
+                        showDayDivider ||
+                        prevMessage.pubkey.toLowerCase() !=
+                            message.pubkey.toLowerCase() ||
+                        (message.createdAt - prevMessage.createdAt) > 300);
 
-              return Padding(
-                key: ValueKey('channel-message-group-${message.id}'),
-                padding: EdgeInsets.only(bottom: index == 0 ? Grid.xs : 0),
-                child: Column(
-                  crossAxisAlignment: CrossAxisAlignment.start,
-                  children: [
-                    if (showDayDivider)
-                      DayDivider(label: formatDayHeading(message.createdAt)),
-                    if (message.isSystem)
-                      _SystemMessageRow(
-                        message: message,
-                        groupedMessages: entryGroup.length > 1
-                            ? entryGroup.map((entry) => entry.message).toList()
-                            : null,
-                        channelId: channelId,
-                        currentPubkey: currentPubkey,
-                        allMessages: null,
-                        isMember: isMember,
-                        isArchived: isArchived,
-                      )
-                    else ...[
-                      _MessageBubble(
-                        message: message,
-                        showAuthor: showAuthor,
-                        channelNames: channelNamesMap,
-                        currentChannelId: channelId,
-                        currentPubkey: currentPubkey,
-                        allMessages: allMessages,
-                        isMember: isMember,
-                        isArchived: isArchived,
-                      ),
-                      if (entry.summary != null)
-                        _ThreadSummaryRow(
-                          summary: entry.summary!,
+                return Padding(
+                  key: ValueKey('channel-message-group-${message.id}'),
+                  padding: EdgeInsets.only(bottom: index == 0 ? Grid.xs : 0),
+                  child: Column(
+                    crossAxisAlignment: CrossAxisAlignment.start,
+                    children: [
+                      if (showDayDivider)
+                        DayDivider(label: formatDayHeading(message.createdAt)),
+                      if (message.isSystem)
+                        _SystemMessageRow(
                           message: message,
-                          allMessages: allMessages,
+                          groupedMessages: entryGroup.length > 1
+                              ? entryGroup
+                                    .map((entry) => entry.message)
+                                    .toList()
+                              : null,
                           channelId: channelId,
                           currentPubkey: currentPubkey,
+                          allMessages: null,
+                          isMember: isMember,
+                          isArchived: isArchived,
+                        )
+                      else ...[
+                        _MessageBubble(
+                          message: message,
+                          showAuthor: showAuthor,
+                          channelNames: channelNamesMap,
+                          currentChannelId: channelId,
+                          currentPubkey: currentPubkey,
+                          allMessages: allMessages,
                           isMember: isMember,
                           isArchived: isArchived,
                         ),
+                        if (entry.summary != null)
+                          _ThreadSummaryRow(
+                            summary: entry.summary!,
+                            message: message,
+                            allMessages: allMessages,
+                            channelId: channelId,
+                            currentPubkey: currentPubkey,
+                            isMember: isMember,
+                            isArchived: isArchived,
+                          ),
+                      ],
                     ],
-                  ],
-                ),
-              );
-            },
+                  ),
+                );
+              },
+            ),
           ),
         ),
         if (!isAtLatest.value)
diff --git a/mobile/lib/features/channels/channel_detail_page/system_rows.dart b/mobile/lib/features/channels/channel_detail_page/system_rows.dart
index f6019febab..0372690e1e 100644
--- a/mobile/lib/features/channels/channel_detail_page/system_rows.dart
+++ b/mobile/lib/features/channels/channel_detail_page/system_rows.dart
@@ -140,6 +140,7 @@ class _SystemMessageRow extends ConsumerWidget {
                             : Grid.xxs),
                   ),
                   child: ReactionRow(
+                    messageId: message.id,
                     reactions: reactions,
                     onToggle: groupedMessages == null
                         ? (emoji) => toggleReaction(ref, message, emoji)
@@ -278,7 +279,12 @@ class _MembershipSystemMessageContent extends StatelessWidget {
       TextSpan(
         text: event.isSelfJoin
             ? 'joined the channel'
-            : 'was added by ${resolveLabel(event.actorPubkey)}',
+            // No "was": the name renders on the line above via
+            // MessageAuthorMeta, so this reads as a status line rather than a
+            // sentence continuing across the metadata row. Matches desktop's
+            // SystemMessageRow. `SystemEvent.describe` keeps "was added by"
+            // because it builds subject and predicate into one string.
+            : 'added by ${resolveLabel(event.actorPubkey)}',
       ),
       if (additionalTargets.isNotEmpty)
         TextSpan(text: event.isSelfJoin ? ' along with ' : ', along with '),
diff --git a/mobile/lib/features/channels/channel_management_provider.dart b/mobile/lib/features/channels/channel_management_provider.dart
index 9a72054a2b..b990194d15 100644
--- a/mobile/lib/features/channels/channel_management_provider.dart
+++ b/mobile/lib/features/channels/channel_management_provider.dart
@@ -7,6 +7,7 @@ import 'package:hooks_riverpod/hooks_riverpod.dart';
 import '../../shared/auth/auth.dart';
 import '../../shared/custom_emoji/custom_emoji.dart';
 import '../../shared/custom_emoji/custom_emoji_provider.dart';
+import '../../shared/mentions/agent_identity_provider.dart';
 import '../../shared/relay/relay.dart';
 import '../profile/profile_provider.dart';
 import 'channel.dart';
@@ -392,8 +393,9 @@ final channelDetailsProvider = FutureProvider.family<ChannelDetails, String>((
 });
 
 /// Channel members from kind:39002 NIP-29 members event.
-final channelMembersProvider =
-    FutureProvider.family<List<ChannelMember>, String>((ref, channelId) async {
+final channelMembersProvider = FutureProvider.autoDispose
+    .family<List<ChannelMember>, String>((ref, channelId) async {
+      ref.watch(channelMembershipUpdateProvider(channelId));
       final session = ref.watch(relaySessionProvider.notifier);
       final events = await session.fetchHistory(
         NostrFilters.channelMembers(channelId),
@@ -557,6 +559,7 @@ class ChannelActions {
       );
     }
     _ref.invalidate(channelMembersProvider(channelId));
+    _ref.invalidate(channelBotPubkeysProvider(channelId));
   }
 
   Future<void> joinChannel(String channelId) async {
@@ -626,6 +629,7 @@ class ChannelActions {
     await _ref.read(channelsProvider.notifier).refresh();
     _ref.invalidate(channelDetailsProvider(channelId));
     _ref.invalidate(channelMembersProvider(channelId));
+    _ref.invalidate(channelBotPubkeysProvider(channelId));
     _ref.invalidate(channelCanvasProvider(channelId));
   }
 
@@ -659,6 +663,7 @@ class ChannelActions {
       ],
     );
     _ref.invalidate(channelMembersProvider(channelId));
+    _ref.invalidate(channelBotPubkeysProvider(channelId));
   }
 
   Future<void> removeMember({
@@ -674,6 +679,7 @@ class ChannelActions {
       ],
     );
     _ref.invalidate(channelMembersProvider(channelId));
+    _ref.invalidate(channelBotPubkeysProvider(channelId));
   }
 
   Future<void> addReaction(String eventId, String emoji) async {
diff --git a/mobile/lib/features/channels/channel_messages_provider.dart b/mobile/lib/features/channels/channel_messages_provider.dart
index 7f657f4b7c..fbcbca8956 100644
--- a/mobile/lib/features/channels/channel_messages_provider.dart
+++ b/mobile/lib/features/channels/channel_messages_provider.dart
@@ -2,11 +2,15 @@ import 'package:flutter/foundation.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 
 import '../../shared/relay/relay.dart';
-import 'channel_management_provider.dart';
 import 'pending_local_messages_provider.dart';
 import 'channel_window.dart';
 import 'thread_replies_provider.dart';
 
+const _channelLiveEventKinds = [
+  ...EventKind.channelEventKinds,
+  EventKind.channelThreadSummary,
+];
+
 /// Provides the message list for a specific channel. Registers a live
 /// subscription first, then syncs history via the server-assembled channel
 /// window fast path, falling back to the legacy websocket history path when the
@@ -17,8 +21,10 @@ class ChannelMessagesNotifier extends Notifier<AsyncValue<List<NostrEvent>>> {
   bool _reachedOldest = false;
   bool _initInFlight = false;
   bool _usingChannelWindow = false;
+  bool _initialWindowQueryInFlight = false;
   int _initVersion = 0;
   ChannelWindowStore _windowStore = const ChannelWindowStore.empty();
+  final Set<String> _liveSummaryRootsDuringInitialWindowQuery = {};
   final Map<String, NostrEvent> _deepLinkEvents = {};
   final Set<String> _retainedDeepLinkEventIds = {};
 
@@ -48,12 +54,16 @@ class ChannelMessagesNotifier extends Notifier<AsyncValue<List<NostrEvent>>> {
     if (sessionState.status != SessionStatus.connected) {
       _initVersion++;
       _initInFlight = false;
+      _initialWindowQueryInFlight = false;
+      _liveSummaryRootsDuringInitialWindowQuery.clear();
       return AsyncData(_lastKnownMessages ?? const []);
     }
 
     _reachedOldest = false;
     _windowStore = const ChannelWindowStore.empty();
     _usingChannelWindow = false;
+    _initialWindowQueryInFlight = false;
+    _liveSummaryRootsDuringInitialWindowQuery.clear();
     _init();
     if (_lastKnownMessages case final cached? when cached.isNotEmpty) {
       return AsyncData(cached);
@@ -71,7 +81,7 @@ class ChannelMessagesNotifier extends Notifier<AsyncValue<List<NostrEvent>>> {
       try {
         final unsubscribe = await session.subscribe(
           NostrFilter(
-            kinds: EventKind.channelEventKinds,
+            kinds: _channelLiveEventKinds,
             tags: {
               '#h': [channelId],
             },
@@ -126,12 +136,21 @@ class ChannelMessagesNotifier extends Notifier<AsyncValue<List<NostrEvent>>> {
     RelaySessionNotifier session,
   ) async {
     try {
+      _initialWindowQueryInFlight = true;
       final page = await _fetchWindowPage(session, null);
-      _windowStore = replaceNewestChannelWindow(_windowStore, page);
+      _initialWindowQueryInFlight = false;
+      _windowStore = replaceNewestChannelWindow(
+        _windowStore,
+        page,
+        retainLiveSummaryRootIds: _liveSummaryRootsDuringInitialWindowQuery,
+      );
+      _liveSummaryRootsDuringInitialWindowQuery.clear();
       _usingChannelWindow = true;
       _reachedOldest = !channelWindowHasMore(_windowStore);
       return flattenChannelWindowEvents(_windowStore);
     } catch (error) {
+      _initialWindowQueryInFlight = false;
+      _liveSummaryRootsDuringInitialWindowQuery.clear();
       debugPrint(
         '[ChannelMessagesNotifier] channel window unavailable for $channelId, falling back to WS history: $error',
       );
@@ -168,6 +187,26 @@ class ChannelMessagesNotifier extends Notifier<AsyncValue<List<NostrEvent>>> {
   );
 
   void _handleLiveEvent(NostrEvent event, {bool authoritative = true}) {
+    // A live summary can race the initial channel-window query. Buffer it in
+    // the window store even before that query installs its first page, rather
+    // than treating metadata as an ordinary websocket timeline event.
+    if (event.kind == EventKind.channelThreadSummary && !_usingChannelWindow) {
+      final rootId = _initialWindowQueryInFlight
+          ? event.getTagValue('e')
+          : null;
+      if (_mergeWindowEventIntoStore(event)) {
+        if (rootId != null) {
+          _liveSummaryRootsDuringInitialWindowQuery.add(rootId);
+        }
+        if (_initInFlight) return;
+        final current =
+            state.value ?? _lastKnownMessages ?? const <NostrEvent>[];
+        _lastKnownMessages = current;
+        state = AsyncData(current);
+      }
+      return;
+    }
+
     // Reply ownership and its thread-local overlay must transition together.
     // The authoritative thread query performs both confirmations after it
     // contains the reply; a live echo only triggers that query below.
@@ -182,11 +221,6 @@ class ChannelMessagesNotifier extends Notifier<AsyncValue<List<NostrEvent>>> {
       _lastKnownMessages = merged;
       state = AsyncData(merged);
     }
-
-    if (event.kind == EventKind.systemMessage &&
-        _isMembershipEvent(event.content)) {
-      ref.invalidate(channelMembersProvider(channelId));
-    }
   }
 
   void _handleWindowLiveEvent(NostrEvent event) {
@@ -222,7 +256,12 @@ class ChannelMessagesNotifier extends Notifier<AsyncValue<List<NostrEvent>>> {
       }
       if (!_isBroadcastReply(event)) return false;
     }
+    // Thread summaries are neither a timeline row nor an aux event, but they are
+    // how the root's "N replies" row learns a reply landed — a reply itself
+    // never reaches the main timeline. Dropping them here meant the count only
+    // appeared after leaving the channel and coming back, which refetched.
     if (!isTimelineRow &&
+        event.kind != EventKind.channelThreadSummary &&
         !EventKind.channelAuxEventKinds.contains(event.kind)) {
       return false;
     }
@@ -243,12 +282,6 @@ class ChannelMessagesNotifier extends Notifier<AsyncValue<List<NostrEvent>>> {
         .confirm(eventIds);
   }
 
-  static bool _isMembershipEvent(String content) {
-    return content.contains('member_joined') ||
-        content.contains('member_left') ||
-        content.contains('member_removed');
-  }
-
   /// Adds a just-signed outgoing message before the relay acknowledges it.
   /// The live relay echo is deduplicated by event id.
   void addLocalMessage(NostrEvent event) {
@@ -320,6 +353,7 @@ class ChannelMessagesNotifier extends Notifier<AsyncValue<List<NostrEvent>>> {
         pages: _windowStore.pages,
         liveOverlay: nextOverlay,
         liveAux: _windowStore.liveAux,
+        liveThreadSummaries: _windowStore.liveThreadSummaries,
       );
     }
 
diff --git a/mobile/lib/features/channels/channel_typing_indicator.dart b/mobile/lib/features/channels/channel_typing_indicator.dart
new file mode 100644
index 0000000000..d021b9e287
--- /dev/null
+++ b/mobile/lib/features/channels/channel_typing_indicator.dart
@@ -0,0 +1,89 @@
+import 'package:flutter/material.dart';
+import 'package:hooks_riverpod/hooks_riverpod.dart';
+
+import '../../shared/theme/theme.dart';
+import '../../shared/utils/string_utils.dart';
+import '../profile/user_cache_provider.dart';
+import 'channel_typing_provider.dart';
+import 'small_avatar.dart';
+
+/// Composer-adjacent status for people currently typing in a channel or thread.
+class ChannelTypingIndicator extends ConsumerWidget {
+  final List<TypingEntry> entries;
+
+  const ChannelTypingIndicator({super.key, required this.entries});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final userCache = ref.watch(userCacheProvider);
+    final names = entries.map((entry) {
+      final profile =
+          userCache[entry.pubkey.toLowerCase()] ??
+          ref.read(userCacheProvider.notifier).get(entry.pubkey.toLowerCase());
+      return profile?.label ?? shortPubkey(entry.pubkey);
+    }).toList();
+    final text = switch (names.length) {
+      1 => '${names[0]} is typing…',
+      2 => '${names[0]} and ${names[1]} are typing…',
+      _ => '${names[0]} and ${names.length - 1} others are typing…',
+    };
+    final visibleEntries = entries.take(3).toList();
+    final avatarCount = visibleEntries.length;
+
+    return Padding(
+      padding: const EdgeInsets.only(
+        left: Grid.twelve,
+        right: Grid.twelve,
+        bottom: Grid.xxs,
+      ),
+      child: Container(
+        key: const ValueKey('channel-typing-indicator'),
+        width: double.infinity,
+        padding: const EdgeInsets.symmetric(
+          horizontal: Grid.xxs,
+          vertical: Grid.xxs,
+        ),
+        decoration: BoxDecoration(
+          color: context.colors.surfaceContainerHighest,
+          borderRadius: BorderRadius.circular(Radii.dialog),
+          border: Border.all(
+            color: Colors.black.withValues(alpha: 0.04),
+            width: 1,
+          ),
+        ),
+        child: Row(
+          children: [
+            SizedBox(
+              width: 24.0 + (avatarCount - 1) * 14.0,
+              height: 24,
+              child: Stack(
+                children: [
+                  for (var i = 0; i < avatarCount; i++)
+                    Positioned(
+                      left: i * 14.0,
+                      child: SmallAvatar(
+                        pubkey: visibleEntries[i].pubkey,
+                        userCache: userCache,
+                        size: 24,
+                      ),
+                    ),
+                ],
+              ),
+            ),
+            const SizedBox(width: Grid.xxs),
+            Flexible(
+              child: Text(
+                text,
+                style: context.textTheme.labelSmall?.copyWith(
+                  color: context.colors.primary,
+                  fontStyle: FontStyle.italic,
+                ),
+                overflow: TextOverflow.ellipsis,
+              ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/channel_window.dart b/mobile/lib/features/channels/channel_window.dart
index 6559115174..2bf8ab3a11 100644
--- a/mobile/lib/features/channels/channel_window.dart
+++ b/mobile/lib/features/channels/channel_window.dart
@@ -23,14 +23,42 @@ class ChannelWindowThreadSummary {
   });
 }
 
+/// A thread-summary snapshot received from the live channel subscription.
+///
+/// [createdAt] is the relay event timestamp used to reject delayed snapshots
+/// after a fresher recount has already been displayed. Recounts created in the
+/// same second retain their live delivery order, because relay timestamps have
+/// second precision.
+class ChannelWindowLiveThreadSummary {
+  final ChannelWindowThreadSummary summary;
+  final int createdAt;
+
+  const ChannelWindowLiveThreadSummary({
+    required this.summary,
+    required this.createdAt,
+  });
+}
+
 class ChannelWindowRow {
   final NostrEvent event;
   final ChannelWindowThreadSummary? thread;
+  final int? threadSummaryCreatedAt;
 
-  const ChannelWindowRow({required this.event, this.thread});
+  const ChannelWindowRow({
+    required this.event,
+    this.thread,
+    this.threadSummaryCreatedAt,
+  });
 
-  ChannelWindowRow copyWith({ChannelWindowThreadSummary? thread}) =>
-      ChannelWindowRow(event: event, thread: thread ?? this.thread);
+  ChannelWindowRow copyWith({
+    ChannelWindowThreadSummary? thread,
+    int? threadSummaryCreatedAt,
+  }) => ChannelWindowRow(
+    event: event,
+    thread: thread ?? this.thread,
+    threadSummaryCreatedAt:
+        threadSummaryCreatedAt ?? this.threadSummaryCreatedAt,
+  );
 }
 
 class ChannelWindowPage {
@@ -54,8 +82,16 @@ class ChannelWindowStore {
   final List<NostrEvent> liveOverlay;
   final List<NostrEvent> liveAux;
 
+  /// Thread summaries that arrived over the live socket, keyed by root event id.
+  ///
+  /// Kept beside the pages rather than folded into [ChannelWindowRow.thread]
+  /// because a root can be in [liveOverlay] instead — a message you just sent
+  /// has no row yet, and its reply count has to land somewhere.
+  final Map<String, ChannelWindowLiveThreadSummary> liveThreadSummaries;
+
   const ChannelWindowStore({
     required this.pages,
+    required this.liveThreadSummaries,
     required this.liveOverlay,
     required this.liveAux,
   });
@@ -63,7 +99,8 @@ class ChannelWindowStore {
   const ChannelWindowStore.empty()
     : pages = const [],
       liveOverlay = const [],
-      liveAux = const [];
+      liveAux = const [],
+      liveThreadSummaries = const {};
 }
 
 ChannelWindowPage parseChannelWindowResponse(
@@ -85,17 +122,9 @@ ChannelWindowPage parseChannelWindowResponse(
     final rootId = event.getTagValue('e');
     final rowIndex = rootId == null ? null : rowIndexesById[rootId];
     if (rowIndex == null) continue;
-    final payload = _parseJsonMap(event, 'thread summary');
-    final participants = payload['participants'];
     rows[rowIndex] = rows[rowIndex].copyWith(
-      thread: ChannelWindowThreadSummary(
-        replyCount: (payload['reply_count'] as num).toInt(),
-        descendantCount: (payload['descendant_count'] as num).toInt(),
-        lastReplyAt: (payload['last_reply_at'] as num?)?.toInt(),
-        participantPubkeys: participants is List
-            ? participants.whereType<String>().toList()
-            : const [],
-      ),
+      thread: parseChannelWindowThreadSummary(event),
+      threadSummaryCreatedAt: event.createdAt,
     );
   }
 
@@ -134,8 +163,9 @@ ChannelWindowPage parseChannelWindowResponse(
 
 ChannelWindowStore replaceNewestChannelWindow(
   ChannelWindowStore current,
-  ChannelWindowPage page,
-) {
+  ChannelWindowPage page, {
+  Set<String> retainLiveSummaryRootIds = const {},
+}) {
   if (page.startCursor != null) {
     throw Exception('Newest channel page must have a null start cursor.');
   }
@@ -150,9 +180,35 @@ ChannelWindowStore replaceNewestChannelWindow(
     liveAux: current.liveAux
         .where((event) => !auxIds.contains(event.id))
         .toList(),
+    // A summary received while the page query was in flight can describe a
+    // mutation after that query's snapshot. Retain just those summaries even
+    // when the relay timestamp matches the page overlay; subscription replay
+    // received before the query still compares timestamps normally.
+    liveThreadSummaries: _retainLiveSummariesAfterPage(
+      current,
+      page.rows,
+      retainLiveSummaryRootIds: retainLiveSummaryRootIds,
+    ),
   );
 }
 
+Map<String, ChannelWindowLiveThreadSummary> _retainLiveSummariesAfterPage(
+  ChannelWindowStore current,
+  List<ChannelWindowRow> rows, {
+  required Set<String> retainLiveSummaryRootIds,
+}) {
+  final rowsById = {for (final row in rows) row.event.id: row};
+  return {
+    for (final entry in current.liveThreadSummaries.entries)
+      if (retainLiveSummaryRootIds.contains(entry.key) ||
+          rowsById[entry.key] == null ||
+          rowsById[entry.key]!.thread == null ||
+          entry.value.createdAt >
+              (rowsById[entry.key]!.threadSummaryCreatedAt ?? -1))
+        entry.key: entry.value,
+  };
+}
+
 ChannelWindowStore appendOlderChannelWindow(
   ChannelWindowStore current,
   ChannelWindowPage page,
@@ -186,6 +242,29 @@ ChannelWindowStore appendOlderChannelWindow(
         .where((event) => !pageIds.contains(event.id))
         .toList(),
     liveAux: current.liveAux,
+    // A live recount can arrive while this older page is in flight. Keep it
+    // when it is fresher than the page's embedded snapshot, just as a newest
+    // page replacement does.
+    liveThreadSummaries: _retainLiveSummariesAfterPage(
+      current,
+      page.rows,
+      retainLiveSummaryRootIds: const {},
+    ),
+  );
+}
+
+/// Decode a kind-39005 thread summary. Same payload whether it came down as a
+/// channel-window page overlay or over the live socket — one contract, two doors.
+ChannelWindowThreadSummary parseChannelWindowThreadSummary(NostrEvent event) {
+  final payload = _parseJsonMap(event, 'thread summary');
+  final participants = payload['participants'];
+  return ChannelWindowThreadSummary(
+    replyCount: (payload['reply_count'] as num).toInt(),
+    descendantCount: (payload['descendant_count'] as num).toInt(),
+    lastReplyAt: (payload['last_reply_at'] as num?)?.toInt(),
+    participantPubkeys: participants is List
+        ? participants.whereType<String>().toList()
+        : const [],
   );
 }
 
@@ -194,6 +273,40 @@ ChannelWindowStore mergeLiveChannelWindowEvent(
   NostrEvent event, {
   required bool isTimelineRow,
 }) {
+  // A reply doesn't reach the main timeline itself — the root's "N replies" row
+  // comes from this summary event, which the relay re-emits on every reply. It
+  // has to be merged, not stored as an aux event: it is a replaceable snapshot
+  // keyed by root, not another row in the timeline.
+  if (event.kind == EventKind.channelThreadSummary) {
+    final rootId = event.getTagValue('e');
+    if (rootId == null) return current;
+    final ChannelWindowThreadSummary summary;
+    try {
+      summary = parseChannelWindowThreadSummary(event);
+    } catch (_) {
+      return current;
+    }
+    final existing = current.liveThreadSummaries[rootId];
+    // A newer timestamp wins. Equal timestamps are ordered by live delivery:
+    // two mutations can produce relay-signed recounts in the same second, and
+    // the later delivery is the authoritative snapshot for that root.
+    if (existing != null && existing.createdAt > event.createdAt) {
+      return current;
+    }
+    return ChannelWindowStore(
+      pages: current.pages,
+      liveOverlay: current.liveOverlay,
+      liveAux: current.liveAux,
+      liveThreadSummaries: {
+        ...current.liveThreadSummaries,
+        rootId: ChannelWindowLiveThreadSummary(
+          summary: summary,
+          createdAt: event.createdAt,
+        ),
+      },
+    );
+  }
+
   if (!isTimelineRow) {
     final alreadyKnown =
         current.liveAux.any((candidate) => candidate.id == event.id) ||
@@ -205,6 +318,7 @@ ChannelWindowStore mergeLiveChannelWindowEvent(
       pages: current.pages,
       liveOverlay: current.liveOverlay,
       liveAux: [...current.liveAux, event],
+      liveThreadSummaries: current.liveThreadSummaries,
     );
   }
 
@@ -227,6 +341,7 @@ ChannelWindowStore mergeLiveChannelWindowEvent(
     pages: current.pages,
     liveOverlay: overlay,
     liveAux: current.liveAux,
+    liveThreadSummaries: current.liveThreadSummaries,
   );
 }
 
@@ -263,6 +378,9 @@ Map<String, ChannelWindowThreadSummary> channelWindowThreadSummaries(
     for (final page in store.pages)
       for (final row in page.rows)
         if (row.thread != null) row.event.id: row.thread!,
+    // Live entries last: they are the newer snapshot for any root they cover.
+    for (final entry in store.liveThreadSummaries.entries)
+      entry.key: entry.value.summary,
   };
 }
 
diff --git a/mobile/lib/features/channels/channels_page.dart b/mobile/lib/features/channels/channels_page.dart
index 8edd056e76..ba5d4ebf9d 100644
--- a/mobile/lib/features/channels/channels_page.dart
+++ b/mobile/lib/features/channels/channels_page.dart
@@ -14,6 +14,7 @@ import '../../shared/community/community_icon_provider.dart';
 import '../../shared/relay/relay.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
+import '../../shared/widgets/anchored_popover_menu.dart';
 import '../../shared/widgets/buzz_loading_indicator.dart';
 import '../../shared/widgets/frosted_app_bar.dart';
 import '../../shared/widgets/frosted_scaffold.dart';
@@ -226,6 +227,7 @@ class ChannelsPage extends HookConsumerWidget {
     }, [isReconnectingWithContent]);
 
     return FrostedScaffold(
+      backgroundColor: Colors.transparent,
       appBar: FrostedAppBar(
         horizontalInset: _kTopSectionInset,
         // Under a Buzz theme the community + account avatar strip carries the
diff --git a/mobile/lib/features/channels/channels_page/body.dart b/mobile/lib/features/channels/channels_page/body.dart
index 2e0a570f41..9f0b1dd4a7 100644
--- a/mobile/lib/features/channels/channels_page/body.dart
+++ b/mobile/lib/features/channels/channels_page/body.dart
@@ -189,7 +189,10 @@ class _SliverChannelsList extends HookConsumerWidget {
     }
 
     return SliverPadding(
-      padding: const EdgeInsets.only(top: Grid.xxs, bottom: 80),
+      padding: EdgeInsets.only(
+        top: Grid.xxs,
+        bottom: MediaQuery.paddingOf(context).bottom,
+      ),
       sliver: SliverList.list(
         children: [
           if (visibleChannels.isEmpty)
diff --git a/mobile/lib/features/channels/channels_page/sections.dart b/mobile/lib/features/channels/channels_page/sections.dart
index 63bd5db9d9..f9fe5453d7 100644
--- a/mobile/lib/features/channels/channels_page/sections.dart
+++ b/mobile/lib/features/channels/channels_page/sections.dart
@@ -152,56 +152,72 @@ class _CustomSectionHeader extends ConsumerWidget {
               ),
             ),
             const SizedBox(width: _kChannelLabelGap),
-            Text(
-              section.name,
-              style: contentListTitleTextStyle.copyWith(
-                color: sectionColor,
-                fontWeight: FontWeight.w600,
+            Expanded(
+              child: Text(
+                section.name,
+                maxLines: 1,
+                overflow: TextOverflow.ellipsis,
+                style: contentListTitleTextStyle.copyWith(
+                  color: sectionColor,
+                  fontWeight: FontWeight.w600,
+                ),
               ),
             ),
-            const Spacer(),
-            GestureDetector(
-              onTapUp: (details) async {
-                final overlay =
-                    Overlay.of(context).context.findRenderObject()!
-                        as RenderBox;
-                final position = RelativeRect.fromRect(
-                  details.globalPosition & Size.zero,
-                  Offset.zero & overlay.size,
-                );
-                final value = await showMenu<String>(
-                  context: context,
-                  position: position,
-                  items: [
-                    const PopupMenuItem(value: 'rename', child: Text('Rename')),
-                    PopupMenuItem(
-                      value: 'move_up',
-                      enabled: !isFirst,
-                      child: const Text('Move Up'),
-                    ),
-                    PopupMenuItem(
-                      value: 'move_down',
-                      enabled: !isLast,
-                      child: const Text('Move Down'),
+            Builder(
+              builder: (buttonContext) => IconButton(
+                key: ValueKey('section-menu-${section.id}'),
+                tooltip: '${section.name} options',
+                visualDensity: VisualDensity.compact,
+                icon: Icon(
+                  LucideIcons.ellipsisVertical,
+                  size: _kChannelIconSize,
+                  color: sectionColor,
+                ),
+                onPressed: () async {
+                  final value = await showAnchoredPopover<String>(
+                    context: buttonContext,
+                    width: 216,
+                    alignment: AnchoredPopoverAlignment.end,
+                    color: context.colors.surface,
+                    elevation: 4,
+                    shadowColor: context.colors.shadow.withValues(alpha: 0.18),
+                    shape: RoundedRectangleBorder(
+                      borderRadius: BorderRadius.circular(Radii.md),
+                      side: BorderSide(color: context.colors.outline),
                     ),
-                    const PopupMenuItem(value: 'delete', child: Text('Delete')),
-                  ],
-                );
-                switch (value) {
-                  case 'rename':
-                    onRename();
-                  case 'move_up':
-                    onMoveUp();
-                  case 'move_down':
-                    onMoveDown();
-                  case 'delete':
-                    onDelete();
-                }
-              },
-              child: Icon(
-                LucideIcons.ellipsisVertical,
-                size: _kChannelIconSize,
-                color: sectionColor,
+                    surfaceKey: ValueKey('section-popover-${section.id}'),
+                    items: [
+                      const PopupMenuItem(
+                        value: 'rename',
+                        child: Text('Rename'),
+                      ),
+                      PopupMenuItem(
+                        value: 'move_up',
+                        enabled: !isFirst,
+                        child: const Text('Move Up'),
+                      ),
+                      PopupMenuItem(
+                        value: 'move_down',
+                        enabled: !isLast,
+                        child: const Text('Move Down'),
+                      ),
+                      const PopupMenuItem(
+                        value: 'delete',
+                        child: Text('Delete'),
+                      ),
+                    ],
+                  );
+                  switch (value) {
+                    case 'rename':
+                      onRename();
+                    case 'move_up':
+                      onMoveUp();
+                    case 'move_down':
+                      onMoveDown();
+                    case 'delete':
+                      onDelete();
+                  }
+                },
               ),
             ),
             const SizedBox(width: Grid.quarter),
diff --git a/mobile/lib/features/channels/channels_provider.dart b/mobile/lib/features/channels/channels_provider.dart
index 614ab054c3..c0525a0b29 100644
--- a/mobile/lib/features/channels/channels_provider.dart
+++ b/mobile/lib/features/channels/channels_provider.dart
@@ -35,8 +35,12 @@ const _authoredRootIdsPrefix = 'buzz-thread-authored.v1';
 class ChannelsNotifier extends AsyncNotifier<List<Channel>> {
   static const _backstopInterval = Duration(seconds: 60);
 
-  final List<void Function()> _unsubscribers = [];
+  final Map<String, void Function()> _unsubscribersByChannel = {};
+  Future<void> _liveSubscriptionQueue = Future.value();
+  List<Channel> _desiredLiveChannels = const [];
+  Set<String> _desiredLiveChannelIds = const {};
   int _subscriptionVersion = 0;
+  String? _subscriptionRelayBaseUrl;
   Timer? _backstopTimer;
   final Map<String, int> _latestObservedByChannel = {};
   final Map<String, Map<String, ObservedUnreadEvent>>
@@ -147,7 +151,10 @@ class ChannelsNotifier extends AsyncNotifier<List<Channel>> {
         .whereType<String>()
         .toSet()
         .toList();
-    if (channelIds.isEmpty) return const [];
+    if (channelIds.isEmpty) {
+      if (subscribeLive) await _subscribeLive(const []);
+      return const [];
+    }
 
     // Step 2: pull channel metadata in one batched filter.
     final metas = await session.fetchHistory(
@@ -423,50 +430,114 @@ class ChannelsNotifier extends AsyncNotifier<List<Channel>> {
   /// Subscribe per-channel to live events (requires `#h` tag for relay
   /// channel-scoped fan-out). Also starts a 60s WS backstop poll to detect
   /// newly created channels we don't yet have subscriptions for.
-  Future<void> _subscribeLive(List<Channel> channels) async {
-    _clearLiveSubscriptions();
-    final subscriptionVersion = _subscriptionVersion;
-    if (ref.read(relaySessionProvider).status != SessionStatus.connected) {
-      return;
-    }
-
-    final session = ref.read(relaySessionProvider.notifier);
+  Future<void> _subscribeLive(List<Channel> channels) {
     final channelIds = {
       for (final channel in channels)
         if (channel.isMember && !channel.isArchived) channel.id,
     };
-
-    final subscriptions = await Future.wait(
-      channelIds.map((channelId) async {
-        try {
-          return await session.subscribe(
-            NostrFilter(
-              kinds: EventKind.channelEventKinds,
-              tags: {
-                '#h': [channelId],
-              },
-              limit: 0,
-            ),
-            _handleLiveEvent,
-          );
-        } catch (error) {
-          debugPrint(
-            '[ChannelsNotifier] live subscription failed for $channelId: $error',
-          );
-          return null;
-        }
-      }),
+    final relayBaseUrl = ref.read(relayConfigProvider).baseUrl;
+    _desiredLiveChannels = channels;
+    _desiredLiveChannelIds = channelIds;
+    final subscriptionVersion = ++_subscriptionVersion;
+
+    final sync = _liveSubscriptionQueue.then(
+      (_) =>
+          _syncLiveSubscriptions(relayBaseUrl, subscriptionVersion, channels),
     );
+    _liveSubscriptionQueue = sync.catchError((Object error, StackTrace stack) {
+      debugPrint(
+        '[ChannelsNotifier] live subscription sync failed: $error\n$stack',
+      );
+    });
+    return sync;
+  }
+
+  Future<void> _syncLiveSubscriptions(
+    String relayBaseUrl,
+    int subscriptionVersion,
+    List<Channel> channels,
+  ) async {
+    if (ref.read(relaySessionProvider).status != SessionStatus.connected) {
+      return;
+    }
+
+    if (subscriptionVersion != _subscriptionVersion) {
+      await _syncLiveSubscriptions(
+        ref.read(relayConfigProvider).baseUrl,
+        _subscriptionVersion,
+        _desiredLiveChannels,
+      );
+      return;
+    }
 
-    if (subscriptionVersion != _subscriptionVersion ||
-        ref.read(relaySessionProvider).status != SessionStatus.connected) {
-      for (final unsubscribe in subscriptions.whereType<void Function()>()) {
+    if (_subscriptionRelayBaseUrl != relayBaseUrl) {
+      for (final unsubscribe in _unsubscribersByChannel.values) {
         unsubscribe();
       }
+      _unsubscribersByChannel.clear();
+      _subscriptionRelayBaseUrl = relayBaseUrl;
+    }
+    if (ref.read(relayConfigProvider).baseUrl != relayBaseUrl) {
+      return;
+    }
+    final session = ref.read(relaySessionProvider.notifier);
+    final channelIds = _desiredLiveChannelIds;
+
+    for (final entry in _unsubscribersByChannel.entries.toList()) {
+      if (channelIds.contains(entry.key)) continue;
+      _unsubscribersByChannel.remove(entry.key);
+      entry.value();
+    }
+
+    for (final channelId in channelIds) {
+      if (ref.read(relaySessionProvider).status != SessionStatus.connected) {
+        return;
+      }
+      if (_unsubscribersByChannel.containsKey(channelId)) continue;
+      try {
+        final unsubscribe = await session.subscribe(
+          NostrFilter(
+            kinds: EventKind.channelEventKinds,
+            tags: {
+              '#h': [channelId],
+            },
+            limit: 0,
+          ),
+          _handleLiveEvent,
+        );
+        if (ref.read(relaySessionProvider).status != SessionStatus.connected ||
+            !_desiredLiveChannelIds.contains(channelId) ||
+            ref.read(relayConfigProvider).baseUrl != relayBaseUrl ||
+            _subscriptionRelayBaseUrl != relayBaseUrl) {
+          unsubscribe();
+          return;
+        }
+        final replaced = _unsubscribersByChannel[channelId];
+        if (replaced != null) {
+          unsubscribe();
+          continue;
+        }
+        _unsubscribersByChannel[channelId] = unsubscribe;
+      } catch (error) {
+        debugPrint(
+          '[ChannelsNotifier] live subscription failed for $channelId: $error',
+        );
+      }
+    }
+
+    if (ref.read(relaySessionProvider).status != SessionStatus.connected) {
       return;
     }
 
-    _unsubscribers.addAll(subscriptions.whereType<void Function()>());
+    if (subscriptionVersion != _subscriptionVersion) {
+      final desiredChannelIds = _desiredLiveChannelIds;
+      for (final entry in _unsubscribersByChannel.entries.toList()) {
+        if (desiredChannelIds.contains(entry.key)) continue;
+        _unsubscribersByChannel.remove(entry.key);
+        entry.value();
+      }
+      return;
+    }
 
     unawaited(_catchUpUnreadEvents(channels));
 
@@ -734,10 +805,13 @@ class ChannelsNotifier extends AsyncNotifier<List<Channel>> {
 
   void _clearLiveSubscriptions() {
     _subscriptionVersion++;
-    for (final unsubscribe in _unsubscribers) {
+    _desiredLiveChannels = const [];
+    _desiredLiveChannelIds = const {};
+    for (final unsubscribe in _unsubscribersByChannel.values) {
       unsubscribe();
     }
-    _unsubscribers.clear();
+    _unsubscribersByChannel.clear();
+    _subscriptionRelayBaseUrl = null;
     _backstopTimer?.cancel();
     _backstopTimer = null;
   }
diff --git a/mobile/lib/features/channels/compose_bar.dart b/mobile/lib/features/channels/compose_bar.dart
index a2421c9339..7560f998f3 100644
--- a/mobile/lib/features/channels/compose_bar.dart
+++ b/mobile/lib/features/channels/compose_bar.dart
@@ -6,6 +6,7 @@ import 'package:camera/camera.dart' as camera;
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter/physics.dart';
+import 'package:flutter/rendering.dart';
 import 'package:flutter/services.dart';
 import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
@@ -14,10 +15,12 @@ import 'package:lucide_icons_flutter/lucide_icons.dart';
 
 import 'package:nostr/nostr.dart' as nostr;
 
+import '../../shared/mentions/agent_identity_provider.dart';
 import '../../shared/relay/relay.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
 import '../../shared/widgets/buzz_loading_indicator.dart';
+import '../../shared/widgets/keyboard_dismiss_on_drag.dart';
 import '../profile/user_cache_provider.dart';
 import '../profile/user_profile.dart';
 import '../../shared/custom_emoji/custom_emoji.dart';
@@ -34,6 +37,7 @@ import 'mentions/mention_ranking.dart';
 import 'photo_library.dart';
 
 part 'compose_bar/helpers.dart';
+part 'compose_bar/agent_mention_labels.dart';
 part 'compose_bar/markdown_editing_controller.dart';
 part 'compose_bar/suggestions.dart';
 part 'compose_bar/formatting_toolbar.dart';
@@ -229,6 +233,16 @@ class ComposeBar extends HookConsumerWidget {
     // owners so @mention suggestions show names ("managed by …" included).
     final relayAgents = ref.watch(agentDirectoryProvider).asData?.value;
     final agentOwners = ref.watch(agentOwnersProvider).asData?.value;
+    final agentMentionLabels = _agentMentionLabels(
+      candidates: mentionMap.value.values,
+    );
+    final agentMentionLabelsKey = (agentMentionLabels.toList()..sort()).join(
+      '\u0000',
+    );
+    useEffect(() {
+      controller.setAgentMentionNames(agentMentionLabels);
+      return null;
+    }, [controller, agentMentionLabelsKey]);
     useEffect(
       () {
         final memberList = membersAsync.asData?.value ?? <ChannelMember>[];
@@ -736,7 +750,6 @@ class ComposeBar extends HookConsumerWidget {
         return;
       }
 
-      focusNode.unfocus();
       unawaited(
         iosAttachmentPopover
             .present(
@@ -767,7 +780,10 @@ class ComposeBar extends HookConsumerWidget {
               }),
             )
             .then((didPresent) {
-              if (!didPresent && context.mounted) toggleAttachments();
+              if (!didPresent && context.mounted) {
+                focusNode.unfocus();
+                toggleAttachments();
+              }
             }),
       );
     }
diff --git a/mobile/lib/features/channels/compose_bar/agent_mention_labels.dart b/mobile/lib/features/channels/compose_bar/agent_mention_labels.dart
new file mode 100644
index 0000000000..bc29d5bb46
--- /dev/null
+++ b/mobile/lib/features/channels/compose_bar/agent_mention_labels.dart
@@ -0,0 +1,10 @@
+part of '../compose_bar.dart';
+
+Set<String> _agentMentionLabels({
+  required Iterable<MentionCandidate> candidates,
+}) {
+  return <String>{
+    for (final candidate in candidates)
+      if (candidate.isAgent) candidate.label,
+  };
+}
diff --git a/mobile/lib/features/channels/compose_bar/attachments.dart b/mobile/lib/features/channels/compose_bar/attachments.dart
index 9d9f278edc..7c53ae1098 100644
--- a/mobile/lib/features/channels/compose_bar/attachments.dart
+++ b/mobile/lib/features/channels/compose_bar/attachments.dart
@@ -2,10 +2,53 @@ part of '../compose_bar.dart';
 
 enum _AttachmentSurface { closed, menu, camera, photos }
 
-const _attachmentMenuWidth = 176.0;
-const _attachmentMenuHeight = 208.0;
+const _attachmentMenuWidth = 216.0;
+const _attachmentMenuPadding = Grid.xs;
+const _attachmentMenuItemHeight = 52.0;
+const _attachmentMenuItemSpacing = Grid.xxs;
+const _attachmentMenuIconSize = 24.0;
+const _attachmentMenuIconSlotWidth = 28.0;
 const _attachmentExpandedHeight = 372.0;
 
+@immutable
+class _AttachmentMenuLayout {
+  final double itemHeight;
+  final double contentHeight;
+  final double height;
+
+  const _AttachmentMenuLayout({
+    required this.itemHeight,
+    required this.contentHeight,
+    required this.height,
+  });
+
+  factory _AttachmentMenuLayout.from(BuildContext context) {
+    final textPainter = TextPainter(
+      text: TextSpan(text: 'Camera', style: context.textTheme.titleMedium),
+      textDirection: Directionality.of(context),
+      textScaler: MediaQuery.textScalerOf(context),
+      maxLines: 1,
+    )..layout();
+    final itemHeight = math.max(
+      _attachmentMenuItemHeight,
+      textPainter.height + (Grid.xxs * 2),
+    );
+    textPainter.dispose();
+    final contentHeight =
+        (_attachmentMenuPadding * 2) +
+        (itemHeight * 4) +
+        (_attachmentMenuItemSpacing * 3);
+
+    return _AttachmentMenuLayout(
+      itemHeight: itemHeight,
+      contentHeight: contentHeight,
+      height: math.min(contentHeight, _attachmentExpandedHeight),
+    );
+  }
+
+  bool get isScrollable => contentHeight > height;
+}
+
 class _AttachmentSurfacePanel extends HookWidget {
   final _AttachmentSurface surface;
   final Widget suggestionPanel;
@@ -36,6 +79,7 @@ class _AttachmentSurfacePanel extends HookWidget {
   Widget build(BuildContext context) {
     if (surface == _AttachmentSurface.closed) return suggestionPanel;
 
+    final menuLayout = _AttachmentMenuLayout.from(context);
     final reducedMotion = MediaQuery.disableAnimationsOf(context);
     final isExpanded =
         surface == _AttachmentSurface.camera ||
@@ -81,10 +125,24 @@ class _AttachmentSurfacePanel extends HookWidget {
 
     final visibleExpandedSurface =
         renderedExpandedSurface.value ?? (isExpanded ? surface : null);
+    final cameraInitializationReady =
+        reducedMotion ||
+        (surface == _AttachmentSurface.camera && rawProgress >= 1);
     final expandedContent = switch (visibleExpandedSurface) {
       _AttachmentSurface.camera => KeyedSubtree(
         key: const ValueKey('camera-preview'),
-        child: _InlineCameraPreview(onClose: onBack, onCapture: onCapture),
+        child: KeyedSubtree(
+          key: ValueKey(
+            cameraInitializationReady
+                ? 'camera-initialization-ready'
+                : 'camera-initialization-deferred',
+          ),
+          child: _InlineCameraPreview(
+            initializeCamera: cameraInitializationReady,
+            onClose: onBack,
+            onCapture: onCapture,
+          ),
+        ),
       ),
       _AttachmentSurface.photos => KeyedSubtree(
         key: const ValueKey('photo-gallery'),
@@ -117,8 +175,8 @@ class _AttachmentSurfacePanel extends HookWidget {
             _attachmentMenuWidth +
             ((expandedWidth - _attachmentMenuWidth) * sizeProgress);
         final height =
-            _attachmentMenuHeight +
-            ((expandedHeight - _attachmentMenuHeight) * sizeProgress);
+            menuLayout.height +
+            ((expandedHeight - menuLayout.height) * sizeProgress);
         final baseColor = context.colors.surfaceContainerHighest;
         final expandedColor =
             visibleExpandedSurface == _AttachmentSurface.camera
@@ -151,12 +209,13 @@ class _AttachmentSurfacePanel extends HookWidget {
                         left: 0,
                         top: 0,
                         width: _attachmentMenuWidth,
-                        height: _attachmentMenuHeight,
+                        height: menuLayout.height,
                         child: IgnorePointer(
                           ignoring: surface != _AttachmentSurface.menu,
                           child: Opacity(
                             opacity: menuOpacity,
                             child: _AttachmentMenu(
+                              layout: menuLayout,
                               onCamera: onCamera,
                               onPhotos: onPhotos,
                               onVideo: onVideo,
@@ -289,12 +348,14 @@ class _AttachmentTrigger extends StatelessWidget {
 }
 
 class _AttachmentMenu extends StatelessWidget {
+  final _AttachmentMenuLayout layout;
   final VoidCallback onCamera;
   final VoidCallback onPhotos;
   final VoidCallback onVideo;
   final VoidCallback onFiles;
 
   const _AttachmentMenu({
+    required this.layout,
     required this.onCamera,
     required this.onPhotos,
     required this.onVideo,
@@ -304,46 +365,45 @@ class _AttachmentMenu extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     return SizedBox(
+      key: const ValueKey('attachment-menu'),
       width: _attachmentMenuWidth,
-      height: _attachmentMenuHeight,
-      child: Padding(
-        padding: const EdgeInsets.symmetric(vertical: Grid.xxs),
-        child: Column(
-          mainAxisSize: MainAxisSize.min,
-          children: [
-            _AttachmentMenuItem(
-              icon: LucideIcons.camera,
-              label: 'Camera',
-              onTap: onCamera,
-            ),
-            _AttachmentMenuItem(
-              icon: LucideIcons.images,
-              label: 'Photos',
-              onTap: onPhotos,
-            ),
-            _AttachmentMenuItem(
-              icon: LucideIcons.video,
-              label: 'Video',
-              onTap: onVideo,
-            ),
-            _AttachmentMenuItem(
-              icon: LucideIcons.file,
-              label: 'Files',
-              onTap: onFiles,
-            ),
-          ],
-        ),
+      height: layout.height,
+      child: ListView.separated(
+        key: const ValueKey('attachment-menu-scroll'),
+        padding: const EdgeInsets.all(_attachmentMenuPadding),
+        physics: layout.isScrollable
+            ? null
+            : const NeverScrollableScrollPhysics(),
+        itemCount: 4,
+        separatorBuilder: (_, _) =>
+            const SizedBox(height: _attachmentMenuItemSpacing),
+        itemBuilder: (context, index) {
+          final (icon, label, onTap) = switch (index) {
+            0 => (LucideIcons.camera, 'Camera', onCamera),
+            1 => (LucideIcons.images, 'Photos', onPhotos),
+            2 => (LucideIcons.video, 'Video', onVideo),
+            _ => (LucideIcons.file, 'Files', onFiles),
+          };
+          return _AttachmentMenuItem(
+            height: layout.itemHeight,
+            icon: icon,
+            label: label,
+            onTap: onTap,
+          );
+        },
       ),
     );
   }
 }
 
 class _AttachmentMenuItem extends StatelessWidget {
+  final double height;
   final IconData icon;
   final String label;
   final VoidCallback onTap;
 
   const _AttachmentMenuItem({
+    required this.height,
     required this.icon,
     required this.label,
     required this.onTap,
@@ -352,21 +412,40 @@ class _AttachmentMenuItem extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     return SizedBox(
-      height: 48,
+      key: ValueKey('attachment-menu-item-${label.toLowerCase()}'),
+      height: height,
       child: Tooltip(
         message: label,
         child: InkWell(
           onTap: onTap,
           child: Padding(
-            padding: const EdgeInsets.symmetric(horizontal: Grid.twelve),
+            padding: const EdgeInsets.symmetric(horizontal: Grid.xxs),
             child: Row(
               children: [
-                Icon(icon, size: 20, color: context.colors.onSurfaceVariant),
+                SizedBox(
+                  key: ValueKey('attachment-menu-icon-${label.toLowerCase()}'),
+                  width: _attachmentMenuIconSlotWidth,
+                  child: Center(
+                    child: Icon(
+                      icon,
+                      size: _attachmentMenuIconSize,
+                      color: context.colors.onSurfaceVariant,
+                    ),
+                  ),
+                ),
                 const SizedBox(width: Grid.xxs),
-                Text(
-                  label,
-                  style: context.textTheme.bodyLarge?.copyWith(
-                    color: context.colors.onSurface,
+                Expanded(
+                  child: Text(
+                    label,
+                    key: ValueKey(
+                      'attachment-menu-label-${label.toLowerCase()}',
+                    ),
+                    maxLines: 1,
+                    overflow: TextOverflow.ellipsis,
+                    style: context.textTheme.titleMedium?.copyWith(
+                      color: context.colors.onSurface,
+                      fontWeight: FontWeight.w400,
+                    ),
                   ),
                 ),
               ],
diff --git a/mobile/lib/features/channels/compose_bar/camera_preview.dart b/mobile/lib/features/channels/compose_bar/camera_preview.dart
index 6179bcfb2f..e51c2d16aa 100644
--- a/mobile/lib/features/channels/compose_bar/camera_preview.dart
+++ b/mobile/lib/features/channels/compose_bar/camera_preview.dart
@@ -1,10 +1,15 @@
 part of '../compose_bar.dart';
 
 class _InlineCameraPreview extends HookConsumerWidget {
+  final bool initializeCamera;
   final Future<void> Function(XFile image) onCapture;
   final VoidCallback onClose;
 
-  const _InlineCameraPreview({required this.onCapture, required this.onClose});
+  const _InlineCameraPreview({
+    required this.initializeCamera,
+    required this.onCapture,
+    required this.onClose,
+  });
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
@@ -15,6 +20,8 @@ class _InlineCameraPreview extends HookConsumerWidget {
     final error = useState<String?>(null);
 
     useEffect(() {
+      if (!initializeCamera) return null;
+
       var disposed = false;
       var generation = 0;
 
@@ -76,7 +83,9 @@ class _InlineCameraPreview extends HookConsumerWidget {
         onInactive: () => unawaited(disposeCurrent()),
         onResume: () => unawaited(initialize()),
       );
-      unawaited(initialize());
+      WidgetsBinding.instance.addPostFrameCallback((_) {
+        if (!disposed) unawaited(initialize());
+      });
 
       return () {
         disposed = true;
@@ -86,7 +95,7 @@ class _InlineCameraPreview extends HookConsumerWidget {
         controllerRef.value = null;
         unawaited(current?.dispose() ?? Future<void>.value());
       };
-    }, const []);
+    }, [initializeCamera]);
 
     Future<void> capture() async {
       final activeController = controller.value;
diff --git a/mobile/lib/features/channels/compose_bar/layout.dart b/mobile/lib/features/channels/compose_bar/layout.dart
index 2d62db836d..31b930e36d 100644
--- a/mobile/lib/features/channels/compose_bar/layout.dart
+++ b/mobile/lib/features/channels/compose_bar/layout.dart
@@ -59,6 +59,10 @@ class _ComposeBarLayout extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
+    return _DragDownToDismissKeyboard(child: _buildBar(context));
+  }
+
+  Widget _buildBar(BuildContext context) {
     return Container(
       decoration: BoxDecoration(
         color: context.colors.surfaceContainerHighest,
@@ -243,3 +247,60 @@ class _ComposeBarLayout extends StatelessWidget {
     );
   }
 }
+
+/// Drag the compose bar downward to put the keyboard away.
+///
+/// Continues the gesture the message list starts: once your finger reaches the
+/// composer, keep pulling down and the keyboard goes with it. Uses a raw
+/// [Listener] rather than a `GestureDetector` on purpose — a gesture recognizer
+/// here would enter the arena against the `TextField` and could steal taps,
+/// caret placement, and selection drags. A [Listener] only observes.
+class _DragDownToDismissKeyboard extends HookWidget {
+  final Widget child;
+
+  const _DragDownToDismissKeyboard({required this.child});
+
+  @override
+  Widget build(BuildContext context) {
+    // A ref, not state: pointer travel must not rebuild the composer, which
+    // would churn the TextField mid-gesture.
+    final downwardTravel = useRef(0.0);
+    final startedInEditable = useRef(false);
+
+    return Listener(
+      onPointerDown: (event) {
+        downwardTravel.value = 0;
+        final hitTest = HitTestResult();
+        RendererBinding.instance.hitTestInView(
+          hitTest,
+          event.position,
+          event.viewId,
+        );
+        startedInEditable.value = hitTest.path.any(
+          (entry) => entry.target is RenderEditable,
+        );
+      },
+      onPointerCancel: (_) {
+        downwardTravel.value = 0;
+        startedInEditable.value = false;
+      },
+      onPointerUp: (_) {
+        downwardTravel.value = 0;
+        startedInEditable.value = false;
+      },
+      onPointerMove: (event) {
+        if (startedInEditable.value) return;
+        final dy = event.delta.dy;
+        if (dy <= 0) {
+          downwardTravel.value = 0;
+          return;
+        }
+        downwardTravel.value += dy;
+        if (downwardTravel.value < keyboardDismissDragThreshold) return;
+        downwardTravel.value = 0;
+        dismissKeyboard(context);
+      },
+      child: child,
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/compose_bar/markdown_editing_controller.dart b/mobile/lib/features/channels/compose_bar/markdown_editing_controller.dart
index 29e22a8ca9..bbca57037a 100644
--- a/mobile/lib/features/channels/compose_bar/markdown_editing_controller.dart
+++ b/mobile/lib/features/channels/compose_bar/markdown_editing_controller.dart
@@ -15,6 +15,8 @@ class _MarkdownRule {
 }
 
 class _MarkdownEditingController extends TextEditingController {
+  final Set<String> _agentMentionNames = <String>{};
+
   static final _rules = [
     _MarkdownRule(
       r'```(?:\r?\n)?([\s\S]*?)(?:\r?\n)?```',
@@ -31,6 +33,21 @@ class _MarkdownEditingController extends TextEditingController {
     _MarkdownRule(r'_([^_\n]*?)_', _MarkdownStyle.italic),
   ];
 
+  /// Updates the known agent labels which should render as agent mention
+  /// chips. The editor still stores the literal `@Name` text, matching the
+  /// markdown sent to the relay.
+  void setAgentMentionNames(Iterable<String> names) {
+    final next = {
+      for (final name in names)
+        if (name.trim().isNotEmpty) name.trim().toLowerCase(),
+    };
+    if (setEquals(_agentMentionNames, next)) return;
+    _agentMentionNames
+      ..clear()
+      ..addAll(next);
+    notifyListeners();
+  }
+
   @override
   TextSpan buildTextSpan({
     required BuildContext context,
@@ -81,6 +98,7 @@ class _MarkdownEditingController extends TextEditingController {
       if (nextRule == null || nextMatch == null) {
         spans.addAll(
           _buildTextSpans(
+            context,
             source.substring(offset),
             inheritedStyle,
             sourceOffset + offset,
@@ -93,6 +111,7 @@ class _MarkdownEditingController extends TextEditingController {
       if (nextMatch.start > 0) {
         spans.addAll(
           _buildTextSpans(
+            context,
             tail.substring(0, nextMatch.start),
             inheritedStyle,
             sourceOffset + offset,
@@ -129,10 +148,12 @@ class _MarkdownEditingController extends TextEditingController {
       } else {
         spans.addAll(
           _buildTextSpans(
+            context,
             content,
             contentStyle,
             matchOffset + contentStart,
             composingRange,
+            renderAgentMentions: false,
           ),
         );
       }
@@ -150,11 +171,18 @@ class _MarkdownEditingController extends TextEditingController {
   }
 
   List<InlineSpan> _buildTextSpans(
+    BuildContext context,
     String source,
     TextStyle style,
     int sourceOffset,
-    TextRange composingRange,
-  ) {
+    TextRange composingRange, {
+    bool renderAgentMentions = true,
+  }) {
+    List<InlineSpan> buildTextSegment(String text, TextStyle segmentStyle) =>
+        renderAgentMentions
+        ? _buildAgentMentionSpans(context, text, segmentStyle)
+        : [TextSpan(text: text, style: segmentStyle)];
+
     if (source.isEmpty) return const [];
     final localStart = (composingRange.start - sourceOffset)
         .clamp(0, source.length)
@@ -165,7 +193,7 @@ class _MarkdownEditingController extends TextEditingController {
     if (!composingRange.isValid ||
         composingRange.isCollapsed ||
         localStart >= localEnd) {
-      return [TextSpan(text: source, style: style)];
+      return buildTextSegment(source, style);
     }
 
     final composingDecorations = [
@@ -178,16 +206,80 @@ class _MarkdownEditingController extends TextEditingController {
     );
     return [
       if (localStart > 0)
-        TextSpan(text: source.substring(0, localStart), style: style),
+        ...buildTextSegment(source.substring(0, localStart), style),
       TextSpan(
         text: source.substring(localStart, localEnd),
         style: composingStyle,
       ),
       if (localEnd < source.length)
-        TextSpan(text: source.substring(localEnd), style: style),
+        ...buildTextSegment(source.substring(localEnd), style),
     ];
   }
 
+  List<InlineSpan> _buildAgentMentionSpans(
+    BuildContext context,
+    String source,
+    TextStyle style,
+  ) {
+    if (_agentMentionNames.isEmpty) {
+      return [TextSpan(text: source, style: style)];
+    }
+
+    final escapedNames = _agentMentionNames.toList()
+      ..sort((a, b) => b.length.compareTo(a.length));
+    final expression = RegExp(
+      r'(^|\s)@(' +
+          escapedNames.map(RegExp.escape).join('|') +
+          r')(?=\s|[,.!?:;)\]}*_]|$)',
+      caseSensitive: false,
+      multiLine: true,
+    );
+    final spans = <InlineSpan>[];
+    var offset = 0;
+    for (final match in expression.allMatches(source)) {
+      final prefix = match.group(1)!;
+      if (match.start > offset) {
+        spans.add(
+          TextSpan(text: source.substring(offset, match.start), style: style),
+        );
+      }
+      if (prefix.isNotEmpty) spans.add(TextSpan(text: prefix, style: style));
+
+      final label = match.group(2)!;
+      spans.add(
+        WidgetSpan(
+          alignment: PlaceholderAlignment.baseline,
+          baseline: TextBaseline.alphabetic,
+          child: _ComposerAgentMentionChip(label: label, textStyle: style),
+        ),
+      );
+      // The visual chip replaces the `@` placeholder. Keep the label as
+      // invisible source text so the text span still has one character per
+      // source character, preserving native cursor and deletion behavior.
+      spans.add(
+        TextSpan(
+          text: label,
+          semanticsLabel: '',
+          style: _hiddenMentionTextStyle(style),
+        ),
+      );
+      offset = match.end;
+    }
+    if (offset < source.length) {
+      spans.add(TextSpan(text: source.substring(offset), style: style));
+    }
+    return spans.isEmpty ? [TextSpan(text: source, style: style)] : spans;
+  }
+
+  TextStyle _hiddenMentionTextStyle(TextStyle inheritedStyle) =>
+      inheritedStyle.copyWith(
+        color: Colors.transparent,
+        fontSize: 0.01,
+        height: 0.01,
+        letterSpacing: 0,
+        decoration: TextDecoration.none,
+      );
+
   (int, int) _contentBounds(String fullMatch, _MarkdownStyle markdownStyle) {
     final delimiterLength = switch (markdownStyle) {
       _MarkdownStyle.bold || _MarkdownStyle.strikethrough => 2,
@@ -247,3 +339,60 @@ class _MarkdownEditingController extends TextEditingController {
     );
   }
 }
+
+class _ComposerAgentMentionChip extends StatelessWidget {
+  final String label;
+  final TextStyle textStyle;
+
+  const _ComposerAgentMentionChip({
+    required this.label,
+    required this.textStyle,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final style = textStyle.copyWith(
+      color: context.colors.primary,
+      fontWeight: FontWeight.w500,
+      height: 1,
+    );
+    final fontSize = style.fontSize ?? 16;
+
+    return Semantics(
+      label: 'Agent mention: $label',
+      excludeSemantics: true,
+      child: Container(
+        key: const ValueKey('composer-agent-mention-chip'),
+        padding: const EdgeInsets.fromLTRB(
+          Grid.half,
+          Grid.quarter + 1,
+          Grid.half,
+          Grid.quarter,
+        ),
+        decoration: BoxDecoration(
+          // The composer surface is already tinted, so the body chip's
+          // low-opacity fill disappears here. Keep the same chip geometry
+          // while giving this editable token enough contrast to read as one.
+          color: context.colors.primary.withValues(alpha: 0.16),
+          borderRadius: BorderRadius.circular(Radii.sm),
+          border: Border.all(
+            color: context.colors.primary.withValues(alpha: 0.12),
+          ),
+        ),
+        child: Row(
+          mainAxisSize: MainAxisSize.min,
+          crossAxisAlignment: CrossAxisAlignment.center,
+          children: [
+            Icon(
+              LucideIcons.bot,
+              size: fontSize * 0.95,
+              color: context.colors.primary,
+            ),
+            const SizedBox(width: Grid.quarter),
+            Text(label, style: style),
+          ],
+        ),
+      ),
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/emoji_picker.dart b/mobile/lib/features/channels/emoji_picker.dart
index c961966531..10292cfa28 100644
--- a/mobile/lib/features/channels/emoji_picker.dart
+++ b/mobile/lib/features/channels/emoji_picker.dart
@@ -1,13 +1,32 @@
 import 'package:flutter/material.dart';
+import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
 
-import '../../shared/theme/theme.dart';
 import '../../shared/custom_emoji/custom_emoji.dart';
 import '../../shared/custom_emoji/custom_emoji_provider.dart';
 import '../../shared/custom_emoji/custom_emoji_render.dart';
+import '../../shared/emoji/emoji_data.dart';
+import '../../shared/emoji/emoji_data_provider.dart';
+import '../../shared/emoji/emoji_search.dart';
+import '../../shared/theme/theme.dart';
+import 'recent_emoji_provider.dart';
+
+part 'emoji_picker/search_field.dart';
+part 'emoji_picker/category_rail.dart';
+part 'emoji_picker/emoji_grid.dart';
+
+/// Height of the picker sheet as a fraction of the screen. The full emoji set
+/// is ~1.9k glyphs; the old fixed 340px sheet only ever showed a hand-picked
+/// subset and had no room to browse.
+const _sheetHeightFactor = 0.62;
 
 /// Opens the full emoji picker as a modal bottom sheet.
+///
+/// [onSelect] receives a single string, normalized the same way desktop's
+/// `EmojiPicker` normalizes its selection: a standard emoji emits its glyph, a
+/// custom emoji emits `:shortcode:`. Callers store or send that string and let
+/// the existing renderers resolve it.
 void showEmojiPicker({
   required BuildContext context,
   required void Function(String emoji) onSelect,
@@ -26,263 +45,119 @@ void showEmojiPicker({
   );
 }
 
-/// Emoji categories for the picker. System Unicode emoji — no packages needed.
-const emojiCategories = <({String label, IconData icon, List<String> emoji})>[
-  (
-    label: 'Popular',
-    icon: LucideIcons.clock,
-    emoji: [
-      '\u{1F44D}',
-      '\u{2764}\u{FE0F}',
-      '\u{1F602}',
-      '\u{1F389}',
-      '\u{1F440}',
-      '\u{1F64F}',
-      '\u{1F525}',
-      '\u{2705}',
-    ],
-  ),
-  (
-    label: 'Smileys',
-    icon: LucideIcons.smile,
-    emoji: [
-      '\u{1F600}',
-      '\u{1F603}',
-      '\u{1F604}',
-      '\u{1F601}',
-      '\u{1F605}',
-      '\u{1F602}',
-      '\u{1F923}',
-      '\u{1F607}',
-      '\u{1F60A}',
-      '\u{1F60D}',
-      '\u{1F618}',
-      '\u{1F617}',
-      '\u{1F61A}',
-      '\u{1F619}',
-      '\u{1F60B}',
-      '\u{1F61B}',
-      '\u{1F61D}',
-      '\u{1F61C}',
-      '\u{1F911}',
-      '\u{1F917}',
-      '\u{1F914}',
-      '\u{1F910}',
-      '\u{1F928}',
-      '\u{1F610}',
-      '\u{1F611}',
-      '\u{1F636}',
-      '\u{1F60F}',
-      '\u{1F612}',
-      '\u{1F644}',
-      '\u{1F62C}',
-      '\u{1F925}',
-      '\u{1F60C}',
-      '\u{1F614}',
-      '\u{1F62A}',
-      '\u{1F924}',
-      '\u{1F634}',
-      '\u{1F637}',
-      '\u{1F912}',
-      '\u{1F915}',
-      '\u{1F922}',
-      '\u{1F92E}',
-      '\u{1F927}',
-      '\u{1F975}',
-      '\u{1F976}',
-      '\u{1F974}',
-      '\u{1F635}',
-      '\u{1F92F}',
-      '\u{1F920}',
-      '\u{1F973}',
-      '\u{1F978}',
-    ],
-  ),
-  (
-    label: 'Gestures',
-    icon: LucideIcons.hand,
-    emoji: [
-      '\u{1F44D}',
-      '\u{1F44E}',
-      '\u{1F44A}',
-      '\u{270A}',
-      '\u{1F91B}',
-      '\u{1F91C}',
-      '\u{1F44F}',
-      '\u{1F64C}',
-      '\u{1F450}',
-      '\u{1F64F}',
-      '\u{1F91D}',
-      '\u{270C}\u{FE0F}',
-      '\u{1F91E}',
-      '\u{1F91F}',
-      '\u{1F918}',
-      '\u{1F448}',
-      '\u{1F449}',
-      '\u{1F446}',
-      '\u{1F447}',
-      '\u{261D}\u{FE0F}',
-      '\u{1F4AA}',
-      '\u{1F44B}',
-      '\u{1F590}\u{FE0F}',
-    ],
-  ),
-  (
-    label: 'Objects',
-    icon: LucideIcons.lightbulb,
-    emoji: [
-      '\u{2764}\u{FE0F}',
-      '\u{1F525}',
-      '\u{2B50}',
-      '\u{1F31F}',
-      '\u{1F4A5}',
-      '\u{1F389}',
-      '\u{1F38A}',
-      '\u{1F3C6}',
-      '\u{1F947}',
-      '\u{1F4A1}',
-      '\u{1F4AF}',
-      '\u{2705}',
-      '\u{274C}',
-      '\u{26A0}\u{FE0F}',
-      '\u{1F6A8}',
-      '\u{1F4DD}',
-      '\u{1F4CB}',
-      '\u{1F4CC}',
-      '\u{1F517}',
-      '\u{1F4E3}',
-      '\u{1F514}',
-      '\u{1F3B5}',
-      '\u{1F3B6}',
-      '\u{1F680}',
-    ],
-  ),
-  (
-    label: 'Nature',
-    icon: LucideIcons.leaf,
-    emoji: [
-      '\u{1F331}',
-      '\u{1F332}',
-      '\u{1F333}',
-      '\u{1F334}',
-      '\u{1F335}',
-      '\u{1F33B}',
-      '\u{1F33A}',
-      '\u{1F337}',
-      '\u{1F339}',
-      '\u{1F340}',
-      '\u{1F341}',
-      '\u{1F343}',
-      '\u{1F31E}',
-      '\u{1F308}',
-      '\u{2600}\u{FE0F}',
-      '\u{1F327}\u{FE0F}',
-      '\u{26A1}',
-      '\u{2744}\u{FE0F}',
-      '\u{1F30A}',
-      '\u{1F436}',
-      '\u{1F431}',
-      '\u{1F98A}',
-      '\u{1F42C}',
-      '\u{1F985}',
-    ],
-  ),
-];
-
-class EmojiPickerSheet extends ConsumerStatefulWidget {
+class EmojiPickerSheet extends HookConsumerWidget {
   final void Function(String emoji) onSelect;
 
   const EmojiPickerSheet({super.key, required this.onSelect});
 
   @override
-  ConsumerState<EmojiPickerSheet> createState() => _EmojiPickerSheetState();
-}
+  Widget build(BuildContext context, WidgetRef ref) {
+    final dataset = ref.watch(emojiDatasetOrEmptyProvider);
+    final customEmoji = ref.watch(customEmojiListProvider);
+    final recent = ref.watch(recentEmojiProvider);
 
-class _EmojiPickerSheetState extends ConsumerState<EmojiPickerSheet> {
-  /// -1 = "All", 0..N = specific category.
-  int _selectedCategory = -1;
+    final searchController = useTextEditingController();
+    final query = useState('');
+    useEffect(() {
+      void onChanged() => query.value = searchController.text;
+      searchController.addListener(onChanged);
+      return () => searchController.removeListener(onChanged);
+    }, [searchController]);
 
-  static final _allEmoji = () {
-    final seen = <String>{};
-    return [
-      for (final cat in emojiCategories)
-        for (final e in cat.emoji)
-          if (seen.add(e)) e,
-    ];
-  }();
+    final trimmedQuery = query.value.trim();
+    final isSearching = trimmedQuery.isNotEmpty;
 
-  @override
-  Widget build(BuildContext context) {
-    final colors = context.colors;
-    final customEmoji = ref.watch(customEmojiListProvider);
-    final isCustomCategory =
-        customEmoji.isNotEmpty && _selectedCategory == emojiCategories.length;
-    final emoji = _selectedCategory < 0
-        ? _allEmoji
-        : _selectedCategory < emojiCategories.length
-        ? emojiCategories[_selectedCategory].emoji
-        : const <String>[];
+    void select(String emoji) => onSelect(emoji);
+
+    final sections = useMemoized(
+      () => _buildSections(
+        dataset: dataset,
+        customEmoji: customEmoji,
+        recent: recent,
+        onSelect: select,
+      ),
+      [dataset, customEmoji, recent],
+    );
+    final offsets = useMemoized(() => _sectionOffsets(sections), [sections]);
+
+    final scrollController = useScrollController();
+    // A notifier rather than state: the highlight changes on every scroll frame
+    // and only the rail needs to hear about it. Rebuilding the sheet would
+    // rebuild the grid underneath it.
+    final activeSection = useMemoized(() => ValueNotifier(0), [sections]);
+    useEffect(() => activeSection.dispose, [activeSection]);
+
+    useEffect(() {
+      void onScroll() {
+        if (!scrollController.hasClients) return;
+        activeSection.value = _activeSectionIndex(
+          offsets,
+          scrollController.offset,
+        );
+      }
+
+      scrollController.addListener(onScroll);
+      return () => scrollController.removeListener(onScroll);
+    }, [scrollController, offsets, activeSection]);
+
+    void jumpToSection(int index) {
+      activeSection.value = index;
+      if (!scrollController.hasClients) return;
+      final max = scrollController.position.maxScrollExtent;
+      scrollController.animateTo(
+        offsets[index].clamp(0.0, max),
+        duration: const Duration(milliseconds: 240),
+        curve: Curves.easeOutCubic,
+      );
+    }
+
+    // Recompute only when the query or the underlying sets change — scanning
+    // ~1.9k entries per keystroke is sub-millisecond, but rebuilds are frequent
+    // while the sheet animates.
+    final results = useMemoized(
+      () => isSearching
+          ? searchEmoji(trimmedQuery, dataset.all)
+          : const <EmojiEntry>[],
+      [trimmedQuery, dataset],
+    );
+    final customResults = useMemoized(
+      () => isSearching
+          ? rankByShortcode(
+              trimmedQuery,
+              customEmoji,
+              (emoji) => emoji.shortcode,
+            )
+          : const <CustomEmoji>[],
+      [trimmedQuery, customEmoji],
+    );
 
     return SizedBox(
-      height: 340,
+      height: MediaQuery.sizeOf(context).height * _sheetHeightFactor,
       child: Column(
         children: [
-          // Category icon bar.
-          SizedBox(
-            height: 40,
-            child: Row(
-              children: [
-                const SizedBox(width: Grid.twelve),
-                CategoryIcon(
-                  icon: LucideIcons.layoutGrid,
-                  selected: _selectedCategory < 0,
-                  onTap: () => setState(() => _selectedCategory = -1),
-                ),
-                for (var i = 0; i < emojiCategories.length; i++)
-                  CategoryIcon(
-                    icon: emojiCategories[i].icon,
-                    selected: _selectedCategory == i,
-                    onTap: () => setState(() => _selectedCategory = i),
-                  ),
-                if (customEmoji.isNotEmpty)
-                  CategoryIcon(
-                    icon: LucideIcons.sparkles,
-                    selected: isCustomCategory,
-                    onTap: () => setState(
-                      () => _selectedCategory = emojiCategories.length,
-                    ),
-                  ),
-              ],
+          _EmojiSearchField(controller: searchController),
+          if (!isSearching && sections.isNotEmpty)
+            ValueListenableBuilder<int>(
+              valueListenable: activeSection,
+              builder: (context, active, _) => _CategoryRail(
+                sections: sections,
+                activeIndex: active,
+                onSelect: jumpToSection,
+              ),
             ),
-          ),
-          Divider(height: 1, color: colors.outlineVariant),
-          const SizedBox(height: Grid.xxs),
+          Divider(height: 1, color: context.colors.outlineVariant),
           Expanded(
-            child: isCustomCategory
-                ? _CustomEmojiGrid(
-                    emoji: customEmoji,
-                    onSelect: widget.onSelect,
+            child: dataset.isEmpty && customEmoji.isEmpty
+                ? const Center(child: CircularProgressIndicator())
+                : isSearching
+                ? _EmojiSearchResults(
+                    entries: results,
+                    customEmoji: customResults,
+                    onSelect: select,
                   )
-                : GridView.builder(
-                    padding: const EdgeInsets.symmetric(
-                      horizontal: Grid.gutter,
-                    ),
-                    gridDelegate:
-                        const SliverGridDelegateWithFixedCrossAxisCount(
-                          crossAxisCount: 8,
-                          mainAxisSpacing: Grid.half,
-                          crossAxisSpacing: Grid.half,
-                        ),
-                    itemCount: emoji.length,
-                    itemBuilder: (context, index) {
-                      final e = emoji[index];
-                      return GestureDetector(
-                        onTap: () => widget.onSelect(e),
-                        child: Center(
-                          child: Text(e, style: const TextStyle(fontSize: 28)),
-                        ),
-                      );
-                    },
+                : _ContinuousEmojiGrid(
+                    sections: sections,
+                    controller: scrollController,
                   ),
           ),
         ],
@@ -291,70 +166,118 @@ class _EmojiPickerSheetState extends ConsumerState<EmojiPickerSheet> {
   }
 }
 
-class _CustomEmojiGrid extends StatelessWidget {
-  final List<CustomEmoji> emoji;
-  final void Function(String emoji) onSelect;
+/// Build the scroll order: frequently-used, the dataset's own categories in
+/// emoji-mart order, then the community's custom emoji.
+///
+/// Frequently-used is omitted rather than shown empty — in a continuous list an
+/// empty section is a gap with a label on it, and the rail entry would lead
+/// nowhere.
+List<_EmojiSection> _buildSections({
+  required EmojiDataset dataset,
+  required List<CustomEmoji> customEmoji,
+  required List<RecentEmojiEntry> recent,
+  required void Function(String emoji) onSelect,
+}) {
+  final sections = <_EmojiSection>[];
 
-  const _CustomEmojiGrid({required this.emoji, required this.onSelect});
+  final recentTiles = _resolveRecentTiles(
+    recent: recent,
+    dataset: dataset,
+    customEmoji: customEmoji,
+    onSelect: onSelect,
+  );
+  if (recentTiles.isNotEmpty) {
+    sections.add(
+      _EmojiSection(
+        id: 'frequent',
+        label: 'Frequently used',
+        icon: LucideIcons.clock,
+        itemCount: recentTiles.length,
+        itemBuilder: (context, index) => recentTiles[index],
+      ),
+    );
+  }
 
-  @override
-  Widget build(BuildContext context) {
-    return GridView.builder(
-      padding: const EdgeInsets.symmetric(horizontal: Grid.gutter),
-      gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
-        crossAxisCount: 6,
-        mainAxisSpacing: Grid.half,
-        crossAxisSpacing: Grid.half,
+  for (final category in dataset.categories) {
+    sections.add(
+      _EmojiSection(
+        id: category.id,
+        label: category.label,
+        icon: _categoryIcon(category.id),
+        itemCount: category.emoji.length,
+        itemBuilder: (context, index) {
+          final entry = category.emoji[index];
+          return _EmojiTile(entry: entry, onTap: () => onSelect(entry.native));
+        },
       ),
-      itemCount: emoji.length,
-      itemBuilder: (context, index) {
-        final entry = emoji[index];
-        return GestureDetector(
-          onTap: () => onSelect(':${entry.shortcode}:'),
-          child: Tooltip(
-            message: ':${entry.shortcode}:',
-            child: Center(
-              child: CustomEmojiImage(
-                shortcode: entry.shortcode,
-                url: entry.url,
-                size: 32,
-              ),
-            ),
-          ),
-        );
-      },
     );
   }
-}
 
-class CategoryIcon extends StatelessWidget {
-  final IconData icon;
-  final bool selected;
-  final VoidCallback onTap;
+  if (customEmoji.isNotEmpty) {
+    sections.add(
+      _EmojiSection(
+        id: 'custom',
+        label: 'Custom',
+        icon: LucideIcons.sparkles,
+        itemCount: customEmoji.length,
+        itemBuilder: (context, index) {
+          final entry = customEmoji[index];
+          return _CustomEmojiTile(
+            emoji: entry,
+            onTap: () => onSelect(':${entry.shortcode}:'),
+          );
+        },
+      ),
+    );
+  }
 
-  const CategoryIcon({
-    super.key,
-    required this.icon,
-    required this.selected,
-    required this.onTap,
-  });
+  return sections;
+}
 
-  @override
-  Widget build(BuildContext context) {
-    final colors = context.colors;
-    return SizedBox(
-      width: 40,
-      height: 40,
-      child: IconButton(
-        onPressed: onTap,
-        icon: Icon(
-          icon,
-          size: 18,
-          color: selected ? colors.primary : colors.onSurfaceVariant,
+/// Resolve the recency list back to renderable tiles.
+///
+/// Entries are stored as the selected string, so a standard emoji is a glyph and
+/// a custom one is `:shortcode:` — resolve each against the dataset and the
+/// palette, and drop anything that no longer exists (a custom emoji removed from
+/// the community would otherwise render as literal text).
+List<Widget> _resolveRecentTiles({
+  required List<RecentEmojiEntry> recent,
+  required EmojiDataset dataset,
+  required List<CustomEmoji> customEmoji,
+  required void Function(String emoji) onSelect,
+}) {
+  final customByShortcode = {
+    for (final emoji in customEmoji) emoji.shortcode.toLowerCase(): emoji,
+  };
+  final entriesByNative = {
+    for (final entry in dataset.all) entry.native: entry,
+  };
+
+  final tiles = <Widget>[];
+  for (final item in recent) {
+    final value = item.emoji;
+    if (value.startsWith(':') && value.endsWith(':')) {
+      final custom =
+          customByShortcode[value.substring(1, value.length - 1).toLowerCase()];
+      if (custom == null) continue;
+      tiles.add(
+        _CustomEmojiTile(
+          emoji: custom,
+          onTap: () => onSelect(value),
+          keyPrefix: 'emoji-tile-frequent-custom',
         ),
-        padding: EdgeInsets.zero,
-        visualDensity: VisualDensity.compact,
+      );
+      continue;
+    }
+    final entry = entriesByNative[value];
+    if (entry == null) continue;
+    tiles.add(
+      _EmojiTile(
+        entry: entry,
+        onTap: () => onSelect(entry.native),
+        keyPrefix: 'emoji-tile-frequent',
       ),
     );
   }
+  return tiles;
 }
diff --git a/mobile/lib/features/channels/emoji_picker/category_rail.dart b/mobile/lib/features/channels/emoji_picker/category_rail.dart
new file mode 100644
index 0000000000..50df140688
--- /dev/null
+++ b/mobile/lib/features/channels/emoji_picker/category_rail.dart
@@ -0,0 +1,98 @@
+part of '../emoji_picker.dart';
+
+/// Rail icon for each emoji-mart category. Ids come from the dataset, so this
+/// map is keyed on emoji-mart's own category ids.
+IconData _categoryIcon(String categoryId) => switch (categoryId) {
+  'people' => LucideIcons.smile,
+  'nature' => LucideIcons.leaf,
+  'foods' => LucideIcons.coffee,
+  'activity' => LucideIcons.volleyball,
+  'places' => LucideIcons.plane,
+  'objects' => LucideIcons.lightbulb,
+  'symbols' => LucideIcons.heart,
+  'flags' => LucideIcons.flag,
+  _ => LucideIcons.layoutGrid,
+};
+
+/// Height of the rail. Sized to a comfortable tap target rather than to the
+/// 18px icon it holds.
+const _railHeight = 36.0;
+
+/// Category selector: one icon per section of the continuous grid, in scroll
+/// order. Tapping jumps to that section; scrolling moves the highlight.
+///
+/// The icons divide the full content width evenly — the same width the search
+/// field above spans — so the rail reads as a segmented control rather than a
+/// short left-aligned strip.
+class _CategoryRail extends StatelessWidget {
+  final List<_EmojiSection> sections;
+  final int activeIndex;
+  final ValueChanged<int> onSelect;
+
+  const _CategoryRail({
+    required this.sections,
+    required this.activeIndex,
+    required this.onSelect,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return SizedBox(
+      height: _railHeight,
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: Grid.gutter),
+        child: Row(
+          children: [
+            for (var i = 0; i < sections.length; i++)
+              Expanded(
+                child: _CategoryIcon(
+                  icon: sections[i].icon,
+                  tooltip: sections[i].label,
+                  selected: i == activeIndex,
+                  onTap: () => onSelect(i),
+                ),
+              ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+
+class _CategoryIcon extends StatelessWidget {
+  final IconData icon;
+  final String tooltip;
+  final bool selected;
+  final VoidCallback onTap;
+
+  const _CategoryIcon({
+    required this.icon,
+    required this.tooltip,
+    required this.selected,
+    required this.onTap,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final colors = context.colors;
+    return Tooltip(
+      message: tooltip,
+      child: InkWell(
+        onTap: onTap,
+        borderRadius: BorderRadius.circular(Radii.sm),
+        child: Semantics(
+          button: true,
+          selected: selected,
+          label: tooltip,
+          child: Center(
+            child: Icon(
+              icon,
+              size: 18,
+              color: selected ? colors.primary : colors.onSurfaceVariant,
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/emoji_picker/emoji_grid.dart b/mobile/lib/features/channels/emoji_picker/emoji_grid.dart
new file mode 100644
index 0000000000..2ebe631edd
--- /dev/null
+++ b/mobile/lib/features/channels/emoji_picker/emoji_grid.dart
@@ -0,0 +1,346 @@
+part of '../emoji_picker.dart';
+
+/// Emoji per row. Matches desktop's `perLine={8}`.
+const _emojiPerLine = 8;
+
+/// Rendered glyph size. Standard and custom emoji share this so a community's
+/// own emoji sit in the grid at the same weight as the native set.
+const _emojiGlyphSize = 28.0;
+
+/// Height of one grid cell. Fixed rather than derived from the cell width so
+/// section offsets are exact — [_EmojiSection.extent] is what the rail scrolls
+/// to, and a width-dependent row height would make it a guess.
+const _cellExtent = 40.0;
+
+/// Height of a pinned section header, padding included. Also fixed, for the
+/// same reason.
+const _sectionHeaderExtent = 28.0;
+
+/// Cells divide the content width evenly with no gaps, the way emoji-mart lays
+/// its grid out; the space around each glyph comes from the cell being larger
+/// than the glyph.
+SliverGridDelegate get _gridDelegate =>
+    const SliverGridDelegateWithFixedCrossAxisCount(
+      crossAxisCount: _emojiPerLine,
+      mainAxisExtent: _cellExtent,
+    );
+
+/// One labelled run of tiles in the continuous grid.
+///
+/// Sections know their own scroll extent so the rail can jump to them without
+/// the grid having been laid out — with ~1.9k emoji most sections are far
+/// off-screen, so there is no render object to measure or `ensureVisible`.
+class _EmojiSection {
+  final String id;
+  final String label;
+  final IconData icon;
+  final int itemCount;
+  final Widget Function(BuildContext context, int index) itemBuilder;
+
+  const _EmojiSection({
+    required this.id,
+    required this.label,
+    required this.icon,
+    required this.itemCount,
+    required this.itemBuilder,
+  });
+
+  int get rowCount => (itemCount / _emojiPerLine).ceil();
+
+  double get extent => _sectionHeaderExtent + rowCount * _cellExtent;
+}
+
+/// Offset of each section's header, in scroll order. Element `i` is where the
+/// rail should land for section `i`.
+List<double> _sectionOffsets(List<_EmojiSection> sections) {
+  final offsets = <double>[];
+  var running = 0.0;
+  for (final section in sections) {
+    offsets.add(running);
+    running += section.extent;
+  }
+  return offsets;
+}
+
+/// Which section owns [offset] — the one whose header is pinned right now.
+int _activeSectionIndex(List<double> offsets, double offset) {
+  var active = 0;
+  for (var i = 0; i < offsets.length; i++) {
+    // Half a header of slack so the highlight flips as a header reaches the
+    // top rather than a pixel before.
+    if (offsets[i] <= offset + _sectionHeaderExtent / 2) active = i;
+  }
+  return active;
+}
+
+/// One tappable standard emoji.
+///
+/// [keyPrefix] exists because the frequently-used section repeats emoji that
+/// also appear in their own category, and both are in the same scroll view — two
+/// widgets keyed `emoji-tile-fire` would be indistinguishable to a test.
+class _EmojiTile extends StatelessWidget {
+  final EmojiEntry entry;
+  final VoidCallback onTap;
+  final String keyPrefix;
+
+  const _EmojiTile({
+    required this.entry,
+    required this.onTap,
+    this.keyPrefix = 'emoji-tile',
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return GestureDetector(
+      key: ValueKey('$keyPrefix-${entry.tileId}'),
+      onTap: onTap,
+      behavior: HitTestBehavior.opaque,
+      child: Semantics(
+        button: true,
+        label: entry.name,
+        child: Center(
+          child: Text(
+            entry.native,
+            style: const TextStyle(fontSize: _emojiGlyphSize),
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+/// One tappable custom (image) emoji. Same cell and same glyph size as
+/// [_EmojiTile] — a community's emoji shouldn't be laid out on its own looser
+/// grid, which is what made the custom tab read as a different component.
+class _CustomEmojiTile extends StatelessWidget {
+  final CustomEmoji emoji;
+  final VoidCallback onTap;
+  final String keyPrefix;
+
+  const _CustomEmojiTile({
+    required this.emoji,
+    required this.onTap,
+    this.keyPrefix = 'emoji-tile-custom',
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return GestureDetector(
+      key: ValueKey('$keyPrefix-${emoji.shortcode}'),
+      onTap: onTap,
+      behavior: HitTestBehavior.opaque,
+      child: Tooltip(
+        message: ':${emoji.shortcode}:',
+        child: Center(
+          child: CustomEmojiImage(
+            shortcode: emoji.shortcode,
+            url: emoji.url,
+            size: _emojiGlyphSize,
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+/// Every section in one scroll view, headers pinning as they reach the top.
+///
+/// Replaces the old tab-per-category swap: the rail is a shortcut into a single
+/// list, not a set of separate pages, which is how both desktop and every
+/// system emoji keyboard behave.
+class _ContinuousEmojiGrid extends StatelessWidget {
+  final List<_EmojiSection> sections;
+  final ScrollController controller;
+
+  const _ContinuousEmojiGrid({
+    required this.sections,
+    required this.controller,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return CustomScrollView(
+      key: const ValueKey('emoji-picker-grid'),
+      controller: controller,
+      slivers: [
+        for (final section in sections)
+          SliverMainAxisGroup(
+            key: ValueKey('emoji-section-${section.id}'),
+            slivers: [
+              SliverPersistentHeader(
+                pinned: true,
+                delegate: _SectionHeaderDelegate(section.label),
+              ),
+              SliverPadding(
+                padding: const EdgeInsets.symmetric(horizontal: Grid.gutter),
+                sliver: SliverGrid.builder(
+                  gridDelegate: _gridDelegate,
+                  itemCount: section.itemCount,
+                  itemBuilder: section.itemBuilder,
+                ),
+              ),
+            ],
+          ),
+        // Clear the home indicator so the last row isn't half-swallowed. Sits
+        // outside the sections so it doesn't skew their offsets.
+        SliverToBoxAdapter(
+          child: SizedBox(
+            height: MediaQuery.viewPaddingOf(context).bottom + Grid.xxs,
+          ),
+        ),
+      ],
+    );
+  }
+}
+
+/// Search results: custom emoji first (a community's own emoji are the ones a
+/// user is most likely hunting for by name), then the standard set.
+class _EmojiSearchResults extends StatelessWidget {
+  final List<EmojiEntry> entries;
+  final List<CustomEmoji> customEmoji;
+  final void Function(String emoji) onSelect;
+
+  const _EmojiSearchResults({
+    required this.entries,
+    required this.customEmoji,
+    required this.onSelect,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    if (entries.isEmpty && customEmoji.isEmpty) {
+      return _EmojiEmptyState(
+        icon: LucideIcons.searchX,
+        message: 'No emoji found.',
+      );
+    }
+
+    return CustomScrollView(
+      key: const ValueKey('emoji-picker-search-results'),
+      slivers: [
+        if (customEmoji.isNotEmpty) ...[
+          const _SectionHeader(label: 'Custom'),
+          SliverPadding(
+            padding: const EdgeInsets.symmetric(horizontal: Grid.gutter),
+            sliver: SliverGrid.builder(
+              gridDelegate: _gridDelegate,
+              itemCount: customEmoji.length,
+              itemBuilder: (context, index) {
+                final entry = customEmoji[index];
+                return _CustomEmojiTile(
+                  emoji: entry,
+                  onTap: () => onSelect(':${entry.shortcode}:'),
+                );
+              },
+            ),
+          ),
+        ],
+        if (entries.isNotEmpty) ...[
+          if (customEmoji.isNotEmpty) const _SectionHeader(label: 'Emoji'),
+          SliverPadding(
+            padding: const EdgeInsets.symmetric(horizontal: Grid.gutter),
+            sliver: SliverGrid.builder(
+              gridDelegate: _gridDelegate,
+              itemCount: entries.length,
+              itemBuilder: (context, index) {
+                final entry = entries[index];
+                return _EmojiTile(
+                  entry: entry,
+                  onTap: () => onSelect(entry.native),
+                );
+              },
+            ),
+          ),
+        ],
+        SliverToBoxAdapter(
+          child: SizedBox(
+            height: MediaQuery.viewPaddingOf(context).bottom + Grid.xxs,
+          ),
+        ),
+      ],
+    );
+  }
+}
+
+/// Pinned header for a section of the continuous grid. Opaque, so rows scroll
+/// under it rather than showing through.
+class _SectionHeaderDelegate extends SliverPersistentHeaderDelegate {
+  final String label;
+
+  const _SectionHeaderDelegate(this.label);
+
+  @override
+  double get minExtent => _sectionHeaderExtent;
+
+  @override
+  double get maxExtent => _sectionHeaderExtent;
+
+  @override
+  Widget build(
+    BuildContext context,
+    double shrinkOffset,
+    bool overlapsContent,
+  ) {
+    return Container(
+      color: context.colors.surfaceContainerHighest,
+      alignment: Alignment.centerLeft,
+      padding: const EdgeInsets.symmetric(horizontal: Grid.gutter),
+      child: Text(label, style: _sectionLabelStyle(context)),
+    );
+  }
+
+  @override
+  bool shouldRebuild(_SectionHeaderDelegate oldDelegate) =>
+      oldDelegate.label != label;
+}
+
+/// Non-pinned header, for the search results list.
+class _SectionHeader extends StatelessWidget {
+  final String label;
+
+  const _SectionHeader({required this.label});
+
+  @override
+  Widget build(BuildContext context) {
+    return SliverToBoxAdapter(
+      child: Container(
+        height: _sectionHeaderExtent,
+        alignment: Alignment.centerLeft,
+        padding: const EdgeInsets.symmetric(horizontal: Grid.gutter),
+        child: Text(label, style: _sectionLabelStyle(context)),
+      ),
+    );
+  }
+}
+
+TextStyle? _sectionLabelStyle(BuildContext context) =>
+    context.textTheme.labelMedium?.copyWith(
+      color: context.colors.onSurfaceVariant,
+      fontWeight: FontWeight.w600,
+    );
+
+class _EmojiEmptyState extends StatelessWidget {
+  final IconData icon;
+  final String message;
+
+  const _EmojiEmptyState({required this.icon, required this.message});
+
+  @override
+  Widget build(BuildContext context) {
+    return Center(
+      child: Column(
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          Icon(icon, size: Grid.md, color: context.colors.onSurfaceVariant),
+          const SizedBox(height: Grid.xxs),
+          Text(
+            message,
+            style: context.textTheme.bodySmall?.copyWith(
+              color: context.colors.onSurfaceVariant,
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/emoji_picker/search_field.dart b/mobile/lib/features/channels/emoji_picker/search_field.dart
new file mode 100644
index 0000000000..dd4c4ee923
--- /dev/null
+++ b/mobile/lib/features/channels/emoji_picker/search_field.dart
@@ -0,0 +1,78 @@
+part of '../emoji_picker.dart';
+
+/// Search field at the top of the picker sheet.
+///
+/// Desktop reaches into emoji-mart's shadow DOM to turn off spellcheck,
+/// autocorrect, and autocapitalize on its search input (see
+/// `disableSearchInputCorrections` in `EmojiPicker.tsx`) — shortcodes are not
+/// words and the OS mangles them. Flutter exposes the same switches directly.
+class _EmojiSearchField extends StatelessWidget {
+  final TextEditingController controller;
+
+  const _EmojiSearchField({required this.controller});
+
+  @override
+  Widget build(BuildContext context) {
+    final colors = context.colors;
+    return Padding(
+      padding: const EdgeInsets.fromLTRB(Grid.gutter, 0, Grid.gutter, Grid.xxs),
+      child: TextField(
+        key: const ValueKey('emoji-picker-search'),
+        controller: controller,
+        autocorrect: false,
+        enableSuggestions: false,
+        textCapitalization: TextCapitalization.none,
+        textInputAction: TextInputAction.search,
+        style: searchInputTextStyle.copyWith(color: colors.onSurface),
+        decoration: InputDecoration(
+          hintText: 'Search emoji',
+          hintStyle: searchInputTextStyle.copyWith(
+            color: colors.onSurfaceVariant,
+          ),
+          prefixIcon: Icon(
+            LucideIcons.search,
+            size: 18,
+            color: colors.onSurfaceVariant,
+          ),
+          prefixIconConstraints: const BoxConstraints(
+            minWidth: Grid.md,
+            minHeight: Grid.md,
+          ),
+          suffixIcon: ValueListenableBuilder<TextEditingValue>(
+            valueListenable: controller,
+            builder: (context, value, _) {
+              if (value.text.isEmpty) return const SizedBox.shrink();
+              return IconButton(
+                key: const ValueKey('emoji-picker-search-clear'),
+                onPressed: controller.clear,
+                icon: Icon(
+                  LucideIcons.x,
+                  size: 16,
+                  color: colors.onSurfaceVariant,
+                ),
+                visualDensity: VisualDensity.compact,
+                tooltip: 'Clear search',
+              );
+            },
+          ),
+          filled: true,
+          fillColor: colors.surface,
+          isDense: true,
+          contentPadding: const EdgeInsets.symmetric(vertical: Grid.xxs),
+          border: OutlineInputBorder(
+            borderRadius: BorderRadius.circular(Radii.lg),
+            borderSide: BorderSide(color: colors.outlineVariant),
+          ),
+          enabledBorder: OutlineInputBorder(
+            borderRadius: BorderRadius.circular(Radii.lg),
+            borderSide: BorderSide(color: colors.outlineVariant),
+          ),
+          focusedBorder: OutlineInputBorder(
+            borderRadius: BorderRadius.circular(Radii.lg),
+            borderSide: BorderSide(color: colors.primary),
+          ),
+        ),
+      ),
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/mentions/mention_candidates.dart b/mobile/lib/features/channels/mentions/mention_candidates.dart
index ca97d65e34..9c4ef96bbe 100644
--- a/mobile/lib/features/channels/mentions/mention_candidates.dart
+++ b/mobile/lib/features/channels/mentions/mention_candidates.dart
@@ -1,59 +1,8 @@
-import 'dart:convert';
-
-import '../../../shared/relay/nostr_models.dart';
+import '../../../shared/mentions/agent_identity_provider.dart';
 import '../../profile/user_profile.dart';
 import '../channel_management_provider.dart';
 import 'mention_ranking.dart';
 
-/// A relay agent parsed from its kind:10100 agent-profile event.
-///
-/// Mirrors the fields desktop's `RelayAgent` uses for mention eligibility
-/// (`agentAutocompleteEligibility.ts`): who the agent responds to and which
-/// channels it sits in.
-class AgentDirectoryEntry {
-  final String pubkey;
-  final String? displayName;
-  final String? respondTo;
-  final List<String> respondToAllowlist;
-  final List<String> channelIds;
-
-  const AgentDirectoryEntry({
-    required this.pubkey,
-    this.displayName,
-    this.respondTo,
-    this.respondToAllowlist = const [],
-    this.channelIds = const [],
-  });
-
-  factory AgentDirectoryEntry.fromEvent(NostrEvent event) {
-    final content = _tryDecodeJsonMap(event.content);
-    return AgentDirectoryEntry(
-      pubkey: event.pubkey.toLowerCase(),
-      displayName:
-          (content?['display_name'] as String?) ??
-          (content?['name'] as String?),
-      respondTo: content?['respond_to'] as String?,
-      respondToAllowlist: [
-        for (final value in (content?['respond_to_allowlist'] as List?) ?? [])
-          if (value is String) value.toLowerCase(),
-      ],
-      channelIds: [
-        for (final value in (content?['channel_ids'] as List?) ?? [])
-          if (value is String) value,
-      ],
-    );
-  }
-}
-
-Map<String, dynamic>? _tryDecodeJsonMap(String content) {
-  try {
-    final decoded = jsonDecode(content);
-    return decoded is Map<String, dynamic> ? decoded : null;
-  } catch (_) {
-    return null;
-  }
-}
-
 /// Whether a non-member relay agent should be mentionable by the current
 /// user. Mirrors desktop's `relayAgentIsSharedWithUser`:
 /// - allowlist mode: user must be on the allowlist
diff --git a/mobile/lib/features/channels/mentions/mention_candidates_provider.dart b/mobile/lib/features/channels/mentions/mention_candidates_provider.dart
index c2aa056a05..6e94459231 100644
--- a/mobile/lib/features/channels/mentions/mention_candidates_provider.dart
+++ b/mobile/lib/features/channels/mentions/mention_candidates_provider.dart
@@ -1,6 +1,7 @@
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 
 import '../../../shared/crypto/nip_oa.dart';
+import '../../../shared/mentions/agent_identity_provider.dart';
 import '../../../shared/relay/relay.dart';
 import '../../profile/user_cache_provider.dart';
 import '../../profile/user_profile.dart';
@@ -10,64 +11,6 @@ import '../channels_provider.dart';
 import 'mention_candidates.dart';
 import 'mention_ranking.dart';
 
-/// Relay agent directory from kind:10100 agent-profile events.
-///
-/// Watches the session and only fetches after the WebSocket connects.
-final agentDirectoryProvider = FutureProvider<List<AgentDirectoryEntry>>((
-  ref,
-) async {
-  final sessionState = ref.watch(relaySessionProvider);
-  if (sessionState.status != SessionStatus.connected) return const [];
-  final session = ref.read(relaySessionProvider.notifier);
-  final events = await session.fetchHistory(NostrFilters.agentProfiles());
-  return [for (final event in events) AgentDirectoryEntry.fromEvent(event)];
-});
-
-/// Verified NIP-OA owner pubkey per agent pubkey, from the agents' kind:0
-/// profiles. An entry exists only when the `auth` tag verifies — mirrors
-/// desktop's `profile_valid_oa_owner_pubkey`.
-final agentOwnersProvider = FutureProvider<Map<String, String>>((ref) async {
-  final agents = await ref.watch(agentDirectoryProvider.future);
-  if (agents.isEmpty) return const {};
-  final session = ref.read(relaySessionProvider.notifier);
-  final events = await session.fetchHistory(
-    NostrFilters.profilesBatch([for (final agent in agents) agent.pubkey]),
-  );
-  final owners = <String, String>{};
-  for (final event in events) {
-    final owner = verifiedOaOwnerPubkey(event.tags, event.pubkey);
-    if (owner != null) owners[event.pubkey.toLowerCase()] = owner;
-  }
-  return owners;
-});
-
-/// Pubkeys currently known to represent agents for rendered mention chips.
-///
-/// Uses the same three identity sources as mention autocomplete: channel bot
-/// roles, relay agent-directory entries, and verified NIP-OA ownership.
-final mentionAgentPubkeysProvider = Provider.family<Set<String>, String>((
-  ref,
-  channelId,
-) {
-  final members =
-      ref.watch(channelMembersProvider(channelId)).asData?.value ??
-      const <ChannelMember>[];
-  final relayAgents =
-      ref.watch(agentDirectoryProvider).asData?.value ??
-      const <AgentDirectoryEntry>[];
-  final owners = ref.watch(agentOwnersProvider).asData?.value ?? const {};
-  final userCache = ref.watch(userCacheProvider);
-
-  return {
-    for (final member in members)
-      if (member.isBot) member.pubkey.toLowerCase(),
-    for (final agent in relayAgents) agent.pubkey.toLowerCase(),
-    ...owners.keys.map((pubkey) => pubkey.toLowerCase()),
-    for (final profile in userCache.values)
-      if (profile.ownerPubkey != null) profile.pubkey.toLowerCase(),
-  };
-});
-
 /// Debounce before a mention query hits the relay search endpoint.
 const _mentionSearchDebounce = Duration(milliseconds: 250);
 
diff --git a/mobile/lib/features/channels/message_actions.dart b/mobile/lib/features/channels/message_actions.dart
index c4cc5e2a0e..519d25898c 100644
--- a/mobile/lib/features/channels/message_actions.dart
+++ b/mobile/lib/features/channels/message_actions.dart
@@ -16,11 +16,14 @@ import '../../shared/relay/relay.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/custom_emoji/custom_emoji.dart';
 import '../../shared/custom_emoji/custom_emoji_provider.dart';
+import '../../shared/custom_emoji/custom_emoji_render.dart';
 import '../../shared/widgets/sheet_divider.dart';
 import '../../shared/reminders/remind_me_later_sheet.dart';
 import '../../shared/reminders/reminder_service.dart';
 import 'channel_management_provider.dart';
 import 'emoji_picker.dart';
+import 'reaction_row.dart';
+import 'recent_emoji_provider.dart';
 import 'read_state/message_read_state.dart';
 import 'read_state/read_state_format.dart';
 import 'read_state/read_state_provider.dart';
@@ -28,8 +31,6 @@ import 'thread_detail_page.dart';
 import 'thread_follows/thread_follows_provider.dart';
 import 'timeline_message.dart';
 
-const quickEmojis = ['\u{1F44D}', '\u{2764}\u{FE0F}', '\u{1F602}', '\u{1F389}'];
-
 /// Preview length for reminder targets — matches desktop's
 /// `msg.body.slice(0, 100)`.
 const _reminderPreviewLength = 100;
@@ -65,42 +66,11 @@ void showMessageActions({
             child: Column(
               mainAxisSize: MainAxisSize.min,
               children: [
-                // Quick emoji row
-                Row(
-                  mainAxisAlignment: MainAxisAlignment.spaceEvenly,
-                  children: [
-                    for (final emoji in quickEmojis)
-                      _QuickReactionCircle(
-                        onTap: () {
-                          Navigator.of(sheetContext).pop();
-                          ref
-                              .read(channelActionsProvider)
-                              .addReaction(message.id, emoji);
-                        },
-                        child: Text(
-                          emoji,
-                          style: const TextStyle(fontSize: 24),
-                        ),
-                      ),
-                    _QuickReactionCircle(
-                      onTap: () {
-                        Navigator.of(sheetContext).pop();
-                        showEmojiPicker(
-                          context: context,
-                          onSelect: (emoji) {
-                            ref
-                                .read(channelActionsProvider)
-                                .addReaction(message.id, emoji);
-                          },
-                        );
-                      },
-                      child: Icon(
-                        LucideIcons.plus,
-                        size: 24,
-                        color: sheetContext.colors.onSurfaceVariant,
-                      ),
-                    ),
-                  ],
+                _QuickReactionRow(
+                  message: message,
+                  sheetContext: sheetContext,
+                  pageContext: context,
+                  pageRef: ref,
                 ),
                 const SizedBox(height: Grid.xs),
                 if (!message.isSystem) ...[
@@ -614,6 +584,115 @@ class _FastActionTile extends StatelessWidget {
   }
 }
 
+/// The row of one-tap reactions at the top of the action sheet, plus the "+"
+/// tile that opens the full picker.
+///
+/// The emoji shown are the user's own frequently-used set (desktop's
+/// `useQuickReactionEmojis` behaviour), topped up with [defaultQuickEmojis] so
+/// the row is full on a fresh install.
+class _QuickReactionRow extends ConsumerWidget {
+  final TimelineMessage message;
+
+  /// The sheet's context, popped before the reaction fires.
+  final BuildContext sheetContext;
+
+  /// The long-pressed message's page context — survives the sheet pop, so the
+  /// picker opened from "+" isn't torn down with the sheet.
+  final BuildContext pageContext;
+
+  /// The long-pressed message's page ref. The picker callback outlives this
+  /// bottom sheet, so it must not read through the sheet's disposed ref.
+  final WidgetRef pageRef;
+
+  const _QuickReactionRow({
+    required this.message,
+    required this.sheetContext,
+    required this.pageContext,
+    required this.pageRef,
+  });
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final customEmoji = ref.watch(customEmojiListProvider);
+    final emoji = quickReactionEmoji(
+      ref.watch(recentEmojiProvider),
+      customShortcodes: {
+        for (final entry in customEmoji) entry.shortcode.toLowerCase(),
+      },
+    );
+    final customByShortcode = {
+      for (final entry in customEmoji) entry.shortcode.toLowerCase(): entry,
+    };
+
+    void react(String value) {
+      // The generic picker is also used for composing and statuses. Record
+      // recency here, at the reaction call site, so only reactions drive the
+      // quick-reaction row.
+      pageRef.read(recentEmojiProvider.notifier).record(value);
+      // The sheet is on its way out, so the burst can't come from this tile —
+      // hand it to the pill that's about to appear in the timeline.
+      armReactionBurst(pageRef, message, value);
+      pageRef.read(channelActionsProvider).addReaction(message.id, value);
+    }
+
+    return Row(
+      mainAxisAlignment: MainAxisAlignment.spaceEvenly,
+      children: [
+        for (final value in emoji)
+          _QuickReactionCircle(
+            onTap: () {
+              Navigator.of(sheetContext).pop();
+              react(value);
+            },
+            child: _QuickReactionGlyph(
+              value: value,
+              customByShortcode: customByShortcode,
+            ),
+          ),
+        _QuickReactionCircle(
+          onTap: () {
+            Navigator.of(sheetContext).pop();
+            showEmojiPicker(context: pageContext, onSelect: react);
+          },
+          child: Icon(
+            LucideIcons.plus,
+            size: 24,
+            color: context.colors.onSurfaceVariant,
+          ),
+        ),
+      ],
+    );
+  }
+}
+
+/// Renders a quick-reaction value: a Unicode glyph as text, a `:shortcode:` as
+/// its custom-emoji image.
+class _QuickReactionGlyph extends StatelessWidget {
+  final String value;
+  final Map<String, CustomEmoji> customByShortcode;
+
+  const _QuickReactionGlyph({
+    required this.value,
+    required this.customByShortcode,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    if (value.startsWith(':') && value.endsWith(':')) {
+      final shortcode = value.substring(1, value.length - 1).toLowerCase();
+      final custom = customByShortcode[shortcode];
+      if (custom != null) {
+        return CustomEmojiImage(
+          shortcode: custom.shortcode,
+          url: custom.url,
+          size: 24,
+        );
+      }
+    }
+    return Text(value, style: const TextStyle(fontSize: 24));
+  }
+}
+
 /// Circular filled tap target shared by the quick-reaction emojis and the
 /// "+" emoji-picker tile — one treatment, one place to change it.
 class _QuickReactionCircle extends StatelessWidget {
diff --git a/mobile/lib/features/channels/message_content.dart b/mobile/lib/features/channels/message_content.dart
index 664594ade7..465585d966 100644
--- a/mobile/lib/features/channels/message_content.dart
+++ b/mobile/lib/features/channels/message_content.dart
@@ -19,6 +19,8 @@ import '../../shared/theme/theme.dart';
 import '../../shared/custom_emoji/custom_emoji.dart';
 import '../../shared/custom_emoji/custom_emoji_provider.dart';
 import '../../shared/custom_emoji/custom_emoji_render.dart';
+import '../../shared/emoji/emoji_data_provider.dart';
+import '../../shared/emoji/emoji_only.dart';
 import 'media_viewer_page.dart';
 import 'message_media.dart';
 
@@ -105,6 +107,12 @@ class MessageContent extends HookConsumerWidget {
 
   final int? maxLines;
 
+  /// Render a body that is nothing but emoji at [kEmojiOnlyFontSize], the way
+  /// desktop's `MessageRow` does. Off by default: previews, search hits, and
+  /// notification rows want a message to occupy its usual line height whatever
+  /// it contains.
+  final bool scaleEmojiOnly;
+
   /// Allows a multi-image carousel to reclaim leading space reserved by the
   /// surrounding message layout, while keeping its image count aligned with
   /// the message body.
@@ -127,15 +135,20 @@ class MessageContent extends HookConsumerWidget {
     this.onMediaMore,
     this.baseStyle,
     this.maxLines,
+    this.scaleEmojiOnly = false,
     this.mediaCarouselLeadingOverflow = 0,
     this.mediaCarouselTrailingOverflow = 0,
   });
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
-    final style =
+    final baseTextStyle =
         baseStyle ??
         context.textTheme.bodyMedium?.copyWith(color: context.colors.onSurface);
+    final resolvedMentionNames = mentionNames;
+    final resolvedAgentMentionPubkeys = {
+      ...agentMentionPubkeys.map((pubkey) => pubkey.toLowerCase()),
+    };
     final imetaByUrl = parseImetaTags(tags);
     final trailingGallery = maxLines == null
         ? _extractTrailingImageGallery(content, imetaByUrl)
@@ -145,6 +158,33 @@ class MessageContent extends HookConsumerWidget {
       customEmojiFromTags(tags),
       ref.watch(customEmojiListProvider),
     );
+    final mentionPresentationKey = [
+      for (final entry
+          in (resolvedMentionNames.entries.toList()
+            ..sort((a, b) => a.key.compareTo(b.key))))
+        '${entry.key}\u0000${entry.value}',
+      ...(resolvedAgentMentionPubkeys.toList()..sort()),
+    ].join('\u0001');
+
+    // Decided here rather than by the caller: this is where the event's own
+    // emoji tags and the community palette have already been merged, and a
+    // `:shortcode:` only counts as emoji if it resolves against that palette.
+    final emojiOnly =
+        scaleEmojiOnly &&
+        isEmojiOnlyMessage(
+          markdownContent,
+          nativeEmoji: ref.watch(nativeEmojiGlyphsProvider),
+          customEmoji: customEmoji,
+        );
+    final style = emojiOnly
+        ? baseTextStyle?.copyWith(
+            fontSize: kEmojiOnlyFontSize,
+            height: kEmojiOnlyHeight,
+          )
+        : baseTextStyle;
+    final inlineCustomEmojiSize = emojiOnly
+        ? kEmojiOnlyCustomEmojiSize
+        : kCustomEmojiInlineSize;
 
     final finalContent = useMemoized(() {
       // Convert autolinks and bare URLs to standard markdown links,
@@ -191,7 +231,7 @@ class MessageContent extends HookConsumerWidget {
           mentionBuf.write('`${mentionParts[i]}`');
         } else {
           var segment = mentionParts[i];
-          for (final name in mentionNames.values) {
+          for (final name in resolvedMentionNames.values) {
             if (name.contains(' ')) {
               final normalizedName = _markdownMentionName(name);
               segment = segment.replaceAllMapped(
@@ -212,29 +252,35 @@ class MessageContent extends HookConsumerWidget {
         result = '\u200B$result';
       }
       return result;
-    }, [markdownContent, mentionNames]);
-
-    final markdown = GptMarkdown(
-      finalContent,
-      style: style,
-      followLinkColor: false,
-      codeBuilder: (context, name, code, closed) =>
-          _MessageCodeBlock(name: name, code: code),
-      linkBuilder: (context, linkText, url, linkStyle) =>
-          _buildLink(context, ref, linkText, url, linkStyle, style),
-      imageBuilder: (context, imageUrl) =>
-          _buildMedia(context, imageUrl, imetaByUrl[imageUrl]),
-      maxLines: maxLines,
-      inlineComponents: [
-        _MentionMd(
-          mentionNames: mentionNames,
-          agentMentionPubkeys: agentMentionPubkeys,
-          onMentionTap: onMentionTap,
-        ),
-        CustomEmojiMd(customEmoji),
-        _ChannelLinkMd(channelNames: channelNames, onChannelTap: onChannelTap),
-        ...MarkdownComponent.inlineComponents,
-      ],
+    }, [markdownContent, resolvedMentionNames]);
+
+    final markdown = KeyedSubtree(
+      key: ValueKey('$finalContent\u0000$mentionPresentationKey'),
+      child: GptMarkdown(
+        finalContent,
+        style: style,
+        followLinkColor: false,
+        codeBuilder: (context, name, code, closed) =>
+            _MessageCodeBlock(name: name, code: code),
+        linkBuilder: (context, linkText, url, linkStyle) =>
+            _buildLink(context, ref, linkText, url, linkStyle, style),
+        imageBuilder: (context, imageUrl) =>
+            _buildMedia(context, imageUrl, imetaByUrl[imageUrl]),
+        maxLines: maxLines,
+        inlineComponents: [
+          _MentionMd(
+            mentionNames: resolvedMentionNames,
+            agentMentionPubkeys: resolvedAgentMentionPubkeys,
+            onMentionTap: onMentionTap,
+          ),
+          CustomEmojiMd(customEmoji, size: inlineCustomEmojiSize),
+          _ChannelLinkMd(
+            channelNames: channelNames,
+            onChannelTap: onChannelTap,
+          ),
+          ...MarkdownComponent.inlineComponents,
+        ],
+      ),
     );
     if (trailingGallery == null) return markdown;
 
diff --git a/mobile/lib/features/channels/message_content/media_carousel.dart b/mobile/lib/features/channels/message_content/media_carousel.dart
index 88bfed5b1d..545adba36c 100644
--- a/mobile/lib/features/channels/message_content/media_carousel.dart
+++ b/mobile/lib/features/channels/message_content/media_carousel.dart
@@ -141,7 +141,7 @@ class _MessageImageCarousel extends HookConsumerWidget {
               fontWeight: FontWeight.w400,
             ),
           ),
-          const SizedBox(height: Grid.half),
+          const SizedBox(height: Grid.half + Grid.quarter),
           LayoutBuilder(
             builder: (context, constraints) {
               final contentWidth = constraints.hasBoundedWidth
@@ -152,12 +152,16 @@ class _MessageImageCarousel extends HookConsumerWidget {
               final leadingExtent = leadingOverflow;
               final isLeftToRight =
                   Directionality.of(context) == TextDirection.ltr;
+              final itemTrailingPaddings = [
+                for (var index = 0; index < items.length; index++)
+                  index == items.length - 1 ? Grid.gutter : Grid.half,
+              ];
               final previewDecodeWidths = [
                 for (var index = 0; index < items.length; index++)
                   math.max(
                     1.0,
                     carouselWidth * controller.viewportFraction -
-                        (index == items.length - 1 ? 0 : Grid.half),
+                        itemTrailingPaddings[index],
                   ),
               ];
               final devicePixelRatio = MediaQuery.devicePixelRatioOf(context);
@@ -190,6 +194,10 @@ class _MessageImageCarousel extends HookConsumerWidget {
                 height: _messageMediaCarouselHeight,
                 child: PageView.builder(
                   controller: controller,
+                  allowImplicitScrolling: true,
+                  // Keep the first image aligned with the message body, but
+                  // allow later pages to paint through the avatar gutter as
+                  // the row scrolls.
                   clipBehavior: Clip.none,
                   padEnds: false,
                   itemCount: items.length,
@@ -197,8 +205,9 @@ class _MessageImageCarousel extends HookConsumerWidget {
                   itemBuilder: (context, index) {
                     final item = items[index];
                     return Padding(
+                      key: ValueKey('message-media-carousel-page:${item.url}'),
                       padding: EdgeInsetsDirectional.only(
-                        end: index == items.length - 1 ? 0 : Grid.half,
+                        end: itemTrailingPaddings[index],
                       ),
                       child: Semantics(
                         button: true,
diff --git a/mobile/lib/features/channels/reaction_row.dart b/mobile/lib/features/channels/reaction_row.dart
index 2f2404ccf7..a9511c587d 100644
--- a/mobile/lib/features/channels/reaction_row.dart
+++ b/mobile/lib/features/channels/reaction_row.dart
@@ -1,15 +1,37 @@
 import 'package:flutter/material.dart';
 import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
+import 'package:lucide_icons_flutter/lucide_icons.dart';
 
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
 import '../../shared/custom_emoji/custom_emoji_render.dart';
+import '../../shared/emoji/emoji_burst.dart';
+import '../../shared/emoji/emoji_data_provider.dart';
+import '../../shared/emoji/positive_emoji.dart';
 import '../profile/user_cache_provider.dart';
 import '../profile/user_profile.dart';
 import 'channel_management_provider.dart';
+import 'emoji_picker.dart';
+import 'recent_emoji_provider.dart';
 import 'timeline_message.dart';
 
+/// Pill geometry, ported from desktop's `REACTION_PILL_BASE_CLASSES` in
+/// `desktop/src/features/messages/ui/MessageReactions.tsx`: a fully-rounded
+/// 28px pill with a fixed minimum width so a row of single-count reactions
+/// doesn't look ragged.
+const _pillHeight = 28.0;
+const _pillMinWidth = 48.0;
+const _pillGap = 6.0;
+
+/// The `+` pill is narrower than a reaction pill — desktop's `w-10` vs `min-w-12`.
+const _addPillWidth = 40.0;
+
+/// Glyph size inside a pill. Desktop uses 12px in a 28px pill; mobile steps that
+/// up because the app's base type is 15sp and a 12px glyph reads as a smudge at
+/// phone viewing distance.
+const _pillGlyphSize = 16.0;
+
 /// Toggle a reaction on [message]. If the current user already reacted with
 /// [emoji], removes the reaction; otherwise adds it.
 ///
@@ -21,22 +43,78 @@ void toggleReaction(WidgetRef ref, TimelineMessage message, String emoji) {
   if (reaction.reactedByCurrentUser && reaction.currentUserReactionId != null) {
     actions.removeReaction(reaction.currentUserReactionId!, emoji);
   } else {
+    // Only adding counts as a use — removing a reaction shouldn't promote the
+    // emoji in the frequently-used ranking.
+    ref.read(recentEmojiProvider.notifier).record(emoji);
     actions.addReaction(message.id, emoji);
   }
 }
 
+/// Arm a burst for a reaction that is about to be added from somewhere the pill
+/// doesn't exist yet — the quick-reaction row or the emoji picker.
+///
+/// Pill taps don't go through here: they burst immediately, because the pill is
+/// already on screen. Adding a reaction you already have is a no-op on the
+/// relay, so it shouldn't celebrate either.
+void armReactionBurst(WidgetRef ref, TimelineMessage message, String emoji) {
+  final alreadyReacted = message.reactions.any(
+    (reaction) => reaction.emoji == emoji && reaction.reactedByCurrentUser,
+  );
+  if (alreadyReacted) return;
+  ref.read(pendingReactionBurstProvider.notifier).arm(message.id, emoji);
+}
+
+/// Open the emoji picker and add whatever the user chooses as a reaction to
+/// [message].
+///
+/// Shared by the `+` pill in the channel timeline and in the thread view so the
+/// recency bookkeeping and burst arming can't drift apart between them.
+void showAddReactionPicker({
+  required BuildContext context,
+  required WidgetRef ref,
+  required TimelineMessage message,
+}) {
+  showEmojiPicker(
+    context: context,
+    onSelect: (emoji) {
+      ref.read(recentEmojiProvider.notifier).record(emoji);
+      armReactionBurst(ref, message, emoji);
+      ref.read(channelActionsProvider).addReaction(message.id, emoji);
+    },
+  );
+}
+
 class ReactionRow extends StatelessWidget {
+  /// The message these reactions belong to. Used to match a pending burst to
+  /// the right pill — the same emoji can be pending on a different message.
+  final String messageId;
+
   final List<TimelineReaction> reactions;
   final void Function(String emoji) onToggle;
 
+  /// Show a trailing `+` pill that opens the emoji picker, mirroring desktop's
+  /// `InlineReactionPicker`. Thread messages set this so reacting is always one
+  /// tap away; the channel timeline leaves it off to keep the list dense.
+  final bool showAddButton;
+
+  /// Invoked by the `+` pill. Required when [showAddButton] is set.
+  final VoidCallback? onAddReaction;
+
   const ReactionRow({
     super.key,
+    required this.messageId,
     required this.reactions,
     required this.onToggle,
+    this.showAddButton = false,
+    this.onAddReaction,
   });
 
   @override
   Widget build(BuildContext context) {
+    // With the add button on, an empty row still renders — that affordance is
+    // the point. Without it, an empty row would be dead space.
+    if (reactions.isEmpty && !showAddButton) return const SizedBox.shrink();
+
     return Padding(
       padding: const EdgeInsets.only(top: Grid.half),
       child: Wrap(
@@ -44,54 +122,177 @@ class ReactionRow extends StatelessWidget {
         runSpacing: Grid.half,
         children: [
           for (final reaction in reactions)
-            GestureDetector(
+            _ReactionPill(
+              messageId: messageId,
+              reaction: reaction,
               onTap: () => onToggle(reaction.emoji),
               onLongPress: () => showReactionDetailSheet(
                 context: context,
                 reactions: reactions,
                 initialEmoji: reaction.emoji,
               ),
-              child: Container(
-                padding: const EdgeInsets.symmetric(
-                  horizontal: Grid.xxs,
-                  vertical: Grid.quarter,
-                ),
-                decoration: BoxDecoration(
-                  color: reaction.reactedByCurrentUser
-                      ? context.colors.primary.withValues(alpha: 0.12)
-                      : context.colors.surfaceContainerHighest,
-                  borderRadius: BorderRadius.circular(Radii.lg),
-                  border: Border.all(
-                    color: reaction.reactedByCurrentUser
-                        ? context.colors.primary.withValues(alpha: 0.4)
-                        : context.colors.outlineVariant,
-                  ),
-                ),
-                child: Row(
-                  mainAxisSize: MainAxisSize.min,
-                  children: [
-                    _ReactionEmoji(reaction: reaction, size: 18),
-                    if (reaction.count > 1) ...[
-                      const SizedBox(width: Grid.quarter),
-                      Text(
-                        '${reaction.count}',
-                        style: reactionCountTextStyle.copyWith(
-                          color: reaction.reactedByCurrentUser
-                              ? context.colors.primary
-                              : context.colors.onSurfaceVariant,
-                        ),
-                      ),
-                    ],
-                  ],
-                ),
-              ),
             ),
+          if (showAddButton && onAddReaction != null)
+            _AddReactionPill(onTap: onAddReaction!),
         ],
       ),
     );
   }
 }
 
+/// Shared pill chrome so the reaction pills and the `+` pill can't drift.
+class _PillSurface extends StatelessWidget {
+  final bool highlighted;
+  final double minWidth;
+  final Widget child;
+
+  const _PillSurface({
+    required this.highlighted,
+    required this.minWidth,
+    required this.child,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final colors = context.colors;
+    return Container(
+      height: _pillHeight,
+      // No `alignment:` — it wraps the child in an expanding Align, which makes
+      // every pill fill the Wrap's full width and stack one per line.
+      // Children center themselves instead.
+      constraints: BoxConstraints(minWidth: minWidth),
+      padding: const EdgeInsets.symmetric(horizontal: Grid.xxs),
+      decoration: BoxDecoration(
+        color: highlighted
+            ? colors.primary.withValues(alpha: 0.10)
+            : colors.surfaceContainerHighest,
+        borderRadius: BorderRadius.circular(_pillHeight / 2),
+        border: Border.all(
+          color: highlighted
+              ? colors.primary.withValues(alpha: 0.40)
+              : colors.outlineVariant,
+        ),
+      ),
+      child: child,
+    );
+  }
+}
+
+class _ReactionPill extends HookConsumerWidget {
+  final String messageId;
+  final TimelineReaction reaction;
+  final VoidCallback onTap;
+  final VoidCallback onLongPress;
+
+  const _ReactionPill({
+    required this.messageId,
+    required this.reaction,
+    required this.onTap,
+    required this.onLongPress,
+  });
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final reacted = reaction.reactedByCurrentUser;
+
+    // Fire a burst armed elsewhere (quick-reaction row, emoji picker) now that
+    // the pill it belongs to is finally on screen. Keyed on [reacted] rather
+    // than watching the provider: watching would rebuild every pill in the
+    // timeline each time a burst is armed or claimed, and the only moments that
+    // matter are this pill's first build and the frame our own reaction lands.
+    useEffect(() {
+      if (!reacted) return null;
+      final target = PendingReactionBurst(
+        messageId: messageId,
+        emoji: reaction.emoji,
+      );
+      if (ref.read(pendingReactionBurstProvider) != target) return null;
+      // Post-frame so the pill has been laid out and can report its centre.
+      WidgetsBinding.instance.addPostFrameCallback((_) {
+        if (!context.mounted) return;
+        // The same message is mounted on two routes at once when a thread is
+        // pushed over its channel, and the channel's copy builds first. Without
+        // this the channel pill claims the burst and it only becomes visible
+        // after popping back — the burst has to play where the user is looking.
+        final route = ModalRoute.of(context);
+        if (route != null && !route.isCurrent) return;
+        if (!ref.read(pendingReactionBurstProvider.notifier).claim(target)) {
+          return;
+        }
+        burstEmojiFromContext(ref, context, reaction.emoji);
+      });
+      return null;
+    }, [reacted, messageId, reaction.emoji]);
+
+    return GestureDetector(
+      key: ValueKey('reaction-pill-${reaction.emoji}'),
+      onTap: () {
+        // The pill is already here, so burst straight away rather than waiting
+        // for the relay echo — desktop does the same on a pill click.
+        if (!reacted && isPositiveEmojiParticle(reaction.emoji)) {
+          burstEmojiFromContext(ref, context, reaction.emoji);
+        }
+        onTap();
+      },
+      onLongPress: onLongPress,
+      child: _PillSurface(
+        highlighted: reacted,
+        minWidth: _pillMinWidth,
+        child: Row(
+          mainAxisSize: MainAxisSize.min,
+          // Centered so a short reaction sits mid-pill once the min width kicks
+          // in rather than hugging the left edge.
+          mainAxisAlignment: MainAxisAlignment.center,
+          children: [
+            _ReactionEmoji(reaction: reaction, size: _pillGlyphSize),
+            const SizedBox(width: _pillGap),
+            // Desktop shows the count even at 1; hiding it made a fresh
+            // reaction jump in width the moment a second person joined.
+            Text(
+              '${reaction.count}',
+              style: reactionCountTextStyle.copyWith(
+                color: reacted
+                    ? context.colors.primary
+                    : context.colors.onSurfaceVariant,
+              ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+
+class _AddReactionPill extends StatelessWidget {
+  final VoidCallback onTap;
+
+  const _AddReactionPill({required this.onTap});
+
+  @override
+  Widget build(BuildContext context) {
+    return Semantics(
+      button: true,
+      label: 'Add reaction',
+      child: GestureDetector(
+        key: const ValueKey('add-reaction-pill'),
+        onTap: onTap,
+        child: _PillSurface(
+          highlighted: false,
+          minWidth: _addPillWidth,
+          child: Center(
+            widthFactor: 1,
+            child: Icon(
+              LucideIcons.smilePlus,
+              size: _pillGlyphSize,
+              color: context.colors.onSurfaceVariant,
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}
+
 class _ReactionEmoji extends StatelessWidget {
   final TimelineReaction reaction;
   final double size;
@@ -202,9 +403,12 @@ class _ReactionDetailSheet extends HookConsumerWidget {
                 _ReactionEmoji(reaction: currentReaction, size: 32),
                 const SizedBox(width: Grid.half),
                 Text(
-                  currentReaction.emoji.startsWith(':')
-                      ? currentReaction.emoji
-                      : ':${_emojiToShortcode(currentReaction.emoji)}:',
+                  // Resolved from the shared emoji-mart dataset, so this name
+                  // matches desktop's `emojiDisplayName` for the whole set
+                  // rather than the 28 glyphs a hardcoded map used to cover.
+                  ref
+                      .watch(emojiDatasetOrEmptyProvider)
+                      .displayName(currentReaction.emoji),
                   style: context.textTheme.titleSmall?.copyWith(
                     color: context.colors.onSurfaceVariant,
                   ),
@@ -294,37 +498,3 @@ class _ReactorAvatar extends StatelessWidget {
     );
   }
 }
-
-String _emojiToShortcode(String emoji) {
-  const map = <String, String>{
-    '👍': 'thumbsup',
-    '👎': 'thumbsdown',
-    '❤️': 'heart',
-    '🎉': 'tada',
-    '😂': 'joy',
-    '😢': 'cry',
-    '😮': 'open_mouth',
-    '🔥': 'fire',
-    '👀': 'eyes',
-    '🚀': 'rocket',
-    '💯': '100',
-    '👏': 'clap',
-    '🙏': 'pray',
-    '💬': 'speech_balloon',
-    '✅': 'white_check_mark',
-    '❌': 'x',
-    '⭐': 'star',
-    '🤔': 'thinking',
-    '😄': 'smile',
-    '😎': 'sunglasses',
-    '🤣': 'rofl',
-    '😍': 'heart_eyes',
-    '🥳': 'partying_face',
-    '👋': 'wave',
-    '💪': 'muscle',
-    '🙌': 'raised_hands',
-    '😅': 'sweat_smile',
-    '🫡': 'saluting_face',
-  };
-  return map[emoji] ?? 'emoji';
-}
diff --git a/mobile/lib/features/channels/recent_emoji_provider.dart b/mobile/lib/features/channels/recent_emoji_provider.dart
new file mode 100644
index 0000000000..088dcd3b2a
--- /dev/null
+++ b/mobile/lib/features/channels/recent_emoji_provider.dart
@@ -0,0 +1,189 @@
+import 'dart:convert';
+
+import 'package:hooks_riverpod/hooks_riverpod.dart';
+
+import '../../shared/relay/relay.dart';
+import '../../shared/theme/theme_provider.dart';
+
+/// Frequently-used emoji, ranked and persisted.
+///
+/// Mirrors desktop's `useQuickReactionEmojis` (`desktop/src/features/messages/
+/// ui/useQuickReactionEmojis.ts`): rank by use count, break ties by recency,
+/// cap the stored set. Same storage key shape, so the two clients describe the
+/// same concept even though the stores are per-device.
+///
+/// Persistence is namespaced by community (relay) and account pubkey, matching
+/// `ComposeDraftsNotifier` — reaction history is user behaviour and must not
+/// leak across an in-place community or account switch.
+const _recentEmojiPrefsKey = 'buzz.quick-reaction-emojis.v1';
+
+/// Desktop's `DEFAULT_QUICK_REACTIONS`, used until the user has reacted enough
+/// to fill the row.
+const defaultQuickEmojis = <String>[
+  '\u{1F44D}',
+  '\u{2764}\u{FE0F}',
+  '\u{1F602}',
+  '\u{1F389}',
+];
+
+/// Desktop's `MAX_STORED_REACTIONS`.
+const _maxStoredEmoji = 24;
+
+/// One persisted frequently-used emoji ranking entry.
+///
+/// [emoji] is the Unicode glyph or custom shortcode, [count] is how many times
+/// it has been selected, and [lastUsedAt] is the most recent selection time in
+/// milliseconds since the Unix epoch.
+class RecentEmojiEntry {
+  /// The Unicode glyph or `:shortcode:` value that was selected.
+  final String emoji;
+
+  /// Number of recorded selections for [emoji].
+  final int count;
+
+  /// Most recent selection time in milliseconds since the Unix epoch.
+  final int lastUsedAt;
+
+  /// Creates a persisted ranking entry for [emoji].
+  const RecentEmojiEntry({
+    required this.emoji,
+    required this.count,
+    required this.lastUsedAt,
+  });
+
+  Map<String, dynamic> toJson() => {
+    'emoji': emoji,
+    'count': count,
+    'lastUsedAt': lastUsedAt,
+  };
+
+  /// Returns null for anything malformed, so one bad record can't poison the
+  /// whole list.
+  static RecentEmojiEntry? fromJson(dynamic raw) {
+    if (raw is! Map) return null;
+    final emoji = raw['emoji'];
+    if (emoji is! String || emoji.trim().isEmpty) return null;
+    final count = raw['count'];
+    final lastUsedAt = raw['lastUsedAt'];
+    return RecentEmojiEntry(
+      emoji: emoji,
+      count: count is int && count > 0 ? count : 1,
+      lastUsedAt: lastUsedAt is int && lastUsedAt > 0 ? lastUsedAt : 0,
+    );
+  }
+}
+
+/// Sort by count desc, then most-recent-first — desktop's `sortEntries`.
+List<RecentEmojiEntry> sortRecentEmoji(List<RecentEmojiEntry> entries) {
+  final sorted = [...entries];
+  sorted.sort((left, right) {
+    final byCount = right.count - left.count;
+    if (byCount != 0) return byCount;
+    return right.lastUsedAt - left.lastUsedAt;
+  });
+  return sorted;
+}
+
+/// Record [emoji] against [entries], returning the new capped, sorted list.
+/// Pure so it can be tested without SharedPreferences.
+List<RecentEmojiEntry> recordRecentEmoji(
+  List<RecentEmojiEntry> entries,
+  String emoji, {
+  required int now,
+}) {
+  if (emoji.trim().isEmpty) return entries;
+  final next = <RecentEmojiEntry>[];
+  var matched = false;
+  for (final entry in entries) {
+    if (entry.emoji == emoji) {
+      matched = true;
+      next.add(
+        RecentEmojiEntry(emoji: emoji, count: entry.count + 1, lastUsedAt: now),
+      );
+    } else {
+      next.add(entry);
+    }
+  }
+  if (!matched) {
+    next.add(RecentEmojiEntry(emoji: emoji, count: 1, lastUsedAt: now));
+  }
+  final sorted = sortRecentEmoji(next);
+  return sorted.length <= _maxStoredEmoji
+      ? sorted
+      : sorted.sublist(0, _maxStoredEmoji);
+}
+
+class RecentEmojiNotifier extends Notifier<List<RecentEmojiEntry>> {
+  late String _prefsKey;
+
+  @override
+  List<RecentEmojiEntry> build() {
+    final config = ref.watch(relayConfigProvider);
+    final pubkey = ref.watch(myPubkeyProvider) ?? 'anon';
+    _prefsKey = '$_recentEmojiPrefsKey:${config.baseUrl}:$pubkey';
+
+    final raw = ref.read(savedPrefsProvider).getString(_prefsKey);
+    if (raw == null || raw.isEmpty) return const [];
+    try {
+      final decoded = jsonDecode(raw);
+      if (decoded is! List) return const [];
+      return sortRecentEmoji(
+        decoded.map(RecentEmojiEntry.fromJson).nonNulls.toList(),
+      );
+    } catch (_) {
+      return const [];
+    }
+  }
+
+  /// Record one use of [emoji]. Called from every place a user picks an emoji:
+  /// the picker, the quick-reaction row, and toggling an existing pill on.
+  void record(String emoji) {
+    final next = recordRecentEmoji(
+      state,
+      emoji,
+      now: DateTime.now().millisecondsSinceEpoch,
+    );
+    if (identical(next, state)) return;
+    state = next;
+    ref
+        .read(savedPrefsProvider)
+        .setString(
+          _prefsKey,
+          jsonEncode(next.map((entry) => entry.toJson()).toList()),
+        );
+  }
+}
+
+final recentEmojiProvider =
+    NotifierProvider<RecentEmojiNotifier, List<RecentEmojiEntry>>(
+      RecentEmojiNotifier.new,
+    );
+
+/// The top [limit] emoji for a quick-reaction row, topped up with
+/// [defaultQuickEmojis] so the row is never short. Custom-emoji shortcodes are
+/// dropped when they are no longer in the community palette — desktop's
+/// `canRenderQuickReactionEmoji` guard, which stops a removed custom emoji from
+/// rendering as literal `:shortcode:` text.
+List<String> quickReactionEmoji(
+  List<RecentEmojiEntry> entries, {
+  required Set<String> customShortcodes,
+  int limit = 4,
+}) {
+  final result = <String>[];
+  void add(String emoji) {
+    if (result.length >= limit || result.contains(emoji)) return;
+    if (emoji.startsWith(':') && emoji.endsWith(':')) {
+      final shortcode = emoji.substring(1, emoji.length - 1).toLowerCase();
+      if (!customShortcodes.contains(shortcode)) return;
+    }
+    result.add(emoji);
+  }
+
+  for (final entry in entries) {
+    add(entry.emoji);
+  }
+  for (final emoji in defaultQuickEmojis) {
+    add(emoji);
+  }
+  return result;
+}
diff --git a/mobile/lib/features/channels/thread_detail_page.dart b/mobile/lib/features/channels/thread_detail_page.dart
index a6d75a9f05..810861aa00 100644
--- a/mobile/lib/features/channels/thread_detail_page.dart
+++ b/mobile/lib/features/channels/thread_detail_page.dart
@@ -3,15 +3,20 @@ import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:scrollable_positioned_list/scrollable_positioned_list.dart';
 
+import '../../shared/mentions/agent_identity_provider.dart';
+import '../../shared/relay/relay.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
 import '../../shared/widgets/frosted_app_bar.dart';
 import '../../shared/widgets/frosted_scaffold.dart';
+import '../../shared/widgets/keyboard_dismiss_on_drag.dart';
 import '../../shared/widgets/message_author_meta.dart';
 import '../profile/user_cache_provider.dart';
 import '../profile/user_profile.dart';
 import 'channel_link_navigation.dart';
+import 'channel_messages_provider.dart';
 import 'channel_typing_provider.dart';
+import 'channel_typing_indicator.dart';
 import 'thread_replies_provider.dart';
 import 'channels_provider.dart';
 import 'compose_bar.dart';
@@ -20,7 +25,6 @@ import 'day_divider.dart';
 import '../profile/user_profile_sheet.dart';
 import 'message_actions.dart';
 import 'message_content.dart';
-import 'mentions/mention_candidates_provider.dart';
 import 'reaction_row.dart';
 import 'read_state/read_state_format.dart';
 import 'read_state/read_state_provider.dart';
@@ -63,16 +67,37 @@ class ThreadDetailPage extends HookConsumerWidget {
         ThreadRepliesArgs(channelId: channelId, rootId: queryRootId),
       ),
     );
+    // The thread query is one-shot and asks only for content kinds, so a
+    // reaction, edit, or deletion that lands while the thread is open never
+    // reaches it — a new pill (and its burst) only showed up after leaving and
+    // re-entering, which refetched. The channel socket already receives those
+    // events, so union the two sources and format once.
+    final liveChannelEvents =
+        ref.watch(channelMessagesProvider(channelId)).value ??
+        const <NostrEvent>[];
     final replyMessages = repliesState.whenData((events) {
-      return formatTimeline(events, currentPubkey: currentPubkey);
+      return formatTimeline(
+        mergeThreadEvents(events, liveChannelEvents),
+        currentPubkey: currentPubkey,
+      );
     });
 
     final fetchedReplies = replyMessages.value;
+    final liveDeletionHidesHead = _isDeletedBy(
+      liveChannelEvents,
+      threadHead.id,
+    );
     final allMsgs = fetchedReplies == null
         ? allMessages
         : [
-            threadHead,
-            ...fetchedReplies.where((message) => message.id != threadHead.id),
+            // Only fall back to the pushed-route snapshot when neither source
+            // carries the head, and no live deletion has suppressed it. That
+            // keeps a temporarily unavailable head visible without restoring
+            // a head that was deleted while this page was open.
+            if (!liveDeletionHidesHead &&
+                !fetchedReplies.any((message) => message.id == threadHead.id))
+              threadHead,
+            ...fetchedReplies,
           ];
 
     // Index all messages by parentId so we can find direct children of any
@@ -86,7 +111,13 @@ class ThreadDetailPage extends HookConsumerWidget {
 
     final replies = childrenByParent[threadHead.id] ?? const [];
     final itemScrollController = useMemoized(ItemScrollController.new);
+    final itemPositionsListener = useMemoized(ItemPositionsListener.create);
     final didJumpToInitialMessage = useRef(false);
+
+    // Item 0 is the thread head; reply `i` lives at `i + 1`.
+    const headIndex = 0;
+    int indexForReply(int chronologicalIndex) => chronologicalIndex + 1;
+
     useEffect(() {
       final messageId = initialMessageId;
       // Wait for the authoritative thread query before consuming the one-shot
@@ -96,10 +127,10 @@ class ThreadDetailPage extends HookConsumerWidget {
         (reply) => reply.id == messageId,
       );
       final targetIndex = messageId == threadHead.id
-          ? replies.length
+          ? headIndex
           : chronologicalIndex < 0
           ? null
-          : replies.length - 1 - chronologicalIndex;
+          : indexForReply(chronologicalIndex);
       if (targetIndex == null || didJumpToInitialMessage.value) return null;
       WidgetsBinding.instance.addPostFrameCallback((_) {
         if (!context.mounted || !itemScrollController.isAttached) return;
@@ -108,6 +139,58 @@ class ThreadDetailPage extends HookConsumerWidget {
       });
       return null;
     }, [initialMessageId, fetchedReplies, replies.length]);
+
+    // A top-anchored list doesn't stick to the newest item the way the old
+    // reversed one did, so follow the tail explicitly: when a reply arrives
+    // while the last item is on screen, scroll it into view. If the user has
+    // scrolled up to read, leave them where they are.
+    final hasFetchedReplies = fetchedReplies != null;
+    final didEstablishInitialReplies = useRef(hasFetchedReplies);
+    final previousReplyCount = useRef(replies.length);
+    useEffect(() {
+      // The first authoritative query result is hydration, not a live arrival.
+      // Establish the baseline without moving the user away from the head.
+      if (!hasFetchedReplies) return null;
+      if (!didEstablishInitialReplies.value) {
+        didEstablishInitialReplies.value = true;
+        previousReplyCount.value = replies.length;
+        return null;
+      }
+
+      final previous = previousReplyCount.value;
+      previousReplyCount.value = replies.length;
+      if (replies.length <= previous) return null;
+      final positions = itemPositionsListener.itemPositions.value;
+      final lastIndex = indexForReply(replies.length - 1);
+      // Positions still describe the list as it was *before* these replies, so
+      // compare against the old tail. Measuring against the new one only reads
+      // as "at the tail" when exactly one reply arrived.
+      final previousLastIndex = previous == 0
+          ? headIndex
+          : indexForReply(previous - 1);
+      final wasAtTail =
+          positions.isEmpty ||
+          positions.any((position) => position.index >= previousLastIndex);
+      final localPubkey = currentPubkey?.toLowerCase();
+      final hasNewLocalReply =
+          localPubkey != null &&
+          replies
+              .skip(previous)
+              .any((reply) => reply.pubkey.toLowerCase() == localPubkey);
+      // A reply the current user just sent must be visible even if they were
+      // reading at the head of a long thread. Remote arrivals still respect
+      // the user's scroll position.
+      if (!wasAtTail && !hasNewLocalReply) return null;
+      WidgetsBinding.instance.addPostFrameCallback((_) {
+        if (!context.mounted || !itemScrollController.isAttached) return;
+        itemScrollController.scrollTo(
+          index: lastIndex,
+          duration: const Duration(milliseconds: 220),
+          curve: Curves.easeOutCubic,
+        );
+      });
+      return null;
+    }, [hasFetchedReplies, replies.length]);
     final readState = ref.watch(readStateProvider);
     final visibleReplyReadKey = replies
         .map((reply) => '${reply.id}:${reply.createdAt}')
@@ -161,127 +244,152 @@ class ThreadDetailPage extends HookConsumerWidget {
       body: Column(
         children: [
           Expanded(
-            child: ScrollablePositionedList.builder(
-              key: const ValueKey('thread-message-list'),
-              itemScrollController: itemScrollController,
-              // Reversed so the list opens pinned to the newest reply,
-              // matching the channel message list.
-              reverse: true,
-              padding: EdgeInsets.only(
-                left: Grid.gutter,
-                right: Grid.gutter,
-                top: frostedAppBarHeight(context),
-                bottom: 0,
-              ),
-              itemCount: replies.length + 1, // +1 for thread head
-              itemBuilder: (context, index) {
-                if (index == replies.length) {
-                  // Thread head.
+            child: KeyboardDismissOnDrag(
+              child: ScrollablePositionedList.builder(
+                key: const ValueKey('thread-message-list'),
+                itemScrollController: itemScrollController,
+                itemPositionsListener: itemPositionsListener,
+                // Top-anchored, head first, replies flowing down — matching
+                // desktop's thread panel. The old reversed list bottom-anchored
+                // the content, which jammed the head against the composer
+                // whenever a thread had only a handful of replies.
+                padding: EdgeInsets.only(
+                  left: Grid.gutter,
+                  right: Grid.gutter,
+                  top: frostedAppBarHeight(context),
+                  bottom: Grid.xs,
+                ),
+                itemCount: replies.length + 1, // +1 for thread head
+                itemBuilder: (context, index) {
+                  if (index == headIndex) {
+                    if (liveDeletionHidesHead) {
+                      return const Padding(
+                        key: ValueKey('thread-message-deleted'),
+                        padding: EdgeInsets.only(bottom: Grid.xs),
+                        child: Text('This message was deleted'),
+                      );
+                    }
+                    return Padding(
+                      key: ValueKey('thread-message-group-${liveHead.id}'),
+                      padding: const EdgeInsets.only(bottom: Grid.xs),
+                      child: Column(
+                        crossAxisAlignment: CrossAxisAlignment.start,
+                        children: [
+                          DayDivider(
+                            label: formatDayHeading(liveHead.createdAt),
+                          ),
+                          _ThreadMessage(
+                            message: liveHead,
+                            channelNames: channelNamesMap,
+                            channelId: channelId,
+                            currentPubkey: currentPubkey,
+                            showAuthor: true,
+                            isHighlighted: liveHead.id == initialMessageId,
+                            allMessages: allMsgs,
+                            isMember: isMember,
+                            isArchived: isArchived,
+                            isThreadHead: true,
+                          ),
+                          Padding(
+                            padding: const EdgeInsets.symmetric(
+                              vertical: Grid.xxs,
+                            ),
+                            child: Row(
+                              children: [
+                                Text(
+                                  '${replies.length} ${replies.length == 1 ? 'reply' : 'replies'}',
+                                  style: context.textTheme.labelMedium
+                                      ?.copyWith(
+                                        color: context.colors.onSurfaceVariant,
+                                        fontWeight: FontWeight.w600,
+                                      ),
+                                ),
+                                const SizedBox(width: Grid.xxs),
+                                Expanded(
+                                  child: Divider(
+                                    color: context.colors.outlineVariant,
+                                  ),
+                                ),
+                              ],
+                            ),
+                          ),
+                        ],
+                      ),
+                    );
+                  }
+
+                  // Chronological list: index 1 = oldest reply.
+                  final chronIdx = index - 1;
+                  final reply = replies[chronIdx];
+                  final prevReply = chronIdx > 0 ? replies[chronIdx - 1] : null;
+                  final previousMessage = prevReply ?? liveHead;
+                  final showDayDivider = !isSameDay(
+                    previousMessage.createdAt,
+                    reply.createdAt,
+                  );
+                  final showAuthor =
+                      prevReply == null ||
+                      showDayDivider ||
+                      prevReply.pubkey.toLowerCase() !=
+                          reply.pubkey.toLowerCase() ||
+                      (reply.createdAt - prevReply.createdAt) > 300;
+
+                  // Check if this reply itself has children (nested thread).
+                  final nestedChildren = childrenByParent[reply.id];
+                  final nestedSummary =
+                      nestedChildren != null && nestedChildren.isNotEmpty
+                      ? _buildNestedSummary(reply.id, nestedChildren)
+                      : null;
+
                   return Padding(
-                    key: ValueKey('thread-message-group-${liveHead.id}'),
-                    padding: EdgeInsets.only(bottom: index == 0 ? Grid.xs : 0),
+                    key: ValueKey('thread-message-group-${reply.id}'),
+                    // Tail spacing comes from the list's own bottom padding now
+                    // that the list runs top-down; the reversed list used to
+                    // need it here because item 0 sat against the composer.
+                    padding: EdgeInsets.zero,
                     child: Column(
                       crossAxisAlignment: CrossAxisAlignment.start,
                       children: [
-                        DayDivider(label: formatDayHeading(liveHead.createdAt)),
+                        if (showDayDivider)
+                          DayDivider(label: formatDayHeading(reply.createdAt)),
                         _ThreadMessage(
-                          message: liveHead,
+                          message: reply,
                           channelNames: channelNamesMap,
                           channelId: channelId,
                           currentPubkey: currentPubkey,
-                          showAuthor: true,
-                          isHighlighted: liveHead.id == initialMessageId,
+                          showAuthor: showAuthor,
+                          isHighlighted: reply.id == initialMessageId,
                           allMessages: allMsgs,
                           isMember: isMember,
                           isArchived: isArchived,
                         ),
-                        Padding(
-                          padding: const EdgeInsets.symmetric(
-                            vertical: Grid.xxs,
+                        if (nestedSummary != null)
+                          _NestedThreadSummaryRow(
+                            summary: nestedSummary,
+                            replyMessage: reply,
+                            allMessages: allMsgs,
+                            channelId: channelId,
+                            currentPubkey: currentPubkey,
+                            isMember: isMember,
+                            isArchived: isArchived,
                           ),
-                          child: Row(
-                            children: [
-                              Text(
-                                '${replies.length} ${replies.length == 1 ? 'reply' : 'replies'}',
-                                style: context.textTheme.labelMedium?.copyWith(
-                                  color: context.colors.onSurfaceVariant,
-                                  fontWeight: FontWeight.w600,
-                                ),
-                              ),
-                              const SizedBox(width: Grid.xxs),
-                              Expanded(
-                                child: Divider(
-                                  color: context.colors.outlineVariant,
-                                ),
-                              ),
-                            ],
-                          ),
-                        ),
                       ],
                     ),
                   );
-                }
-
-                // Reversed list: index 0 = newest reply.
-                final chronIdx = replies.length - 1 - index;
-                final reply = replies[chronIdx];
-                final prevReply = chronIdx > 0 ? replies[chronIdx - 1] : null;
-                final previousMessage = prevReply ?? liveHead;
-                final showDayDivider = !isSameDay(
-                  previousMessage.createdAt,
-                  reply.createdAt,
-                );
-                final showAuthor =
-                    prevReply == null ||
-                    showDayDivider ||
-                    prevReply.pubkey.toLowerCase() !=
-                        reply.pubkey.toLowerCase() ||
-                    (reply.createdAt - prevReply.createdAt) > 300;
-
-                // Check if this reply itself has children (nested thread).
-                final nestedChildren = childrenByParent[reply.id];
-                final nestedSummary =
-                    nestedChildren != null && nestedChildren.isNotEmpty
-                    ? _buildNestedSummary(reply.id, nestedChildren)
-                    : null;
-
-                return Padding(
-                  key: ValueKey('thread-message-group-${reply.id}'),
-                  padding: EdgeInsets.only(bottom: index == 0 ? Grid.xs : 0),
-                  child: Column(
-                    crossAxisAlignment: CrossAxisAlignment.start,
-                    children: [
-                      if (showDayDivider)
-                        DayDivider(label: formatDayHeading(reply.createdAt)),
-                      _ThreadMessage(
-                        message: reply,
-                        channelNames: channelNamesMap,
-                        channelId: channelId,
-                        currentPubkey: currentPubkey,
-                        showAuthor: showAuthor,
-                        isHighlighted: reply.id == initialMessageId,
-                        allMessages: allMsgs,
-                        isMember: isMember,
-                        isArchived: isArchived,
-                      ),
-                      if (nestedSummary != null)
-                        _NestedThreadSummaryRow(
-                          summary: nestedSummary,
-                          replyMessage: reply,
-                          allMessages: allMsgs,
-                          channelId: channelId,
-                          currentPubkey: currentPubkey,
-                          isMember: isMember,
-                          isArchived: isArchived,
-                        ),
-                    ],
-                  ),
-                );
-              },
+                },
+              ),
             ),
           ),
-          if (threadTyping.isNotEmpty)
-            _ThreadTypingIndicator(entries: threadTyping),
+          AnimatedSize(
+            duration: MediaQuery.disableAnimationsOf(context)
+                ? Duration.zero
+                : const Duration(milliseconds: 180),
+            curve: Curves.easeOutCubic,
+            alignment: Alignment.bottomCenter,
+            child: threadTyping.isEmpty
+                ? const SizedBox.shrink()
+                : ChannelTypingIndicator(entries: threadTyping),
+          ),
           if (isMember && !isArchived)
             ComposeBar(
               channelId: channelId,
@@ -310,6 +418,21 @@ class ThreadDetailPage extends HookConsumerWidget {
   }
 }
 
+bool _isDeletedBy(Iterable<NostrEvent> events, String messageId) {
+  for (final event in events) {
+    if (event.kind != EventKind.deletion &&
+        event.kind != EventKind.nip29DeleteEvent) {
+      continue;
+    }
+    if (event.tags.any(
+      (tag) => tag.length >= 2 && tag[0] == 'e' && tag[1] == messageId,
+    )) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /// Build a lightweight summary for a nested thread (reply that has its own
 /// replies). Same logic as the top-level [ThreadSummary] but kept local to
 /// avoid coupling.
@@ -454,6 +577,10 @@ class _ThreadMessage extends ConsumerWidget {
   final bool isMember;
   final bool isArchived;
 
+  /// Whether this is the message the thread hangs off, which keeps a standing
+  /// "+" where replies only get one once they carry a reaction.
+  final bool isThreadHead;
+
   const _ThreadMessage({
     required this.message,
     required this.channelNames,
@@ -464,6 +591,7 @@ class _ThreadMessage extends ConsumerWidget {
     this.allMessages,
     this.isMember = false,
     this.isArchived = false,
+    this.isThreadHead = false,
   });
 
   @override
@@ -479,7 +607,13 @@ class _ThreadMessage extends ConsumerWidget {
             profile?.ownerPubkey == currentPubkey?.toLowerCase());
 
     final userCache = ref.watch(userCacheProvider);
-    final knownAgentPubkeys = ref.watch(mentionAgentPubkeysProvider(channelId));
+    final knownAgentPubkeys = agentPubkeysWithProfileOwners(
+      knownAgentPubkeys: ref.watch(agentMentionPubkeysProvider(channelId)),
+      profileOwnedAgentPubkeys: [
+        for (final profile in userCache.values)
+          if (profile.ownerPubkey != null) profile.pubkey,
+      ],
+    );
     final mentionNames = <String, String>{};
     final agentMentionPubkeys = <String>{};
     for (final mpk in message.mentionPubkeys) {
@@ -492,233 +626,192 @@ class _ThreadMessage extends ConsumerWidget {
         agentMentionPubkeys.add(normalizedPubkey);
       }
     }
+    final resolvedMentionNames = mentionNamesWithDirectoryLabels(
+      mentionPubkeys: message.mentionPubkeys,
+      profileMentionNames: mentionNames,
+      directoryDisplayNames: ref.watch(agentDirectoryDisplayNamesProvider),
+      agentMentionPubkeys: agentMentionPubkeys,
+    );
 
-    return DecoratedBox(
-      key: ValueKey('thread-message-${message.id}'),
-      decoration: BoxDecoration(
-        color: isHighlighted
-            ? context.colors.primary.withValues(alpha: 0.12)
-            : Colors.transparent,
-        borderRadius: BorderRadius.circular(Radii.md),
-      ),
-      child: Material(
-        color: Colors.transparent,
-        borderRadius: BorderRadius.circular(Radii.md),
-        clipBehavior: Clip.antiAlias,
-        child: InkWell(
-          key: ValueKey('thread-message-row-${message.id}'),
+    return Padding(
+      padding: EdgeInsets.only(top: showAuthor ? Grid.xs : 0),
+      child: DecoratedBox(
+        key: ValueKey('thread-message-${message.id}'),
+        decoration: BoxDecoration(
+          color: isHighlighted
+              ? context.colors.primary.withValues(alpha: 0.12)
+              : Colors.transparent,
           borderRadius: BorderRadius.circular(Radii.md),
-          highlightColor: context.colors.primary.withValues(alpha: 0.1),
-          onLongPress: () => showMessageActions(
-            context: context,
-            ref: ref,
-            message: message,
-            channelId: channelId,
-            canManageMessage: canManageMessage,
-            allMessages: allMessages,
-            currentPubkey: currentPubkey,
-            isMember: isMember,
-            isArchived: isArchived,
-          ),
-          child: Padding(
-            padding: EdgeInsets.only(
-              top: showAuthor ? Grid.xs : Grid.xxs,
-              bottom: showAuthor ? 0 : Grid.xxs,
+        ),
+        child: Material(
+          color: Colors.transparent,
+          borderRadius: BorderRadius.circular(Radii.md),
+          // The media carousel intentionally continues through the list's
+          // trailing gutter. InkWell still clips its ink to [borderRadius],
+          // while leaving overflowing message content visible.
+          clipBehavior: Clip.none,
+          child: InkWell(
+            key: ValueKey('thread-message-row-${message.id}'),
+            borderRadius: BorderRadius.circular(Radii.md),
+            highlightColor: context.colors.primary.withValues(alpha: 0.1),
+            onLongPress: () => showMessageActions(
+              context: context,
+              ref: ref,
+              message: message,
+              channelId: channelId,
+              canManageMessage: canManageMessage,
+              allMessages: allMessages,
+              currentPubkey: currentPubkey,
+              isMember: isMember,
+              isArchived: isArchived,
             ),
-            child: Row(
-              crossAxisAlignment: CrossAxisAlignment.start,
-              children: [
-                if (showAuthor)
-                  GestureDetector(
-                    onTap: () => showUserProfileSheet(context, message.pubkey),
-                    child: _Avatar(profile: profile, pubkey: message.pubkey),
-                  )
-                else
-                  const SizedBox(width: messageAvatarSize),
-                const SizedBox(width: messageAvatarContentGap),
-                Expanded(
-                  child: Transform.translate(
-                    offset: Offset(0, showAuthor ? -Grid.quarter : 0),
-                    child: Column(
-                      crossAxisAlignment: CrossAxisAlignment.start,
-                      children: [
-                        if (showAuthor)
-                          Padding(
-                            padding: const EdgeInsets.only(
-                              bottom: Grid.quarter,
-                            ),
-                            child: Row(
-                              children: [
-                                Expanded(
-                                  child: MessageAuthorMeta(
-                                    displayName: displayName,
-                                    username: messageUsernameLabel(profile),
-                                    timestamp: formatMessageTime(
-                                      message.createdAt,
-                                    ),
-                                    nameColor: context.colors.onSurface,
-                                    metadataColor:
-                                        context.colors.onSurfaceVariant,
-                                    onAuthorTap: () => showUserProfileSheet(
-                                      context,
-                                      message.pubkey,
-                                    ),
-                                    displayNameKey: ValueKey(
-                                      'thread-message-author-${message.id}',
-                                    ),
-                                    usernameKey: ValueKey(
-                                      'thread-message-username-${message.id}',
-                                    ),
-                                    timestampKey: ValueKey(
-                                      'thread-message-timestamp-${message.id}',
+            child: Padding(
+              padding: EdgeInsets.only(
+                top: showAuthor ? 0 : Grid.xxs,
+                bottom: showAuthor ? 0 : Grid.xxs,
+              ),
+              child: Row(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                children: [
+                  if (showAuthor)
+                    GestureDetector(
+                      onTap: () =>
+                          showUserProfileSheet(context, message.pubkey),
+                      child: _Avatar(profile: profile, pubkey: message.pubkey),
+                    )
+                  else
+                    const SizedBox(width: messageAvatarSize),
+                  const SizedBox(width: messageAvatarContentGap),
+                  Expanded(
+                    child: Padding(
+                      padding: EdgeInsets.only(top: showAuthor ? Grid.half : 0),
+                      child: Column(
+                        crossAxisAlignment: CrossAxisAlignment.start,
+                        children: [
+                          if (showAuthor)
+                            Padding(
+                              padding: const EdgeInsets.only(
+                                bottom: Grid.quarter,
+                              ),
+                              child: Row(
+                                children: [
+                                  Expanded(
+                                    child: MessageAuthorMeta(
+                                      displayName: displayName,
+                                      username: messageUsernameLabel(profile),
+                                      timestamp: formatMessageTime(
+                                        message.createdAt,
+                                      ),
+                                      nameColor: context.colors.onSurface,
+                                      metadataColor:
+                                          context.colors.onSurfaceVariant,
+                                      onAuthorTap: () => showUserProfileSheet(
+                                        context,
+                                        message.pubkey,
+                                      ),
+                                      displayNameKey: ValueKey(
+                                        'thread-message-author-${message.id}',
+                                      ),
+                                      usernameKey: ValueKey(
+                                        'thread-message-username-${message.id}',
+                                      ),
+                                      timestampKey: ValueKey(
+                                        'thread-message-timestamp-${message.id}',
+                                      ),
                                     ),
                                   ),
-                                ),
-                                if (message.edited) ...[
-                                  const SizedBox(width: Grid.half),
-                                  Text(
-                                    '(edited)',
-                                    style: context.textTheme.labelSmall
-                                        ?.copyWith(
-                                          color:
-                                              context.colors.onSurfaceVariant,
-                                          fontStyle: FontStyle.italic,
-                                        ),
-                                  ),
+                                  if (message.edited) ...[
+                                    const SizedBox(width: Grid.half),
+                                    Text(
+                                      '(edited)',
+                                      style: context.textTheme.labelSmall
+                                          ?.copyWith(
+                                            color:
+                                                context.colors.onSurfaceVariant,
+                                            fontStyle: FontStyle.italic,
+                                          ),
+                                    ),
+                                  ],
                                 ],
-                              ],
+                              ),
                             ),
-                          ),
-                        MessageContent(
-                          content: message.content,
-                          mentionNames: mentionNames,
-                          agentMentionPubkeys: agentMentionPubkeys,
-                          channelNames: channelNames,
-                          tags: message.tags,
-                          baseStyle: messageBodyTextStyle.copyWith(
-                            color: context.colors.onSurface,
-                          ),
-                          mediaCarouselTrailingOverflow: Grid.gutter,
-                          onMediaReply: allMessages == null
-                              ? null
-                              : () {
-                                  if (!context.mounted) return;
-                                  Navigator.of(context).push(
-                                    MaterialPageRoute<void>(
-                                      builder: (_) => ThreadDetailPage(
-                                        threadHead: message,
-                                        allMessages: allMessages!,
-                                        channelId: channelId,
-                                        currentPubkey: currentPubkey,
-                                        isMember: isMember,
-                                        isArchived: isArchived,
+                          MessageContent(
+                            content: message.content,
+                            mentionNames: resolvedMentionNames,
+                            agentMentionPubkeys: agentMentionPubkeys,
+                            channelNames: channelNames,
+                            tags: message.tags,
+                            baseStyle: messageBodyTextStyle.copyWith(
+                              color: context.colors.onSurface,
+                            ),
+                            scaleEmojiOnly: true,
+                            mediaCarouselTrailingOverflow: Grid.gutter,
+                            onMediaReply: allMessages == null
+                                ? null
+                                : () {
+                                    if (!context.mounted) return;
+                                    Navigator.of(context).push(
+                                      MaterialPageRoute<void>(
+                                        builder: (_) => ThreadDetailPage(
+                                          threadHead: message,
+                                          allMessages: allMessages!,
+                                          channelId: channelId,
+                                          currentPubkey: currentPubkey,
+                                          isMember: isMember,
+                                          isArchived: isArchived,
+                                        ),
                                       ),
-                                    ),
-                                  );
-                                },
-                          onMediaMore: (viewerContext, imageUrl) =>
-                              showImageActions(
-                                context: viewerContext,
+                                    );
+                                  },
+                            onMediaMore: (viewerContext, imageUrl) =>
+                                showImageActions(
+                                  context: viewerContext,
+                                  ref: ref,
+                                  message: message,
+                                  channelId: channelId,
+                                  imageUrl: imageUrl,
+                                  canManageMessage: canManageMessage,
+                                  onDeleted: () {
+                                    if (viewerContext.mounted) {
+                                      Navigator.of(viewerContext).maybePop();
+                                    }
+                                  },
+                                ),
+                            onChannelTap: (targetChannelId) {
+                              openChannelLink(
+                                context: context,
                                 ref: ref,
-                                message: message,
-                                channelId: channelId,
-                                imageUrl: imageUrl,
-                                canManageMessage: canManageMessage,
-                                onDeleted: () {
-                                  if (viewerContext.mounted) {
-                                    Navigator.of(viewerContext).maybePop();
-                                  }
-                                },
-                              ),
-                          onChannelTap: (targetChannelId) {
-                            openChannelLink(
-                              context: context,
-                              ref: ref,
-                              channelId: targetChannelId,
-                              currentChannelId: channelId,
-                            );
-                          },
-                          onMentionTap: (pubkey) =>
-                              showUserProfileSheet(context, pubkey),
-                        ),
-                        if (message.reactions.isNotEmpty)
+                                channelId: targetChannelId,
+                                currentChannelId: channelId,
+                              );
+                            },
+                            onMentionTap: (pubkey) =>
+                                showUserProfileSheet(context, pubkey),
+                          ),
                           ReactionRow(
+                            messageId: message.id,
                             reactions: message.reactions,
                             onToggle: (emoji) =>
                                 toggleReaction(ref, message, emoji),
+                            showAddButton:
+                                isMember &&
+                                !isArchived &&
+                                (isThreadHead || message.reactions.isNotEmpty),
+                            onAddReaction: () => showAddReactionPicker(
+                              context: context,
+                              ref: ref,
+                              message: message,
+                            ),
                           ),
-                      ],
-                    ),
-                  ),
-                ),
-              ],
-            ),
-          ),
-        ),
-      ),
-    );
-  }
-}
-
-class _ThreadTypingIndicator extends ConsumerWidget {
-  final List<TypingEntry> entries;
-
-  const _ThreadTypingIndicator({required this.entries});
-
-  @override
-  Widget build(BuildContext context, WidgetRef ref) {
-    final userCache = ref.watch(userCacheProvider);
-    final names = entries.map((e) {
-      final profile =
-          userCache[e.pubkey.toLowerCase()] ??
-          ref.read(userCacheProvider.notifier).get(e.pubkey.toLowerCase());
-      return profile?.label ?? shortPubkey(e.pubkey);
-    }).toList();
-    final text = switch (names.length) {
-      1 => '${names[0]} is typing...',
-      2 => '${names[0]} and ${names[1]} are typing...',
-      _ => '${names[0]} and ${names.length - 1} others are typing...',
-    };
-
-    final visibleEntries = entries.take(3).toList();
-    final avatarCount = visibleEntries.length;
-
-    return Container(
-      width: double.infinity,
-      padding: const EdgeInsets.symmetric(
-        horizontal: Grid.gutter,
-        vertical: Grid.quarter + 2,
-      ),
-      child: Row(
-        children: [
-          SizedBox(
-            width: 20.0 + (avatarCount - 1) * 12.0,
-            height: 20,
-            child: Stack(
-              children: [
-                for (var i = 0; i < avatarCount; i++)
-                  Positioned(
-                    left: i * 12.0,
-                    child: SmallAvatar(
-                      pubkey: visibleEntries[i].pubkey,
-                      userCache: userCache,
+                        ],
+                      ),
                     ),
                   ),
-              ],
-            ),
-          ),
-          const SizedBox(width: Grid.xxs),
-          Flexible(
-            child: Text(
-              text,
-              style: context.textTheme.labelSmall?.copyWith(
-                color: context.colors.outline,
-                fontStyle: FontStyle.italic,
+                ],
               ),
-              overflow: TextOverflow.ellipsis,
             ),
           ),
-        ],
+        ),
       ),
     );
   }
diff --git a/mobile/lib/features/channels/thread_replies_provider.dart b/mobile/lib/features/channels/thread_replies_provider.dart
index 6904ba8c5e..81ab5a4b39 100644
--- a/mobile/lib/features/channels/thread_replies_provider.dart
+++ b/mobile/lib/features/channels/thread_replies_provider.dart
@@ -128,6 +128,17 @@ final threadRepliesWithLocalProvider =
       );
     });
 
+/// Union two event lists by id, newest-wins, in timeline order.
+///
+/// The thread view needs this to fold the channel's live socket events into its
+/// own one-shot query result: the query asks for content kinds only, so
+/// reactions, edits, and deletions that land while a thread is open never reach
+/// it on their own.
+List<NostrEvent> mergeThreadEvents(
+  Iterable<NostrEvent> first,
+  Iterable<NostrEvent> second,
+) => _mergeReplies(first, second);
+
 List<NostrEvent> _mergeReplies(
   Iterable<NostrEvent> first,
   Iterable<NostrEvent> second,
diff --git a/mobile/lib/features/channels/timeline_message.dart b/mobile/lib/features/channels/timeline_message.dart
index 253c949703..c8fd96491b 100644
--- a/mobile/lib/features/channels/timeline_message.dart
+++ b/mobile/lib/features/channels/timeline_message.dart
@@ -101,9 +101,10 @@ class SystemEvent {
         final target = resolveLabel(targetPubkey);
         return '$actor removed $target from the channel';
       }(),
-      SystemEventType.topicChanged => '$actor changed the topic to "$topic"',
+      SystemEventType.topicChanged =>
+        '$actor ${_describeTextFieldChange('topic', topic)}',
       SystemEventType.purposeChanged =>
-        '$actor changed the purpose to "$purpose"',
+        '$actor ${_describeTextFieldChange('purpose', purpose)}',
       SystemEventType.channelCreated => '$actor created this channel',
       SystemEventType.channelArchived => '$actor archived this channel',
       SystemEventType.channelUnarchived => '$actor unarchived this channel',
@@ -113,6 +114,25 @@ class SystemEvent {
   }
 }
 
+/// Caption fragment for a channel topic or purpose change, e.g.
+/// `changed the topic to "Release planning"` or `cleared the topic`.
+///
+/// A blank value means the field was cleared: the relay reports a clear as a
+/// `topic_changed` / `purpose_changed` event carrying an empty string, not as a
+/// separate event type. Without this branch the timeline renders
+/// `changed the topic to ""`, which reads as if the topic were set to two quote
+/// marks. Whitespace-only values are treated as cleared for the same reason.
+///
+/// Mirrors `describeChannelTextFieldChange` in
+/// `desktop/src/features/messages/lib/systemEventCopy.ts`.
+String _describeTextFieldChange(String field, String? value) {
+  final trimmed = value?.trim();
+  if (trimmed == null || trimmed.isEmpty) {
+    return 'cleared the $field';
+  }
+  return 'changed the $field to "$trimmed"';
+}
+
 @immutable
 class TimelineReaction {
   final String emoji;
diff --git a/mobile/lib/features/forum/forum_post_card.dart b/mobile/lib/features/forum/forum_post_card.dart
index 8666919a4a..ddc36a1d4a 100644
--- a/mobile/lib/features/forum/forum_post_card.dart
+++ b/mobile/lib/features/forum/forum_post_card.dart
@@ -1,8 +1,10 @@
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
+import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
 
+import '../../shared/mentions/agent_identity_provider.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
 import '../channels/message_content.dart';
@@ -15,7 +17,7 @@ import 'forum_models.dart';
 ///
 /// Long-press opens an action sheet (copy, delete) matching the stream
 /// message pattern from channel_detail_page.dart.
-class ForumPostCard extends ConsumerWidget {
+class ForumPostCard extends HookConsumerWidget {
   final ForumPost post;
   final String? currentPubkey;
   final VoidCallback onTap;
@@ -31,16 +33,57 @@ class ForumPostCard extends ConsumerWidget {
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
+    final mentionPubkeys = useMemoized(
+      () =>
+          post.mentionPubkeys.map((pubkey) => pubkey.toLowerCase()).toSet()
+            ..remove(post.pubkey.toLowerCase()),
+      [post],
+    );
+    final mentionPubkeysKey = (mentionPubkeys.toList()..sort()).join('\u0000');
+
+    useEffect(() {
+      if (mentionPubkeys.isNotEmpty) {
+        ref.read(userCacheProvider.notifier).preload(mentionPubkeys.toList());
+      }
+      return null;
+    }, [mentionPubkeysKey]);
+
     final pk = post.pubkey.toLowerCase();
     final profile =
         ref.watch(userCacheProvider.select((cache) => cache[pk])) ??
         ref.read(userCacheProvider.notifier).get(pk);
     final displayName = profile?.label ?? _shortPubkey(post.pubkey);
-    final mentionNames = ref.watch(
+    final profileMentionNames = ref.watch(
       userCacheProvider.select(
         (cache) => _buildMentionNames(post.mentionPubkeys, cache),
       ),
     );
+    final profileOwnedMentionPubkeys = ref.watch(
+      userCacheProvider.select(
+        (cache) =>
+            (post.mentionPubkeys
+                    .where(
+                      (pubkey) =>
+                          cache[pubkey.toLowerCase()]?.ownerPubkey != null,
+                    )
+                    .map((pubkey) => pubkey.toLowerCase())
+                    .toList()
+                  ..sort())
+                .join('\u0000'),
+      ),
+    );
+    final agentMentionPubkeys = agentPubkeysWithProfileOwners(
+      knownAgentPubkeys: ref.watch(agentMentionPubkeysProvider(post.channelId)),
+      profileOwnedAgentPubkeys: profileOwnedMentionPubkeys.isEmpty
+          ? const <String>[]
+          : profileOwnedMentionPubkeys.split('\u0000'),
+    );
+    final mentionNames = mentionNamesWithDirectoryLabels(
+      mentionPubkeys: post.mentionPubkeys,
+      profileMentionNames: profileMentionNames,
+      directoryDisplayNames: ref.watch(agentDirectoryDisplayNamesProvider),
+      agentMentionPubkeys: agentMentionPubkeys,
+    );
     final preview = post.content.length > 200
         ? '${post.content.substring(0, 200)}...'
         : post.content;
@@ -128,6 +171,7 @@ class ForumPostCard extends ConsumerWidget {
                   child: MessageContent(
                     content: preview,
                     mentionNames: mentionNames,
+                    agentMentionPubkeys: agentMentionPubkeys,
                     tags: post.tags,
                     baseStyle: messageBodyTextStyle.copyWith(
                       color: context.colors.onSurface,
diff --git a/mobile/lib/features/forum/forum_thread_page.dart b/mobile/lib/features/forum/forum_thread_page.dart
index d2e8490d61..68d2562f68 100644
--- a/mobile/lib/features/forum/forum_thread_page.dart
+++ b/mobile/lib/features/forum/forum_thread_page.dart
@@ -6,6 +6,7 @@ import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
 
+import '../../shared/mentions/agent_identity_provider.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
 import '../../shared/widgets/buzz_loading_indicator.dart';
@@ -209,21 +210,27 @@ class _ThreadContent extends HookConsumerWidget {
     final post = thread.post;
     final replies = thread.replies;
 
-    // Preload profiles for all participants.
+    // Preload profiles for all participants and tagged mentions.
     final allPubkeys = useMemoized(() {
-      final pks = <String>{post.pubkey};
+      final pks = <String>{
+        post.pubkey.toLowerCase(),
+        ...post.mentionPubkeys.map((pubkey) => pubkey.toLowerCase()),
+      };
       for (final reply in replies) {
-        pks.add(reply.pubkey);
+        pks
+          ..add(reply.pubkey.toLowerCase())
+          ..addAll(reply.mentionPubkeys.map((pubkey) => pubkey.toLowerCase()));
       }
-      return pks.toList();
+      return pks.toList()..sort();
     }, [post, replies]);
+    final allPubkeysKey = allPubkeys.join('\u0000');
 
     useEffect(() {
       if (allPubkeys.isNotEmpty) {
         ref.read(userCacheProvider.notifier).preload(allPubkeys);
       }
       return null;
-    }, [allPubkeys]);
+    }, [allPubkeysKey]);
 
     return Column(
       children: [
@@ -322,7 +329,19 @@ class _OriginalPost extends ConsumerWidget {
     final displayName = profile?.label ?? _shortPubkey(post.pubkey);
 
     final userCache = ref.watch(userCacheProvider);
-    final mentionNames = _buildMentionNames(post.mentionPubkeys, userCache);
+    final agentMentionPubkeys = agentPubkeysWithProfileOwners(
+      knownAgentPubkeys: ref.watch(agentMentionPubkeysProvider(post.channelId)),
+      profileOwnedAgentPubkeys: [
+        for (final profile in userCache.values)
+          if (profile.ownerPubkey != null) profile.pubkey,
+      ],
+    );
+    final mentionNames = mentionNamesWithDirectoryLabels(
+      mentionPubkeys: post.mentionPubkeys,
+      profileMentionNames: _buildMentionNames(post.mentionPubkeys, userCache),
+      directoryDisplayNames: ref.watch(agentDirectoryDisplayNamesProvider),
+      agentMentionPubkeys: agentMentionPubkeys,
+    );
 
     return Padding(
       padding: const EdgeInsets.all(Grid.xs),
@@ -375,6 +394,7 @@ class _OriginalPost extends ConsumerWidget {
           MessageContent(
             content: post.content,
             mentionNames: mentionNames,
+            agentMentionPubkeys: agentMentionPubkeys,
             tags: post.tags,
             baseStyle: messageBodyTextStyle.copyWith(
               color: context.colors.onSurface,
@@ -409,7 +429,19 @@ class _ReplyRow extends ConsumerWidget {
     final displayName = profile?.label ?? _shortPubkey(reply.pubkey);
 
     final userCache = ref.watch(userCacheProvider);
-    final mentionNames = _buildMentionNames(reply.mentionPubkeys, userCache);
+    final agentMentionPubkeys = agentPubkeysWithProfileOwners(
+      knownAgentPubkeys: ref.watch(agentMentionPubkeysProvider(channelId)),
+      profileOwnedAgentPubkeys: [
+        for (final profile in userCache.values)
+          if (profile.ownerPubkey != null) profile.pubkey,
+      ],
+    );
+    final mentionNames = mentionNamesWithDirectoryLabels(
+      mentionPubkeys: reply.mentionPubkeys,
+      profileMentionNames: _buildMentionNames(reply.mentionPubkeys, userCache),
+      directoryDisplayNames: ref.watch(agentDirectoryDisplayNamesProvider),
+      agentMentionPubkeys: agentMentionPubkeys,
+    );
 
     return Padding(
       padding: const EdgeInsets.symmetric(
@@ -481,6 +513,7 @@ class _ReplyRow extends ConsumerWidget {
             child: MessageContent(
               content: reply.content,
               mentionNames: mentionNames,
+              agentMentionPubkeys: agentMentionPubkeys,
               tags: reply.tags,
               baseStyle: messageBodyTextStyle.copyWith(
                 color: context.colors.onSurface,
diff --git a/mobile/lib/features/home/home_page.dart b/mobile/lib/features/home/home_page.dart
index 7c1e5792f9..a40e317469 100644
--- a/mobile/lib/features/home/home_page.dart
+++ b/mobile/lib/features/home/home_page.dart
@@ -8,6 +8,7 @@ import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
 
 import '../../shared/theme/theme.dart';
+import '../../shared/widgets/mobile_tab_footer_backdrop.dart';
 import '../activity/activity_page.dart';
 import '../channels/channels_page.dart';
 import '../search/search_page.dart';
@@ -17,12 +18,12 @@ class HomePage extends HookConsumerWidget {
 
   final WidgetBuilder settingsPageBuilder;
 
-  static const double _tabBarHeight = 56;
+  static const double _tabBarHeight = mobileTabBarHeight;
   static const double _tabBarRadius = _tabBarHeight / 2;
   static const double _tabBarInnerInset = Grid.half;
   static const double _selectedTabRadius =
       (_tabBarHeight - (_tabBarInnerInset * 2)) / 2;
-  static const double _tabBarBottomGap = Grid.twelve;
+  static const double _tabBarBottomGap = mobileTabBarBottomGap;
   static const double _tabBarHorizontalMargin = Grid.gutter;
   static const double _tabDestinationHorizontalPadding = Grid.sm;
   static const double _tabIconSize = 22;
@@ -63,6 +64,7 @@ class HomePage extends HookConsumerWidget {
     ];
 
     return Scaffold(
+      backgroundColor: Colors.transparent,
       // Keep the floating navigation and Home quick actions anchored while the
       // keyboard is visible on any tab.
       resizeToAvoidBottomInset: false,
@@ -71,6 +73,7 @@ class HomePage extends HookConsumerWidget {
         child: Stack(
           fit: StackFit.expand,
           children: [
+            Positioned.fill(child: ColoredBox(color: context.colors.surface)),
             Positioned.fill(
               child: MediaQuery(
                 data: _mediaQueryWithFloatingTabBarClearance(
@@ -80,6 +83,14 @@ class HomePage extends HookConsumerWidget {
                 child: IndexedStack(index: tabIndex.value, children: pages),
               ),
             ),
+            Align(
+              alignment: Alignment.bottomCenter,
+              child: IgnorePointer(
+                child: MobileTabFooterBackdrop(
+                  height: mobileTabFooterBackdropHeight(context),
+                ),
+              ),
+            ),
             Positioned.fill(
               child: ChannelQuickActionsLauncher(
                 visible: tabIndex.value == 0,
diff --git a/mobile/lib/features/search/recent_searches_provider.dart b/mobile/lib/features/search/recent_searches_provider.dart
index 813672a9cc..2fad17832e 100644
--- a/mobile/lib/features/search/recent_searches_provider.dart
+++ b/mobile/lib/features/search/recent_searches_provider.dart
@@ -19,8 +19,16 @@ class RecentSearchesNotifier extends Notifier<List<String>> {
     final pubkey = ref.watch(myPubkeyProvider) ?? 'anon';
     _prefsKey = '$_recentSearchesPrefsKey:${config.baseUrl}:$pubkey';
 
+    final prefs = ref.read(savedPrefsProvider);
     final stored =
-        ref.read(savedPrefsProvider).getStringList(_prefsKey) ?? const [];
+        readMigratedPref<List<String>>(
+          prefs,
+          canonicalKey: _prefsKey,
+          legacyKey: '$_recentSearchesPrefsKey:${config.storedOrigin}:$pubkey',
+          read: prefs.getStringList,
+          write: prefs.setStringList,
+        ) ??
+        const [];
     return List.unmodifiable(
       stored
           .map((query) => query.trim())
diff --git a/mobile/lib/features/search/search_page.dart b/mobile/lib/features/search/search_page.dart
index 7f4dc24b45..65fc12dfd9 100644
--- a/mobile/lib/features/search/search_page.dart
+++ b/mobile/lib/features/search/search_page.dart
@@ -3,6 +3,8 @@ import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
 
+import '../../shared/mentions/agent_identity_provider.dart';
+import '../../shared/mentions/mention_tags.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
 import '../../shared/widgets/buzz_loading_indicator.dart';
@@ -93,10 +95,12 @@ class SearchPage extends HookConsumerWidget {
     }
 
     return FrostedScaffold(
+      backgroundColor: Colors.transparent,
       // Keep the empty state centered in the page rather than the portion left
       // above the keyboard.
       resizeToAvoidBottomInset: false,
       appBar: FrostedAppBar(
+        automaticallyImplyLeading: false,
         gradient: context.appColors.topSectionGradient,
         title: const Text('Search'),
         titleStyle: headerTitleStyle,
@@ -344,7 +348,10 @@ class _SearchBody extends ConsumerWidget {
     return ListView(
       key: const Key('search-results-list'),
       padding: EdgeInsets.only(
-        bottom: Grid.xl + MediaQuery.viewInsetsOf(context).bottom,
+        bottom:
+            Grid.xl +
+            MediaQuery.paddingOf(context).bottom +
+            MediaQuery.viewInsetsOf(context).bottom,
       ),
       children: [
         if (showChannels && state.channelResults.isNotEmpty)
@@ -394,7 +401,10 @@ class _RecentSearches extends StatelessWidget {
     return ListView(
       key: const Key('recent-searches-list'),
       padding: EdgeInsets.only(
-        bottom: Grid.xl + MediaQuery.viewInsetsOf(context).bottom,
+        bottom:
+            Grid.xl +
+            MediaQuery.paddingOf(context).bottom +
+            MediaQuery.viewInsetsOf(context).bottom,
       ),
       children: [
         Padding(
@@ -589,7 +599,7 @@ class _PeopleSection extends ConsumerWidget {
   }
 }
 
-class _MessagesSection extends ConsumerWidget {
+class _MessagesSection extends HookConsumerWidget {
   final List<SearchHit> hits;
   final String? currentPubkey;
   final VoidCallback onResultSelected;
@@ -606,8 +616,15 @@ class _MessagesSection extends ConsumerWidget {
     final channels = ref.watch(channelsProvider).value ?? [];
 
     // Preload author profiles.
-    final pubkeys = hits.map((h) => h.pubkey.toLowerCase()).toSet().toList();
-    ref.read(userCacheProvider.notifier).preload(pubkeys);
+    final preloadPubkeys = {
+      for (final hit in hits) hit.pubkey.toLowerCase(),
+      for (final hit in hits) ...mentionedPubkeysFromTags(hit.tags),
+    }.toList()..sort();
+    final preloadPubkeysKey = preloadPubkeys.join('\u0000');
+    useEffect(() {
+      ref.read(userCacheProvider.notifier).preload(preloadPubkeys);
+      return null;
+    }, [preloadPubkeysKey]);
 
     return Column(
       crossAxisAlignment: CrossAxisAlignment.start,
@@ -627,7 +644,7 @@ class _MessagesSection extends ConsumerWidget {
   }
 }
 
-class _MessageTile extends StatelessWidget {
+class _MessageTile extends ConsumerWidget {
   final SearchHit hit;
   final UserProfile? authorProfile;
   final Map<String, UserProfile> userCache;
@@ -645,12 +662,34 @@ class _MessageTile extends StatelessWidget {
   });
 
   @override
-  Widget build(BuildContext context) {
+  Widget build(BuildContext context, WidgetRef ref) {
     final authorName = authorProfile?.label ?? shortPubkey(hit.pubkey);
     final timeAgo = relativeTime(hit.createdAt);
     final channelName = hit.channelName?.trim().replaceFirst(RegExp(r'^#'), '');
     final hasChannelName = channelName != null && channelName.isNotEmpty;
     final isDm = channel?.isDm ?? false;
+    final profileMentionNames = {
+      for (final pubkey in mentionedPubkeysFromTags(hit.tags))
+        if (userCache[pubkey]?.displayName?.trim().isNotEmpty == true)
+          pubkey: userCache[pubkey]!.displayName!.trim(),
+    };
+    final mentionPubkeys = mentionedPubkeysFromTags(hit.tags);
+    final knownAgentPubkeys = channel == null
+        ? ref.watch(knownAgentPubkeysProvider)
+        : ref.watch(agentMentionPubkeysProvider(channel!.id));
+    final agentMentionPubkeys = agentPubkeysWithProfileOwners(
+      knownAgentPubkeys: knownAgentPubkeys,
+      profileOwnedAgentPubkeys: [
+        for (final profile in userCache.values)
+          if (profile.ownerPubkey != null) profile.pubkey,
+      ],
+    );
+    final mentionNames = mentionNamesWithDirectoryLabels(
+      mentionPubkeys: mentionPubkeys,
+      profileMentionNames: profileMentionNames,
+      directoryDisplayNames: ref.watch(agentDirectoryDisplayNamesProvider),
+      agentMentionPubkeys: agentMentionPubkeys,
+    );
 
     return ListTile(
       key: ValueKey('search-message-row-${hit.eventId}'),
@@ -722,6 +761,8 @@ class _MessageTile extends StatelessWidget {
           MessageContent(
             key: ValueKey('search-message-body-${hit.eventId}'),
             content: hit.content,
+            mentionNames: mentionNames,
+            agentMentionPubkeys: agentMentionPubkeys,
             tags: hit.tags,
             maxLines: 2,
             baseStyle: activityPreviewTextStyle.copyWith(
diff --git a/mobile/lib/shared/emoji/emoji_burst.dart b/mobile/lib/shared/emoji/emoji_burst.dart
new file mode 100644
index 0000000000..7717ea3746
--- /dev/null
+++ b/mobile/lib/shared/emoji/emoji_burst.dart
@@ -0,0 +1,398 @@
+/// Emoji particle bursts, ported from desktop's `EmojiBurstProvider`
+/// (`desktop/src/shared/ui/EmojiBurstProvider.tsx`).
+///
+/// Desktop paints to a fixed full-window `<canvas>` above everything and steps
+/// the particles on `requestAnimationFrame`. Mobile does the same shape:
+/// [EmojiBurstOverlay] installs one full-screen [CustomPaint] above the
+/// navigator (so bursts survive route pushes and modal sheets), and a [Ticker]
+/// steps the same physics.
+///
+/// The constants below are desktop's, unchanged — the motion is the product
+/// decision, and drifting it would make the two clients feel different.
+library;
+
+import 'dart:math';
+
+import 'package:flutter/material.dart';
+import 'package:flutter/scheduler.dart';
+import 'package:flutter_hooks/flutter_hooks.dart';
+import 'package:hooks_riverpod/hooks_riverpod.dart';
+
+import 'positive_emoji.dart';
+
+/// Particles per burst — desktop's `PICKER_PARTICLES_PER_BURST`.
+const _particlesPerBurst = 5;
+
+/// Frames a particle lives — desktop's `PICKER_PARTICLE_LIFE_FRAMES`.
+const _particleLifeFrames = 108;
+
+/// Desktop's `MAX_ACTIVE`, scaled down: a phone screen holds far fewer
+/// particles before it reads as noise, and every one costs a `saveLayer`.
+const _maxActiveParticles = 160;
+
+/// Physics runs at a fixed 60Hz step regardless of display refresh rate.
+/// Desktop's constants are per-frame deltas on a 60Hz assumption; stepping them
+/// once per real frame would run the burst at double speed on a 120Hz panel.
+const _stepSeconds = 1 / 60;
+
+/// Cap on catch-up steps per frame so a stalled frame can't spiral.
+const _maxStepsPerFrame = 4;
+
+/// Glyph size the cached [TextPainter] is laid out at. Particles scale off this
+/// rather than re-laying out text every frame.
+const _glyphCachePx = 64.0;
+
+/// The last emoji added as a reaction that is still waiting for its pill to
+/// appear on screen.
+///
+/// Mobile reactions are not optimistic — `addReaction` awaits the relay and the
+/// pill only exists once the event echoes back — so a burst fired at pick time
+/// would play against a row that has not changed yet. Desktop solves this the
+/// same way (`burstEmojiOnRender` in `MessageReactions.tsx`): remember the
+/// pending emoji, and let the pill fire the burst from its own position the
+/// frame it first renders as reacted-by-me.
+@immutable
+class PendingReactionBurst {
+  final String messageId;
+  final String emoji;
+
+  const PendingReactionBurst({required this.messageId, required this.emoji});
+
+  @override
+  bool operator ==(Object other) =>
+      other is PendingReactionBurst &&
+      other.messageId == messageId &&
+      other.emoji == emoji;
+
+  @override
+  int get hashCode => Object.hash(messageId, emoji);
+}
+
+/// One slot, not a queue: a burst is a flourish on the reaction you just added,
+/// and two adds in flight at once means the newer one is the interesting one.
+class PendingReactionBurstNotifier extends Notifier<PendingReactionBurst?> {
+  @override
+  PendingReactionBurst? build() => null;
+
+  /// Arm a burst for [emoji] on [messageId]. No-op for emoji that don't
+  /// celebrate, so callers don't have to gate themselves.
+  void arm(String messageId, String emoji) {
+    if (!isPositiveEmojiParticle(emoji)) return;
+    state = PendingReactionBurst(messageId: messageId, emoji: emoji);
+  }
+
+  /// Claim the pending burst if it is [target], returning whether the caller
+  /// won. The same message can be on screen twice (a thread pushed over its
+  /// channel), so exactly one pill must fire.
+  bool claim(PendingReactionBurst target) {
+    if (state != target) return false;
+    state = null;
+    return true;
+  }
+}
+
+final pendingReactionBurstProvider =
+    NotifierProvider<PendingReactionBurstNotifier, PendingReactionBurst?>(
+      PendingReactionBurstNotifier.new,
+    );
+
+class _Particle {
+  double x;
+  double y;
+  double xv;
+  double yv;
+  double rotation;
+  double spin;
+  double scale;
+  double opacity;
+  double life;
+  final double maxLife;
+  final String emoji;
+  final double fontSize;
+  final double gravity;
+
+  _Particle({
+    required this.x,
+    required this.y,
+    required this.xv,
+    required this.yv,
+    required this.rotation,
+    required this.spin,
+    required this.scale,
+    required this.opacity,
+    required this.life,
+    required this.maxLife,
+    required this.emoji,
+    required this.fontSize,
+    required this.gravity,
+  });
+
+  /// Desktop's `updateParticle`. Returns false once the particle is spent.
+  bool step() {
+    life -= 1;
+    rotation += spin;
+    yv += gravity;
+    xv *= 0.965;
+    yv *= 0.998;
+    x += xv;
+    y += yv;
+    scale += (1 - scale) * 0.28;
+
+    final lifeRatio = life / maxLife;
+    if (lifeRatio < 0.24) {
+      opacity = max(0, lifeRatio / 0.24);
+    }
+
+    return life > 0 && opacity > 0.02;
+  }
+}
+
+/// Holds the live particles and notifies the painter each step.
+///
+/// Deliberately not a `Notifier` over a particle list: the particles mutate 60
+/// times a second and must never rebuild a widget. Listeners are the painter's
+/// repaint signal only.
+class EmojiBurstController extends ChangeNotifier {
+  final List<_Particle> _particles = [];
+  final Random _random;
+
+  /// Set when a spawn arrives so the overlay knows to start its ticker.
+  VoidCallback? onSpawn;
+
+  EmojiBurstController({Random? random}) : _random = random ?? Random();
+
+  bool get hasParticles => _particles.isNotEmpty;
+
+  /// Spawn a burst of [emoji] centred on [origin] (global coordinates).
+  /// Mirrors desktop's `spawnPickerEmojiBurst`.
+  void burst(String emoji, Offset origin) {
+    final trimmed = emoji.trim();
+    if (trimmed.isEmpty) return;
+    if (_particles.length + _particlesPerBurst > _maxActiveParticles) return;
+
+    for (var i = 0; i < _particlesPerBurst; i += 1) {
+      final horizontalDrift = (_random.nextDouble() - 0.5) * 4.4;
+      final initialLift = 2.1 + _random.nextDouble() * 2.35;
+
+      _particles.add(
+        _Particle(
+          x: origin.dx,
+          y: origin.dy,
+          xv: horizontalDrift,
+          yv: -initialLift,
+          rotation: (_random.nextDouble() - 0.5) * 22,
+          spin: (_random.nextDouble() - 0.5) * 5.2,
+          scale: 0.25,
+          opacity: 1,
+          life: _particleLifeFrames.toDouble(),
+          maxLife: _particleLifeFrames.toDouble(),
+          emoji: trimmed,
+          fontSize: 18 + (_random.nextDouble() * 24).ceilToDouble(),
+          // Negative: the burst floats up and keeps accelerating upward.
+          gravity: -(0.018 + _random.nextDouble() * 0.018),
+        ),
+      );
+    }
+
+    onSpawn?.call();
+    notifyListeners();
+  }
+
+  /// Advance one fixed step. Returns whether any particles remain.
+  bool step() {
+    for (var i = _particles.length - 1; i >= 0; i -= 1) {
+      if (!_particles[i].step()) {
+        _particles[i] = _particles.last;
+        _particles.removeLast();
+      }
+    }
+    notifyListeners();
+    return _particles.isNotEmpty;
+  }
+
+  void clear() {
+    if (_particles.isEmpty) return;
+    _particles.clear();
+    notifyListeners();
+  }
+
+  @override
+  void dispose() {
+    _particles.clear();
+    super.dispose();
+  }
+}
+
+final emojiBurstControllerProvider = Provider<EmojiBurstController>((ref) {
+  final controller = EmojiBurstController();
+  ref.onDispose(controller.dispose);
+  return controller;
+});
+
+/// Fire a burst of [emoji] centred on [context]'s own box.
+///
+/// The convenience the call sites actually want: they have a build context for
+/// the pill or tile that was tapped and no reason to know about global
+/// coordinates. Silently does nothing for emoji outside the positive set or
+/// when the platform asks for reduced motion, so callers stay simple.
+void burstEmojiFromContext(
+  WidgetRef ref,
+  BuildContext context,
+  String emoji, {
+  bool requirePositive = true,
+}) {
+  if (requirePositive && !isPositiveEmojiParticle(emoji)) return;
+  if (MediaQuery.maybeDisableAnimationsOf(context) ?? false) return;
+
+  final box = context.findRenderObject();
+  if (box is! RenderBox || !box.hasSize) return;
+  final origin = box.localToGlobal(box.size.center(Offset.zero));
+  ref.read(emojiBurstControllerProvider).burst(emoji, origin);
+}
+
+/// Full-screen particle layer. Install once, above the navigator, so bursts
+/// keep playing over pushed routes and modal sheets.
+class EmojiBurstOverlay extends HookConsumerWidget {
+  final Widget child;
+
+  const EmojiBurstOverlay({super.key, required this.child});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final controller = ref.watch(emojiBurstControllerProvider);
+    final tickerProvider = useSingleTickerProvider();
+
+    // Ticker + leftover time live in refs: stepping physics must not rebuild
+    // this widget, which wraps the entire app.
+    final leftover = useRef(0.0);
+    final lastElapsed = useRef(Duration.zero);
+
+    final ticker = useMemoized(() {
+      late final Ticker created;
+      created = tickerProvider.createTicker((elapsed) {
+        final delta = elapsed - lastElapsed.value;
+        lastElapsed.value = elapsed;
+        leftover.value += delta.inMicroseconds / Duration.microsecondsPerSecond;
+
+        var steps = 0;
+        var alive = controller.hasParticles;
+        while (leftover.value >= _stepSeconds && steps < _maxStepsPerFrame) {
+          leftover.value -= _stepSeconds;
+          steps += 1;
+          alive = controller.step();
+          if (!alive) break;
+        }
+        // Don't bank unspent time from a stall — it would fast-forward the
+        // next burst.
+        if (steps >= _maxStepsPerFrame) leftover.value = 0;
+
+        if (!alive) {
+          created.stop();
+          lastElapsed.value = Duration.zero;
+          leftover.value = 0;
+        }
+      });
+      return created;
+    }, [tickerProvider, controller]);
+
+    useEffect(() => ticker.dispose, [ticker]);
+
+    useEffect(() {
+      void start() {
+        if (ticker.isActive) return;
+        lastElapsed.value = Duration.zero;
+        leftover.value = 0;
+        ticker.start();
+      }
+
+      controller.onSpawn = start;
+      if (controller.hasParticles) start();
+      return () {
+        if (controller.onSpawn == start) controller.onSpawn = null;
+      };
+    }, [ticker, controller]);
+
+    return Stack(
+      children: [
+        child,
+        Positioned.fill(
+          child: IgnorePointer(
+            child: ExcludeSemantics(
+              child: RepaintBoundary(
+                child: CustomPaint(painter: _EmojiBurstPainter(controller)),
+              ),
+            ),
+          ),
+        ),
+      ],
+    );
+  }
+}
+
+/// Laid-out glyphs, keyed by emoji. Emoji are drawn thousands of times per
+/// burst; laying out the text once and scaling the canvas is the whole trick.
+final Map<String, TextPainter> _glyphCache = {};
+
+/// Bounded so a chatty channel full of distinct reactions can't grow it
+/// without limit. Bursts are visual sugar — evicting the whole cache costs one
+/// re-layout per emoji still on screen.
+const _glyphCacheLimit = 64;
+
+TextPainter _glyphFor(String emoji) {
+  final cached = _glyphCache[emoji];
+  if (cached != null) return cached;
+  if (_glyphCache.length >= _glyphCacheLimit) _glyphCache.clear();
+
+  final painter = TextPainter(
+    text: TextSpan(
+      text: emoji,
+      style: const TextStyle(fontSize: _glyphCachePx),
+    ),
+    textDirection: TextDirection.ltr,
+  )..layout();
+  _glyphCache[emoji] = painter;
+  return painter;
+}
+
+/// Drop the cached glyph layouts. Exposed for tests; the cache is not
+/// community- or account-scoped, so nothing else needs to reset it.
+@visibleForTesting
+void clearEmojiBurstGlyphCache() => _glyphCache.clear();
+
+class _EmojiBurstPainter extends CustomPainter {
+  final EmojiBurstController controller;
+
+  _EmojiBurstPainter(this.controller) : super(repaint: controller);
+
+  @override
+  void paint(Canvas canvas, Size size) {
+    for (final particle in controller._particles) {
+      final glyph = _glyphFor(particle.emoji);
+      final drawSize = particle.fontSize * particle.scale;
+      final scale = drawSize / _glyphCachePx;
+
+      canvas.save();
+      canvas.translate(particle.x, particle.y);
+      canvas.rotate(particle.rotation * pi / 180);
+      canvas.scale(scale);
+      // Color fonts ignore TextStyle.color, so fade through a layer instead.
+      if (particle.opacity < 1) {
+        canvas.saveLayer(
+          Rect.fromCenter(
+            center: Offset.zero,
+            width: glyph.width,
+            height: glyph.height,
+          ),
+          Paint()..color = Colors.black.withValues(alpha: particle.opacity),
+        );
+      }
+      glyph.paint(canvas, Offset(-glyph.width / 2, -glyph.height / 2));
+      if (particle.opacity < 1) canvas.restore();
+      canvas.restore();
+    }
+  }
+
+  @override
+  bool shouldRepaint(_EmojiBurstPainter oldDelegate) =>
+      oldDelegate.controller != controller;
+}
diff --git a/mobile/lib/shared/emoji/emoji_data.dart b/mobile/lib/shared/emoji/emoji_data.dart
new file mode 100644
index 0000000000..c4a34ebe6c
--- /dev/null
+++ b/mobile/lib/shared/emoji/emoji_data.dart
@@ -0,0 +1,154 @@
+import 'package:flutter/foundation.dart';
+
+/// The standard (Unicode) emoji set, projected from the same emoji-mart dataset
+/// desktop uses.
+///
+/// The asset at `assets/emoji/emoji-data.json` is generated by
+/// `just mobile-emoji-data`; ids here are emoji-mart ids, which are exactly the
+/// `:shortcode:` values desktop emits from its picker and resolves in
+/// `emojiDisplayName`. Keeping both clients on one dataset is what stops a
+/// shortcode from meaning different things on mobile and desktop.
+@immutable
+class EmojiEntry {
+  /// emoji-mart id, i.e. the shortcode without the surrounding colons.
+  final String id;
+
+  /// Human-readable name, e.g. `Index Pointing Up`.
+  final String name;
+
+  /// Search keywords from the dataset.
+  final List<String> keywords;
+
+  /// The default-skin glyph.
+  final String native;
+
+  /// Position within emoji-mart's skin list. The default skin is zero.
+  final int skinIndex;
+
+  /// Owning category id, e.g. `people`.
+  final String categoryId;
+
+  const EmojiEntry({
+    required this.id,
+    required this.name,
+    required this.keywords,
+    required this.native,
+    required this.categoryId,
+    this.skinIndex = 0,
+  });
+
+  /// Unique tile id while preserving the desktop-identical shortcode for the
+  /// default skin.
+  String get tileId => skinIndex == 0 ? id : '$id-$skinIndex';
+}
+
+/// One dataset category, in emoji-mart's own order.
+@immutable
+class EmojiCategory {
+  final String id;
+  final List<EmojiEntry> emoji;
+
+  const EmojiCategory({required this.id, required this.emoji});
+
+  /// Title-cased label for the category rail.
+  String get label => switch (id) {
+    'people' => 'Smileys & People',
+    'nature' => 'Animals & Nature',
+    'foods' => 'Food & Drink',
+    'activity' => 'Activity',
+    'places' => 'Travel & Places',
+    'objects' => 'Objects',
+    'symbols' => 'Symbols',
+    'flags' => 'Flags',
+    _ => id,
+  };
+}
+
+/// Parsed emoji dataset: ordered categories, a flat list for search, and a
+/// reverse glyph index for resolving a reaction back to its shortcode.
+@immutable
+class EmojiDataset {
+  final List<EmojiCategory> categories;
+
+  /// Every entry, in category order. Search scans this.
+  final List<EmojiEntry> all;
+
+  /// Glyph to `:shortcode:`. Mirrors desktop's `emojiDisplayName`.
+  final Map<String, String> nativeToShortcode;
+
+  const EmojiDataset({
+    required this.categories,
+    required this.all,
+    required this.nativeToShortcode,
+  });
+
+  static const empty = EmojiDataset(
+    categories: [],
+    all: [],
+    nativeToShortcode: {},
+  );
+
+  bool get isEmpty => all.isEmpty;
+
+  /// Resolve a reaction value to something displayable as a name: a custom
+  /// emoji's `:shortcode:` passes through, a Unicode glyph maps to its
+  /// shortcode, and anything unknown falls back to itself.
+  String displayName(String emoji) {
+    final trimmed = emoji.trim();
+    if (trimmed.startsWith(':') && trimmed.endsWith(':')) return trimmed;
+    return nativeToShortcode[trimmed] ?? trimmed;
+  }
+
+  /// Parse the generated asset. Runs on a background isolate via `compute`, so
+  /// it must stay a top-level-callable pure function over plain JSON.
+  static EmojiDataset fromJson(Map<String, dynamic> json) {
+    final rawEmoji = (json['emoji'] as Map).cast<String, dynamic>();
+    final rawCategories = (json['categories'] as List).cast<dynamic>();
+
+    final categories = <EmojiCategory>[];
+    final all = <EmojiEntry>[];
+    final nativeToShortcode = <String, String>{};
+
+    for (final rawCategory in rawCategories) {
+      final category = (rawCategory as Map).cast<String, dynamic>();
+      final categoryId = category['id'] as String;
+      final entries = <EmojiEntry>[];
+
+      for (final rawId in (category['emoji'] as List).cast<dynamic>()) {
+        final id = rawId as String;
+        final record = (rawEmoji[id] as Map?)?.cast<String, dynamic>();
+        if (record == null) continue;
+        // Older committed assets used one string; accept that shape so the
+        // parser remains safe while generated assets move to all skin variants.
+        final natives = switch (record['u']) {
+          final List values => values.cast<String>(),
+          final String value => [value],
+          _ => const <String>[],
+        };
+        for (final (skinIndex, native) in natives.indexed) {
+          final entry = EmojiEntry(
+            id: id,
+            name: record['n'] as String,
+            keywords: (record['k'] as List).cast<String>(),
+            native: native,
+            categoryId: categoryId,
+            skinIndex: skinIndex,
+          );
+          entries.add(entry);
+          all.add(entry);
+          // First writer wins so the earliest category owns a shared glyph,
+          // matching desktop's map build order.
+          nativeToShortcode.putIfAbsent(entry.native, () => ':$id:');
+        }
+      }
+
+      categories.add(EmojiCategory(id: categoryId, emoji: entries));
+    }
+
+    return EmojiDataset(
+      categories: categories,
+      all: all,
+      nativeToShortcode: nativeToShortcode,
+    );
+  }
+}
diff --git a/mobile/lib/shared/emoji/emoji_data_provider.dart b/mobile/lib/shared/emoji/emoji_data_provider.dart
new file mode 100644
index 0000000000..dbb56b5c33
--- /dev/null
+++ b/mobile/lib/shared/emoji/emoji_data_provider.dart
@@ -0,0 +1,38 @@
+import 'dart:convert';
+
+import 'package:flutter/foundation.dart';
+import 'package:flutter/services.dart' show rootBundle;
+import 'package:hooks_riverpod/hooks_riverpod.dart';
+
+import 'emoji_data.dart';
+
+/// Asset path for the generated dataset. See `mobile/scripts/generate-emoji-data.mjs`.
+const emojiDataAssetPath = 'assets/emoji/emoji-data.json';
+
+/// Decode + parse off the UI isolate. ~1.9k entries is fast but not free, and
+/// the picker sheet animates in while this runs.
+EmojiDataset _parseEmojiData(String source) {
+  return EmojiDataset.fromJson(jsonDecode(source) as Map<String, dynamic>);
+}
+
+/// The standard emoji dataset, loaded once from the app bundle.
+final emojiDatasetProvider = FutureProvider<EmojiDataset>((ref) async {
+  final source = await rootBundle.loadString(emojiDataAssetPath);
+  return compute(_parseEmojiData, source);
+});
+
+/// Synchronous read of the dataset — [EmojiDataset.empty] while loading or on
+/// error. Convenience for widgets that only need the resolved value, mirroring
+/// `customEmojiListProvider`.
+final emojiDatasetOrEmptyProvider = Provider<EmojiDataset>((ref) {
+  return ref.watch(emojiDatasetProvider).value ?? EmojiDataset.empty;
+});
+
+/// Every glyph in the dataset, as a set for membership tests.
+///
+/// Built once per dataset load rather than per message: `isEmojiOnlyMessage`
+/// runs on every rendered body, and materializing ~1.9k keys there would be a
+/// per-frame cost.
+final nativeEmojiGlyphsProvider = Provider<Set<String>>((ref) {
+  return ref.watch(emojiDatasetOrEmptyProvider).nativeToShortcode.keys.toSet();
+});
diff --git a/mobile/lib/shared/emoji/emoji_only.dart b/mobile/lib/shared/emoji/emoji_only.dart
new file mode 100644
index 0000000000..e6994f0b9b
--- /dev/null
+++ b/mobile/lib/shared/emoji/emoji_only.dart
@@ -0,0 +1,87 @@
+/// Detection and sizing for messages whose entire body is emoji, ported from
+/// desktop's `isEmojiOnlyMessage` (`desktop/src/shared/lib/emojiOnly.ts`) and
+/// the `emojiOnly` branch of `MessageRow.tsx`.
+library;
+
+import 'package:characters/characters.dart';
+
+import '../custom_emoji/custom_emoji.dart';
+
+/// Body size for an emoji-only message. Desktop steps `text-sm` (14px) up to
+/// `text-4xl`; mobile body text is the same 14px, so the same 36px lands the
+/// same jump.
+const double kEmojiOnlyFontSize = 36.0;
+
+/// Line height for an emoji-only body — desktop's `leading-tight`. Emoji have
+/// generous internal leading already, so normal line spacing leaves a gap that
+/// reads as a blank row.
+const double kEmojiOnlyHeight = 1.25;
+
+/// Inline custom-emoji size inside an emoji-only message. Desktop sizes these
+/// at `1.45em` of the surrounding text.
+const double kEmojiOnlyCustomEmojiSize = kEmojiOnlyFontSize * 1.45;
+
+/// Anything with `Extended_Pictographic` in it is emoji enough. Keycaps and
+/// digit-based sequences don't match — those are covered by the dataset's own
+/// native set instead, exactly as desktop does it.
+final RegExp _pictographic = RegExp(
+  r'\p{Extended_Pictographic}',
+  unicode: true,
+);
+
+/// Whether [content] is nothing but emoji — native glyphs, known custom
+/// `:shortcode:`s, and whitespace, with at least one emoji present.
+///
+/// [nativeEmoji] is the dataset's glyph set — read `nativeEmojiGlyphsProvider`.
+/// Passing an empty set still gives correct results for ordinary emoji, since
+/// the pictographic check stands on its own; only glyphs with no pictographic
+/// code point of their own (keycaps like 1️⃣) need the set.
+bool isEmojiOnlyMessage(
+  String content, {
+  required Set<String> nativeEmoji,
+  List<CustomEmoji> customEmoji = const [],
+}) {
+  final trimmed = content.trim();
+  if (trimmed.isEmpty) return false;
+
+  final shortcodes = {
+    for (final emoji in customEmoji) emoji.shortcode.toLowerCase(),
+  };
+  var sawEmoji = false;
+
+  // Grapheme clusters, so a ZWJ family or a flag pair is one unit. Desktop
+  // hand-rolls this scan; Dart's `characters` already segments correctly.
+  final iterator = trimmed.characters.iterator;
+  final clusters = <String>[];
+  while (iterator.moveNext()) {
+    clusters.add(iterator.current);
+  }
+
+  var index = 0;
+  while (index < clusters.length) {
+    final cluster = clusters[index];
+
+    if (cluster.trim().isEmpty) {
+      index += 1;
+      continue;
+    }
+
+    if (cluster == ':') {
+      final end = clusters.indexOf(':', index + 1);
+      if (end <= index + 1) return false;
+      final shortcode = clusters.sublist(index + 1, end).join().toLowerCase();
+      if (!shortcodes.contains(shortcode)) return false;
+      sawEmoji = true;
+      index = end + 1;
+      continue;
+    }
+
+    if (!nativeEmoji.contains(cluster) && !_pictographic.hasMatch(cluster)) {
+      return false;
+    }
+    sawEmoji = true;
+    index += 1;
+  }
+
+  return sawEmoji;
+}
diff --git a/mobile/lib/shared/emoji/emoji_search.dart b/mobile/lib/shared/emoji/emoji_search.dart
new file mode 100644
index 0000000000..b4f3d9798c
--- /dev/null
+++ b/mobile/lib/shared/emoji/emoji_search.dart
@@ -0,0 +1,214 @@
+/// Emoji search for the mobile picker and reaction tray.
+///
+/// Ported from `desktop/src/shared/lib/emojiSearch.ts`, which exists because
+/// emoji-mart's own search is token-prefix based and so can't cross the `_` in
+/// a shortcode — `pointup` never finds `point_up`. The tiers keep ordinary
+/// queries ranked the way you'd expect while still surfacing looser matches
+/// last: exact > prefix > substring > subsequence over the shortcode.
+///
+/// Mobile extends the desktop tiers with name/keyword matching, because the
+/// tray replaces emoji-mart's picker (which searched names and keywords) rather
+/// than just its `:shortcode` autocomplete. Shortcode hits still outrank
+/// keyword hits, so typing a shortcode you know never buries it.
+library;
+
+import 'emoji_data.dart';
+
+// Lower tier = stronger match.
+const _tierExact = 0;
+const _tierShortcodePrefix = 1;
+const _tierKeywordPrefix = 2;
+const _tierShortcodeSubstring = 3;
+const _tierKeywordSubstring = 4;
+const _tierSubsequence = 5;
+
+/// Sentinel ranking worse than every real tier.
+const _noMatch = 1 << 20;
+
+final _separators = RegExp(r'[:_\s-]');
+final _wordSplit = RegExp(r'[\s_-]+');
+
+/// Lowercase and drop separators (`:`, `_`, `-`, whitespace) so matching is
+/// insensitive to shortcode punctuation. `point_up` and `pointup` collapse to
+/// the same normalized form.
+///
+/// Named for what it does rather than desktop's `normalizeShortcode`, because
+/// `custom_emoji.dart` already exports a validating `normalizeShortcode` with
+/// different semantics (it returns null for malformed input).
+String collapseSeparators(String value) {
+  return value.toLowerCase().replaceAll(_separators, '');
+}
+
+/// A ranked match. [score] is a within-tier tiebreak — lower is better.
+class EmojiMatch {
+  final int tier;
+  final int score;
+
+  const EmojiMatch({required this.tier, required this.score});
+}
+
+/// If [query] is a subsequence of [target] (all chars in order, gaps allowed),
+/// return the span of the match as a tightness score — smaller is tighter.
+/// Returns null when it isn't a subsequence.
+int? _subsequenceSpan(String query, String target) {
+  var first = -1;
+  var last = -1;
+  var qi = 0;
+  for (var ti = 0; ti < target.length && qi < query.length; ti++) {
+    if (target[ti] == query[qi]) {
+      if (first == -1) first = ti;
+      last = ti;
+      qi++;
+    }
+  }
+  if (qi < query.length) return null;
+  return last - first;
+}
+
+/// Score [query] against a single [shortcode]. Returns null when there is no
+/// match at any tier. Both sides are normalized first, so separators are
+/// ignored. This is the desktop-identical half of the ranking.
+EmojiMatch? scoreShortcodeMatch(String query, String shortcode) {
+  final q = collapseSeparators(query);
+  if (q.isEmpty) return null;
+  final target = collapseSeparators(shortcode);
+  if (target.isEmpty) return null;
+
+  if (q == target) return const EmojiMatch(tier: _tierExact, score: 0);
+  if (target.startsWith(q)) {
+    return const EmojiMatch(tier: _tierShortcodePrefix, score: 0);
+  }
+  final index = target.indexOf(q);
+  if (index != -1) {
+    return EmojiMatch(tier: _tierShortcodeSubstring, score: index);
+  }
+  final span = _subsequenceSpan(q, target);
+  if (span != null) return EmojiMatch(tier: _tierSubsequence, score: span);
+  return null;
+}
+
+/// Score [query] against an entry's name and keywords, word by word. Used to
+/// top up shortcode matching so a query like `smiling` finds emoji whose
+/// shortcode doesn't contain it.
+EmojiMatch? _scoreKeywordMatch(
+  String query,
+  String name,
+  List<String> keywords,
+) {
+  final q = query.toLowerCase().trim();
+  if (q.isEmpty) return null;
+
+  var bestTier = _noMatch;
+  var bestScore = 0;
+
+  // Earlier words rank better: the name comes before the keywords, and within
+  // each the dataset's own order is meaningful.
+  void consider(String candidate, int wordIndex) {
+    if (bestTier == _tierKeywordPrefix) return;
+    final word = candidate.toLowerCase();
+    if (word.isEmpty) return;
+    final tier = word.startsWith(q)
+        ? _tierKeywordPrefix
+        : word.contains(q)
+        ? _tierKeywordSubstring
+        : _noMatch;
+    if (tier < bestTier) {
+      bestTier = tier;
+      bestScore = wordIndex;
+    }
+  }
+
+  var wordIndex = 0;
+  for (final word in name.split(_wordSplit)) {
+    consider(word, wordIndex++);
+  }
+  for (final keyword in keywords) {
+    for (final word in keyword.split(_wordSplit)) {
+      consider(word, wordIndex++);
+    }
+  }
+
+  if (bestTier == _noMatch) return null;
+  return EmojiMatch(tier: bestTier, score: bestScore);
+}
+
+class _Scored<T> {
+  final T item;
+  final int tier;
+  final int score;
+  final String code;
+
+  const _Scored({
+    required this.item,
+    required this.tier,
+    required this.score,
+    required this.code,
+  });
+}
+
+int _compare<T>(_Scored<T> a, _Scored<T> b) {
+  if (a.tier != b.tier) return a.tier - b.tier;
+  if (a.score != b.score) return a.score - b.score;
+  // Shorter shortcode is the more specific match, then alphabetical for a
+  // stable result.
+  if (a.code.length != b.code.length) return a.code.length - b.code.length;
+  return a.code.compareTo(b.code);
+}
+
+/// Rank [items] by how well their shortcode matches [query], best first, capped
+/// at [limit]. Mirrors desktop's `rankByShortcode` — used for the custom-emoji
+/// palette, which has no names or keywords.
+List<T> rankByShortcode<T>(
+  String query,
+  List<T> items,
+  String Function(T item) shortcodeOf, {
+  int? limit,
+}) {
+  if (limit != null && limit <= 0) return const [];
+  final scored = <_Scored<T>>[];
+  for (final item in items) {
+    final code = shortcodeOf(item);
+    final match = scoreShortcodeMatch(query, code);
+    if (match == null) continue;
+    scored.add(
+      _Scored(item: item, tier: match.tier, score: match.score, code: code),
+    );
+  }
+  scored.sort(_compare);
+  final ranked = scored.map((entry) => entry.item).toList();
+  if (limit == null || ranked.length <= limit) return ranked;
+  return ranked.sublist(0, limit);
+}
+
+/// Rank standard emoji by shortcode, name, and keywords, best first.
+List<EmojiEntry> searchEmoji(
+  String query,
+  List<EmojiEntry> entries, {
+  int? limit,
+}) {
+  if (limit != null && limit <= 0) return const [];
+  final scored = <_Scored<EmojiEntry>>[];
+  for (final entry in entries) {
+    final shortcode = scoreShortcodeMatch(query, entry.id);
+    final keyword = _scoreKeywordMatch(query, entry.name, entry.keywords);
+    final match = switch ((shortcode, keyword)) {
+      (null, null) => null,
+      (final EmojiMatch only, null) => only,
+      (null, final EmojiMatch only) => only,
+      (final EmojiMatch a, final EmojiMatch b) => a.tier <= b.tier ? a : b,
+    };
+    if (match == null) continue;
+    scored.add(
+      _Scored(
+        item: entry,
+        tier: match.tier,
+        score: match.score,
+        code: entry.id,
+      ),
+    );
+  }
+  scored.sort(_compare);
+  final ranked = scored.map((entry) => entry.item).toList();
+  if (limit == null || ranked.length <= limit) return ranked;
+  return ranked.sublist(0, limit);
+}
diff --git a/mobile/lib/shared/emoji/positive_emoji.dart b/mobile/lib/shared/emoji/positive_emoji.dart
new file mode 100644
index 0000000000..9e6c295361
--- /dev/null
+++ b/mobile/lib/shared/emoji/positive_emoji.dart
@@ -0,0 +1,91 @@
+/// The emoji that earn a particle burst.
+///
+/// Ported verbatim from `POSITIVE_EMOJI_PARTICLES` in
+/// `desktop/src/shared/ui/EmojiBurstProvider.tsx`. Only affirmation reacts
+/// celebrate — a 😢 or 👎 shouldn't throw confetti — so the three groups below
+/// are the whole gate, and both clients must agree on them or the same reaction
+/// bursts on one device and not the other.
+library;
+
+const heartParticleEmojis = <String>[
+  '\u{2764}\u{FE0F}', // ❤️
+  '\u{1FA77}', // 🩷
+  '\u{1F9E1}', // 🧡
+  '\u{1F49B}', // 💛
+  '\u{1F49A}', // 💚
+  '\u{1FA75}', // 🩵
+  '\u{1F499}', // 💙
+  '\u{1F49C}', // 💜
+  '\u{1F90E}', // 🤎
+  '\u{1F5A4}', // 🖤
+  '\u{1FA76}', // 🩶
+  '\u{1F90D}', // 🤍
+  '\u{2764}\u{FE0F}\u{200D}\u{1F525}', // ❤️‍🔥
+  '\u{2764}\u{FE0F}\u{200D}\u{1FA79}', // ❤️‍🩹
+  '\u{1F496}', // 💖
+  '\u{1F495}', // 💕
+  '\u{1F497}', // 💗
+  '\u{1F493}', // 💓
+  '\u{1F49E}', // 💞
+  '\u{1F498}', // 💘
+  '\u{1F49D}', // 💝
+  '\u{2763}\u{FE0F}', // ❣️
+  '\u{2665}\u{FE0F}', // ♥️
+];
+
+const positiveReactionParticleEmojis = <String>[
+  '\u{1F44D}', // 👍
+  '\u{1F44F}', // 👏
+  '\u{1F64C}', // 🙌
+  '\u{1F64F}', // 🙏
+  '\u{1F4AF}', // 💯
+  '\u{1F525}', // 🔥
+  '\u{2728}', // ✨
+  '\u{2B50}', // ⭐
+  '\u{1F31F}', // 🌟
+  '\u{1F389}', // 🎉
+  '\u{1F38A}', // 🎊
+  '\u{1F973}', // 🥳
+  '\u{1F680}', // 🚀
+  '\u{1F4AA}', // 💪
+];
+
+const positiveFaceParticleEmojis = <String>[
+  '\u{1F600}', // 😀
+  '\u{1F603}', // 😃
+  '\u{1F604}', // 😄
+  '\u{1F601}', // 😁
+  '\u{1F60A}', // 😊
+  '\u{1F607}', // 😇
+  '\u{1F642}', // 🙂
+  '\u{1F60D}', // 😍
+  '\u{1F929}', // 🤩
+  '\u{1F970}', // 🥰
+  '\u{1F618}', // 😘
+  '\u{1F60B}', // 😋
+  '\u{1F60E}', // 😎
+  '\u{1F602}', // 😂
+  '\u{1F923}', // 🤣
+];
+
+const positiveEmojiParticles = <String>[
+  ...heartParticleEmojis,
+  ...positiveReactionParticleEmojis,
+  ...positiveFaceParticleEmojis,
+];
+
+/// Emoji presentation selectors carry no meaning for this comparison, and the
+/// same emoji reaches us with and without one depending on where it came from
+/// (the emoji-mart dataset, a hand-typed reaction, an older client). Desktop
+/// gets away with exact set membership because its picker is the only producer;
+/// mobile reactions also arrive off the wire, so fold the selector away.
+String _foldSelectors(String emoji) =>
+    emoji.trim().replaceAll('\u{FE0F}', '').replaceAll('\u{FE0E}', '');
+
+final Set<String> _positiveEmojiParticleSet = {
+  for (final emoji in positiveEmojiParticles) _foldSelectors(emoji),
+};
+
+/// Whether [emoji] should burst. Mirrors desktop's `isPositiveEmojiParticle`.
+bool isPositiveEmojiParticle(String emoji) =>
+    _positiveEmojiParticleSet.contains(_foldSelectors(emoji));
diff --git a/mobile/lib/shared/mentions/agent_identity_provider.dart b/mobile/lib/shared/mentions/agent_identity_provider.dart
new file mode 100644
index 0000000000..ea6a2ee50f
--- /dev/null
+++ b/mobile/lib/shared/mentions/agent_identity_provider.dart
@@ -0,0 +1,274 @@
+import 'dart:collection';
+import 'dart:convert';
+
+import 'package:flutter/foundation.dart';
+import 'package:hooks_riverpod/hooks_riverpod.dart';
+
+import '../../shared/crypto/nip_oa.dart';
+import '../../shared/relay/relay.dart';
+
+/// A relay agent parsed from its kind:10100 agent-profile event.
+///
+/// Mirrors the fields desktop's `RelayAgent` uses for mention eligibility
+/// (`agentAutocompleteEligibility.ts`): who the agent responds to and which
+/// channels it sits in.
+class AgentDirectoryEntry {
+  final String pubkey;
+  final String? displayName;
+  final String? respondTo;
+  final List<String> respondToAllowlist;
+  final List<String> channelIds;
+
+  const AgentDirectoryEntry({
+    required this.pubkey,
+    this.displayName,
+    this.respondTo,
+    this.respondToAllowlist = const [],
+    this.channelIds = const [],
+  });
+
+  factory AgentDirectoryEntry.fromEvent(NostrEvent event) {
+    final content = _tryDecodeJsonMap(event.content);
+    return AgentDirectoryEntry(
+      pubkey: event.pubkey.toLowerCase(),
+      displayName:
+          (content?['display_name'] as String?) ??
+          (content?['name'] as String?),
+      respondTo: content?['respond_to'] as String?,
+      respondToAllowlist: [
+        for (final value in (content?['respond_to_allowlist'] as List?) ?? [])
+          if (value is String) value.toLowerCase(),
+      ],
+      channelIds: [
+        for (final value in (content?['channel_ids'] as List?) ?? [])
+          if (value is String) value,
+      ],
+    );
+  }
+}
+
+Map<String, dynamic>? _tryDecodeJsonMap(String content) {
+  try {
+    final decoded = jsonDecode(content);
+    return decoded is Map<String, dynamic> ? decoded : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/// Relay agent directory from kind:10100 agent-profile events.
+///
+/// Watches the session and only fetches after the WebSocket connects.
+final agentDirectoryProvider = FutureProvider<List<AgentDirectoryEntry>>((
+  ref,
+) async {
+  final sessionState = ref.watch(relaySessionProvider);
+  if (sessionState.status != SessionStatus.connected) return const [];
+  final session = ref.read(relaySessionProvider.notifier);
+  final events = await session.fetchHistory(NostrFilters.agentProfiles());
+  return [for (final event in events) AgentDirectoryEntry.fromEvent(event)];
+});
+
+/// Verified NIP-OA owner pubkey per agent pubkey, from the agents' kind:0
+/// profiles. An entry exists only when the `auth` tag verifies — mirrors
+/// desktop's `profile_valid_oa_owner_pubkey`.
+final agentOwnersProvider = FutureProvider<Map<String, String>>((ref) async {
+  final agents = await ref.watch(agentDirectoryProvider.future);
+  if (agents.isEmpty) return const {};
+  final session = ref.read(relaySessionProvider.notifier);
+  final events = await session.fetchHistory(
+    NostrFilters.profilesBatch([for (final agent in agents) agent.pubkey]),
+  );
+  final owners = <String, String>{};
+  for (final event in events) {
+    final owner = verifiedOaOwnerPubkey(event.tags, event.pubkey);
+    if (owner != null) owners[event.pubkey.toLowerCase()] = owner;
+  }
+  return owners;
+});
+
+/// Pubkeys currently known to represent agents across the active relay.
+///
+/// Message surfaces that do not own channel membership can use this shared
+/// identity source; channel features add their bot roles separately.
+final knownAgentPubkeysProvider = Provider<Set<String>>((ref) {
+  final relayAgents =
+      ref.watch(agentDirectoryProvider).asData?.value ??
+      const <AgentDirectoryEntry>[];
+  final owners = ref.watch(agentOwnersProvider).asData?.value ?? const {};
+  return _AgentPubkeySet({
+    for (final agent in relayAgents) agent.pubkey.toLowerCase(),
+    ...owners.keys.map((pubkey) => pubkey.toLowerCase()),
+  });
+});
+
+/// Directory display names keyed by agent pubkey for mention presentation.
+final agentDirectoryDisplayNamesProvider = Provider<Map<String, String>>((ref) {
+  final agents =
+      ref.watch(agentDirectoryProvider).asData?.value ??
+      const <AgentDirectoryEntry>[];
+  return Map.unmodifiable({
+    for (final agent in agents)
+      if (agent.displayName?.trim().isNotEmpty == true)
+        agent.pubkey.toLowerCase(): agent.displayName!.trim(),
+  });
+});
+
+/// Adds channel bot roles to relay-wide agent identities.
+Set<String> agentPubkeysWithChannelBots({
+  required Set<String> knownAgentPubkeys,
+  required Iterable<String> channelBotPubkeys,
+}) => _AgentPubkeySet({
+  ...knownAgentPubkeys,
+  ...channelBotPubkeys.map((pubkey) => pubkey.toLowerCase()),
+});
+
+/// Adds agent identities derived from locally cached verified profiles.
+Set<String> agentPubkeysWithProfileOwners({
+  required Set<String> knownAgentPubkeys,
+  required Iterable<String> profileOwnedAgentPubkeys,
+}) => _AgentPubkeySet({
+  ...knownAgentPubkeys,
+  ...profileOwnedAgentPubkeys.map((pubkey) => pubkey.toLowerCase()),
+});
+
+/// Preserves profile labels while filling missing agent mentions from the
+/// relay's agent directory.
+Map<String, String> mentionNamesWithDirectoryLabels({
+  required Iterable<String> mentionPubkeys,
+  required Map<String, String> profileMentionNames,
+  required Map<String, String> directoryDisplayNames,
+  required Set<String> agentMentionPubkeys,
+}) {
+  final names = Map<String, String>.from(profileMentionNames);
+  for (final pubkey in mentionPubkeys) {
+    final normalizedPubkey = pubkey.toLowerCase();
+    if (names[normalizedPubkey]?.trim().isEmpty == true) {
+      names.remove(normalizedPubkey);
+    }
+    final directoryName = directoryDisplayNames[normalizedPubkey];
+    if (!names.containsKey(normalizedPubkey) && directoryName != null) {
+      names[normalizedPubkey] = directoryName;
+    }
+    if (!names.containsKey(normalizedPubkey) &&
+        agentMentionPubkeys.contains(normalizedPubkey)) {
+      names[normalizedPubkey] = _agentFallbackLabel(normalizedPubkey);
+    }
+  }
+  return names;
+}
+
+String _agentFallbackLabel(String pubkey) =>
+    pubkey.length >= 8 ? pubkey.substring(0, 8) : pubkey;
+
+/// Keeps the role feed alive for consumers that render mentions outside the
+/// channel timeline, such as search results. A membership change refreshes the
+/// shared bot-role lookup below, regardless of which surface owns the channel.
+class _ChannelBotRoleSubscription extends Notifier<int> {
+  final String channelId;
+  void Function()? _unsubscribe;
+  int _subscriptionVersion = 0;
+
+  _ChannelBotRoleSubscription(this.channelId);
+
+  @override
+  int build() {
+    final sessionState = ref.watch(relaySessionProvider);
+    final subscriptionVersion = ++_subscriptionVersion;
+    _clearSubscription();
+    ref.onDispose(() {
+      _subscriptionVersion++;
+      _clearSubscription();
+    });
+
+    if (sessionState.status != SessionStatus.connected) return 0;
+    Future.microtask(() => _subscribe(channelId, subscriptionVersion));
+    return 0;
+  }
+
+  Future<void> _subscribe(String channelId, int subscriptionVersion) async {
+    final session = ref.read(relaySessionProvider.notifier);
+    try {
+      final unsubscribe = await session.subscribe(
+        NostrFilter(
+          kinds: const [39002],
+          tags: {
+            '#h': [channelId],
+          },
+        ).copyWithSince(DateTime.now().millisecondsSinceEpoch ~/ 1000),
+        (_) {
+          if (_isCurrent(subscriptionVersion)) {
+            state++;
+          }
+        },
+      );
+      if (!_isCurrent(subscriptionVersion)) {
+        unsubscribe();
+        return;
+      }
+      _unsubscribe = unsubscribe;
+    } catch (error) {
+      if (_isCurrent(subscriptionVersion)) {
+        debugPrint(
+          '[ChannelBotRoleSubscription] failed for $channelId: $error',
+        );
+      }
+    }
+  }
+
+  bool _isCurrent(int subscriptionVersion) =>
+      subscriptionVersion == _subscriptionVersion;
+
+  void _clearSubscription() {
+    _unsubscribe?.call();
+    _unsubscribe = null;
+  }
+}
+
+/// Monotonically increments when the channel's kind:39002 membership snapshot
+/// changes. Channel-member and agent-role views share this source so remote
+/// membership updates refresh both snapshots together.
+final channelMembershipUpdateProvider = NotifierProvider.autoDispose
+    .family<_ChannelBotRoleSubscription, int, String>(
+      _ChannelBotRoleSubscription.new,
+    );
+
+/// Bot pubkeys currently assigned a channel bot role.
+final channelBotPubkeysProvider = FutureProvider.autoDispose
+    .family<Set<String>, String>((ref, channelId) async {
+      ref.watch(channelMembershipUpdateProvider(channelId));
+      final sessionState = ref.watch(relaySessionProvider);
+      if (sessionState.status != SessionStatus.connected) return const {};
+      final session = ref.read(relaySessionProvider.notifier);
+      final events = await session.fetchHistory(
+        NostrFilters.channelMembers(channelId),
+      );
+      if (events.isEmpty) return const {};
+      return _AgentPubkeySet({
+        for (final member in membersFromEvent(events.first))
+          if (member.role == 'bot') member.pubkey.toLowerCase(),
+      });
+    });
+
+/// Pubkeys currently known to represent agents in a channel.
+final agentMentionPubkeysProvider = Provider.autoDispose
+    .family<Set<String>, String>((ref, channelId) {
+      final channelBotPubkeys =
+          ref.watch(channelBotPubkeysProvider(channelId)).asData?.value ??
+          const <String>{};
+      return agentPubkeysWithChannelBots(
+        knownAgentPubkeys: ref.watch(knownAgentPubkeysProvider),
+        channelBotPubkeys: channelBotPubkeys,
+      );
+    });
+
+class _AgentPubkeySet extends UnmodifiableSetView<String> {
+  _AgentPubkeySet(Iterable<String> pubkeys) : super(Set.unmodifiable(pubkeys));
+
+  @override
+  bool operator ==(Object other) =>
+      other is Set && length == other.length && every(other.contains);
+
+  @override
+  int get hashCode => Object.hashAllUnordered(this);
+}
diff --git a/mobile/lib/shared/mentions/mention_tags.dart b/mobile/lib/shared/mentions/mention_tags.dart
new file mode 100644
index 0000000000..bf21282715
--- /dev/null
+++ b/mobile/lib/shared/mentions/mention_tags.dart
@@ -0,0 +1,6 @@
+/// Pubkeys tagged as message mentions, normalized for profile lookups.
+Set<String> mentionedPubkeysFromTags(Iterable<List<String>> tags) => {
+  for (final tag in tags)
+    if (tag.length >= 2 && (tag[0] == 'p' || tag[0] == 'mention'))
+      tag[1].toLowerCase(),
+};
diff --git a/mobile/lib/shared/relay/identity_scoped_prefs.dart b/mobile/lib/shared/relay/identity_scoped_prefs.dart
new file mode 100644
index 0000000000..e080b1ca8c
--- /dev/null
+++ b/mobile/lib/shared/relay/identity_scoped_prefs.dart
@@ -0,0 +1,50 @@
+import 'dart:async';
+
+import 'package:shared_preferences/shared_preferences.dart';
+
+/// Reads an identity-scoped preference, migrating values left under a
+/// pre-canonicalization relay origin.
+///
+/// Identity-scoped keys embed the relay origin, and that origin used to be
+/// whatever scheme the onboarding flow happened to persist — `wss://` for an
+/// invite join, `https://` for device pairing. Now that [RelayConfig.baseUrl]
+/// canonicalizes the scheme, an install that joined by invite would compute a
+/// different key than the one its data was written under, leaving that data on
+/// disk but unreachable.
+///
+/// The value under [canonicalKey] wins. Otherwise a value under [legacyKey] is
+/// returned straight away and promoted onto the canonical key in the
+/// background. The legacy entry is removed only once the copy reports success,
+/// so a migration interrupted mid-flight leaves the original readable and the
+/// next read simply retries.
+///
+/// Pass matching accessors for the stored type — `getString`/`setString`, or
+/// `getStringList`/`setStringList`.
+T? readMigratedPref<T>(
+  SharedPreferences prefs, {
+  required String canonicalKey,
+  required String legacyKey,
+  required T? Function(String key) read,
+  required Future<bool> Function(String key, T value) write,
+}) {
+  final canonical = read(canonicalKey);
+  if (canonical != null) return canonical;
+
+  // Pairing-created communities already store an HTTP origin, so the two keys
+  // coincide and there is nothing to migrate.
+  if (canonicalKey == legacyKey) return null;
+
+  final legacy = read(legacyKey);
+  if (legacy == null) return null;
+
+  unawaited(_promote(prefs, legacyKey, write(canonicalKey, legacy)));
+  return legacy;
+}
+
+Future<void> _promote(
+  SharedPreferences prefs,
+  String legacyKey,
+  Future<bool> copy,
+) async {
+  if (await copy) await prefs.remove(legacyKey);
+}
diff --git a/mobile/lib/shared/relay/relay.dart b/mobile/lib/shared/relay/relay.dart
index d168b9a097..dd153fc928 100644
--- a/mobile/lib/shared/relay/relay.dart
+++ b/mobile/lib/shared/relay/relay.dart
@@ -1,11 +1,14 @@
 export 'app_lifecycle_provider.dart';
+export 'identity_scoped_prefs.dart';
 export 'media_auth.dart';
 export 'media_image.dart';
 export 'media_upload.dart';
 export 'nostr_filters.dart';
 export 'nostr_models.dart';
+export 'relay_closed_policy.dart';
 export 'relay_client.dart';
 export 'relay_provider.dart';
+export 'relay_rate_limit_gate.dart';
 export 'relay_session.dart';
 export 'relay_socket.dart';
 export 'signed_event_relay.dart';
diff --git a/mobile/lib/shared/relay/relay_closed_policy.dart b/mobile/lib/shared/relay/relay_closed_policy.dart
new file mode 100644
index 0000000000..d39084b189
--- /dev/null
+++ b/mobile/lib/shared/relay/relay_closed_policy.dart
@@ -0,0 +1,39 @@
+/// Recovery policy for a relay `CLOSED` subscription message.
+enum RelayClosedClass {
+  /// A transient failure that may recover when the same REQ is retried.
+  retryable,
+
+  /// Relay back-pressure that must also arm the shared request gate.
+  rateLimited,
+
+  /// An authorization, access, or filter failure that cannot recover unchanged.
+  terminal,
+}
+
+/// Classifies whether a relay `CLOSED` message should be retried.
+RelayClosedClass classifyRelayClosed(String message) {
+  final normalized = message.trim().toLowerCase();
+  if (normalized.startsWith('rate-limited:')) {
+    return RelayClosedClass.rateLimited;
+  }
+  if (normalized.startsWith('restricted:') ||
+      normalized.startsWith('auth-required:') ||
+      normalized.startsWith('blocked:') ||
+      normalized.startsWith('invalid:') ||
+      normalized.startsWith('pow:') ||
+      normalized.startsWith('duplicate:') ||
+      normalized.startsWith('unsupported:') ||
+      normalized.startsWith('error: mixed search') ||
+      normalized.startsWith('error: too many subscriptions')) {
+    return RelayClosedClass.terminal;
+  }
+  return RelayClosedClass.retryable;
+}
+
+final _rateLimitRetryPattern = RegExp(r'retry in (\d+)s', caseSensitive: false);
+
+/// Parses the relay's canonical `retry in Ns` hint, when present.
+int? parseRateLimitRetrySeconds(String message) {
+  final match = _rateLimitRetryPattern.firstMatch(message);
+  return match == null ? null : int.tryParse(match.group(1)!);
+}
diff --git a/mobile/lib/shared/relay/relay_provider.dart b/mobile/lib/shared/relay/relay_provider.dart
index 97b88dd3df..061dd6cb38 100644
--- a/mobile/lib/shared/relay/relay_provider.dart
+++ b/mobile/lib/shared/relay/relay_provider.dart
@@ -10,12 +10,46 @@ import 'relay_client.dart';
 ///   - `baseUrl` — where the relay lives (used for WS + media upload)
 ///   - `nsec`    — the user's signing key (drives NIP-42 AUTH and event sigs)
 class RelayConfig {
-  final String baseUrl;
+  const RelayConfig({required String baseUrl, this.nsec}) : _baseUrl = baseUrl;
+
+  /// Relay origin exactly as the active community stored it.
+  final String _baseUrl;
 
   /// Nostr secret key (bech32 nsec) for signing events and NIP-42 AUTH.
   final String? nsec;
 
-  const RelayConfig({required this.baseUrl, this.nsec});
+  /// The origin as persisted, before scheme canonicalization.
+  ///
+  /// Exists solely so identity-scoped storage keys written before [baseUrl]
+  /// was canonicalized stay reachable — see [readMigratedPref]. Never use it
+  /// for network I/O; [baseUrl] and [wsUrl] are the addresses to connect to.
+  String get storedOrigin => _baseUrl;
+
+  /// Relay origin as an HTTP(S) URL.
+  ///
+  /// Communities are persisted with whichever scheme their onboarding flow
+  /// used: device pairing stores `https://` (it rejects anything else), while
+  /// an invite join stores the `wss://` relay URL carried by the invite link.
+  /// Every consumer treats this as an HTTP origin — [wsUrl], the `/query`
+  /// endpoint, media upload and Blossom auth — so a `wss://` base silently
+  /// degrades all of them. Folding the websocket schemes back here keeps both
+  /// onboarding paths equivalent, including for already-persisted communities.
+  ///
+  /// Derived rather than normalized in the constructor so that the constructor
+  /// stays `const`: the compile-time fallback below relies on canonicalization
+  /// to keep its identity stable across rebuilds, and Riverpod's default
+  /// `updateShouldNotify` is `previous != next`, which falls back to identity
+  /// here. A fresh instance per rebuild would resubscribe every listener.
+  String get baseUrl {
+    final uri = Uri.tryParse(_baseUrl);
+    if (uri == null) return _baseUrl;
+    final scheme = switch (uri.scheme) {
+      'wss' => 'https',
+      'ws' => 'http',
+      _ => null,
+    };
+    return scheme == null ? _baseUrl : uri.replace(scheme: scheme).toString();
+  }
 
   /// Derive the websocket URL from the HTTP base URL.
   String get wsUrl {
diff --git a/mobile/lib/shared/relay/relay_rate_limit_gate.dart b/mobile/lib/shared/relay/relay_rate_limit_gate.dart
new file mode 100644
index 0000000000..6164013936
--- /dev/null
+++ b/mobile/lib/shared/relay/relay_rate_limit_gate.dart
@@ -0,0 +1,80 @@
+import 'dart:async';
+import 'dart:math';
+
+/// Creates a timer used by [RelayRateLimitGate].
+typedef RelayTimerFactory =
+    Timer Function(Duration duration, void Function() callback);
+
+/// Session-owned gate that pauses relay requests after back-pressure.
+class RelayRateLimitGate {
+  /// Default gate duration when the relay omits a positive retry hint.
+  static const defaultRetrySeconds = 10;
+
+  /// Longest retry hint accepted from a relay response.
+  static const maxRetrySeconds = 300;
+
+  RelayRateLimitGate({
+    DateTime Function()? now,
+    RelayTimerFactory timerFactory = Timer.new,
+  }) : _now = now ?? DateTime.now,
+       _timerFactory = timerFactory;
+
+  final DateTime Function() _now;
+  final RelayTimerFactory _timerFactory;
+  DateTime? _expiresAt;
+  Timer? _timer;
+  Completer<void>? _completer;
+
+  /// Whether a rate-limit window is currently active.
+  bool get isActive {
+    final expiresAt = _expiresAt;
+    return expiresAt != null && _now().isBefore(expiresAt);
+  }
+
+  /// Activates or extends the gate without shrinking an existing window.
+  void activate(int? retryInSeconds) {
+    final seconds = retryInSeconds != null && retryInSeconds > 0
+        ? min(retryInSeconds, maxRetrySeconds)
+        : defaultRetrySeconds;
+    final duration = Duration(seconds: seconds);
+    final newExpiry = _now().add(duration);
+    final currentExpiry = _expiresAt;
+    if (currentExpiry != null && !newExpiry.isAfter(currentExpiry)) return;
+
+    _expiresAt = newExpiry;
+    _timer?.cancel();
+    _completer ??= Completer<void>();
+    _timer = _timerFactory(duration, _expire);
+  }
+
+  /// Resolves when the active rate-limit window expires.
+  Future<void> wait() {
+    if (!isActive) return Future.value();
+    return _completer!.future;
+  }
+
+  /// Milliseconds remaining in the active window, or zero when inactive.
+  int remainingMs() {
+    final expiresAt = _expiresAt;
+    if (expiresAt == null) return 0;
+    return max(0, expiresAt.difference(_now()).inMilliseconds);
+  }
+
+  /// Clears the gate and releases all current waiters.
+  void reset() {
+    _timer?.cancel();
+    _timer = null;
+    _expiresAt = null;
+    final completer = _completer;
+    _completer = null;
+    if (completer != null && !completer.isCompleted) completer.complete();
+  }
+
+  void _expire() {
+    _timer = null;
+    _expiresAt = null;
+    final completer = _completer;
+    _completer = null;
+    if (completer != null && !completer.isCompleted) completer.complete();
+  }
+}
diff --git a/mobile/lib/shared/relay/relay_session.dart b/mobile/lib/shared/relay/relay_session.dart
index 9c167e10b1..877bd15e82 100644
--- a/mobile/lib/shared/relay/relay_session.dart
+++ b/mobile/lib/shared/relay/relay_session.dart
@@ -13,7 +13,9 @@ import 'package:hooks_riverpod/hooks_riverpod.dart';
 import '../auth/auth.dart';
 import 'nostr_models.dart';
 import 'relay_client.dart';
+import 'relay_closed_policy.dart';
 import 'relay_provider.dart';
+import 'relay_rate_limit_gate.dart';
 import 'relay_socket.dart';
 
 enum SessionStatus { disconnected, connecting, connected, reconnecting }
@@ -40,6 +42,8 @@ class _LiveSubscription {
   final void Function(String message)? onClosed;
   Completer<void>? readyCompleter;
   int? lastSeenCreatedAt;
+  int closedRetryAttempt = 0;
+  Timer? closedRetryTimer;
 
   _LiveSubscription({
     required this.filter,
@@ -49,6 +53,13 @@ class _LiveSubscription {
   });
 }
 
+class _ClosedRetry {
+  final _LiveSubscription subscription;
+  final int generation;
+
+  _ClosedRetry({required this.subscription, required this.generation});
+}
+
 class _PendingEvent {
   final Completer<NostrEvent> completer;
   final Timer timeout;
@@ -78,21 +89,33 @@ class RelaySessionNotifier extends Notifier<SessionState> {
   RelaySessionNotifier({
     http.Client? httpClient,
     RelaySocketFactory socketFactory = RelaySocket.new,
+    RelayRateLimitGate? rateLimitGate,
+    RelayTimerFactory retryTimerFactory = Timer.new,
+    Future<void> Function(Duration) replayDelay = Future.delayed,
   }) : _httpClient = httpClient,
-       _socketFactory = socketFactory;
+       _socketFactory = socketFactory,
+       _rateLimitGate = rateLimitGate ?? RelayRateLimitGate(),
+       _retryTimerFactory = retryTimerFactory,
+       _replayDelay = replayDelay;
 
   final http.Client? _httpClient;
   final RelaySocketFactory _socketFactory;
+  final RelayRateLimitGate _rateLimitGate;
+  final RelayTimerFactory _retryTimerFactory;
+  final Future<void> Function(Duration) _replayDelay;
 
   static const _baseReconnectDelayMs = 1000;
   static const _maxReconnectDelayMs = 30000;
   static const _eventBatchMs = 16;
   static const _reconnectReplaySkewSeconds = 5;
+  static const _replayBatchSize = 8;
+  static const _replayInterBatchDelay = Duration(milliseconds: 50);
   static const _maxRecentDeliveryKeys = 5000;
 
   RelaySocket? _socket;
   final Map<String, _HistorySubscription> _historySubscriptions = {};
   final Map<String, _LiveSubscription> _liveSubscriptions = {};
+  final Map<String, _ClosedRetry> _pendingClosedRetries = {};
   final Map<String, _PendingEvent> _pendingEvents = {};
   final List<_BufferedEvent> _eventBuffer = [];
   final Set<String> _recentDeliveryKeys = {};
@@ -105,6 +128,9 @@ class RelaySessionNotifier extends Notifier<SessionState> {
   bool _paused = false;
   bool _hasConnectedOnce = false;
   int _connectionGeneration = 0;
+  final Map<Object, String> _visibleChannelsByOwner = {};
+  bool _socketConnected = false;
+  bool _closedRetryReplayScheduled = false;
 
   @override
   SessionState build() {
@@ -158,6 +184,7 @@ class RelaySessionNotifier extends Notifier<SessionState> {
           if (shouldCloseClient) client.close();
         });
     if (response.statusCode < 200 || response.statusCode >= 300) {
+      _activateRateLimitGateFromHttpError(response.body);
       throw RelayException(response.statusCode, response.body);
     }
     final decoded = jsonDecode(response.body);
@@ -178,12 +205,30 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     }
   }
 
+  void _activateRateLimitGateFromHttpError(String body) {
+    final dynamic decoded;
+    try {
+      decoded = jsonDecode(body);
+    } on FormatException {
+      return;
+    }
+    if (decoded is! Map<String, dynamic>) return;
+    final message = decoded['error'];
+    if (message is! String ||
+        classifyRelayClosed(message) != RelayClosedClass.rateLimited) {
+      return;
+    }
+    _rateLimitGate.activate(parseRateLimitRetrySeconds(message));
+  }
+
   /// Fetch historical events matching [filter]. Sends REQ, collects events
   /// until EOSE, then resolves. One-shot subscription.
   Future<List<NostrEvent>> fetchHistory(
     NostrFilter filter, {
     Duration timeout = const Duration(seconds: 8),
-  }) {
+  }) async {
+    if (_rateLimitGate.isActive) await _rateLimitGate.wait();
+    if (_disposed) throw StateError('Relay session is disposed');
     final subId = _nextSubId('h');
     final completer = Completer<List<NostrEvent>>();
 
@@ -214,6 +259,7 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     void Function(NostrEvent) onEvent, {
     void Function(String message)? onClosed,
   }) async {
+    if (_disposed) throw StateError('Relay session is disposed');
     final subId = _nextSubId('l');
     final readyCompleter = Completer<void>();
 
@@ -285,11 +331,35 @@ class RelaySessionNotifier extends Notifier<SessionState> {
   void debugFlushEventBuffer() => _flushEventBuffer();
 
   @visibleForTesting
-  void debugHandleConnected() => _handleConnected(_connectionGeneration);
+  Future<void> debugHandleConnected() =>
+      _handleConnected(_connectionGeneration);
+
+  @visibleForTesting
+  Future<void> debugReplayLiveSubscriptions() =>
+      _replayLiveSubscriptions(_connectionGeneration);
+
+  @visibleForTesting
+  void debugDispose() => _dispose();
 
   @visibleForTesting
-  void debugHandleDisconnected([Object? error]) =>
-      _handleDisconnected(_connectionGeneration, error);
+  void debugSupersedeConnection() => _connectionGeneration++;
+
+  @visibleForTesting
+  void debugHandleDisconnected([Object? error]) {
+    _socketConnected = false;
+    _handleDisconnected(_connectionGeneration, error);
+  }
+
+  @visibleForTesting
+  void debugResetClosedRetriesForDisconnect() {
+    _socketConnected = false;
+    _resetAllClosedRetries();
+  }
+
+  @visibleForTesting
+  void debugSetSessionStatus(SessionStatus status) {
+    _socketConnected = status == SessionStatus.connected;
+  }
 
   @visibleForTesting
   void debugPauseNow() => _pauseNow();
@@ -302,11 +372,20 @@ class RelaySessionNotifier extends Notifier<SessionState> {
   void debugAttachSocketForTest(RelaySocket socket) {
     _socket?.dispose();
     _socket = socket;
-    state = const SessionState(status: SessionStatus.connected);
+    _socketConnected = true;
+  }
+
+  /// Registers a visible channel and returns an owner-scoped release callback.
+  /// The most recently registered owner is prioritized during reconnect replay.
+  void Function() registerVisibleChannel(String channelId) {
+    final owner = Object();
+    _visibleChannelsByOwner[owner] = channelId;
+    return () => _visibleChannelsByOwner.remove(owner);
   }
 
   /// Force a reconnect (e.g., returning from background).
   Future<void> reconnect() async {
+    _socketConnected = false;
     await _socket?.disconnect();
     _reconnectDelayMs = _baseReconnectDelayMs;
     final config = ref.read(relayConfigProvider);
@@ -321,6 +400,7 @@ class RelaySessionNotifier extends Notifier<SessionState> {
 
   void _pauseNow() {
     _paused = true;
+    _socketConnected = false;
     _reconnectTimer?.cancel();
     _cancelAllHistory(Exception('App moved to background'));
     _rejectAllPending(Exception('App moved to background'));
@@ -372,18 +452,21 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     await socket.connect();
   }
 
-  void _handleConnected(int generation) {
+  Future<void> _handleConnected(int generation) async {
     if (_disposed || generation != _connectionGeneration) return;
+    _socketConnected = true;
     _hasConnectedOnce = true;
     _reconnectDelayMs = _baseReconnectDelayMs;
     state = const SessionState(status: SessionStatus.connected);
-    _replayLiveSubscriptions();
+    await _replayLiveSubscriptions(generation);
   }
 
   void _handleDisconnected(int generation, Object? error) {
     if (_disposed || generation != _connectionGeneration) return;
+    _socketConnected = false;
     _cancelAllHistory(error);
     _rejectAllPending(error);
+    _resetAllClosedRetries();
     _eventBuffer.clear();
     _flushTimer?.cancel();
     _flushTimer = null;
@@ -413,19 +496,84 @@ class RelaySessionNotifier extends Notifier<SessionState> {
 
   /// Replay all live subscriptions after a reconnect, with a time skew to
   /// catch events that occurred during the disconnect.
-  void _replayLiveSubscriptions() {
-    for (final entry in _liveSubscriptions.entries) {
-      final sub = entry.value;
-      final since = sub.lastSeenCreatedAt != null
-          ? sub.lastSeenCreatedAt! - _reconnectReplaySkewSeconds
-          : null;
-      final filter = since != null
-          ? sub.filter.copyWithSince(since)
-          : sub.filter;
-      _sendReq(entry.key, filter);
+  Future<void> _replayLiveSubscriptions(int generation) async {
+    if (_rateLimitGate.isActive) await _rateLimitGate.wait();
+    if (!_isActiveConnection(generation)) return;
+
+    final entries = _liveSubscriptions.entries.toList();
+    final visibleChannelId = _visibleChannelsByOwner.isEmpty
+        ? null
+        : _visibleChannelsByOwner.values.last;
+    if (visibleChannelId != null) {
+      entries.sort((left, right) {
+        final leftVisible =
+            left.value.filter.tags['#h']?.contains(visibleChannelId) ?? false;
+        final rightVisible =
+            right.value.filter.tags['#h']?.contains(visibleChannelId) ?? false;
+        if (leftVisible == rightVisible) return 0;
+        return leftVisible ? -1 : 1;
+      });
+    }
+
+    await _sendReplayBatches(entries, generation);
+  }
+
+  Future<void> _replayPendingClosedRetries(int generation) async {
+    if (!_isActiveConnection(generation)) return;
+    final entries = _pendingClosedRetries.entries
+        .where((entry) => entry.value.generation == generation)
+        .map(
+          (entry) => MapEntry<String, _LiveSubscription>(
+            entry.key,
+            entry.value.subscription,
+          ),
+        )
+        .toList();
+    await _sendReplayBatches(entries, generation, pendingClosedRetries: true);
+  }
+
+  Future<void> _sendReplayBatches(
+    List<MapEntry<String, _LiveSubscription>> entries,
+    int generation, {
+    bool pendingClosedRetries = false,
+  }) async {
+    for (var i = 0; i < entries.length; i += _replayBatchSize) {
+      if (_rateLimitGate.isActive) await _rateLimitGate.wait();
+      if (!_isActiveConnection(generation)) return;
+      final batch = entries.sublist(
+        i,
+        min(i + _replayBatchSize, entries.length),
+      );
+      for (final entry in batch) {
+        if (_liveSubscriptions[entry.key] != entry.value) continue;
+        if (pendingClosedRetries) {
+          final pendingRetry = _pendingClosedRetries[entry.key];
+          if (pendingRetry?.subscription != entry.value ||
+              pendingRetry?.generation != generation) {
+            continue;
+          }
+          _pendingClosedRetries.remove(entry.key);
+        }
+        _sendReq(entry.key, _replayFilter(entry.value));
+      }
+      if (i + _replayBatchSize < entries.length) {
+        await _replayDelay(_replayInterBatchDelay);
+      }
     }
   }
 
+  bool _isActiveConnection(int generation) =>
+      !_disposed && generation == _connectionGeneration;
+
+  NostrFilter _replayFilter(_LiveSubscription subscription) {
+    final since = subscription.lastSeenCreatedAt;
+    return since == null
+        ? subscription.filter
+        : subscription.filter.copyWithSince(
+            max(0, since - _reconnectReplaySkewSeconds),
+          );
+  }
+
   void _handleMessage(List<dynamic> data) {
     if (data.isEmpty) return;
     final type = data[0] as String;
@@ -458,6 +606,7 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     // Live subscriptions get batched.
     final liveSub = _liveSubscriptions[subId];
     if (liveSub != null) {
+      _resetClosedRetry(liveSub);
       // Track last seen timestamp for reconnect replay.
       if (liveSub.lastSeenCreatedAt == null ||
           event.createdAt > liveSub.lastSeenCreatedAt!) {
@@ -485,9 +634,17 @@ class RelaySessionNotifier extends Notifier<SessionState> {
 
     // Live subscription: signal ready.
     final liveSub = _liveSubscriptions[subId];
+    if (liveSub != null) {
+      _resetClosedRetry(liveSub);
+    }
     if (liveSub != null &&
         liveSub.readyCompleter != null &&
         !liveSub.readyCompleter!.isCompleted) {
+      // EOSE is the boundary between replay and live delivery. Flush any
+      // replay events before resolving subscribe(), so callers that begin a
+      // one-shot query immediately afterwards cannot classify a delayed batch
+      // callback as having arrived during that query.
+      _flushBufferedEventsNow();
       liveSub.readyCompleter!.complete();
       liveSub.readyCompleter = null;
     }
@@ -499,9 +656,13 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     final message = data.length >= 3 && data[2] is String
         ? data[2] as String
         : 'subscription closed by relay';
+    final closedClass = classifyRelayClosed(message);
 
     final historySub = _historySubscriptions.remove(subId);
     if (historySub != null) {
+      if (closedClass == RelayClosedClass.rateLimited) {
+        _rateLimitGate.activate(parseRateLimitRetrySeconds(message));
+      }
       historySub.timeout.cancel();
       if (!historySub.completer.isCompleted) {
         historySub.completer.completeError(Exception(message));
@@ -509,17 +670,87 @@ class RelaySessionNotifier extends Notifier<SessionState> {
       return;
     }
 
-    final liveSub = _liveSubscriptions.remove(subId);
+    final liveSub = _liveSubscriptions[subId];
     if (liveSub == null) return;
-    _recentDeliveryKeys.removeWhere((key) => key.startsWith('$subId:'));
-
     final readyCompleter = liveSub.readyCompleter;
-    if (readyCompleter != null && !readyCompleter.isCompleted) {
-      readyCompleter.completeError(Exception(message));
+    if (closedClass == RelayClosedClass.terminal) {
+      if (readyCompleter != null && !readyCompleter.isCompleted) {
+        readyCompleter.completeError(Exception(message));
+      }
+      liveSub.onClosed?.call(message);
+      _removeLiveSubscription(subId, liveSub);
       return;
     }
+    if (readyCompleter != null && !readyCompleter.isCompleted) {
+      readyCompleter.complete();
+      liveSub.readyCompleter = null;
+    }
+    if (liveSub.closedRetryTimer != null) return;
+
+    final attempt = liveSub.closedRetryAttempt;
+    final backoffMs = attempt >= 5
+        ? _maxReconnectDelayMs
+        : _baseReconnectDelayMs * (1 << attempt);
+    var delayMs = backoffMs;
+    if (closedClass == RelayClosedClass.rateLimited) {
+      final retrySeconds = parseRateLimitRetrySeconds(message);
+      _rateLimitGate.activate(retrySeconds);
+      final fallbackMs =
+          (retrySeconds != null && retrySeconds > 0
+              ? min(retrySeconds, RelayRateLimitGate.maxRetrySeconds)
+              : RelayRateLimitGate.defaultRetrySeconds) *
+          1000;
+      delayMs = max(
+        backoffMs,
+        _rateLimitGate.remainingMs() == 0
+            ? fallbackMs
+            : _rateLimitGate.remainingMs(),
+      );
+    }
 
-    liveSub.onClosed?.call(message);
+    liveSub.closedRetryAttempt = attempt + 1;
+    final retryGeneration = _connectionGeneration;
+    liveSub.closedRetryTimer = _retryTimerFactory(
+      Duration(milliseconds: delayMs),
+      () async {
+        liveSub.closedRetryTimer = null;
+        if (!_isActiveConnection(retryGeneration) ||
+            _liveSubscriptions[subId] != liveSub) {
+          return;
+        }
+        if (_rateLimitGate.isActive) await _rateLimitGate.wait();
+        if (!_isActiveConnection(retryGeneration) ||
+            _liveSubscriptions[subId] != liveSub ||
+            !_socketConnected) {
+          return;
+        }
+        _pendingClosedRetries[subId] = _ClosedRetry(
+          subscription: liveSub,
+          generation: retryGeneration,
+        );
+        _scheduleClosedRetryReplay(retryGeneration);
+      },
+    );
+  }
+
+  void _scheduleClosedRetryReplay(int generation) {
+    if (_closedRetryReplayScheduled) return;
+    _closedRetryReplayScheduled = true;
+    scheduleMicrotask(() async {
+      try {
+        await _replayPendingClosedRetries(generation);
+      } finally {
+        _closedRetryReplayScheduled = false;
+        _pendingClosedRetries.removeWhere(
+          (_, retry) => retry.generation != _connectionGeneration,
+        );
+        if (_pendingClosedRetries.values.any(
+          (retry) => retry.generation == _connectionGeneration,
+        )) {
+          _scheduleClosedRetryReplay(_connectionGeneration);
+        }
+      }
+    });
   }
 
   void _handleOk(List<dynamic> data) {
@@ -567,6 +798,12 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     );
   }
 
+  void _flushBufferedEventsNow() {
+    _flushTimer?.cancel();
+    _flushTimer = null;
+    _flushEventBuffer();
+  }
+
   void _flushEventBuffer() {
     _flushTimer = null;
     if (_eventBuffer.isEmpty) return;
@@ -608,9 +845,41 @@ class RelaySessionNotifier extends Notifier<SessionState> {
   }
 
   void _unsubscribe(String subId) {
+    final subscription = _liveSubscriptions[subId];
+    if (subscription != null) {
+      _removeLiveSubscription(subId, subscription);
+    }
+    _sendClose(subId);
+  }
+
+  void _removeLiveSubscription(String subId, _LiveSubscription subscription) {
+    if (_liveSubscriptions[subId] != subscription) return;
     _liveSubscriptions.remove(subId);
+    _pendingClosedRetries.remove(subId);
+    subscription.closedRetryTimer?.cancel();
+    subscription.closedRetryTimer = null;
     _recentDeliveryKeys.removeWhere((key) => key.startsWith('$subId:'));
-    _sendClose(subId);
+  }
+
+  void _resetClosedRetry(_LiveSubscription subscription) {
+    subscription.closedRetryAttempt = 0;
+    subscription.closedRetryTimer?.cancel();
+    subscription.closedRetryTimer = null;
+  }
+
+  void _cancelAllClosedRetries() {
+    _pendingClosedRetries.clear();
+    for (final subscription in _liveSubscriptions.values) {
+      subscription.closedRetryTimer?.cancel();
+      subscription.closedRetryTimer = null;
+    }
+  }
+
+  void _resetAllClosedRetries() {
+    _pendingClosedRetries.clear();
+    for (final subscription in _liveSubscriptions.values) {
+      _resetClosedRetry(subscription);
+    }
   }
 
   void _cancelAllHistory(Object? error) {
@@ -639,8 +908,18 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     _reconnectTimer?.cancel();
     _flushTimer?.cancel();
     _backgroundGraceTimer?.cancel();
+    _cancelAllClosedRetries();
+    _rateLimitGate.reset();
+    _visibleChannelsByOwner.clear();
+    _socketConnected = false;
     _cancelAllHistory(null);
     _rejectAllPending(null);
+    final subscriptions = _liveSubscriptions.values.toList();
+    _liveSubscriptions.clear();
+    for (final subscription in subscriptions) {
+      subscription.closedRetryTimer?.cancel();
+      subscription.closedRetryTimer = null;
+    }
     _recentDeliveryKeys.clear();
     _socket?.dispose();
     _socket = null;
diff --git a/mobile/lib/features/activity/activity_page/popover_menu.dart b/mobile/lib/shared/widgets/anchored_popover_menu.dart
similarity index 79%
rename from mobile/lib/features/activity/activity_page/popover_menu.dart
rename to mobile/lib/shared/widgets/anchored_popover_menu.dart
index 56d0a612ec..46b50b6b00 100644
--- a/mobile/lib/features/activity/activity_page/popover_menu.dart
+++ b/mobile/lib/shared/widgets/anchored_popover_menu.dart
@@ -1,16 +1,30 @@
-part of '../activity_page.dart';
+import 'dart:math' as math;
+import 'dart:ui' show SemanticsRole;
 
-const _activityPopoverEnterDuration = Duration(milliseconds: 150);
-const _activityPopoverExitDuration = Duration(milliseconds: 110);
-const _activityPopoverStartScale = 0.96;
+import 'package:flutter/material.dart';
 
-enum _ActivityPopoverAlignment { start, end }
+import '../theme/theme.dart';
 
-Future<T?> _showActivityPopover<T>({
+const _popoverEnterDuration = Duration(milliseconds: 150);
+const _popoverExitDuration = Duration(milliseconds: 110);
+const _popoverStartScale = 0.96;
+
+/// The horizontal edge a popover aligns to on its triggering control.
+enum AnchoredPopoverAlignment {
+  /// Aligns the popover's leading edge with the trigger's leading edge.
+  start,
+
+  /// Aligns the popover's trailing edge with the trigger's trailing edge.
+  end,
+}
+
+/// Shows an anchored, cross-platform popup menu with the Activity controls'
+/// sizing, motion, and safe-area placement.
+Future<T?> showAnchoredPopover<T>({
   required BuildContext context,
   required List<PopupMenuEntry<T>> items,
   required double width,
-  required _ActivityPopoverAlignment alignment,
+  required AnchoredPopoverAlignment alignment,
   required Color color,
   required ShapeBorder shape,
   required double elevation,
@@ -36,7 +50,7 @@ Future<T?> _showActivityPopover<T>({
   final mediaQuery = MediaQuery.of(context);
 
   return navigator.push<T>(
-    _ActivityPopoverRoute<T>(
+    _AnchoredPopoverRoute<T>(
       position: RelativeRect.fromRect(triggerRect, overlayRect),
       items: items,
       width: width,
@@ -61,11 +75,11 @@ Future<T?> _showActivityPopover<T>({
   );
 }
 
-class _ActivityPopoverRoute<T> extends PopupRoute<T> {
+class _AnchoredPopoverRoute<T> extends PopupRoute<T> {
   final RelativeRect position;
   final List<PopupMenuEntry<T>> items;
   final double width;
-  final _ActivityPopoverAlignment alignment;
+  final AnchoredPopoverAlignment alignment;
   final Offset offset;
   final Color color;
   final ShapeBorder shape;
@@ -78,7 +92,7 @@ class _ActivityPopoverRoute<T> extends PopupRoute<T> {
   final bool reducedMotion;
   final String _barrierLabel;
 
-  _ActivityPopoverRoute({
+  _AnchoredPopoverRoute({
     required this.position,
     required this.items,
     required this.width,
@@ -107,11 +121,11 @@ class _ActivityPopoverRoute<T> extends PopupRoute<T> {
 
   @override
   Duration get transitionDuration =>
-      reducedMotion ? Duration.zero : _activityPopoverEnterDuration;
+      reducedMotion ? Duration.zero : _popoverEnterDuration;
 
   @override
   Duration get reverseTransitionDuration =>
-      reducedMotion ? Duration.zero : _activityPopoverExitDuration;
+      reducedMotion ? Duration.zero : _popoverExitDuration;
 
   @override
   Widget buildPage(
@@ -123,16 +137,16 @@ class _ActivityPopoverRoute<T> extends PopupRoute<T> {
       CurveTween(curve: Curves.easeOutCubic),
     );
     final scaleAnimation = Tween<double>(
-      begin: _activityPopoverStartScale,
+      begin: _popoverStartScale,
       end: 1,
     ).animate(curvedAnimation);
     final transformOrigin = switch (alignment) {
-      _ActivityPopoverAlignment.start => Alignment.topLeft,
-      _ActivityPopoverAlignment.end => Alignment.topRight,
+      AnchoredPopoverAlignment.start => Alignment.topLeft,
+      AnchoredPopoverAlignment.end => Alignment.topRight,
     };
 
     return CustomSingleChildLayout(
-      delegate: _ActivityPopoverLayoutDelegate(
+      delegate: _AnchoredPopoverLayoutDelegate(
         position: position,
         alignment: alignment,
         offset: offset,
@@ -174,13 +188,13 @@ class _ActivityPopoverRoute<T> extends PopupRoute<T> {
   }
 }
 
-class _ActivityPopoverLayoutDelegate extends SingleChildLayoutDelegate {
+class _AnchoredPopoverLayoutDelegate extends SingleChildLayoutDelegate {
   final RelativeRect position;
-  final _ActivityPopoverAlignment alignment;
+  final AnchoredPopoverAlignment alignment;
   final Offset offset;
   final EdgeInsets screenPadding;
 
-  const _ActivityPopoverLayoutDelegate({
+  const _AnchoredPopoverLayoutDelegate({
     required this.position,
     required this.alignment,
     required this.offset,
@@ -201,8 +215,8 @@ class _ActivityPopoverLayoutDelegate extends SingleChildLayoutDelegate {
   Offset getPositionForChild(Size size, Size childSize) {
     final anchorBottom = size.height - position.bottom;
     final desiredX = switch (alignment) {
-      _ActivityPopoverAlignment.start => position.left + offset.dx,
-      _ActivityPopoverAlignment.end =>
+      AnchoredPopoverAlignment.start => position.left + offset.dx,
+      AnchoredPopoverAlignment.end =>
         size.width - position.right - childSize.width + offset.dx,
     };
     final minX = screenPadding.left;
@@ -222,7 +236,7 @@ class _ActivityPopoverLayoutDelegate extends SingleChildLayoutDelegate {
   }
 
   @override
-  bool shouldRelayout(_ActivityPopoverLayoutDelegate oldDelegate) {
+  bool shouldRelayout(_AnchoredPopoverLayoutDelegate oldDelegate) {
     return position != oldDelegate.position ||
         alignment != oldDelegate.alignment ||
         offset != oldDelegate.offset ||
diff --git a/mobile/lib/shared/widgets/frosted_scaffold.dart b/mobile/lib/shared/widgets/frosted_scaffold.dart
index 6b7e39fd75..fc0e2fe506 100644
--- a/mobile/lib/shared/widgets/frosted_scaffold.dart
+++ b/mobile/lib/shared/widgets/frosted_scaffold.dart
@@ -21,17 +21,23 @@ class FrostedScaffold extends StatelessWidget {
   /// Whether the body should resize when the on-screen keyboard appears.
   final bool? resizeToAvoidBottomInset;
 
+  /// Optional scaffold background, useful when a parent supplies a shared
+  /// surface behind this page.
+  final Color? backgroundColor;
+
   const FrostedScaffold({
     super.key,
     required this.appBar,
     required this.body,
     this.floatingActionButton,
     this.resizeToAvoidBottomInset,
+    this.backgroundColor,
   });
 
   @override
   Widget build(BuildContext context) {
     return Scaffold(
+      backgroundColor: backgroundColor,
       resizeToAvoidBottomInset: resizeToAvoidBottomInset,
       floatingActionButton: floatingActionButton,
       body: Stack(children: [body, appBar]),
diff --git a/mobile/lib/shared/widgets/keyboard_dismiss_on_drag.dart b/mobile/lib/shared/widgets/keyboard_dismiss_on_drag.dart
new file mode 100644
index 0000000000..f562b9f83a
--- /dev/null
+++ b/mobile/lib/shared/widgets/keyboard_dismiss_on_drag.dart
@@ -0,0 +1,98 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_hooks/flutter_hooks.dart';
+
+/// How far a finger must travel downward before the keyboard is dismissed.
+///
+/// Large enough that reading-speed scrolling never trips it, small enough that
+/// a deliberate "push it away" swipe feels immediate.
+const keyboardDismissDragThreshold = 48.0;
+
+/// Dismiss the software keyboard when the user deliberately drags downward.
+///
+/// Flutter only offers `ScrollViewKeyboardDismissBehavior.manual` and `.onDrag`
+/// — and `.onDrag` fires the instant a drag begins, so a one-pixel scroll to
+/// re-read a message would tear the keyboard away. Neither is available on
+/// `ScrollablePositionedList` regardless, which is what both message lists use.
+///
+/// So: accumulate raw finger travel and only unfocus once a downward drag
+/// clears [keyboardDismissDragThreshold]. Any upward movement resets the
+/// accumulator, so a scroll that wanders up and down never adds up to a
+/// dismissal.
+///
+/// This tracks the *finger*, not the scroll direction, so it behaves the same
+/// in the reversed channel timeline and the top-anchored thread list. It is not
+/// interactive dismissal — the keyboard animates away on the OS's own curve
+/// rather than following the finger, which Flutter can't do without a native
+/// plugin (iOS `UIScrollView.keyboardDismissMode`, Android
+/// `WindowInsetsAnimationController`).
+class KeyboardDismissOnDrag extends HookWidget {
+  final Widget child;
+
+  const KeyboardDismissOnDrag({super.key, required this.child});
+
+  @override
+  Widget build(BuildContext context) {
+    // A ref, not state: accumulating travel must never trigger a rebuild of
+    // the message list this wraps.
+    final downwardTravel = useRef(0.0);
+
+    bool handle(ScrollNotification notification) {
+      if (notification is ScrollStartNotification ||
+          notification is ScrollEndNotification) {
+        downwardTravel.value = 0;
+        return false;
+      }
+
+      // Overscroll counts as much as ordinary scrolling. You focus the composer
+      // at the resting end of the list far more often than not, and there a
+      // downward drag moves the position nowhere — it is pure overscroll, and
+      // reports `OverscrollNotification` instead. Listening only for
+      // `ScrollUpdateNotification` meant the most common dismissal gesture in
+      // both lists produced no notification this saw at all.
+      final DragUpdateDetails? drag;
+      if (notification is ScrollUpdateNotification) {
+        drag = notification.dragDetails;
+      } else if (notification is OverscrollNotification) {
+        drag = notification.dragDetails;
+      } else {
+        return false;
+      }
+
+      // Null during a momentum fling — only a finger still on the glass should
+      // dismiss, so a fling that coasts downward leaves the keyboard up.
+      if (drag == null) {
+        downwardTravel.value = 0;
+        return false;
+      }
+
+      final dy = drag.delta.dy;
+      if (dy <= 0) {
+        downwardTravel.value = 0;
+        return false;
+      }
+
+      downwardTravel.value += dy;
+      if (downwardTravel.value < keyboardDismissDragThreshold) return false;
+      downwardTravel.value = 0;
+      dismissKeyboard(context);
+      return false;
+    }
+
+    return NotificationListener<ScrollNotification>(
+      onNotification: handle,
+      child: child,
+    );
+  }
+}
+
+/// Drop focus so the OS retracts the keyboard. No-op when nothing is focused
+/// or the keyboard is already down, so callers can fire it freely.
+void dismissKeyboard(BuildContext context) {
+  // Read the view's own insets, not MediaQuery's. `Scaffold` strips the bottom
+  // view inset from its body while `resizeToAvoidBottomInset` is on — it has
+  // already resized to account for it — so a MediaQuery read from anywhere
+  // inside the body reports 0 whether the keyboard is up or not, which made
+  // this gate a permanent no-op for both message lists and the compose bar.
+  if (View.of(context).viewInsets.bottom <= 0) return;
+  FocusManager.instance.primaryFocus?.unfocus();
+}
diff --git a/mobile/lib/shared/widgets/message_author_meta.dart b/mobile/lib/shared/widgets/message_author_meta.dart
index bc69506cc9..c7aff7df82 100644
--- a/mobile/lib/shared/widgets/message_author_meta.dart
+++ b/mobile/lib/shared/widgets/message_author_meta.dart
@@ -83,7 +83,7 @@ class MessageAuthorMeta extends StatelessWidget {
         return Row(
           crossAxisAlignment: CrossAxisAlignment.center,
           children: [
-            Expanded(child: authorName),
+            Flexible(child: authorName),
             if (showUsername) ...[
               const SizedBox(width: Grid.half),
               ConstrainedBox(
diff --git a/mobile/lib/shared/widgets/mobile_tab_footer_backdrop.dart b/mobile/lib/shared/widgets/mobile_tab_footer_backdrop.dart
new file mode 100644
index 0000000000..687880acb1
--- /dev/null
+++ b/mobile/lib/shared/widgets/mobile_tab_footer_backdrop.dart
@@ -0,0 +1,61 @@
+import 'package:flutter/material.dart';
+
+import '../theme/theme.dart';
+
+/// Height of the floating mobile tab bar, excluding its bottom clearance.
+const mobileTabBarHeight = 56.0;
+
+/// Gap between the floating mobile tab bar and the bottom safe area.
+const mobileTabBarBottomGap = Grid.twelve;
+
+/// Returns the shared footer backdrop height, including the logical safe area.
+double mobileTabFooterBackdropHeight(BuildContext context) =>
+    mobileTabBarHeight +
+    mobileTabBarBottomGap +
+    MediaQuery.paddingOf(context).bottom +
+    Grid.xl +
+    Grid.gutter;
+
+/// Shared fade behind the floating mobile tab bar.
+class MobileTabFooterBackdrop extends StatelessWidget {
+  /// Vertical extent of the backdrop in logical pixels.
+  final double height;
+
+  /// Gradient stop positions, from the transparent top to the opaque bottom.
+  final List<double> stops;
+
+  /// Surface-color alpha values paired with [stops].
+  final List<double> opacities;
+
+  /// Creates a footer backdrop with the required [height].
+  ///
+  /// Override [stops] and [opacities] together to customize the gradient.
+  const MobileTabFooterBackdrop({
+    super.key,
+    required this.height,
+    this.stops = const [0, 0.5, 1],
+    this.opacities = const [0, 0.75, 1],
+  }) : assert(stops.length == opacities.length);
+
+  @override
+  Widget build(BuildContext context) {
+    final surface = context.colors.surface;
+    return SizedBox(
+      height: height,
+      width: double.infinity,
+      child: DecoratedBox(
+        decoration: BoxDecoration(
+          gradient: LinearGradient(
+            begin: Alignment.topCenter,
+            end: Alignment.bottomCenter,
+            stops: stops,
+            colors: [
+              for (final opacity in opacities)
+                surface.withValues(alpha: opacity),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+}
diff --git a/mobile/pubspec.lock b/mobile/pubspec.lock
index 61d7fd58e4..05ccc2ea0f 100644
--- a/mobile/pubspec.lock
+++ b/mobile/pubspec.lock
@@ -170,7 +170,7 @@ packages:
     source: hosted
     version: "0.3.5+4"
   characters:
-    dependency: transitive
+    dependency: "direct main"
     description:
       name: characters
       sha256: faf38497bda5ead2a8c7615f4f7939df04333478bf32e4173fcb06d428b5716b
diff --git a/mobile/pubspec.yaml b/mobile/pubspec.yaml
index b525926288..42b7935582 100644
--- a/mobile/pubspec.yaml
+++ b/mobile/pubspec.yaml
@@ -9,6 +9,10 @@ environment:
 dependencies:
   flutter:
     sdk: flutter
+  # Grapheme-cluster segmentation, for deciding whether a message body is
+  # nothing but emoji. Already present transitively via the Flutter SDK;
+  # declared here because we import it directly.
+  characters: ^1.4.0
   hooks_riverpod: ^3.0.3
   flutter_hooks: ^0.21.3
   lucide_icons_flutter: ^3.1.0
@@ -51,6 +55,9 @@ flutter:
   uses-material-design: true
   assets:
     - assets/images/buzz-icon.png
+    # Generated by `just mobile-emoji-data` from the same emoji-mart dataset
+    # desktop uses. Do not hand-edit.
+    - assets/emoji/emoji-data.json
   fonts:
     - family: Inter
       fonts:
diff --git a/mobile/scripts/generate-emoji-data.mjs b/mobile/scripts/generate-emoji-data.mjs
new file mode 100644
index 0000000000..0b92d0c64e
--- /dev/null
+++ b/mobile/scripts/generate-emoji-data.mjs
@@ -0,0 +1,84 @@
+/**
+ * Generate the mobile emoji dataset from emoji-mart.
+ *
+ * Desktop's emoji picker, autocomplete, and reaction display names all read
+ * `@emoji-mart/data/sets/15/native.json` (see
+ * `desktop/src/features/custom-emoji/ui/EmojiPicker.tsx` and
+ * `desktop/src/shared/lib/emojiName.ts`). Mobile can't consume the npm package,
+ * so this script projects the same source into a trimmed JSON asset that ships
+ * with the Flutter app. Same ids, same names, same keywords, same category
+ * order — so a `:shortcode:` means the same thing on both clients.
+ *
+ * The output is committed. Regenerate with `just mobile-emoji-data` after
+ * bumping the emoji-mart dependency.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const mobileRoot = path.resolve(__dirname, "..");
+const repoRoot = path.resolve(mobileRoot, "..");
+
+const DATA_SUBPATH = "@emoji-mart/data/sets/15/native.json";
+// `EMOJI_MART_DATA` lets a git worktree (which has no desktop/node_modules of
+// its own) point at the main checkout's install instead of paying for a full
+// `pnpm install` just to regenerate a committed asset.
+const SOURCE =
+  process.env.EMOJI_MART_DATA ??
+  path.join(repoRoot, "desktop/node_modules", DATA_SUBPATH);
+const OUTPUT = path.join(mobileRoot, "assets/emoji/emoji-data.json");
+
+let raw;
+try {
+  raw = readFileSync(SOURCE, "utf8");
+} catch {
+  console.error(
+    `Missing emoji-mart data at ${SOURCE}.\n` +
+      "Run `pnpm install` in desktop/ first — this script projects the same\n" +
+      "dataset the desktop picker uses so the two clients cannot drift.\n" +
+      "From a worktree, point EMOJI_MART_DATA at the main checkout's copy:\n" +
+      `  EMOJI_MART_DATA=<main-checkout>/desktop/node_modules/${DATA_SUBPATH}`,
+  );
+  process.exit(1);
+}
+
+const data = JSON.parse(raw);
+
+// Category order is emoji-mart's own, which is the order desktop's picker
+// renders. Preserve it verbatim rather than re-sorting.
+const categories = data.categories.map((category) => ({
+  id: category.id,
+  emoji: category.emojis.filter((id) => {
+    const entry = data.emojis[id];
+    return Boolean(entry?.skins?.some((skin) => skin.native));
+  }),
+}));
+
+// Keys are deliberately short (`n`/`u`/`k`) — the map is ~1.9k entries and the
+// asset ships in the app bundle.
+const emoji = {};
+for (const category of categories) {
+  for (const id of category.emoji) {
+    const entry = data.emojis[id];
+    emoji[id] = {
+      n: entry.name,
+      // Keep every skin variation. The app flattens these into selectable
+      // tiles and maps every glyph back to this desktop-identical shortcode.
+      u: entry.skins.map((skin) => skin.native).filter(Boolean),
+      k: entry.keywords ?? [],
+    };
+  }
+}
+
+const payload = { categories, emoji };
+
+mkdirSync(path.dirname(OUTPUT), { recursive: true });
+// Trailing newline keeps the file diff-friendly; no indentation because the
+// asset is machine-read only and indentation would roughly double its size.
+writeFileSync(OUTPUT, `${JSON.stringify(payload)}\n`, "utf8");
+
+console.log(
+  `Wrote ${path.relative(repoRoot, OUTPUT)} — ` +
+    `${categories.length} categories, ${Object.keys(emoji).length} emoji.`,
+);
diff --git a/mobile/test/features/activity/activity_page_test.dart b/mobile/test/features/activity/activity_page_test.dart
index 19b170b52a..a0293455f2 100644
--- a/mobile/test/features/activity/activity_page_test.dart
+++ b/mobile/test/features/activity/activity_page_test.dart
@@ -182,6 +182,18 @@ void main() {
     expect(find.byTooltip('Back'), findsNothing);
   });
 
+  testWidgets('keeps bottom clearance for the floating tab bar', (
+    tester,
+  ) async {
+    await tester.pumpWidget(await buildTestable());
+    await tester.pumpAndSettle();
+
+    final safeAreas = tester.widgetList<SafeArea>(find.byType(SafeArea));
+    expect(safeAreas, hasLength(1));
+    expect(safeAreas.single.top, isFalse);
+    expect(safeAreas.single.bottom, isTrue);
+  });
+
   testWidgets('shows error view with retry button', (tester) async {
     await tester.pumpWidget(
       await buildTestable(activityNotifier: _ErrorActivityNotifier.new),
diff --git a/mobile/test/features/activity/compose_drafts_provider_test.dart b/mobile/test/features/activity/compose_drafts_provider_test.dart
index 1f93dcb674..15899e6597 100644
--- a/mobile/test/features/activity/compose_drafts_provider_test.dart
+++ b/mobile/test/features/activity/compose_drafts_provider_test.dart
@@ -34,6 +34,35 @@ void main() {
     return container;
   }
 
+  test(
+    'an invite-joined community keeps its drafts after origin canonicalization',
+    () async {
+      // Written by a build that stored the invite link's wss:// origin
+      // verbatim; RelayConfig now canonicalizes that to https://, so the key
+      // the app computes no longer matches the key on disk.
+      const legacyKey = 'compose_drafts_v1:wss://relay-a.example:pk_a';
+      const canonicalKey = 'compose_drafts_v1:https://relay-a.example:pk_a';
+      SharedPreferences.setMockInitialValues({
+        legacyKey:
+            '[{"key":"ch1","channel_id":"ch1","text":"unsent work",'
+            '"updated_at":1700000000}]',
+      });
+
+      final container = await containerWithPrefs(
+        relayUrl: 'wss://relay-a.example',
+      );
+
+      final drafts = container.read(composeDraftsProvider);
+      expect(drafts, hasLength(1), reason: 'draft survives the upgrade');
+      expect(drafts.single.text, 'unsent work');
+
+      await Future<void>.delayed(Duration.zero);
+      final prefs = await SharedPreferences.getInstance();
+      expect(prefs.getString(canonicalKey), isNotNull);
+      expect(prefs.getString(legacyKey), isNull);
+    },
+  );
+
   test('composeDraftKey separates channel and thread composers', () {
     expect(composeDraftKey('ch1'), 'ch1');
     expect(composeDraftKey('ch1', threadHeadId: 't1'), 'ch1:t1');
diff --git a/mobile/test/features/channels/channel_detail_page_test.dart b/mobile/test/features/channels/channel_detail_page_test.dart
index 2dc01a9a0b..f95c6fefed 100644
--- a/mobile/test/features/channels/channel_detail_page_test.dart
+++ b/mobile/test/features/channels/channel_detail_page_test.dart
@@ -1,3 +1,4 @@
+import 'dart:async';
 import 'dart:convert';
 
 import 'package:flutter/foundation.dart';
@@ -14,6 +15,7 @@ import 'package:buzz/features/channels/channel_messages_provider.dart';
 import 'package:buzz/features/channels/channel_typing_provider.dart';
 import 'package:buzz/features/channels/date_formatters.dart';
 import 'package:buzz/features/channels/day_divider.dart';
+import 'package:buzz/features/channels/emoji_picker.dart';
 import 'package:buzz/features/channels/reaction_row.dart';
 import 'package:buzz/features/channels/thread_detail_page.dart';
 import 'package:buzz/features/channels/thread_replies_provider.dart';
@@ -24,6 +26,7 @@ import 'package:buzz/features/channels/small_avatar.dart';
 import 'package:buzz/features/profile/profile_provider.dart';
 import 'package:buzz/features/profile/user_cache_provider.dart';
 import 'package:buzz/features/profile/user_profile.dart';
+import 'package:buzz/shared/mentions/agent_identity_provider.dart';
 import 'package:buzz/shared/relay/relay.dart';
 import 'package:buzz/shared/theme/theme.dart';
 import 'package:buzz/shared/widgets/skeleton.dart';
@@ -153,6 +156,7 @@ Widget _buildTestable({
   String? initialMessageId,
   String? initialThreadRootId,
   Map<String, List<NostrEvent>> threadReplies = const {},
+  Map<String, Future<List<NostrEvent>>> pendingThreadReplies = const {},
   TextScaler textScaler = TextScaler.noScaling,
   RelaySessionNotifier? relaySessionNotifier,
 }) {
@@ -185,6 +189,9 @@ Widget _buildTestable({
       channelMembersProvider(_channelId).overrideWith(
         (ref) async => loadMembers != null ? loadMembers() : members,
       ),
+      channelBotPubkeysProvider(
+        _channelId,
+      ).overrideWith((ref) async => const <String>{}),
       if (createChannelActions != null)
         channelActionsProvider.overrideWith(createChannelActions),
       if (readStateNotifier != null)
@@ -193,6 +200,10 @@ Widget _buildTestable({
         threadRepliesProvider(
           ThreadRepliesArgs(channelId: _channelId, rootId: entry.key),
         ).overrideWith((ref) async => entry.value),
+      for (final entry in pendingThreadReplies.entries)
+        threadRepliesProvider(
+          ThreadRepliesArgs(channelId: _channelId, rootId: entry.key),
+        ).overrideWith((ref) => entry.value),
       // Stub the relay client provider so preloadMembers doesn't crash.
       relayClientProvider.overrideWithValue(
         RelayClient(baseUrl: 'http://localhost:3000'),
@@ -218,6 +229,55 @@ Widget _buildTestable({
   );
 }
 
+Widget _buildNavigationTestable({
+  required Channel channelA,
+  required Channel channelB,
+  required RelaySessionNotifier relaySession,
+}) {
+  return ProviderScope(
+    overrides: [
+      relaySessionProvider.overrideWith(() => relaySession),
+      channelMessagesProvider(
+        channelA.id,
+      ).overrideWith(() => _FakeMessagesNotifier([], channelId: channelA.id)),
+      channelMessagesProvider(
+        channelB.id,
+      ).overrideWith(() => _FakeMessagesNotifier([], channelId: channelB.id)),
+      channelTypingProvider(
+        channelA.id,
+      ).overrideWith(() => _FakeTypingNotifier([], channelId: channelA.id)),
+      channelTypingProvider(
+        channelB.id,
+      ).overrideWith(() => _FakeTypingNotifier([], channelId: channelB.id)),
+      channelDetailsProvider(
+        channelA.id,
+      ).overrideWith((ref) async => ChannelDetails.fromChannel(channelA)),
+      channelDetailsProvider(
+        channelB.id,
+      ).overrideWith((ref) async => ChannelDetails.fromChannel(channelB)),
+      channelMembersProvider(
+        channelA.id,
+      ).overrideWith((ref) async => const <ChannelMember>[]),
+      channelMembersProvider(
+        channelB.id,
+      ).overrideWith((ref) async => const <ChannelMember>[]),
+      userCacheProvider.overrideWith(() => _FakeUserCacheNotifier({})),
+      profileProvider.overrideWith(() => _FakeProfileNotifier()),
+      channelsProvider.overrideWith(
+        () => _FakeChannelsNotifier([channelA, channelB]),
+      ),
+      relayClientProvider.overrideWithValue(
+        RelayClient(baseUrl: 'http://localhost:3000'),
+      ),
+      savedPrefsProvider.overrideWithValue(_testPrefs),
+    ],
+    child: MaterialApp(
+      theme: AppTheme.light(),
+      home: ChannelDetailPage(channel: channelA),
+    ),
+  );
+}
+
 /// Finder that searches for text within RichText spans. [find.text] only
 /// matches the top-level text property; this also searches nested TextSpans.
 Finder findRichText(String text) {
@@ -251,6 +311,103 @@ void main() {
   });
 
   group('ChannelDetailPage', () {
+    testWidgets(
+      'restores the previous channel replay priority after a nested pop',
+      (tester) async {
+        final channelA = _channel(id: 'channel-a', name: 'channel A');
+        final channelB = _channel(id: 'channel-b', name: 'channel B');
+        final socket = _RecordingRelaySocket();
+        final relaySession = RelaySessionNotifier();
+        relaySession.debugAttachSocketForTest(socket);
+
+        final subscribeB = relaySession.subscribe(
+          _filterForChannel(channelB.id),
+          (_) {},
+        );
+        relaySession.debugHandleMessage(['EOSE', 'l-1']);
+        await subscribeB;
+        final subscribeA = relaySession.subscribe(
+          _filterForChannel(channelA.id),
+          (_) {},
+        );
+        relaySession.debugHandleMessage(['EOSE', 'l-2']);
+        await subscribeA;
+
+        await tester.pumpWidget(
+          _buildNavigationTestable(
+            channelA: channelA,
+            channelB: channelB,
+            relaySession: relaySession,
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        final navigator = Navigator.of(
+          tester.element(find.byType(ChannelDetailPage)),
+        );
+        navigator.push(
+          MaterialPageRoute<void>(
+            builder: (_) => ChannelDetailPage(channel: channelB),
+          ),
+        );
+        await tester.pumpAndSettle();
+        navigator.pop();
+        await tester.pumpAndSettle();
+
+        socket.messages.clear();
+        await relaySession.debugReplayLiveSubscriptions();
+
+        expect(_replayedChannelIds(socket), [channelA.id, channelB.id]);
+      },
+    );
+
+    testWidgets(
+      'keeps replacement channel replay priority after old route disposal',
+      (tester) async {
+        final channelA = _channel(id: 'channel-a', name: 'channel A');
+        final channelB = _channel(id: 'channel-b', name: 'channel B');
+        final socket = _RecordingRelaySocket();
+        final relaySession = RelaySessionNotifier();
+        relaySession.debugAttachSocketForTest(socket);
+
+        final subscribeA = relaySession.subscribe(
+          _filterForChannel(channelA.id),
+          (_) {},
+        );
+        relaySession.debugHandleMessage(['EOSE', 'l-1']);
+        await subscribeA;
+        final subscribeB = relaySession.subscribe(
+          _filterForChannel(channelB.id),
+          (_) {},
+        );
+        relaySession.debugHandleMessage(['EOSE', 'l-2']);
+        await subscribeB;
+
+        await tester.pumpWidget(
+          _buildNavigationTestable(
+            channelA: channelA,
+            channelB: channelB,
+            relaySession: relaySession,
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        Navigator.of(
+          tester.element(find.byType(ChannelDetailPage)),
+        ).pushReplacement(
+          MaterialPageRoute<void>(
+            builder: (_) => ChannelDetailPage(channel: channelB),
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        socket.messages.clear();
+        await relaySession.debugReplayLiveSubscriptions();
+
+        expect(_replayedChannelIds(socket), [channelB.id, channelA.id]);
+      },
+    );
+
     testWidgets('debounces same-slot reconnect skeletons before revealing', (
       tester,
     ) async {
@@ -749,6 +906,63 @@ void main() {
       );
     });
 
+    testWidgets(
+      'keeps image galleries body-aligned and flush with the trailing edge',
+      (tester) async {
+        tester.view.physicalSize = const Size(400, 800);
+        tester.view.devicePixelRatio = 1;
+        addTearDown(tester.view.resetPhysicalSize);
+        addTearDown(tester.view.resetDevicePixelRatio);
+
+        const firstImage = 'https://example.com/media/first.png';
+        const secondImage = 'https://example.com/media/second.png';
+        await tester.pumpWidget(
+          _buildTestable(
+            messages: [
+              _textMsg(
+                id: 'gallery',
+                pubkey: 'alice',
+                content:
+                    'Gallery\n'
+                    '![First]($firstImage)\n'
+                    '![Second]($secondImage)',
+                extraTags: const [
+                  ['imeta', 'url $firstImage', 'm image/png'],
+                  ['imeta', 'url $secondImage', 'm image/png'],
+                ],
+              ),
+            ],
+            users: const {
+              'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
+            },
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        final carousel = find.byKey(const ValueKey('message-media-carousel'));
+        final imageCount = find.byKey(
+          const ValueKey('message-media-carousel-count'),
+        );
+        final carouselRect = tester.getRect(carousel);
+        final imageCountRect = tester.getRect(imageCount);
+
+        expect(carouselRect.left, imageCountRect.left);
+        expect(carouselRect.right, tester.view.physicalSize.width);
+        expect(carouselRect.top - imageCountRect.bottom, Grid.half + 2);
+
+        final messageMaterial = find
+            .ancestor(
+              of: find.byKey(const ValueKey('message-row-gallery')),
+              matching: find.byType(Material),
+            )
+            .first;
+        expect(
+          tester.widget<Material>(messageMaterial).clipBehavior,
+          Clip.none,
+        );
+      },
+    );
+
     testWidgets('uses larger participant avatars in reply summaries', (
       tester,
     ) async {
@@ -1073,7 +1287,11 @@ void main() {
         // Small scrolls that keep the newest message visible, so isAtLatest
         // stays true while the scroll offset becomes non-zero. This lets a
         // later programmatic jumpTo dispatch ScrollEndNotification.
-        for (final dy in const [10.0, 20.0, 30.0]) {
+        //
+        // Each drag must clear `kDragSlopDefault`; below it `tester.drag`
+        // sends a single sub-slop move, which a message bubble now claims as
+        // a tap and pushes the thread page over this list.
+        for (final dy in const [30.0, 30.0, 30.0]) {
           await tester.drag(
             find.byKey(const ValueKey('channel-message-list')),
             Offset(0, dy),
@@ -1276,7 +1494,7 @@ void main() {
       await tester.pumpAndSettle();
 
       expect(find.text('Bob'), findsOneWidget);
-      final addedAction = findRichText('was added by Alice');
+      final addedAction = findRichText('added by Alice');
       expect(addedAction, findsOneWidget);
       expect(find.text('Alice added Bob to the channel'), findsNothing);
       expect(
@@ -1294,7 +1512,7 @@ void main() {
       expect(timestampRect.left, greaterThan(nameRect.right));
       final addedText = tester.widget<RichText>(addedAction);
       expect(
-        effectiveFontSizeForText(addedText.text, 'was added by Alice'),
+        effectiveFontSizeForText(addedText.text, 'added by Alice'),
         systemMessageBodyTextStyle.fontSize,
       );
     });
@@ -1363,7 +1581,7 @@ void main() {
 
       expect(find.text('Bob'), findsOneWidget);
       expect(
-        findRichText('was added by Alice, along with Carol, Dave, Erin, and '),
+        findRichText('added by Alice, along with Carol, Dave, Erin, and '),
         findsOneWidget,
       );
       expect(find.byKey(const Key('membership-overflow')), findsOneWidget);
@@ -1412,6 +1630,51 @@ void main() {
       );
     });
 
+    testWidgets('a reacted message offers the + picker in the timeline', (
+      tester,
+    ) async {
+      // Desktop puts the picker trigger beside existing reactions on every row,
+      // so reacting doesn't require discovering the long-press sheet.
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: [
+            _textMsg(id: 'msg1', pubkey: 'alice', content: 'ship it'),
+            _reaction(id: 'reaction-1', targetId: 'msg1'),
+          ],
+          users: {
+            'alice': const UserProfile(pubkey: 'alice', displayName: 'Alice'),
+          },
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      expect(find.byKey(const ValueKey('add-reaction-pill')), findsOneWidget);
+
+      await tester.tap(find.byKey(const ValueKey('add-reaction-pill')));
+      // Not pumpAndSettle: with no dataset asset in a widget test the sheet
+      // shows its loading spinner, which animates forever.
+      await tester.pump();
+      await tester.pump(const Duration(milliseconds: 400));
+      expect(find.byType(EmojiPickerSheet), findsOneWidget);
+    });
+
+    testWidgets('an unreacted message keeps the timeline free of chrome', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: [_textMsg(id: 'msg1', pubkey: 'alice', content: 'ship it')],
+          users: {
+            'alice': const UserProfile(pubkey: 'alice', displayName: 'Alice'),
+          },
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      // No reactions, no row — the + only trails reactions that already exist.
+      expect(find.byKey(const ValueKey('add-reaction-pill')), findsNothing);
+    });
+
     testWidgets('renders member_left system event', (tester) async {
       final messages = [
         _systemMsg(
@@ -1751,6 +2014,25 @@ void main() {
       await tester.pumpAndSettle();
 
       expect(find.text('Alice is typing…'), findsOneWidget);
+
+      final indicator = tester.widget<Container>(
+        find.byKey(const ValueKey('channel-typing-indicator')),
+      );
+      final decoration = indicator.decoration! as BoxDecoration;
+      expect(
+        indicator.padding,
+        const EdgeInsets.symmetric(horizontal: Grid.xxs, vertical: Grid.xxs),
+      );
+      expect(
+        decoration.color,
+        AppTheme.light().colorScheme.surfaceContainerHighest,
+      );
+      expect(decoration.border, isA<Border>());
+      expect(
+        tester.widget<Text>(find.text('Alice is typing…')).style?.color,
+        AppTheme.light().colorScheme.primary,
+      );
+      expect(tester.widget<SmallAvatar>(find.byType(SmallAvatar)).size, 24);
     });
 
     testWidgets('shows two typers', (tester) async {
@@ -2192,14 +2474,322 @@ void main() {
       expect(find.byType(DayDivider), findsNWidgets(2));
       expect(find.text(formatDayHeading(rootCreatedAt)), findsOneWidget);
       expect(find.text(formatDayHeading(nextDayCreatedAt)), findsOneWidget);
+      // The list runs top-down (head first), so tail spacing lives on the list
+      // and reply groups carry none.
       final threadList = tester.widget<ScrollablePositionedList>(
         find.byKey(const ValueKey('thread-message-list')),
       );
-      expect(threadList.padding!.bottom, 0);
+      expect(threadList.reverse, isFalse);
+      expect(threadList.padding!.bottom, Grid.xs);
       final newestThreadGroup = tester.widget<Padding>(
         find.byKey(const ValueKey('thread-message-group-reply-next-day')),
       );
-      expect(newestThreadGroup.padding, const EdgeInsets.only(bottom: Grid.xs));
+      expect(newestThreadGroup.padding, EdgeInsets.zero);
+
+      // The head sits above its replies rather than jammed against the
+      // composer, matching desktop's thread panel.
+      final headY = tester
+          .getTopLeft(
+            find.byKey(const ValueKey('thread-message-group-thread-root')),
+          )
+          .dy;
+      final oldestReplyY = tester
+          .getTopLeft(
+            find.byKey(const ValueKey('thread-message-group-reply-same-day')),
+          )
+          .dy;
+      final newestReplyY = tester
+          .getTopLeft(
+            find.byKey(const ValueKey('thread-message-group-reply-next-day')),
+          )
+          .dy;
+      expect(headY, lessThan(oldestReplyY));
+      expect(oldestReplyY, lessThan(newestReplyY));
+    });
+
+    testWidgets(
+      'initial thread hydration keeps the head visible instead of following the tail',
+      (tester) async {
+        final rootEvent = _textMsg(
+          id: 'thread-root',
+          pubkey: 'alice',
+          content: 'Thread root',
+          createdAt: 1000,
+        );
+        final replies = [
+          for (var i = 0; i < 30; i++)
+            _textMsg(
+              id: 'reply-$i',
+              pubkey: 'bob',
+              content: 'Reply $i',
+              createdAt: 1100 + i,
+              extraTags: const [
+                ['e', 'thread-root', '', 'reply'],
+              ],
+            ),
+        ];
+        final completer = Completer<List<NostrEvent>>();
+
+        await tester.pumpWidget(
+          _buildTestable(
+            messages: [rootEvent],
+            pendingThreadReplies: {'thread-root': completer.future},
+            users: const {
+              'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
+              'bob': UserProfile(pubkey: 'bob', displayName: 'Bob'),
+            },
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        final threadHead = formatTimeline([rootEvent]).single;
+        Navigator.of(tester.element(find.byType(ChannelDetailPage))).push(
+          MaterialPageRoute<void>(
+            builder: (_) => ThreadDetailPage(
+              threadHead: threadHead,
+              allMessages: [threadHead],
+              channelId: _channelId,
+              currentPubkey: 'self',
+              isMember: true,
+              isArchived: false,
+            ),
+          ),
+        );
+        await tester.pumpAndSettle();
+        expect(
+          find.byKey(const ValueKey('thread-message-group-thread-root')),
+          findsOneWidget,
+        );
+
+        completer.complete(replies);
+        await tester.pumpAndSettle();
+
+        expect(
+          find.byKey(const ValueKey('thread-message-group-thread-root')),
+          findsOneWidget,
+        );
+        expect(
+          find.byKey(const ValueKey('thread-message-group-reply-29')),
+          findsNothing,
+        );
+      },
+    );
+
+    testWidgets('a reaction landing while the thread is open shows up there', (
+      tester,
+    ) async {
+      // The thread's own relay query is one-shot and asks only for content
+      // kinds, so it can never carry a reaction that arrives afterwards. Until
+      // the live channel events were folded in, the pill (and its burst) only
+      // appeared after leaving the thread and coming back, which refetched.
+      final rootEvent = _textMsg(
+        id: 'thread-root',
+        pubkey: 'alice',
+        content: 'Thread root',
+        createdAt: 1000,
+      );
+      final reply = _textMsg(
+        id: 'reply-1',
+        pubkey: 'bob',
+        content: 'A reply',
+        createdAt: 1100,
+        extraTags: const [
+          ['e', 'thread-root', '', 'reply'],
+        ],
+      );
+      final messagesNotifier = _FakeMessagesNotifier([rootEvent]);
+
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: [rootEvent],
+          messagesNotifier: messagesNotifier,
+          threadReplies: {
+            'thread-root': [reply],
+          },
+          users: {
+            'alice': const UserProfile(pubkey: 'alice', displayName: 'Alice'),
+            'bob': const UserProfile(pubkey: 'bob', displayName: 'Bob'),
+          },
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      final threadHead = formatTimeline([rootEvent]).single;
+      Navigator.of(tester.element(find.byType(ChannelDetailPage))).push(
+        MaterialPageRoute<void>(
+          builder: (_) => ThreadDetailPage(
+            threadHead: threadHead,
+            allMessages: [threadHead],
+            channelId: _channelId,
+            currentPubkey: 'self',
+            isMember: true,
+            isArchived: false,
+          ),
+        ),
+      );
+      await tester.pumpAndSettle();
+      expect(find.byKey(const ValueKey('reaction-pill-👍')), findsNothing);
+
+      // The reaction arrives over the channel socket, as it does on device.
+      messagesNotifier.setMessages([
+        rootEvent,
+        _reaction(id: 'reaction-1', targetId: 'reply-1'),
+      ]);
+      await tester.pumpAndSettle();
+
+      // Still on the thread route — no pop needed for the pill to appear.
+      expect(find.byType(ThreadDetailPage), findsOneWidget);
+      expect(find.byKey(const ValueKey('reaction-pill-👍')), findsOneWidget);
+    });
+
+    testWidgets('a live deletion does not restore the routed thread head', (
+      tester,
+    ) async {
+      final rootEvent = _textMsg(
+        id: 'thread-root',
+        pubkey: 'alice',
+        content: 'Thread root',
+        createdAt: 1000,
+      );
+      final reply = _textMsg(
+        id: 'reply-1',
+        pubkey: 'bob',
+        content: 'A reply',
+        createdAt: 1100,
+        extraTags: const [
+          ['e', 'thread-root', '', 'reply'],
+        ],
+      );
+      final messagesNotifier = _FakeMessagesNotifier([rootEvent]);
+
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: [rootEvent],
+          messagesNotifier: messagesNotifier,
+          threadReplies: {
+            'thread-root': [reply],
+          },
+          users: const {
+            'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
+            'bob': UserProfile(pubkey: 'bob', displayName: 'Bob'),
+          },
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      final threadHead = formatTimeline([rootEvent]).single;
+      Navigator.of(tester.element(find.byType(ChannelDetailPage))).push(
+        MaterialPageRoute<void>(
+          builder: (_) => ThreadDetailPage(
+            threadHead: threadHead,
+            allMessages: [threadHead],
+            channelId: _channelId,
+            currentPubkey: 'self',
+            isMember: true,
+            isArchived: false,
+          ),
+        ),
+      );
+      await tester.pumpAndSettle();
+      expect(find.text('Thread root'), findsOneWidget);
+
+      messagesNotifier.setMessages([
+        rootEvent,
+        _deletion(id: 'delete-root', targetIds: ['thread-root']),
+      ]);
+      await tester.pumpAndSettle();
+
+      expect(find.text('Thread root'), findsNothing);
+      expect(
+        find.byKey(const ValueKey('thread-message-deleted')),
+        findsOneWidget,
+      );
+      expect(find.text('This message was deleted'), findsOneWidget);
+    });
+
+    testWidgets('thread replies earn the + only once they carry a reaction', (
+      tester,
+    ) async {
+      final rootEvent = _textMsg(
+        id: 'thread-root',
+        pubkey: 'alice',
+        content: 'Thread root',
+        createdAt: 1000,
+      );
+      final bareReply = _textMsg(
+        id: 'reply-bare',
+        pubkey: 'bob',
+        content: 'No reactions here',
+        createdAt: 1100,
+        extraTags: const [
+          ['e', 'thread-root', '', 'reply'],
+        ],
+      );
+      final reactedReply = _textMsg(
+        id: 'reply-reacted',
+        pubkey: 'bob',
+        content: 'This one has a reaction',
+        createdAt: 1200,
+        extraTags: const [
+          ['e', 'thread-root', '', 'reply'],
+        ],
+      );
+
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: [
+            rootEvent,
+            _reaction(id: 'reaction-1', targetId: 'reply-reacted'),
+          ],
+          threadReplies: {
+            'thread-root': [bareReply, reactedReply],
+          },
+          users: {
+            'alice': const UserProfile(pubkey: 'alice', displayName: 'Alice'),
+            'bob': const UserProfile(pubkey: 'bob', displayName: 'Bob'),
+          },
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      final threadHead = formatTimeline([rootEvent]).single;
+      Navigator.of(tester.element(find.byType(ChannelDetailPage))).push(
+        MaterialPageRoute<void>(
+          builder: (_) => ThreadDetailPage(
+            threadHead: threadHead,
+            allMessages: [threadHead],
+            channelId: _channelId,
+            currentPubkey: 'self',
+            isMember: true,
+            isArchived: false,
+          ),
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      // The head keeps a standing +; the bare reply gets none, so a thread
+      // reads as quietly as the channel does. Two + pills, not three: the head
+      // and the reacted reply.
+      expect(find.byKey(const ValueKey('add-reaction-pill')), findsNWidgets(2));
+      final headRow = find.descendant(
+        of: find.byKey(const ValueKey('thread-message-group-thread-root')),
+        matching: find.byKey(const ValueKey('add-reaction-pill')),
+      );
+      expect(headRow, findsOneWidget);
+      expect(
+        find.descendant(
+          of: find.byKey(const ValueKey('thread-message-group-reply-bare')),
+          matching: find.byKey(const ValueKey('add-reaction-pill')),
+        ),
+        findsNothing,
+      );
+      expect(
+        find.descendant(
+          of: find.byKey(const ValueKey('thread-message-group-reply-reacted')),
+          matching: find.byKey(const ValueKey('add-reaction-pill')),
+        ),
+        findsOneWidget,
+      );
     });
   });
 }
@@ -2220,9 +2810,12 @@ class _FakeMessagesNotifier extends ChannelMessagesNotifier {
   List<NostrEvent> _messages;
   bool _hasLoadedMessages;
 
-  _FakeMessagesNotifier(this._messages, {bool hasLoadedMessages = true})
-    : _hasLoadedMessages = hasLoadedMessages,
-      super(_channelId);
+  _FakeMessagesNotifier(
+    this._messages, {
+    String channelId = _channelId,
+    bool hasLoadedMessages = true,
+  }) : _hasLoadedMessages = hasLoadedMessages,
+       super(channelId);
 
   @override
   AsyncValue<List<NostrEvent>> build() => AsyncData(_messages);
@@ -2269,7 +2862,8 @@ class _ReconnectingRelaySession extends RelaySessionNotifier {
 
 class _FakeTypingNotifier extends ChannelTypingNotifier {
   final List<TypingEntry> _entries;
-  _FakeTypingNotifier(this._entries) : super(_channelId);
+  _FakeTypingNotifier(this._entries, {String channelId = _channelId})
+    : super(channelId);
 
   @override
   List<TypingEntry> build() => _entries;
@@ -2350,6 +2944,42 @@ class _FakeChannelActions extends ChannelActions {
   }
 }
 
+class _RecordingRelaySocket extends RelaySocket {
+  _RecordingRelaySocket()
+    : super(
+        wsUrl: 'wss://relay.example',
+        nsec: null,
+        onMessage: (_) {},
+        onConnected: () {},
+        onDisconnected: (_) {},
+      );
+
+  final List<List<dynamic>> messages = [];
+
+  @override
+  void send(List<dynamic> payload) => messages.add(payload);
+
+  @override
+  void dispose() {}
+}
+
+NostrFilter _filterForChannel(String channelId) => NostrFilter(
+  kinds: EventKind.channelEventKinds,
+  tags: {
+    '#h': [channelId],
+  },
+  limit: 0,
+);
+
+List<String> _replayedChannelIds(_RecordingRelaySocket socket) => socket
+    .messages
+    .where((message) => message.first == 'REQ')
+    .map(
+      (message) =>
+          ((message[2] as Map<String, dynamic>)['#h'] as List).single as String,
+    )
+    .toList();
+
 class _TestNavigatorObserver extends NavigatorObserver {
   int pushCount = 0;
 
diff --git a/mobile/test/features/channels/channel_messages_provider_test.dart b/mobile/test/features/channels/channel_messages_provider_test.dart
index 6620c8c506..4f4efdce1f 100644
--- a/mobile/test/features/channels/channel_messages_provider_test.dart
+++ b/mobile/test/features/channels/channel_messages_provider_test.dart
@@ -39,10 +39,10 @@ void main() {
           .value!;
       expect(messages.map((event) => event.id), ['history', 'live']);
       expect(relaySession.operations, ['subscribe', 'query', 'fetch']);
-      expect(
-        relaySession.liveFilters.single.kinds,
-        EventKind.channelEventKinds,
-      );
+      expect(relaySession.liveFilters.single.kinds, [
+        ...EventKind.channelEventKinds,
+        EventKind.channelThreadSummary,
+      ]);
       expect(relaySession.liveFilters.single.tags['#h'], [_channelId]);
       expect(relaySession.liveFilters.single.limit, 200);
       expect(
@@ -59,6 +59,47 @@ void main() {
     },
   );
 
+  test(
+    'buffers a live thread summary until the initial window is installed',
+    () async {
+      final window = Completer<List<NostrEvent>>();
+      final relaySession = _RecordingRelaySessionNotifier(
+        queryResults: [window.future],
+      );
+      final container = _buildContainer(relaySession);
+      addTearDown(container.dispose);
+
+      container.read(channelMessagesProvider(_channelId));
+      await relaySession.subscribed;
+      final notifier = container.read(
+        channelMessagesProvider(_channelId).notifier,
+      );
+
+      relaySession.emit(_summary(rootId: 'root', replyCount: 2));
+      await _pumpEventQueue();
+      expect(
+        container.read(channelMessagesProvider(_channelId)).isLoading,
+        isTrue,
+      );
+
+      window.complete([
+        _event(id: 'root', createdAt: 10),
+        _summary(rootId: 'root', replyCount: 1, createdAt: 10),
+        _bounds(),
+      ]);
+      await _pumpEventQueue();
+
+      expect(notifier.threadSummaries['root']?.replyCount, 2);
+      expect(
+        container
+            .read(channelMessagesProvider(_channelId))
+            .value
+            ?.map((event) => event.id),
+        ['root'],
+      );
+    },
+  );
+
   test('still loads history when live subscription fails', () async {
     final relaySession = _RecordingRelaySessionNotifier(failSubscribe: true);
     final container = _buildContainer(relaySession);
@@ -242,6 +283,42 @@ void main() {
     );
   });
 
+  test(
+    'live thread summary survives rolling back an unrelated local row',
+    () async {
+      final relaySession = _RecordingRelaySessionNotifier(
+        queryResults: [
+          [_event(id: 'root', createdAt: 10), _bounds()],
+        ],
+      );
+      final container = _buildContainer(relaySession);
+      addTearDown(container.dispose);
+
+      container.read(channelMessagesProvider(_channelId));
+      await relaySession.subscribed;
+      await _pumpEventQueue();
+      final notifier = container.read(
+        channelMessagesProvider(_channelId).notifier,
+      );
+      notifier.addLocalMessage(_event(id: 'local', createdAt: 20));
+
+      relaySession.emit(_summary(rootId: 'root', replyCount: 2));
+      await _pumpEventQueue();
+      expect(notifier.threadSummaries['root']?.replyCount, 2);
+
+      notifier.removeLocalMessage('local');
+
+      expect(notifier.threadSummaries['root']?.replyCount, 2);
+      expect(
+        container
+            .read(channelMessagesProvider(_channelId))
+            .value
+            ?.map((event) => event.id),
+        ['root'],
+      );
+    },
+  );
+
   test('reconnect hydration cannot retain a rolled-back local row', () async {
     final relaySession = _RecordingRelaySessionNotifier(
       queryResults: [
@@ -562,6 +639,30 @@ NostrEvent _event({
   );
 }
 
+NostrEvent _summary({
+  required String rootId,
+  required int replyCount,
+  int createdAt = 20,
+}) {
+  return NostrEvent(
+    id: 'summary-$rootId-$createdAt-$replyCount',
+    pubkey: 'relay',
+    createdAt: createdAt,
+    kind: EventKind.channelThreadSummary,
+    tags: [
+      ['h', _channelId],
+      ['e', rootId],
+    ],
+    content: jsonEncode({
+      'reply_count': replyCount,
+      'descendant_count': replyCount,
+      'last_reply_at': 20,
+      'participants': ['alice'],
+    }),
+    sig: 'sig',
+  );
+}
+
 NostrEvent _bounds({
   bool hasMore = false,
   int? cursorCreatedAt,
@@ -629,6 +730,7 @@ class _RecordingRelaySessionNotifier extends RelaySessionNotifier {
     if (_queryResults.isEmpty) throw Exception('unsupported');
     final result = _queryResults.removeFirst();
     if (result is Exception) throw result;
+    if (result is Future<List<NostrEvent>>) return await result;
     return (result as List<NostrEvent>).toList();
   }
 
diff --git a/mobile/test/features/channels/channel_window_test.dart b/mobile/test/features/channels/channel_window_test.dart
index 4db3d7decb..f6e6a25f34 100644
--- a/mobile/test/features/channels/channel_window_test.dart
+++ b/mobile/test/features/channels/channel_window_test.dart
@@ -141,6 +141,296 @@ void main() {
       expect(merged.liveOverlay.map((event) => event.id), ['live']);
     });
   });
+
+  group('live thread summaries', () {
+    test('a live summary gives a loaded row its reply count', () {
+      final store = replaceNewestChannelWindow(
+        const ChannelWindowStore.empty(),
+        _page(rows: [_row('root', createdAt: 10)]),
+      );
+      // No summary yet: the row was fetched before anyone replied.
+      expect(channelWindowThreadSummaries(store), isEmpty);
+
+      final merged = mergeLiveChannelWindowEvent(
+        store,
+        _summary('root', replyCount: 1, participants: ['p1']),
+        isTimelineRow: false,
+      );
+
+      expect(channelWindowThreadSummaries(merged)['root']?.replyCount, 1);
+    });
+
+    test('a live summary covers a root that is only in the overlay', () {
+      // A message you just sent has no page row yet, so its count has nowhere
+      // to live except beside the pages.
+      final store = mergeLiveChannelWindowEvent(
+        replaceNewestChannelWindow(
+          const ChannelWindowStore.empty(),
+          _page(rows: [_row('old', createdAt: 10)]),
+        ),
+        _row('mine', createdAt: 11),
+        isTimelineRow: true,
+      );
+
+      final merged = mergeLiveChannelWindowEvent(
+        store,
+        _summary('mine', replyCount: 2, participants: ['p1', 'p2']),
+        isTimelineRow: false,
+      );
+
+      expect(channelWindowThreadSummaries(merged)['mine']?.replyCount, 2);
+    });
+
+    test('a later live summary replaces an earlier one', () {
+      var store = replaceNewestChannelWindow(
+        const ChannelWindowStore.empty(),
+        _page(rows: [_row('root', createdAt: 10)]),
+      );
+      store = mergeLiveChannelWindowEvent(
+        store,
+        _summary('root', replyCount: 1, participants: ['p1'], createdAt: 11),
+        isTimelineRow: false,
+      );
+      store = mergeLiveChannelWindowEvent(
+        store,
+        _summary(
+          'root',
+          replyCount: 2,
+          participants: ['p1', 'p2'],
+          createdAt: 12,
+        ),
+        isTimelineRow: false,
+      );
+
+      expect(channelWindowThreadSummaries(store)['root']?.replyCount, 2);
+    });
+
+    test(
+      'an older live summary is ignored but a later same-second summary wins',
+      () {
+        var store = replaceNewestChannelWindow(
+          const ChannelWindowStore.empty(),
+          _page(rows: [_row('root', createdAt: 10)]),
+        );
+        store = mergeLiveChannelWindowEvent(
+          store,
+          _summary('root', replyCount: 3, participants: ['p1'], createdAt: 30),
+          isTimelineRow: false,
+        );
+        final afterOlder = mergeLiveChannelWindowEvent(
+          store,
+          _summary('root', replyCount: 1, participants: ['p1'], createdAt: 29),
+          isTimelineRow: false,
+        );
+        final afterSameSecond = mergeLiveChannelWindowEvent(
+          afterOlder,
+          _summary('root', replyCount: 2, participants: ['p1'], createdAt: 30),
+          isTimelineRow: false,
+        );
+
+        expect(identical(afterOlder, store), isTrue);
+        expect(
+          channelWindowThreadSummaries(afterSameSecond)['root']?.replyCount,
+          2,
+        );
+      },
+    );
+
+    test(
+      'a summary received during the initial query wins the page snapshot',
+      () {
+        var store = mergeLiveChannelWindowEvent(
+          const ChannelWindowStore.empty(),
+          _summary('root', replyCount: 2, participants: ['p1'], createdAt: 30),
+          isTimelineRow: false,
+        );
+
+        store = replaceNewestChannelWindow(
+          store,
+          ChannelWindowPage(
+            startCursor: null,
+            rows: [
+              ChannelWindowRow(
+                event: _row('root', createdAt: 10),
+                thread: const ChannelWindowThreadSummary(
+                  replyCount: 1,
+                  descendantCount: 1,
+                  lastReplyAt: 12,
+                  participantPubkeys: ['p1'],
+                ),
+                // The page overlay can be signed after its query snapshot.
+                threadSummaryCreatedAt: 31,
+              ),
+            ],
+            aux: const [],
+            nextCursor: null,
+            hasMore: false,
+          ),
+          retainLiveSummaryRootIds: const {'root'},
+        );
+
+        expect(channelWindowThreadSummaries(store)['root']?.replyCount, 2);
+      },
+    );
+
+    test('a replayed summary yields to a newer initial page snapshot', () {
+      var store = mergeLiveChannelWindowEvent(
+        const ChannelWindowStore.empty(),
+        _summary('root', replyCount: 2, participants: ['p1'], createdAt: 30),
+        isTimelineRow: false,
+      );
+
+      store = replaceNewestChannelWindow(
+        store,
+        ChannelWindowPage(
+          startCursor: null,
+          rows: [
+            ChannelWindowRow(
+              event: _row('root', createdAt: 10),
+              thread: const ChannelWindowThreadSummary(
+                replyCount: 1,
+                descendantCount: 1,
+                lastReplyAt: 12,
+                participantPubkeys: ['p1'],
+              ),
+              threadSummaryCreatedAt: 31,
+            ),
+          ],
+          aux: const [],
+          nextCursor: null,
+          hasMore: false,
+        ),
+      );
+
+      expect(channelWindowThreadSummaries(store)['root']?.replyCount, 1);
+    });
+
+    test('a newer live summary survives an appended older page', () {
+      var store = replaceNewestChannelWindow(
+        const ChannelWindowStore.empty(),
+        _page(rows: [_row('head', createdAt: 10)], hasMore: true),
+      );
+      store = mergeLiveChannelWindowEvent(
+        store,
+        _summary('older', replyCount: 2, participants: ['p1'], createdAt: 30),
+        isTimelineRow: false,
+      );
+
+      store = appendOlderChannelWindow(
+        store,
+        ChannelWindowPage(
+          startCursor: const ChannelPageCursor(createdAt: 10, eventId: 'head'),
+          rows: [
+            ChannelWindowRow(
+              event: _row('older', createdAt: 9),
+              thread: const ChannelWindowThreadSummary(
+                replyCount: 1,
+                descendantCount: 1,
+                lastReplyAt: 12,
+                participantPubkeys: ['p1'],
+              ),
+              threadSummaryCreatedAt: 29,
+            ),
+          ],
+          aux: const [],
+          nextCursor: null,
+          hasMore: false,
+        ),
+      );
+
+      expect(channelWindowThreadSummaries(store)['older']?.replyCount, 2);
+    });
+
+    test('a refetched row outranks the live entry it duplicates', () {
+      var store = replaceNewestChannelWindow(
+        const ChannelWindowStore.empty(),
+        _page(rows: [_row('root', createdAt: 10)]),
+      );
+      store = mergeLiveChannelWindowEvent(
+        store,
+        _summary('root', replyCount: 1, participants: ['p1']),
+        isTimelineRow: false,
+      );
+
+      // Refetching the head brings down the authoritative count with the row,
+      // so the stale live entry must not shadow it.
+      final refreshed = replaceNewestChannelWindow(
+        store,
+        ChannelWindowPage(
+          startCursor: null,
+          rows: [
+            ChannelWindowRow(
+              event: _row('root', createdAt: 10),
+              thread: const ChannelWindowThreadSummary(
+                replyCount: 5,
+                descendantCount: 5,
+                lastReplyAt: 12,
+                participantPubkeys: ['p1'],
+              ),
+              threadSummaryCreatedAt: 20,
+            ),
+          ],
+          aux: const [],
+          nextCursor: null,
+          hasMore: false,
+        ),
+      );
+
+      expect(channelWindowThreadSummaries(refreshed)['root']?.replyCount, 5);
+    });
+
+    test('a summary survives unrelated live events', () {
+      var store = replaceNewestChannelWindow(
+        const ChannelWindowStore.empty(),
+        _page(rows: [_row('root', createdAt: 10)]),
+      );
+      store = mergeLiveChannelWindowEvent(
+        store,
+        _summary('root', replyCount: 1, participants: ['p1']),
+        isTimelineRow: false,
+      );
+      store = mergeLiveChannelWindowEvent(
+        store,
+        _reaction('reaction'),
+        isTimelineRow: false,
+      );
+      store = mergeLiveChannelWindowEvent(
+        store,
+        _row('later', createdAt: 11),
+        isTimelineRow: true,
+      );
+
+      expect(channelWindowThreadSummaries(store)['root']?.replyCount, 1);
+    });
+
+    test('a summary with no root tag or bad content is ignored', () {
+      final store = replaceNewestChannelWindow(
+        const ChannelWindowStore.empty(),
+        _page(rows: [_row('root', createdAt: 10)]),
+      );
+
+      final untagged = mergeLiveChannelWindowEvent(
+        store,
+        _event(id: 'no-e', kind: EventKind.channelThreadSummary, content: '{}'),
+        isTimelineRow: false,
+      );
+      expect(identical(untagged, store), isTrue);
+
+      final malformed = mergeLiveChannelWindowEvent(
+        store,
+        _event(
+          id: 'bad',
+          kind: EventKind.channelThreadSummary,
+          tags: const [
+            ['e', 'root'],
+          ],
+          content: 'not json',
+        ),
+        isTimelineRow: false,
+      );
+      expect(channelWindowThreadSummaries(malformed), isEmpty);
+    });
+  });
 }
 
 const _channelId = 'ABCDEF';
@@ -185,8 +475,10 @@ NostrEvent _summary(
   String rootId, {
   required int replyCount,
   required List<String> participants,
+  int createdAt = 10,
 }) => _event(
-  id: 'summary-$rootId',
+  id: 'summary-$rootId-$createdAt-$replyCount',
+  createdAt: createdAt,
   kind: EventKind.channelThreadSummary,
   tags: [
     ['e', rootId],
diff --git a/mobile/test/features/channels/channels_page_test.dart b/mobile/test/features/channels/channels_page_test.dart
index 2a624cbde7..991db3b5cd 100644
--- a/mobile/test/features/channels/channels_page_test.dart
+++ b/mobile/test/features/channels/channels_page_test.dart
@@ -8,6 +8,8 @@ import 'package:hooks_riverpod/misc.dart';
 import 'package:lucide_icons_flutter/lucide_icons.dart';
 import 'package:buzz/features/channels/channel.dart';
 import 'package:buzz/features/channels/channel_management_provider.dart';
+import 'package:buzz/features/channels/channel_sections/channel_sections_provider.dart';
+import 'package:buzz/features/channels/channel_sections/channel_sections_storage.dart';
 import 'package:buzz/features/channels/channels_page.dart';
 import 'package:buzz/features/channels/channels_provider.dart';
 import 'package:buzz/features/channels/read_state/read_state_provider.dart';
@@ -28,6 +30,7 @@ void main() {
     bool previewDirectory = false,
     double keyboardInset = 0,
     bool disableAnimations = false,
+    double bottomPadding = 0,
     Map<String, String?> communityIcons = const {},
     ValueChanged<String>? onCommunityIconLoad,
     TextScaler textScaler = TextScaler.noScaling,
@@ -52,6 +55,7 @@ void main() {
           data: MediaQuery.of(context).copyWith(
             disableAnimations: disableAnimations,
             textScaler: textScaler,
+            padding: EdgeInsets.only(bottom: bottomPadding),
             viewInsets: EdgeInsets.only(bottom: keyboardInset),
           ),
           child: child!,
@@ -142,6 +146,60 @@ void main() {
     expect(sectionTitle.style?.fontWeight, FontWeight.w600);
   });
 
+  testWidgets('keeps the last channel above the floating tab bar', (
+    tester,
+  ) async {
+    const footerClearance = 102.0;
+    await tester.pumpWidget(
+      buildTestable(
+        bottomPadding: footerClearance,
+        overrides: [
+          channelsProvider.overrideWith(() => _FakeNotifier(testChannels)),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    final padding = tester.widget<SliverPadding>(
+      find.descendant(
+        of: find.byType(CustomScrollView),
+        matching: find.byType(SliverPadding),
+      ),
+    );
+    expect((padding.padding as EdgeInsets).bottom, footerClearance);
+  });
+
+  testWidgets('truncates long custom section names beside the menu', (
+    tester,
+  ) async {
+    tester.view.physicalSize = const Size(320, 800);
+    tester.view.devicePixelRatio = 1;
+    addTearDown(tester.view.reset);
+    const sectionName = 'A deliberately long custom section name for testing';
+    await tester.pumpWidget(
+      buildTestable(
+        overrides: [
+          channelsProvider.overrideWith(() => _FakeNotifier(testChannels)),
+          channelSectionsProvider.overrideWith(
+            () => _FakeChannelSectionsNotifier(
+              const ChannelSectionStore(
+                sections: [
+                  ChannelSection(id: 'section-1', name: sectionName, order: 0),
+                ],
+              ),
+            ),
+          ),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    final label = tester.widget<Text>(find.text(sectionName));
+    expect(label.maxLines, 1);
+    expect(label.overflow, TextOverflow.ellipsis);
+    expect(tester.takeException(), isNull);
+  });
+
   testWidgets('aligns the top, section, row, and skeleton label columns', (
     tester,
   ) async {
@@ -1384,6 +1442,16 @@ class _FakeNotifier extends ChannelsNotifier {
   get observedUnreadEventsByChannel => _observedEventsByChannel;
 }
 
+class _FakeChannelSectionsNotifier extends ChannelSectionsNotifier {
+  _FakeChannelSectionsNotifier(this._store);
+
+  final ChannelSectionStore _store;
+
+  @override
+  ChannelSectionsState build() =>
+      ChannelSectionsState(isReady: true, store: _store, version: 1);
+}
+
 class _FakeCommunityListNotifier extends CommunityListNotifier {
   _FakeCommunityListNotifier(this._communities);
 
diff --git a/mobile/test/features/channels/channels_provider_test.dart b/mobile/test/features/channels/channels_provider_test.dart
index 79be7a66f7..c128b9be5a 100644
--- a/mobile/test/features/channels/channels_provider_test.dart
+++ b/mobile/test/features/channels/channels_provider_test.dart
@@ -1,3 +1,5 @@
+import 'dart:async';
+
 import 'package:flutter/widgets.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
@@ -52,6 +54,174 @@ void main() {
     },
   );
 
+  test(
+    'refreshing an unchanged channel set issues zero new live REQs',
+    () async {
+      final session = _FakeRelaySession(
+        memberships: [
+          _membership(_channelA, myPk),
+          _membership(_channelB, myPk),
+        ],
+        metadata: [
+          _meta(id: _channelA, name: 'general'),
+          _meta(id: _channelB, name: 'random'),
+        ],
+      );
+      final container = _buildContainer(session: session);
+      addTearDown(container.dispose);
+
+      await container.read(channelsProvider.future);
+      final initialSubscribeCount = session.totalSubscribeCount;
+
+      await container.read(channelsProvider.notifier).refresh();
+
+      expect(session.totalSubscribeCount, initialSubscribeCount);
+      expect(session.unsubscribeCount, 0);
+      expect(session.subscribeFilters, hasLength(2));
+    },
+  );
+
+  test(
+    'live subscription diff only removes and adds changed channels',
+    () async {
+      final session = _FakeRelaySession(
+        memberships: [
+          _membership(_channelA, myPk),
+          _membership(_channelB, myPk),
+        ],
+        metadata: [
+          _meta(id: _channelA, name: 'general'),
+          _meta(id: _channelB, name: 'random'),
+        ],
+      );
+      final container = _buildContainer(session: session);
+      addTearDown(container.dispose);
+
+      await container.read(channelsProvider.future);
+      session.memberships = [
+        _membership(_channelB, myPk),
+        _membership(_channelD, myPk),
+      ];
+      session.metadata = [
+        _meta(id: _channelB, name: 'random'),
+        _meta(id: _channelD, name: 'support'),
+      ];
+
+      await container.read(channelsProvider.notifier).refresh();
+
+      expect(session.totalSubscribeCount, 3);
+      expect(session.unsubscribeCount, 1);
+      expect(
+        session.subscribeFilters
+            .map((filter) => filter.tags['#h']!.single)
+            .toSet(),
+        {_channelB, _channelD},
+      );
+    },
+  );
+
+  test(
+    'empty channel refresh removes every retained live subscription',
+    () async {
+      final session = _FakeRelaySession(
+        memberships: [
+          _membership(_channelA, myPk),
+          _membership(_channelB, myPk),
+        ],
+        metadata: [
+          _meta(id: _channelA, name: 'general'),
+          _meta(id: _channelB, name: 'random'),
+        ],
+      );
+      final container = _buildContainer(session: session);
+      addTearDown(container.dispose);
+
+      await container.read(channelsProvider.future);
+      session.memberships = [];
+      session.metadata = [];
+
+      await container.read(channelsProvider.notifier).refresh();
+
+      expect(session.activeChannels, isEmpty);
+      expect(session.activeSubscriptionCount, 0);
+      expect(session.unsubscribeCount, 2);
+    },
+  );
+
+  test(
+    'overlapping refreshes retain one live subscription per desired channel',
+    () async {
+      final session = _FakeRelaySession(
+        memberships: [
+          _membership(_channelA, myPk),
+          _membership(_channelB, myPk),
+        ],
+        metadata: [
+          _meta(id: _channelA, name: 'general'),
+          _meta(id: _channelB, name: 'random'),
+        ],
+      );
+      final container = _buildContainer(session: session);
+      addTearDown(container.dispose);
+
+      await container.read(channelsProvider.future);
+      session.pauseNextSubscribe();
+      session.memberships = [
+        _membership(_channelA, myPk),
+        _membership(_channelB, myPk),
+        _membership(_channelD, myPk),
+      ];
+      session.metadata = [
+        _meta(id: _channelA, name: 'general'),
+        _meta(id: _channelB, name: 'random'),
+        _meta(id: _channelD, name: 'support'),
+      ];
+
+      final firstRefresh = container.read(channelsProvider.notifier).refresh();
+      await session.nextSubscribeStarted;
+      final secondRefresh = container.read(channelsProvider.notifier).refresh();
+      session.resumePausedSubscribe();
+      await Future.wait([firstRefresh, secondRefresh]);
+
+      expect(session.activeChannels, {_channelA, _channelB, _channelD});
+      expect(session.activeSubscriptionCount, 3);
+    },
+  );
+
+  test(
+    'community switch replaces retained live subscriptions on the new relay',
+    () async {
+      final session = _FakeRelaySession(
+        memberships: [_membership(_channelA, myPk)],
+        metadata: [_meta(id: _channelA, name: 'general')],
+      );
+      final container = _buildContainer(session: session);
+      addTearDown(container.dispose);
+
+      await container.read(channelsProvider.future);
+      expect(session.activeChannels, {_channelA});
+
+      session.setStatus(SessionStatus.disconnected);
+      session.memberships = [_membership(_channelB, myPk)];
+      session.metadata = [_meta(id: _channelB, name: 'random')];
+      container
+          .read(relayConfigProvider.notifier)
+          .update(baseUrl: 'https://new-community.example');
+      await Future<void>.delayed(Duration.zero);
+      session.setStatus(SessionStatus.connected);
+      await container.read(channelsProvider.future);
+      await _waitUntil(
+        () =>
+            session.activeChannels.length == 1 &&
+            session.activeChannels.contains(_channelB),
+      );
+
+      expect(session.activeChannels, {_channelB});
+      expect(session.activeSubscriptionCount, 1);
+      expect(session.unsubscribeCount, 1);
+    },
+  );
+
   test('live channel events update channel lastMessageAt', () async {
     final session = _FakeRelaySession(
       memberships: [_membership(_channelA, myPk)],
@@ -423,6 +593,14 @@ ProviderContainer _buildContainer({required _FakeRelaySession session}) {
   );
 }
 
+Future<void> _waitUntil(bool Function() predicate) async {
+  for (var i = 0; i < 100; i++) {
+    if (predicate()) return;
+    await Future<void>.delayed(Duration.zero);
+  }
+  fail('Timed out waiting for asynchronous provider work');
+}
+
 /// Fake [RelaySessionNotifier] that returns canned events from [fetchHistory]
 /// and records subscribe calls.
 class _FakeRelaySession extends RelaySessionNotifier {
@@ -440,8 +618,40 @@ class _FakeRelaySession extends RelaySessionNotifier {
 
   final List<NostrFilter> historyFilters = [];
   final List<NostrFilter> subscribeFilters = [];
-  final List<void Function(NostrEvent)> _listeners = [];
+  final Map<int, (NostrFilter, void Function(NostrEvent))> _subscriptions = {};
+  int _nextSubscriptionKey = 0;
+  Completer<void>? _pausedSubscribe;
+  Completer<void>? _subscribeStarted;
   int unsubscribeCount = 0;
+  int totalSubscribeCount = 0;
+
+  Set<String> get activeChannels => {
+    for (final (filter, _) in _subscriptions.values) ?filter.tags['#h']?.single,
+  };
+
+  int get activeSubscriptionCount => _subscriptions.length;
+
+  Future<void> get nextSubscribeStarted async {
+    final started = _subscribeStarted;
+    if (started == null) {
+      throw StateError('No paused subscription is pending');
+    }
+    await started.future;
+  }
+
+  void pauseNextSubscribe() {
+    if (_pausedSubscribe != null) {
+      throw StateError('A subscription is already paused');
+    }
+    _pausedSubscribe = Completer<void>();
+    _subscribeStarted = Completer<void>();
+  }
+
+  void resumePausedSubscribe() {
+    final paused = _pausedSubscribe;
+    if (paused == null) throw StateError('No subscription is paused');
+    paused.complete();
+  }
 
   @override
   SessionState build() => const SessionState(status: SessionStatus.connected);
@@ -483,12 +693,22 @@ class _FakeRelaySession extends RelaySessionNotifier {
     void Function(NostrEvent) onEvent, {
     void Function(String message)? onClosed,
   }) async {
+    totalSubscribeCount++;
     subscribeFilters.add(filter);
-    _listeners.add(onEvent);
+    final paused = _pausedSubscribe;
+    if (paused != null) {
+      _subscribeStarted!.complete();
+      await paused.future;
+      _pausedSubscribe = null;
+      _subscribeStarted = null;
+    }
+    final subscriptionKey = ++_nextSubscriptionKey;
+    _subscriptions[subscriptionKey] = (filter, onEvent);
     return () {
+      final subscription = _subscriptions.remove(subscriptionKey);
+      if (subscription == null) return;
       unsubscribeCount++;
-      subscribeFilters.remove(filter);
-      _listeners.remove(onEvent);
+      subscribeFilters.remove(subscription.$1);
     };
   }
 
@@ -498,7 +718,7 @@ class _FakeRelaySession extends RelaySessionNotifier {
 
   /// Emit a live event to all subscribers.
   void emit(NostrEvent event) {
-    for (final listener in List.of(_listeners)) {
+    for (final (_, listener) in List.of(_subscriptions.values)) {
       listener(event);
     }
   }
diff --git a/mobile/test/features/channels/compose_bar_test.dart b/mobile/test/features/channels/compose_bar_test.dart
index bf236e8151..919d4039eb 100644
--- a/mobile/test/features/channels/compose_bar_test.dart
+++ b/mobile/test/features/channels/compose_bar_test.dart
@@ -17,11 +17,10 @@ import 'package:buzz/features/channels/channel.dart';
 import 'package:buzz/features/channels/channel_management_provider.dart';
 import 'package:buzz/features/channels/compose_bar.dart';
 import 'package:buzz/features/channels/channels_provider.dart';
-import 'package:buzz/features/channels/mentions/mention_candidates.dart';
-import 'package:buzz/features/channels/mentions/mention_candidates_provider.dart';
 import 'package:buzz/features/channels/photo_library.dart';
 import 'package:buzz/shared/custom_emoji/custom_emoji.dart';
 import 'package:buzz/shared/custom_emoji/custom_emoji_provider.dart';
+import 'package:buzz/shared/mentions/agent_identity_provider.dart';
 import 'package:buzz/shared/relay/relay.dart';
 import 'package:buzz/shared/theme/theme.dart';
 import 'package:shared_preferences/shared_preferences.dart';
@@ -544,6 +543,104 @@ void main() {
       }
     });
 
+    testWidgets('opening the native attachment popover keeps composer focus', (
+      tester,
+    ) async {
+      final previousPlatform = debugDefaultTargetPlatformOverride;
+      debugDefaultTargetPlatformOverride = TargetPlatform.iOS;
+      var presentCalls = 0;
+      _setMockNativeAttachmentPopoverHandler((call) async {
+        switch (call.method) {
+          case 'isSupported':
+            return true;
+          case 'present':
+            presentCalls += 1;
+            return true;
+          case 'dismiss':
+            return null;
+        }
+        return null;
+      });
+
+      try {
+        await tester.pumpWidget(
+          _buildComposeBar(
+            uploadService: _testUploadService(nostr.Keys.generate().nsec),
+            onSend:
+                (
+                  content,
+                  mentionPubkeys, {
+                  mediaTags = const <List<String>>[],
+                }) async {},
+          ),
+        );
+
+        await _expandComposer(tester);
+        await tester.enterText(find.byType(TextField), 'Hello');
+        await tester.pumpAndSettle();
+
+        final textField = tester.widget<TextField>(find.byType(TextField));
+        expect(textField.focusNode?.hasFocus, isTrue);
+
+        await tester.tap(find.byTooltip('Add attachment').hitTestable());
+        await tester.pumpAndSettle();
+
+        expect(presentCalls, 1);
+        expect(textField.focusNode?.hasFocus, isTrue);
+      } finally {
+        await _sendNativeAttachmentPopoverCall(tester, 'dismissed');
+        await tester.pumpWidget(const SizedBox.shrink());
+        _setMockNativeAttachmentPopoverHandler(null);
+        debugDefaultTargetPlatformOverride = previousPlatform;
+      }
+    });
+
+    testWidgets(
+      'unsupported iOS attachment popover unfocuses before fallback menu',
+      (tester) async {
+        final previousPlatform = debugDefaultTargetPlatformOverride;
+        debugDefaultTargetPlatformOverride = TargetPlatform.iOS;
+        _setMockNativeAttachmentPopoverHandler((call) async {
+          return switch (call.method) {
+            'isSupported' => false,
+            'dismiss' => null,
+            _ => null,
+          };
+        });
+
+        try {
+          await tester.pumpWidget(
+            _buildComposeBar(
+              uploadService: _testUploadService(nostr.Keys.generate().nsec),
+              onSend:
+                  (
+                    content,
+                    mentionPubkeys, {
+                    mediaTags = const <List<String>>[],
+                  }) async {},
+            ),
+          );
+
+          await _expandComposer(tester);
+          await tester.enterText(find.byType(TextField), 'Hello');
+          await tester.pumpAndSettle();
+
+          final textField = tester.widget<TextField>(find.byType(TextField));
+          expect(textField.focusNode?.hasFocus, isTrue);
+
+          await tester.tap(find.byTooltip('Add attachment').hitTestable());
+          await tester.pumpAndSettle();
+
+          expect(textField.focusNode?.hasFocus, isFalse);
+          expect(find.byKey(const ValueKey('attachment-menu')), findsOneWidget);
+        } finally {
+          await tester.pumpWidget(const SizedBox.shrink());
+          _setMockNativeAttachmentPopoverHandler(null);
+          debugDefaultTargetPlatformOverride = previousPlatform;
+        }
+      },
+    );
+
     testWidgets('disposing a non-owner keeps native popover callbacks active', (
       tester,
     ) async {
@@ -1150,6 +1247,161 @@ void main() {
       expect(find.text('Photos'), findsOneWidget);
     });
 
+    testWidgets('attachment menu uses roomy rows and surrounding padding', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        _buildComposeBar(
+          uploadService: _testUploadService(nostr.Keys.generate().nsec),
+          onSend:
+              (
+                content,
+                mentionPubkeys, {
+                mediaTags = const <List<String>>[],
+              }) async {},
+        ),
+      );
+
+      await _openAttachmentMenu(tester);
+
+      final menu = find.byKey(const ValueKey('attachment-menu'));
+      final rows = [
+        for (final label in ['camera', 'photos', 'video', 'files'])
+          find.byKey(ValueKey('attachment-menu-item-$label')),
+      ];
+      final menuRect = tester.getRect(menu);
+
+      expect(menuRect.size, const Size(216, 264));
+      for (final row in rows) {
+        expect(tester.getSize(row).height, 52);
+        expect(tester.getRect(row).left - menuRect.left, Grid.xs);
+        expect(menuRect.right - tester.getRect(row).right, Grid.xs);
+      }
+      for (final label in ['Camera', 'Photos', 'Video', 'Files']) {
+        final text = tester.widget<Text>(find.text(label));
+        expect(text.style?.fontSize, 20);
+      }
+      final icons = [
+        for (final label in ['camera', 'photos', 'video', 'files'])
+          find.byKey(ValueKey('attachment-menu-icon-$label')),
+      ];
+      final labels = [
+        for (final label in ['camera', 'photos', 'video', 'files'])
+          find.byKey(ValueKey('attachment-menu-label-$label')),
+      ];
+      for (final icon in icons) {
+        expect(tester.getSize(icon).width, 28);
+        expect(
+          tester
+              .widget<Icon>(
+                find.descendant(of: icon, matching: find.byType(Icon)),
+              )
+              .size,
+          24,
+        );
+      }
+      final labelLeft = tester.getRect(labels.first).left;
+      for (var index = 0; index < labels.length; index += 1) {
+        expect(tester.getRect(labels[index]).left, labelLeft);
+        expect(
+          tester.getRect(labels[index]).center.dy,
+          tester.getRect(rows[index]).center.dy,
+        );
+      }
+      expect(tester.getRect(rows.first).top - menuRect.top, Grid.xs);
+      expect(menuRect.bottom - tester.getRect(rows.last).bottom, Grid.xs);
+      for (var index = 1; index < rows.length; index += 1) {
+        expect(
+          tester.getRect(rows[index]).top -
+              tester.getRect(rows[index - 1]).bottom,
+          Grid.xxs,
+        );
+      }
+    });
+
+    testWidgets(
+      'attachment menu grows rows and scrolls for accessibility text',
+      (tester) async {
+        await tester.pumpWidget(
+          _buildComposeBar(
+            uploadService: _testUploadService(nostr.Keys.generate().nsec),
+            textScaler: const TextScaler.linear(4),
+            onSend:
+                (
+                  content,
+                  mentionPubkeys, {
+                  mediaTags = const <List<String>>[],
+                }) async {},
+          ),
+        );
+
+        await _openAttachmentMenu(tester);
+
+        final menu = find.byKey(const ValueKey('attachment-menu'));
+        final rows = [
+          for (final label in ['camera', 'photos', 'video', 'files'])
+            find.byKey(ValueKey('attachment-menu-item-$label')),
+        ];
+        final scrollView = tester.widget<ListView>(
+          find.byKey(const ValueKey('attachment-menu-scroll')),
+        );
+
+        expect(tester.getSize(menu), const Size(216, 372));
+        expect(tester.getSize(rows.first).height, greaterThan(52));
+        expect(scrollView.physics, isA<AlwaysScrollableScrollPhysics>());
+        await tester.drag(
+          find.byKey(const ValueKey('attachment-menu-scroll')),
+          const Offset(0, -300),
+        );
+        await tester.pump();
+        expect(tester.getSize(rows.last).height, greaterThan(52));
+        expect(tester.takeException(), isNull);
+      },
+    );
+
+    testWidgets('defers camera startup until the surface morph finishes', (
+      tester,
+    ) async {
+      final previousPlatform = debugDefaultTargetPlatformOverride;
+      debugDefaultTargetPlatformOverride = TargetPlatform.android;
+      try {
+        await tester.pumpWidget(
+          _buildComposeBar(
+            uploadService: _testUploadService(nostr.Keys.generate().nsec),
+            onSend:
+                (
+                  content,
+                  mentionPubkeys, {
+                  mediaTags = const <List<String>>[],
+                }) async {},
+          ),
+        );
+
+        await _openAttachmentMenu(tester);
+        await tester.tap(find.text('Camera'));
+        await tester.pump();
+
+        expect(
+          find.byKey(const ValueKey('camera-initialization-deferred')),
+          findsOneWidget,
+        );
+
+        await tester.pump(const Duration(milliseconds: 300));
+        expect(
+          find.byKey(const ValueKey('camera-initialization-deferred')),
+          findsOneWidget,
+        );
+
+        await tester.pump(const Duration(milliseconds: 20));
+        expect(
+          find.byKey(const ValueKey('camera-initialization-ready')),
+          findsOneWidget,
+        );
+      } finally {
+        debugDefaultTargetPlatformOverride = previousPlatform;
+      }
+    });
+
     testWidgets('photo picker errors keep the action visible at large text', (
       tester,
     ) async {
@@ -2016,6 +2268,11 @@ void main() {
       await tester.pumpAndSettle();
       await tester.tap(find.text('Helper Bot'));
       await tester.pumpAndSettle();
+      expect(find.byIcon(LucideIcons.bot), findsOneWidget);
+      expect(
+        find.byKey(const ValueKey('composer-agent-mention-chip')),
+        findsOneWidget,
+      );
       await tester.enterText(find.byType(TextField), 'hello @Helper Bot');
       await tester.tap(find.byIcon(LucideIcons.arrowUp));
       await tester.pumpAndSettle();
@@ -2032,6 +2289,70 @@ void main() {
       ]);
     });
 
+    testWidgets(
+      'renders chips only for selected agents outside code and composition',
+      (tester) async {
+        final semantics = tester.ensureSemantics();
+        final signer = nostr.Keys.generate();
+        await tester.pumpWidget(
+          _buildComposeBar(
+            uploadService: _testUploadService(signer.nsec),
+            currentPubkey: signer.public,
+            relayAgents: [_testAgent('f' * 64)],
+            channels: [_makeCurrentChannel(), _makeSharedMemberChannel()],
+            onSend:
+                (
+                  content,
+                  mentionPubkeys, {
+                  mediaTags = const <List<String>>[],
+                }) async {},
+          ),
+        );
+
+        await _expandComposer(tester);
+        await tester.enterText(find.byType(TextField), '@Helper Bot');
+        await tester.pump();
+        expect(
+          find.byKey(const ValueKey('composer-agent-mention-chip')),
+          findsNothing,
+        );
+
+        await tester.enterText(find.byType(TextField), '@hel');
+        await tester.pumpAndSettle();
+        await tester.tap(find.text('Helper Bot'));
+        await tester.pumpAndSettle();
+        expect(
+          find.byKey(const ValueKey('composer-agent-mention-chip')),
+          findsOneWidget,
+        );
+        expect(
+          find.bySemanticsLabel('Agent mention: Helper Bot'),
+          findsOneWidget,
+        );
+        expect(find.bySemanticsLabel('Helper Bot'), findsNothing);
+
+        await tester.enterText(find.byType(TextField), '`@Helper Bot`');
+        await tester.pump();
+        expect(
+          find.byKey(const ValueKey('composer-agent-mention-chip')),
+          findsNothing,
+        );
+
+        await tester.enterText(find.byType(TextField), '@Helper Bot typing');
+        final textField = tester.widget<TextField>(find.byType(TextField));
+        textField.controller!.value = textField.controller!.value.copyWith(
+          composing: const TextRange(start: 12, end: 18),
+        );
+        await tester.pump();
+        expect(
+          find.byKey(const ValueKey('composer-agent-mention-chip')),
+          findsOneWidget,
+        );
+        await tester.pump(const Duration(milliseconds: 250));
+        semantics.dispose();
+      },
+    );
+
     testWidgets('does not mutate a DM when mentioning a non-member agent', (
       tester,
     ) async {
diff --git a/mobile/test/features/channels/emoji_picker_test.dart b/mobile/test/features/channels/emoji_picker_test.dart
new file mode 100644
index 0000000000..1fc56f7317
--- /dev/null
+++ b/mobile/test/features/channels/emoji_picker_test.dart
@@ -0,0 +1,429 @@
+import 'package:buzz/features/channels/emoji_picker.dart';
+import 'package:buzz/features/channels/recent_emoji_provider.dart';
+import 'package:buzz/shared/custom_emoji/custom_emoji.dart';
+import 'package:buzz/shared/custom_emoji/custom_emoji_provider.dart';
+import 'package:buzz/shared/emoji/emoji_data.dart';
+import 'package:buzz/shared/emoji/emoji_data_provider.dart';
+import 'package:buzz/shared/relay/relay.dart';
+import 'package:buzz/shared/theme/theme.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+import '../../helpers/widget_helpers.dart';
+
+EmojiEntry _entry(
+  String id, {
+  required String native,
+  required String categoryId,
+  String? name,
+  List<String> keywords = const [],
+  int skinIndex = 0,
+}) => EmojiEntry(
+  id: id,
+  name: name ?? id,
+  keywords: keywords,
+  native: native,
+  categoryId: categoryId,
+  skinIndex: skinIndex,
+);
+
+/// A miniature stand-in for the generated asset — two categories so the rail
+/// has something to switch between. `emoji_data_test.dart` covers the real one.
+final _dataset = () {
+  final people = [
+    _entry('grinning', native: '\u{1F600}', categoryId: 'people'),
+    _entry(
+      'point_up',
+      native: '\u{261D}\u{FE0F}',
+      categoryId: 'people',
+      name: 'Index Pointing Up',
+    ),
+    _entry(
+      'point_up',
+      native: '\u{261D}\u{1F3FD}',
+      categoryId: 'people',
+      name: 'Index Pointing Up',
+      skinIndex: 1,
+    ),
+  ];
+  final nature = [
+    _entry(
+      'fire',
+      native: '\u{1F525}',
+      categoryId: 'nature',
+      name: 'Fire',
+      keywords: const ['flame'],
+    ),
+  ];
+  final all = [...people, ...nature];
+  return EmojiDataset(
+    categories: [
+      EmojiCategory(id: 'people', emoji: people),
+      EmojiCategory(id: 'nature', emoji: nature),
+    ],
+    all: all,
+    nativeToShortcode: {for (final entry in all) entry.native: ':${entry.id}:'},
+  );
+}();
+
+/// A dataset tall enough that the grid actually scrolls, so rail navigation has
+/// somewhere to go. [_dataset] fits on one screen and clamps to offset 0.
+final _tallDataset = () {
+  final people = [
+    for (var i = 0; i < 200; i++)
+      _entry('people_$i', native: '\u{1F600}', categoryId: 'people'),
+  ];
+  // Nature is tall too, so the People target isn't clamped by the end of the
+  // list — this test is about landing on a header, not about the clamp.
+  final nature = [
+    _entry('fire', native: '\u{1F525}', categoryId: 'nature'),
+    for (var i = 0; i < 200; i++)
+      _entry('nature_$i', native: '\u{1F33F}', categoryId: 'nature'),
+  ];
+  final all = [...people, ...nature];
+  return EmojiDataset(
+    categories: [
+      EmojiCategory(id: 'people', emoji: people),
+      EmojiCategory(id: 'nature', emoji: nature),
+    ],
+    all: all,
+    nativeToShortcode: {for (final entry in all) entry.native: ':${entry.id}:'},
+  );
+}();
+
+const _customEmoji = [
+  CustomEmoji(shortcode: 'partyparrot', url: 'https://example.test/parrot.gif'),
+];
+
+Future<SharedPreferences> _prefs() {
+  SharedPreferences.setMockInitialValues({});
+  return SharedPreferences.getInstance();
+}
+
+Future<List<String>> _pumpPicker(
+  WidgetTester tester, {
+  required SharedPreferences prefs,
+  List<CustomEmoji> customEmoji = _customEmoji,
+  EmojiDataset? dataset,
+}) async {
+  final selected = <String>[];
+  await tester.pumpWidget(
+    WidgetHelpers.testable(
+      overrides: [
+        savedPrefsProvider.overrideWithValue(prefs),
+        myPubkeyProvider.overrideWithValue('self'),
+        emojiDatasetOrEmptyProvider.overrideWithValue(dataset ?? _dataset),
+        customEmojiListProvider.overrideWithValue(customEmoji),
+      ],
+      child: EmojiPickerSheet(onSelect: selected.add),
+    ),
+  );
+  await tester.pumpAndSettle();
+  return selected;
+}
+
+void main() {
+  group('EmojiPickerSheet', () {
+    testWidgets('with no history there is no Frequently used section', (
+      tester,
+    ) async {
+      await _pumpPicker(tester, prefs: await _prefs());
+
+      // An empty section in a continuous list is a labelled gap, and its rail
+      // entry would lead nowhere — so it is omitted until something is picked.
+      expect(find.byTooltip('Frequently used'), findsNothing);
+      expect(find.text('Frequently used'), findsNothing);
+      expect(find.byKey(const ValueKey('emoji-picker-grid')), findsOneWidget);
+    });
+
+    testWidgets('every section lives in one continuous scroll view', (
+      tester,
+    ) async {
+      await _pumpPicker(tester, prefs: await _prefs());
+
+      // The old picker swapped the grid per tab, so only one category's emoji
+      // existed at a time. Now they are all in the same list — the rail is a
+      // shortcut into it, not a page switcher.
+      final grid = find.byKey(const ValueKey('emoji-picker-grid'));
+      expect(grid, findsOneWidget);
+      expect(
+        find.descendant(
+          of: grid,
+          matching: find.byKey(const ValueKey('emoji-tile-grinning')),
+        ),
+        findsOneWidget,
+      );
+      expect(
+        find.descendant(
+          of: grid,
+          matching: find.byKey(const ValueKey('emoji-tile-fire')),
+        ),
+        findsOneWidget,
+      );
+      expect(
+        find.descendant(
+          of: grid,
+          matching: find.byKey(const ValueKey('emoji-tile-custom-partyparrot')),
+        ),
+        findsOneWidget,
+      );
+    });
+
+    testWidgets('the rail divides the full tray width evenly', (tester) async {
+      await _pumpPicker(tester, prefs: await _prefs());
+
+      // The rail used to be a short left-aligned strip. Every section now gets
+      // one evenly-sized slot across the same width the search field spans.
+      final searchField = tester.getRect(
+        find.byKey(const ValueKey('emoji-picker-search')),
+      );
+      final people = tester.getRect(find.byTooltip('Smileys & People'));
+      final nature = tester.getRect(find.byTooltip('Animals & Nature'));
+      final custom = tester.getRect(find.byTooltip('Custom'));
+
+      expect(nature.left, greaterThan(people.left));
+      expect(custom.left, greaterThan(nature.left));
+      expect(people.width, closeTo(nature.width, 0.5));
+      expect(people.width, closeTo(custom.width, 0.5));
+      // First slot starts and last slot ends on the search field's edges.
+      expect(people.left, closeTo(searchField.left, 0.5));
+      expect(custom.right, closeTo(searchField.right, 0.5));
+    });
+
+    testWidgets('tapping the rail scrolls the grid instead of replacing it', (
+      tester,
+    ) async {
+      await _pumpPicker(tester, prefs: await _prefs(), dataset: _tallDataset);
+
+      final grid = find.byKey(const ValueKey('emoji-picker-grid'));
+      double offset() =>
+          tester.widget<CustomScrollView>(grid).controller!.offset;
+      expect(offset(), 0);
+
+      await tester.tap(find.byTooltip('Animals & Nature'));
+      await tester.pumpAndSettle();
+
+      // Same scroll view, moved — not a swapped-in second grid.
+      expect(grid, findsOneWidget);
+      expect(offset(), greaterThan(0));
+      // People has 200 emoji at 8 per row: 25 rows of 40px plus a 28px header.
+      expect(offset(), closeTo(28 + 25 * 40, 0.5));
+    });
+
+    testWidgets('the custom section only exists when the palette has emoji', (
+      tester,
+    ) async {
+      await _pumpPicker(tester, prefs: await _prefs(), customEmoji: const []);
+      expect(find.byTooltip('Custom'), findsNothing);
+      expect(
+        find.byKey(const ValueKey('emoji-tile-custom-partyparrot')),
+        findsNothing,
+      );
+
+      await _pumpPicker(tester, prefs: await _prefs());
+      expect(find.byTooltip('Custom'), findsOneWidget);
+      expect(
+        find.byKey(const ValueKey('emoji-tile-custom-partyparrot')),
+        findsOneWidget,
+      );
+    });
+
+    testWidgets('custom emoji sit in the same cell as native glyphs', (
+      tester,
+    ) async {
+      await _pumpPicker(tester, prefs: await _prefs());
+
+      // A community's own emoji used to get their own looser 6-per-row grid,
+      // which read as a different component bolted onto the sheet.
+      final native = tester.getRect(
+        find.byKey(const ValueKey('emoji-tile-fire')),
+      );
+      final custom = tester.getRect(
+        find.byKey(const ValueKey('emoji-tile-custom-partyparrot')),
+      );
+      expect(custom.width, closeTo(native.width, 0.5));
+      expect(custom.height, closeTo(native.height, 0.5));
+    });
+
+    testWidgets('typing filters across the standard and custom sets', (
+      tester,
+    ) async {
+      await _pumpPicker(tester, prefs: await _prefs());
+
+      await tester.enterText(
+        find.byKey(const ValueKey('emoji-picker-search')),
+        'flame',
+      );
+      await tester.pumpAndSettle();
+
+      expect(
+        find.byKey(const ValueKey('emoji-picker-search-results')),
+        findsOneWidget,
+      );
+      expect(find.byKey(const ValueKey('emoji-tile-fire')), findsOneWidget);
+      expect(find.byKey(const ValueKey('emoji-tile-grinning')), findsNothing);
+      // Searching hides the rail — the query is the navigation.
+      expect(find.byTooltip('Smileys & People'), findsNothing);
+
+      // Custom emoji rank in the same query, in their own section.
+      await tester.enterText(
+        find.byKey(const ValueKey('emoji-picker-search')),
+        'parrot',
+      );
+      await tester.pumpAndSettle();
+      expect(find.text('Custom'), findsOneWidget);
+      expect(
+        find.byKey(const ValueKey('emoji-tile-custom-partyparrot')),
+        findsOneWidget,
+      );
+    });
+
+    testWidgets('crosses the shortcode separator emoji-mart cannot', (
+      tester,
+    ) async {
+      await _pumpPicker(tester, prefs: await _prefs());
+
+      await tester.enterText(
+        find.byKey(const ValueKey('emoji-picker-search')),
+        'pointup',
+      );
+      await tester.pumpAndSettle();
+
+      expect(find.byKey(const ValueKey('emoji-tile-point_up')), findsOneWidget);
+    });
+
+    testWidgets('reports no results rather than an empty grid', (tester) async {
+      await _pumpPicker(tester, prefs: await _prefs());
+
+      await tester.enterText(
+        find.byKey(const ValueKey('emoji-picker-search')),
+        'zzzzzz',
+      );
+      await tester.pumpAndSettle();
+
+      expect(find.text('No emoji found.'), findsOneWidget);
+    });
+
+    testWidgets('clear button restores browsing', (tester) async {
+      await _pumpPicker(tester, prefs: await _prefs());
+
+      await tester.enterText(
+        find.byKey(const ValueKey('emoji-picker-search')),
+        'fire',
+      );
+      await tester.pumpAndSettle();
+      await tester.tap(find.byKey(const ValueKey('emoji-picker-search-clear')));
+      await tester.pumpAndSettle();
+
+      expect(
+        find.byKey(const ValueKey('emoji-picker-search-results')),
+        findsNothing,
+      );
+      expect(find.byTooltip('Smileys & People'), findsOneWidget);
+    });
+
+    testWidgets('a standard emoji emits its glyph', (tester) async {
+      final selected = await _pumpPicker(tester, prefs: await _prefs());
+
+      await tester.tap(find.byKey(const ValueKey('emoji-tile-fire')));
+      await tester.pumpAndSettle();
+
+      expect(selected, ['\u{1F525}']);
+    });
+
+    testWidgets('a skin-tone variant is selectable', (tester) async {
+      final selected = await _pumpPicker(tester, prefs: await _prefs());
+
+      await tester.tap(find.byKey(const ValueKey('emoji-tile-point_up-1')));
+      await tester.pumpAndSettle();
+
+      expect(selected, ['\u{261D}\u{1F3FD}']);
+    });
+
+    testWidgets('a custom emoji emits :shortcode:', (tester) async {
+      final selected = await _pumpPicker(tester, prefs: await _prefs());
+
+      await tester.tap(
+        find.byKey(const ValueKey('emoji-tile-custom-partyparrot')),
+      );
+      await tester.pumpAndSettle();
+
+      expect(selected, [':partyparrot:']);
+    });
+
+    testWidgets('a non-reaction selection does not record a quick reaction', (
+      tester,
+    ) async {
+      final prefs = await _prefs();
+      final selected = await _pumpPicker(tester, prefs: prefs);
+
+      await tester.tap(find.byKey(const ValueKey('emoji-tile-fire')));
+      await tester.pumpAndSettle();
+
+      expect(selected, ['\u{1F525}']);
+      expect(
+        prefs.getString(
+          'buzz.quick-reaction-emojis.v1:http://localhost:3000:self',
+        ),
+        isNull,
+      );
+    });
+
+    testWidgets('shows a spinner while the dataset is still loading', (
+      tester,
+    ) async {
+      final prefs = await _prefs();
+      await tester.pumpWidget(
+        WidgetHelpers.testable(
+          overrides: [
+            savedPrefsProvider.overrideWithValue(prefs),
+            myPubkeyProvider.overrideWithValue('self'),
+            emojiDatasetOrEmptyProvider.overrideWithValue(EmojiDataset.empty),
+            customEmojiListProvider.overrideWithValue(const []),
+          ],
+          child: EmojiPickerSheet(onSelect: (_) {}),
+        ),
+      );
+      // Not pumpAndSettle — the spinner animates forever.
+      await tester.pump();
+
+      expect(find.byType(CircularProgressIndicator), findsOneWidget);
+    });
+  });
+
+  group('recent emoji ranking', () {
+    test('promotes by use count, breaking ties on recency', () {
+      var entries = <RecentEmojiEntry>[];
+      entries = recordRecentEmoji(entries, 'a', now: 10);
+      entries = recordRecentEmoji(entries, 'b', now: 20);
+      entries = recordRecentEmoji(entries, 'b', now: 30);
+      entries = recordRecentEmoji(entries, 'c', now: 40);
+
+      expect(entries.map((entry) => entry.emoji), ['b', 'c', 'a']);
+      expect(entries.first.count, 2);
+    });
+
+    test('tops the quick row up with the defaults', () {
+      final entries = recordRecentEmoji(const [], '\u{1F525}', now: 1);
+      final row = quickReactionEmoji(entries, customShortcodes: const {});
+
+      expect(row.first, '\u{1F525}');
+      expect(row, hasLength(4));
+      expect(row, containsAll(defaultQuickEmojis.take(3)));
+    });
+
+    test('drops custom emoji no longer in the palette', () {
+      final entries = recordRecentEmoji(const [], ':gone:', now: 1);
+
+      expect(
+        quickReactionEmoji(entries, customShortcodes: const {}),
+        defaultQuickEmojis,
+      );
+      expect(
+        quickReactionEmoji(entries, customShortcodes: const {'gone'}).first,
+        ':gone:',
+      );
+    });
+  });
+}
diff --git a/mobile/test/features/channels/mentions/mention_candidates_test.dart b/mobile/test/features/channels/mentions/mention_candidates_test.dart
index 3f2e8e3d6a..811996857c 100644
--- a/mobile/test/features/channels/mentions/mention_candidates_test.dart
+++ b/mobile/test/features/channels/mentions/mention_candidates_test.dart
@@ -2,6 +2,7 @@ import 'package:flutter_test/flutter_test.dart';
 import 'package:buzz/features/channels/channel_management_provider.dart';
 import 'package:buzz/features/channels/mentions/mention_candidates.dart';
 import 'package:buzz/features/profile/user_profile.dart';
+import 'package:buzz/shared/mentions/agent_identity_provider.dart';
 
 final userPubkey = 'a' * 64;
 final memberPubkey = 'b' * 64;
@@ -18,6 +19,20 @@ ChannelMember member(String pubkey, {String role = 'member'}) {
 }
 
 void main() {
+  test('role-only agent mentions fall back to a pubkey prefix label', () {
+    const pubkey = 'deadbeef0123456789';
+
+    expect(
+      mentionNamesWithDirectoryLabels(
+        mentionPubkeys: const [pubkey],
+        profileMentionNames: const {},
+        directoryDisplayNames: const {},
+        agentMentionPubkeys: const {pubkey},
+      ),
+      const {pubkey: 'deadbeef'},
+    );
+  });
+
   group('agentIsSharedWithUser', () {
     test('anyone-mode agent is shared when a channel overlaps', () {
       final agent = AgentDirectoryEntry(
diff --git a/mobile/test/features/channels/message_content_test.dart b/mobile/test/features/channels/message_content_test.dart
index 91e31eee22..9d8adb69bc 100644
--- a/mobile/test/features/channels/message_content_test.dart
+++ b/mobile/test/features/channels/message_content_test.dart
@@ -6,6 +6,7 @@ import 'package:lucide_icons_flutter/lucide_icons.dart';
 import 'package:nostr/nostr.dart' as nostr;
 import 'package:buzz/features/channels/message_content.dart';
 import 'package:buzz/features/channels/media_viewer_page.dart';
+import 'package:buzz/shared/emoji/emoji_only.dart';
 import 'package:buzz/shared/relay/relay.dart';
 import 'package:buzz/shared/theme/theme.dart';
 
@@ -262,6 +263,93 @@ void main() {
       });
     });
 
+    group('emoji-only bodies', () {
+      /// Font size the body text actually rendered at.
+      ///
+      /// gpt_markdown resolves the style onto the spans rather than the root
+      /// RichText, which keeps the ambient 14px — so read the span carrying the
+      /// text, not the root.
+      double bodyFontSize(WidgetTester tester, String text) {
+        final richText = tester.widget<RichText>(_findRich(text).first);
+        double? size;
+        richText.text.visitChildren((span) {
+          if (span is TextSpan && (span.text ?? '').contains(text)) {
+            size ??= span.style?.fontSize;
+          }
+          return size == null;
+        });
+        return size ?? richText.text.style!.fontSize!;
+      }
+
+      testWidgets('an all-emoji body renders larger, like desktop', (
+        tester,
+      ) async {
+        await tester.pumpWidget(
+          _testable(
+            const MessageContent(content: '\u{1F389}', scaleEmojiOnly: true),
+          ),
+        );
+
+        expect(bodyFontSize(tester, '\u{1F389}'), kEmojiOnlyFontSize);
+      });
+
+      testWidgets('one word alongside the emoji keeps body size', (
+        tester,
+      ) async {
+        await tester.pumpWidget(
+          _testable(
+            const MessageContent(
+              content: 'ship it \u{1F389}',
+              scaleEmojiOnly: true,
+            ),
+          ),
+        );
+
+        expect(bodyFontSize(tester, 'ship it'), lessThan(kEmojiOnlyFontSize));
+      });
+
+      testWidgets('the scale is opt-in, so previews are unaffected', (
+        tester,
+      ) async {
+        await tester.pumpWidget(
+          _testable(const MessageContent(content: '\u{1F389}')),
+        );
+
+        expect(bodyFontSize(tester, '\u{1F389}'), lessThan(kEmojiOnlyFontSize));
+      });
+
+      testWidgets('a tagged custom emoji alone scales its image too', (
+        tester,
+      ) async {
+        await tester.pumpWidget(
+          _testable(
+            const MessageContent(
+              content: ':shipit:',
+              scaleEmojiOnly: true,
+              tags: [
+                ['emoji', 'shipit', 'https://relay.example/shipit.png'],
+              ],
+            ),
+          ),
+        );
+
+        final image = tester.widget<Image>(find.byType(Image));
+        expect(image.height, kEmojiOnlyCustomEmojiSize);
+      });
+
+      testWidgets('an unresolvable shortcode stays body size', (tester) async {
+        // Without a matching emoji tag it renders as literal text, so scaling it
+        // would blow up a `:word:` that was never emoji at all.
+        await tester.pumpWidget(
+          _testable(
+            const MessageContent(content: ':shipit:', scaleEmojiOnly: true),
+          ),
+        );
+
+        expect(bodyFontSize(tester, ':shipit:'), lessThan(kEmojiOnlyFontSize));
+      });
+    });
+
     group('inline formatting', () {
       testWidgets('renders bold text', (tester) async {
         await tester.pumpWidget(
@@ -539,6 +627,51 @@ Photos
         },
       );
 
+      testWidgets(
+        'keeps adjacent carousel images active and ends with a gutter',
+        (tester) async {
+          const first = 'https://example.com/media/gutter-one.png';
+          const second = 'https://example.com/media/gutter-two.png';
+          await tester.pumpWidget(
+            _testable(
+              const MessageContent(
+                content:
+                    '''
+![image]($first)
+![image]($second)
+''',
+                tags: [
+                  ['imeta', 'url $first', 'm image/png'],
+                  ['imeta', 'url $second', 'm image/png'],
+                ],
+              ),
+            ),
+          );
+          await tester.pumpAndSettle();
+
+          final carousel = find.byKey(const ValueKey('message-media-carousel'));
+          final pageViewFinder = find.descendant(
+            of: carousel,
+            matching: find.byType(PageView),
+          );
+          final pageView = tester.widget<PageView>(pageViewFinder);
+
+          expect(pageView.allowImplicitScrolling, isTrue);
+          expect(pageView.clipBehavior, Clip.none);
+
+          pageView.controller!.jumpToPage(1);
+          await tester.pumpAndSettle();
+
+          final lastCard = find.byKey(
+            const ValueKey('message-media-carousel-item:$second'),
+          );
+          expect(
+            tester.getRect(carousel).right - tester.getRect(lastCard).right,
+            Grid.gutter,
+          );
+        },
+      );
+
       testWidgets(
         'jumps to a selected gallery thumbnail when motion is disabled',
         (tester) async {
@@ -1071,6 +1204,43 @@ Photos
         expect(find.text('Alice'), findsOneWidget);
       });
 
+      testWidgets('renders a known agent mention with the bot chip', (
+        tester,
+      ) async {
+        await tester.pumpWidget(
+          _testable(
+            const MessageContent(
+              content: 'Ask @Helper Bot to investigate',
+              mentionNames: {'agent-pubkey': 'Helper Bot'},
+              agentMentionPubkeys: {'agent-pubkey'},
+              maxLines: 2,
+            ),
+          ),
+        );
+
+        expect(find.byIcon(LucideIcons.bot), findsOneWidget);
+        expect(find.text('@'), findsNothing);
+        expect(find.text('Helper Bot'), findsOneWidget);
+      });
+
+      testWidgets('normalizes passed multi-word agent mentions', (
+        tester,
+      ) async {
+        await tester.pumpWidget(
+          _testable(
+            const MessageContent(
+              content: 'Ask @Helper Bot to investigate',
+              mentionNames: {'agent-pubkey': 'Helper Bot'},
+              agentMentionPubkeys: {'agent-pubkey'},
+            ),
+          ),
+        );
+
+        expect(find.byIcon(LucideIcons.bot), findsOneWidget);
+        expect(find.text('Helper Bot'), findsOneWidget);
+        expect(_allRichText(tester), isNot(contains('Bot Bot')));
+      });
+
       testWidgets('highlights an entire multi-word display name', (
         tester,
       ) async {
diff --git a/mobile/test/features/channels/reaction_row_test.dart b/mobile/test/features/channels/reaction_row_test.dart
new file mode 100644
index 0000000000..053670f433
--- /dev/null
+++ b/mobile/test/features/channels/reaction_row_test.dart
@@ -0,0 +1,390 @@
+import 'package:buzz/features/channels/reaction_row.dart';
+import 'package:buzz/features/channels/timeline_message.dart';
+import 'package:buzz/shared/emoji/emoji_burst.dart';
+import 'package:buzz/shared/emoji/emoji_data.dart';
+import 'package:buzz/shared/emoji/emoji_data_provider.dart';
+import 'package:buzz/features/profile/user_cache_provider.dart';
+import 'package:buzz/features/profile/user_profile.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:hooks_riverpod/hooks_riverpod.dart';
+
+import '../../helpers/widget_helpers.dart';
+
+const _fire = '\u{1F525}';
+
+/// 👀 — a real reaction that is deliberately not in the positive-burst set.
+const _eyes = '\u{1F440}';
+
+TimelineReaction _reaction({
+  String emoji = _fire,
+  int count = 1,
+  bool reactedByCurrentUser = false,
+  List<String> userPubkeys = const ['alice'],
+}) => TimelineReaction(
+  emoji: emoji,
+  count: count,
+  reactedByCurrentUser: reactedByCurrentUser,
+  userPubkeys: userPubkeys,
+);
+
+final _dataset = EmojiDataset(
+  categories: const [],
+  all: const [
+    EmojiEntry(
+      id: 'fire',
+      name: 'Fire',
+      keywords: [],
+      native: _fire,
+      categoryId: 'nature',
+    ),
+  ],
+  nativeToShortcode: const {_fire: ':fire:'},
+);
+
+const _messageId = 'msg-1';
+
+/// Pumps the row and hands back the enclosing container, so tests can arm a
+/// pending burst or inspect the particle controller.
+///
+/// Re-pumping keeps the same `ProviderScope` state, which is what lets a test
+/// swap the reactions list — standing in for the relay echo — without losing
+/// the pending burst that was armed before it.
+Future<ProviderContainer> _pumpRow(
+  WidgetTester tester, {
+  required List<TimelineReaction> reactions,
+  void Function(String emoji)? onToggle,
+  bool showAddButton = false,
+  VoidCallback? onAddReaction,
+  String messageId = _messageId,
+}) async {
+  await tester.pumpWidget(
+    WidgetHelpers.testable(
+      overrides: [
+        emojiDatasetOrEmptyProvider.overrideWithValue(_dataset),
+        userCacheProvider.overrideWith(
+          () => _FakeUserCacheNotifier({
+            'alice': const UserProfile(pubkey: 'alice', displayName: 'Alice'),
+          }),
+        ),
+      ],
+      child: ReactionRow(
+        messageId: messageId,
+        reactions: reactions,
+        onToggle: onToggle ?? (_) {},
+        showAddButton: showAddButton,
+        onAddReaction: onAddReaction,
+      ),
+    ),
+  );
+  await tester.pumpAndSettle();
+  return ProviderScope.containerOf(tester.element(find.byType(ReactionRow)));
+}
+
+class _FakeUserCacheNotifier extends UserCacheNotifier {
+  final Map<String, UserProfile> _profiles;
+
+  _FakeUserCacheNotifier(this._profiles);
+
+  @override
+  Map<String, UserProfile> build() => _profiles;
+
+  @override
+  Future<void> preload(Iterable<String> pubkeys) async {}
+}
+
+void main() {
+  group('ReactionRow', () {
+    testWidgets('shows the count even at one, matching desktop', (
+      tester,
+    ) async {
+      await _pumpRow(tester, reactions: [_reaction()]);
+
+      expect(
+        find.byKey(const ValueKey('reaction-pill-$_fire')),
+        findsOneWidget,
+      );
+      expect(find.text('1'), findsOneWidget);
+    });
+
+    testWidgets('collapses entirely when there is nothing to show', (
+      tester,
+    ) async {
+      await _pumpRow(tester, reactions: const []);
+
+      expect(find.byType(Wrap), findsNothing);
+      expect(find.byKey(const ValueKey('add-reaction-pill')), findsNothing);
+    });
+
+    testWidgets('renders the + pill on an empty row when asked', (
+      tester,
+    ) async {
+      var taps = 0;
+      await _pumpRow(
+        tester,
+        reactions: const [],
+        showAddButton: true,
+        onAddReaction: () => taps++,
+      );
+
+      final addPill = find.byKey(const ValueKey('add-reaction-pill'));
+      expect(addPill, findsOneWidget);
+      await tester.tap(addPill);
+      expect(taps, 1);
+    });
+
+    testWidgets('+ pill trails the existing reactions', (tester) async {
+      await _pumpRow(
+        tester,
+        reactions: [
+          _reaction(),
+          _reaction(emoji: '\u{1F44D}', count: 3),
+        ],
+        showAddButton: true,
+        onAddReaction: () {},
+      );
+
+      final firstPill = tester.getRect(
+        find.byKey(const ValueKey('reaction-pill-$_fire')),
+      );
+      final lastPill = tester.getRect(
+        find.byKey(const ValueKey('reaction-pill-\u{1F44D}')),
+      );
+      final addPill = tester.getRect(
+        find.byKey(const ValueKey('add-reaction-pill')),
+      );
+
+      // One row, in order, with the + last.
+      expect(lastPill.left, greaterThan(firstPill.left));
+      expect(addPill.left, greaterThan(lastPill.left));
+      expect(addPill.top, firstPill.top);
+
+      // Pills hug their content. A `Container.alignment` here would silently
+      // stretch each one to the full row width and stack them vertically.
+      expect(firstPill.height, 28);
+      expect(firstPill.width, greaterThanOrEqualTo(48));
+      expect(firstPill.width, lessThan(120));
+      expect(addPill.width, 40);
+    });
+
+    testWidgets('the + pill stays hidden without a handler', (tester) async {
+      await _pumpRow(tester, reactions: [_reaction()], showAddButton: true);
+
+      expect(find.byKey(const ValueKey('add-reaction-pill')), findsNothing);
+    });
+
+    testWidgets('tapping a pill toggles that emoji', (tester) async {
+      final toggled = <String>[];
+      await _pumpRow(tester, reactions: [_reaction()], onToggle: toggled.add);
+
+      await tester.tap(find.byKey(const ValueKey('reaction-pill-$_fire')));
+      expect(toggled, [_fire]);
+    });
+
+    testWidgets('long-press opens the detail sheet named from the dataset', (
+      tester,
+    ) async {
+      await _pumpRow(
+        tester,
+        reactions: [
+          _reaction(count: 1, userPubkeys: const ['alice']),
+        ],
+      );
+
+      await tester.longPress(
+        find.byKey(const ValueKey('reaction-pill-$_fire')),
+      );
+      await tester.pumpAndSettle();
+
+      expect(find.text(':fire:'), findsOneWidget);
+      expect(find.text('Alice'), findsOneWidget);
+    });
+  });
+
+  group('reaction bursts', () {
+    testWidgets('adding a positive reaction bursts from the pill', (
+      tester,
+    ) async {
+      final container = await _pumpRow(tester, reactions: [_reaction()]);
+      final controller = container.read(emojiBurstControllerProvider);
+      expect(controller.hasParticles, isFalse);
+
+      await tester.tap(find.byKey(const ValueKey('reaction-pill-$_fire')));
+      await tester.pump();
+
+      expect(controller.hasParticles, isTrue);
+    });
+
+    testWidgets('a non-positive reaction does not burst', (tester) async {
+      final container = await _pumpRow(
+        tester,
+        reactions: [_reaction(emoji: _eyes)],
+      );
+      final controller = container.read(emojiBurstControllerProvider);
+
+      await tester.tap(find.byKey(const ValueKey('reaction-pill-$_eyes')));
+      await tester.pump();
+
+      expect(controller.hasParticles, isFalse);
+    });
+
+    testWidgets('removing your own reaction does not burst', (tester) async {
+      final container = await _pumpRow(
+        tester,
+        reactions: [_reaction(reactedByCurrentUser: true)],
+      );
+      final controller = container.read(emojiBurstControllerProvider);
+
+      await tester.tap(find.byKey(const ValueKey('reaction-pill-$_fire')));
+      await tester.pump();
+
+      expect(controller.hasParticles, isFalse);
+    });
+
+    testWidgets('a pending burst fires when the new pill arrives', (
+      tester,
+    ) async {
+      // Reacting from the quick row or the picker arms a burst, then the pill
+      // only appears once the relay echoes the reaction back.
+      final container = await _pumpRow(tester, reactions: const []);
+      final controller = container.read(emojiBurstControllerProvider);
+      container
+          .read(pendingReactionBurstProvider.notifier)
+          .arm(_messageId, _fire);
+
+      await _pumpRow(
+        tester,
+        reactions: [_reaction(reactedByCurrentUser: true)],
+      );
+      await tester.pump();
+
+      expect(controller.hasParticles, isTrue);
+      // Claimed, so a second row showing the same message can't double-burst.
+      expect(container.read(pendingReactionBurstProvider), isNull);
+    });
+
+    testWidgets('a pending burst waits for our own reaction, not anyone\'s', (
+      tester,
+    ) async {
+      final container = await _pumpRow(tester, reactions: const []);
+      final controller = container.read(emojiBurstControllerProvider);
+      container
+          .read(pendingReactionBurstProvider.notifier)
+          .arm(_messageId, _fire);
+
+      // Someone else's reaction lands first.
+      await _pumpRow(tester, reactions: [_reaction()]);
+      await tester.pump();
+
+      expect(controller.hasParticles, isFalse);
+      expect(container.read(pendingReactionBurstProvider), isNotNull);
+    });
+
+    testWidgets('a pending burst armed for another message is left alone', (
+      tester,
+    ) async {
+      final container = await _pumpRow(tester, reactions: const []);
+      final controller = container.read(emojiBurstControllerProvider);
+      container
+          .read(pendingReactionBurstProvider.notifier)
+          .arm('some-other-message', _fire);
+
+      await _pumpRow(
+        tester,
+        reactions: [_reaction(reactedByCurrentUser: true)],
+      );
+      await tester.pump();
+
+      expect(controller.hasParticles, isFalse);
+      expect(container.read(pendingReactionBurstProvider), isNotNull);
+    });
+
+    testWidgets(
+      'a pill under a pushed route leaves the burst for the top one',
+      (tester) async {
+        // The channel timeline stays mounted under a pushed thread page and
+        // rebuilds first, so without a route check it claimed the burst and the
+        // user saw nothing until they popped back.
+        final navigatorKey = GlobalKey<NavigatorState>();
+        late ProviderContainer container;
+
+        await tester.pumpWidget(
+          ProviderScope(
+            overrides: [
+              emojiDatasetOrEmptyProvider.overrideWithValue(_dataset),
+              userCacheProvider.overrideWith(
+                () => _FakeUserCacheNotifier(const {}),
+              ),
+            ],
+            child: MaterialApp(
+              navigatorKey: navigatorKey,
+              home: Scaffold(
+                body: ReactionRow(
+                  messageId: _messageId,
+                  reactions: [_reaction(reactedByCurrentUser: true)],
+                  onToggle: (_) {},
+                ),
+              ),
+            ),
+          ),
+        );
+        await tester.pumpAndSettle();
+        container = ProviderScope.containerOf(
+          tester.element(find.byType(ReactionRow)),
+        );
+        final controller = container.read(emojiBurstControllerProvider);
+
+        // Push a route over it, then arm and let the covered pill rebuild.
+        navigatorKey.currentState!.push(
+          MaterialPageRoute<void>(
+            builder: (_) => const Scaffold(body: Text('thread')),
+          ),
+        );
+        await tester.pumpAndSettle();
+        container
+            .read(pendingReactionBurstProvider.notifier)
+            .arm(_messageId, _fire);
+        await tester.pump();
+
+        expect(controller.hasParticles, isFalse);
+        // Still armed, so the pill on the visible route can claim it.
+        expect(container.read(pendingReactionBurstProvider), isNotNull);
+      },
+    );
+
+    testWidgets('reduced motion suppresses the burst', (tester) async {
+      await tester.pumpWidget(
+        ProviderScope(
+          overrides: [
+            emojiDatasetOrEmptyProvider.overrideWithValue(_dataset),
+            userCacheProvider.overrideWith(
+              () => _FakeUserCacheNotifier(const {}),
+            ),
+          ],
+          child: MediaQuery(
+            data: const MediaQueryData(disableAnimations: true),
+            child: MaterialApp(
+              home: Scaffold(
+                body: ReactionRow(
+                  messageId: _messageId,
+                  reactions: [_reaction()],
+                  onToggle: (_) {},
+                ),
+              ),
+            ),
+          ),
+        ),
+      );
+      await tester.pumpAndSettle();
+      final container = ProviderScope.containerOf(
+        tester.element(find.byType(ReactionRow)),
+      );
+      final controller = container.read(emojiBurstControllerProvider);
+
+      await tester.tap(find.byKey(const ValueKey('reaction-pill-$_fire')));
+      await tester.pump();
+
+      expect(controller.hasParticles, isFalse);
+    });
+  });
+}
diff --git a/mobile/test/features/channels/timeline_message_test.dart b/mobile/test/features/channels/timeline_message_test.dart
index 87f39d1c65..c29a12aef4 100644
--- a/mobile/test/features/channels/timeline_message_test.dart
+++ b/mobile/test/features/channels/timeline_message_test.dart
@@ -287,6 +287,53 @@ void main() {
       );
     });
 
+    // The relay reports a clear as a change carrying an empty string, so
+    // without the cleared branch this reads: changed the topic to "".
+    test('a blank topic or purpose reads as cleared', () {
+      for (final blank in [null, '', '   \n\t ']) {
+        expect(
+          SystemEvent(
+            type: SystemEventType.topicChanged,
+            actorPubkey: 'pk1',
+            topic: blank,
+          ).describe(resolve),
+          'Alice cleared the topic',
+        );
+        expect(
+          SystemEvent(
+            type: SystemEventType.purposeChanged,
+            actorPubkey: 'pk1',
+            purpose: blank,
+          ).describe(resolve),
+          'Alice cleared the purpose',
+        );
+      }
+    });
+
+    test('no caption announces empty quotes', () {
+      for (final value in [null, '', ' ', 'Real topic']) {
+        expect(
+          SystemEvent(
+            type: SystemEventType.topicChanged,
+            actorPubkey: 'pk1',
+            topic: value,
+          ).describe(resolve),
+          isNot(contains('""')),
+        );
+      }
+    });
+
+    test('surrounding whitespace is trimmed out of the quotes', () {
+      expect(
+        SystemEvent(
+          type: SystemEventType.topicChanged,
+          actorPubkey: 'pk1',
+          topic: '  Release v2  ',
+        ).describe(resolve),
+        'Alice changed the topic to "Release v2"',
+      );
+    });
+
     test('channel_created', () {
       final event = SystemEvent(
         type: SystemEventType.channelCreated,
diff --git a/mobile/test/features/search/recent_searches_provider_test.dart b/mobile/test/features/search/recent_searches_provider_test.dart
index 30f13c329c..df0a08a8ea 100644
--- a/mobile/test/features/search/recent_searches_provider_test.dart
+++ b/mobile/test/features/search/recent_searches_provider_test.dart
@@ -35,6 +35,27 @@ void main() {
     return container;
   }
 
+  test('an invite-joined community keeps its recent searches after '
+      'origin canonicalization', () async {
+    const legacyKey = 'recent_searches_v1:wss://relay-a.example:pk-a';
+    const canonicalKey = 'recent_searches_v1:https://relay-a.example:pk-a';
+    SharedPreferences.setMockInitialValues({
+      legacyKey: <String>['nostr', 'relays'],
+    });
+
+    final container = await containerWithPrefs(
+      relayUrl: 'wss://relay-a.example',
+      pubkey: 'pk-a',
+    );
+
+    expect(container.read(recentSearchesProvider), ['nostr', 'relays']);
+
+    await Future<void>.delayed(Duration.zero);
+    final prefs = await SharedPreferences.getInstance();
+    expect(prefs.getStringList(canonicalKey), ['nostr', 'relays']);
+    expect(prefs.getStringList(legacyKey), isNull);
+  });
+
   test(
     'normalizes, deduplicates, caps, and persists submitted queries',
     () async {
diff --git a/mobile/test/features/search/search_page_test.dart b/mobile/test/features/search/search_page_test.dart
index 52c2fb23ae..c3db833fc1 100644
--- a/mobile/test/features/search/search_page_test.dart
+++ b/mobile/test/features/search/search_page_test.dart
@@ -10,8 +10,10 @@ import 'package:buzz/features/search/recent_searches_provider.dart';
 import 'package:buzz/features/search/search_page.dart';
 import 'package:buzz/features/search/search_provider.dart';
 import 'package:buzz/shared/theme/theme.dart';
+import 'package:buzz/shared/mentions/agent_identity_provider.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
+import 'package:lucide_icons_flutter/lucide_icons.dart';
 
 import '../../helpers/widget_helpers.dart';
 
@@ -248,6 +250,7 @@ void main() {
     tester,
   ) async {
     const keyboardInset = 300.0;
+    const footerClearance = 102.0;
 
     await tester.pumpWidget(
       WidgetHelpers.testable(
@@ -266,6 +269,7 @@ void main() {
         child: Builder(
           builder: (context) => MediaQuery(
             data: MediaQuery.of(context).copyWith(
+              padding: const EdgeInsets.only(bottom: footerClearance),
               viewInsets: const EdgeInsets.only(bottom: keyboardInset),
             ),
             child: const SearchPage(),
@@ -282,13 +286,14 @@ void main() {
     );
     final padding = recentSearches.padding! as EdgeInsets;
 
-    expect(padding.bottom, Grid.xl + keyboardInset);
+    expect(padding.bottom, Grid.xl + footerClearance + keyboardInset);
   });
 
   testWidgets('keeps search results scrollable above the keyboard', (
     tester,
   ) async {
     const keyboardInset = 300.0;
+    const footerClearance = 102.0;
     final state = SearchState(
       query: 'general',
       channelResults: [
@@ -318,6 +323,7 @@ void main() {
         child: Builder(
           builder: (context) => MediaQuery(
             data: MediaQuery.of(context).copyWith(
+              padding: const EdgeInsets.only(bottom: footerClearance),
               viewInsets: const EdgeInsets.only(bottom: keyboardInset),
             ),
             child: const SearchPage(),
@@ -332,7 +338,7 @@ void main() {
     );
     final padding = results.padding! as EdgeInsets;
 
-    expect(padding.bottom, Grid.xl + keyboardInset);
+    expect(padding.bottom, Grid.xl + footerClearance + keyboardInset);
   });
 
   testWidgets('keeps no-results feedback above the keyboard', (tester) async {
@@ -589,6 +595,72 @@ void main() {
     await tester.pump();
     expect(recentSearches.searches, const ['design']);
   });
+
+  testWidgets('renders channel-role bots in message previews', (tester) async {
+    final channel = Channel(
+      id: 'channel-1',
+      name: 'general',
+      channelType: 'stream',
+      visibility: 'open',
+      description: '',
+      createdBy: 'test',
+      createdAt: DateTime(2025),
+      memberCount: 2,
+      isMember: true,
+    );
+    const agentPubkey = 'agent-pubkey';
+    const cachedProfile = UserProfile(pubkey: 'author-pubkey');
+    final state = SearchState(
+      query: 'helper',
+      messageResults: [
+        SearchHit(
+          eventId: 'message-1',
+          content: 'Ask @Helper Bot to investigate',
+          kind: 9,
+          pubkey: 'author-pubkey',
+          channelId: channel.id,
+          channelName: channel.name,
+          createdAt: 1,
+          score: 1,
+          tags: [
+            ['p', agentPubkey],
+          ],
+        ),
+      ],
+    );
+
+    await tester.pumpWidget(
+      WidgetHelpers.testable(
+        overrides: [
+          searchProvider.overrideWith(() => _FakeSearchNotifier(state)),
+          recentSearchesProvider.overrideWith(
+            () => _FakeRecentSearchesNotifier(const []),
+          ),
+          profileProvider.overrideWith(() => _FakeProfileNotifier()),
+          channelsProvider.overrideWith(() => _FakeChannelsNotifier([channel])),
+          userCacheProvider.overrideWith(
+            () => _FakeUserCacheNotifier(cachedProfile),
+          ),
+          knownAgentPubkeysProvider.overrideWith((ref) => const {}),
+          channelBotPubkeysProvider(
+            channel.id,
+          ).overrideWith((ref) async => {agentPubkey}),
+          agentDirectoryDisplayNamesProvider.overrideWith(
+            (ref) => const {agentPubkey: 'Helper Bot'},
+          ),
+        ],
+        child: const SearchPage(),
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    final content = tester.widget<MessageContent>(
+      find.byKey(const ValueKey('search-message-body-message-1')),
+    );
+    expect(content.mentionNames, const {agentPubkey: 'Helper Bot'});
+    expect(content.agentMentionPubkeys, contains(agentPubkey));
+    expect(find.byIcon(LucideIcons.bot), findsOneWidget);
+  });
 }
 
 class _FakeSearchNotifier extends SearchNotifier {
@@ -642,8 +714,12 @@ class _FakeProfileNotifier extends ProfileNotifier {
 }
 
 class _FakeChannelsNotifier extends ChannelsNotifier {
+  _FakeChannelsNotifier([this.channels = const []]);
+
+  final List<Channel> channels;
+
   @override
-  Future<List<Channel>> build() async => const [];
+  Future<List<Channel>> build() async => channels;
 }
 
 class _FakeUserCacheNotifier extends UserCacheNotifier {
diff --git a/mobile/test/shared/emoji/emoji_burst_test.dart b/mobile/test/shared/emoji/emoji_burst_test.dart
new file mode 100644
index 0000000000..52041f25a2
--- /dev/null
+++ b/mobile/test/shared/emoji/emoji_burst_test.dart
@@ -0,0 +1,227 @@
+import 'package:buzz/shared/emoji/emoji_burst.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:hooks_riverpod/hooks_riverpod.dart';
+
+const _fire = '\u{1F525}';
+
+/// Run the controller forward until it says it is done, capped so a physics
+/// regression fails the test instead of hanging it.
+int _runToCompletion(EmojiBurstController controller, {int maxSteps = 600}) {
+  var steps = 0;
+  while (controller.hasParticles && steps < maxSteps) {
+    controller.step();
+    steps += 1;
+  }
+  return steps;
+}
+
+void main() {
+  group('EmojiBurstController', () {
+    test('a burst spawns particles and eventually clears itself', () {
+      final controller = EmojiBurstController();
+      addTearDown(controller.dispose);
+
+      expect(controller.hasParticles, isFalse);
+      controller.burst(_fire, const Offset(100, 200));
+      expect(controller.hasParticles, isTrue);
+
+      final steps = _runToCompletion(controller);
+      expect(controller.hasParticles, isFalse);
+      // Desktop's particles live 108 frames and fade over the last 24%.
+      expect(steps, lessThanOrEqualTo(108));
+      expect(steps, greaterThan(60));
+    });
+
+    test('ignores a blank emoji', () {
+      final controller = EmojiBurstController();
+      addTearDown(controller.dispose);
+
+      controller.burst('   ', Offset.zero);
+      expect(controller.hasParticles, isFalse);
+    });
+
+    test('notifies on spawn and on every step', () {
+      final controller = EmojiBurstController();
+      addTearDown(controller.dispose);
+
+      var notifications = 0;
+      controller.addListener(() => notifications += 1);
+
+      controller.burst(_fire, Offset.zero);
+      expect(notifications, 1);
+
+      controller.step();
+      expect(notifications, 2);
+    });
+
+    test('calls onSpawn so the overlay can start its ticker', () {
+      final controller = EmojiBurstController();
+      addTearDown(controller.dispose);
+
+      var spawns = 0;
+      controller.onSpawn = () => spawns += 1;
+
+      controller.burst(_fire, Offset.zero);
+      controller.burst(_fire, Offset.zero);
+      expect(spawns, 2);
+    });
+
+    test('caps the active particle count', () {
+      final controller = EmojiBurstController();
+      addTearDown(controller.dispose);
+
+      // Far more bursts than the cap allows, with no steps in between so
+      // nothing expires.
+      for (var i = 0; i < 200; i += 1) {
+        controller.burst(_fire, Offset.zero);
+      }
+
+      // Still bounded, and still animating rather than wedged.
+      expect(controller.hasParticles, isTrue);
+      _runToCompletion(controller);
+      expect(controller.hasParticles, isFalse);
+    });
+
+    test('clear drops everything immediately', () {
+      final controller = EmojiBurstController();
+      addTearDown(controller.dispose);
+
+      controller.burst(_fire, Offset.zero);
+      controller.clear();
+      expect(controller.hasParticles, isFalse);
+    });
+  });
+
+  group('PendingReactionBurstNotifier', () {
+    ProviderContainer container() {
+      final result = ProviderContainer();
+      addTearDown(result.dispose);
+      return result;
+    }
+
+    test('arms only positive emoji', () {
+      final ref = container();
+      final notifier = ref.read(pendingReactionBurstProvider.notifier);
+
+      notifier.arm('msg-1', '\u{1F44E}'); // 👎
+      expect(ref.read(pendingReactionBurstProvider), isNull);
+
+      notifier.arm('msg-1', _fire);
+      expect(
+        ref.read(pendingReactionBurstProvider),
+        const PendingReactionBurst(messageId: 'msg-1', emoji: _fire),
+      );
+    });
+
+    test('claim succeeds once, so one pill bursts when a message is on screen '
+        'twice', () {
+      final ref = container();
+      final notifier = ref.read(pendingReactionBurstProvider.notifier);
+      const target = PendingReactionBurst(messageId: 'msg-1', emoji: _fire);
+
+      notifier.arm('msg-1', _fire);
+      expect(notifier.claim(target), isTrue);
+      expect(notifier.claim(target), isFalse);
+      expect(ref.read(pendingReactionBurstProvider), isNull);
+    });
+
+    test('a claim for a different message or emoji does not consume it', () {
+      final ref = container();
+      final notifier = ref.read(pendingReactionBurstProvider.notifier);
+
+      notifier.arm('msg-1', _fire);
+      expect(
+        notifier.claim(
+          const PendingReactionBurst(messageId: 'msg-2', emoji: _fire),
+        ),
+        isFalse,
+      );
+      expect(
+        notifier.claim(
+          const PendingReactionBurst(messageId: 'msg-1', emoji: '\u{1F389}'),
+        ),
+        isFalse,
+      );
+      expect(ref.read(pendingReactionBurstProvider), isNotNull);
+    });
+
+    test('a newer arm replaces the pending one', () {
+      final ref = container();
+      final notifier = ref.read(pendingReactionBurstProvider.notifier);
+
+      notifier.arm('msg-1', _fire);
+      notifier.arm('msg-2', '\u{1F389}');
+      expect(
+        ref.read(pendingReactionBurstProvider),
+        const PendingReactionBurst(messageId: 'msg-2', emoji: '\u{1F389}'),
+      );
+    });
+  });
+
+  group('EmojiBurstOverlay', () {
+    testWidgets('paints its child and drains the burst', (tester) async {
+      late EmojiBurstController controller;
+
+      await tester.pumpWidget(
+        ProviderScope(
+          child: MaterialApp(
+            home: Consumer(
+              builder: (context, ref, _) {
+                controller = ref.watch(emojiBurstControllerProvider);
+                return const EmojiBurstOverlay(child: Text('body'));
+              },
+            ),
+          ),
+        ),
+      );
+
+      expect(find.text('body'), findsOneWidget);
+
+      controller.burst(_fire, const Offset(120, 240));
+      expect(controller.hasParticles, isTrue);
+
+      // Physics advances a bounded number of fixed steps per frame (no
+      // catch-up spiral), so drain it a frame at a time — 130 frames is past
+      // the 108-frame particle life.
+      await tester.pump();
+      for (var frame = 0; frame < 130; frame += 1) {
+        await tester.pump(const Duration(milliseconds: 16));
+      }
+      expect(controller.hasParticles, isFalse);
+    });
+
+    testWidgets('the overlay never takes a tap from the app below', (
+      tester,
+    ) async {
+      var taps = 0;
+      late EmojiBurstController controller;
+
+      await tester.pumpWidget(
+        ProviderScope(
+          child: MaterialApp(
+            home: Consumer(
+              builder: (context, ref, _) {
+                controller = ref.watch(emojiBurstControllerProvider);
+                return EmojiBurstOverlay(
+                  child: Center(
+                    child: GestureDetector(
+                      onTap: () => taps += 1,
+                      child: const Text('tap me'),
+                    ),
+                  ),
+                );
+              },
+            ),
+          ),
+        ),
+      );
+
+      controller.burst(_fire, const Offset(200, 400));
+      await tester.pump();
+
+      await tester.tap(find.text('tap me'));
+      expect(taps, 1);
+    });
+  });
+}
diff --git a/mobile/test/shared/emoji/emoji_data_test.dart b/mobile/test/shared/emoji/emoji_data_test.dart
new file mode 100644
index 0000000000..fd7356ae7a
--- /dev/null
+++ b/mobile/test/shared/emoji/emoji_data_test.dart
@@ -0,0 +1,81 @@
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:buzz/shared/emoji/emoji_data.dart';
+import 'package:buzz/shared/emoji/emoji_data_provider.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+/// Reads the committed asset straight off disk rather than through
+/// `rootBundle`, so this test guards the generated file itself — if
+/// `just mobile-emoji-data` ever emits a different shape, this fails.
+EmojiDataset _loadFromDisk() {
+  final source = File(emojiDataAssetPath).readAsStringSync();
+  return EmojiDataset.fromJson(jsonDecode(source) as Map<String, dynamic>);
+}
+
+void main() {
+  late EmojiDataset dataset;
+
+  setUpAll(() {
+    dataset = _loadFromDisk();
+  });
+
+  test('parses every emoji-mart category in order', () {
+    expect(dataset.categories.map((category) => category.id), [
+      'people',
+      'nature',
+      'foods',
+      'activity',
+      'places',
+      'objects',
+      'symbols',
+      'flags',
+    ]);
+  });
+
+  test('carries the full standard set, not a hand-picked subset', () {
+    // The hardcoded list this replaced had ~140 glyphs; emoji-mart ships ~1.9k.
+    expect(dataset.all.length, greaterThan(1800));
+    expect(
+      dataset.all.length,
+      dataset.categories.fold<int>(
+        0,
+        (total, category) => total + category.emoji.length,
+      ),
+    );
+  });
+
+  test('every entry has an id, a glyph, and a category', () {
+    for (final entry in dataset.all) {
+      expect(entry.id, isNotEmpty);
+      expect(entry.native, isNotEmpty);
+      expect(entry.categoryId, isNotEmpty);
+    }
+  });
+
+  test('resolves glyphs back to desktop-identical shortcodes', () {
+    expect(dataset.nativeToShortcode['💯'], ':100:');
+    expect(dataset.nativeToShortcode['🔥'], ':fire:');
+    expect(dataset.nativeToShortcode['☝️'], ':point_up:');
+    expect(dataset.nativeToShortcode['👍🏽'], ':+1:');
+    expect(
+      dataset.all
+          .where((entry) => entry.id == '+1')
+          .map((entry) => entry.native),
+      containsAll(['👍', '👍🏻', '👍🏼', '👍🏽', '👍🏾', '👍🏿']),
+    );
+  });
+
+  test('displayName mirrors desktop emojiDisplayName', () {
+    expect(dataset.displayName('🎉'), ':tada:');
+    // Custom emoji already arrive as a shortcode and pass through untouched.
+    expect(dataset.displayName(':party_parrot:'), ':party_parrot:');
+    // Unknown glyphs fall back to themselves rather than a bogus name.
+    expect(dataset.displayName('\u{1FAF6}\u{200D}\u{2764}'), isNotEmpty);
+  });
+
+  test('empty dataset degrades safely', () {
+    expect(EmojiDataset.empty.isEmpty, isTrue);
+    expect(EmojiDataset.empty.displayName('🔥'), '🔥');
+  });
+}
diff --git a/mobile/test/shared/emoji/emoji_only_test.dart b/mobile/test/shared/emoji/emoji_only_test.dart
new file mode 100644
index 0000000000..261b7d7cf1
--- /dev/null
+++ b/mobile/test/shared/emoji/emoji_only_test.dart
@@ -0,0 +1,81 @@
+import 'package:buzz/shared/custom_emoji/custom_emoji.dart';
+import 'package:buzz/shared/emoji/emoji_only.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+const _customEmoji = [
+  CustomEmoji(shortcode: 'buzz', url: 'https://example.test/buzz.png'),
+];
+
+/// Keycaps carry no `Extended_Pictographic` code point of their own, so they
+/// only pass via the dataset's glyph set — the one case that needs it.
+const _keycapOne = '1\u{FE0F}\u{20E3}';
+
+bool emojiOnly(
+  String content, {
+  Set<String> nativeEmoji = const {},
+  List<CustomEmoji> customEmoji = const [],
+}) => isEmojiOnlyMessage(
+  content,
+  nativeEmoji: nativeEmoji,
+  customEmoji: customEmoji,
+);
+
+void main() {
+  group('isEmojiOnlyMessage', () {
+    test('accepts emoji, alone and in runs', () {
+      // Mirrors the cases in desktop's emojiOnly.test.mjs.
+      expect(emojiOnly('\u{1F600}'), isTrue);
+      expect(
+        emojiOnly('\u{1F600} \u{1F44D}\u{1F3FD}\n\u{2764}\u{FE0F}'),
+        isTrue,
+      );
+      expect(emojiOnly('\u{1F3F3}\u{FE0F}\u{200D}\u{1F308}'), isTrue);
+      expect(
+        emojiOnly(
+          '\u{1F468}\u{200D}\u{1F469}\u{200D}\u{1F467}\u{200D}\u{1F466}',
+        ),
+        isTrue,
+      );
+    });
+
+    test('rejects anything with text in it', () {
+      expect(emojiOnly('hi \u{1F600}'), isFalse);
+      expect(emojiOnly('\u{1F600}!'), isFalse);
+      expect(emojiOnly('nice'), isFalse);
+    });
+
+    test('rejects empty and whitespace-only bodies', () {
+      expect(emojiOnly(''), isFalse);
+      expect(emojiOnly('   \n '), isFalse);
+    });
+
+    test('counts a known custom shortcode as emoji', () {
+      expect(emojiOnly(':buzz:', customEmoji: _customEmoji), isTrue);
+      expect(emojiOnly(':buzz: \u{1F600}', customEmoji: _customEmoji), isTrue);
+      expect(emojiOnly('hi :buzz:', customEmoji: _customEmoji), isFalse);
+    });
+
+    test('an unknown shortcode is just text', () {
+      // Desktop behaves the same: without the palette it renders literally, so
+      // it must not be scaled up as if it were a glyph.
+      expect(emojiOnly(':buzz:'), isFalse);
+      expect(emojiOnly(':nope:', customEmoji: _customEmoji), isFalse);
+      expect(emojiOnly(':', customEmoji: _customEmoji), isFalse);
+      expect(emojiOnly('::', customEmoji: _customEmoji), isFalse);
+    });
+
+    test('keycaps need the dataset glyph set', () {
+      expect(emojiOnly(_keycapOne), isFalse);
+      expect(emojiOnly(_keycapOne, nativeEmoji: {_keycapOne}), isTrue);
+    });
+  });
+
+  group('emoji-only sizing', () {
+    test('matches desktop’s step up from body text', () {
+      // Desktop goes text-sm (14px) to text-4xl; mobile body is the same 14px.
+      expect(kEmojiOnlyFontSize, 36.0);
+      // Desktop sizes inline custom emoji at 1.45em of the surrounding text.
+      expect(kEmojiOnlyCustomEmojiSize, closeTo(36.0 * 1.45, 0.001));
+    });
+  });
+}
diff --git a/mobile/test/shared/emoji/emoji_search_test.dart b/mobile/test/shared/emoji/emoji_search_test.dart
new file mode 100644
index 0000000000..d6de0e941d
--- /dev/null
+++ b/mobile/test/shared/emoji/emoji_search_test.dart
@@ -0,0 +1,121 @@
+import 'package:buzz/shared/emoji/emoji_data.dart';
+import 'package:buzz/shared/emoji/emoji_search.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+EmojiEntry _entry(
+  String id, {
+  String? name,
+  List<String> keywords = const [],
+  String native = '*',
+}) {
+  return EmojiEntry(
+    id: id,
+    name: name ?? id,
+    keywords: keywords,
+    native: native,
+    categoryId: 'people',
+  );
+}
+
+void main() {
+  group('collapseSeparators', () {
+    test('lowercases and drops shortcode punctuation', () {
+      expect(collapseSeparators(':Point_Up:'), 'pointup');
+      expect(collapseSeparators('white-check-mark'), 'whitecheckmark');
+      expect(collapseSeparators('  thumbs up '), 'thumbsup');
+    });
+  });
+
+  group('scoreShortcodeMatch', () {
+    test('ranks exact above prefix above substring above subsequence', () {
+      final exact = scoreShortcodeMatch('point_up', 'point_up')!;
+      final prefix = scoreShortcodeMatch('point', 'point_up')!;
+      final substring = scoreShortcodeMatch('up', 'point_up')!;
+      final subsequence = scoreShortcodeMatch('pntup', 'point_up')!;
+
+      expect(exact.tier, lessThan(prefix.tier));
+      expect(prefix.tier, lessThan(substring.tier));
+      expect(substring.tier, lessThan(subsequence.tier));
+    });
+
+    test('crosses the separator emoji-mart cannot', () {
+      expect(scoreShortcodeMatch('pointup', 'point_up'), isNotNull);
+      expect(scoreShortcodeMatch('pointup', 'point_up')!.tier, 0);
+    });
+
+    test('returns null for an empty query or no match', () {
+      expect(scoreShortcodeMatch('', 'point_up'), isNull);
+      expect(scoreShortcodeMatch('   ', 'point_up'), isNull);
+      expect(scoreShortcodeMatch('zzzz', 'point_up'), isNull);
+    });
+  });
+
+  group('searchEmoji', () {
+    final entries = [
+      _entry(
+        'point_up',
+        name: 'Index Pointing Up',
+        keywords: ['point', 'hand'],
+      ),
+      _entry('fire', name: 'Fire', keywords: ['flame', 'hot', 'lit']),
+      _entry(
+        'fire_engine',
+        name: 'Fire Engine',
+        keywords: ['fire', 'truck', 'emergency'],
+      ),
+      _entry('firecracker', name: 'Firecracker', keywords: ['dynamite']),
+      _entry('smile', name: 'Grinning Face With Smiling Eyes'),
+    ];
+
+    test('exact shortcode wins over longer prefixes', () {
+      final results = searchEmoji('fire', entries);
+      expect(results.first.id, 'fire');
+      expect(
+        results.map((entry) => entry.id),
+        containsAll(['fire', 'fire_engine', 'firecracker']),
+      );
+    });
+
+    test('shortcode prefix outranks a keyword-only hit', () {
+      final results = searchEmoji('flame', entries);
+      expect(results.single.id, 'fire');
+    });
+
+    test('separator-insensitive shortcode search still works', () {
+      expect(searchEmoji('pointup', entries).first.id, 'point_up');
+      expect(searchEmoji('fireengine', entries).first.id, 'fire_engine');
+    });
+
+    test('matches on name words when the shortcode does not contain them', () {
+      expect(searchEmoji('grinning', entries).single.id, 'smile');
+    });
+
+    test('honors the limit and returns empty for a blank query', () {
+      expect(searchEmoji('fire', entries, limit: 2), hasLength(2));
+      expect(searchEmoji('fire', entries, limit: 0), isEmpty);
+      expect(searchEmoji('', entries), isEmpty);
+    });
+  });
+
+  group('rankByShortcode', () {
+    test('ranks custom-emoji shortcodes with the desktop tiers', () {
+      final ranked = rankByShortcode('parrot', const [
+        'party_parrot',
+        'parrot',
+        'pirate_parrot',
+      ], (code) => code);
+
+      expect(ranked.first, 'parrot');
+      expect(ranked, hasLength(3));
+    });
+
+    test('prefers the shorter shortcode within a tier', () {
+      final ranked = rankByShortcode('par', const [
+        'parrotparrot',
+        'park',
+      ], (code) => code);
+
+      expect(ranked.first, 'park');
+    });
+  });
+}
diff --git a/mobile/test/shared/emoji/positive_emoji_test.dart b/mobile/test/shared/emoji/positive_emoji_test.dart
new file mode 100644
index 0000000000..0326a87a9b
--- /dev/null
+++ b/mobile/test/shared/emoji/positive_emoji_test.dart
@@ -0,0 +1,48 @@
+import 'package:buzz/shared/emoji/positive_emoji.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  group('isPositiveEmojiParticle', () {
+    test('accepts each group desktop celebrates', () {
+      expect(isPositiveEmojiParticle('\u{1F44D}'), isTrue); // 👍
+      expect(isPositiveEmojiParticle('\u{1F389}'), isTrue); // 🎉
+      expect(isPositiveEmojiParticle('\u{2764}\u{FE0F}'), isTrue); // ❤️
+      expect(isPositiveEmojiParticle('\u{1F602}'), isTrue); // 😂
+    });
+
+    test('rejects everything outside the set', () {
+      expect(isPositiveEmojiParticle('\u{1F44E}'), isFalse); // 👎
+      expect(isPositiveEmojiParticle('\u{1F622}'), isFalse); // 😢
+      expect(isPositiveEmojiParticle('\u{1F440}'), isFalse); // 👀
+      expect(isPositiveEmojiParticle(':partyparrot:'), isFalse);
+      expect(isPositiveEmojiParticle(''), isFalse);
+    });
+
+    test('ignores the presentation selector and surrounding space', () {
+      // The same emoji arrives with and without U+FE0F depending on the
+      // producer, and reactions come off the wire as well as from our picker.
+      expect(isPositiveEmojiParticle('\u{2764}'), isTrue);
+      expect(isPositiveEmojiParticle('\u{2B50}\u{FE0F}'), isTrue);
+      expect(isPositiveEmojiParticle(' \u{1F525} '), isTrue);
+    });
+
+    test('every entry in the exported list passes its own gate', () {
+      for (final emoji in positiveEmojiParticles) {
+        expect(
+          isPositiveEmojiParticle(emoji),
+          isTrue,
+          reason: 'expected $emoji to be a positive particle',
+        );
+      }
+    });
+
+    test('the three groups match desktop counts', () {
+      // Guards against a half-applied port: desktop has 23 hearts, 14 reaction
+      // emoji, and 15 faces.
+      expect(heartParticleEmojis, hasLength(23));
+      expect(positiveReactionParticleEmojis, hasLength(14));
+      expect(positiveFaceParticleEmojis, hasLength(15));
+      expect(positiveEmojiParticles, hasLength(52));
+    });
+  });
+}
diff --git a/mobile/test/shared/mentions/agent_identity_provider_test.dart b/mobile/test/shared/mentions/agent_identity_provider_test.dart
new file mode 100644
index 0000000000..0ea0afb268
--- /dev/null
+++ b/mobile/test/shared/mentions/agent_identity_provider_test.dart
@@ -0,0 +1,228 @@
+import 'dart:async';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:hooks_riverpod/hooks_riverpod.dart';
+import 'package:buzz/features/channels/agent_activity/working_bots_provider.dart';
+import 'package:buzz/features/channels/channel_management_provider.dart';
+import 'package:buzz/shared/mentions/agent_identity_provider.dart';
+import 'package:buzz/shared/relay/relay.dart';
+
+void main() {
+  test('refreshes channel bot roles from live membership updates', () async {
+    final relaySession = _MembershipRelaySessionNotifier([
+      _membershipEvent(role: 'bot'),
+      _membershipEvent(role: 'member'),
+    ]);
+    final container = ProviderContainer(
+      overrides: [relaySessionProvider.overrideWith(() => relaySession)],
+    );
+    addTearDown(container.dispose);
+    final keepAlive = container.listen(
+      channelBotPubkeysProvider(_channelId),
+      (_, _) {},
+      fireImmediately: true,
+    );
+    addTearDown(keepAlive.close);
+
+    expect(await container.read(channelBotPubkeysProvider(_channelId).future), {
+      _agentPubkey,
+    });
+    await relaySession.subscribed;
+    expect(relaySession.liveFilters.single.kinds, const [39002]);
+    expect(relaySession.liveFilters.single.tags['#h'], [_channelId]);
+
+    relaySession.emit(_membershipEvent(role: 'member'));
+    await _pumpEventQueue();
+
+    expect(
+      await container.read(channelBotPubkeysProvider(_channelId).future),
+      isEmpty,
+    );
+  });
+
+  test('refreshes channel members from live membership updates', () async {
+    final relaySession = _MembershipRelaySessionNotifier([
+      _membershipEvent(role: 'bot'),
+      _membershipEvent(role: 'member'),
+    ]);
+    final container = ProviderContainer(
+      overrides: [relaySessionProvider.overrideWith(() => relaySession)],
+    );
+    addTearDown(container.dispose);
+    final keepAlive = container.listen(
+      channelMembersProvider(_channelId),
+      (_, _) {},
+      fireImmediately: true,
+    );
+    addTearDown(keepAlive.close);
+
+    expect(
+      (await container.read(
+        channelMembersProvider(_channelId).future,
+      )).single.role,
+      'bot',
+    );
+    await relaySession.subscribed;
+
+    relaySession.emit(_membershipEvent(role: 'member'));
+    await _pumpEventQueue();
+
+    expect(
+      (await container.read(
+        channelMembersProvider(_channelId).future,
+      )).single.role,
+      'member',
+    );
+  });
+
+  test('disposes the live role subscription without consumers', () async {
+    final relaySession = _MembershipRelaySessionNotifier([
+      _membershipEvent(role: 'bot'),
+    ]);
+    final container = ProviderContainer(
+      overrides: [relaySessionProvider.overrideWith(() => relaySession)],
+    );
+    addTearDown(container.dispose);
+    final keepAlive = container.listen(
+      channelBotPubkeysProvider(_channelId),
+      (_, _) {},
+      fireImmediately: true,
+    );
+
+    await container.read(channelBotPubkeysProvider(_channelId).future);
+    await relaySession.subscribed;
+    keepAlive.close();
+    await container.pump();
+
+    expect(relaySession.unsubscribeCount, 1);
+  });
+
+  test(
+    'does not retain a live role subscription through working bots',
+    () async {
+      final relaySession = _MembershipRelaySessionNotifier([
+        _membershipEvent(role: 'bot'),
+      ]);
+      final container = ProviderContainer(
+        overrides: [relaySessionProvider.overrideWith(() => relaySession)],
+      );
+      addTearDown(container.dispose);
+      final keepAlive = container.listen(
+        workingBotPubkeysProvider(_channelId),
+        (_, _) {},
+        fireImmediately: true,
+      );
+
+      await relaySession.subscribed;
+      keepAlive.close();
+      await container.pump();
+
+      expect(relaySession.unsubscribeCount, 1);
+    },
+  );
+
+  test('blank profile labels defer to the directory label', () {
+    const pubkey = 'deadbeef0123456789';
+
+    expect(
+      mentionNamesWithDirectoryLabels(
+        mentionPubkeys: const [pubkey],
+        profileMentionNames: const {pubkey: '  '},
+        directoryDisplayNames: const {pubkey: 'Directory bot'},
+        agentMentionPubkeys: const {pubkey},
+      ),
+      const {pubkey: 'Directory bot'},
+    );
+  });
+}
+
+const _channelId = '11111111-1111-4111-8111-111111111111';
+const _agentPubkey =
+    'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa';
+
+NostrEvent _membershipEvent({required String role}) => NostrEvent(
+  id: 'membership-$role',
+  pubkey: 'owner',
+  createdAt: 1,
+  kind: 39002,
+  tags: [
+    ['d', _channelId],
+    ['h', _channelId],
+    ['p', _agentPubkey, 'wss://relay.example', role],
+  ],
+  content: '',
+  sig: 'sig',
+);
+
+Future<void> _pumpEventQueue() async {
+  await Future<void>.delayed(Duration.zero);
+  await Future<void>.delayed(Duration.zero);
+}
+
+class _MembershipRelaySessionNotifier extends RelaySessionNotifier {
+  final List<NostrEvent> _memberships;
+  final List<NostrFilter> liveFilters = [];
+  final List<_LiveSubscription> _subscriptions = [];
+  final Completer<void> _subscribed = Completer<void>();
+  var unsubscribeCount = 0;
+  var _membershipIndex = 0;
+
+  _MembershipRelaySessionNotifier(this._memberships);
+
+  Future<void> get subscribed => _subscribed.future;
+
+  @override
+  SessionState build() => const SessionState(status: SessionStatus.connected);
+
+  @override
+  Future<List<NostrEvent>> fetchHistory(
+    NostrFilter filter, {
+    Duration timeout = const Duration(seconds: 8),
+  }) async {
+    return [_memberships[_membershipIndex++]];
+  }
+
+  @override
+  Future<void Function()> subscribe(
+    NostrFilter filter,
+    void Function(NostrEvent) onEvent, {
+    void Function(String message)? onClosed,
+  }) async {
+    liveFilters.add(filter);
+    final subscription = _LiveSubscription(filter, onEvent);
+    _subscriptions.add(subscription);
+    if (!_subscribed.isCompleted) _subscribed.complete();
+    return () {
+      unsubscribeCount++;
+      _subscriptions.remove(subscription);
+    };
+  }
+
+  void emit(NostrEvent event) {
+    for (final subscription in List.of(_subscriptions)) {
+      if (_matches(subscription.filter, event)) {
+        subscription.onEvent(event);
+      }
+    }
+  }
+}
+
+class _LiveSubscription {
+  final NostrFilter filter;
+  final void Function(NostrEvent) onEvent;
+
+  const _LiveSubscription(this.filter, this.onEvent);
+}
+
+bool _matches(NostrFilter filter, NostrEvent event) {
+  if (!filter.kinds.contains(event.kind)) return false;
+  return filter.tags.entries.every((entry) {
+    final tagName = entry.key.substring(1);
+    return event.tags.any(
+      (tag) =>
+          tag.isNotEmpty &&
+          tag.first == tagName &&
+          tag.skip(1).any(entry.value.contains),
+    );
+  });
+}
diff --git a/mobile/test/shared/relay/identity_scoped_prefs_test.dart b/mobile/test/shared/relay/identity_scoped_prefs_test.dart
new file mode 100644
index 0000000000..4fce3f254b
--- /dev/null
+++ b/mobile/test/shared/relay/identity_scoped_prefs_test.dart
@@ -0,0 +1,92 @@
+import 'package:buzz/shared/relay/identity_scoped_prefs.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+void main() {
+  TestWidgetsFlutterBinding.ensureInitialized();
+
+  const canonical = 'k_v1:https://relay.example:pk';
+  const legacy = 'k_v1:wss://relay.example:pk';
+
+  Future<SharedPreferences> prefsWith(Map<String, Object> values) async {
+    SharedPreferences.setMockInitialValues(values);
+    return SharedPreferences.getInstance();
+  }
+
+  String? readString(SharedPreferences prefs) => readMigratedPref<String>(
+    prefs,
+    canonicalKey: canonical,
+    legacyKey: legacy,
+    read: prefs.getString,
+    write: prefs.setString,
+  );
+
+  test('returns the canonical value when present', () async {
+    final prefs = await prefsWith({canonical: 'new', legacy: 'old'});
+    expect(readString(prefs), 'new');
+  });
+
+  test('falls back to the legacy value and returns it immediately', () async {
+    final prefs = await prefsWith({legacy: 'carried over'});
+    expect(readString(prefs), 'carried over');
+  });
+
+  test('promotes the legacy value onto the canonical key', () async {
+    final prefs = await prefsWith({legacy: 'carried over'});
+    readString(prefs);
+    await Future<void>.delayed(Duration.zero);
+
+    expect(prefs.getString(canonical), 'carried over');
+    expect(prefs.getString(legacy), isNull, reason: 'legacy entry is cleared');
+  });
+
+  test('is idempotent across repeated reads', () async {
+    final prefs = await prefsWith({legacy: 'carried over'});
+    readString(prefs);
+    await Future<void>.delayed(Duration.zero);
+    expect(readString(prefs), 'carried over');
+    await Future<void>.delayed(Duration.zero);
+    expect(prefs.getString(canonical), 'carried over');
+  });
+
+  test('returns null when neither key holds a value', () async {
+    final prefs = await prefsWith({});
+    expect(readString(prefs), isNull);
+  });
+
+  test('does not touch storage when the keys coincide', () async {
+    // A pairing-created community already stores an HTTP origin, so canonical
+    // and legacy are the same string and there is nothing to migrate.
+    SharedPreferences.setMockInitialValues({canonical: 'only'});
+    final prefs = await SharedPreferences.getInstance();
+    final value = readMigratedPref<String>(
+      prefs,
+      canonicalKey: canonical,
+      legacyKey: canonical,
+      read: prefs.getString,
+      write: prefs.setString,
+    );
+    await Future<void>.delayed(Duration.zero);
+
+    expect(value, 'only');
+    expect(prefs.getString(canonical), 'only');
+  });
+
+  test('migrates string lists as well as strings', () async {
+    final prefs = await prefsWith({
+      legacy: <String>['alpha', 'beta'],
+    });
+    final value = readMigratedPref<List<String>>(
+      prefs,
+      canonicalKey: canonical,
+      legacyKey: legacy,
+      read: prefs.getStringList,
+      write: prefs.setStringList,
+    );
+    await Future<void>.delayed(Duration.zero);
+
+    expect(value, ['alpha', 'beta']);
+    expect(prefs.getStringList(canonical), ['alpha', 'beta']);
+    expect(prefs.getStringList(legacy), isNull);
+  });
+}
diff --git a/mobile/test/shared/relay/relay_closed_policy_test.dart b/mobile/test/shared/relay/relay_closed_policy_test.dart
new file mode 100644
index 0000000000..ff78ea89ef
--- /dev/null
+++ b/mobile/test/shared/relay/relay_closed_policy_test.dart
@@ -0,0 +1,45 @@
+import 'package:buzz/shared/relay/relay.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  group('classifyRelayClosed', () {
+    const cases = {
+      'rate-limited: quota exceeded; retry in 4s': RelayClosedClass.rateLimited,
+      'rate-limited: too many concurrent requests':
+          RelayClosedClass.rateLimited,
+      'restricted: access revoked': RelayClosedClass.terminal,
+      'auth-required: verification failed': RelayClosedClass.terminal,
+      'blocked: community policy': RelayClosedClass.terminal,
+      'invalid: malformed filter': RelayClosedClass.terminal,
+      'pow: insufficient work': RelayClosedClass.terminal,
+      'duplicate: subscription already exists': RelayClosedClass.terminal,
+      'unsupported: filter extension': RelayClosedClass.terminal,
+      'error: mixed search and channel filter': RelayClosedClass.terminal,
+      'error: too many subscriptions': RelayClosedClass.terminal,
+      'error: relay temporarily unavailable': RelayClosedClass.retryable,
+      'subscription closed by relay': RelayClosedClass.retryable,
+    };
+
+    for (final entry in cases.entries) {
+      test(entry.key, () {
+        expect(classifyRelayClosed(entry.key), entry.value);
+      });
+    }
+  });
+
+  test('parseRateLimitRetrySeconds handles canonical and absent hints', () {
+    expect(
+      parseRateLimitRetrySeconds('rate-limited: quota exceeded; retry in 17s'),
+      17,
+    );
+    expect(parseRateLimitRetrySeconds('RETRY IN 2S'), 2);
+    expect(parseRateLimitRetrySeconds('retry in 0s'), 0);
+    expect(parseRateLimitRetrySeconds('retry in 999999s'), 999999);
+    final oversizedHint = List.filled(1000, '9').join();
+    expect(parseRateLimitRetrySeconds('retry in ${oversizedHint}s'), isNull);
+    expect(
+      parseRateLimitRetrySeconds('rate-limited: too many concurrent requests'),
+      isNull,
+    );
+  });
+}
diff --git a/mobile/test/shared/relay/relay_config_test.dart b/mobile/test/shared/relay/relay_config_test.dart
new file mode 100644
index 0000000000..d0decb3685
--- /dev/null
+++ b/mobile/test/shared/relay/relay_config_test.dart
@@ -0,0 +1,67 @@
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:buzz/shared/relay/relay_provider.dart';
+
+void main() {
+  group('RelayConfig.baseUrl normalization', () {
+    test('folds a wss:// community URL to https://', () {
+      // Invite joins persist the relay URL straight off the invite link, which
+      // deep_link.dart always emits as ws:// or wss://.
+      final config = RelayConfig(baseUrl: 'wss://relay.example.com');
+      expect(config.baseUrl, 'https://relay.example.com');
+    });
+
+    test('folds a ws:// community URL to http://', () {
+      final config = RelayConfig(baseUrl: 'ws://relay.example.com:3000');
+      expect(config.baseUrl, 'http://relay.example.com:3000');
+    });
+
+    test('leaves an https:// community URL untouched', () {
+      // Device pairing rejects anything but https://, so these already conform.
+      final config = RelayConfig(baseUrl: 'https://relay.example.com');
+      expect(config.baseUrl, 'https://relay.example.com');
+    });
+
+    test('leaves an http:// community URL untouched', () {
+      final config = RelayConfig(baseUrl: 'http://localhost:3000');
+      expect(config.baseUrl, 'http://localhost:3000');
+    });
+
+    test('preserves a non-default port', () {
+      final config = RelayConfig(baseUrl: 'wss://relay.example.com:8443');
+      expect(config.baseUrl, 'https://relay.example.com:8443');
+    });
+  });
+
+  group('RelayConfig.wsUrl', () {
+    test('keeps TLS for a relay joined by invite', () {
+      // Regression: a wss:// base used to fall through to the non-https branch
+      // and downgrade to ws://, dialing port 80 — which never connects on a
+      // relay that only serves 443, and drops TLS everywhere else.
+      final config = RelayConfig(baseUrl: 'wss://relay.example.com');
+      expect(config.wsUrl, 'wss://relay.example.com');
+    });
+
+    test('keeps TLS for a relay added by pairing', () {
+      final config = RelayConfig(baseUrl: 'https://relay.example.com');
+      expect(config.wsUrl, 'wss://relay.example.com');
+    });
+
+    test('both onboarding paths agree on the same relay', () {
+      final invited = RelayConfig(baseUrl: 'wss://relay.example.com');
+      final paired = RelayConfig(baseUrl: 'https://relay.example.com');
+      expect(invited.wsUrl, paired.wsUrl);
+      expect(invited.baseUrl, paired.baseUrl);
+    });
+
+    test('stays plaintext for local development', () {
+      final config = RelayConfig(baseUrl: 'http://localhost:3000');
+      expect(config.wsUrl, 'ws://localhost:3000');
+    });
+
+    test('preserves a non-default port', () {
+      final config = RelayConfig(baseUrl: 'wss://relay.example.com:8443');
+      expect(config.wsUrl, 'wss://relay.example.com:8443');
+    });
+  });
+}
diff --git a/mobile/test/shared/relay/relay_rate_limit_gate_test.dart b/mobile/test/shared/relay/relay_rate_limit_gate_test.dart
new file mode 100644
index 0000000000..811d439572
--- /dev/null
+++ b/mobile/test/shared/relay/relay_rate_limit_gate_test.dart
@@ -0,0 +1,118 @@
+import 'dart:async';
+
+import 'package:buzz/shared/relay/relay.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  test('uses the default for absent and non-positive hints', () {
+    var now = DateTime.utc(2026);
+    final timers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => now,
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+
+    gate.activate(null);
+    expect(gate.remainingMs(), 10000);
+    expect(timers.single.duration, const Duration(seconds: 10));
+
+    now = now.add(const Duration(seconds: 11));
+    gate.activate(0);
+    expect(timers.last.duration, const Duration(seconds: 10));
+  });
+
+  test('clamps large hints to five minutes', () {
+    final timers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime.utc(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+
+    gate.activate(999999);
+
+    expect(timers.single.duration, const Duration(seconds: 300));
+    expect(gate.remainingMs(), 300000);
+  });
+
+  test('overlapping activations only extend the active window', () async {
+    var now = DateTime.utc(2026);
+    final timers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => now,
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+
+    gate.activate(30);
+    final wait = gate.wait();
+    final firstTimer = timers.single;
+
+    now = now.add(const Duration(seconds: 5));
+    gate.activate(10);
+    expect(timers, hasLength(1));
+    expect(gate.remainingMs(), 25000);
+
+    gate.activate(40);
+    expect(timers, hasLength(2));
+    expect(firstTimer.isActive, isFalse);
+    expect(gate.remainingMs(), 40000);
+
+    timers.last.fire();
+    await wait;
+    expect(gate.isActive, isFalse);
+    expect(gate.remainingMs(), 0);
+  });
+
+  test('reset releases waiters and cancels the active timer', () async {
+    final timers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+
+    gate.activate(20);
+    final wait = gate.wait();
+    gate.reset();
+
+    await wait;
+    expect(timers.single.isActive, isFalse);
+    expect(gate.isActive, isFalse);
+  });
+}
+
+class _ManualTimer implements Timer {
+  _ManualTimer(this.duration, this._callback);
+
+  final Duration duration;
+  final void Function() _callback;
+  bool _active = true;
+
+  void fire() {
+    if (!_active) return;
+    _active = false;
+    _callback();
+  }
+
+  @override
+  void cancel() => _active = false;
+
+  @override
+  bool get isActive => _active;
+
+  @override
+  int get tick => _active ? 0 : 1;
+}
diff --git a/mobile/test/shared/relay/relay_session_test.dart b/mobile/test/shared/relay/relay_session_test.dart
index 6cd601f56b..b97df0849d 100644
--- a/mobile/test/shared/relay/relay_session_test.dart
+++ b/mobile/test/shared/relay/relay_session_test.dart
@@ -105,6 +105,178 @@ void main() {
     );
   });
 
+  test('queryRelay arms the rate-limit gate from a 429 retry hint', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    const body = '{"error":"rate-limited: quota exceeded; retry in 4s"}';
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async => http.Response(body, 429)),
+    );
+    addTearDown(harness.container.dispose);
+
+    await expectLater(
+      harness.session.queryRelay(const []),
+      throwsA(
+        isA<RelayException>()
+            .having((error) => error.statusCode, 'statusCode', 429)
+            .having((error) => error.body, 'body', body),
+      ),
+    );
+
+    expect(gateTimers.single.duration, const Duration(seconds: 4));
+    expect(gate.isActive, isTrue);
+  });
+
+  test('queryRelay uses the default gate for a 503 without a hint', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    const body = '{"error":"rate-limited: shared admission unavailable"}';
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async => http.Response(body, 503)),
+    );
+    addTearDown(harness.container.dispose);
+
+    await expectLater(
+      harness.session.queryRelay(const []),
+      throwsA(
+        isA<RelayException>()
+            .having((error) => error.statusCode, 'statusCode', 503)
+            .having((error) => error.body, 'body', body),
+      ),
+    );
+
+    expect(gateTimers.single.duration, const Duration(seconds: 10));
+    expect(gate.isActive, isTrue);
+  });
+
+  test('queryRelay does not arm the gate for a non-rate-limit error', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    const body = '{"error":"not found"}';
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async => http.Response(body, 404)),
+    );
+    addTearDown(harness.container.dispose);
+
+    await expectLater(
+      harness.session.queryRelay(const []),
+      throwsA(
+        isA<RelayException>()
+            .having((error) => error.statusCode, 'statusCode', 404)
+            .having((error) => error.body, 'body', body),
+      ),
+    );
+
+    expect(gateTimers, isEmpty);
+    expect(gate.isActive, isFalse);
+  });
+
+  test('queryRelay preserves an error with an unrecognized body', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    const body = 'upstream unavailable';
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async => http.Response(body, 503)),
+    );
+    addTearDown(harness.container.dispose);
+
+    await expectLater(
+      harness.session.queryRelay(const []),
+      throwsA(
+        isA<RelayException>()
+            .having((error) => error.statusCode, 'statusCode', 503)
+            .having((error) => error.body, 'body', body),
+      ),
+    );
+
+    expect(gateTimers, isEmpty);
+    expect(gate.isActive, isFalse);
+  });
+
+  test('queryRelay success does not arm the rate-limit gate', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async => http.Response('[]', 200)),
+    );
+    addTearDown(harness.container.dispose);
+
+    expect(await harness.session.queryRelay(const []), isEmpty);
+    expect(gateTimers, isEmpty);
+    expect(gate.isActive, isFalse);
+  });
+
+  test('queryRelay does not wait for an active rate-limit gate', () async {
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: _ManualTimer.new,
+    );
+    var requestCount = 0;
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async {
+        requestCount++;
+        return http.Response('[]', 200);
+      }),
+    );
+    addTearDown(harness.container.dispose);
+    // Let the provider's build/dispose churn settle before arming: reading the
+    // notifier registers `ref.onDispose(_dispose)`, and `_dispose` resets the
+    // shared gate. Arming before that settles leaves the gate disarmed by the
+    // time the request runs, which makes this row pass for the wrong reason.
+    await pumpEventQueue();
+    gate.activate(4);
+    expect(gate.isActive, isTrue);
+
+    final query = harness.session.queryRelay(const []);
+    await Future<void>.delayed(Duration.zero);
+
+    expect(requestCount, 1);
+    expect(await query, isEmpty);
+    // Still armed: the read must neither wait on the gate nor clear it.
+    expect(gate.isActive, isTrue);
+  });
+
   test(
     'history timeout rejects instead of returning partial empty data',
     () async {
@@ -298,7 +470,37 @@ void main() {
     unsubscribeSecond();
   });
 
-  test('live subscribe fails when relay closes before ready', () async {
+  test('flushes replay events before a post-EOSE query can begin', () async {
+    final session = RelaySessionNotifier();
+    final deliveryPhases = <bool>[];
+    var queryHasBegun = false;
+    const filter = NostrFilter(
+      kinds: EventKind.channelEventKinds,
+      tags: {
+        '#h': [_channelId],
+      },
+      limit: 50,
+    );
+
+    final subscribe = session.subscribe(
+      filter,
+      (_) => deliveryPhases.add(queryHasBegun),
+    );
+    final replayEvent = _event();
+    session.debugHandleMessage(['EVENT', 'l-1', replayEvent.toJson()]);
+    session.debugHandleMessage(['EOSE', 'l-1']);
+
+    final unsubscribe = await subscribe;
+    queryHasBegun = true;
+    // The original batch timer must not deliver the replay event after the
+    // caller has advanced to its query phase.
+    session.debugFlushEventBuffer();
+
+    expect(deliveryPhases, [false]);
+    unsubscribe();
+  });
+
+  test('terminal CLOSED fails a live subscribe before ready', () async {
     final session = RelaySessionNotifier();
     const filter = NostrFilter(kinds: [EventKind.agentObserverFrame], limit: 0);
 
@@ -322,32 +524,601 @@ void main() {
   });
 
   test(
-    'live onClosed callback runs when relay closes an open subscription',
+    'retryable CLOSED before EOSE retains and retries the live sub',
     () async {
-      final session = RelaySessionNotifier();
-      final closedMessages = <String>[];
-      const filter = NostrFilter(
-        kinds: [EventKind.agentObserverFrame],
-        limit: 0,
+      final timers = <_ManualTimer>[];
+      final socket = _RecordingRelaySocket();
+      final session = RelaySessionNotifier(
+        retryTimerFactory: (duration, callback) {
+          final timer = _ManualTimer(duration, callback);
+          timers.add(timer);
+          return timer;
+        },
       );
+      session.debugAttachSocketForTest(socket);
 
-      final subscribe = session.subscribe(
-        filter,
-        (_) {},
-        onClosed: closedMessages.add,
+      final subscribe = session.subscribe(_channelFilter, (_) {});
+      session.debugHandleMessage(['CLOSED', 'l-1', 'error: relay overloaded']);
+      final unsubscribe = await subscribe;
+
+      expect(timers.single.duration, const Duration(seconds: 1));
+      timers.single.fire();
+      await Future<void>.delayed(Duration.zero);
+
+      expect(_reqs(socket).where((req) => req[1] == 'l-1'), hasLength(2));
+      unsubscribe();
+    },
+  );
+
+  test('CLOSED retries back off and reset after EOSE', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 1));
+    timers.last.fire();
+    await Future<void>.delayed(Duration.zero);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 2));
+
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 1));
+    unsubscribe();
+  });
+
+  test('CLOSED retry backoff saturates before a high-attempt shift', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+
+    for (var attempt = 0; attempt < 100; attempt++) {
+      session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+      expect(
+        timers.last.duration,
+        attempt >= 5
+            ? const Duration(seconds: 30)
+            : Duration(seconds: 1 << attempt),
+      );
+      timers.last.fire();
+      await Future<void>.delayed(Duration.zero);
+    }
+
+    unsubscribe();
+  });
+
+  test('CLOSED retries reset after a delivered event', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    timers.last.fire();
+    await Future<void>.delayed(Duration.zero);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 2));
+
+    session.debugHandleMessage([
+      'EVENT',
+      'l-1',
+      _event(createdAt: 30).toJson(),
+    ]);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 1));
+    unsubscribe();
+  });
+
+  test('CLOSED retries reset after disconnect and reconnect', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    timers.last.fire();
+    await Future<void>.delayed(Duration.zero);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 2));
+
+    session.debugResetClosedRetriesForDisconnect();
+    expect(timers.last.isActive, isFalse);
+    session.debugSetSessionStatus(SessionStatus.connected);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 1));
+    unsubscribe();
+  });
+
+  test('a CLOSED retry timer does not send while disconnected', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+    final requestCount = _reqs(socket).length;
+
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    session.debugSetSessionStatus(SessionStatus.reconnecting);
+    timers.single.fire();
+    await Future<void>.delayed(Duration.zero);
+
+    expect(_reqs(socket), hasLength(requestCount));
+    unsubscribe();
+  });
+
+  test('terminal CLOSED removes a live sub without retrying it', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    await subscribe;
+
+    session.debugHandleMessage(['CLOSED', 'l-1', 'restricted: access revoked']);
+    await session.debugReplayLiveSubscriptions();
+
+    expect(timers, isEmpty);
+    expect(_reqs(socket).where((req) => req[1] == 'l-1'), hasLength(1));
+  });
+
+  test('unsubscribe and dispose cancel CLOSED retry timers', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+
+    final firstSubscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await firstSubscribe;
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    final unsubscribeTimer = timers.last;
+    unsubscribe();
+    expect(unsubscribeTimer.isActive, isFalse);
+
+    final secondSubscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-2']);
+    await secondSubscribe;
+    session.debugHandleMessage(['CLOSED', 'l-2', 'error: transient']);
+    final disposeTimer = timers.last;
+    session.debugDispose();
+    expect(disposeTimer.isActive, isFalse);
+  });
+
+  test('rate-limited live CLOSED honours the gate floor', () async {
+    final retryTimers = <_ManualTimer>[];
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    final session = RelaySessionNotifier(
+      rateLimitGate: gate,
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        retryTimers.add(timer);
+        return timer;
+      },
+    );
+    final socket = _RecordingRelaySocket();
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+
+    session.debugHandleMessage([
+      'CLOSED',
+      'l-1',
+      'rate-limited: quota exceeded; retry in 4s',
+    ]);
+
+    expect(
+      retryTimers.single.duration.inMilliseconds,
+      inInclusiveRange(3990, 4000),
+    );
+    expect(gateTimers.single.duration, const Duration(seconds: 4));
+    unsubscribe();
+  });
+
+  test(
+    'rate-limited CLOSED retry does not survive a superseded connection',
+    () async {
+      final retryTimers = <_ManualTimer>[];
+      final gateTimers = <_ManualTimer>[];
+      final gate = RelayRateLimitGate(
+        now: () => DateTime(2026),
+        timerFactory: (duration, callback) {
+          final timer = _ManualTimer(duration, callback);
+          gateTimers.add(timer);
+          return timer;
+        },
+      );
+      final socket = _RecordingRelaySocket();
+      final session = RelaySessionNotifier(
+        rateLimitGate: gate,
+        retryTimerFactory: (duration, callback) {
+          final timer = _ManualTimer(duration, callback);
+          retryTimers.add(timer);
+          return timer;
+        },
       );
+      session.debugAttachSocketForTest(socket);
+      final subscribe = session.subscribe(_channelFilter, (_) {});
       session.debugHandleMessage(['EOSE', 'l-1']);
       final unsubscribe = await subscribe;
+      socket.messages.clear();
+
       session.debugHandleMessage([
         'CLOSED',
         'l-1',
-        'restricted: no longer valid',
+        'rate-limited: quota exceeded; retry in 4s',
       ]);
+      retryTimers.single.fire();
+      await Future<void>.delayed(Duration.zero);
+      expect(_reqs(socket), isEmpty);
+
+      session.debugSupersedeConnection();
+      final replacementReplay = session.debugReplayLiveSubscriptions();
+      await Future<void>.delayed(Duration.zero);
+      gateTimers.single.fire();
+      await replacementReplay;
+      await Future<void>.delayed(Duration.zero);
 
-      expect(closedMessages, ['restricted: no longer valid']);
+      expect(_reqs(socket).where((req) => req[1] == 'l-1'), hasLength(1));
       unsubscribe();
     },
   );
+
+  test('simultaneous rate-limited CLOSED retries are replay-paced', () async {
+    final retryTimers = <_ManualTimer>[];
+    final gateTimers = <_ManualTimer>[];
+    final replayDelays = <Duration>[];
+    final replayDelayCompleters = <Completer<void>>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      rateLimitGate: gate,
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        retryTimers.add(timer);
+        return timer;
+      },
+      replayDelay: (duration) {
+        replayDelays.add(duration);
+        final completer = Completer<void>();
+        replayDelayCompleters.add(completer);
+        return completer.future;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+
+    for (var i = 0; i < 30; i++) {
+      final subscribe = session.subscribe(
+        _filterForChannel('channel-$i'),
+        (_) {},
+      );
+      session.debugHandleMessage(['EOSE', 'l-${i + 1}']);
+      await subscribe;
+    }
+    socket.messages.clear();
+
+    for (var i = 0; i < 30; i++) {
+      session.debugHandleMessage([
+        'CLOSED',
+        'l-${i + 1}',
+        'rate-limited: quota exceeded; retry in 4s',
+      ]);
+    }
+    for (final timer in retryTimers) {
+      timer.fire();
+    }
+    await Future<void>.delayed(Duration.zero);
+    expect(_reqs(socket), isEmpty);
+
+    gateTimers.single.fire();
+    await Future<void>.delayed(Duration.zero);
+    expect(_reqs(socket), hasLength(8));
+    expect(replayDelays, [const Duration(milliseconds: 50)]);
+
+    for (final expectedCount in [16, 24, 30]) {
+      replayDelayCompleters.last.complete();
+      await Future<void>.delayed(Duration.zero);
+      expect(_reqs(socket), hasLength(expectedCount));
+    }
+    expect(replayDelays, [
+      const Duration(milliseconds: 50),
+      const Duration(milliseconds: 50),
+      const Duration(milliseconds: 50),
+    ]);
+    session.debugDispose();
+  });
+
+  test('active rate-limit gate does not delay a new live subscribe', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(rateLimitGate: gate);
+    session.debugAttachSocketForTest(socket);
+    gate.activate(4);
+
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+
+    expect(_reqs(socket), hasLength(1));
+    expect(gateTimers.single.duration, const Duration(seconds: 4));
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+    unsubscribe();
+    session.debugDispose();
+  });
+
+  test('rate-limited history CLOSED gates the next REQ', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(rateLimitGate: gate);
+    session.debugAttachSocketForTest(socket);
+
+    final first = session.fetchHistory(_channelFilter);
+    session.debugHandleMessage([
+      'CLOSED',
+      'h-1',
+      'rate-limited: quota exceeded; retry in 4s',
+    ]);
+    await expectLater(first, throwsException);
+
+    final second = session.fetchHistory(_channelFilter);
+    await Future<void>.delayed(Duration.zero);
+    expect(_reqs(socket), hasLength(1));
+    expect(gateTimers.single.duration, const Duration(seconds: 4));
+
+    gateTimers.single.fire();
+    await Future<void>.delayed(Duration.zero);
+    expect(_reqs(socket), hasLength(2));
+    session.debugHandleMessage(['EOSE', 'h-2']);
+    await second;
+  });
+
+  test(
+    'visible channel owners restore and ignore out-of-order release',
+    () async {
+      final socket = _RecordingRelaySocket();
+      final session = RelaySessionNotifier();
+      session.debugAttachSocketForTest(socket);
+      const channelIds = ['channel-a', 'channel-b', 'channel-c'];
+
+      for (var i = 0; i < channelIds.length; i++) {
+        final subscribe = session.subscribe(
+          _filterForChannel(channelIds[i]),
+          (_) {},
+        );
+        session.debugHandleMessage(['EOSE', 'l-${i + 1}']);
+        await subscribe;
+      }
+
+      final releaseA = session.registerVisibleChannel('channel-a');
+      final releaseB = session.registerVisibleChannel('channel-b');
+      final releaseC = session.registerVisibleChannel('channel-c');
+      releaseB();
+      socket.messages.clear();
+      await session.debugReplayLiveSubscriptions();
+      expect(_replayedChannelIds(socket).first, 'channel-c');
+
+      releaseC();
+      socket.messages.clear();
+      await session.debugReplayLiveSubscriptions();
+      expect(_replayedChannelIds(socket).first, 'channel-a');
+
+      releaseB();
+      releaseA();
+    },
+  );
+
+  test('replay is visible-first and batched eight at a time', () async {
+    final replayDelays = <Duration>[];
+    final replayDelayCompleter = Completer<void>();
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      replayDelay: (duration) {
+        replayDelays.add(duration);
+        return replayDelayCompleter.future;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+
+    for (var i = 0; i < 9; i++) {
+      final channelId = i == 8 ? _visibleChannelId : 'channel-$i';
+      final subscribe = session.subscribe(_filterForChannel(channelId), (_) {});
+      session.debugHandleMessage(['EOSE', 'l-${i + 1}']);
+      await subscribe;
+    }
+    socket.messages.clear();
+    final releaseVisibleChannel = session.registerVisibleChannel(
+      _visibleChannelId,
+    );
+
+    final replay = session.debugReplayLiveSubscriptions();
+    await Future<void>.delayed(Duration.zero);
+
+    final firstBatch = _reqs(socket);
+    expect(firstBatch, hasLength(8));
+    expect((firstBatch.first[2] as Map<String, dynamic>)['#h'], [
+      _visibleChannelId,
+    ]);
+    expect(replayDelays, [const Duration(milliseconds: 50)]);
+
+    replayDelayCompleter.complete();
+    await replay;
+    expect(_reqs(socket), hasLength(9));
+    releaseVisibleChannel();
+  });
+
+  test(
+    'replay generation guard bails after a connection is superseded',
+    () async {
+      final replayDelayCompleter = Completer<void>();
+      final socket = _RecordingRelaySocket();
+      final session = RelaySessionNotifier(
+        replayDelay: (_) => replayDelayCompleter.future,
+      );
+      session.debugAttachSocketForTest(socket);
+
+      for (var i = 0; i < 9; i++) {
+        final subscribe = session.subscribe(
+          _filterForChannel('channel-$i'),
+          (_) {},
+        );
+        session.debugHandleMessage(['EOSE', 'l-${i + 1}']);
+        await subscribe;
+      }
+      socket.messages.clear();
+
+      final replay = session.debugReplayLiveSubscriptions();
+      await Future<void>.delayed(Duration.zero);
+      expect(_reqs(socket), hasLength(8));
+
+      session.debugSupersedeConnection();
+      replayDelayCompleter.complete();
+      await replay;
+
+      expect(_reqs(socket), hasLength(8));
+    },
+  );
+
+  test('live onClosed callback runs only for a terminal CLOSED', () async {
+    final session = RelaySessionNotifier();
+    final closedMessages = <String>[];
+    const filter = NostrFilter(kinds: [EventKind.agentObserverFrame], limit: 0);
+
+    final subscribe = session.subscribe(
+      filter,
+      (_) {},
+      onClosed: closedMessages.add,
+    );
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+    session.debugHandleMessage([
+      'CLOSED',
+      'l-1',
+      'error: temporarily unavailable',
+    ]);
+    expect(closedMessages, isEmpty);
+    session.debugHandleMessage([
+      'CLOSED',
+      'l-1',
+      'restricted: no longer valid',
+    ]);
+
+    expect(closedMessages, ['restricted: no longer valid']);
+    unsubscribe();
+  });
+}
+
+class _QueryHarness {
+  final ProviderContainer container;
+  final RelaySessionNotifier session;
+
+  _QueryHarness({required this.container, required this.session});
+}
+
+_QueryHarness _queryHarness({
+  required RelayRateLimitGate gate,
+  required http.Client client,
+}) {
+  final session = RelaySessionNotifier(httpClient: client, rateLimitGate: gate);
+  final container = ProviderContainer(
+    overrides: [
+      relaySessionProvider.overrideWith(() => session),
+      relayConfigProvider.overrideWith(
+        () => _FakeRelayConfigNotifier(
+          baseUrl: 'https://relay.example',
+          nsec: nostr.Keys.generate().nsec,
+        ),
+      ),
+    ],
+  );
+  container.read(relaySessionProvider);
+  return _QueryHarness(container: container, session: session);
 }
 
 class _FakeAuthNotifier extends AuthNotifier {
@@ -407,11 +1178,11 @@ class _FakeRelayConfigNotifier extends RelayConfigNotifier {
   RelayConfig build() => RelayConfig(baseUrl: _baseUrl, nsec: _nsec);
 }
 
-NostrEvent _event() {
-  return const NostrEvent(
+NostrEvent _event({int createdAt = 20}) {
+  return NostrEvent(
     id: 'event-1',
     pubkey: 'alice',
-    createdAt: 20,
+    createdAt: createdAt,
     kind: EventKind.streamMessageV2,
     tags: [
       ['h', _channelId],
@@ -420,3 +1191,72 @@ NostrEvent _event() {
     sig: 'sig',
   );
 }
+
+const _visibleChannelId = '99999999-9999-4999-8999-999999999999';
+const _channelFilter = NostrFilter(
+  kinds: EventKind.channelEventKinds,
+  tags: {
+    '#h': [_channelId],
+  },
+  limit: 0,
+);
+
+NostrFilter _filterForChannel(String channelId) => NostrFilter(
+  kinds: EventKind.channelEventKinds,
+  tags: {
+    '#h': [channelId],
+  },
+  limit: 0,
+);
+
+List<String> _replayedChannelIds(_RecordingRelaySocket socket) => _reqs(socket)
+    .map(
+      (message) =>
+          ((message[2] as Map<String, dynamic>)['#h'] as List).single as String,
+    )
+    .toList();
+
+List<List<dynamic>> _reqs(_RecordingRelaySocket socket) =>
+    socket.messages.where((message) => message.first == 'REQ').toList();
+
+class _RecordingRelaySocket extends RelaySocket {
+  _RecordingRelaySocket()
+    : super(
+        wsUrl: 'wss://relay.example',
+        nsec: null,
+        onMessage: (_) {},
+        onConnected: () {},
+        onDisconnected: (_) {},
+      );
+
+  final List<List<dynamic>> messages = [];
+
+  @override
+  void send(List<dynamic> payload) => messages.add(payload);
+
+  @override
+  void dispose() {}
+}
+
+class _ManualTimer implements Timer {
+  _ManualTimer(this.duration, this._callback);
+
+  final Duration duration;
+  final void Function() _callback;
+  bool _active = true;
+
+  void fire() {
+    if (!_active) return;
+    _active = false;
+    _callback();
+  }
+
+  @override
+  void cancel() => _active = false;
+
+  @override
+  bool get isActive => _active;
+
+  @override
+  int get tick => _active ? 0 : 1;
+}
diff --git a/mobile/test/shared/widgets/keyboard_dismiss_on_drag_test.dart b/mobile/test/shared/widgets/keyboard_dismiss_on_drag_test.dart
new file mode 100644
index 0000000000..ae03f55c16
--- /dev/null
+++ b/mobile/test/shared/widgets/keyboard_dismiss_on_drag_test.dart
@@ -0,0 +1,138 @@
+import 'package:buzz/shared/widgets/keyboard_dismiss_on_drag.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+/// A focused field inside a `Scaffold` body, which is the only arrangement
+/// either message list ever runs in.
+Widget _testable({required FocusNode focusNode}) {
+  return MaterialApp(
+    home: Scaffold(
+      body: Column(
+        children: [
+          TextField(focusNode: focusNode),
+          Expanded(
+            child: KeyboardDismissOnDrag(
+              child: ListView(
+                children: [
+                  for (var i = 0; i < 40; i++)
+                    SizedBox(height: 60, child: Text('row $i')),
+                ],
+              ),
+            ),
+          ),
+        ],
+      ),
+    ),
+  );
+}
+
+/// Raise the keyboard the way the platform does — on the view, not via a
+/// synthetic `MediaQuery` wrapper. It has to travel the real path, because
+/// `Scaffold` strips the bottom view inset from its body once it has resized to
+/// account for it, and that stripping is the whole reason this widget broke.
+void _raiseKeyboard(WidgetTester tester) {
+  tester.view.viewInsets = const FakeViewPadding(bottom: 300);
+  addTearDown(tester.view.reset);
+}
+
+Future<void> _dragDown(
+  WidgetTester tester,
+  double distance, {
+  String on = 'row 3',
+}) async {
+  final gesture = await tester.startGesture(tester.getCenter(find.text(on)));
+  // Several small moves, the way a real finger reports — the accumulator has to
+  // add them up rather than needing one big delta.
+  final step = distance / 6;
+  for (var i = 0; i < 6; i++) {
+    await gesture.moveBy(Offset(0, step));
+    await tester.pump();
+  }
+  await gesture.up();
+  await tester.pump();
+}
+
+void main() {
+  group('KeyboardDismissOnDrag', () {
+    testWidgets('a deliberate downward drag drops focus', (tester) async {
+      final focusNode = FocusNode();
+      addTearDown(focusNode.dispose);
+      _raiseKeyboard(tester);
+      await tester.pumpWidget(_testable(focusNode: focusNode));
+      focusNode.requestFocus();
+      await tester.pump();
+      expect(focusNode.hasFocus, isTrue);
+
+      await _dragDown(tester, keyboardDismissDragThreshold * 2);
+
+      // At rest the list can't scroll down, so this gesture is pure overscroll
+      // — the case that reports `OverscrollNotification` rather than
+      // `ScrollUpdateNotification`, and the one a focused composer is usually
+      // sitting in.
+      expect(focusNode.hasFocus, isFalse);
+    });
+
+    testWidgets('an ordinary downward scroll dismisses too', (tester) async {
+      final focusNode = FocusNode();
+      addTearDown(focusNode.dispose);
+      _raiseKeyboard(tester);
+      await tester.pumpWidget(_testable(focusNode: focusNode));
+      focusNode.requestFocus();
+      await tester.pump();
+
+      // Move off the resting edge so dragging down actually moves the position,
+      // covering the `ScrollUpdateNotification` path rather than overscroll.
+      await tester.drag(find.text('row 3'), const Offset(0, -400));
+      await tester.pumpAndSettle();
+      expect(focusNode.hasFocus, isTrue);
+
+      await _dragDown(tester, keyboardDismissDragThreshold * 2, on: 'row 10');
+
+      expect(focusNode.hasFocus, isFalse);
+    });
+
+    testWidgets('a short scroll leaves the keyboard alone', (tester) async {
+      final focusNode = FocusNode();
+      addTearDown(focusNode.dispose);
+      _raiseKeyboard(tester);
+      await tester.pumpWidget(_testable(focusNode: focusNode));
+      focusNode.requestFocus();
+      await tester.pump();
+
+      await _dragDown(tester, keyboardDismissDragThreshold / 2);
+
+      expect(focusNode.hasFocus, isTrue);
+    });
+
+    testWidgets('an upward drag never dismisses, however far it goes', (
+      tester,
+    ) async {
+      final focusNode = FocusNode();
+      addTearDown(focusNode.dispose);
+      _raiseKeyboard(tester);
+      await tester.pumpWidget(_testable(focusNode: focusNode));
+      focusNode.requestFocus();
+      await tester.pump();
+
+      await _dragDown(tester, -keyboardDismissDragThreshold * 4);
+
+      expect(focusNode.hasFocus, isTrue);
+    });
+
+    testWidgets('with the keyboard already down, focus is left as it is', (
+      tester,
+    ) async {
+      final focusNode = FocusNode();
+      addTearDown(focusNode.dispose);
+      // No _raiseKeyboard: the keyboard is down.
+      await tester.pumpWidget(_testable(focusNode: focusNode));
+      focusNode.requestFocus();
+      await tester.pump();
+
+      await _dragDown(tester, keyboardDismissDragThreshold * 2);
+
+      // Nothing to dismiss, so don't yank focus out of whatever holds it.
+      expect(focusNode.hasFocus, isTrue);
+    });
+  });
+}
diff --git a/mobile/test/shared/widgets/message_author_meta_test.dart b/mobile/test/shared/widgets/message_author_meta_test.dart
index a97af86130..3b55946d47 100644
--- a/mobile/test/shared/widgets/message_author_meta_test.dart
+++ b/mobile/test/shared/widgets/message_author_meta_test.dart
@@ -4,6 +4,41 @@ import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
 
 void main() {
+  testWidgets('keeps the separator and timestamp next to a short name', (
+    tester,
+  ) async {
+    const displayNameKey = Key('author-display-name');
+    const timestampKey = Key('author-timestamp');
+
+    await tester.pumpWidget(
+      MaterialApp(
+        theme: AppTheme.light(),
+        home: const Scaffold(
+          body: SizedBox(
+            width: 300,
+            child: MessageAuthorMeta(
+              displayName: 'Alice',
+              timestamp: '2m',
+              displayNameKey: displayNameKey,
+              timestampKey: timestampKey,
+              nameColor: Colors.black,
+              metadataColor: Colors.grey,
+            ),
+          ),
+        ),
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    final displayNameRect = tester.getRect(find.byKey(displayNameKey));
+    final separatorRect = tester.getRect(find.text('·'));
+    final timestampRect = tester.getRect(find.byKey(timestampKey));
+
+    expect(separatorRect.left - displayNameRect.right, Grid.half);
+    expect(timestampRect.left - separatorRect.right, Grid.half);
+    expect(tester.takeException(), isNull);
+  });
+
   testWidgets('reallocates unused metadata width to the display name', (
     tester,
   ) async {
diff --git a/mobile/test/shared/widgets/mobile_tab_footer_backdrop_test.dart b/mobile/test/shared/widgets/mobile_tab_footer_backdrop_test.dart
new file mode 100644
index 0000000000..9e54177d61
--- /dev/null
+++ b/mobile/test/shared/widgets/mobile_tab_footer_backdrop_test.dart
@@ -0,0 +1,23 @@
+import 'package:buzz/shared/widgets/mobile_tab_footer_backdrop.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('uses the logical bottom safe-area inset', (tester) async {
+    double? height;
+
+    await tester.pumpWidget(
+      MediaQuery(
+        data: const MediaQueryData(padding: EdgeInsets.only(bottom: 34)),
+        child: Builder(
+          builder: (context) {
+            height = mobileTabFooterBackdropHeight(context);
+            return const SizedBox();
+          },
+        ),
+      ),
+    );
+
+    expect(height, 170);
+  });
+}
diff --git a/schema/schema.sql b/schema/schema.sql
index f5f32cc3e3..3c64729367 100644
--- a/schema/schema.sql
+++ b/schema/schema.sql
@@ -54,6 +54,9 @@ CREATE TABLE communities (
     id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     host            VARCHAR(255) NOT NULL,
     signing_key     BYTEA,
+    -- Per-community workspace icon (NIP-11 `icon`), set via kind:9033.
+    -- Added by migration 0003; kept here so desired-state applies match.
+    icon            TEXT,
     created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
     archived_at     TIMESTAMPTZ,
     CONSTRAINT chk_communities_id_not_nil CHECK (id <> '00000000-0000-0000-0000-000000000000'::uuid)
@@ -1051,3 +1054,23 @@ INSERT INTO _operator_global_tables (table_name, reason) VALUES
     ('push_gateway_endpoint_quotas', 'public gateway endpoint abuse ceilings span relay communities'),
     ('push_gateway_delivery_auth_replays', 'public gateway signed-event replay admission spans relay communities'),
     ('push_gateway_delivery_request_replays', 'public gateway stable request-id admission spans relay communities');
+
+-- ── Replica heartbeat (read-replica freshness fence) ─────────────────────────
+-- Portable read-side freshness observation for the replica fence (see
+-- crates/buzz-db/src/replica_fence.rs and migrations/0026). Exactly one row;
+-- the single-row token UPDATE is the serialization point that makes tokens
+-- globally commit-ordered across relay pods. `epoch` detects token resets
+-- (restore/re-seed) so a stale retained token can never masquerade as fresh
+-- coverage. Deployment-global by design: describes replication topology,
+-- never tenant data.
+
+CREATE TABLE replica_heartbeat (
+    id    smallint PRIMARY KEY CHECK (id = 1),
+    epoch uuid     NOT NULL DEFAULT gen_random_uuid(),
+    token bigint   NOT NULL DEFAULT 0
+);
+
+INSERT INTO replica_heartbeat (id) VALUES (1);
+
+INSERT INTO _operator_global_tables (table_name, reason) VALUES
+    ('replica_heartbeat', 'single-row replication freshness token; describes deployment topology, never tenant data');
diff --git a/scripts/bundle-sidecars.sh b/scripts/bundle-sidecars.sh
index 07de477405..8ea5fe2bbe 100755
--- a/scripts/bundle-sidecars.sh
+++ b/scripts/bundle-sidecars.sh
@@ -4,6 +4,12 @@ set -euo pipefail
 SIDECARS=(buzz-acp buzz-agent buzz-dev-mcp git-credential-nostr buzz)
 HOST=$(rustc -vV | sed -n 's|host: ||p')
 TARGET=${1:-$HOST}
+if [[ "$TARGET" != *windows* ]]; then
+    SIDECARS+=(buzz-backend-kubernetes)
+    BUILD_HINT="cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli"
+else
+    BUILD_HINT="cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli"
+fi
 BINARIES_DIR="desktop/src-tauri/binaries"
 
 # When --target is passed explicitly to cargo (even if it matches the host),
@@ -29,7 +35,7 @@ for bin in "${SIDECARS[@]}"; do
 done
 if [[ ${#missing[@]} -gt 0 ]]; then
     echo "Error: missing release binaries in $SRC_DIR: ${missing[*]}" >&2
-    echo "Run 'cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli' first." >&2
+    echo "Run '$BUILD_HINT' first." >&2
     exit 1
 fi
 
diff --git a/scripts/desktop_release.py b/scripts/desktop_release.py
new file mode 100755
index 0000000000..d6518b26b1
--- /dev/null
+++ b/scripts/desktop_release.py
@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""Generate and validate immutable desktop release candidates."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+CHANGELOG = ROOT / "CHANGELOG.md"
+METADATA = ROOT / ".release" / "desktop-candidate.json"
+SEMVER = re.compile(r"^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$")
+DESKTOP_PATHS = (
+    "desktop/",
+    "crates/buzz-core/",
+    "crates/buzz-persona/",
+    "crates/buzz-sdk/",
+    "crates/buzz-agent/",
+    "crates/buzz-media/",
+)
+CANDIDATE_FILES = {
+    ".release/desktop-candidate.json",
+    "CHANGELOG.md",
+    "desktop/package.json",
+    "desktop/src-tauri/tauri.conf.json",
+    "desktop/src-tauri/Cargo.toml",
+    "desktop/src-tauri/Cargo.lock",
+    "pnpm-lock.yaml",
+}
+REQUIRED_CANDIDATE_FILES = {
+    ".release/desktop-candidate.json",
+    "CHANGELOG.md",
+    "desktop/package.json",
+    "desktop/src-tauri/tauri.conf.json",
+    "desktop/src-tauri/Cargo.toml",
+}
+
+
+def git(*args: str) -> str:
+    return subprocess.check_output(["git", *args], cwd=ROOT, text=True).strip()
+
+
+def commit_list(range_spec: str, paths: tuple[str, ...] | None = None) -> list[dict[str, str]]:
+    args = ["log", range_spec, "--no-merges", "--format=%H%x00%s"]
+    if paths:
+        args += ["--", *paths]
+    out = git(*args)
+    if not out:
+        return []
+    return [dict(zip(("sha", "subject"), line.split("\0", 1))) for line in out.splitlines()]
+
+
+def stable_tags(base_sha: str) -> list[tuple[int, str, str]]:
+    tags: list[tuple[int, str, str]] = []
+    for tag in git("tag", "--merged", base_sha, "--list").splitlines():
+        if not re.fullmatch(r"(?:desktop-)?v[0-9]+\.[0-9]+\.[0-9]+", tag):
+            continue
+        sha = git("rev-list", "-n", "1", tag)
+        distance = int(git("rev-list", "--count", f"{sha}..{base_sha}"))
+        tags.append((distance, tag, sha))
+    return tags
+
+
+def previous_tag(base_sha: str) -> str:
+    tags = stable_tags(base_sha)
+    if not tags:
+        return ""
+    min_distance = min(item[0] for item in tags)
+    nearest = [item for item in tags if item[0] == min_distance]
+    commits = {item[2] for item in nearest}
+    if len(commits) != 1:
+        detail = ", ".join(f"{tag}@{sha}" for _, tag, sha in nearest)
+        raise SystemExit(f"ambiguous previous desktop release tags: {detail}")
+    # During migration, prefer the namespaced tag when aliases share a commit.
+    nearest.sort(key=lambda item: (not item[1].startswith("desktop-v"), item[1]))
+    return nearest[0][1]
+
+
+def bullet(commit: dict[str, str], repo: str) -> str:
+    sha, subject = commit["sha"], commit["subject"]
+    short = sha[:12]
+    pr_match = re.search(r" \(#([0-9]+)\)$", subject)
+    if pr_match:
+        pr = pr_match.group(1)
+        subject = subject[: pr_match.start()]
+        return f"- {subject} ([#{pr}](https://github.com/{repo}/pull/{pr})) ([`{sha}`](https://github.com/{repo}/commit/{sha}))"
+    return f"- {subject} ([`{sha}`](https://github.com/{repo}/commit/{sha}))"
+
+
+def expected(base_sha: str, previous: str) -> tuple[list[dict[str, str]], list[dict[str, str]]]:
+    # With no prior desktop tag, account for the repository's root commit too.
+    # A ``root..base`` range silently drops that first commit.
+    range_spec = f"{previous}..{base_sha}" if previous else base_sha
+    all_commits = commit_list(range_spec)
+    relevant_shas = {c["sha"] for c in commit_list(range_spec, DESKTOP_PATHS)}
+    relevant = [c for c in all_commits if c["sha"] in relevant_shas]
+    other = [c for c in all_commits if c["sha"] not in relevant_shas]
+    return relevant, other
+
+
+def render(version: str, base_sha: str, previous: str, repo: str) -> tuple[str, list[str]]:
+    relevant, other = expected(base_sha, previous)
+    lines = [f"## v{version}", "", "### Desktop and shared changes", ""]
+    lines += [bullet(c, repo) for c in relevant] or ["- None"]
+    lines += ["", "### Other repository changes", ""]
+    lines += [bullet(c, repo) for c in other] or ["- None"]
+    compare_start = previous or git("rev-list", "--max-parents=0", base_sha).splitlines()[0]
+    lines += ["", f"[Compare {compare_start}...desktop-v{version}](https://github.com/{repo}/compare/{compare_start}...desktop-v{version})"]
+    return "\n".join(lines) + "\n", [c["sha"] for c in relevant + other]
+
+
+def generate(args: argparse.Namespace) -> None:
+    if not SEMVER.fullmatch(args.version):
+        raise SystemExit(f"invalid semver: {args.version}")
+    base_sha = git("rev-parse", args.base)
+    previous = previous_tag(base_sha)
+    repo = args.repo or re.sub(r".*github\.com[:/]", "", git("remote", "get-url", "origin")).removesuffix(".git")
+    block, commits = render(args.version, base_sha, previous, repo)
+    old = CHANGELOG.read_text() if CHANGELOG.exists() else "# Changelog\n"
+    if not old.startswith("# Changelog"):
+        raise SystemExit("CHANGELOG.md must begin with '# Changelog'")
+    remainder = old.split("\n", 1)[1].lstrip("\n") if "\n" in old else ""
+    CHANGELOG.write_text(f"# Changelog\n\n{block}\n{remainder}")
+    METADATA.parent.mkdir(parents=True, exist_ok=True)
+    METADATA.write_text(json.dumps({
+        "schema": 1,
+        "version": args.version,
+        "base_sha": base_sha,
+        "previous_tag": previous or None,
+        "tag": f"desktop-v{args.version}",
+        "commit_count": len(commits),
+    }, indent=2) + "\n")
+
+
+def validate(args: argparse.Namespace) -> None:
+    data = json.loads(METADATA.read_text())
+    version = args.version or data["version"]
+    if data != {**data, "version": version}:
+        raise SystemExit("candidate version does not match metadata")
+    if data["tag"] != f"desktop-v{version}":
+        raise SystemExit("candidate tag does not match version")
+    candidate = git("rev-parse", args.candidate)
+    parents = git("show", "-s", "--format=%P", candidate).split()
+    if len(parents) != 1 or parents[0] != data["base_sha"]:
+        raise SystemExit("candidate must be one commit directly above recorded base_sha")
+    changed = set(git("diff-tree", "--no-commit-id", "--name-only", "-r", candidate).splitlines())
+    unexpected = changed - CANDIDATE_FILES
+    missing = REQUIRED_CANDIDATE_FILES - changed
+    if unexpected or missing:
+        detail = []
+        if unexpected:
+            detail.append(f"unexpected files: {', '.join(sorted(unexpected))}")
+        if missing:
+            detail.append(f"missing required files: {', '.join(sorted(missing))}")
+        raise SystemExit("candidate is not version-only (" + "; ".join(detail) + ")")
+    previous = data["previous_tag"] or ""
+    actual_previous = previous_tag(data["base_sha"])
+    if previous != actual_previous:
+        raise SystemExit(
+            f"recorded previous tag {previous or '<none>'} does not match "
+            f"nearest release tag {actual_previous or '<none>'}"
+        )
+    repo = args.repo or "block/buzz"
+    expected_block, shas = render(version, data["base_sha"], previous, repo)
+    text = CHANGELOG.read_text()
+    blocks = re.findall(rf"(?ms)^## v{re.escape(version)}\n.*?(?=^## v|\Z)", text)
+    if len(blocks) != 1:
+        raise SystemExit(f"expected exactly one changelog block for v{version}")
+    if blocks[0].rstrip() != expected_block.rstrip():
+        raise SystemExit("changelog block is not deterministic for recorded candidate base")
+    found = re.findall(r"\[`([0-9a-f]{40})`\]", blocks[0])
+    if len(found) != len(set(found)) or set(found) != set(shas) or len(found) != data["commit_count"]:
+        raise SystemExit("changelog does not account for every expected non-merge commit exactly once")
+    manifests = {
+        ROOT / "desktop/package.json": json.loads((ROOT / "desktop/package.json").read_text())["version"],
+        ROOT / "desktop/src-tauri/tauri.conf.json": json.loads((ROOT / "desktop/src-tauri/tauri.conf.json").read_text())["version"],
+    }
+    cargo = re.search(r'(?m)^version = "([^"]+)"', (ROOT / "desktop/src-tauri/Cargo.toml").read_text())
+    manifests[ROOT / "desktop/src-tauri/Cargo.toml"] = cargo.group(1) if cargo else ""
+    bad = [str(path.relative_to(ROOT)) for path, value in manifests.items() if value != version]
+    if bad:
+        raise SystemExit(f"version mismatch in: {', '.join(bad)}")
+    author = git("show", "-s", "--format=%an <%ae>", candidate)
+    body = git("show", "-s", "--format=%B", candidate)
+    if author != "Wes <wesbillman@users.noreply.github.com>":
+        raise SystemExit(f"unexpected candidate author: {author}")
+    if "Signed-off-by: Wes <wesbillman@users.noreply.github.com>" not in body:
+        raise SystemExit("candidate is missing Wes Signed-off-by trailer")
+    if not re.search(r"(?m)^Co-authored-by: .+ <.+>$", body):
+        raise SystemExit("candidate is missing automation Co-authored-by trailer")
+    print(f"validated immutable desktop candidate {candidate} for desktop-v{version}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    sub = parser.add_subparsers(dest="command", required=True)
+    gen = sub.add_parser("generate")
+    gen.add_argument("version")
+    gen.add_argument("--base", required=True)
+    gen.add_argument("--repo")
+    val = sub.add_parser("validate")
+    val.add_argument("--candidate", default="HEAD")
+    val.add_argument("--version")
+    val.add_argument("--repo")
+    args = parser.parse_args()
+    generate(args) if args.command == "generate" else validate(args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/fork-gates/check-additive-only.sh b/scripts/fork-gates/check-additive-only.sh
index 0c8b2460b5..f87fa1b116 100755
--- a/scripts/fork-gates/check-additive-only.sh
+++ b/scripts/fork-gates/check-additive-only.sh
@@ -30,6 +30,8 @@ ALLOW=(
   "scripts/fork-gates/"
   "scripts/audit-harness"
   ".audit-harness/"
+  ".harness-hash"
+  ".harness-hash-extra-patterns"
 )
 # Deliberately carried patches (normally empty — populate ONLY when we carry a
 # fix upstream hasn't merged, and remove the entry once upstream merges it).
diff --git a/scripts/prepare-desktop-release.sh b/scripts/prepare-desktop-release.sh
new file mode 100755
index 0000000000..fb586005fb
--- /dev/null
+++ b/scripts/prepare-desktop-release.sh
@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+version="${1:-}"
+mode="${2:-publish}"
+[[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]] || {
+  echo "usage: $0 <semver> [publish|validate-only]" >&2
+  exit 1
+}
+
+remote="${RELEASE_REMOTE:-origin}"
+git fetch "$remote" refs/heads/main:refs/remotes/origin/main --no-tags
+git fetch "$remote" '+refs/tags/v*:refs/tags/v*' '+refs/tags/desktop-v*:refs/tags/desktop-v*'
+base_sha="$(git rev-parse refs/remotes/origin/main)"
+branch="version-bump/$version"
+
+remote_branch="refs/heads/$branch"
+remote_oid=""
+if remote_oid="$(git ls-remote "$remote" "$remote_branch" | awk '{print $1}')" && [[ -n "$remote_oid" ]]; then
+  git fetch "$remote" "$remote_branch:refs/remotes/origin/$branch"
+fi
+
+git checkout -B "$branch" "$base_sha"
+just bump-desktop-version "$version"
+scripts/desktop_release.py generate "$version" --base "$base_sha" --repo block/buzz
+
+git add \
+  .release/desktop-candidate.json \
+  CHANGELOG.md \
+  desktop/package.json \
+  desktop/src-tauri/tauri.conf.json \
+  desktop/src-tauri/Cargo.toml \
+  desktop/src-tauri/Cargo.lock \
+  pnpm-lock.yaml
+
+agent_name="${RELEASE_AUTOMATION_NAME:-${AGENT_NAME:-Release Automation}}"
+agent_email="${RELEASE_AUTOMATION_EMAIL:-${AGENT_EMAIL:-release-automation@users.noreply.github.com}}"
+msg="$(mktemp)"
+trap 'rm -f "$msg"' EXIT
+cat >"$msg" <<EOF
+chore(release): release Buzz Desktop version $version
+
+Co-authored-by: $agent_name <$agent_email>
+EOF
+git -c user.name='Wes' -c user.email='wesbillman@users.noreply.github.com' \
+  commit -s -F "$msg"
+scripts/desktop_release.py validate --candidate HEAD --version "$version" --repo block/buzz
+
+candidate_sha="$(git rev-parse HEAD)"
+previous_tag="$(python3 -c 'import json; print(json.load(open(".release/desktop-candidate.json"))["previous_tag"] or "initial")')"
+printf 'base_sha=%s\ncandidate_sha=%s\nprevious_tag=%s\ntag=desktop-v%s\n' \
+  "$base_sha" "$candidate_sha" "$previous_tag" "$version"
+
+if [[ "$mode" == validate-only ]]; then
+  exit 0
+fi
+[[ "$mode" == publish ]] || { echo "unknown mode: $mode" >&2; exit 1; }
+if [[ -n "$remote_oid" ]]; then
+  git push --force-with-lease="$remote_branch:$remote_oid" "$remote" "HEAD:$remote_branch"
+else
+  git push --force-with-lease="$remote_branch:" "$remote" "HEAD:$remote_branch"
+fi
+
+body="$(mktemp)"
+trap 'rm -f "$msg" "$body"' EXIT
+cat >"$body" <<EOF
+## Buzz Desktop release v$version
+
+- **Frozen main:** \`$base_sha\`
+- **Reviewed candidate:** \`$candidate_sha\`
+- **Previous desktop release:** \`$previous_tag\`
+- **Proposed immutable tag:** \`desktop-v$version\`
+
+This PR must be **squash merged** only after the Desktop Release Candidate check passes. The branch must remain based directly on current \`main\`; stale base, payload drift, incomplete notes, or an unauthorized merge produce no tag.
+
+The checked-in changelog accounts for every non-merge commit in the release range. Publication remains bound to the immutable candidate tag.
+EOF
+if existing="$(gh pr list --head "$branch" --state open --json number --jq '.[0].number')" && [[ -n "$existing" ]]; then
+  gh pr edit "$existing" --title "chore(release): release Buzz Desktop version $version" --body-file "$body"
+else
+  gh pr create --base main --head "$branch" \
+    --title "chore(release): release Buzz Desktop version $version" --body-file "$body"
+fi
diff --git a/scripts/required-check-succeeded.jq b/scripts/required-check-succeeded.jq
new file mode 100644
index 0000000000..e848f46143
--- /dev/null
+++ b/scripts/required-check-succeeded.jq
@@ -0,0 +1,14 @@
+# GitHub treats success, skipped, and neutral as successful conclusions for
+# required checks. Evaluate the newest run so a stale pass cannot mask a rerun.
+[
+  .[].check_runs[]
+  | select(.name == $name)
+]
+| sort_by(.started_at // .created_at // "")
+| last
+| .status == "completed"
+  and (
+    .conclusion == "success"
+    or .conclusion == "skipped"
+    or .conclusion == "neutral"
+  )
diff --git a/scripts/review-decision-approved.jq b/scripts/review-decision-approved.jq
new file mode 100644
index 0000000000..011f28fdc6
--- /dev/null
+++ b/scripts/review-decision-approved.jq
@@ -0,0 +1 @@
+.reviewDecision == "APPROVED"
diff --git a/scripts/run-tests.sh b/scripts/run-tests.sh
index 4dd1142801..0e5946ca18 100755
--- a/scripts/run-tests.sh
+++ b/scripts/run-tests.sh
@@ -84,6 +84,12 @@ run_unit_tests() {
   run_test_step "buzz-auth unit tests" \
     cargo test -p buzz-auth --lib -- --nocapture
 
+  run_test_step "buzz-voice tests" \
+    cargo test -p buzz-voice --lib -- --nocapture
+
+  run_test_step "buzz-cli tests" \
+    cargo test -p buzz-cli -- --nocapture
+
   # buzz-db migrator/lint unit tests (no infra): guard the embedded-migrator
   # invariant (exactly the consolidated 0001; cutover/backfill stays an operator
   # script, not startup state) and the tenant-scoping lints. The Postgres-backed
@@ -100,6 +106,12 @@ run_unit_tests() {
 
   run_test_step "buzz-push-gateway tests" \
     cargo test -p buzz-push-gateway -- --nocapture
+
+  # Kubernetes backend provider: pure decision layers driven by a fake
+  # substrate, no cluster. Mirrors the nextest path in `just test-unit` —
+  # the two lists must stay in step or the fallback silently covers less.
+  run_test_step "buzz-backend-kubernetes tests" \
+    cargo test -p buzz-backend-kubernetes -- --nocapture
 }
 
 # ---- DB / integration tests (infra required) --------------------------------
diff --git a/scripts/sprig-entrypoint.sh b/scripts/sprig-entrypoint.sh
new file mode 100755
index 0000000000..16abf7bc51
--- /dev/null
+++ b/scripts/sprig-entrypoint.sh
@@ -0,0 +1,16 @@
+#!/bin/bash
+set -euo pipefail
+
+# Match desktop's URL-scoped git credential configuration without installing a
+# helper globally (which would make it answer for unrelated remotes).
+if [[ -n "${BUZZ_RELAY_URL:-}" ]]; then
+    relay_http_url="${BUZZ_RELAY_URL/#ws:/http:}"
+    relay_http_url="${relay_http_url/#wss:/https:}"
+    relay_http_url="${relay_http_url%/}"
+    git config --global "credential.${relay_http_url}/git.helper" \
+        /usr/local/bin/git-credential-nostr
+    git config --global "credential.${relay_http_url}/git.useHttpPath" true
+fi
+
+# The harness must receive Kubernetes' termination signal directly.
+exec buzz-acp "$@"
diff --git a/scripts/test-desktop-release-authorization.sh b/scripts/test-desktop-release-authorization.sh
new file mode 100755
index 0000000000..5a51a976be
--- /dev/null
+++ b/scripts/test-desktop-release-authorization.sh
@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/bin"
+cat >"$tmp/bin/gh" <<'GH'
+#!/usr/bin/env bash
+set -euo pipefail
+printf '%q ' "$@" >>"$GH_CALLS"
+printf '\n' >>"$GH_CALLS"
+
+[[ "${1:-}" == api ]] || { echo "expected gh api" >&2; exit 91; }
+if [[ "${2:-}" == graphql ]]; then
+  expected_query='query($owner:String!,$repo:String!,$number:Int!){repository(owner:$owner,name:$repo){pullRequest(number:$number){reviewDecision}}}'
+  [[ "$#" -eq 12 && "$3" == -f && "$4" == "query=$expected_query" &&
+    "$5" == -F && "$6" == owner=block &&
+    "$7" == -F && "$8" == repo=buzz &&
+    "$9" == -F && "${10}" == number=123 &&
+    "${11}" == --jq && "${12}" == '.data.repository.pullRequest' ]] || {
+    echo "GraphQL call does not match the deployed query contract" >&2; exit 92;
+  }
+  if [[ -n "${REVIEW_DECISION:-}" ]]; then printf '%s\n' "$REVIEW_DECISION"; else printf '%s\n' '{"reviewDecision":"APPROVED"}'; fi
+elif [[ "$#" -eq 4 && "$2" == --paginate && "$3" == --slurp && "$4" == "repos/block/buzz/pulls/123/reviews?per_page=100&page=1" ]]; then
+  [[ "${GH_FAIL_REVIEWS:-false}" != true ]] || { echo "simulated reviews API failure" >&2; exit 94; }
+  if [[ -n "${REVIEWS:-}" ]]; then printf '%s\n' "$REVIEWS"; else printf '%s\n' '[[],[{"state":"APPROVED","commit_id":"head","author_association":"MEMBER"}]]'; fi
+else
+  echo "unexpected or malformed gh call: $*" >&2
+  exit 95
+fi
+GH
+chmod +x "$tmp/bin/gh"
+
+run_authorization() {
+  (cd "$repo_root" && PATH="$tmp/bin:$PATH" GH_CALLS="$tmp/calls" GH_TOKEN=test \
+    GITHUB_REPOSITORY=block/buzz PR_NUMBER=123 PR_HEAD_SHA=head \
+    REVIEW_DECISION="${REVIEW_DECISION-}" REVIEWS="${REVIEWS-}" GH_FAIL_REVIEWS="${GH_FAIL_REVIEWS-false}" \
+    scripts/verify-desktop-release-authorization.sh)
+}
+
+: >"$tmp/calls"
+run_authorization
+! grep -Fq 'rule-suites' "$tmp/calls"
+
+for invalid in \
+  '[[{"state":"APPROVED","commit_id":"stale","author_association":"MEMBER"}]]' \
+  '[[{"state":"APPROVED","commit_id":"head","author_association":"NONE"}]]' \
+  '[[{"state":"CHANGES_REQUESTED","commit_id":"head","author_association":"MEMBER"}]]'; do
+  : >"$tmp/calls"
+  if REVIEWS="$invalid" run_authorization >/dev/null 2>&1; then
+    echo "invalid approval was accepted: $invalid" >&2
+    exit 1
+  fi
+done
+
+: >"$tmp/calls"
+if REVIEW_DECISION='{"reviewDecision":"CHANGES_REQUESTED"}' run_authorization >/dev/null 2>&1; then
+  echo "changes-requested review decision was accepted" >&2
+  exit 1
+fi
+
+: >"$tmp/calls"
+if GH_FAIL_REVIEWS=true run_authorization >/dev/null 2>&1; then
+  echo "reviews API failure was ignored" >&2
+  exit 1
+fi
+
+echo "desktop release authorization passed"
diff --git a/scripts/test-desktop-release-candidate.sh b/scripts/test-desktop-release-candidate.sh
new file mode 100755
index 0000000000..f36a1d690a
--- /dev/null
+++ b/scripts/test-desktop-release-candidate.sh
@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+cp "$repo_root/scripts/desktop_release.py" "$tmp/desktop_release.py"
+
+git -C "$tmp" init -q
+git -C "$tmp" config user.name test
+git -C "$tmp" config user.email test@example.com
+mkdir -p "$tmp/scripts" "$tmp/desktop/src-tauri" "$tmp/crates/buzz-core" "$tmp/.release"
+mv "$tmp/desktop_release.py" "$tmp/scripts/desktop_release.py"
+printf '{"version":"1.0.0"}\n' > "$tmp/desktop/package.json"
+printf '{"version":"1.0.0"}\n' > "$tmp/desktop/src-tauri/tauri.conf.json"
+printf '[package]\nversion = "1.0.0"\n' > "$tmp/desktop/src-tauri/Cargo.toml"
+echo '# Changelog' > "$tmp/CHANGELOG.md"
+echo first > "$tmp/desktop/feature"
+git -C "$tmp" add .
+git -C "$tmp" commit -qm 'feat: first desktop change'
+git -C "$tmp" -c tag.gpgSign=false tag v1.0.0
+echo second >> "$tmp/desktop/feature"
+git -C "$tmp" commit -qam 'fix: desktop fix'
+echo policy > "$tmp/POLICY.md"
+git -C "$tmp" add POLICY.md
+git -C "$tmp" commit -qm 'docs: repository policy'
+base=$(git -C "$tmp" rev-parse HEAD)
+(
+  cd "$tmp"
+  scripts/desktop_release.py generate 1.0.1 --base "$base" --repo block/buzz
+  python3 - <<'PY'
+import json
+for path in ('desktop/package.json', 'desktop/src-tauri/tauri.conf.json'):
+    data=json.load(open(path)); data['version']='1.0.1'; open(path,'w').write(json.dumps(data)+'\n')
+p='desktop/src-tauri/Cargo.toml'; open(p,'w').write('[package]\nversion = "1.0.1"\n')
+PY
+  rm -f msg
+  git add .
+  cat >msg <<'EOF'
+chore(release): release Buzz Desktop version 1.0.1
+
+Co-authored-by: Test Automation <test@example.com>
+EOF
+  git -c user.name=Wes -c user.email=wesbillman@users.noreply.github.com commit -q -s -F msg
+  rm msg
+  scripts/desktop_release.py validate --version 1.0.1 --repo block/buzz
+  grep -Fq '### Other repository changes' CHANGELOG.md
+  grep -Fq "$(git rev-parse HEAD~1)" CHANGELOG.md
+  grep -Fq "$(git rev-parse HEAD~2)" CHANGELOG.md
+
+  # Metadata cannot lie about the prior release boundary.
+  cp .release/desktop-candidate.json metadata.json
+  python3 - <<'PY'
+import json
+p='.release/desktop-candidate.json'; d=json.load(open(p)); d['previous_tag']=None; open(p,'w').write(json.dumps(d)+'\n')
+PY
+  if scripts/desktop_release.py validate --version 1.0.1 --repo block/buzz >/dev/null 2>&1; then
+    echo "validator accepted a forged previous release tag" >&2
+    exit 1
+  fi
+  mv metadata.json .release/desktop-candidate.json
+)
+
+# An initial release must account for the root commit, not silently omit it.
+initial=$(mktemp -d)
+cp "$repo_root/scripts/desktop_release.py" "$initial/desktop_release.py"
+git -C "$initial" init -q
+git -C "$initial" config user.name test
+git -C "$initial" config user.email test@example.com
+mkdir -p "$initial/scripts" "$initial/desktop/src-tauri"
+mv "$initial/desktop_release.py" "$initial/scripts/desktop_release.py"
+printf '{"version":"0.1.0"}\n' > "$initial/desktop/package.json"
+printf '{"version":"0.1.0"}\n' > "$initial/desktop/src-tauri/tauri.conf.json"
+printf '[package]\nversion = "0.1.0"\n' > "$initial/desktop/src-tauri/Cargo.toml"
+printf '# Changelog\n' > "$initial/CHANGELOG.md"
+echo root > "$initial/ROOT.md"
+git -C "$initial" add .
+git -C "$initial" commit -qm 'feat: root release content'
+root_sha=$(git -C "$initial" rev-parse HEAD)
+(cd "$initial" && scripts/desktop_release.py generate 0.1.0 --base "$root_sha" --repo block/buzz)
+grep -Fq "$root_sha" "$initial/CHANGELOG.md"
+rm -rf "$initial"
+
+echo "desktop release candidate contract passed"
diff --git a/scripts/test-k8s-provider-release.sh b/scripts/test-k8s-provider-release.sh
new file mode 100755
index 0000000000..40c78e2688
--- /dev/null
+++ b/scripts/test-k8s-provider-release.sh
@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Reproduce the desktop release's multi-package build shape, then prove the
+# Kubernetes provider reports an unreachable cluster in-band rather than
+# panicking when rustls has multiple compiled crypto providers available.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+TARGET_DIR="${CARGO_TARGET_DIR:-$ROOT/target}"
+PROVIDER_BINARY="$TARGET_DIR/release/buzz-backend-kubernetes"
+
+CARGO="${CARGO:-cargo}"
+"$CARGO" build --release \
+  -p buzz-acp \
+  -p buzz-agent \
+  -p buzz-dev-mcp \
+  -p git-credential-nostr \
+  -p buzz-cli \
+  -p buzz-backend-kubernetes
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+cat >"$TMP/kubeconfig" <<'YAML'
+apiVersion: v1
+kind: Config
+clusters:
+  - name: unreachable
+    cluster:
+      server: http://127.0.0.1:9
+contexts:
+  - name: unreachable
+    context:
+      cluster: unreachable
+      user: none
+current-context: unreachable
+users:
+  - name: none
+    user: {}
+YAML
+
+cat >"$TMP/request.json" <<'JSON'
+{
+  "op": "deploy",
+  "agent": {
+    "relay_url": "wss://relay.example",
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+    "auth_tag": "owner",
+    "launch": {"command": "goose", "args": [], "env": {}, "policy_env": {}}
+  },
+  "provider_config": {
+    "context": "unreachable",
+    "namespace": "never-created",
+    "image": "example.invalid/sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "inactivity_seconds": 60
+  }
+}
+JSON
+
+set +e
+KUBECONFIG="$TMP/kubeconfig" \
+  "$PROVIDER_BINARY" \
+  <"$TMP/request.json" >"$TMP/stdout" 2>"$TMP/stderr"
+status=$?
+set -e
+
+[[ "$status" == 0 ]] || {
+  echo "provider exited $status instead of returning an in-band failure" >&2
+  cat "$TMP/stderr" >&2
+  exit 1
+}
+[[ "$(wc -l <"$TMP/stdout" | tr -d ' ')" == 1 ]]
+jq -e '.ok == false and (.error | type == "string" and length > 0)' "$TMP/stdout" >/dev/null
+if rg -i 'panic|crypto provider|no process-level' "$TMP/stdout" "$TMP/stderr"; then
+  echo "provider emitted a panic/crypto-provider failure" >&2
+  exit 1
+fi
+printf 'PASS: release-shaped provider returned one in-band unreachable-cluster failure\n'
diff --git a/scripts/test-k8s-sprig-image-live.sh b/scripts/test-k8s-sprig-image-live.sh
new file mode 100755
index 0000000000..ec9f259053
--- /dev/null
+++ b/scripts/test-k8s-sprig-image-live.sh
@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# Prove that a cluster can resolve and start the exact digest-qualified Sprig
+# image that will be passed to the Kubernetes provider. This is intentionally a
+# separate preflight: a Docker image existing in the host daemon does not imply
+# that the kubelet's container runtime can resolve the same name and digest.
+set -euo pipefail
+
+: "${BUZZ_K8S_TEST_CONTEXT:?set the explicit disposable/local kubectl context}"
+: "${BUZZ_SPRIG_IMAGE:?set an immutable image reference (name@sha256:<64 hex>)}"
+
+if [[ ! "$BUZZ_SPRIG_IMAGE" =~ ^[^[:space:]@]+@sha256:[0-9a-fA-F]{64}$ ]]; then
+    echo "error: BUZZ_SPRIG_IMAGE must be name@sha256:<64 hex>" >&2
+    exit 2
+fi
+
+CONTEXT="$BUZZ_K8S_TEST_CONTEXT"
+IMAGE="$BUZZ_SPRIG_IMAGE"
+PULL_POLICY="${BUZZ_K8S_TEST_PULL_POLICY:-IfNotPresent}"
+case "$PULL_POLICY" in
+    Always|IfNotPresent|Never) ;;
+    *) echo "error: invalid BUZZ_K8S_TEST_PULL_POLICY: $PULL_POLICY" >&2; exit 2 ;;
+esac
+
+MANAGED_BY="buzz-backend-kubernetes"
+BINDING_VERSION="v1"
+NAMESPACE="buzz-k8s-sprig-$(date +%s)-$RANDOM"
+CREATED=0
+
+cleanup() {
+    (( CREATED == 1 )) || return 0
+    local managed binding foreign
+    managed="$(kubectl --context "$CONTEXT" get namespace "$NAMESPACE" \
+        -o jsonpath='{.metadata.labels.app\.kubernetes\.io/managed-by}' 2>/dev/null || true)"
+    binding="$(kubectl --context "$CONTEXT" get namespace "$NAMESPACE" \
+        -o jsonpath='{.metadata.labels.buzz\.block\.xyz/binding-version}' 2>/dev/null || true)"
+    if [[ "$managed" != "$MANAGED_BY" || "$binding" != "$BINDING_VERSION" ]]; then
+        echo "REFUSING cleanup: namespace ownership markers changed: $NAMESPACE" >&2
+        return 1
+    fi
+    foreign="$(kubectl --context "$CONTEXT" --namespace "$NAMESPACE" get pods -o json \
+        | jq '[.items[] | select(.metadata.labels["app.kubernetes.io/managed-by"] != "buzz-backend-kubernetes" or .metadata.labels["buzz.block.xyz/binding-version"] != "v1")] | length')"
+    if [[ "$foreign" != 0 ]]; then
+        echo "REFUSING cleanup: namespace contains an unowned pod: $NAMESPACE" >&2
+        return 1
+    fi
+    kubectl --context "$CONTEXT" delete namespace "$NAMESPACE" --wait=true
+}
+trap cleanup EXIT
+
+# Fail before mutation if the named context is absent or inaccessible. Print the
+# cluster identity so evidence cannot be mistaken for a different kubeconfig.
+kubectl config get-contexts "$CONTEXT" >/dev/null
+SERVER="$(kubectl config view --minify --context "$CONTEXT" -o jsonpath='{.clusters[0].cluster.server}')"
+kubectl --context "$CONTEXT" get nodes -o name >/dev/null
+printf 'context=%s\nserver=%s\nimage=%s\npull_policy=%s\nnamespace=%s\n' \
+    "$CONTEXT" "$SERVER" "$IMAGE" "$PULL_POLICY" "$NAMESPACE"
+
+kubectl --context "$CONTEXT" create namespace "$NAMESPACE"
+CREATED=1
+kubectl --context "$CONTEXT" label namespace "$NAMESPACE" \
+    "app.kubernetes.io/managed-by=$MANAGED_BY" \
+    "buzz.block.xyz/binding-version=$BINDING_VERSION"
+
+cat <<YAML | kubectl --context "$CONTEXT" --namespace "$NAMESPACE" apply -f -
+apiVersion: v1
+kind: Pod
+metadata:
+  name: digest-resolution-probe
+  labels:
+    app.kubernetes.io/managed-by: $MANAGED_BY
+    buzz.block.xyz/binding-version: $BINDING_VERSION
+spec:
+  restartPolicy: Never
+  containers:
+    - name: probe
+      image: $IMAGE
+      imagePullPolicy: $PULL_POLICY
+      command: [/bin/bash, -ceu]
+      args:
+        - 'test "\$(readlink /usr/local/bin/buzz-acp)" = sprig; echo DIGEST_ABI_OK'
+YAML
+
+if ! kubectl --context "$CONTEXT" --namespace "$NAMESPACE" wait \
+    --for=jsonpath='{.status.phase}'=Succeeded pod/digest-resolution-probe --timeout=120s; then
+    kubectl --context "$CONTEXT" --namespace "$NAMESPACE" describe pod digest-resolution-probe >&2 || true
+    exit 1
+fi
+
+kubectl --context "$CONTEXT" --namespace "$NAMESPACE" logs digest-resolution-probe
+IMAGE_ID="$(kubectl --context "$CONTEXT" --namespace "$NAMESPACE" get pod digest-resolution-probe \
+    -o jsonpath='{.status.containerStatuses[0].imageID}')"
+RESOLVED_SPEC="$(kubectl --context "$CONTEXT" --namespace "$NAMESPACE" get pod digest-resolution-probe \
+    -o jsonpath='{.spec.containers[0].image}')"
+[[ "$RESOLVED_SPEC" == "$IMAGE" ]]
+[[ -n "$IMAGE_ID" ]]
+printf 'resolved_spec=%s\nimage_id=%s\nPASS: exact digest-qualified Sprig reference started\n' \
+    "$RESOLVED_SPEC" "$IMAGE_ID"
diff --git a/scripts/test-release-ref-contract.sh b/scripts/test-release-ref-contract.sh
index 0d810819d9..6722135bb8 100755
--- a/scripts/test-release-ref-contract.sh
+++ b/scripts/test-release-ref-contract.sh
@@ -12,16 +12,16 @@ git -C "$tmp" config user.email test@example.com
 echo first >"$tmp/file"
 git -C "$tmp" add file
 git -C "$tmp" commit -qm first
-git -C "$tmp" tag -m "desktop release" v1.2.3
+git -C "$tmp" tag -m "desktop release" desktop-v1.2.3
 
 (
   cd "$tmp"
-  GITHUB_REF=refs/tags/v1.2.3 "$verify" v 1.2.3
+  GITHUB_REF=refs/tags/desktop-v1.2.3 "$verify" desktop-v 1.2.3
 )
 
 if (
   cd "$tmp"
-  GITHUB_REF=refs/heads/main "$verify" v 1.2.3
+  GITHUB_REF=refs/heads/main "$verify" desktop-v 1.2.3
 ); then
   echo "branch-backed desktop release was accepted" >&2
   exit 1
@@ -31,7 +31,7 @@ echo second >>"$tmp/file"
 git -C "$tmp" commit -qam second
 if (
   cd "$tmp"
-  GITHUB_REF=refs/tags/v1.2.3 "$verify" v 1.2.3
+  GITHUB_REF=refs/tags/desktop-v1.2.3 "$verify" desktop-v 1.2.3
 ); then
   echo "release accepted HEAD after the tag commit" >&2
   exit 1
@@ -61,6 +61,90 @@ grep -q 'private-key:.*secrets\.BUZZ_RELEASE_TAGGER_PRIVATE_KEY' "$auto_tag"
 grep -q 'permission-contents: write' "$auto_tag"
 grep -q 'GH_TOKEN:.*steps\.release-tagger\.outputs\.token' "$auto_tag"
 grep -Fq 'git/refs' "$auto_tag"
+grep -Fq 'TAG_PREFIX="desktop-v"' "$auto_tag"
+grep -Fq 'target_sha=${{ github.event.pull_request.merge_commit_sha }}' "$auto_tag"
+grep -Fq 'scripts/verify-desktop-release-merge.sh' "$auto_tag"
+grep -Fq 'current \`main\`' "$repo_root/scripts/prepare-desktop-release.sh"
+if grep -Fq 'current `main`' "$repo_root/scripts/prepare-desktop-release.sh"; then
+  echo "desktop release PR body contains executable command substitution" >&2
+  exit 1
+fi
+"$repo_root/scripts/test-desktop-release-authorization.sh"
+if rg -q 'rule-suites|desktop-release-bypass-authorized|MERGED_BY' \
+  "$repo_root/scripts/verify-desktop-release-merge.sh" \
+  "$repo_root/scripts/verify-desktop-release-authorization.sh" \
+  "$auto_tag"; then
+  echo "desktop auto-tag still depends on unavailable rule-suite authorization" >&2
+  exit 1
+fi
+
+review_filter="$repo_root/scripts/review-decision-approved.jq"
+for fixture in \
+  '{"reviewDecision":"CHANGES_REQUESTED"}' \
+  '{"reviewDecision":"REVIEW_REQUIRED"}' \
+  '{"reviewDecision":null}' \
+  '{}'; do
+  if jq -e -f "$review_filter" <<<"$fixture" >/dev/null; then
+    echo "review-decision filter accepted non-approved fixture: $fixture" >&2
+    exit 1
+  fi
+done
+jq -e -f "$review_filter" >/dev/null <<'JSON' || {
+{"reviewDecision":"APPROVED"}
+JSON
+  echo "review-decision filter rejected approved GraphQL response" >&2
+  exit 1
+}
+required_check_filter="$repo_root/scripts/required-check-succeeded.jq"
+check_fixture() {
+  local expected="$1" conclusion="$2" status="${3:-completed}"
+  local payload
+  payload=$(jq -n --arg status "$status" --arg conclusion "$conclusion" '{check_runs: [{name: "Web", status: $status, conclusion: $conclusion, started_at: "2026-01-01T00:00:00Z"}]}')
+  if jq -e --arg name Web -f "$required_check_filter" <<<"[$payload]" >/dev/null; then
+    actual=pass
+  else
+    actual=fail
+  fi
+  [[ "$actual" == "$expected" ]] || {
+    echo "required-check filter: expected $conclusion/$status to $expected" >&2
+    exit 1
+  }
+}
+check_fixture pass success
+check_fixture pass skipped
+check_fixture pass neutral
+check_fixture fail failure
+check_fixture fail success in_progress
+# A newer failure must not be hidden by an older successful run of the same check.
+jq -e --arg name Web -f "$required_check_filter" >/dev/null <<'JSON' && {
+[{"check_runs":[
+  {"name":"Web","status":"completed","conclusion":"success","started_at":"2026-01-01T00:00:00Z"},
+  {"name":"Web","status":"completed","conclusion":"failure","started_at":"2026-01-02T00:00:00Z"}
+]}]
+JSON
+  echo "required-check filter accepted a stale pass over a newer failure" >&2
+  exit 1
+}
+release_workflow="$repo_root/.github/workflows/release.yml"
+[[ "$(grep -c 'contents: write' "$release_workflow")" -eq 1 ]] || {
+  echo "desktop release must have exactly one GitHub contents writer" >&2; exit 1;
+}
+grep -Fq "needs.release.result == 'success'" "$release_workflow"
+grep -Fq "needs.release-macos-x64.result == 'success'" "$release_workflow"
+grep -Fq "needs.release-linux.result == 'success'" "$release_workflow"
+grep -Fq "needs.release-windows.result == 'success'" "$release_workflow"
+grep -Fq "refs/tags/desktop-v{0}" "$release_workflow"
+grep -Fq "if: \${{ !contains(needs.setup.outputs.version, '-') }}" "$release_workflow"
+if grep -Fq "env.already_published != 'true' && !contains(needs.setup.outputs.version, '-')" "$release_workflow"; then
+  echo "rolling updater retry is incorrectly gated by versioned publication state" >&2; exit 1
+fi
+grep -Fq 'group: desktop-release-${{ github.ref }}' "$release_workflow"
+grep -Fq 'cancel-in-progress: false' "$release_workflow"
+grep -Fq 'release artifact basename collision' "$release_workflow"
+[[ "$(grep -c 'gh release upload' "$release_workflow")" -eq 2 ]] || {
+  echo "only the final writer may upload versioned and rolling release assets" >&2; exit 1;
+}
+grep -Fq 'if: env.already_published' "$release_workflow"
 grep -Fq 'if gh api "repos/$GITHUB_REPOSITORY/git/ref/tags/$TAG" --silent 2>/dev/null; then' "$auto_tag"
 if grep -F 'git/ref/tags/$TAG' "$auto_tag" | grep -Fq '|| true'; then
   echo "auto-tag ignores a failed tag lookup, so a 404 body can look like an existing tag" >&2
diff --git a/scripts/test-sprig-image.sh b/scripts/test-sprig-image.sh
new file mode 100755
index 0000000000..4ca42fdb4d
--- /dev/null
+++ b/scripts/test-sprig-image.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+IMAGE="${1:-buzz-sprig:contract-test}"
+if [[ "${SKIP_BUILD:-0}" != 1 ]]; then
+    docker build --file Dockerfile.sprig --tag "$IMAGE" .
+fi
+
+assert_run() {
+    docker run --rm --entrypoint /bin/bash "$IMAGE" -ceu "$1"
+}
+
+assert_run '
+  command -v bash git update-ca-certificates >/dev/null
+  test "$(readlink /usr/local/bin/buzz-acp)" = sprig
+  for name in buzz-agent buzz-dev-mcp rg tree buzz git-credential-nostr git-sign-nostr; do
+    test "$(readlink "/usr/local/bin/$name")" = sprig
+  done
+  test "$(git config --system gpg.x509.program)" = /usr/local/bin/git-sign-nostr
+  ! git config --system --get-all credential.helper
+  test "$HOME" = /home/agent
+  test "$(pwd)" = /home/agent
+'
+
+assert_run '
+  grep -Eq "^[[:space:]]*exec buzz-acp" /usr/local/bin/sprig-entrypoint
+  ! grep -Eq "^[[:space:]]*(buzz-acp|bash -c .*buzz-acp)" /usr/local/bin/sprig-entrypoint
+'
+
+docker run --rm --entrypoint /bin/bash \
+  -e BUZZ_RELAY_URL=wss://relay.example.test/ "$IMAGE" -ceu '
+    /usr/local/bin/sprig-entrypoint --help >/dev/null 2>&1 & pid=$!
+    for _ in 1 2 3 4 5; do
+      git config --global --get credential.https://relay.example.test/git.helper >/dev/null 2>&1 && break
+      sleep 0.1
+    done
+    test "$(git config --global --get credential.https://relay.example.test/git.helper)" = /usr/local/bin/git-credential-nostr
+    test "$(git config --global --get credential.https://relay.example.test/git.useHttpPath)" = true
+    ! git config --global --get-all credential.helper
+    wait "$pid" || true
+  '
+
+echo "PASS: Sprig image runtime contract ($IMAGE)"
diff --git a/scripts/verify-desktop-release-authorization.sh b/scripts/verify-desktop-release-authorization.sh
new file mode 100755
index 0000000000..b18cf6cade
--- /dev/null
+++ b/scripts/verify-desktop-release-authorization.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+: "${PR_HEAD_SHA:?}"
+: "${PR_NUMBER:?}"
+: "${GITHUB_REPOSITORY:?}"
+: "${GH_TOKEN:?}"
+
+review="$(gh api graphql -f query='query($owner:String!,$repo:String!,$number:Int!){repository(owner:$owner,name:$repo){pullRequest(number:$number){reviewDecision}}}' -F owner="${GITHUB_REPOSITORY%/*}" -F repo="${GITHUB_REPOSITORY#*/}" -F number="$PR_NUMBER" --jq '.data.repository.pullRequest')"
+reviews="$(gh api --paginate --slurp "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/reviews?per_page=100&page=1")"
+valid_approvals="$(jq --arg sha "$PR_HEAD_SHA" '[.[][] | select(.state == "APPROVED" and .commit_id == $sha and (.author_association == "MEMBER" or .author_association == "OWNER" or .author_association == "COLLABORATOR"))] | length' <<<"$reviews")"
+if ! jq -e -f scripts/review-decision-approved.jq <<<"$review" >/dev/null || [[ "$valid_approvals" -eq 0 ]]; then
+  echo "release lacks an exact-head approval" >&2
+  exit 1
+fi
diff --git a/scripts/verify-desktop-release-merge.sh b/scripts/verify-desktop-release-merge.sh
new file mode 100755
index 0000000000..a9fbb48d09
--- /dev/null
+++ b/scripts/verify-desktop-release-merge.sh
@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+: "${PR_HEAD_SHA:?}"
+: "${MERGE_SHA:?}"
+: "${VERSION:?}"
+: "${PR_NUMBER:?}"
+: "${GH_TOKEN:?}"
+
+required_checks=(
+  "Desktop E2E Integration"
+  "Desktop"
+  "Rust Lint"
+  "Security"
+  "Unit Tests"
+  "Windows Rust (x86_64-pc-windows-msvc)"
+  "Mobile"
+  "Web"
+  "Backend Integration (relay e2e)"
+  "Desktop E2E Relay"
+  "Relay E2E"
+  "Desktop Build (macOS)"
+  "DCO Check"
+  "Desktop Release Candidate"
+)
+
+expected_branch="version-bump/$VERSION"
+[[ "${PR_HEAD_REF:-}" == "$expected_branch" ]] || { echo "unexpected release branch" >&2; exit 1; }
+[[ "${PR_BASE_REF:-}" == main ]] || { echo "desktop release must target main" >&2; exit 1; }
+[[ "${PR_HEAD_REPO:-}" == "$GITHUB_REPOSITORY" ]] || { echo "desktop release must be internal" >&2; exit 1; }
+
+git fetch origin "$MERGE_SHA" "$PR_HEAD_SHA" refs/heads/main:refs/remotes/origin/main --no-tags
+mapfile -t parents < <(git show -s --format='%P' "$MERGE_SHA" | tr ' ' '\n')
+[[ "${#parents[@]}" -eq 1 ]] || { echo "desktop release was not squash merged" >&2; exit 1; }
+base_sha="$(git show "$PR_HEAD_SHA:.release/desktop-candidate.json" | jq -r .base_sha)"
+[[ "${parents[0]}" == "$base_sha" ]] || { echo "squash parent is not the frozen candidate base" >&2; exit 1; }
+[[ "$(git show -s --format=%T "$MERGE_SHA")" == "$(git show -s --format=%T "$PR_HEAD_SHA")" ]] || {
+  echo "squash tree differs from the validated candidate" >&2
+  exit 1
+}
+git merge-base --is-ancestor "$MERGE_SHA" origin/main || { echo "squash commit is not reachable from current main" >&2; exit 1; }
+
+git checkout --detach "$PR_HEAD_SHA"
+scripts/desktop_release.py validate --candidate "$PR_HEAD_SHA" --version "$VERSION" --repo "$GITHUB_REPOSITORY"
+
+scripts/verify-desktop-release-authorization.sh
+
+checks="$(gh api --paginate --slurp "repos/$GITHUB_REPOSITORY/commits/$PR_HEAD_SHA/check-runs?per_page=100")"
+for required in "${required_checks[@]}"; do
+  jq -e --arg name "$required" -f scripts/required-check-succeeded.jq <<<"$checks" >/dev/null || {
+    echo "required check is missing or unsuccessful: $required" >&2
+    exit 1
+  }
+done
+status="$(gh api "repos/$GITHUB_REPOSITORY/commits/$PR_HEAD_SHA/status")"
+jq -e '(.total_count == 0) or (.state == "success")' <<<"$status" >/dev/null || {
+  echo "candidate has a failing or pending combined commit status" >&2
+  exit 1
+}
+
+echo "verified desktop candidate $PR_HEAD_SHA at squash $MERGE_SHA"