From a7ea86cdcf2aa3cbb1486baabc4c9d6aea8c576c Mon Sep 17 00:00:00 2001
From: Jordan Mecom <jm@squareup.com>
Date: Wed, 5 Aug 2026 18:36:36 -0500
Subject: [PATCH 01/16] fix(desktop): enable the content security policy
 (#4614)

This change enables a Tauri content security policy that limits
executable content to the packaged application and does not allow inline
scripts.

Relay, media, asset, and Tauri IPC schemes remain available for desktop
compatibility. The policy contains the impact of a future renderer
injection; it does not itself remove an injection bug.

## Testing

- `git diff --check origin/main...codex/security-desktop-csp`
- Rebased onto `origin/main` at `5c98932`
- Full CI pending

Originating Buzz thread:
`buzz://message?channel=3928fe05-df61-4b5d-b9c7-d623b9b10ea1&id=3c6c02312f763fbe0d2bfc33a6c1a362f91d0354f3d18b039cf7a0558c1439d1`

---------

Signed-off-by: Jordan Mecom <jm@squareup.com>
Signed-off-by: Eli Foster <efoster@squareup.com>
Co-authored-by: Eli Foster <efoster@squareup.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 desktop/src-tauri/tauri.conf.json             |   2 +-
 desktop/src-tauri/tests/csp.rs                | 201 ++++++++++++++++++
 .../profile/lib/animatedAvatarCapture.ts      |   5 +-
 3 files changed, 206 insertions(+), 2 deletions(-)
 create mode 100644 desktop/src-tauri/tests/csp.rs

diff --git a/desktop/src-tauri/tauri.conf.json b/desktop/src-tauri/tauri.conf.json
index 0d4417a754..39950d5902 100644
--- a/desktop/src-tauri/tauri.conf.json
+++ b/desktop/src-tauri/tauri.conf.json
@@ -36,7 +36,7 @@
     ],
     "macOSPrivateApi": true,
     "security": {
-      "csp": null
+      "csp": "default-src 'self'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'; object-src 'none'; script-src 'self' 'wasm-unsafe-eval' https://cdn.jsdelivr.net/npm/@mediapipe/; style-src 'self' 'unsafe-inline'; font-src 'self' data:; connect-src 'self' ipc: http://ipc.localhost buzz-media: http://buzz-media.localhost https: http: wss: ws:; img-src 'self' buzz-media: http://buzz-media.localhost data: blob: https: http:; media-src 'self' buzz-media: http://buzz-media.localhost data: blob: https: http:; worker-src 'self' blob:"
     }
   },
   "plugins": {
diff --git a/desktop/src-tauri/tests/csp.rs b/desktop/src-tauri/tests/csp.rs
new file mode 100644
index 0000000000..a8cc880e41
--- /dev/null
+++ b/desktop/src-tauri/tests/csp.rs
@@ -0,0 +1,201 @@
+//! Guards on the packaged-app Content-Security-Policy in `tauri.conf.json`.
+//!
+//! The CSP is only enforced on assets Tauri itself serves, so neither
+//! `just dev` (loads the Vite `devUrl`) nor the Playwright suite (runs under
+//! `vite preview`) can catch a policy that breaks the app. These tests pin the
+//! non-obvious sources the frontend actually needs, so a future tightening
+//! fails here instead of in a signed build.
+//!
+//! Kept as an integration test so the policy can be checked without the app
+//! crate having to declare a test-only module.
+
+use std::collections::HashMap;
+
+const TAURI_CONF: &str = include_str!("../tauri.conf.json");
+
+fn csp_directives() -> HashMap<String, Vec<String>> {
+    let conf: serde_json::Value =
+        serde_json::from_str(TAURI_CONF).expect("tauri.conf.json is valid JSON");
+    let csp = conf["app"]["security"]["csp"]
+        .as_str()
+        .expect("app.security.csp is set as a policy string");
+
+    csp.split(';')
+        .filter_map(|directive| {
+            let mut parts = directive.split_whitespace();
+            let name = parts.next()?;
+            Some((name.to_owned(), parts.map(str::to_owned).collect()))
+        })
+        .collect()
+}
+
+fn sources(directive: &str) -> Vec<String> {
+    csp_directives()
+        .remove(directive)
+        .unwrap_or_else(|| panic!("csp is missing the {directive} directive"))
+}
+
+#[test]
+fn script_src_allows_wasm_instantiation() {
+    // Shiki's default engine (Oniguruma) instantiates inlined WebAssembly for
+    // every code block; MediaPipe selfie segmentation does the same. Without
+    // this token both silently degrade — highlighting drops to plain text and
+    // animated avatars keep their background.
+    assert!(sources("script-src").contains(&"'wasm-unsafe-eval'".to_owned()));
+}
+
+/// The `MEDIAPIPE_WASM_BASE` literal the frontend hands to `FilesetResolver`.
+fn mediapipe_wasm_base() -> String {
+    const CAPTURE: &str = include_str!("../../src/features/profile/lib/animatedAvatarCapture.ts");
+
+    let after = CAPTURE
+        .split_once("const MEDIAPIPE_WASM_BASE =")
+        .expect("animatedAvatarCapture.ts declares MEDIAPIPE_WASM_BASE")
+        .1;
+    let url = after
+        .split_once('"')
+        .expect("MEDIAPIPE_WASM_BASE is a double-quoted string literal")
+        .1;
+    url.split_once('"')
+        .expect("MEDIAPIPE_WASM_BASE literal is terminated")
+        .0
+        .to_owned()
+}
+
+/// The npm scope the MediaPipe loader must come from. A CSP source ending in
+/// `/` is a path *prefix* — paths can't be wildcarded — so this admits any
+/// `@mediapipe` package while excluding the rest of what jsDelivr serves.
+const MEDIAPIPE_SCOPE: &str = "https://cdn.jsdelivr.net/npm/@mediapipe/";
+
+#[test]
+fn script_src_scopes_the_mediapipe_loader() {
+    // `FilesetResolver.forVisionTasks` loads `vision_wasm[_nosimd]_internal.js`
+    // via a `<script>` tag (which of the two depends on a runtime SIMD probe),
+    // so the loader URL the frontend builds has to fall inside the allowlisted
+    // prefix — checked here rather than discovered in a signed build.
+    let allowed = sources("script-src");
+    assert!(
+        allowed.contains(&MEDIAPIPE_SCOPE.to_owned()),
+        "script-src must allow {MEDIAPIPE_SCOPE}"
+    );
+
+    let base = mediapipe_wasm_base();
+    assert!(
+        base.starts_with(MEDIAPIPE_SCOPE),
+        "MEDIAPIPE_WASM_BASE ({base}) must sit under the allowlisted {MEDIAPIPE_SCOPE}"
+    );
+}
+
+/// How many path segments a source narrows to past its origin.
+fn path_depth(source: &str) -> usize {
+    let Some((_scheme, authority)) = source.split_once("://") else {
+        return 0;
+    };
+    match authority.split_once('/') {
+        Some((_host, path)) => path.split('/').filter(|part| !part.is_empty()).count(),
+        None => 0,
+    }
+}
+
+/// Whether a `script-src` source is narrow enough to be worth allowing. CSP
+/// keywords (`'self'`, `'wasm-unsafe-eval'`) pass. A remote source must name a
+/// non-wildcard host *and* a path reaching at least a publisher scope — a bare
+/// origin, a scheme, or a registry root would put arbitrary third-party code
+/// one injected `<script>` away.
+fn is_pinned_script_source(source: &str) -> bool {
+    if source.starts_with('\'') {
+        return true;
+    }
+    !source.contains('*') && path_depth(source) >= 2
+}
+
+#[test]
+fn script_src_trusts_no_bare_origins() {
+    for source in sources("script-src") {
+        assert!(
+            is_pinned_script_source(&source),
+            "script-src must stay scoped, found broad source `{source}`"
+        );
+    }
+}
+
+#[test]
+fn pinned_script_source_rejects_broad_sources() {
+    // Guards the guard: the check above is only worth having if it fails on the
+    // shapes that reopen the allowlist.
+    for allowed in [
+        "'self'",
+        "'wasm-unsafe-eval'",
+        MEDIAPIPE_SCOPE,
+        "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.35/wasm/vision_wasm_internal.js",
+    ] {
+        assert!(is_pinned_script_source(allowed), "{allowed} should pass");
+    }
+    for rejected in [
+        "https://cdn.jsdelivr.net",
+        "https://cdn.jsdelivr.net/",
+        "https://cdn.jsdelivr.net/npm/",
+        "https://cdn.jsdelivr.net/gh/",
+        "https://*.jsdelivr.net/npm/@mediapipe/",
+        "https:",
+        "*",
+    ] {
+        assert!(
+            !is_pinned_script_source(rejected),
+            "{rejected} should be rejected"
+        );
+    }
+}
+
+#[test]
+fn media_directives_allow_the_buzz_media_scheme() {
+    // `rewriteRelayUrl` emits `buzz-media://localhost/...` until the loopback
+    // proxy port resolves, so cold-start media renders through the custom
+    // scheme (mapped to `http://buzz-media.localhost` on Windows).
+    for directive in ["img-src", "media-src", "connect-src"] {
+        let allowed = sources(directive);
+        assert!(
+            allowed.contains(&"buzz-media:".to_owned()),
+            "{directive} must allow buzz-media:"
+        );
+        assert!(
+            allowed.contains(&"http://buzz-media.localhost".to_owned()),
+            "{directive} must allow http://buzz-media.localhost"
+        );
+    }
+}
+
+#[test]
+fn connect_src_allows_ipc_and_cleartext_relays() {
+    // `ipc:` / `http://ipc.localhost` carry every Tauri command. Cleartext
+    // `http:`/`ws:` stay allowed because a relay URL is user-supplied and the
+    // app accepts plain `ws://` on any host (`communityStorage::normalizeRelayUrl`,
+    // the community edit form): `relayProbe` opens a browser WebSocket to it,
+    // so narrowing this to loopback would report reachable relays as dead —
+    // while the real connection, which runs through tauri-plugin-websocket in
+    // Rust, is not governed by CSP at all. Blanket `https:` is already allowed,
+    // so restricting the cleartext schemes would close no exfiltration path.
+    let allowed = sources("connect-src");
+    for source in [
+        "ipc:",
+        "http://ipc.localhost",
+        "https:",
+        "http:",
+        "wss:",
+        "ws:",
+    ] {
+        assert!(
+            allowed.contains(&source.to_owned()),
+            "connect-src must allow {source}"
+        );
+    }
+}
+
+#[test]
+fn script_src_stays_free_of_unsafe_inline_and_eval() {
+    let allowed = sources("script-src");
+    // The inline boot script in index.html is covered by Tauri's build-time
+    // sha256 hashing, so neither escape hatch is ever needed here.
+    assert!(!allowed.contains(&"'unsafe-inline'".to_owned()));
+    assert!(!allowed.contains(&"'unsafe-eval'".to_owned()));
+}
diff --git a/desktop/src/features/profile/lib/animatedAvatarCapture.ts b/desktop/src/features/profile/lib/animatedAvatarCapture.ts
index 3c906e1cbc..e812a0e65b 100644
--- a/desktop/src/features/profile/lib/animatedAvatarCapture.ts
+++ b/desktop/src/features/profile/lib/animatedAvatarCapture.ts
@@ -106,7 +106,10 @@ const PERSON_OUTLINE_OFFSETS = [
 ] as const;
 
 // Pinned to the installed @mediapipe/tasks-vision version so the wasm loader
-// always matches the JS API.
+// always matches the JS API. `script-src` in tauri.conf.json allowlists the
+// jsDelivr path prefix for the @mediapipe npm scope rather than the whole
+// origin, which also serves arbitrary npm and GitHub scripts; this URL must
+// stay under that prefix — `src-tauri/tests/csp.rs` checks that it does.
 const MEDIAPIPE_WASM_BASE =
   "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.35/wasm";
 const SELFIE_SEGMENTER_MODEL_URL =

From 4da7264d9070ae48c755819598294c9de44c6d3d Mon Sep 17 00:00:00 2001
From: Tyler <109685178+tlongwell-block@users.noreply.github.com>
Date: Wed, 5 Aug 2026 21:32:21 -0400
Subject: [PATCH 02/16] fix(acp): pace observer telemetry at 1/s with
 per-channel batch envelopes (#4917)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Problem

Observer telemetry is the noisiest client of the relay: the old pacer
(167ms spacing + 90/min rolling cap) let a busy session bill up to 6
events/second against the owner's message quota, and the rolling cap
silently *dropped* frames once exceeded.

Ruling from the rate-limiting investigation thread (channel
`826fc99b-1472-40e7-a529-6b9db8943b8c`): pace at 1/s, always emit,
minimal PR.

**Review round 1 (Max, Sami)** found the first cut wrong in three ways —
tick burst (all pending frames per tick), startup burst (`interval`
fires at t=0), and per-channel quota arithmetic. All fixed and
mutation-verified in round 1.

**Review round 2 (Sami, Max)** found two more against the round-1 head:
1. **Drain-rate collapse (Sami, blocker):** front-run-only packing meant
a frame held ONE event whenever channels interleaved — measured 275 B/s
vs 63.5 KB/s, so an ordinary 2-channel session fell minutes behind with
zero drops and no warning. Silent unbounded latency.
2. **Coalescer byte-cap bypass (Max):** chunks pending in
`ObserverChunkCoalescer` were unbounded and outside the 4 MiB cap — 500
distinct-`messageId` 50KB chunks retained ~48MB with `pending_bytes ==
0` and zero drops.

**Review round 3 (Max)** found the drop accounting undercounted merged
chunks: a coalescer entry that merged N same-`messageId` chunks counted
as **1** in `dropped_events` when evicted (50 merged 1KB chunks evicted
→ counter read 1, 49 generated events unaccounted). Fixed: accounting is
now denominated in **source (generated) observer events** end to end —
each pending entry tracks how many chunks it absorbed, eviction charges
that count, and the count survives flush into the publish FIFO.

**Review round 4 (Sami, Max)** found three more against the round-3
head:
1. **Coalescer byte undercount (both, independently):** a pending merged
entry retains its first chunk's text **twice** until flush — once inside
the serialized event skeleton and once in the extracted text accumulator
— but was charged only `serialized_len`, so true retention overshot the
4 MiB cap ~2× (measured 8.3 MB). Fixed: `push_pending` charges
`serialized_len(&event) + text.len()`.
2. **Cap regressions asserted the accumulator against itself,** which is
how the undercount hid. All three cap tests now assert on independently
**walked** retained bytes (`serialized_len` per FIFO entry +
`serialized_len + text.len()` per coalescer entry), with a secondary
`accumulator >= walked` sanity check. Reverting the fix makes them fail
at exactly 8,328,386 / 8,328,272 bytes.
3. **FIFO-arm source accounting was implemented but untested (Sami M13;
Max reproduced at `cc9333b7c` with 102/151):** the round-3 regression
only evicted a merged entry while still in the coalescer. New test
forces a merged entry (50×1KB, `source_events=50`) through flush into
the publish FIFO, then evicts it from there — mutating the FIFO eviction
to `dropped += 1` fails with the reviewers' exact numbers (102 vs 151).

**Review round 5 (Sami 9/9/9, Max 9/9/9)** — production judged
merge-safe by both; remaining items are tests only, all landed at
`63d821620`:
1. **The walker instrument was itself unverified (Sami M17–M20; Max
independently confirmed the `return 0` mutant survives):** every cap
test asks `walked_retained_bytes()` only for `<= CAP`, so a blinded
walker passes everything — and paired with a reverted `push_pending` fix
the two mutations cancel, hiding exactly the 8.3 MB overshoot it exists
to detect. New two-sided pin: the walker must SEE the first chunk's text
twice, and must agree with the accumulator EXACTLY while both stores are
non-empty. Kills M17, M18, M19, M20.
2. **Two pre-existing snapshot-clone siblings (Sami D5b/D5c;
byte-identical at merge-base `7334ad1e1` — not this PR's regression, but
the PR made the class visible):** aliasing the inner turns map leaks a
post-save turn into the snapshot; aliasing the inner tombstones map
leaks a post-save terminal that blocks a legitimate post-restore
resurrection. Two isolation tests with in-test controls — all three
inner-map clones in `saveActiveAgentTurnsForCommunity` are now pinned.

## Change

**Harness (`crates/buzz-acp`)**
- **Global pacer: AT MOST ONE relay frame per second**, regardless of
channel count or backlog size. `interval_at(now + 1s)` restores the
no-startup-burst property; `MissedTickBehavior::Skip` is now pinned by a
paused-time test (a stalled tick arm fires one catch-up frame, not one
per missed deadline). At 1 frame/s telemetry spends ≤60/min of the
shared 120/min quota; `OBSERVER_PUBLISH_TICK` documents the tradeoff as
the knob.
- **`ObserverPublishQueue` with gather-packing:** events wait as
byte-accounted events (FIFO). `next_frame()` packs the front event's
channel **gathered queue-wide in FIFO order** — frames never mix
channels, and each channel's events keep their FIFO order, but
cross-channel frame order MAY differ from arrival order. That is what
keeps the drain rate in **bytes per slot** (one ~64KB frame/s) instead
of front-run-length events per slot. **Null-channel events
(`agent_panic`-class) are packing barriers** nothing gathers across, so
causally-global events keep exact order against every channel.
- **One byte cap over BOTH stores:** the event FIFO and the coalescer's
pending chunk buffer count against the 4 MiB budget together; eviction
is oldest-first across both (queue front, then coalescer front —
structural age order) with accounting (warn + counter). A
high-cardinality chunk flood is bounded exactly like a plain event
flood. Coalescer entries are charged their **true** retention
(`serialized_len + text.len()` — the first chunk's text lives in both
the serialized skeleton and the extracted accumulator until flush).
- **Shutdown is not a burst bypass:** paced one-frame-per-tick drain
until empty.

**Desktop**
- `unwrapObserverBatch` expands envelopes on the live relay path and
archive-ingest seam (round 1, unchanged).
- **`activeAgentTurnsStore` watermark re-keyed per (agent, channel)**
with a dedicated null-channel bucket: the per-agent `(timestamp, seq)`
gate would silently skip a delayed channel's frames as stale under
gather-packing's intentional cross-channel reorder. Safe because every
turn-mutating path is channel-scoped by the event's own `channelId`
(endTurn's null-turnId fallback matches `turn.channelId`; resurrectTurn
keys on `event.channelId`), so per-channel serialization preserves each
guard the per-agent gate provided. The tombstone-cap justification is
rewritten for the new keying (worst case for an evicted tombstone is a
ghost badge the prune reaps — bounded cosmetic staleness, not
corruption). Community-switch save/restore deep-clones the nested map.
Other per-agent maps stay agent-keyed: the clock offset is a running
minimum (order-insensitive); turns/tombstones mutate only through
channel-scoped paths.

## Version skew — old desktop + new harness

Gather-packing *intentionally* emits cross-channel-reordered frames. An
**old desktop** (per-agent watermark) against a **new harness** will
silently skip a delayed channel's turn-state events as stale — working
badges on that channel can go stale/missing until its next fresh event.
Transcript and archive are unaffected (the transcript store sorts +
rebuilds on out-of-order arrival; the archive is per-channel by
construction). Ship desktop and harness together; skew degrades badges
only, not data at rest.

## Throughput ceiling — "lossless" is qualified

Sustained lossless rate is what fits in one ~64KB frame per second, now
genuinely in bytes under interleaving:

| event payload | events per frame | sustained ceiling |
|---|---|---|
| 100 B | 250 | 250 ev/s |
| 500 B | 99 | 99 ev/s |
| 2 KB | 30 | 30 ev/s |
| 10 KB | 6 | 6 ev/s |

With C channels producing concurrently, publish slots round-robin
between them: per-channel drain is ~64KB/C per second and the 4 MiB
burst budget (~64s single-channel) shortens accordingly. Beyond budget,
oldest-first drops **with accounting** — visible, designed loss.

**Accounting semantics:** `dropped_events` counts SOURCE (generated)
observer events, not retained entries — evicting a coalesced entry that
merged N chunks charges N. On the published side, a merged entry ships
all N sources' text in ONE event, so the reconciliation invariant is
`ingested == dropped_events + Σ source_events over published events`
(for unmerged events, source_events = 1).

## Verification

At `63d821620d3513505e8766ac691a8002f9d4a96f` (this head; `git rev-parse
HEAD` matched in the same shell as every run), rustc 1.95.0:
- `cargo test -p buzz-acp`: **689 lib + 9 integration, 0 failed** —
regressions: interleaved 2-channel drain packs into ≤4 frames not 200
slots; null-channel barrier; queue-wide gather with within-channel FIFO;
distinct-key 50KB chunk flood bounded by the cap with event-level
accounting (published + dropped == ingested, survivors newest);
paused-time `MissedTickBehavior::Skip` pin (verified to fail under
`Burst`: 3 frames vs 1); merged-key eviction accounts every absorbed
source chunk in BOTH arms — coalescer-side (Max's round-3 probe) and
post-flush FIFO-side (Sami M13 / Max's round-4 probe: fails 102 vs 151
under `+= 1`). All three cap tests assert on independently walked
retained bytes, not the accumulator (verified to fail without the
`+text.len()` fix: 8,328,386 / 8,328,272 vs 4 MiB); the walker itself is
pinned two-sided against the accumulator (all four blinding mutants
M17–M20 verified to fail it, including the walker+fix cancellation
pair).
- `cargo clippy -p buzz-acp --all-targets -- -D warnings` clean, `cargo
fmt --check` clean
- Desktop: `tsc --noEmit` clean; node tests **4366 passed, 0 failed** —
snapshot-clone family fully pinned: watermark aliasing (round 4), turns
aliasing and tombstone aliasing (round 5, pre-existing gaps; each mutant
verified to fail exactly its target test with an in-test control). Prior
rounds: cross-channel reorder processed, cross-channel-delayed
null-turnId `turn_error` evicts only its own channel's turn, null-bucket
replay idempotency, same-channel stale/duplicate still skipped,
watermark survives community-switch save/restore
- All pre-push hooks green at the pushed commit (branch-skew,
desktop-check, desktop-test, rust-tests, desktop-tauri-checks)

Part of the rate-limiting fix stack; independent of
`eva/rate-limit-fixes` by design (separate minimal PR per Tyler's
ruling).

---------

Signed-off-by: Eva <011987e296fd5006292d2f930b574be47c7801048d1983c46c425d3c95f0cffd@buzz.block.builderlab.xyz>
Signed-off-by: Sami <f4a42a97e594b77bdbd8ee35191c8b28a94a4cb871d96f32921558275421fb68@buzz.block.builderlab.xyz>
Co-authored-by: Eva <011987e296fd5006292d2f930b574be47c7801048d1983c46c425d3c95f0cffd@buzz.block.builderlab.xyz>
Co-authored-by: Sami <f4a42a97e594b77bdbd8ee35191c8b28a94a4cb871d96f32921558275421fb68@buzz.block.builderlab.xyz>
---
 crates/buzz-acp/src/lib.rs                    | 1290 +++++++++++++++--
 crates/buzz-acp/src/relay.rs                  |    9 +-
 .../agents/activeAgentTurnsStore.test.mjs     |  272 +++-
 .../features/agents/activeAgentTurnsStore.ts  |  105 +-
 .../ingestArchivedObserverEvents.test.mjs     |   80 +
 .../src/features/agents/observerRelayStore.ts |  134 +-
 6 files changed, 1688 insertions(+), 202 deletions(-)

diff --git a/crates/buzz-acp/src/lib.rs b/crates/buzz-acp/src/lib.rs
index 0c4e5f158c..65c9dd6203 100644
--- a/crates/buzz-acp/src/lib.rs
+++ b/crates/buzz-acp/src/lib.rs
@@ -361,50 +361,242 @@ async fn check_sibling_via_profile(
     false
 }
 
-const OBSERVER_PUBLISH_INTERVAL: Duration = Duration::from_millis(167);
-const OBSERVER_PUBLISH_LIMIT_PER_MINUTE: usize = 90;
+/// Observer frames are published at a global rate of AT MOST ONE relay frame
+/// per tick — not one per channel, and not one per drain. Everything that
+/// accumulates between ticks waits in [`ObserverPublishQueue`] as events and
+/// is packed greedily into that single frame. One update per second is smooth
+/// enough for a human watching the session viewer, and the global budget is
+/// what makes the relay cost model flat: observer frames bill the agent's
+/// `LimitType::Messages` quota (`agent_standard_messages_per_min` = 120,
+/// enforced in relay `connection.rs::enforce_ws_admission`), shared with the
+/// agent's real chat messages. At 1 frame/s telemetry spends at most 60/min —
+/// half that budget — regardless of how many channels are active. A slower
+/// tick (e.g. 2s → 30/min) would leave more quota headroom for chat at the
+/// price of doubled viewer latency; this constant is the knob.
+const OBSERVER_PUBLISH_TICK: Duration = Duration::from_secs(1);
+
+/// Byte budget for EVERYTHING retained while awaiting a publish slot: the
+/// event FIFO (serialized, post-`fit_observer_event_to_budget` bytes) PLUS
+/// the chunk coalescer's pending buffer (serialized event skeletons + raw
+/// accumulated text). Both stores count against this one cap — a
+/// high-cardinality chunk flood (many distinct coalescer keys) is bounded
+/// exactly like a plain event flood; neither buffer is a bypass around the
+/// other. Lossless-ness is bounded by this budget: each publish slot packs
+/// one ~64KB frame, gathered queue-wide for the front channel, so a single
+/// channel drains at ~64KB/s and 4 MiB buys roughly **64 seconds** of
+/// sustained over-production before the oldest items are dropped WITH
+/// accounting (a warn carrying the dropped-event count). With C channels
+/// producing concurrently the slots round-robin between them, so the
+/// per-channel drain is ~64KB/Cs and the budget shortens accordingly —
+/// still bytes-per-slot, never events-per-slot (see
+/// [`ObserverPublishQueue::next_frame`]). Beyond-budget floods therefore
+/// degrade to designed, visible loss — strictly better than the
+/// pre-batching pacer's silent 90/min drop.
+const OBSERVER_PENDING_QUEUE_MAX_BYTES: usize = 4 * 1024 * 1024;
+
+/// Observer event kind for a batch envelope wrapping multiple events.
+///
+/// The payload is `{"events": [<ObserverEvent>, ...]}` with every inner event
+/// carrying its own `seq`/`timestamp`, so consumers process inner events
+/// exactly as they would unbatched ones. Single pending events are published
+/// unwrapped, so the envelope only appears when there is something to batch.
+const OBSERVER_BATCH_KIND: &str = "batch";
 
-struct ObserverPublishPacer {
-    next_publish: tokio::time::Instant,
-    published: VecDeque<tokio::time::Instant>,
+/// Collects observer events awaiting a publish slot.
+///
+/// Chunk-type events ride the [`ObserverChunkCoalescer`]; everything else is
+/// appended in arrival order, force-flushing pending chunks first — the same
+/// ordering rule the pre-batching publisher enforced, so merged chunk text can
+/// never leapfrog a tool call that arrived mid-stream.
+///
+/// Events wait here as EVENTS, not pre-sealed frames: each publish slot packs
+/// one frame at publish time ([`Self::next_frame`]), so a backlog keeps
+/// compacting into full frames instead of freezing into a frame queue.
+///
+/// The queue is bounded by [`OBSERVER_PENDING_QUEUE_MAX_BYTES`]. When a
+/// sustained flood outruns the one-frame-per-tick drain for longer than the
+/// budget, the OLDEST events are dropped (the viewer wants recent state) with
+/// accounting: a warning carrying the dropped-event count, and
+/// `dropped_events` for tests.
+#[derive(Default)]
+struct ObserverPublishQueue {
+    coalescer: ObserverChunkCoalescer,
+    /// `(serialized_len, source_events, event)`, oldest first. Length is
+    /// captured at enqueue (post-fit) so byte accounting never re-serializes
+    /// on eviction; `source_events` is how many GENERATED observer events the
+    /// entry represents (a merged chunk carries every chunk it absorbed), so
+    /// eviction accounting stays in source units after flush.
+    events: VecDeque<(usize, u64, observer::ObserverEvent)>,
+    pending_bytes: usize,
+    /// SOURCE observer events lost to byte-budget eviction. Counted in
+    /// generated-event units, not retained entries: a coalesced entry that
+    /// merged N chunks accounts for N when evicted. A PUBLISHED merged entry
+    /// delivers all N sources' text in one event, so the invariant is
+    /// `ingested == dropped_events + Σ source_events over published events`.
+    dropped_events: u64,
 }
 
-impl ObserverPublishPacer {
-    fn new() -> Self {
-        Self {
-            // No initial burst: even the first snapshot frame waits for its slot.
-            next_publish: tokio::time::Instant::now() + OBSERVER_PUBLISH_INTERVAL,
-            published: VecDeque::with_capacity(OBSERVER_PUBLISH_LIMIT_PER_MINUTE),
+impl ObserverPublishQueue {
+    fn ingest(&mut self, event: observer::ObserverEvent) {
+        // ObserverChunkCoalescer::ingest returns immediately-publishable events
+        // (force-flushed pending chunks + non-chunk passthrough, or a pending
+        // set displaced by the 60KB pre-flush); they join the queue in the
+        // order the coalescer emitted them, each carrying the count of source
+        // events it represents.
+        for (source_events, ready) in self.coalescer.ingest(event) {
+            self.enqueue(source_events, ready);
         }
+        self.enforce_byte_budget();
     }
 
-    async fn wait(&mut self) {
-        loop {
-            let now = tokio::time::Instant::now();
-            while self
-                .published
-                .front()
-                .is_some_and(|sent| now.duration_since(*sent) >= Duration::from_secs(60))
-            {
-                self.published.pop_front();
+    fn enqueue(&mut self, source_events: u64, mut event: observer::ObserverEvent) {
+        // Pre-trim at enqueue so (a) byte accounting reflects what will ship
+        // and (b) one oversized leaf cannot force every frame it touches into
+        // whole-envelope elision downstream.
+        fit_observer_event_to_budget(&mut event);
+        let bytes = serialized_len(&event);
+        self.pending_bytes += bytes;
+        self.events.push_back((bytes, source_events, event));
+    }
+
+    /// Total bytes retained across BOTH stores — the event FIFO and the
+    /// coalescer's pending chunk buffer. The budget binds this sum; counting
+    /// only the FIFO would let a high-cardinality chunk flood (many distinct
+    /// coalescer keys, nothing ever flushing) grow unbounded outside the cap.
+    fn total_pending_bytes(&self) -> usize {
+        self.pending_bytes + self.coalescer.pending_bytes
+    }
+
+    /// Enforce [`OBSERVER_PENDING_QUEUE_MAX_BYTES`] over the total, dropping
+    /// OLDEST items first with accounting in SOURCE-event units. Global age
+    /// order across the two stores is structural: every enqueue path flushes
+    /// the coalescer first, so every pending coalescer entry is strictly newer
+    /// than every queued event — eviction is queue front, then coalescer
+    /// front. The `> 1` guard never drops the sole remaining item (any single
+    /// fitted event or pre-flush-capped chunk entry is far under the budget).
+    fn enforce_byte_budget(&mut self) {
+        let mut dropped = 0u64;
+        while self.total_pending_bytes() > OBSERVER_PENDING_QUEUE_MAX_BYTES
+            && self.events.len() + self.coalescer.pending.len() > 1
+        {
+            if let Some((bytes, source_events, _)) = self.events.pop_front() {
+                self.pending_bytes -= bytes;
+                dropped += source_events;
+            } else {
+                dropped += self.coalescer.drop_oldest().expect("guard ensures an item");
             }
+        }
+        if dropped > 0 {
+            self.dropped_events += dropped;
+            tracing::warn!(
+                dropped,
+                total_dropped = self.dropped_events,
+                pending_bytes = self.total_pending_bytes(),
+                "observer publish queue over byte budget; dropped oldest events"
+            );
+        }
+    }
 
-            let minute_slot = self.published.front().and_then(|sent| {
-                (self.published.len() >= OBSERVER_PUBLISH_LIMIT_PER_MINUTE)
-                    .then_some(*sent + Duration::from_secs(60))
-            });
-            let publish_at =
-                minute_slot.map_or(self.next_publish, |slot| slot.max(self.next_publish));
-            if publish_at > now {
-                tokio::time::sleep_until(publish_at).await;
-                continue;
-            }
+    /// True when nothing is waiting anywhere — the event queue AND the
+    /// coalescer's pending chunk buffer.
+    fn is_empty(&self) -> bool {
+        self.events.is_empty() && self.coalescer.pending.is_empty()
+    }
 
-            let published_at = tokio::time::Instant::now();
-            self.published.push_back(published_at);
-            self.next_publish = published_at + OBSERVER_PUBLISH_INTERVAL;
-            return;
+    /// Pack and remove AT MOST ONE publishable frame: the front event's
+    /// channel, gathered queue-wide in FIFO order (packed greedily until
+    /// adding the next event would push the envelope over
+    /// `OBSERVER_MAX_PLAINTEXT_LEN`). Singletons ship unwrapped.
+    ///
+    /// Two invariants bound the gather:
+    /// - A frame never mixes channels (the desktop archive indexes a frame
+    ///   under its decrypted top-level `channelId`), and events keep their
+    ///   FIFO order *within* each channel. Cross-channel frame order MAY
+    ///   differ from arrival order — the desktop tolerates that everywhere:
+    ///   the transcript store sorts + rebuilds on out-of-order arrival, the
+    ///   archive is per-channel by construction, and the turn store's
+    ///   watermark is keyed per (agent, channel).
+    /// - A NULL-channel event is a BARRIER nothing gathers across: null-scope
+    ///   events (`agent_panic`-class) can causally couple to any channel, so
+    ///   their relative order against every channel is preserved exactly.
+    ///   Null-channel events themselves ship only as their contiguous front
+    ///   run.
+    ///
+    /// Gathering queue-wide (not just the front run) is what keeps the drain
+    /// rate in BYTES per slot rather than front-run-length events per slot:
+    /// with round-robin producers (channel A, B, A, B, ...) a front-run
+    /// packer degrades to ~1 event per slot regardless of size, silently
+    /// growing latency without ever tripping the byte budget.
+    ///
+    /// Pending coalesced chunks are flushed into the queue first, so a
+    /// publish slot never leaves merged chunk text stranded behind the tick.
+    fn next_frame(&mut self) -> Option<observer::ObserverEvent> {
+        for (source_events, ready) in self.coalescer.flush() {
+            self.enqueue(source_events, ready);
         }
+        let channel = self.events.front()?.2.channel_id.clone();
+
+        let mut picked: Vec<observer::ObserverEvent> = Vec::new();
+        let mut kept: VecDeque<(usize, u64, observer::ObserverEvent)> =
+            VecDeque::with_capacity(self.events.len());
+        let mut gathering = true;
+        while let Some((bytes, source_events, event)) = self.events.pop_front() {
+            if gathering && event.channel_id == channel {
+                picked.push(event);
+                if picked.len() > 1
+                    && serialized_len(&batch_envelope(&picked)) > OBSERVER_MAX_PLAINTEXT_LEN
+                {
+                    // Frame full: the overflow event stays queued and leads
+                    // its channel's next slot.
+                    let event = picked.pop().expect("len > 1");
+                    kept.push_back((bytes, source_events, event));
+                    gathering = false;
+                } else {
+                    self.pending_bytes -= bytes;
+                }
+            } else {
+                if gathering && (channel.is_none() || event.channel_id.is_none()) {
+                    // Null-channel barrier (or, for a null-channel frame, the
+                    // end of its contiguous front run): stop gathering.
+                    gathering = false;
+                }
+                kept.push_back((bytes, source_events, event));
+            }
+        }
+        self.events = kept;
+        Some(seal_batch(picked))
+    }
+}
+
+/// A single event ships unwrapped; two or more get the batch envelope.
+fn seal_batch(mut events: Vec<observer::ObserverEvent>) -> observer::ObserverEvent {
+    if events.len() == 1 {
+        return events.pop().expect("len == 1");
+    }
+    batch_envelope(&events)
+}
+
+/// Build the batch envelope for a set of same-channel events.
+///
+/// Envelope metadata mirrors the LAST inner event — the same convention the
+/// chunk coalescer uses for merged chunks — so `(timestamp, seq)` ordering and
+/// the desktop's latest-live-session tracking see the newest state.
+fn batch_envelope(events: &[observer::ObserverEvent]) -> observer::ObserverEvent {
+    let last = events
+        .last()
+        .expect("batch envelope needs at least 1 event");
+    observer::ObserverEvent {
+        seq: last.seq,
+        timestamp: last.timestamp.clone(),
+        kind: OBSERVER_BATCH_KIND.to_string(),
+        agent_index: last.agent_index,
+        channel_id: last.channel_id.clone(),
+        session_id: last.session_id.clone(),
+        turn_id: last.turn_id.clone(),
+        started_at: last.started_at.clone(),
+        payload: serde_json::json!({
+            "events": serde_json::to_value(events).unwrap_or_default(),
+        }),
     }
 }
 
@@ -445,29 +637,26 @@ async fn run_relay_observer_publisher(
     owner_pubkey_hex: String,
     owner_pubkey: PublicKey,
 ) {
-    let mut coalescer = ObserverChunkCoalescer::default();
-    let mut pacer = ObserverPublishPacer::new();
+    let mut queue = ObserverPublishQueue::default();
     let max_snapshot_seq = snapshot.iter().map(|event| event.seq).max().unwrap_or(0);
     for event in snapshot {
-        for event in coalescer.ingest(event) {
-            publish_relay_observer_event(
-                &publisher,
-                &keys,
-                &agent_pubkey_hex,
-                &owner_pubkey_hex,
-                &owner_pubkey,
-                &mut pacer,
-                event,
-            )
-            .await;
-        }
+        queue.ingest(event);
     }
 
-    let mut flush_interval = tokio::time::interval(std::time::Duration::from_millis(500));
-    flush_interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+    // Global pacer: AT MOST ONE relay frame per tick, no matter how many
+    // channels are active or how large the backlog is. `interval_at` starts
+    // the first tick a full period out, so a pre-loaded snapshot (up to the
+    // 1,000-event replay buffer on reconnect) cannot burst at t=0 — the old
+    // pacer's explicit "no initial burst" property, restored.
+    let mut publish_tick = tokio::time::interval_at(
+        tokio::time::Instant::now() + OBSERVER_PUBLISH_TICK,
+        OBSERVER_PUBLISH_TICK,
+    );
+    publish_tick.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+    let mut closed = false;
     loop {
         tokio::select! {
-            result = rx.recv() => {
+            result = rx.recv(), if !closed => {
                 match result {
                     Ok(event) => {
                         // Skip live events already delivered via the snapshot
@@ -475,41 +664,30 @@ async fn run_relay_observer_publisher(
                         if event.seq <= max_snapshot_seq {
                             continue;
                         }
-                        for event in coalescer.ingest(event) {
-                            publish_relay_observer_event(
-                                &publisher, &keys, &agent_pubkey_hex,
-                                &owner_pubkey_hex, &owner_pubkey, &mut pacer, event,
-                            ).await;
-                        }
+                        queue.ingest(event);
                     }
                     Err(tokio::sync::broadcast::error::RecvError::Lagged(count)) => {
-                        for event in coalescer.flush() {
-                            publish_relay_observer_event(
-                                &publisher, &keys, &agent_pubkey_hex,
-                                &owner_pubkey_hex, &owner_pubkey, &mut pacer, event,
-                            ).await;
-                        }
                         tracing::warn!(dropped = count, "relay observer publisher lagged");
                     }
                     Err(tokio::sync::broadcast::error::RecvError::Closed) => {
-                        for event in coalescer.flush() {
-                            publish_relay_observer_event(
-                                &publisher, &keys, &agent_pubkey_hex,
-                                &owner_pubkey_hex, &owner_pubkey, &mut pacer, event,
-                            ).await;
-                        }
-                        break;
+                        // Producer gone: stop selecting on the receiver and let
+                        // the tick arm drain what remains — still one frame per
+                        // tick. An unpaced final drain would be a burst bypass
+                        // around everything the pacer exists to prevent.
+                        closed = true;
                     }
                 }
             }
-            _ = flush_interval.tick() => {
-                // Periodic flush ensures live streaming even during continuous chunk delivery.
-                for event in coalescer.flush() {
+            _ = publish_tick.tick() => {
+                if let Some(frame) = queue.next_frame() {
                     publish_relay_observer_event(
                         &publisher, &keys, &agent_pubkey_hex,
-                        &owner_pubkey_hex, &owner_pubkey, &mut pacer, event,
+                        &owner_pubkey_hex, &owner_pubkey, frame,
                     ).await;
                 }
+                if closed && queue.is_empty() {
+                    break;
+                }
             }
         }
     }
@@ -518,12 +696,25 @@ async fn run_relay_observer_publisher(
 #[derive(Default)]
 struct ObserverChunkCoalescer {
     pending: Vec<PendingObserverChunk>,
+    /// Approximate serialized bytes retained in `pending` (each entry's
+    /// serialized skeleton at creation plus appended chunk text). Counted
+    /// against [`OBSERVER_PENDING_QUEUE_MAX_BYTES`] by the owning
+    /// [`ObserverPublishQueue`] so this buffer can never grow outside the
+    /// queue's byte budget (a distinct-key chunk flood parks everything here
+    /// and nothing would otherwise bound it).
+    pending_bytes: usize,
 }
 
 struct PendingObserverChunk {
     key: ObserverChunkKey,
     event: observer::ObserverEvent,
     text: String,
+    /// Bytes this entry contributes to `pending_bytes`.
+    bytes: usize,
+    /// GENERATED observer events merged into this entry (1 at creation, +1
+    /// per absorbed chunk). Evicting the entry loses this many source events,
+    /// so drop accounting must charge this count, not 1.
+    source_events: u64,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -544,10 +735,13 @@ struct ObserverChunkKey {
 const OBSERVER_CHUNK_MAX_TEXT_BYTES: usize = 60_000;
 
 impl ObserverChunkCoalescer {
-    fn ingest(&mut self, event: observer::ObserverEvent) -> Vec<observer::ObserverEvent> {
+    /// Returns immediately-publishable events, each paired with the number of
+    /// SOURCE observer events it represents (merged chunks carry the count of
+    /// every chunk they absorbed; passthrough events are always 1).
+    fn ingest(&mut self, event: observer::ObserverEvent) -> Vec<(u64, observer::ObserverEvent)> {
         let Some((key, text)) = observer_chunk_key_and_text(&event) else {
             let mut events = self.flush();
-            events.push(event);
+            events.push((1, event));
             return events;
         };
 
@@ -556,25 +750,64 @@ impl ObserverChunkCoalescer {
             if pending.text.len() + text.len() >= OBSERVER_CHUNK_MAX_TEXT_BYTES {
                 let events = self.flush();
                 // Start a new pending entry with the current chunk.
-                self.pending.push(PendingObserverChunk { key, event, text });
+                self.push_pending(key, event, text);
                 return events;
             }
             pending.text.push_str(&text);
+            pending.bytes += text.len();
+            pending.source_events += 1;
+            self.pending_bytes += text.len();
             pending.event.seq = event.seq;
             pending.event.timestamp = event.timestamp;
             return Vec::new();
         }
 
-        self.pending.push(PendingObserverChunk { key, event, text });
+        self.push_pending(key, event, text);
         Vec::new()
     }
 
-    fn flush(&mut self) -> Vec<observer::ObserverEvent> {
+    fn push_pending(
+        &mut self,
+        key: ObserverChunkKey,
+        event: observer::ObserverEvent,
+        text: String,
+    ) {
+        // The entry RETAINS the first chunk's text twice until flush: once
+        // inside the serialized skeleton (`event.payload` still carries it)
+        // and once as the extracted `text` copy that appends grow. Both are
+        // real memory, so both count — charging only `serialized_len` lets a
+        // high-cardinality flood retain up to 2x the byte budget (each entry
+        // undercounts by exactly its first chunk's length).
+        let bytes = serialized_len(&event) + text.len();
+        self.pending_bytes += bytes;
+        self.pending.push(PendingObserverChunk {
+            key,
+            event,
+            text,
+            bytes,
+            source_events: 1,
+        });
+    }
+
+    /// Evict the OLDEST pending entry for byte-budget enforcement. Returns
+    /// the number of SOURCE events the entry represented (its merged chunk
+    /// count), or `None` when there is nothing to drop.
+    fn drop_oldest(&mut self) -> Option<u64> {
+        if self.pending.is_empty() {
+            return None;
+        }
+        let removed = self.pending.remove(0);
+        self.pending_bytes -= removed.bytes;
+        Some(removed.source_events)
+    }
+
+    fn flush(&mut self) -> Vec<(u64, observer::ObserverEvent)> {
+        self.pending_bytes = 0;
         self.pending
             .drain(..)
             .map(|mut pending| {
                 set_observer_chunk_text(&mut pending.event.payload, pending.text);
-                pending.event
+                (pending.source_events, pending.event)
             })
             .collect()
     }
@@ -793,10 +1026,8 @@ async fn publish_relay_observer_event(
     agent_pubkey_hex: &str,
     owner_pubkey_hex: &str,
     owner_pubkey: &PublicKey,
-    pacer: &mut ObserverPublishPacer,
     mut event: observer::ObserverEvent,
 ) {
-    pacer.wait().await;
     // Trim oversized frames to fit the plaintext cap rather than letting
     // encrypt_observer_payload reject and drop them whole (silent telemetry loss).
     fit_observer_event_to_budget(&mut event);
@@ -4939,12 +5170,21 @@ mod observer_snapshot_race_tests {
 
         // The run loop has exited, dropping the publisher; drain the forwarded
         // events until the channel closes (deterministic — no try_recv race
-        // with the test_pair forwarding task).
+        // with the test_pair forwarding task). With per-tick batching the three
+        // events arrive inside batch envelopes (or unwrapped when a drain held
+        // exactly one event); unwrap both shapes.
         let mut markers = Vec::new();
         while let Some(event) = published_rx.recv().await {
             let payload: serde_json::Value =
                 decrypt_observer_payload(&owner_keys, &event).expect("decrypt published frame");
-            markers.push(payload["payload"]["marker"].as_str().unwrap().to_string());
+            match payload["payload"]["events"].as_array() {
+                Some(inner) => markers.extend(
+                    inner
+                        .iter()
+                        .map(|e| e["payload"]["marker"].as_str().unwrap().to_string()),
+                ),
+                None => markers.push(payload["payload"]["marker"].as_str().unwrap().to_string()),
+            }
         }
         assert_eq!(
             markers,
@@ -4955,36 +5195,865 @@ mod observer_snapshot_race_tests {
 }
 
 #[cfg(test)]
-mod observer_publish_pacer_tests {
+mod observer_publish_queue_tests {
     use super::*;
 
+    fn event(seq: u64, kind: &str, channel: Option<&str>) -> observer::ObserverEvent {
+        observer::ObserverEvent {
+            seq,
+            timestamp: format!("2026-04-29T04:00:{:02}Z", seq.min(59)),
+            kind: kind.to_string(),
+            agent_index: Some(0),
+            channel_id: channel.map(ToOwned::to_owned),
+            session_id: Some("session-1".to_string()),
+            turn_id: Some("turn-1".to_string()),
+            started_at: None,
+            payload: serde_json::json!({ "seq": seq }),
+        }
+    }
+
+    fn queue_of(events: Vec<observer::ObserverEvent>) -> ObserverPublishQueue {
+        let mut queue = ObserverPublishQueue::default();
+        for event in events {
+            queue.ingest(event);
+        }
+        queue
+    }
+
+    /// Collect every frame the queue will produce, one publish slot at a time.
+    fn drain_frames(queue: &mut ObserverPublishQueue) -> Vec<observer::ObserverEvent> {
+        let mut frames = Vec::new();
+        while !queue.is_empty() {
+            frames.push(queue.next_frame().expect("queue not empty"));
+        }
+        frames
+    }
+
+    /// Inner seqs of a frame, whether it is an envelope or an unwrapped
+    /// singleton.
+    fn frame_seqs(frame: &observer::ObserverEvent) -> Vec<u64> {
+        match frame.payload.get("events").and_then(|v| v.as_array()) {
+            Some(inner) => inner.iter().map(|e| e["seq"].as_u64().unwrap()).collect(),
+            None => vec![frame.seq],
+        }
+    }
+
+    /// Retained bytes computed by WALKING the entries, independently of the
+    /// queue's own accumulator. Cap regressions must assert on this, not on
+    /// `total_pending_bytes()` — asserting the counter against itself passed
+    /// while the process retained ~2x the budget (Sami/Max round 3: each
+    /// pending coalescer entry holds the first chunk's text twice, in the
+    /// serialized skeleton AND the extracted `text` copy).
+    fn walked_retained_bytes(queue: &ObserverPublishQueue) -> usize {
+        let fifo: usize = queue
+            .events
+            .iter()
+            .map(|(_, _, event)| serialized_len(event))
+            .sum();
+        let coalescer: usize = queue
+            .coalescer
+            .pending
+            .iter()
+            .map(|pending| serialized_len(&pending.event) + pending.text.len())
+            .sum();
+        fifo + coalescer
+    }
+
+    /// The walker above is itself an instrument, and every cap test asks it
+    /// only for `<= CAP` — a blinded walker (missing an arm, or returning 0)
+    /// would satisfy all of them while hiding exactly the 2x overshoot it was
+    /// added to catch (Sami round 5, M17-M20). Pin it two-sided: it must SEE
+    /// the double retention, and it must agree with the accumulator EXACTLY
+    /// while both stores are non-empty — neither may drift.
+    #[test]
+    fn walked_retained_bytes_agrees_with_the_accumulator_exactly() {
+        fn chunk(seq: u64, message_id: &str, text: &str) -> observer::ObserverEvent {
+            let mut e = event(seq, "acp_read", Some("chan-a"));
+            e.payload = serde_json::json!({
+                "jsonrpc": "2.0",
+                "method": "session/update",
+                "params": {
+                    "sessionId": "session-1",
+                    "update": {
+                        "sessionUpdate": "agent_message_chunk",
+                        "messageId": message_id,
+                        "content": { "type": "text", "text": text },
+                    },
+                },
+            });
+            e
+        }
+
+        let text = "w".repeat(7_000);
+        let mut queue = ObserverPublishQueue::default();
+        // One pending chunk: its text lives in the serialized skeleton AND
+        // the extracted copy, so a walker blind to either arm reads short.
+        queue.ingest(chunk(1, "message-a", &text));
+        assert!(
+            walked_retained_bytes(&queue) >= 2 * text.len(),
+            "the walker must SEE the first chunk's text twice \
+             (skeleton + extracted copy), got {}",
+            walked_retained_bytes(&queue)
+        );
+
+        // Populate BOTH stores: the non-chunk event flushes message-a into
+        // the FIFO and queues itself; fresh pending keys (plus a same-key
+        // append) rebuild the coalescer side.
+        queue.ingest(event(2, "tool_call", Some("chan-a")));
+        queue.ingest(chunk(3, "message-b", &text));
+        queue.ingest(chunk(4, "message-b", &text));
+        queue.ingest(chunk(5, "message-c", &text));
+        assert!(
+            !queue.events.is_empty() && !queue.coalescer.pending.is_empty(),
+            "both arms must be non-empty for the agreement check to bind"
+        );
+        assert_eq!(
+            queue.total_pending_bytes(),
+            walked_retained_bytes(&queue),
+            "accumulator and entry-walk must agree exactly: neither may drift"
+        );
+    }
+
+    /// Two or more pending events for one channel ship as a single batch
+    /// envelope whose payload carries every inner event in arrival order.
+    #[test]
+    fn multiple_events_ship_as_one_envelope_in_order() {
+        let mut queue = queue_of(vec![
+            event(1, "turn_started", Some("chan-a")),
+            event(2, "acp_read", Some("chan-a")),
+            event(3, "acp_write", Some("chan-a")),
+        ]);
+
+        let frame = queue.next_frame().expect("one frame");
+        assert!(queue.is_empty(), "one channel, one publish slot");
+        assert_eq!(frame.kind, OBSERVER_BATCH_KIND);
+        assert_eq!(frame.seq, 3, "envelope mirrors the last inner event");
+        assert_eq!(frame_seqs(&frame), [1, 2, 3], "arrival order preserved");
+        let inner = frame.payload["events"].as_array().expect("events array");
+        assert_eq!(inner[1]["kind"], "acp_read", "inner events keep their kind");
+    }
+
+    /// A single pending event is published unwrapped — no envelope, so
+    /// consumers that predate batching still understand quiet periods.
+    #[test]
+    fn a_single_event_stays_unwrapped() {
+        let mut queue = queue_of(vec![event(7, "turn_started", Some("chan-a"))]);
+        let frame = queue.next_frame().expect("one frame");
+        assert!(queue.is_empty());
+        assert_eq!(frame.kind, "turn_started");
+        assert_eq!(frame.seq, 7);
+    }
+
+    /// An empty queue yields no frame — a tick with nothing pending must not
+    /// publish anything.
+    #[test]
+    fn empty_queue_yields_no_frame() {
+        let mut queue = ObserverPublishQueue::default();
+        assert!(queue.next_frame().is_none());
+        assert!(queue.is_empty());
+    }
+
+    /// Frames never mix channels, and each channel's events keep their FIFO
+    /// order. Gathering is QUEUE-WIDE: the front event's channel collects its
+    /// events from anywhere in the queue (that is what keeps the drain rate
+    /// in bytes per slot under interleaving), so cross-channel frame order
+    /// MAY differ from arrival order — but a null-channel event is a barrier
+    /// nothing gathers across.
+    #[test]
+    fn frames_never_mix_channels_and_gather_queue_wide() {
+        let mut queue = queue_of(vec![
+            event(1, "acp_read", Some("chan-a")),
+            event(2, "acp_write", Some("chan-a")),
+            event(3, "acp_read", Some("chan-b")),
+            event(4, "acp_read", Some("chan-a")),
+            event(5, "acp_read", None),
+        ]);
+
+        let frames = drain_frames(&mut queue);
+        assert_eq!(
+            frames.len(),
+            3,
+            "gathered: [1,2,4]@a, [3]@b, [5]@None — one frame each"
+        );
+        for frame in &frames {
+            let channels: HashSet<Option<String>> = match frame.payload.get("events") {
+                Some(serde_json::Value::Array(inner)) => inner
+                    .iter()
+                    .map(|e| e["channelId"].as_str().map(ToOwned::to_owned))
+                    .collect(),
+                _ => std::iter::once(frame.channel_id.clone()).collect(),
+            };
+            assert_eq!(channels.len(), 1, "a frame never mixes channels");
+        }
+        assert_eq!(
+            frame_seqs(&frames[0]),
+            [1, 2, 4],
+            "chan-a gathers queue-wide, FIFO within the channel"
+        );
+        assert_eq!(frames[0].channel_id.as_deref(), Some("chan-a"));
+        assert_eq!(frames[1].kind, "acp_read", "singleton stays unwrapped");
+        assert_eq!(frames[1].channel_id.as_deref(), Some("chan-b"));
+        assert_eq!(frames[2].channel_id, None);
+    }
+
+    /// A NULL-channel event is a barrier: channel events queued BEHIND it
+    /// must not gather into a frame ahead of it, so causally-global events
+    /// (`agent_panic`-class) keep their exact order against every channel.
+    /// The null event itself ships only its contiguous front run.
+    #[test]
+    fn null_channel_events_are_gather_barriers() {
+        let mut queue = queue_of(vec![
+            event(1, "acp_read", Some("chan-a")),
+            event(2, "acp_read", Some("chan-b")),
+            event(3, "agent_panic", None),
+            event(4, "acp_write", Some("chan-a")),
+        ]);
+
+        let frames = drain_frames(&mut queue);
+        let published: Vec<Vec<u64>> = frames.iter().map(frame_seqs).collect();
+        assert_eq!(
+            published,
+            [vec![1], vec![2], vec![3], vec![4]],
+            "seq 4 must not gather past the null barrier into frame 1"
+        );
+    }
+
+    /// The drain-rate regression Sami measured: with two channels strictly
+    /// alternating, a front-run packer degrades to ONE event per slot
+    /// (~275 B/s regardless of the 64KB frame budget). Queue-wide gathering
+    /// must drain an interleaved backlog in ~ceil(events / per-frame-fit)
+    /// slots per channel, not one slot per event.
+    #[test]
+    fn interleaved_channels_drain_at_bytes_per_slot_not_events_per_slot() {
+        let mut events = Vec::new();
+        for i in 0..100u64 {
+            events.push(event(2 * i + 1, "acp_read", Some("chan-a")));
+            events.push(event(2 * i + 2, "acp_read", Some("chan-b")));
+        }
+        let mut queue = queue_of(events);
+
+        let frames = drain_frames(&mut queue);
+        assert!(
+            frames.len() <= 4,
+            "200 tiny alternating events must gather into a few full frames, \
+             got {} (front-run packing would need 200 slots)",
+            frames.len()
+        );
+        for frame in &frames {
+            assert!(serialized_len(frame) <= OBSERVER_MAX_PLAINTEXT_LEN);
+        }
+        // Within each channel, FIFO order survives the gather.
+        let mut seqs_a = Vec::new();
+        let mut seqs_b = Vec::new();
+        for frame in &frames {
+            match frame.channel_id.as_deref() {
+                Some("chan-a") => seqs_a.extend(frame_seqs(frame)),
+                Some("chan-b") => seqs_b.extend(frame_seqs(frame)),
+                other => panic!("unexpected channel {other:?}"),
+            }
+        }
+        assert!(seqs_a.windows(2).all(|w| w[0] < w[1]), "chan-a FIFO");
+        assert!(seqs_b.windows(2).all(|w| w[0] < w[1]), "chan-b FIFO");
+        assert_eq!(seqs_a.len() + seqs_b.len(), 200, "nothing lost");
+    }
+
+    /// A same-channel backlog that cannot fit one 64KB frame splits across
+    /// SUCCESSIVE publish slots — never multiple frames from one slot — with
+    /// every frame under the cap and no event lost or reordered.
+    #[test]
+    fn oversized_backlogs_split_across_publish_slots_under_the_cap() {
+        let big_text = "x".repeat(30_000);
+        let mut queue = queue_of(
+            (1..=6)
+                .map(|seq| {
+                    let mut e = event(seq, "acp_read", Some("chan-a"));
+                    e.payload = serde_json::json!({ "seq": seq, "text": big_text });
+                    e
+                })
+                .collect(),
+        );
+
+        let frames = drain_frames(&mut queue);
+        assert!(
+            frames.len() > 1,
+            "six 30KB events cannot fit one 64KB frame"
+        );
+        let mut seen = Vec::new();
+        for frame in &frames {
+            assert!(
+                serialized_len(frame) <= OBSERVER_MAX_PLAINTEXT_LEN,
+                "every emitted frame must fit the plaintext cap"
+            );
+            seen.extend(frame_seqs(frame));
+        }
+        assert_eq!(
+            seen,
+            [1, 2, 3, 4, 5, 6],
+            "no event lost or reordered by splitting"
+        );
+    }
+
+    /// The queue preserves the coalescer's ordering rule: a non-chunk event
+    /// force-flushes pending chunk text ahead of itself, so merged chunks can
+    /// never leapfrog a tool call that arrived after them.
+    #[test]
+    fn non_chunk_events_flush_pending_chunks_ahead_of_themselves() {
+        fn chunk(seq: u64, text: &str) -> observer::ObserverEvent {
+            let mut e = event(seq, "acp_read", Some("chan-a"));
+            e.payload = serde_json::json!({
+                "params": { "update": {
+                    "sessionUpdate": "agent_message_chunk",
+                    "messageId": "m1",
+                    "content": { "text": text },
+                }}
+            });
+            e
+        }
+
+        let mut queue = ObserverPublishQueue::default();
+        queue.ingest(chunk(1, "hello "));
+        queue.ingest(chunk(2, "world"));
+        queue.ingest(event(3, "tool_call", Some("chan-a")));
+
+        let frame = queue.next_frame().expect("one frame");
+        assert!(queue.is_empty());
+        let inner = frame.payload["events"].as_array().expect("batch of 2");
+        assert_eq!(inner.len(), 2, "two chunks coalesce into one event");
+        assert_eq!(
+            inner[0]["payload"]["params"]["update"]["content"]["text"], "hello world",
+            "chunk text merged before the tool call"
+        );
+        assert_eq!(inner[1]["kind"], "tool_call");
+        assert!(inner[0]["seq"].as_u64() < inner[1]["seq"].as_u64());
+    }
+
+    /// Chunks still pending inside the coalescer (no non-chunk flushed them)
+    /// are picked up by the publish slot itself, not stranded.
+    #[test]
+    fn a_publish_slot_flushes_pending_coalesced_chunks() {
+        let mut e = event(1, "acp_read", Some("chan-a"));
+        e.payload = serde_json::json!({
+            "params": { "update": {
+                "sessionUpdate": "agent_message_chunk",
+                "messageId": "m1",
+                "content": { "text": "buffered" },
+            }}
+        });
+        let mut queue = ObserverPublishQueue::default();
+        queue.ingest(e);
+        assert!(!queue.is_empty(), "pending chunk counts as queued work");
+
+        let frame = queue.next_frame().expect("chunk must ship");
+        assert!(queue.is_empty());
+        assert_eq!(
+            frame.payload["params"]["update"]["content"]["text"],
+            "buffered"
+        );
+    }
+
+    /// Sami's ceiling assertion: when sustained input outruns the one-frame
+    /// drain budget for longer than the queue's byte budget, the OLDEST events
+    /// drop with accounting — never silently — and everything that survives
+    /// publishes in order with nothing else lost.
+    #[test]
+    fn over_budget_floods_drop_oldest_with_accounting() {
+        let big_text = "y".repeat(10_000);
+        let total = 500usize; // ~5MB of ~10KB events > 4MiB budget
+        let mut queue = ObserverPublishQueue::default();
+        for seq in 1..=total as u64 {
+            let mut e = event(seq, "acp_read", Some("chan-a"));
+            e.payload = serde_json::json!({ "seq": seq, "text": big_text });
+            queue.ingest(e);
+        }
+
+        assert!(
+            queue.dropped_events > 0,
+            "a 5MB backlog must overflow the 4MiB budget"
+        );
+        assert!(
+            walked_retained_bytes(&queue) <= OBSERVER_PENDING_QUEUE_MAX_BYTES,
+            "eviction must restore the byte budget (entry-walked), got {}",
+            walked_retained_bytes(&queue)
+        );
+
+        let frames = drain_frames(&mut queue);
+        let published: Vec<u64> = frames.iter().flat_map(frame_seqs).collect();
+        let expected: Vec<u64> = (queue.dropped_events + 1..=total as u64).collect();
+        assert_eq!(
+            published, expected,
+            "exactly the oldest `dropped_events` events are missing; the rest \
+             publish in order"
+        );
+        assert_eq!(
+            published.len() as u64 + queue.dropped_events,
+            total as u64,
+            "accounting: published + dropped == ingested"
+        );
+    }
+
+    /// Max's coalescer-bypass regression: a flood of chunks with DISTINCT
+    /// messageIds never flushes on its own, so every chunk sits in the
+    /// coalescer's pending buffer. TRUE retained bytes — walked from the
+    /// entries, never the queue's own accumulator — MUST respect the byte
+    /// budget with event-level drop accounting. Pre-fix this retained ~25MB
+    /// against the 4 MiB cap with `pending_bytes == 0` and zero drops; the
+    /// round-3 refinement (Sami/Max) caught the accumulator itself reading
+    /// under cap while true retention was 1.99x over.
+    #[test]
+    fn distinct_key_chunk_floods_are_bounded_by_the_byte_budget() {
+        let big_text = "z".repeat(50_000);
+        let total = 500u64; // ~25MB pending chunk text vs a 4MiB budget
+        let mut queue = ObserverPublishQueue::default();
+        for seq in 1..=total {
+            let mut e = event(seq, "acp_read", Some("chan-a"));
+            e.payload = serde_json::json!({
+                "jsonrpc": "2.0",
+                "method": "session/update",
+                "params": {
+                    "sessionId": "session-1",
+                    "update": {
+                        "sessionUpdate": "agent_message_chunk",
+                        "messageId": format!("message-{seq}"),
+                        "content": { "type": "text", "text": big_text },
+                    },
+                },
+            });
+            queue.ingest(e);
+        }
+
+        let walked = walked_retained_bytes(&queue);
+        assert!(
+            walked <= OBSERVER_PENDING_QUEUE_MAX_BYTES,
+            "TRUE retained bytes (walked from entries) must respect the cap, \
+             got {walked}"
+        );
+        assert!(
+            queue.total_pending_bytes() >= walked,
+            "the accumulator must never under-count true retention \
+             (accumulator {} < walked {walked})",
+            queue.total_pending_bytes()
+        );
+        assert!(
+            queue.dropped_events > 0,
+            "a ~25MB distinct-key chunk flood must record drops"
+        );
+        // Event-level accounting: everything that survives publishes, and
+        // survivors + dropped == ingested.
+        let frames = drain_frames(&mut queue);
+        let survived: u64 = frames.iter().map(|f| frame_seqs(f).len() as u64).sum();
+        assert_eq!(
+            survived + queue.dropped_events,
+            total,
+            "accounting: published + dropped == ingested"
+        );
+        // The survivors are the NEWEST events (drop-oldest).
+        let last_frame_seqs = frame_seqs(frames.last().expect("frames"));
+        assert_eq!(*last_frame_seqs.last().expect("seqs"), total);
+    }
+
+    /// Max's merged-chunk accounting regression: one coalescer entry can
+    /// represent MANY generated observer events (same-messageId chunks merge
+    /// in place), so evicting it must charge every merged source event to
+    /// `dropped_events`, not 1 per retained entry. Pre-fix, evicting an entry
+    /// that merged 50 chunks recorded `dropped_events == 1` and 49 generated
+    /// events vanished from the accounting.
+    #[test]
+    fn evicting_a_merged_chunk_entry_accounts_every_source_event() {
+        fn chunk(seq: u64, message_id: &str, text: &str) -> observer::ObserverEvent {
+            let mut e = event(seq, "acp_read", Some("chan-a"));
+            e.payload = serde_json::json!({
+                "jsonrpc": "2.0",
+                "method": "session/update",
+                "params": {
+                    "sessionId": "session-1",
+                    "update": {
+                        "sessionUpdate": "agent_message_chunk",
+                        "messageId": message_id,
+                        "content": { "type": "text", "text": text },
+                    },
+                },
+            });
+            e
+        }
+
+        let mut queue = ObserverPublishQueue::default();
+        // 50 × 1KB chunks under ONE messageId merge into a single pending
+        // coalescer entry — the oldest item anywhere in the queue.
+        let merged_text = "m".repeat(1_000);
+        let merged_sources = 50u64;
+        for seq in 1..=merged_sources {
+            queue.ingest(chunk(seq, "message-merged", &merged_text));
+        }
+        // Flood with distinct-key 50KB chunks until the byte budget evicts
+        // the oldest entries — the merged entry goes first.
+        let flood_text = "f".repeat(50_000);
+        let flood = 100u64;
+        for seq in 1..=flood {
+            queue.ingest(chunk(
+                merged_sources + seq,
+                &format!("message-{seq}"),
+                &flood_text,
+            ));
+        }
+
+        assert!(
+            walked_retained_bytes(&queue) <= OBSERVER_PENDING_QUEUE_MAX_BYTES,
+            "eviction must restore the byte budget (entry-walked), got {}",
+            walked_retained_bytes(&queue)
+        );
+        let frames = drain_frames(&mut queue);
+        assert!(
+            !frames
+                .iter()
+                .flat_map(frame_seqs)
+                .any(|seq| seq <= merged_sources),
+            "the merged entry (globally oldest) must have been evicted"
+        );
+        // Every survivor is an unmerged distinct-key chunk (1 source each),
+        // so source-event accounting must close exactly: the merged entry's
+        // eviction charges all 50 sources.
+        let survived: u64 = frames.iter().map(|f| frame_seqs(f).len() as u64).sum();
+        assert_eq!(
+            survived + queue.dropped_events,
+            merged_sources + flood,
+            "accounting: published sources + dropped sources == ingested"
+        );
+    }
+
+    /// Sami's M13 / Max's forced-flush probe: the OTHER eviction arm. A
+    /// merged entry FLUSHED into the publish FIFO (by a non-chunk event) must
+    /// still charge every absorbed source on eviction — the FIFO stores the
+    /// per-entry count precisely so the ledger survives flush. The
+    /// coalescer-side regression above never exercises this arm; mutating the
+    /// FIFO eviction to `dropped += 1` survived all 687 tests until this one.
+    #[test]
+    fn evicting_a_flushed_merged_entry_from_the_fifo_accounts_every_source_event() {
+        fn chunk(seq: u64, message_id: &str, text: &str) -> observer::ObserverEvent {
+            let mut e = event(seq, "acp_read", Some("chan-a"));
+            e.payload = serde_json::json!({
+                "jsonrpc": "2.0",
+                "method": "session/update",
+                "params": {
+                    "sessionId": "session-1",
+                    "update": {
+                        "sessionUpdate": "agent_message_chunk",
+                        "messageId": message_id,
+                        "content": { "type": "text", "text": text },
+                    },
+                },
+            });
+            e
+        }
+
+        let mut queue = ObserverPublishQueue::default();
+        // 50 × 1KB chunks merge under one messageId in the coalescer…
+        let merged_text = "m".repeat(1_000);
+        let merged_sources = 50u64;
+        for seq in 1..=merged_sources {
+            queue.ingest(chunk(seq, "message-merged", &merged_text));
+        }
+        // …then a non-chunk event force-flushes the merged entry into the
+        // publish FIFO. From here eviction happens on the FIFO arm.
+        queue.ingest(event(merged_sources + 1, "tool_call", Some("chan-a")));
+        assert!(
+            queue.coalescer.pending.is_empty(),
+            "the non-chunk event must have flushed the merged entry"
+        );
+        assert_eq!(
+            queue.events.front().expect("flushed entry queued").1,
+            merged_sources,
+            "the FIFO front must carry the merged source count"
+        );
+
+        // Distinct-key flood forces byte-budget eviction of the FIFO front.
+        let flood_text = "f".repeat(50_000);
+        let flood = 100u64;
+        for seq in 1..=flood {
+            queue.ingest(chunk(
+                merged_sources + 1 + seq,
+                &format!("message-{seq}"),
+                &flood_text,
+            ));
+        }
+
+        assert!(
+            walked_retained_bytes(&queue) <= OBSERVER_PENDING_QUEUE_MAX_BYTES,
+            "eviction must restore the byte budget (entry-walked), got {}",
+            walked_retained_bytes(&queue)
+        );
+        let frames = drain_frames(&mut queue);
+        assert!(
+            !frames
+                .iter()
+                .flat_map(frame_seqs)
+                .any(|seq| seq <= merged_sources),
+            "the flushed merged entry (globally oldest) must have been evicted"
+        );
+        // Ledger in source units: survivors are unmerged (1 source each), the
+        // evicted merged FIFO entry must charge all 50 sources.
+        let survived: u64 = frames.iter().map(|f| frame_seqs(f).len() as u64).sum();
+        let ingested = merged_sources + 1 + flood;
+        assert_eq!(
+            survived + queue.dropped_events,
+            ingested,
+            "accounting: published sources + dropped sources == ingested"
+        );
+    }
+
+    /// Under the byte budget the queue is lossless: every ingested event
+    /// publishes exactly once.
+    #[test]
+    fn under_budget_backlogs_are_lossless() {
+        let mut queue = queue_of(
+            (1..=200)
+                .map(|seq| event(seq, "acp_read", Some("chan-a")))
+                .collect(),
+        );
+        let frames = drain_frames(&mut queue);
+        let published: Vec<u64> = frames.iter().flat_map(frame_seqs).collect();
+        assert_eq!(published, (1..=200).collect::<Vec<u64>>());
+        assert_eq!(queue.dropped_events, 0);
+    }
+}
+
+#[cfg(test)]
+mod observer_publish_cadence_tests {
+    use super::*;
+    use nostr::Keys;
+
+    /// Let every spawned task (publisher loop, test_pair forwarder) run to
+    /// quiescence WITHOUT advancing paused time. `yield_now` keeps this task
+    /// runnable, so tokio's auto-advance never fires here — time only moves
+    /// when the test says so.
+    async fn settle() {
+        for _ in 0..64 {
+            tokio::task::yield_now().await;
+        }
+    }
+
+    fn recv_all(rx: &mut tokio::sync::mpsc::Receiver<nostr::Event>) -> Vec<nostr::Event> {
+        let mut out = Vec::new();
+        while let Ok(event) = rx.try_recv() {
+            out.push(event);
+        }
+        out
+    }
+
+    fn count_inner(owner: &Keys, event: &nostr::Event) -> usize {
+        let payload: serde_json::Value =
+            decrypt_observer_payload(owner, event).expect("decrypt frame");
+        match payload["payload"]["events"].as_array() {
+            Some(inner) => inner.len(),
+            None => 1,
+        }
+    }
+
+    fn emit_on(observer: &observer::ObserverHandle, channel: Option<uuid::Uuid>, marker: &str) {
+        observer.emit(
+            "test_event",
+            None,
+            &observer::context_for(channel, None, None),
+            serde_json::json!({ "marker": marker }),
+        );
+    }
+
+    /// THE regression Max demanded: with a backlog needing multiple frames
+    /// (two channels — a frame never mixes channels, so the backlog takes two
+    /// publish slots), no frame publishes before its tick. Startup publishes
+    /// NOTHING at t=0 (Sami's Finding 1: a full replay buffer must not burst
+    /// on reconnect), frame 1 arrives at +1s, frame 2 no earlier than +2s.
     #[tokio::test(start_paused = true)]
-    async fn starts_without_a_burst_and_spaces_frames() {
-        let started = tokio::time::Instant::now();
-        let mut pacer = ObserverPublishPacer::new();
+    async fn one_frame_per_second_and_no_startup_burst() {
+        let observer = observer::ObserverHandle::in_process();
+        let agent_keys = Keys::generate();
+        let owner_keys = Keys::generate();
+        let (publisher, mut published_rx) = RelayEventPublisher::test_pair();
+
+        // Interleave channels so the backlog cannot fit one frame: each run
+        // boundary forces a new publish slot.
+        let chan_a = uuid::Uuid::new_v4();
+        let chan_b = uuid::Uuid::new_v4();
+        emit_on(&observer, Some(chan_a), "a1");
+        emit_on(&observer, Some(chan_b), "b1");
+        emit_on(&observer, Some(chan_a), "a2");
+
+        let rx = observer.subscribe();
+        let snapshot = observer.snapshot();
+        assert_eq!(snapshot.len(), 3, "all three preloaded in the snapshot");
+
+        let task = tokio::spawn(run_relay_observer_publisher(
+            snapshot,
+            rx,
+            publisher,
+            agent_keys.clone(),
+            agent_keys.public_key().to_hex(),
+            owner_keys.public_key().to_hex(),
+            owner_keys.public_key(),
+        ));
+
+        // t=0: nothing may publish, no matter how full the snapshot was.
+        settle().await;
+        assert_eq!(
+            recv_all(&mut published_rx).len(),
+            0,
+            "startup must not burst at t=0"
+        );
 
-        pacer.wait().await;
-        let first = tokio::time::Instant::now();
-        pacer.wait().await;
-        let second = tokio::time::Instant::now();
+        // t=0.999s: still nothing.
+        tokio::time::advance(Duration::from_millis(999)).await;
+        settle().await;
+        assert_eq!(
+            recv_all(&mut published_rx).len(),
+            0,
+            "no frame may publish before the first tick"
+        );
 
-        assert_eq!(first.duration_since(started), OBSERVER_PUBLISH_INTERVAL);
-        assert_eq!(second.duration_since(first), OBSERVER_PUBLISH_INTERVAL);
+        // t=1s: exactly ONE frame — chan-a gathered queue-wide, so a1 AND a2
+        // ride the first slot together.
+        tokio::time::advance(Duration::from_millis(1)).await;
+        settle().await;
+        let frames = recv_all(&mut published_rx);
+        assert_eq!(frames.len(), 1, "tick 1 publishes exactly one frame");
+        assert_eq!(count_inner(&owner_keys, &frames[0]), 2, "a1 + a2 gathered");
+
+        // t=1.5s: between ticks, nothing.
+        tokio::time::advance(Duration::from_millis(500)).await;
+        settle().await;
+        assert_eq!(
+            recv_all(&mut published_rx).len(),
+            0,
+            "frame 2 must wait for tick 2"
+        );
+
+        // t=2s: the chan-b frame drains on its own tick.
+        tokio::time::advance(Duration::from_millis(500)).await;
+        settle().await;
+        assert_eq!(recv_all(&mut published_rx).len(), 1, "tick 2: one frame");
+
+        // Backlog drained; a quiet tick publishes nothing.
+        tokio::time::advance(Duration::from_secs(1)).await;
+        settle().await;
+        assert_eq!(recv_all(&mut published_rx).len(), 0, "quiet tick is quiet");
+
+        task.abort();
     }
 
+    /// Shutdown is NOT a burst bypass: when the producer closes with a
+    /// backlog, the remaining frames still publish one per tick, and the loop
+    /// exits only after the queue is empty — paced, lossless, in order.
     #[tokio::test(start_paused = true)]
-    async fn limits_frames_in_each_rolling_minute() {
-        let mut pacer = ObserverPublishPacer::new();
-        pacer.wait().await;
-        let first = tokio::time::Instant::now();
-        for _ in 1..OBSERVER_PUBLISH_LIMIT_PER_MINUTE {
-            pacer.wait().await;
+    async fn shutdown_drain_is_paced_and_lossless() {
+        let observer = observer::ObserverHandle::in_process();
+        let agent_keys = Keys::generate();
+        let owner_keys = Keys::generate();
+        let (publisher, mut published_rx) = RelayEventPublisher::test_pair();
+
+        let chan_a = uuid::Uuid::new_v4();
+        let chan_b = uuid::Uuid::new_v4();
+        emit_on(&observer, Some(chan_a), "a1");
+        emit_on(&observer, Some(chan_b), "b1");
+        emit_on(&observer, Some(chan_a), "a2");
+
+        let rx = observer.subscribe();
+        let snapshot = observer.snapshot();
+        // Close the broadcast channel immediately: the entire drain happens
+        // in "shutdown" mode.
+        drop(observer);
+
+        let task = tokio::spawn(run_relay_observer_publisher(
+            snapshot,
+            rx,
+            publisher,
+            agent_keys.clone(),
+            agent_keys.public_key().to_hex(),
+            owner_keys.public_key().to_hex(),
+            owner_keys.public_key(),
+        ));
+
+        settle().await;
+        assert_eq!(
+            recv_all(&mut published_rx).len(),
+            0,
+            "shutdown drain must not burst at t=0"
+        );
+
+        let mut markers = Vec::new();
+        for tick in 1..=2 {
+            tokio::time::advance(Duration::from_secs(1)).await;
+            settle().await;
+            let frames = recv_all(&mut published_rx);
+            assert_eq!(frames.len(), 1, "shutdown tick {tick}: exactly one frame");
+            let payload: serde_json::Value =
+                decrypt_observer_payload(&owner_keys, &frames[0]).expect("decrypt");
+            match payload["payload"]["events"].as_array() {
+                Some(inner) => markers.extend(
+                    inner
+                        .iter()
+                        .map(|e| e["payload"]["marker"].as_str().unwrap().to_string()),
+                ),
+                None => markers.push(payload["payload"]["marker"].as_str().unwrap().to_string()),
+            }
         }
+        // Gather-packing: chan-a (a1+a2) ships tick 1, chan-b tick 2.
+        assert_eq!(markers, ["a1", "a2", "b1"], "paced drain loses nothing");
+
+        // Queue empty + closed: the loop must have exited on its own.
+        tokio::time::advance(Duration::from_secs(1)).await;
+        settle().await;
+        assert!(task.is_finished(), "publisher exits after paced drain");
+    }
+
+    /// Pins `MissedTickBehavior::Skip` (Sami's M6 mutant): when the publisher
+    /// misses ticks — relay backpressure can stall the tick arm past several
+    /// deadlines, since `publish_event` awaits a bounded mpsc — the interval
+    /// must fire ONE catch-up tick and realign, not fire once per missed
+    /// deadline. With `Burst`, a 10s stall against a multi-frame backlog
+    /// would replay all 10 missed ticks back-to-back: an unpaced burst that
+    /// bypasses exactly what the pacer exists to prevent.
+    #[tokio::test(start_paused = true)]
+    async fn missed_ticks_skip_instead_of_bursting() {
+        let observer = observer::ObserverHandle::in_process();
+        let agent_keys = Keys::generate();
+        let owner_keys = Keys::generate();
+        let (publisher, mut published_rx) = RelayEventPublisher::test_pair();
+
+        // Three channels => three frames pending (a frame never mixes
+        // channels), so a bursting interval would have work for every
+        // spurious catch-up tick.
+        for chan in 0..3 {
+            emit_on(&observer, Some(uuid::Uuid::new_v4()), &format!("c{chan}"));
+        }
+        let rx = observer.subscribe();
+        let snapshot = observer.snapshot();
+
+        let task = tokio::spawn(run_relay_observer_publisher(
+            snapshot,
+            rx,
+            publisher,
+            agent_keys.clone(),
+            agent_keys.public_key().to_hex(),
+            owner_keys.public_key().to_hex(),
+            owner_keys.public_key(),
+        ));
+        settle().await;
 
-        pacer.wait().await;
-        let ninety_first = tokio::time::Instant::now();
+        // Jump 10 seconds in ONE advance — the loop was never polled in
+        // between, exactly like a stall across 10 deadlines.
+        tokio::time::advance(Duration::from_secs(10)).await;
+        settle().await;
+        assert_eq!(
+            recv_all(&mut published_rx).len(),
+            1,
+            "Skip: one catch-up frame after a stall — Burst would publish \
+             one per missed deadline"
+        );
+
+        // The interval realigned: the remaining backlog stays paced.
+        tokio::time::advance(Duration::from_secs(1)).await;
+        settle().await;
+        assert_eq!(recv_all(&mut published_rx).len(), 1, "paced after realign");
 
-        assert_eq!(ninety_first.duration_since(first), Duration::from_secs(60));
+        task.abort();
     }
 }
 
@@ -5058,9 +6127,14 @@ mod observer_chunk_coalescer_tests {
 
         let events = coalescer.ingest(non_chunk_event(3));
         assert_eq!(events.len(), 2);
-        assert_eq!(events[0].seq, 2);
-        assert_eq!(chunk_text(&events[0]), "hello world");
-        assert_eq!(events[1].kind, "turn_started");
+        assert_eq!(events[0].1.seq, 2);
+        assert_eq!(chunk_text(&events[0].1), "hello world");
+        assert_eq!(
+            events[0].0, 2,
+            "a merged entry reports every source chunk it absorbed"
+        );
+        assert_eq!(events[1].1.kind, "turn_started");
+        assert_eq!(events[1].0, 1);
     }
 
     #[test]
@@ -5081,8 +6155,8 @@ mod observer_chunk_coalescer_tests {
 
         let events = coalescer.flush();
         assert_eq!(events.len(), 2);
-        assert_eq!(chunk_text(&events[0]), "answer");
-        assert_eq!(chunk_text(&events[1]), "thinking");
+        assert_eq!(chunk_text(&events[0].1), "answer");
+        assert_eq!(chunk_text(&events[1].1), "thinking");
     }
 }
 
diff --git a/crates/buzz-acp/src/relay.rs b/crates/buzz-acp/src/relay.rs
index aea5cee077..2cbb82411f 100644
--- a/crates/buzz-acp/src/relay.rs
+++ b/crates/buzz-acp/src/relay.rs
@@ -106,9 +106,12 @@ const REQ_PACING_INTERVAL: Duration = Duration::from_millis(125);
 /// blocked for more than one REQ's worth of I/O between drain ticks.
 const DRAIN_BUDGET_PER_ITER: usize = 1;
 /// Maximum observer telemetry frames parked while the rate-limit gate is armed
-/// (or the socket is down). The upstream pacer feeds at most ~6 frames/s, so
-/// this covers ~40 s of gating; beyond that the oldest frames are dropped with
-/// visible accounting (`gated_observer_dropped`).
+/// (or the socket is down). The upstream publisher ships at most ONE batched
+/// frame per second GLOBALLY (one publish slot per tick, regardless of how
+/// many channels are active), so this covers ~4 minutes of gating; beyond that
+/// the oldest frames are dropped with visible accounting
+/// (`gated_observer_dropped`). Note each dropped frame may carry a whole batch
+/// of events, so event-level loss is larger than the frame count.
 const GATED_OBSERVER_QUEUE_CAP: usize = 256;
 
 use std::time::Instant;
diff --git a/desktop/src/features/agents/activeAgentTurnsStore.test.mjs b/desktop/src/features/agents/activeAgentTurnsStore.test.mjs
index d78d1d21af..e3e3b3e756 100644
--- a/desktop/src/features/agents/activeAgentTurnsStore.test.mjs
+++ b/desktop/src/features/agents/activeAgentTurnsStore.test.mjs
@@ -59,30 +59,47 @@ describe("activeAgentTurnsStore", () => {
       assert.ok(channels.has("c1"));
     });
 
-    it("skips events at or below the watermark", () => {
+    it("skips events at or below their channel's watermark", () => {
+      syncAgentTurnsFromEvents(AGENT, [
+        makeEvent({ seq: 5, turnId: "t1", channelId: "c1" }),
+      ]);
+      // An older event on the SAME channel is stale — ignored.
+      syncAgentTurnsFromEvents(AGENT, [
+        makeEvent({ seq: 3, turnId: "t1b", channelId: "c1" }),
+      ]);
+      const turns = getActiveTurnsForAgent(AGENT);
+      assert.equal(turns.length, 1);
+      assert.ok(channelIdsOf(turns).has("c1"));
+    });
+
+    it("processes an older event on a DIFFERENT channel (cross-channel reorder)", () => {
+      // The harness's batching packer may publish channel frames out of
+      // arrival order; each channel gates independently.
       syncAgentTurnsFromEvents(AGENT, [
         makeEvent({ seq: 5, turnId: "t1", channelId: "c1" }),
       ]);
-      // Try to process an older event — should be ignored
       syncAgentTurnsFromEvents(AGENT, [
         makeEvent({ seq: 3, turnId: "t2", channelId: "c2" }),
       ]);
       const channels = channelIdsOf(getActiveTurnsForAgent(AGENT));
-      assert.equal(channels.size, 1);
+      assert.equal(channels.size, 2);
       assert.ok(channels.has("c1"));
-      assert.ok(!channels.has("c2"));
+      assert.ok(
+        channels.has("c2"),
+        "a delayed channel's events must not be skipped as stale",
+      );
     });
 
-    it("skips duplicate seq", () => {
+    it("skips duplicate seq on the same channel", () => {
       syncAgentTurnsFromEvents(AGENT, [
         makeEvent({ seq: 1, turnId: "t1", channelId: "c1" }),
       ]);
       syncAgentTurnsFromEvents(AGENT, [
-        makeEvent({ seq: 1, turnId: "t2", channelId: "c2" }),
+        makeEvent({ seq: 1, turnId: "t1-dup", channelId: "c1" }),
       ]);
-      const channels = channelIdsOf(getActiveTurnsForAgent(AGENT));
-      assert.equal(channels.size, 1);
-      assert.ok(channels.has("c1"));
+      const turns = getActiveTurnsForAgent(AGENT);
+      assert.equal(turns.length, 1);
+      assert.ok(channelIdsOf(turns).has("c1"));
     });
   });
 
@@ -631,6 +648,85 @@ describe("activeAgentTurnsStore", () => {
 
       assert.equal(notified, 0, "replayed evictions must not notify listeners");
     });
+
+    it("cross-channel-delayed null-turnId turn_error evicts only its own channel's turn", () => {
+      // Sami's redteam target for gather-packing: channel frames may publish
+      // out of arrival order, so an OLDER turn_error on channel B can arrive
+      // AFTER newer events on channel A. Its null-turnId fallback must evict
+      // only B's turn — never A's live one — and it must not be skipped as
+      // stale either (B's own watermark hasn't seen it).
+      syncAgentTurnsFromEvents(AGENT, [
+        // Channel A's frame arrives first, carrying the NEWER events.
+        makeEvent({
+          seq: 10,
+          turnId: "t-a",
+          channelId: "c-a",
+          timestamp: "2024-01-01T00:01:00Z",
+        }),
+      ]);
+      syncAgentTurnsFromEvents(AGENT, [
+        // Channel B's frame arrives second with OLDER events, in B's own
+        // FIFO order (the harness preserves within-channel order).
+        makeEvent({
+          seq: 1,
+          turnId: "t-b",
+          channelId: "c-b",
+          timestamp: "2024-01-01T00:00:00Z",
+        }),
+        makeEvent({
+          seq: 2,
+          kind: "turn_error",
+          turnId: null,
+          channelId: "c-b",
+          timestamp: "2024-01-01T00:00:01Z",
+        }),
+      ]);
+
+      const channels = channelIdsOf(getActiveTurnsForAgent(AGENT));
+      assert.ok(
+        channels.has("c-a"),
+        "the delayed channel's eviction must not kill the other channel's live turn",
+      );
+      assert.ok(!channels.has("c-b"), "B's own errored turn must be evicted");
+    });
+
+    it("null-channel events gate against their own per-agent bucket", () => {
+      // A null-channel agent_panic has no channel watermark; it lands in the
+      // dedicated null bucket. Replaying it must be a no-op, and it must not
+      // advance (or be gated by) any real channel's watermark.
+      const panic = makeEvent({
+        seq: 20,
+        kind: "agent_panic",
+        turnId: null,
+        channelId: null,
+        timestamp: "2024-01-01T00:02:00Z",
+      });
+      syncAgentTurnsFromEvents(AGENT, [panic]);
+
+      // An older event on a real channel still processes — the panic's newer
+      // timestamp lives in the null bucket, not the channel's.
+      syncAgentTurnsFromEvents(AGENT, [
+        makeEvent({
+          seq: 1,
+          turnId: "t1",
+          channelId: "c1",
+          timestamp: "2024-01-01T00:00:00Z",
+        }),
+      ]);
+      assert.ok(
+        channelIdsOf(getActiveTurnsForAgent(AGENT)).has("c1"),
+        "a null-channel event must not raise real channels' watermarks",
+      );
+
+      // Replaying the panic is gated by the null bucket: no notification.
+      let notified = 0;
+      const unsub = subscribeActiveAgentTurns(() => {
+        notified++;
+      });
+      syncAgentTurnsFromEvents(AGENT, [panic]);
+      unsub();
+      assert.equal(notified, 0, "replayed null-channel event must be a no-op");
+    });
   });
 
   describe("getActiveTurnsForAgent", () => {
@@ -1674,7 +1770,7 @@ describe("community-switch save / restore", () => {
     resetActiveAgentTurnsStore();
     restoreActiveAgentTurnsForCommunity("ws-a");
 
-    // Replaying an event at or below the watermark must be a no-op.
+    // Replaying an event at or below its channel's watermark must be a no-op.
     let notified = 0;
     const unsub = subscribeActiveAgentTurns(() => {
       notified++;
@@ -1682,18 +1778,164 @@ describe("community-switch save / restore", () => {
     syncAgentTurnsFromEvents(AGENT, [
       makeEvent({
         seq: 3,
-        turnId: "t2",
-        channelId: "c2",
+        turnId: "t1-stale",
+        channelId: "c1",
         timestamp: "2024-01-01T00:00:00Z",
       }),
     ]);
     unsub();
 
     assert.equal(notified, 0, "stale event after restore must not notify");
-    const channels = new Set(
-      getActiveTurnsForAgent(AGENT).map((s) => s.channelId),
+    const turns = getActiveTurnsForAgent(AGENT);
+    assert.equal(turns.length, 1, "stale event must not add a turn");
+  });
+
+  it("snapshot watermarks are isolated — live advances after save must not leak into the snapshot", () => {
+    // Save with the channel watermark at seq 5.
+    syncAgentTurnsFromEvents(AGENT, [
+      makeEvent({
+        seq: 5,
+        turnId: "t1",
+        channelId: "c1",
+        timestamp: "2024-01-01T00:00:00Z",
+      }),
+    ]);
+    saveActiveAgentTurnsForCommunity("ws-a");
+
+    // Keep working in the live store AFTER the save: the watermark advances
+    // to seq 10 by mutating the same inner per-agent map the snapshot cloned.
+    // If save aliased instead of deep-cloning, this leaks into the snapshot.
+    syncAgentTurnsFromEvents(AGENT, [
+      makeEvent({
+        seq: 10,
+        turnId: "t10",
+        channelId: "c1",
+        timestamp: "2024-01-01T00:00:20Z",
+      }),
+    ]);
+
+    resetActiveAgentTurnsStore();
+    restoreActiveAgentTurnsForCommunity("ws-a");
+
+    // seq 7 is FRESH relative to the saved watermark (5) and must be
+    // processed — processing notifies listeners (stale events do not, per
+    // the gate). Under save-side aliasing the leaked watermark (10) wrongly
+    // skips it as stale and no notification fires.
+    let notified = 0;
+    const unsub = subscribeActiveAgentTurns(() => {
+      notified++;
+    });
+    syncAgentTurnsFromEvents(AGENT, [
+      makeEvent({
+        seq: 7,
+        turnId: "t7",
+        channelId: "c1",
+        timestamp: "2024-01-01T00:00:10Z",
+      }),
+    ]);
+    unsub();
+    assert.ok(
+      notified > 0,
+      "event fresh vs the SAVED watermark must be processed — a live " +
+        "watermark advancing after save must not leak into the snapshot",
+    );
+  });
+
+  it("snapshot turns are isolated — a turn started after save must not leak into the snapshot", () => {
+    // Save with one live turn on c1.
+    syncAgentTurnsFromEvents(AGENT, [
+      makeEvent({ seq: 1, turnId: "t1", channelId: "c1" }),
+    ]);
+    saveActiveAgentTurnsForCommunity("ws-a");
+
+    // Keep working AFTER the save: a new turn on c2 mutates the same inner
+    // per-agent turns map the snapshot cloned. If save aliased that inner
+    // map instead of deep-cloning it, t2 leaks into the snapshot.
+    syncAgentTurnsFromEvents(AGENT, [
+      makeEvent({ seq: 2, turnId: "t2", channelId: "c2" }),
+    ]);
+
+    resetActiveAgentTurnsStore();
+    restoreActiveAgentTurnsForCommunity("ws-a");
+
+    const channels = channelIdsOf(getActiveTurnsForAgent(AGENT));
+    assert.ok(channels.has("c1"), "the saved turn must restore");
+    assert.ok(
+      !channels.has("c2"),
+      "a turn started after the save must NOT appear in the restored snapshot",
+    );
+  });
+
+  it("snapshot tombstones are isolated — a terminal recorded after save must not block a legitimate post-restore resurrection", () => {
+    // Complete t1 on c1 before saving: the snapshot legitimately carries its
+    // tombstone (terminal at 00:00:10).
+    syncAgentTurnsFromEvents(AGENT, [
+      makeEvent({
+        seq: 1,
+        turnId: "t1",
+        channelId: "c1",
+        timestamp: "2024-01-01T00:00:00Z",
+      }),
+      makeEvent({
+        seq: 2,
+        kind: "turn_completed",
+        turnId: "t1",
+        channelId: "c1",
+        timestamp: "2024-01-01T00:00:10Z",
+      }),
+    ]);
+    saveActiveAgentTurnsForCommunity("ws-a");
+
+    // AFTER the save, t2 on c2 starts and completes (terminal at 00:00:30).
+    // That records a tombstone in the same inner per-agent tombstone map the
+    // snapshot cloned — if save aliased it, t2's tombstone leaks in.
+    syncAgentTurnsFromEvents(AGENT, [
+      makeEvent({
+        seq: 3,
+        turnId: "t2",
+        channelId: "c2",
+        timestamp: "2024-01-01T00:00:20Z",
+      }),
+      makeEvent({
+        seq: 4,
+        kind: "turn_completed",
+        turnId: "t2",
+        channelId: "c2",
+        timestamp: "2024-01-01T00:00:30Z",
+      }),
+    ]);
+
+    resetActiveAgentTurnsStore();
+    restoreActiveAgentTurnsForCommunity("ws-a");
+
+    // Recovered liveness frames: t1's is strictly newer than its (snapshot)
+    // terminal so it revives either way — the control. t2 has NO tombstone
+    // in a properly isolated snapshot, so its frame (00:00:25, before its
+    // live-store terminal at 00:00:30) must also revive; a leaked tombstone
+    // wrongly blocks exactly this legitimate resurrection.
+    syncAgentTurnsFromEvents(AGENT, [
+      makeEvent({
+        seq: 5,
+        kind: "turn_liveness",
+        turnId: "t1",
+        channelId: "c1",
+        timestamp: "2024-01-01T00:00:15Z",
+      }),
+      makeEvent({
+        seq: 6,
+        kind: "turn_liveness",
+        turnId: "t2",
+        channelId: "c2",
+        timestamp: "2024-01-01T00:00:25Z",
+      }),
+    ]);
+    const channels = channelIdsOf(getActiveTurnsForAgent(AGENT));
+    assert.ok(channels.has("c1"), "control: t1 revives past its own terminal");
+    assert.ok(
+      channels.has("c2"),
+      "a tombstone recorded after the save must NOT leak into the snapshot " +
+        "and block a legitimate resurrection",
     );
-    assert.ok(!channels.has("c2"), "stale event must not add a turn");
   });
 
   it("terminal tombstones are preserved — a stale liveness cannot resurrect a completed turn", () => {
diff --git a/desktop/src/features/agents/activeAgentTurnsStore.ts b/desktop/src/features/agents/activeAgentTurnsStore.ts
index 3af41ae078..15789f2c3c 100644
--- a/desktop/src/features/agents/activeAgentTurnsStore.ts
+++ b/desktop/src/features/agents/activeAgentTurnsStore.ts
@@ -29,10 +29,19 @@ const PRUNE_PAUSE_MAX_MS = 3 * 60_000;
  * Desktop default of 24 — any lower value silently evicts a live turn, dropping
  * its working badge. */
 const MAX_TURNS_PER_AGENT = 32;
-/** Cap on per-agent terminal tombstones (A's resurrection guard). Only the
- * most recently completed turns can be raced by a late liveness frame; older
- * ones are already below the watermark, so a small multiple of the live cap is
- * ample and keeps the map from growing across a long session. */
+/** Cap on per-agent terminal tombstones (A's resurrection guard). For
+ * terminals that carry the turn's channelId (turn_completed / turn_error),
+ * the (agent, channel) watermark already gates any liveness emitted before
+ * the terminal — both gate on the same channel key and within-channel order
+ * is preserved end-to-end — so those tombstones only matter briefly. The
+ * tombstones doing durable work are the ones whose creation the channel
+ * watermark does NOT witness: null-channel terminals (agent_panic gates on
+ * the null bucket) and desktop-initiated clears (`clearActiveTurnsForAgent`).
+ * Those are always the newest entries, so evicting the oldest past a small
+ * multiple of the live cap preserves them. Worst case for an evicted
+ * tombstone (a >128-completions-late liveness beating a quiet channel's
+ * watermark) is a ghost badge that the prune reaps within its normal bounds —
+ * bounded cosmetic staleness, not state corruption. */
 const MAX_TERMINAL_TOMBSTONES = MAX_TURNS_PER_AGENT * 4;
 /** Interval for pruning stale/expired turns. */
 const PRUNE_INTERVAL_MS = 5_000;
@@ -85,11 +94,36 @@ const clockOffsetByAgent = new Map<string, number>();
 const cachedTurnSummaries = new Map<string, ActiveTurnSummary[]>();
 let cachedChannelTurnSummaries: ActiveChannelTurnSummary[] | null = null;
 
-// Composite watermark per agent: the newest observer event processed, by
-// (timestamp, seq) ordering. An event is processed only if it is strictly
-// newer than this — making full-buffer replays idempotent and post-restart
-// streams (seq resets to 1, timestamp keeps climbing) handled for free.
-const lastProcessed = new Map<string, ObserverEvent>();
+// Composite watermark per (agent, channel): the newest observer event
+// processed for that channel, by (timestamp, seq) ordering. An event is
+// processed only if it is strictly newer than its channel's watermark —
+// making full-buffer replays idempotent and post-restart streams (seq resets
+// to 1, timestamp keeps climbing) handled for free.
+//
+// Keyed per channel, not per agent, because the harness's batching packer
+// preserves FIFO order only WITHIN a channel: frames for different channels
+// may publish in an order that differs from arrival order. A per-agent
+// watermark would silently skip a delayed channel's events as stale. This is
+// safe because every turn-mutating path is channel-scoped by the event's own
+// channelId (endTurn's fallback matches `turn.channelId`, resurrectTurn keys
+// on `event.channelId`), so per-channel serialization gives each channel
+// exactly the protection per-agent serialization gave the whole agent.
+//
+// Events with a null channelId (agent_panic-class) gate against a dedicated
+// per-agent bucket: the harness treats null-channel events as packing
+// barriers, so they never reorder against any channel's events.
+//
+// The other per-agent maps stay agent-keyed because they are reorder-safe:
+// `clockOffsetByAgent` is a running MINIMUM (order-insensitive by
+// construction), and `activeTurnsByAgent` / `terminalAtByAgent` are mutated
+// only through channel-scoped paths this gate serializes (see the
+// MAX_TERMINAL_TOMBSTONES doc for the tombstone-eviction analysis).
+const NULL_CHANNEL_KEY = "\u0000null-channel";
+const lastProcessed = new Map<string, Map<string, ObserverEvent>>();
+
+function watermarkChannelKey(event: ObserverEvent): string {
+  return event.channelId ?? NULL_CHANNEL_KEY;
+}
 
 // Per-agent record of when each turn terminally ended (turnId →
 // terminal-event timestamp, in agent-host clock ms). endTurn hard-deletes a
@@ -324,21 +358,36 @@ function pruneExpired() {
 function processEvent(agentPubkey: string, event: ObserverEvent) {
   const key = normalizePubkey(agentPubkey);
 
-  // Gate every event kind on the watermark uniformly: process only events
-  // strictly newer than the last one seen for this agent. With sorted buffers
-  // (the documented invariant), this makes full-buffer replays a complete
-  // no-op. Evictions must be gated too — replaying a stale turn_error/
-  // agent_panic (emitted with a null turnId) would otherwise fall back to
-  // deleting the first turn in the channel, killing the live turn. Resurrection
+  // Gate every event kind on its (agent, channel) watermark uniformly:
+  // process only events strictly newer than the last one seen for this
+  // agent+channel. With sorted buffers (the documented invariant), this makes
+  // full-buffer replays a complete no-op. Evictions must be gated too —
+  // replaying a stale turn_error/agent_panic (emitted with a null turnId)
+  // would otherwise fall back to deleting the first turn in the channel,
+  // killing the live turn; the gate is per-channel, but so is that fallback
+  // (it matches the event's own channelId), so each channel's stream is
+  // serialized against exactly the mutations it can perform. Resurrection
   // (the turn_liveness/acp case below) is gated here too: it runs only for a
-  // frame that passes the watermark, so replayed stale frames cannot revive a
-  // pruned turn, and the per-turn terminal tombstone blocks reviving a turn
-  // that already completed.
-  const last = lastProcessed.get(key);
+  // frame that passes its channel's watermark, so replayed stale frames
+  // cannot revive a pruned turn, and the per-turn terminal tombstone blocks
+  // reviving a turn that already completed.
+  //
+  // The per-agent map grows one entry per channel the agent has ever emitted
+  // on — bounded by real channel membership. Deliberately NOT capped:
+  // evicting a channel's watermark would reopen replay-processing for that
+  // channel, and a re-run stale eviction is exactly the badge-killing hazard
+  // this gate exists to prevent.
+  const channelKey = watermarkChannelKey(event);
+  let agentWatermarks = lastProcessed.get(key);
+  const last = agentWatermarks?.get(channelKey);
   if (last && compareObserverEvents(event, last) <= 0) {
     return;
   }
-  lastProcessed.set(key, event);
+  if (!agentWatermarks) {
+    agentWatermarks = new Map();
+    lastProcessed.set(key, agentWatermarks);
+  }
+  agentWatermarks.set(channelKey, event);
 
   // Refine the clock offset from every fresh event. A tighter offset shifts
   // every live anchor for this agent, so a change must reach the UI even when
@@ -630,7 +679,7 @@ export function resetActiveAgentTurnsStore() {
 type TurnsStoreSnapshot = {
   turns: Map<string, Map<string, ActiveTurn>>;
   offsets: Map<string, number>;
-  watermarks: Map<string, ObserverEvent>;
+  watermarks: Map<string, Map<string, ObserverEvent>>;
   terminals: Map<string, Map<string, number>>;
 };
 
@@ -663,9 +712,15 @@ export function saveActiveAgentTurnsForCommunity(communityId: string): void {
     turns.set(agentKey, clonedAgent);
   }
 
-  // Shallow-clone scalar maps (primitives as values).
+  // Shallow-clone the offsets map (primitives as values).
   const offsets = new Map(clockOffsetByAgent);
-  const watermarks = new Map(lastProcessed);
+
+  // Deep-clone the per-(agent, channel) watermark map: outer map + inner
+  // per-agent maps (ObserverEvent values are treated as immutable).
+  const watermarks = new Map<string, Map<string, ObserverEvent>>();
+  for (const [agentKey, channelMarks] of lastProcessed) {
+    watermarks.set(agentKey, new Map(channelMarks));
+  }
 
   // Deep-clone terminalAtByAgent: outer map + inner per-agent maps.
   const terminals = new Map<string, Map<string, number>>();
@@ -719,8 +774,8 @@ export function restoreActiveAgentTurnsForCommunity(communityId: string): void {
     clockOffsetByAgent.set(agentKey, offset);
   }
 
-  for (const [agentKey, event] of snap.watermarks) {
-    lastProcessed.set(agentKey, event);
+  for (const [agentKey, channelMarks] of snap.watermarks) {
+    lastProcessed.set(agentKey, new Map(channelMarks));
   }
 
   for (const [agentKey, tombstones] of snap.terminals) {
diff --git a/desktop/src/features/agents/ingestArchivedObserverEvents.test.mjs b/desktop/src/features/agents/ingestArchivedObserverEvents.test.mjs
index c44c2a88e0..343ce24133 100644
--- a/desktop/src/features/agents/ingestArchivedObserverEvents.test.mjs
+++ b/desktop/src/features/agents/ingestArchivedObserverEvents.test.mjs
@@ -1106,4 +1106,84 @@ describe("raw-event-level merge: stateful aggregates across live/archive boundar
     );
     assert.equal(latestMs, Date.parse(TIMESTAMP));
   });
+
+  it("test_batch_envelope_inner_events_route_by_channel_id", async () => {
+    // A kind:"batch" envelope from the 1/s observer pacer must be unwrapped on
+    // the archive-ingest seam: inner events with a channelId land in the
+    // channel-scoped archive window, inner events without one fall through to
+    // the per-agent live store — and the envelope itself is never stored.
+    _testRegisterKnownAgents(SUB_ID, [AGENT_PUBKEY]);
+    const CHANNEL = "chan-batch";
+
+    const channelInner = makeObserverEvent({
+      seq: 21,
+      timestamp: "2026-01-01T00:21:00.000Z",
+      channelId: CHANNEL,
+    });
+    const liveInner = makeObserverEvent({
+      seq: 22,
+      timestamp: "2026-01-01T00:21:01.000Z",
+      channelId: null,
+      sessionId: null,
+    });
+    // Envelope metadata mirrors the last inner event (production shape).
+    const envelope = makeObserverEvent({
+      seq: 22,
+      timestamp: "2026-01-01T00:21:01.000Z",
+      kind: "batch",
+      channelId: CHANNEL,
+      payload: { events: [channelInner, liveInner] },
+    });
+
+    await ingestArchivedObserverEvents([makeRawEvent()], makeDecrypt(envelope));
+
+    const archived = _testGetArchivedChannelEvents(AGENT_PUBKEY, CHANNEL);
+    assert.equal(
+      archived.length,
+      1,
+      "channelId inner event must land in the archive window",
+    );
+    assert.equal(archived[0].seq, 21);
+    assert.equal(archived[0].kind, "acp_write");
+
+    const snap = getAgentObserverSnapshot(AGENT_PUBKEY, true);
+    assert.equal(
+      snap.events.length,
+      1,
+      "null-channelId inner event must land in the live store",
+    );
+    assert.equal(snap.events[0].seq, 22);
+    assert.notEqual(
+      snap.events[0].kind,
+      "batch",
+      "the batch envelope itself must never be stored",
+    );
+  });
+
+  it("test_malformed_batch_envelope_degrades_to_itself", async () => {
+    // A kind:"batch" envelope with no events array (harness bug shape) must
+    // degrade to the envelope itself rather than being silently dropped, so a
+    // batching defect stays visible in the session viewer.
+    _testRegisterKnownAgents(SUB_ID, [AGENT_PUBKEY]);
+    const CHANNEL = "chan-malformed-batch";
+
+    const envelope = makeObserverEvent({
+      seq: 31,
+      timestamp: "2026-01-01T00:31:00.000Z",
+      kind: "batch",
+      channelId: CHANNEL,
+      payload: {},
+    });
+
+    await ingestArchivedObserverEvents([makeRawEvent()], makeDecrypt(envelope));
+
+    const archived = _testGetArchivedChannelEvents(AGENT_PUBKEY, CHANNEL);
+    assert.equal(
+      archived.length,
+      1,
+      "malformed envelope must be stored as itself, not dropped",
+    );
+    assert.equal(archived[0].kind, "batch");
+    assert.equal(archived[0].seq, 31);
+  });
 });
diff --git a/desktop/src/features/agents/observerRelayStore.ts b/desktop/src/features/agents/observerRelayStore.ts
index 56c69f915a..611fdd489d 100644
--- a/desktop/src/features/agents/observerRelayStore.ts
+++ b/desktop/src/features/agents/observerRelayStore.ts
@@ -338,6 +338,71 @@ export function isObserverEventAfter(
   return candidate.seq > stored.seq;
 }
 
+// Observer event kind for a batch envelope wrapping multiple events. The ACP
+// harness publishes one frame per second; everything that accumulated between
+// ticks arrives as `{ kind: "batch", payload: { events: [...] } }` with every
+// inner event carrying its own seq/timestamp. Inner events are processed
+// exactly as unbatched ones; the envelope itself is never stored.
+const OBSERVER_BATCH_KIND = "batch";
+
+// Expand a decrypted observer event into its inner events when it is a batch
+// envelope; a non-batch event passes through as a single-element array. A
+// malformed envelope (no events array) degrades to the envelope itself so a
+// harness bug cannot silently blank the session viewer.
+function unwrapObserverBatch(parsed: ObserverEvent): ObserverEvent[] {
+  if (parsed.kind !== OBSERVER_BATCH_KIND) {
+    return [parsed];
+  }
+  const payload = parsed.payload as { events?: unknown } | null;
+  const events = Array.isArray(payload?.events)
+    ? (payload.events as ObserverEvent[])
+    : null;
+  return events && events.length > 0 ? events : [parsed];
+}
+
+// Per-event processing shared by every event a live frame carries (one for a
+// plain frame, many for a batch envelope).
+function processLiveObserverEvent(agentPubkey: string, parsed: ObserverEvent) {
+  // Track the latest-live-session-id per (agent, channel) on the live path.
+  // Only set when the parsed event carries both a sessionId and channelId,
+  // so we never attribute a session to the wrong channel.
+  if (parsed.sessionId && parsed.channelId) {
+    const key = liveSessionKey(agentPubkey, parsed.channelId);
+    const stored = latestLiveSessionByAgentChannel.get(key);
+    // Advance only when this event sorts strictly AFTER the stored one via
+    // isObserverEventAfter (timestamp then seq — same ordering as
+    // compareObserverEvents). This prevents late-arriving live frames from
+    // older sessions from regressing the latest-live id, while also
+    // correctly advancing on a same-timestamp frame with a higher seq.
+    if (!stored || isObserverEventAfter(parsed, stored)) {
+      latestLiveSessionByAgentChannel.set(key, {
+        sessionId: parsed.sessionId,
+        timestamp: parsed.timestamp,
+        seq: parsed.seq,
+      });
+    }
+  }
+  appendAgentEvent(agentPubkey, parsed);
+  const managementRequest = parseAgentManagementRequest(parsed.payload);
+  if (managementRequest) {
+    for (const listener of agentManagementListeners) {
+      listener(agentPubkey, managementRequest);
+    }
+  }
+  if (parsed.kind === "session_config_captured") {
+    void putAgentSessionConfig(agentPubkey, parsed.payload);
+    onSessionConfigCaptured?.(agentPubkey);
+  } else if (parsed.kind === "control_result") {
+    dispatchControlResult(agentPubkey, parsed.payload);
+  } else if (parsed.kind === "managed_agent_runtime_lifecycle") {
+    void putManagedAgentRuntimeLifecycle(agentPubkey, parsed.payload).catch(
+      (error) => {
+        console.debug("Late/untracked lifecycle frame dropped:", error);
+      },
+    );
+  }
+}
+
 async function handleRelayObserverEvent(
   event: RelayEvent,
   activeGeneration: number,
@@ -372,43 +437,8 @@ async function handleRelayObserverEvent(
     if (activeGeneration !== generation) {
       return;
     }
-    // Track the latest-live-session-id per (agent, channel) on the live path.
-    // Only set when the parsed event carries both a sessionId and channelId,
-    // so we never attribute a session to the wrong channel.
-    if (parsed.sessionId && parsed.channelId) {
-      const key = liveSessionKey(agentPubkey, parsed.channelId);
-      const stored = latestLiveSessionByAgentChannel.get(key);
-      // Advance only when this event sorts strictly AFTER the stored one via
-      // isObserverEventAfter (timestamp then seq — same ordering as
-      // compareObserverEvents). This prevents late-arriving live frames from
-      // older sessions from regressing the latest-live id, while also
-      // correctly advancing on a same-timestamp frame with a higher seq.
-      if (!stored || isObserverEventAfter(parsed, stored)) {
-        latestLiveSessionByAgentChannel.set(key, {
-          sessionId: parsed.sessionId,
-          timestamp: parsed.timestamp,
-          seq: parsed.seq,
-        });
-      }
-    }
-    appendAgentEvent(agentPubkey, parsed);
-    const managementRequest = parseAgentManagementRequest(parsed.payload);
-    if (managementRequest) {
-      for (const listener of agentManagementListeners) {
-        listener(agentPubkey, managementRequest);
-      }
-    }
-    if (parsed.kind === "session_config_captured") {
-      void putAgentSessionConfig(agentPubkey, parsed.payload);
-      onSessionConfigCaptured?.(agentPubkey);
-    } else if (parsed.kind === "control_result") {
-      dispatchControlResult(agentPubkey, parsed.payload);
-    } else if (parsed.kind === "managed_agent_runtime_lifecycle") {
-      void putManagedAgentRuntimeLifecycle(agentPubkey, parsed.payload).catch(
-        (error) => {
-          console.debug("Late/untracked lifecycle frame dropped:", error);
-        },
-      );
+    for (const inner of unwrapObserverBatch(parsed)) {
+      processLiveObserverEvent(agentPubkey, inner);
     }
   } catch (error) {
     if (activeGeneration !== generation) {
@@ -676,20 +706,22 @@ export async function ingestArchivedObserverEvents(
     }
     try {
       const parsed = (await _decryptFn(event)) as ObserverEvent;
-      // Route archived events to the channel-scoped archive window (no cap)
-      // rather than the per-agent live-relay store (MAX_OBSERVER_EVENTS cap).
-      // Events without a channelId fall through to the live store so they
-      // remain visible in the agent's general transcript.
-      if (parsed.channelId) {
-        const added = appendArchivedChannelEvent(
-          agentPubkey,
-          parsed.channelId,
-          parsed,
-        );
-        if (added) archiveChanged = true;
-      } else {
-        // Live path already calls notifyListeners() inside appendAgentEvent.
-        appendAgentEvent(agentPubkey, parsed);
+      for (const inner of unwrapObserverBatch(parsed)) {
+        // Route archived events to the channel-scoped archive window (no cap)
+        // rather than the per-agent live-relay store (MAX_OBSERVER_EVENTS cap).
+        // Events without a channelId fall through to the live store so they
+        // remain visible in the agent's general transcript.
+        if (inner.channelId) {
+          const added = appendArchivedChannelEvent(
+            agentPubkey,
+            inner.channelId,
+            inner,
+          );
+          if (added) archiveChanged = true;
+        } else {
+          // Live path already calls notifyListeners() inside appendAgentEvent.
+          appendAgentEvent(agentPubkey, inner);
+        }
       }
     } catch {
       // Silently drop decrypt failures — same as live path error handling.

From 5677e4ca050bcfe2aef16b89f7abe326e45d0b0d Mon Sep 17 00:00:00 2001
From: Taylor Ho <taylorkmho@gmail.com>
Date: Wed, 5 Aug 2026 18:46:29 -0700
Subject: [PATCH 03/16] test(desktop): match attachment button label (#4993)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

**Category:** fix
**User Impact:** Pull requests can once again pass the Desktop smoke
test suite.
**Problem:** The inbox attachment-edit smoke test still looked for the
composer's former “Attach image” label after the shared action was
renamed to “Attach file,” causing shard 3 and the aggregate Desktop CI
job to fail on every PR.
**Solution:** Update the stale accessible-name selector to match the
current composer control while preserving the test's media-tag coverage.

<details>
<summary>File changes</summary>

**desktop/tests/e2e/inbox-edit.spec.ts**
Updates the attachment button selector to use the current accessible
label so the existing attachment-edit regression test reaches the
behavior it is meant to verify.

</details>

## Reproduction steps

1. Build the Desktop E2E application with `pnpm -C desktop build:e2e`.
2. Run `cd desktop && pnpm exec playwright test --project=smoke
tests/e2e/inbox-edit.spec.ts -g "editing an immediate attachment reply
preserves its media tags"`.
3. Confirm the test locates the “Attach file” control and passes.

Signed-off-by: Taylor Ho <taylorkmho@gmail.com>
---
 desktop/tests/e2e/inbox-edit.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/desktop/tests/e2e/inbox-edit.spec.ts b/desktop/tests/e2e/inbox-edit.spec.ts
index e78576d892..a962056fa6 100644
--- a/desktop/tests/e2e/inbox-edit.spec.ts
+++ b/desktop/tests/e2e/inbox-edit.spec.ts
@@ -230,7 +230,7 @@ test("editing an immediate attachment reply preserves its media tags", async ({
   const detail = page.getByTestId("home-inbox-detail");
   await expect(detail).toContainText("Inbox thread root.");
 
-  await detail.getByRole("button", { name: "Attach image" }).click();
+  await detail.getByRole("button", { name: "Attach file" }).click();
   await expect(detail.getByTestId("message-composer")).toContainText(
     ATTACHMENT_FILENAME,
   );

From 16cc3de6d6bb23ebdc3a928172fb585494079232 Mon Sep 17 00:00:00 2001
From: Tom Brow <tomb@block.xyz>
Date: Wed, 5 Aug 2026 18:58:24 -0700
Subject: [PATCH 04/16] fix(desktop): enforce owner-only access in internal
 builds (#4053)

## Problem

Managed agents in internal Buzz builds should answer only their owner.
Previously, an agent could keep a broader access setting and respond to
other people, which did not match the access policy for internal builds.

This PR makes owner-only access effective for every managed agent in
internal builds and makes that restriction clear in the Desktop UI. Open
source builds remain configurable.

## Changes

- Enforce owner-only access when any managed agent starts or is deployed
from an internal build.
- Show the agent access control as locked to **Only me** in Desktop,
with an explanation of why it cannot be changed.
- Keep Welcome teammates working under the same rule without triggering
unnecessary restarts.
- Leave open source build behavior unchanged. This changes effective
runtime access without rewriting stored or relay-advertised settings.

The companion [#4064](https://github.com/block/buzz/pull/4064) explains
the restriction in-thread when someone without access mentions an agent.

The enforcement will remain inactive in shipped builds until
[squareup/buzz-releases#74](https://github.com/squareup/buzz-releases/pull/74)
marks internal releases during the build.

## Screenshots

| Before | After |
| --- | --- |
| ![Editable agent access control before the
change](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/4053/4053-before.png)
| ![Agent access locked to Only me in an internal
build](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/4053/4053-after-v2.png)
|

## Tests

Added coverage for:

- Runtime enforcement for [locally run
agents](https://github.com/block/buzz/blob/e0165f52b52741a74184c9899e2b51eeec40c939/desktop/src-tauri/src/managed_agents/runtime/tests.rs#L196)
and [deployed
agents](https://github.com/block/buzz/blob/e0165f52b52741a74184c9899e2b51eeec40c939/desktop/src-tauri/src/commands/agents_tests.rs#L510).
- The [current-build deployment
path](https://github.com/block/buzz/blob/e0165f52b52741a74184c9899e2b51eeec40c939/desktop/src-tauri/src/commands/agents_tests.rs#L455),
[invalid stored
access](https://github.com/block/buzz/blob/e0165f52b52741a74184c9899e2b51eeec40c939/desktop/src-tauri/src/managed_agents/access_policy.rs#L98),
and the [local startup
guard](https://github.com/block/buzz/blob/e0165f52b52741a74184c9899e2b51eeec40c939/desktop/src-tauri/src/managed_agents/env_vars/tests.rs#L149).
- Consistent enforcement across [both agent
backends](https://github.com/block/buzz/blob/e0165f52b52741a74184c9899e2b51eeec40c939/desktop/src-tauri/src/managed_agents/access_policy.rs#L112).
- Welcome teammates created as [locally
run](https://github.com/block/buzz/blob/e0165f52b52741a74184c9899e2b51eeec40c939/desktop/src/features/onboarding/welcomeGuide.test.mjs#L384)
or
[deployed](https://github.com/block/buzz/blob/e0165f52b52741a74184c9899e2b51eeec40c939/desktop/src/features/onboarding/welcomeGuide.test.mjs#L393)
agents, including
[access-only](https://github.com/block/buzz/blob/e0165f52b52741a74184c9899e2b51eeec40c939/desktop/src/features/onboarding/welcomeKickoff.test.mjs#L202)
and
[runtime-related](https://github.com/block/buzz/blob/e0165f52b52741a74184c9899e2b51eeec40c939/desktop/src/features/onboarding/welcomeKickoff.test.mjs#L225)
restart behavior.

The full Desktop Rust and JavaScript suites, type checks, formatting,
clippy, and file-size checks passed. Playwright E2E was not run.

---

Originated from Buzz channel
[buzz-agent-control](buzz://channel?id=cf5dada7-e26a-4887-ae41-b3bd5f42d3b2).
Supersedes #2537.

---------

Signed-off-by: Tom Brow <tomb@block.xyz>
Signed-off-by: npub1tquskdu6yc4h8l7xxtceculxw600grekeq0xg2ukqfrwl7vrzg3quz3gmp <58390b379a262b73ffc632f19c73e6769ef40f36c81e642b960246eff9831222@buzz.block.builderlab.xyz>
Co-authored-by: npub1tquskdu6yc4h8l7xxtceculxw600grekeq0xg2ukqfrwl7vrzg3quz3gmp <58390b379a262b73ffc632f19c73e6769ef40f36c81e642b960246eff9831222@buzz.block.builderlab.xyz>
Co-authored-by: Amp <amp@ampcode.com>
---
 Justfile                                      |  21 +-
 desktop/src-tauri/build.rs                    |  24 +++
 .../buzz-terminal/src/env_fence_tests.rs      |   5 +-
 .../src-tauri/src/commands/agent_access.rs    |  18 ++
 desktop/src-tauri/src/commands/agents.rs      |   2 +-
 .../src/commands/agents/provider_access.rs    | 196 ++++++++++++++++++
 .../src-tauri/src/commands/agents_deploy.rs   |  16 +-
 .../src-tauri/src/commands/agents_tests.rs    | 149 +++++++++++++
 desktop/src-tauri/src/commands/mod.rs         |   2 +
 desktop/src-tauri/src/commands/workspace.rs   |   2 +
 desktop/src-tauri/src/lib.rs                  |   1 +
 .../src/managed_agents/access_policy.rs       | 190 +++++++++++++++++
 .../src-tauri/src/managed_agents/agent_env.rs |  75 +++++++
 .../src-tauri/src/managed_agents/env_vars.rs  |  92 +-------
 .../src/managed_agents/env_vars/tests.rs      |   6 +-
 desktop/src-tauri/src/managed_agents/mod.rs   |   2 +
 .../src/managed_agents/reserved_env_keys.rs   |  79 +++++++
 .../src-tauri/src/managed_agents/runtime.rs   |  50 +----
 .../managed_agents/runtime/test_fixtures.rs   |  93 +++++++++
 .../src/managed_agents/runtime/tests.rs       | 136 ++++++------
 desktop/src/features/agents/AGENTS.md         |   5 +-
 desktop/src/features/agents/hooks.ts          |   1 -
 .../agents/ui/AgentInstanceEditDialog.tsx     |  14 +-
 .../agents/ui/OwnerOnlyAccessField.tsx        |  35 ++++
 .../agents/ui/PersonaAdvancedFields.tsx       |  20 +-
 .../src/features/agents/ui/RespondToField.tsx |  22 +-
 .../agents/ui/respondToFieldContract.test.mjs |  10 +
 .../agents/useAgentAccessOwnerOnly.ts         |  25 +++
 .../channels/ui/EditRespondToDialog.tsx       |  23 +-
 .../features/onboarding/welcomeGuide.test.mjs |  73 +++++++
 .../src/features/onboarding/welcomeGuide.ts   |  84 ++++++--
 .../onboarding/welcomeKickoff.test.mjs        |  41 ++++
 .../src/features/onboarding/welcomeKickoff.ts |  22 +-
 desktop/src/shared/api/tauriAgentAccess.ts    |   4 +
 desktop/src/testing/e2eBridge.ts              |   4 +
 desktop/tests/e2e/edit-agent.spec.ts          |  75 +++++++
 desktop/tests/helpers/bridge.ts               |   1 +
 37 files changed, 1366 insertions(+), 252 deletions(-)
 create mode 100644 desktop/src-tauri/src/commands/agent_access.rs
 create mode 100644 desktop/src-tauri/src/commands/agents/provider_access.rs
 create mode 100644 desktop/src-tauri/src/managed_agents/access_policy.rs
 create mode 100644 desktop/src-tauri/src/managed_agents/reserved_env_keys.rs
 create mode 100644 desktop/src-tauri/src/managed_agents/runtime/test_fixtures.rs
 create mode 100644 desktop/src/features/agents/ui/OwnerOnlyAccessField.tsx
 create mode 100644 desktop/src/features/agents/useAgentAccessOwnerOnly.ts
 create mode 100644 desktop/src/shared/api/tauriAgentAccess.ts

diff --git a/Justfile b/Justfile
index c3d755ffeb..0a43249d5f 100644
--- a/Justfile
+++ b/Justfile
@@ -212,9 +212,10 @@ desktop-tauri-test: _ensure-sidecar-stubs
 desktop-terminal-performance-test:
     cargo test --manifest-path desktop/src-tauri/crates/buzz-terminal/Cargo.toml --release --test latency g3_renderer_acquire_stays_within_frame_budget -- --ignored --exact --nocapture
 
-# Verify compiled-flag behavior under both compile states (clean + internal).
-# Runs the auto-connect compiled-flag test twice with independently supplied
-# expected values; build.rs rerun-if-env-changed triggers recompilation.
+# Verify compiled-flag behavior under both compile states (clean + capability set).
+# Runs the auto-connect and owner-only access focused tests twice with
+# independently supplied expected values; build.rs rerun-if-env-changed
+# triggers recompilation.
 desktop-tauri-test-compiled-flags: _ensure-sidecar-stubs
     #!/usr/bin/env bash
     set -euo pipefail
@@ -223,10 +224,22 @@ desktop-tauri-test-compiled-flags: _ensure-sidecar-stubs
     env -u BUZZ_BUILD_AUTO_CONNECT_DEFAULT_RELAY \
       BUZZ_TEST_EXPECTED_AUTO_CONNECT_DEFAULT_RELAY=false \
       cargo test compiled_flag_matches_expected -- --ignored --nocapture
-    echo "=== Internal build (flag set) → expect true ==="
+    env -u BUZZ_BUILD_AGENT_ACCESS_OWNER_ONLY \
+      BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY=false \
+      cargo test --lib
+    env -u BUZZ_BUILD_AGENT_ACCESS_OWNER_ONLY \
+      BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY=false \
+      cargo test compiled_policy_matches_expected -- --ignored --nocapture
+    echo "=== Internal build (flags set) → expect true ==="
     BUZZ_BUILD_AUTO_CONNECT_DEFAULT_RELAY=1 \
       BUZZ_TEST_EXPECTED_AUTO_CONNECT_DEFAULT_RELAY=true \
       cargo test compiled_flag_matches_expected -- --ignored --nocapture
+    BUZZ_BUILD_AGENT_ACCESS_OWNER_ONLY=1 \
+      BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY=true \
+      cargo test --lib
+    BUZZ_BUILD_AGENT_ACCESS_OWNER_ONLY=1 \
+      BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY=true \
+      cargo test compiled_policy_matches_expected -- --ignored --nocapture
     echo "Both compiled states verified."
 
 # Build the full desktop Tauri app locally (unsigned, for testing)
diff --git a/desktop/src-tauri/build.rs b/desktop/src-tauri/build.rs
index 2b997af891..2cdd785c73 100644
--- a/desktop/src-tauri/build.rs
+++ b/desktop/src-tauri/build.rs
@@ -1,6 +1,9 @@
 // Shared schema, included from the same source the runtime command parses with,
 // so the build-time validation below and the runtime parse cannot drift.
 include!("src/commands/reconnect_hook_config.rs");
+// Same source of truth the runtime filters with, so a baked build env cannot
+// carry a reserved key the runtime believes it already rejected.
+include!("src/managed_agents/reserved_env_keys.rs");
 
 use base64::Engine as _;
 
@@ -13,9 +16,16 @@ fn main() {
     println!("cargo:rerun-if-env-changed=BUZZ_BUILD_BUZZ_AGENT_MODEL");
     println!("cargo:rerun-if-env-changed=BUZZ_BUILD_AGENT_ENV");
     println!("cargo:rerun-if-env-changed=BUZZ_BUILD_RELAY_RECONNECT_CMD");
+    println!("cargo:rerun-if-env-changed=BUZZ_BUILD_AGENT_ACCESS_OWNER_ONLY");
     println!("cargo:rerun-if-env-changed=BUZZ_BUILD_AUTO_CONNECT_DEFAULT_RELAY");
     println!("cargo:rustc-check-cfg=cfg(buzz_updater_enabled)");
 
+    // Explicit owner-only agent-access capability. Release packaging sets this
+    // presence-only marker; OSS/custom builds leave agent access configurable.
+    if std::env::var("BUZZ_BUILD_AGENT_ACCESS_OWNER_ONLY").is_ok() {
+        println!("cargo:rustc-env=BUZZ_DESKTOP_BUILD_AGENT_ACCESS_OWNER_ONLY=1");
+    }
+
     if let Ok(relay_url) = std::env::var("BUZZ_RELAY_URL") {
         println!("cargo:rustc-env=BUZZ_DESKTOP_BUILD_RELAY_URL={relay_url}");
     }
@@ -59,6 +69,20 @@ fn main() {
                     line
                 );
             }
+            // The baked env is written into every spawned agent's environment
+            // LAST (see `managed_agents/runtime.rs`), after Buzz sets the
+            // access gates and identity vars. A baked reserved key would
+            // therefore silently override the gate the UI promises, so reject
+            // it at build time instead of shipping a binary that bypasses its
+            // own enforcement.
+            if is_reserved_env_key(key) {
+                panic!(
+                    "BUZZ_BUILD_AGENT_ENV line {}: `{}` is reserved by Buzz and cannot be baked \
+                     into a build (it would override Buzz's own identity/access env)",
+                    line_no + 1,
+                    key
+                );
+            }
         }
         let encoded = base64::engine::general_purpose::STANDARD.encode(raw.as_bytes());
         println!("cargo:rustc-env=BUZZ_DESKTOP_BUILD_AGENT_ENV={encoded}");
diff --git a/desktop/src-tauri/crates/buzz-terminal/src/env_fence_tests.rs b/desktop/src-tauri/crates/buzz-terminal/src/env_fence_tests.rs
index 6d99337c4b..59e94a1f63 100644
--- a/desktop/src-tauri/crates/buzz-terminal/src/env_fence_tests.rs
+++ b/desktop/src-tauri/crates/buzz-terminal/src/env_fence_tests.rs
@@ -330,7 +330,10 @@ fn child_shell_is_the_resolved_shell_not_the_inherited_one() {
 /// grows a new secret, this points at the file to update.
 #[test]
 fn reserved_keys_are_covered() {
-    let source = include_str!("../../../src/managed_agents/env_vars.rs");
+    // The list lives in its own file because `build.rs` `include!`s the same
+    // source (see `managed_agents/reserved_env_keys.rs`); read it there rather
+    // than through the module that includes it.
+    let source = include_str!("../../../src/managed_agents/reserved_env_keys.rs");
     let declared: Vec<&str> = source
         .lines()
         .skip_while(|line| !line.contains("RESERVED_ENV_KEYS"))
diff --git a/desktop/src-tauri/src/commands/agent_access.rs b/desktop/src-tauri/src/commands/agent_access.rs
new file mode 100644
index 0000000000..ef118e82b2
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_access.rs
@@ -0,0 +1,18 @@
+/// Return whether this build enforces owner-only managed-agent access.
+#[tauri::command]
+pub fn agent_access_owner_only() -> bool {
+    crate::managed_agents::owner_only_access_build()
+}
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    #[ignore = "requires BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY"]
+    fn compiled_policy_matches_expected() {
+        let expected = std::env::var("BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY")
+            .expect("BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY must be set")
+            .parse::<bool>()
+            .expect("BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY must be true or false");
+        assert_eq!(super::agent_access_owner_only(), expected);
+    }
+}
diff --git a/desktop/src-tauri/src/commands/agents.rs b/desktop/src-tauri/src/commands/agents.rs
index e17a90cac3..dd61fc9398 100644
--- a/desktop/src-tauri/src/commands/agents.rs
+++ b/desktop/src-tauri/src/commands/agents.rs
@@ -1355,9 +1355,9 @@ pub async fn delete_managed_agent(
 // 2. Harness sees it, exits gracefully, sets presence to "offline"
 // 3. Desktop's existing presence polling sees "offline" — UI updates automatically
 // No backend Tauri command needed. Presence IS the status.
-
 #[path = "agents_deploy.rs"]
 mod deploy;
+pub(super) mod provider_access;
 use deploy::build_deploy_payload;
 #[cfg(test)]
 use deploy::{deploy_payload_json, DeployProjections};
diff --git a/desktop/src-tauri/src/commands/agents/provider_access.rs b/desktop/src-tauri/src/commands/agents/provider_access.rs
new file mode 100644
index 0000000000..467230e56f
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agents/provider_access.rs
@@ -0,0 +1,196 @@
+//! Upgrade reconciliation for provider-backed managed-agent access.
+
+use tauri::AppHandle;
+
+use crate::{
+    app_state::AppState,
+    managed_agents::{
+        find_managed_agent_mut, load_managed_agents, save_managed_agents, BackendKind,
+        ManagedAgentRecord,
+    },
+    util::now_iso,
+};
+
+pub(super) fn needs_reconciliation_with_policy(
+    record: &ManagedAgentRecord,
+    owner_only_access: bool,
+) -> bool {
+    owner_only_access && record.backend != BackendKind::Local && record.backend_agent_id.is_some()
+}
+
+#[derive(Debug)]
+struct ProviderAccessTarget {
+    pubkey: String,
+    provider_id: String,
+    config: serde_json::Value,
+    cached_binary_path: Option<String>,
+    agent_json: Result<serde_json::Value, String>,
+}
+
+fn collect_targets_with(
+    records: Vec<ManagedAgentRecord>,
+    owner_only_access: bool,
+    mut build_payload: impl FnMut(&ManagedAgentRecord) -> Result<serde_json::Value, String>,
+) -> Vec<ProviderAccessTarget> {
+    records
+        .into_iter()
+        .filter(|record| needs_reconciliation_with_policy(record, owner_only_access))
+        .map(|record| match record.backend.clone() {
+            BackendKind::Provider { id, config } => ProviderAccessTarget {
+                agent_json: build_payload(&record),
+                pubkey: record.pubkey,
+                provider_id: id,
+                config,
+                cached_binary_path: record.provider_binary_path,
+            },
+            BackendKind::Local => {
+                unreachable!("provider access reconciliation selected a local agent")
+            }
+        })
+        .collect()
+}
+
+/// Redeploy every existing provider agent in an owner-only access build.
+///
+/// The saved `backend_agent_id` only proves that some provider deployment
+/// exists. A marked build sends the current owner-only payload before each
+/// community UI load. Workspace apply fails closed if any provider rejects it.
+pub(crate) async fn reconcile_on_workspace_apply(
+    app: &AppHandle,
+    state: &AppState,
+) -> Result<(), String> {
+    if !crate::managed_agents::owner_only_access_build() {
+        return Ok(());
+    }
+
+    let targets = {
+        let _store_guard = state
+            .managed_agents_store_lock
+            .lock()
+            .map_err(|error| error.to_string())?;
+        collect_targets_with(load_managed_agents(app)?, true, |record| {
+            super::build_deploy_payload(app, state, record)
+        })
+    };
+
+    for target in targets {
+        let ProviderAccessTarget {
+            pubkey,
+            provider_id,
+            config,
+            cached_binary_path,
+            agent_json,
+        } = target;
+        let agent_json = match agent_json {
+            Ok(agent_json) => agent_json,
+            Err(error) => {
+                persist_failure(app, state, &pubkey, &error)?;
+                return Err(format!(
+                    "provider access reconciliation failed for agent {pubkey}: {error}"
+                ));
+            }
+        };
+        if let Err(error) = super::deploy_to_provider(
+            app,
+            state,
+            &pubkey,
+            &provider_id,
+            &config,
+            agent_json,
+            cached_binary_path.as_deref(),
+        )
+        .await
+        {
+            return Err(format!(
+                "provider access reconciliation failed for agent {pubkey}: {error}"
+            ));
+        }
+    }
+
+    Ok(())
+}
+
+fn persist_failure(
+    app: &AppHandle,
+    state: &AppState,
+    pubkey: &str,
+    error: &str,
+) -> Result<(), String> {
+    let _store_guard = state
+        .managed_agents_store_lock
+        .lock()
+        .map_err(|lock_error| lock_error.to_string())?;
+    let mut records = load_managed_agents(app)?;
+    let record = find_managed_agent_mut(&mut records, pubkey)?;
+    record.last_error = Some(error.to_string());
+    record.updated_at = now_iso();
+    save_managed_agents(app, &records)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn record(backend: BackendKind, backend_agent_id: Option<&str>) -> ManagedAgentRecord {
+        let mut record: ManagedAgentRecord = serde_json::from_value(serde_json::json!({
+            "pubkey": "agent", "name": "Agent", "relay_url": "", "acp_command": "",
+            "agent_command": "", "agent_args": [], "mcp_command": "",
+            "turn_timeout_seconds": 0, "system_prompt": null, "created_at": "",
+            "updated_at": "", "last_started_at": null, "last_stopped_at": null,
+            "last_exit_code": null, "last_error": null
+        }))
+        .unwrap();
+        record.backend = backend;
+        record.backend_agent_id = backend_agent_id.map(str::to_string);
+        record
+    }
+
+    #[test]
+    fn upgrade_collects_existing_provider_and_builds_projected_payload() {
+        let records = vec![
+            record(
+                BackendKind::Provider {
+                    id: "provider".into(),
+                    config: serde_json::json!({"region": "test"}),
+                },
+                Some("existing"),
+            ),
+            record(
+                BackendKind::Provider {
+                    id: "not-deployed".into(),
+                    config: serde_json::json!({}),
+                },
+                None,
+            ),
+            record(BackendKind::Local, Some("stale")),
+        ];
+
+        let targets = collect_targets_with(records, true, |_| {
+            Ok(serde_json::json!({"respond_to": "owner-only"}))
+        });
+
+        assert_eq!(targets.len(), 1);
+        assert_eq!(targets[0].pubkey, "agent");
+        assert_eq!(targets[0].provider_id, "provider");
+        assert_eq!(targets[0].config["region"], "test");
+        assert_eq!(
+            targets[0].agent_json.as_ref().unwrap()["respond_to"],
+            "owner-only"
+        );
+    }
+
+    #[test]
+    fn unmarked_build_collects_no_upgrade_targets() {
+        let records = vec![record(
+            BackendKind::Provider {
+                id: "provider".into(),
+                config: serde_json::json!({}),
+            },
+            Some("existing"),
+        )];
+
+        assert!(
+            collect_targets_with(records, false, |_| { Ok(serde_json::Value::Null) }).is_empty()
+        );
+    }
+}
diff --git a/desktop/src-tauri/src/commands/agents_deploy.rs b/desktop/src-tauri/src/commands/agents_deploy.rs
index d924394b29..47ee5f92d4 100644
--- a/desktop/src-tauri/src/commands/agents_deploy.rs
+++ b/desktop/src-tauri/src/commands/agents_deploy.rs
@@ -24,6 +24,8 @@ pub(super) struct DeployProjections {
     /// Effective parallelism derived from the same resolved `descriptor.command`
     /// as `launch.policy_env["BUZZ_ACP_AGENTS"]`.
     pub effective_parallelism: u32,
+    /// Access fields projected from the same build policy that gates local starts.
+    pub owner_only_access: bool,
 }
 
 /// Resolve the deploy-specific structured model/provider for a managed agent.
@@ -170,6 +172,7 @@ pub(super) fn build_deploy_payload(
             effective_provider: effective.provider.value,
             effective_prompt: effective.system_prompt.value,
             effective_parallelism,
+            owner_only_access: crate::managed_agents::owner_only_access_build(),
         },
         merged_user_env,
         launch,
@@ -179,8 +182,8 @@ pub(super) fn build_deploy_payload(
 /// Pure serialization half of [`build_deploy_payload`]. Legacy top-level fields
 /// remain for display/bookkeeping; providers execute the resolved `launch` block.
 /// `projections.effective_parallelism` is pre-computed from the same resolved
-/// descriptor as `launch.policy_env["BUZZ_ACP_AGENTS"]` — the two fields are
-/// always consistent regardless of stale `record.agent_command` pins.
+/// descriptor as `launch.policy_env["BUZZ_ACP_AGENTS"]`. Access is projected from
+/// the same compiled policy that gates local starts.
 pub(super) fn deploy_payload_json(
     record: &ManagedAgentRecord,
     relay_url: String,
@@ -188,6 +191,8 @@ pub(super) fn deploy_payload_json(
     merged_env: BTreeMap<String, String>,
     launch: serde_json::Value,
 ) -> serde_json::Value {
+    let (respond_to, respond_to_allowlist) =
+        crate::managed_agents::projected_access_with_policy(record, projections.owner_only_access);
     serde_json::json!({
         "name": &record.name,
         "relay_url": relay_url,
@@ -204,8 +209,8 @@ pub(super) fn deploy_payload_json(
         // Legacy top-level field: projected from the same resolved descriptor as
         // launch.policy_env["BUZZ_ACP_AGENTS"] — the two are always consistent.
         "parallelism": projections.effective_parallelism,
-        "respond_to": record.respond_to,
-        "respond_to_allowlist": &record.respond_to_allowlist,
+        "respond_to": respond_to,
+        "respond_to_allowlist": respond_to_allowlist,
         "env_vars": merged_env,
         "launch": launch,
     })
@@ -363,6 +368,7 @@ mod tests {
                 effective_provider: None,
                 effective_prompt: None,
                 effective_parallelism,
+                owner_only_access: false,
             },
             BTreeMap::new(),
             launch.clone(),
@@ -407,6 +413,7 @@ mod tests {
                 effective_provider: None,
                 effective_prompt: None,
                 effective_parallelism,
+                owner_only_access: false,
             },
             BTreeMap::new(),
             launch.clone(),
@@ -452,6 +459,7 @@ mod tests {
                 effective_provider: None,
                 effective_prompt: None,
                 effective_parallelism,
+                owner_only_access: false,
             },
             BTreeMap::new(),
             launch.clone(),
diff --git a/desktop/src-tauri/src/commands/agents_tests.rs b/desktop/src-tauri/src/commands/agents_tests.rs
index 20061debe7..54a03e2bab 100644
--- a/desktop/src-tauri/src/commands/agents_tests.rs
+++ b/desktop/src-tauri/src/commands/agents_tests.rs
@@ -411,6 +411,27 @@ fn legacy_avatar_empty_when_nothing_resolves() {
 
 // ── Provider deploy payload completeness ─────────────────────────────────────
 
+fn deploy_payload_for_policy(
+    record: &ManagedAgentRecord,
+    owner_only_access: bool,
+) -> serde_json::Value {
+    deploy_payload_json(
+        record,
+        "wss://relay.example".to_string(),
+        DeployProjections {
+            effective_model: Some("gpt-x".to_string()),
+            effective_provider: Some("openai".to_string()),
+            effective_prompt: None,
+            effective_parallelism: record.parallelism,
+            owner_only_access,
+        },
+        std::collections::BTreeMap::new(),
+        // Access projection is the subject here; the launch block is exercised
+        // by the shared provider fixture test below.
+        serde_json::Value::Null,
+    )
+}
+
 /// The shared provider fixture is the contract arbiter: it must be the exact
 /// richest deploy request produced by the real desktop serializers.
 #[test]
@@ -473,6 +494,8 @@ fn deploy_payload_matches_the_shared_full_launch_fixture() {
                 &descriptor.command,
                 record.parallelism,
             ),
+            // Fixture asserts the record's own access fields survive.
+            owner_only_access: false,
         },
         std::collections::BTreeMap::from([("USER_KEY".into(), "user-value".into())]),
         launch,
@@ -507,3 +530,129 @@ fn tauri_platform_configs_bundle_kubernetes_only_on_supported_hosts() {
         );
     }
 }
+
+#[test]
+fn current_build_deploy_payload_forwards_compiled_policy() {
+    use crate::managed_agents::{BackendKind, RespondTo};
+
+    let expected_owner_only = match std::env::var("BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY") {
+        Ok(value) => value
+            .parse::<bool>()
+            .expect("BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY must be true or false"),
+        Err(std::env::VarError::NotPresent)
+            if !crate::managed_agents::owner_only_access_build() =>
+        {
+            false
+        }
+        Err(std::env::VarError::NotPresent) => {
+            panic!(
+                "BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY must be set for owner-only-access-build tests"
+            )
+        }
+        Err(std::env::VarError::NotUnicode(_)) => {
+            panic!("BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY must be valid UTF-8")
+        }
+    };
+    let mut record = bare_agent_record(None, None, None);
+    record.backend = BackendKind::Provider {
+        id: "provider".to_string(),
+        config: serde_json::json!({}),
+    };
+    record.respond_to = RespondTo::Anyone;
+    record.respond_to_allowlist = vec!["a".repeat(64)];
+
+    let payload = deploy_payload_json(
+        &record,
+        "wss://relay.example".to_string(),
+        DeployProjections {
+            effective_model: None,
+            effective_provider: None,
+            effective_prompt: None,
+            effective_parallelism: record.parallelism,
+            owner_only_access: crate::managed_agents::owner_only_access_build(),
+        },
+        std::collections::BTreeMap::new(),
+        // The compiled access policy is the subject here; the launch block is
+        // exercised by the shared provider fixture test above.
+        serde_json::Value::Null,
+    );
+    let expected_mode = if expected_owner_only {
+        "owner-only"
+    } else {
+        "anyone"
+    };
+
+    assert_eq!(
+        payload["respond_to"], expected_mode,
+        "current-build deploy payload did not forward the compiled policy",
+    );
+    let expected_allowlist = if expected_owner_only {
+        serde_json::json!([])
+    } else {
+        serde_json::json!(["a".repeat(64)])
+    };
+    assert_eq!(
+        payload["respond_to_allowlist"], expected_allowlist,
+        "current-build deploy payload did not apply the compiled policy to the stale allowlist",
+    );
+}
+
+#[test]
+fn provider_upgrade_reconciliation_targets_existing_deployments_only_in_marked_builds() {
+    use crate::managed_agents::BackendKind;
+
+    let mut record = bare_agent_record(None, None, None);
+    record.backend = BackendKind::Provider {
+        id: "provider".to_string(),
+        config: serde_json::json!({}),
+    };
+    record.backend_agent_id = Some("existing-provider-agent".to_string());
+    record.respond_to = crate::managed_agents::RespondTo::Anyone;
+    record.respond_to_allowlist = vec!["a".repeat(64)];
+
+    assert!(provider_access::needs_reconciliation_with_policy(
+        &record, true
+    ));
+    let payload = deploy_payload_for_policy(&record, true);
+    assert_eq!(payload["respond_to"], "owner-only");
+    assert_eq!(payload["respond_to_allowlist"], serde_json::json!([]));
+    assert!(!provider_access::needs_reconciliation_with_policy(
+        &record, false
+    ));
+
+    record.backend_agent_id = None;
+    assert!(!provider_access::needs_reconciliation_with_policy(
+        &record, true
+    ));
+
+    record.backend = BackendKind::Local;
+    record.backend_agent_id = Some("stale-provider-id".to_string());
+    assert!(!provider_access::needs_reconciliation_with_policy(
+        &record, true
+    ));
+}
+
+#[test]
+fn owner_only_access_deploy_payload_clamps_stale_access() {
+    use crate::managed_agents::{BackendKind, RespondTo};
+
+    let mut record = bare_agent_record(None, None, None);
+    record.backend = BackendKind::Provider {
+        id: "provider".to_string(),
+        config: serde_json::json!({}),
+    };
+    record.respond_to = RespondTo::Anyone;
+    record.respond_to_allowlist = vec!["a".repeat(64)];
+
+    let payload = deploy_payload_for_policy(&record, true);
+
+    assert_eq!(
+        payload["respond_to"], "owner-only",
+        "owner-only-access deploy payload widened stale access"
+    );
+    assert_eq!(
+        payload["respond_to_allowlist"],
+        serde_json::json!([]),
+        "owner-only-access deploy payload retained a stale allowlist"
+    );
+}
diff --git a/desktop/src-tauri/src/commands/mod.rs b/desktop/src-tauri/src/commands/mod.rs
index 237bc06e8d..322834630a 100644
--- a/desktop/src-tauri/src/commands/mod.rs
+++ b/desktop/src-tauri/src/commands/mod.rs
@@ -1,3 +1,4 @@
+mod agent_access;
 mod agent_auth;
 mod agent_config;
 mod agent_discovery;
@@ -63,6 +64,7 @@ mod window_vibrancy;
 mod workflows;
 mod workspace;
 
+pub use agent_access::*;
 pub use agent_auth::*;
 pub use agent_config::*;
 pub use agent_discovery::*;
diff --git a/desktop/src-tauri/src/commands/workspace.rs b/desktop/src-tauri/src/commands/workspace.rs
index 731a99d9d9..aa88bfe39a 100644
--- a/desktop/src-tauri/src/commands/workspace.rs
+++ b/desktop/src-tauri/src/commands/workspace.rs
@@ -212,6 +212,8 @@ pub async fn apply_workspace(
     .map_err(|e| format!("spawn_blocking failed: {e}"))??;
 
     let state = restore_app.state::<AppState>();
+    super::agents::provider_access::reconcile_on_workspace_apply(&restore_app, &state).await?;
+
     // Backfill this exact relay+owner scope only after the workspace has been
     // applied. Running at process boot would target the fallback relay and
     // collapse every community into one pending-event store.
diff --git a/desktop/src-tauri/src/lib.rs b/desktop/src-tauri/src/lib.rs
index d22b95224b..2847b87877 100644
--- a/desktop/src-tauri/src/lib.rs
+++ b/desktop/src-tauri/src/lib.rs
@@ -774,6 +774,7 @@ pub fn run() {
             get_managed_agent_log,
             get_agent_models,
             discover_agent_models,
+            agent_access_owner_only,
             get_agent_config_surface,
             get_runtime_file_config,
             get_baked_build_env_keys,
diff --git a/desktop/src-tauri/src/managed_agents/access_policy.rs b/desktop/src-tauri/src/managed_agents/access_policy.rs
new file mode 100644
index 0000000000..2d8326abc3
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/access_policy.rs
@@ -0,0 +1,190 @@
+//! Distribution policy at managed-agent enforcement boundaries.
+//!
+//! ## What this build capability guarantees, and what it does not
+//!
+//! `BUZZ_BUILD_AGENT_ACCESS_OWNER_ONLY` marks a build whose managed agents may
+//! answer only their owner. Enforcement is applied at the two boundaries where
+//! Desktop hands access to something that runs the agent, and nowhere else. The
+//! stored record and its relay-advertised access fields are left untouched, so
+//! the same profile keeps its user-chosen access when it is opened in an OSS
+//! build.
+//!
+//! Enforced:
+//!
+//! - **Local spawn.** [`build_respond_to_env_with_policy`] clamps
+//!   `BUZZ_ACP_RESPOND_TO` to `owner-only` and pins the independent
+//!   `BUZZ_ACP_ALLOWED_RESPOND_TO=owner-only` guard on every start, whatever
+//!   the record says.
+//! - **Provider deployment, including upgrades.**
+//!   [`projected_access_with_policy`] projects owner-only into every payload.
+//!   Workspace apply redeploys each existing provider agent before the marked
+//!   build renders community UI. A failed redeploy fails the apply, so Desktop
+//!   does not present the locked owner-only control as applied while the remote
+//!   deployment may still use a wider policy.
+//!
+//! ## "owner-only" is owner plus verified same-owner sibling agents
+//!
+//! The harness gate this projection targets admits the human owner *and* every
+//! cryptographically NIP-OA-verified agent that shares that owner (see
+//! `crates/buzz-acp/src/lib.rs`). That is the intended boundary, not an
+//! oversight: an owner's own agents are inside their trust boundary, and Buzz's
+//! built-in Welcome team relies on it, because the lead instructs its teammates
+//! while every teammate is created owner-only (see
+//! `welcomeTeammateHasExpectedAccess` in
+//! `desktop/src/features/onboarding/welcomeGuide.ts`). Read every use of
+//! "owner-only" in this module as `owner ∪ verified same-owner agents`. The
+//! setting's own copy says so: the line under Only me reads "Only you and your
+//! agents can send instructions." (`RespondToField.tsx`). The dropdown label
+//! stays "Only me", which is the audience the user picks.
+
+use super::{validate_respond_to_allowlist, ManagedAgentRecord, RespondTo};
+
+pub(crate) type RespondToEnv = (Vec<(&'static str, String)>, Vec<&'static str>);
+
+/// Release packaging sets `BUZZ_BUILD_AGENT_ACCESS_OWNER_ONLY`; OSS/custom
+/// builds do not.
+pub(crate) fn owner_only_access_build() -> bool {
+    option_env!("BUZZ_DESKTOP_BUILD_AGENT_ACCESS_OWNER_ONLY").is_some()
+}
+
+pub(crate) fn owner_only() -> bool {
+    owner_only_with_policy(owner_only_access_build())
+}
+
+pub(crate) fn owner_only_with_policy(owner_only_access: bool) -> bool {
+    owner_only_access
+}
+
+/// Project effective access at a behavioral boundary without changing the
+/// stored or relay-advertised access fields.
+pub(crate) fn projected_access_with_policy(
+    record: &ManagedAgentRecord,
+    owner_only_access: bool,
+) -> (RespondTo, Vec<String>) {
+    if owner_only_with_policy(owner_only_access) {
+        (RespondTo::OwnerOnly, Vec::new())
+    } else {
+        (record.respond_to, record.respond_to_allowlist.clone())
+    }
+}
+
+/// Build the inbound-author access environment for a launched agent. The
+/// explicit policy input keeps owner-only access enforcement testable without
+/// weakening the production caller's compile-time decision.
+pub(crate) fn build_respond_to_env_with_policy(
+    record: &ManagedAgentRecord,
+    owner_hex: Option<&str>,
+    enforced_owner_only: bool,
+) -> Result<RespondToEnv, String> {
+    let (respond_to, _) = projected_access_with_policy(record, enforced_owner_only);
+    let normalized = validate_respond_to_allowlist(&record.respond_to_allowlist)?;
+    if respond_to == RespondTo::Allowlist && normalized.is_empty() {
+        return Err(
+            "respond-to mode 'allowlist' requires at least one pubkey in the allowlist".to_string(),
+        );
+    }
+
+    let mut set = vec![("BUZZ_ACP_RESPOND_TO", respond_to.as_str().to_string())];
+    let mut remove = Vec::new();
+    if enforced_owner_only {
+        set.push((
+            "BUZZ_ACP_ALLOWED_RESPOND_TO",
+            RespondTo::OwnerOnly.as_str().to_string(),
+        ));
+    } else {
+        remove.push("BUZZ_ACP_ALLOWED_RESPOND_TO");
+    }
+    if respond_to == RespondTo::Allowlist {
+        set.push(("BUZZ_ACP_RESPOND_TO_ALLOWLIST", normalized.join(",")));
+    } else {
+        remove.push("BUZZ_ACP_RESPOND_TO_ALLOWLIST");
+    }
+
+    if record.auth_tag.is_none() {
+        if let Some(owner) = owner_hex {
+            set.push(("BUZZ_ACP_AGENT_OWNER", owner.to_string()));
+        } else {
+            remove.push("BUZZ_ACP_AGENT_OWNER");
+        }
+    } else {
+        remove.push("BUZZ_ACP_AGENT_OWNER");
+    }
+    Ok((set, remove))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::managed_agents::BackendKind;
+
+    fn record(backend: BackendKind) -> ManagedAgentRecord {
+        let mut record: ManagedAgentRecord = serde_json::from_value(serde_json::json!({
+            "pubkey": "agent", "name": "Agent", "relay_url": "", "acp_command": "",
+            "agent_command": "", "agent_args": [], "mcp_command": "",
+            "turn_timeout_seconds": 0, "system_prompt": null, "created_at": "",
+            "updated_at": "", "last_started_at": null, "last_stopped_at": null,
+            "last_exit_code": null, "last_error": null
+        }))
+        .unwrap();
+        record.backend = backend;
+        record.respond_to = RespondTo::Anyone;
+        record.respond_to_allowlist = vec!["a".repeat(64)];
+        record
+    }
+
+    #[test]
+    fn owner_only_access_policy_rejects_malformed_stored_allowlist_before_clamping() {
+        let mut record = record(BackendKind::Local);
+        record.respond_to_allowlist = vec!["malformed stale allowlist".into()];
+
+        let error = build_respond_to_env_with_policy(&record, Some("owner"), true)
+            .expect_err("owner-only access policy accepted a malformed stored allowlist");
+
+        assert!(
+            error.contains("invalid pubkey in respond-to allowlist"),
+            "owner-only access policy returned the wrong malformed-allowlist error: {error}",
+        );
+    }
+
+    #[test]
+    fn owner_only_access_enforcement_clamps_local_and_provider() {
+        for (label, backend) in [
+            ("local", BackendKind::Local),
+            (
+                "provider",
+                BackendKind::Provider {
+                    id: "p".into(),
+                    config: serde_json::json!({}),
+                },
+            ),
+        ] {
+            let record = record(backend);
+            let (gate_set, _) =
+                build_respond_to_env_with_policy(&record, Some("owner"), true).unwrap();
+            let gate_set: std::collections::HashMap<_, _> = gate_set.into_iter().collect();
+            assert_eq!(
+                gate_set.get("BUZZ_ACP_RESPOND_TO").map(String::as_str),
+                Some("owner-only"),
+                "owner-only runtime env did not clamp {label} agent",
+            );
+            assert_eq!(
+                gate_set
+                    .get("BUZZ_ACP_ALLOWED_RESPOND_TO")
+                    .map(String::as_str),
+                Some("owner-only"),
+                "owner-only runtime env omitted the {label} agent guard",
+            );
+
+            let (respond_to, allowlist) = projected_access_with_policy(&record, true);
+            assert_eq!(
+                respond_to,
+                RespondTo::OwnerOnly,
+                "owner-only provider payload did not clamp {label} agent",
+            );
+            assert!(
+                allowlist.is_empty(),
+                "owner-only provider payload retained {label} agent allowlist",
+            );
+        }
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/agent_env.rs b/desktop/src-tauri/src/managed_agents/agent_env.rs
index bf6bcb2298..05979e76cb 100644
--- a/desktop/src-tauri/src/managed_agents/agent_env.rs
+++ b/desktop/src-tauri/src/managed_agents/agent_env.rs
@@ -58,6 +58,19 @@ fn build_env_map(
             }
         }
     }
+    // Defense in depth. `build.rs` already refuses to bake a reserved key, so
+    // reaching this filter means the binary was produced by a build that
+    // skipped that check. Drop the key rather than let it override the access
+    // gate: the baked map is written into the spawned agent's environment last
+    // (see `managed_agents/runtime.rs`), so a baked `BUZZ_ACP_RESPOND_TO` would
+    // otherwise win over the gate Desktop just set.
+    map.retain(|key, _| {
+        if super::env_vars::is_reserved_env_key(key) {
+            eprintln!("buzz-desktop: ignoring reserved env var `{key}` from the baked build env");
+            return false;
+        }
+        true
+    });
     map
 }
 
@@ -356,4 +369,66 @@ mod tests {
             "unrelated merged_env keys must pass through unchanged"
         );
     }
+
+    // ── baked reserved-key filtering ──────────────────────────────────────
+    //
+    // The baked map is written into a spawned agent's environment LAST (see
+    // `managed_agents/runtime.rs`), after Buzz sets the access gates. If a
+    // baked reserved key survived here, an internal build packaged with
+    // `BUZZ_ACP_RESPOND_TO=anyone` would answer anyone while the UI shows
+    // "Only me". `build.rs` rejects such a key at build time; these tests pin
+    // the runtime backstop for a binary built without that check.
+
+    #[test]
+    fn build_env_map_drops_baked_access_gate_keys() {
+        use base64::Engine as _;
+        let raw = "BUZZ_ACP_RESPOND_TO=anyone\nBUZZ_ACP_ALLOWED_RESPOND_TO=anyone\nBUZZ_ACP_RESPOND_TO_ALLOWLIST=deadbeef\nDATABRICKS_MODEL=goose-claude-opus-4-8";
+        let blob = base64::engine::general_purpose::STANDARD.encode(raw.as_bytes());
+        let map = build_env_map(None, None, Some(&blob));
+        for key in [
+            "BUZZ_ACP_RESPOND_TO",
+            "BUZZ_ACP_ALLOWED_RESPOND_TO",
+            "BUZZ_ACP_RESPOND_TO_ALLOWLIST",
+        ] {
+            assert!(
+                !map.contains_key(key),
+                "baked `{key}` must not reach the spawned agent env"
+            );
+        }
+        assert_eq!(
+            map.get("DATABRICKS_MODEL").map(String::as_str),
+            Some("goose-claude-opus-4-8"),
+            "non-reserved baked keys must still pass through"
+        );
+    }
+
+    #[test]
+    fn build_env_map_drops_baked_reserved_keys_case_insensitively() {
+        use base64::Engine as _;
+        // `is_reserved_env_key` compares case-insensitively, and so must the
+        // baked filter: env lookup is case-sensitive on Unix, but a lowercase
+        // spelling would still be a reserved key smuggled past a case-sensitive
+        // check on Windows.
+        let raw = "buzz_acp_respond_to=anyone\nBuzz_Private_Key=nsec1fake";
+        let blob = base64::engine::general_purpose::STANDARD.encode(raw.as_bytes());
+        let map = build_env_map(None, None, Some(&blob));
+        assert!(
+            map.is_empty(),
+            "reserved keys in any casing must be dropped from the baked env: {map:?}"
+        );
+    }
+
+    #[test]
+    fn build_env_map_drops_every_reserved_key() {
+        use base64::Engine as _;
+        for key in super::super::env_vars::RESERVED_ENV_KEYS {
+            let raw = format!("{key}=baked-value");
+            let blob = base64::engine::general_purpose::STANDARD.encode(raw.as_bytes());
+            let map = build_env_map(None, None, Some(&blob));
+            assert!(
+                map.is_empty(),
+                "baked reserved key `{key}` must be dropped, got {map:?}"
+            );
+        }
+    }
 }
diff --git a/desktop/src-tauri/src/managed_agents/env_vars.rs b/desktop/src-tauri/src/managed_agents/env_vars.rs
index f912d5bbc0..9ca5fd080d 100644
--- a/desktop/src-tauri/src/managed_agents/env_vars.rs
+++ b/desktop/src-tauri/src/managed_agents/env_vars.rs
@@ -5,19 +5,13 @@
 //! Precedence: desktop parent env < persona env < agent env (last wins on
 //! key collision). See `runtime::spawn_agent_child`.
 //!
-//! A small set of *reserved* keys — Buzz's identity and secrets, and
-//! control-plane values set by the Desktop — are rejected at save time and
-//! stripped at runtime so a typo or malicious value can't swap the agent's
-//! nsec or bypass a harness-specific execution cap. Behavior knobs
+//! A small set of *reserved* keys includes Buzz's identity, secrets, security
+//! gates, and control-plane values. Save-time validation rejects those keys.
+//! Runtime filtering strips old persisted overrides. Behavior knobs
 //! (GOOSE_MODE, BUZZ_ACP_MODEL, BUZZ_ACP_SYSTEM_PROMPT, …) remain freely
-//! overridable — those have dedicated UI fields, but power users may want
-//! to bypass them.
-//!
-//! `BUZZ_ACP_AGENTS` is reserved because the Desktop resolves the effective
-//! parallelism (applying per-harness caps such as OpenClaw's cap of 5) and
-//! writes the result into `launch.policy_env`. A user-supplied
-//! `BUZZ_ACP_AGENTS` would bypass the cap and cause OpenClaw agents to spawn
-//! uncapped workers against their single shared Gateway daemon.
+//! overridable. Power users can still bypass their dedicated UI fields.
+//! `BUZZ_ACP_AGENTS` is reserved because Desktop applies harness-specific caps
+//! before it writes the provider launch policy.
 
 use std::collections::BTreeMap;
 
@@ -47,77 +41,9 @@ pub(crate) fn is_derived_provider_model_key(key: &str) -> bool {
         .any(|k| k.eq_ignore_ascii_case(key))
 }
 
-/// Env var keys that Buzz sets itself and users must not override from
-/// the persona/agent env_vars UI. Four categories:
-///
-/// 1. **Identity / secrets** — overriding would swap the agent's nsec or
-///    leak credentials.
-/// 2. **Code-execution surface** — overriding the binary/args lets the
-///    user run arbitrary code as the agent process.
-/// 3. **Security gates** — overriding the respond-to mode/allowlist or
-///    relay URL would silently break the saved security settings (the UI
-///    shows owner-only while the running agent answers anyone, for
-///    example), or redirect the agent to an attacker-controlled relay.
-/// 4. **Control-plane execution policy** — the Desktop owns the effective
-///    value, derived from structured record fields after applying per-harness
-///    caps. A user-supplied override would bypass the cap and produce a
-///    worker pool size that neither the record nor the UI represents.
-///
-/// This list is deliberately narrow — it only covers keys with security or
-/// correctness implications. Behavior knobs (GOOSE_MODE, BUZZ_ACP_MODEL,
-/// BUZZ_ACP_SYSTEM_PROMPT, …) remain freely overridable; those have
-/// dedicated UI fields but power users may want to bypass them.
-pub(crate) const RESERVED_ENV_KEYS: &[&str] = &[
-    // Identity / secrets.
-    "BUZZ_PRIVATE_KEY",
-    "NOSTR_PRIVATE_KEY",
-    "BUZZ_AUTH_TAG",
-    "BUZZ_API_TOKEN",
-    "BUZZ_ACP_PRIVATE_KEY",
-    "BUZZ_ACP_API_TOKEN",
-    // Relay URL: overriding would let a malicious config redirect the
-    // agent to an attacker-controlled relay.
-    "BUZZ_RELAY_URL",
-    // Code-execution surface: overriding would let the user run arbitrary
-    // binaries/args as the agent process.
-    "BUZZ_ACP_AGENT_COMMAND",
-    "BUZZ_ACP_AGENT_ARGS",
-    "BUZZ_ACP_MCP_COMMAND",
-    // Control-plane parallelism: the Desktop resolves the effective
-    // worker-pool size (applying any per-harness cap) and writes it into
-    // launch.policy_env. A user-supplied BUZZ_ACP_AGENTS would bypass the
-    // harness cap and cause OpenClaw agents to spawn uncapped workers.
-    "BUZZ_ACP_AGENTS",
-    // Security gates: respond-to mode + allowlist + legacy owner-only
-    // fallback. Overriding would make the running agent's gate diverge
-    // from the saved/UI-visible settings.
-    "BUZZ_ACP_RESPOND_TO",
-    "BUZZ_ACP_RESPOND_TO_ALLOWLIST",
-    "BUZZ_ACP_AGENT_OWNER",
-    // Stable agent identity used for git attribution and private-conversation
-    // provenance must come from the managed-agent record, not user overrides.
-    "BUZZ_ACP_DISPLAY_NAME",
-    // 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.
-    "BUZZ_ACP_SETUP_PAYLOAD",
-    // Desktop ownership markers: these brand every spawned harness with the
-    // launching Desktop instance. A user-supplied override would let a
-    // definition masquerade as a different instance or fake the nonce used
-    // for same-session sweep decisions.
-    "BUZZ_MANAGED_AGENT",
-    "BUZZ_MANAGED_AGENT_START_NONCE",
-];
-
-pub(crate) fn is_reserved_env_key(key: &str) -> bool {
-    RESERVED_ENV_KEYS
-        .iter()
-        .any(|reserved| reserved.eq_ignore_ascii_case(key))
-}
+// Canonical reserved-key list + predicate, shared verbatim with `build.rs`.
+// See `reserved_env_keys.rs` for why this is `include!`d rather than a module.
+include!("reserved_env_keys.rs");
 
 /// Returns true if `key` is a well-formed POSIX-shaped env var name:
 /// `[A-Za-z_][A-Za-z0-9_]*`. This is a hard requirement, not a stylistic
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 534c2e0835..34cdfede2c 100644
--- a/desktop/src-tauri/src/managed_agents/env_vars/tests.rs
+++ b/desktop/src-tauri/src/managed_agents/env_vars/tests.rs
@@ -150,7 +150,11 @@ fn reserved_keys_include_respond_to_gate() {
     // Respond-to mode + allowlist control who the agent answers.
     // Overriding via env_vars would let the running agent answer
     // anyone even when the UI/record says owner-only.
-    for key in ["BUZZ_ACP_RESPOND_TO", "BUZZ_ACP_RESPOND_TO_ALLOWLIST"] {
+    for key in [
+        "BUZZ_ACP_RESPOND_TO",
+        "BUZZ_ACP_RESPOND_TO_ALLOWLIST",
+        "BUZZ_ACP_ALLOWED_RESPOND_TO",
+    ] {
         assert!(is_reserved_env_key(key), "{key} should be reserved");
         let agent = map(&[(key, "anyone")]);
         let merged = merged_user_env(&BTreeMap::new(), &agent);
diff --git a/desktop/src-tauri/src/managed_agents/mod.rs b/desktop/src-tauri/src/managed_agents/mod.rs
index 986ce4e0c0..fe90ce430f 100644
--- a/desktop/src-tauri/src/managed_agents/mod.rs
+++ b/desktop/src-tauri/src/managed_agents/mod.rs
@@ -1,8 +1,10 @@
+pub(crate) mod access_policy;
 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 access_policy::{owner_only, owner_only_access_build, projected_access_with_policy};
 pub(crate) use agent_env::{
     baked_build_env, build_buzz_agent_provider_defaults, discovery_env_with_baked_floor,
 };
diff --git a/desktop/src-tauri/src/managed_agents/reserved_env_keys.rs b/desktop/src-tauri/src/managed_agents/reserved_env_keys.rs
new file mode 100644
index 0000000000..8698d3a51d
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/reserved_env_keys.rs
@@ -0,0 +1,79 @@
+// Canonical reserved-env-key list, `include!`d into BOTH `build.rs`
+// (compile-time rejection of baked `BUZZ_BUILD_AGENT_ENV` collisions) and
+// `managed_agents/env_vars.rs` (save-time validation and spawn-time
+// filtering). Build scripts cannot import from the crate, so sharing the
+// source via `include!` is what guarantees the build-time check and the
+// runtime filter use one identical list — zero drift surface. See
+// `commands/reconnect_hook_config.rs` for the same pattern.
+//
+// Keep this file dependency-free: no crate-internal imports, no external
+// crates. Both consumers compile it as-is.
+
+/// Env var keys that Buzz sets itself and users must not override from
+/// the persona/agent env_vars UI. Three categories:
+///
+/// 1. **Identity / secrets** — overriding would swap the agent's nsec or
+///    leak credentials.
+/// 2. **Code-execution surface** — overriding the binary/args lets the
+///    user run arbitrary code as the agent process.
+/// 3. **Security gates** — overriding the respond-to mode/allowlist or
+///    relay URL would silently break the saved security settings (the UI
+///    shows owner-only while the running agent answers anyone, for
+///    example), or redirect the agent to an attacker-controlled relay.
+///
+/// This list is deliberately narrow — it only covers keys with security
+/// implications. Behavior knobs (GOOSE_MODE, BUZZ_ACP_MODEL, BUZZ_ACP_SYSTEM_PROMPT, …) remain freely
+/// overridable; those have dedicated UI fields but power users may want
+/// to bypass them.
+pub(crate) const RESERVED_ENV_KEYS: &[&str] = &[
+    // Identity / secrets.
+    "BUZZ_PRIVATE_KEY",
+    "NOSTR_PRIVATE_KEY",
+    "BUZZ_AUTH_TAG",
+    "BUZZ_API_TOKEN",
+    "BUZZ_ACP_PRIVATE_KEY",
+    "BUZZ_ACP_API_TOKEN",
+    // Relay URL: overriding would let a malicious config redirect the
+    // agent to an attacker-controlled relay.
+    "BUZZ_RELAY_URL",
+    // Code-execution surface: overriding would let the user run arbitrary
+    // binaries/args as the agent process.
+    "BUZZ_ACP_AGENT_COMMAND",
+    "BUZZ_ACP_AGENT_ARGS",
+    "BUZZ_ACP_MCP_COMMAND",
+    // Control-plane parallelism: the Desktop resolves the effective
+    // worker-pool size (applying any per-harness cap) and writes it into
+    // launch.policy_env. A user-supplied BUZZ_ACP_AGENTS would bypass the
+    // harness cap and cause OpenClaw agents to spawn uncapped workers.
+    "BUZZ_ACP_AGENTS",
+    // Security gates: respond-to mode + allowlist + deployment allowlist +
+    // legacy owner-only fallback. Overriding would make the running agent's
+    // gate diverge from the saved/UI-visible settings.
+    "BUZZ_ACP_RESPOND_TO",
+    "BUZZ_ACP_RESPOND_TO_ALLOWLIST",
+    "BUZZ_ACP_ALLOWED_RESPOND_TO",
+    "BUZZ_ACP_AGENT_OWNER",
+    // Stable agent identity used for git attribution and private-conversation
+    // provenance must come from the managed-agent record, not user overrides.
+    "BUZZ_ACP_DISPLAY_NAME",
+    // 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.
+    "BUZZ_ACP_SETUP_PAYLOAD",
+    // Desktop ownership markers: these brand every spawned harness with the
+    // launching Desktop instance. A user-supplied override would let a
+    // definition masquerade as a different instance or fake the nonce used
+    // for same-session sweep decisions.
+    "BUZZ_MANAGED_AGENT",
+    "BUZZ_MANAGED_AGENT_START_NONCE",
+];
+
+pub(crate) fn is_reserved_env_key(key: &str) -> bool {
+    RESERVED_ENV_KEYS
+        .iter()
+        .any(|reserved| reserved.eq_ignore_ascii_case(key))
+}
diff --git a/desktop/src-tauri/src/managed_agents/runtime.rs b/desktop/src-tauri/src/managed_agents/runtime.rs
index 7afd80d1d6..ec804869c4 100644
--- a/desktop/src-tauri/src/managed_agents/runtime.rs
+++ b/desktop/src-tauri/src/managed_agents/runtime.rs
@@ -16,9 +16,9 @@ use crate::{
 
 mod path;
 pub(in crate::managed_agents) use path::build_augmented_path;
-pub(crate) use path::compose_path_entries;
-pub(crate) use path::should_skip_claude_executable;
-pub(crate) use path::should_use_inherited;
+pub(crate) use path::{compose_path_entries, should_skip_claude_executable, should_use_inherited};
+
+pub(crate) use super::access_policy::{build_respond_to_env_with_policy, RespondToEnv};
 
 mod metadata;
 pub(crate) use metadata::{
@@ -33,8 +33,6 @@ pub use stop::{stop_managed_agent_process, stop_managed_agent_workspace_pair};
 mod sweep;
 pub(crate) use sweep::sweep_untracked_bundle_harnesses;
 
-type RespondToEnv = (Vec<(&'static str, String)>, Vec<&'static str>);
-
 mod process;
 #[cfg(test)]
 use process::{
@@ -370,44 +368,7 @@ pub(crate) fn build_respond_to_env(
     record: &ManagedAgentRecord,
     owner_hex: Option<&str>,
 ) -> Result<RespondToEnv, String> {
-    // Defensive re-validation: an on-disk record could have been hand-edited.
-    let normalized = super::types::validate_respond_to_allowlist(&record.respond_to_allowlist)?;
-    if record.respond_to == super::types::RespondTo::Allowlist && normalized.is_empty() {
-        return Err(
-            "respond-to mode 'allowlist' requires at least one pubkey in the allowlist".to_string(),
-        );
-    }
-
-    let mut set: Vec<(&'static str, String)> = Vec::new();
-    let mut remove: Vec<&'static str> = Vec::new();
-
-    set.push((
-        "BUZZ_ACP_RESPOND_TO",
-        record.respond_to.as_str().to_string(),
-    ));
-
-    if record.respond_to == super::types::RespondTo::Allowlist {
-        set.push(("BUZZ_ACP_RESPOND_TO_ALLOWLIST", normalized.join(",")));
-    } else {
-        remove.push("BUZZ_ACP_RESPOND_TO_ALLOWLIST");
-    }
-
-    // Legacy fallback: agents created before NIP-OA lack `auth_tag`. Without
-    // it the harness can't resolve the owner, and owner-dependent gate modes
-    // would drop every event. Forwarding the workspace owner pubkey via
-    // BUZZ_ACP_AGENT_OWNER keeps those records functional. Modern records
-    // (`auth_tag = Some(...)`) use `BUZZ_AUTH_TAG` as before.
-    if record.auth_tag.is_none() {
-        if let Some(owner) = owner_hex {
-            set.push(("BUZZ_ACP_AGENT_OWNER", owner.to_string()));
-        } else {
-            remove.push("BUZZ_ACP_AGENT_OWNER");
-        }
-    } else {
-        remove.push("BUZZ_ACP_AGENT_OWNER");
-    }
-
-    Ok((set, remove))
+    build_respond_to_env_with_policy(record, owner_hex, super::owner_only())
 }
 
 pub(crate) fn configure_runtime_cli(
@@ -1015,5 +976,8 @@ pub fn start_managed_agent_process(
     Ok(())
 }
 
+#[cfg(test)]
+mod test_fixtures;
+
 #[cfg(test)]
 mod tests;
diff --git a/desktop/src-tauri/src/managed_agents/runtime/test_fixtures.rs b/desktop/src-tauri/src/managed_agents/runtime/test_fixtures.rs
new file mode 100644
index 0000000000..9836d983ed
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/runtime/test_fixtures.rs
@@ -0,0 +1,93 @@
+use crate::managed_agents::types::{ManagedAgentRecord, RespondTo};
+
+pub(super) const EXPECTED_ACCESS_ENV: &str = "BUZZ_TEST_EXPECTED_AGENT_ACCESS_OWNER_ONLY";
+
+pub(super) fn expected_owner_only() -> bool {
+    match std::env::var(EXPECTED_ACCESS_ENV) {
+        Ok(value) => value
+            .parse::<bool>()
+            .unwrap_or_else(|_| panic!("{EXPECTED_ACCESS_ENV} must be true or false")),
+        Err(std::env::VarError::NotPresent)
+            if !crate::managed_agents::owner_only_access_build() =>
+        {
+            false
+        }
+        Err(std::env::VarError::NotPresent) => {
+            panic!("{EXPECTED_ACCESS_ENV} must be set for owner-only-access-build tests")
+        }
+        Err(std::env::VarError::NotUnicode(_)) => {
+            panic!("{EXPECTED_ACCESS_ENV} must be valid UTF-8")
+        }
+    }
+}
+
+pub(super) fn expected_mode(oss_mode: &'static str) -> &'static str {
+    if expected_owner_only() {
+        "owner-only"
+    } else {
+        oss_mode
+    }
+}
+
+/// Construct a minimal record fixture for runtime tests.
+pub(super) fn fixture(
+    respond_to: RespondTo,
+    allowlist: Vec<String>,
+    auth_tag: Option<String>,
+) -> ManagedAgentRecord {
+    ManagedAgentRecord {
+        pubkey: "p".into(),
+        name: "n".into(),
+        persona_id: None,
+        private_key_nsec: "nsec1fake".into(),
+        auth_tag,
+        relay_url: "ws://localhost:3000".into(),
+        avatar_url: None,
+        acp_command: "buzz-acp".into(),
+        agent_command: "goose".into(),
+        agent_command_override: None,
+        agent_args: vec![],
+        mcp_command: String::new(),
+        turn_timeout_seconds: 320,
+        idle_timeout_seconds: None,
+        max_turn_duration_seconds: None,
+        parallelism: 1,
+        system_prompt: None,
+        model: None,
+        provider: None,
+        persona_source_version: None,
+        env_vars: std::collections::BTreeMap::new(),
+        start_on_app_launch: false,
+        auto_restart_on_config_change: true,
+        runtime_pid: None,
+        backend: Default::default(),
+        backend_agent_id: None,
+        provider_binary_path: None,
+        team_id: None,
+        persona_team_dir: None,
+        persona_name_in_team: None,
+        created_at: "now".into(),
+        updated_at: "now".into(),
+        last_started_at: None,
+        last_stopped_at: None,
+        last_exit_code: None,
+        last_error: None,
+        last_error_code: None,
+        respond_to,
+        respond_to_allowlist: allowlist,
+        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,
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/runtime/tests.rs b/desktop/src-tauri/src/managed_agents/runtime/tests.rs
index bea4b1c3e3..762b0fe2a6 100644
--- a/desktop/src-tauri/src/managed_agents/runtime/tests.rs
+++ b/desktop/src-tauri/src/managed_agents/runtime/tests.rs
@@ -117,73 +117,10 @@ fn unknown_command_returns_none() {
 
 // ── build_respond_to_env tests ───────────────────────────────────────
 
-use super::build_respond_to_env;
+use super::test_fixtures::{expected_mode, expected_owner_only, fixture};
+use super::{build_respond_to_env, build_respond_to_env_with_policy};
 use crate::managed_agents::types::{ManagedAgentRecord, RespondTo};
 
-/// Construct a minimal record fixture for env-building tests. Only the
-/// fields read by `build_respond_to_env` matter here.
-fn fixture(
-    respond_to: RespondTo,
-    allowlist: Vec<String>,
-    auth_tag: Option<String>,
-) -> ManagedAgentRecord {
-    ManagedAgentRecord {
-        pubkey: "p".into(),
-        name: "n".into(),
-        persona_id: None,
-        private_key_nsec: "nsec1fake".into(),
-        auth_tag,
-        relay_url: "ws://localhost:3000".into(),
-        avatar_url: None,
-        acp_command: "buzz-acp".into(),
-        agent_command: "goose".into(),
-        agent_command_override: None,
-        agent_args: vec![],
-        mcp_command: String::new(),
-        turn_timeout_seconds: 320,
-        idle_timeout_seconds: None,
-        max_turn_duration_seconds: None,
-        parallelism: 1,
-        system_prompt: None,
-        model: None,
-        provider: None,
-        persona_source_version: None,
-        env_vars: std::collections::BTreeMap::new(),
-        start_on_app_launch: false,
-        auto_restart_on_config_change: true,
-        runtime_pid: None,
-        backend: Default::default(),
-        backend_agent_id: None,
-        provider_binary_path: None,
-        team_id: None,
-        persona_team_dir: None,
-        persona_name_in_team: None,
-        created_at: "now".into(),
-        updated_at: "now".into(),
-        last_started_at: None,
-        last_stopped_at: None,
-        last_exit_code: None,
-        last_error: None,
-        last_error_code: None,
-        respond_to,
-        respond_to_allowlist: allowlist,
-        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,
-    }
-}
-
 #[test]
 fn build_env_owner_only_sets_mode_and_removes_others() {
     let rec = fixture(RespondTo::OwnerOnly, vec![], Some("tag".into()));
@@ -195,6 +132,18 @@ fn build_env_owner_only_sets_mode_and_removes_others() {
     );
     assert!(!set_map.contains_key("BUZZ_ACP_RESPOND_TO_ALLOWLIST"));
     assert!(remove.contains(&"BUZZ_ACP_RESPOND_TO_ALLOWLIST"));
+    if expected_owner_only() {
+        assert_eq!(
+            set_map
+                .get("BUZZ_ACP_ALLOWED_RESPOND_TO")
+                .map(String::as_str),
+            Some("owner-only")
+        );
+        assert!(!remove.contains(&"BUZZ_ACP_ALLOWED_RESPOND_TO"));
+    } else {
+        assert!(!set_map.contains_key("BUZZ_ACP_ALLOWED_RESPOND_TO"));
+        assert!(remove.contains(&"BUZZ_ACP_ALLOWED_RESPOND_TO"));
+    }
     // auth_tag is present → no AGENT_OWNER fallback fires.
     assert!(remove.contains(&"BUZZ_ACP_AGENT_OWNER"));
 }
@@ -214,14 +163,19 @@ fn build_env_allowlist_sets_both_envs_and_joins() {
     let set_map: std::collections::HashMap<_, _> = set.into_iter().collect();
     assert_eq!(
         set_map.get("BUZZ_ACP_RESPOND_TO").map(String::as_str),
-        Some("allowlist")
-    );
-    assert_eq!(
-        set_map
-            .get("BUZZ_ACP_RESPOND_TO_ALLOWLIST")
-            .map(String::as_str),
-        Some(format!("{a},{b}").as_str()),
+        Some(expected_mode("allowlist")),
+        "runtime wrapper did not apply the declared build policy",
     );
+    if expected_owner_only() {
+        assert!(!set_map.contains_key("BUZZ_ACP_RESPOND_TO_ALLOWLIST"));
+    } else {
+        assert_eq!(
+            set_map
+                .get("BUZZ_ACP_RESPOND_TO_ALLOWLIST")
+                .map(String::as_str),
+            Some(format!("{a},{b}").as_str()),
+        );
+    }
 }
 
 #[test]
@@ -231,7 +185,30 @@ fn build_env_anyone_omits_allowlist_var() {
     let set_map: std::collections::HashMap<_, _> = set.into_iter().collect();
     assert_eq!(
         set_map.get("BUZZ_ACP_RESPOND_TO").map(String::as_str),
-        Some("anyone")
+        Some(expected_mode("anyone")),
+        "runtime wrapper did not apply the declared build policy",
+    );
+    assert!(!set_map.contains_key("BUZZ_ACP_RESPOND_TO_ALLOWLIST"));
+    assert!(remove.contains(&"BUZZ_ACP_RESPOND_TO_ALLOWLIST"));
+}
+
+#[test]
+fn owner_only_access_policy_overrides_stale_anyone_record_at_runtime() {
+    let rec = fixture(RespondTo::Anyone, vec!["a".repeat(64)], Some("tag".into()));
+    let (set, remove) = build_respond_to_env_with_policy(&rec, Some("owner"), true).unwrap();
+    let set_map: std::collections::HashMap<_, _> = set.into_iter().collect();
+
+    assert_eq!(
+        set_map.get("BUZZ_ACP_RESPOND_TO").map(String::as_str),
+        Some("owner-only"),
+        "owner-only-access runtime env widened stale access",
+    );
+    assert_eq!(
+        set_map
+            .get("BUZZ_ACP_ALLOWED_RESPOND_TO")
+            .map(String::as_str),
+        Some("owner-only"),
+        "owner-only-access runtime env omitted the owner-only guard",
     );
     assert!(!set_map.contains_key("BUZZ_ACP_RESPOND_TO_ALLOWLIST"));
     assert!(remove.contains(&"BUZZ_ACP_RESPOND_TO_ALLOWLIST"));
@@ -271,8 +248,17 @@ fn build_env_rejects_corrupted_allowlist() {
 #[test]
 fn build_env_rejects_empty_allowlist_in_allowlist_mode() {
     let rec = fixture(RespondTo::Allowlist, vec![], Some("tag".into()));
-    let err = build_respond_to_env(&rec, Some("owner")).unwrap_err();
-    assert!(err.contains("at least one pubkey"));
+    if expected_owner_only() {
+        let (set, _) = build_respond_to_env(&rec, Some("owner")).unwrap();
+        let set_map: std::collections::HashMap<_, _> = set.into_iter().collect();
+        assert_eq!(
+            set_map.get("BUZZ_ACP_RESPOND_TO").map(String::as_str),
+            Some("owner-only")
+        );
+    } else {
+        let err = build_respond_to_env(&rec, Some("owner")).unwrap_err();
+        assert!(err.contains("at least one pubkey"));
+    }
 }
 
 // ── persona fixture helpers ─────────────────────────────────────────
diff --git a/desktop/src/features/agents/AGENTS.md b/desktop/src/features/agents/AGENTS.md
index 2cb1d82df2..b929dbb613 100644
--- a/desktop/src/features/agents/AGENTS.md
+++ b/desktop/src/features/agents/AGENTS.md
@@ -164,7 +164,10 @@ with a TypeScript lookup table or an id comparison in a component.
    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.
+   copy. **The owner-only-access build capability is backend-independent.** When
+   `getAgentAccessOwnerOnly()` is true, every managed agent's access control is
+   locked to owner-only, including provider-backed agents. A provider backend
+   does not prove remote execution and must never create a policy carve-out.
 
 ## The tests that enforce this
 
diff --git a/desktop/src/features/agents/hooks.ts b/desktop/src/features/agents/hooks.ts
index b39a7e8ec8..b3d4c5315e 100644
--- a/desktop/src/features/agents/hooks.ts
+++ b/desktop/src/features/agents/hooks.ts
@@ -946,7 +946,6 @@ export function useRuntimeFileConfigQuery(
 
 export const bakedBuildEnvKeysQueryKey = ["baked-build-env-keys"] as const;
 export const bakedBuildEnvQueryKey = ["baked-build-env"] as const;
-
 /**
  * Query safely displayable baked build env entries. The backend masks secrets,
  * so this is only used for inherited provider/model/effort labels.
diff --git a/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx b/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx
index adfb8182a8..f7ee098833 100644
--- a/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx
+++ b/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx
@@ -11,6 +11,7 @@ import {
   useStartManagedAgentMutation,
   useUpdateManagedAgentMutation,
 } from "@/features/agents/hooks";
+import { useAgentAccessOwnerOnlyQuery } from "@/features/agents/useAgentAccessOwnerOnly";
 import { isManagedAgentActive } from "@/features/agents/lib/managedAgentControlActions";
 import type {
   ManagedAgent,
@@ -63,9 +64,9 @@ import {
   type RuntimeModelProviderSelection,
 } from "./runtimeModelProviderSelection";
 import { AgentCreationPreview } from "./AgentCreationPreview";
+import { OwnerOnlyAccessField } from "./OwnerOnlyAccessField";
 import type { EnvVarsValue } from "./EnvVarsEditor";
 import { useRequiredCredentialState } from "./useRequiredCredentialState";
-import { CreateAgentRespondToField } from "./RespondToField";
 import { RunOnSummarySection } from "./RunOnSummarySection";
 import { PersonaDropdownField } from "./PersonaDropdownField";
 import {
@@ -392,6 +393,9 @@ export function AgentInstanceEditDialog({
     });
 
   const { data: bakedEnvKeys } = useBakedBuildEnvKeysQuery({ enabled: open });
+  const { data: agentAccessOwnerOnly } = useAgentAccessOwnerOnlyQuery({
+    enabled: open,
+  });
 
   // Merge global env as the base layer so credential keys satisfied via global
   // config (e.g. ANTHROPIC_API_KEY) are available to model discovery. Use
@@ -905,7 +909,6 @@ export function AgentInstanceEditDialog({
             )}
           </div>
           <div className="space-y-5">
-            {/* Agent name */}
             <div className="space-y-1.5">
               <label
                 className="text-sm font-medium text-foreground"
@@ -933,17 +936,14 @@ export function AgentInstanceEditDialog({
                 />
               </div>
             </div>
-
-            {/* Who can send instructions */}
-            <CreateAgentRespondToField
+            <OwnerOnlyAccessField
+              accessLocked={agentAccessOwnerOnly === true}
               allowlist={respondToAllowlist}
               disabled={updateMutation.isPending}
               mode={respondTo}
               onAllowlistChange={setRespondToAllowlist}
               onModeChange={setRespondTo}
-              variant="persona"
             />
-
             <RunOnSummarySection backend={agent.backend} />
 
             {/* Provider (runtime) */}
diff --git a/desktop/src/features/agents/ui/OwnerOnlyAccessField.tsx b/desktop/src/features/agents/ui/OwnerOnlyAccessField.tsx
new file mode 100644
index 0000000000..4ff7f351a0
--- /dev/null
+++ b/desktop/src/features/agents/ui/OwnerOnlyAccessField.tsx
@@ -0,0 +1,35 @@
+import type { RespondToMode } from "@/shared/api/types";
+import {
+  CreateAgentRespondToField,
+  OWNER_ONLY_ACCESS_DISABLED_REASON,
+} from "./RespondToField";
+
+export function OwnerOnlyAccessField({
+  accessLocked,
+  allowlist,
+  disabled,
+  mode,
+  onAllowlistChange,
+  onModeChange,
+}: {
+  accessLocked: boolean;
+  allowlist: string[];
+  disabled: boolean;
+  mode: RespondToMode;
+  onAllowlistChange: (allowlist: string[]) => void;
+  onModeChange: (mode: RespondToMode) => void;
+}) {
+  return (
+    <CreateAgentRespondToField
+      allowlist={accessLocked ? [] : allowlist}
+      disabled={disabled || accessLocked}
+      disabledReason={
+        accessLocked ? OWNER_ONLY_ACCESS_DISABLED_REASON : undefined
+      }
+      mode={accessLocked ? "owner-only" : mode}
+      onAllowlistChange={onAllowlistChange}
+      onModeChange={onModeChange}
+      variant="persona"
+    />
+  );
+}
diff --git a/desktop/src/features/agents/ui/PersonaAdvancedFields.tsx b/desktop/src/features/agents/ui/PersonaAdvancedFields.tsx
index 62cb8a240c..622fe5d674 100644
--- a/desktop/src/features/agents/ui/PersonaAdvancedFields.tsx
+++ b/desktop/src/features/agents/ui/PersonaAdvancedFields.tsx
@@ -1,8 +1,12 @@
 import * as React from "react";
+import { useAgentAccessOwnerOnlyQuery } from "../useAgentAccessOwnerOnly";
 import { Input } from "@/shared/ui/input";
 import { cn } from "@/shared/lib/cn";
 import { EnvVarsEditor, type EnvVarsValue } from "./EnvVarsEditor";
-import { CreateAgentRespondToField } from "./RespondToField";
+import {
+  CreateAgentRespondToField,
+  OWNER_ONLY_ACCESS_DISABLED_REASON,
+} from "./RespondToField";
 import type { PersonaBehaviorDraft } from "./personaBehaviorDraft";
 import {
   isBuzzAgentRuntime,
@@ -83,6 +87,11 @@ export function PersonaAdvancedFields({
    */
   selectedRuntime?: AcpRuntimeCatalogEntry;
 }) {
+  const { data: agentAccessOwnerOnly = false } = useAgentAccessOwnerOnlyQuery();
+  const respondToMode = agentAccessOwnerOnly
+    ? "owner-only"
+    : (behaviorDraft.respondTo ?? "owner-only");
+
   // Numeric tuning descriptors — gate on catalog status so that loading/error
   // never collapses to "no controls": keys stay visible as generic rows.
   const numericDescriptors = React.useMemo(
@@ -126,9 +135,12 @@ export function PersonaAdvancedFields({
   return (
     <div className="space-y-5 pt-2">
       <CreateAgentRespondToField
-        allowlist={behaviorDraft.respondToAllowlist}
-        disabled={disabled}
-        mode={behaviorDraft.respondTo ?? "owner-only"}
+        allowlist={agentAccessOwnerOnly ? [] : behaviorDraft.respondToAllowlist}
+        disabled={disabled || agentAccessOwnerOnly}
+        disabledReason={
+          agentAccessOwnerOnly ? OWNER_ONLY_ACCESS_DISABLED_REASON : undefined
+        }
+        mode={respondToMode}
         onAllowlistChange={(allowlist) =>
           onBehaviorDraftChange({
             ...behaviorDraft,
diff --git a/desktop/src/features/agents/ui/RespondToField.tsx b/desktop/src/features/agents/ui/RespondToField.tsx
index b32b9e0983..589d4c8c7a 100644
--- a/desktop/src/features/agents/ui/RespondToField.tsx
+++ b/desktop/src/features/agents/ui/RespondToField.tsx
@@ -39,6 +39,12 @@ import type { PersonaDropdownOption } from "./agentConfigOptions";
  * than an explanation, and stays one sentence — Only me already owns the line
  * below the control.
  *
+ * The line below Only me says "Only you and your agents", because the harness
+ * gate admits the owner and every verified same-owner agent, not the owner
+ * alone (see `managed_agents/access_policy.rs`). The dropdown label stays
+ * "Only me": it is the audience the user picks, and it has meant this since
+ * before agents could instruct each other.
+ *
  * 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
@@ -72,6 +78,9 @@ const RESPOND_TO_OPTIONS: PersonaDropdownOption[] = [
   { label: "Selected people", value: "allowlist" },
 ];
 
+export const OWNER_ONLY_ACCESS_DISABLED_REASON =
+  "This build disallows changing this setting.";
+
 export function CreateAgentRespondToField({
   mode,
   allowlist,
@@ -79,6 +88,7 @@ export function CreateAgentRespondToField({
   onAllowlistChange,
   ownerPubkey,
   disabled,
+  disabledReason,
   variant,
   runLocation,
 }: {
@@ -93,6 +103,8 @@ export function CreateAgentRespondToField({
    */
   ownerPubkey?: string | null;
   disabled?: boolean;
+  /** Explanation shown when this access control is unavailable. */
+  disabledReason?: string;
   /** When "persona", uses PersonaDropdownField styling to match the persona dialog. */
   variant?: "default" | "persona";
   /**
@@ -219,10 +231,18 @@ export function CreateAgentRespondToField({
           ))}
         </select>
       )}
+      {disabledReason ? (
+        <p
+          className="text-xs text-muted-foreground"
+          data-testid="agent-respond-to-disabled-reason"
+        >
+          {disabledReason}
+        </p>
+      ) : null}
       {mode === "anyone" ? accessWarning : null}
       {mode === "owner-only" ? (
         <p className="text-xs text-muted-foreground">
-          Only you can send instructions.
+          Only you and your agents can send instructions.
         </p>
       ) : null}
       {mode === "allowlist" ? (
diff --git a/desktop/src/features/agents/ui/respondToFieldContract.test.mjs b/desktop/src/features/agents/ui/respondToFieldContract.test.mjs
index c3efd34650..91b4c6d1f6 100644
--- a/desktop/src/features/agents/ui/respondToFieldContract.test.mjs
+++ b/desktop/src/features/agents/ui/respondToFieldContract.test.mjs
@@ -55,6 +55,16 @@ test("the warning copy comes from the shared helper, not inline text", () => {
   assert.match(collapsedSource, /<p aria-live="polite"[^>]*> \{warningText\}/);
 });
 
+test("the Only me line names the owner's agents, not the owner alone", () => {
+  // The harness gate admits the owner and every verified same-owner agent
+  // (`managed_agents/access_policy.rs`), and the built-in Welcome team depends
+  // on that, so a line promising the owner alone would overstate the boundary.
+  assert.match(
+    collapsedSource,
+    /mode === "owner-only" \? \( <p[^>]*> Only you and your agents can send instructions\./,
+  );
+});
+
 test("primary respond-to copy does not expose implementation jargon", () => {
   const primaryFieldSource = respondToFieldSource.slice(
     respondToFieldSource.indexOf('data-testid="agent-respond-to"'),
diff --git a/desktop/src/features/agents/useAgentAccessOwnerOnly.ts b/desktop/src/features/agents/useAgentAccessOwnerOnly.ts
new file mode 100644
index 0000000000..d5de995334
--- /dev/null
+++ b/desktop/src/features/agents/useAgentAccessOwnerOnly.ts
@@ -0,0 +1,25 @@
+/**
+ * React hook: report whether this build forces owner-only agent access.
+ *
+ * The value is baked at build time, so it cannot change while the app runs.
+ * The query key is stable and the result never goes stale, which keeps one
+ * fetch per QueryClient lifetime and gives every caller the same answer.
+ */
+import { useQuery } from "@tanstack/react-query";
+
+import { getAgentAccessOwnerOnly } from "@/shared/api/tauriAgentAccess";
+
+export const agentAccessOwnerOnlyQueryKey = [
+  "agent-access-owner-only",
+] as const;
+
+export function useAgentAccessOwnerOnlyQuery(options?: { enabled?: boolean }) {
+  return useQuery({
+    queryKey: agentAccessOwnerOnlyQueryKey,
+    queryFn: () => getAgentAccessOwnerOnly(),
+    enabled: options?.enabled ?? true,
+    staleTime: Infinity,
+    refetchInterval: false,
+    retry: false,
+  });
+}
diff --git a/desktop/src/features/channels/ui/EditRespondToDialog.tsx b/desktop/src/features/channels/ui/EditRespondToDialog.tsx
index d9f091e902..d3c3df339b 100644
--- a/desktop/src/features/channels/ui/EditRespondToDialog.tsx
+++ b/desktop/src/features/channels/ui/EditRespondToDialog.tsx
@@ -1,8 +1,12 @@
 import * as React from "react";
 
 import { useUpdateManagedAgentMutation } from "@/features/agents/hooks";
+import { useAgentAccessOwnerOnlyQuery } from "@/features/agents/useAgentAccessOwnerOnly";
 import { runLocationForBackend } from "@/features/agents/lib/agentAccessWarning";
-import { CreateAgentRespondToField } from "@/features/agents/ui/RespondToField";
+import {
+  CreateAgentRespondToField,
+  OWNER_ONLY_ACCESS_DISABLED_REASON,
+} from "@/features/agents/ui/RespondToField";
 import type { ManagedAgent, RespondToMode } from "@/shared/api/types";
 import { Button } from "@/shared/ui/button";
 import {
@@ -25,6 +29,10 @@ export function EditRespondToDialog({
   open: boolean;
 }) {
   const updateMutation = useUpdateManagedAgentMutation();
+  const { data: agentAccessOwnerOnly } = useAgentAccessOwnerOnlyQuery({
+    enabled: open,
+  });
+  const accessLocked = agentAccessOwnerOnly === true;
   const [respondTo, setRespondTo] = React.useState<RespondToMode>("owner-only");
   const [respondToAllowlist, setRespondToAllowlist] = React.useState<string[]>(
     [],
@@ -61,9 +69,12 @@ export function EditRespondToDialog({
           </DialogDescription>
         </DialogHeader>
         <CreateAgentRespondToField
-          allowlist={respondToAllowlist}
-          disabled={updateMutation.isPending}
-          mode={respondTo}
+          allowlist={accessLocked ? [] : respondToAllowlist}
+          disabled={updateMutation.isPending || accessLocked}
+          disabledReason={
+            accessLocked ? OWNER_ONLY_ACCESS_DISABLED_REASON : undefined
+          }
+          mode={accessLocked ? "owner-only" : respondTo}
           onAllowlistChange={setRespondToAllowlist}
           onModeChange={setRespondTo}
           ownerPubkey={currentPubkey}
@@ -84,7 +95,9 @@ export function EditRespondToDialog({
             Cancel
           </Button>
           <Button
-            disabled={!respondToValid || updateMutation.isPending}
+            disabled={
+              !respondToValid || updateMutation.isPending || accessLocked
+            }
             onClick={() => void handleSave()}
             size="sm"
             type="button"
diff --git a/desktop/src/features/onboarding/welcomeGuide.test.mjs b/desktop/src/features/onboarding/welcomeGuide.test.mjs
index b3def930f1..59af9c75d3 100644
--- a/desktop/src/features/onboarding/welcomeGuide.test.mjs
+++ b/desktop/src/features/onboarding/welcomeGuide.test.mjs
@@ -9,6 +9,8 @@ import {
   pickWelcomeGuideAgentForRelay,
   pickWelcomeTeamStarterAgentForRelay,
   welcomeStarterRuntimeUpdate,
+  welcomeTeammateAccessUpdate,
+  welcomeTeammateHasExpectedAccess,
   WELCOME_GUIDE_AGENT_NAME,
   WELCOME_GUIDE_PERSONA_ID,
   WELCOME_TEAM_ID,
@@ -379,3 +381,74 @@ test("starter matching prefers running, then deployed instances", () => {
     deployed,
   );
 });
+
+test("owner-only-access policy accepts local Welcome teammates", () => {
+  const teammate = makeAgent({
+    respondTo: "owner-only",
+    respondToAllowlist: [],
+  });
+  assert.equal(welcomeTeammateHasExpectedAccess(teammate, PUB_B, true), true);
+  assert.equal(welcomeTeammateHasExpectedAccess(teammate, PUB_B, false), false);
+});
+
+test("access remediation converges for an upgraded owner-only install", () => {
+  // Pre-existing installs allowlisted the lead. An owner-only build must move
+  // them to owner-only, and the write it makes must satisfy the predicate, so
+  // the next provisioning pass makes no further write.
+  const allowlisted = makeAgent({
+    respondTo: "allowlist",
+    respondToAllowlist: [PUB_B],
+  });
+  const update = welcomeTeammateAccessUpdate(allowlisted, PUB_B, true);
+  assert.deepEqual(update, {
+    pubkey: PUB_A,
+    respondTo: "owner-only",
+    respondToAllowlist: [],
+  });
+  const remediated = makeAgent({
+    respondTo: update.respondTo,
+    respondToAllowlist: update.respondToAllowlist,
+  });
+  assert.equal(welcomeTeammateHasExpectedAccess(remediated, PUB_B, true), true);
+  assert.equal(welcomeTeammateAccessUpdate(remediated, PUB_B, true), null);
+});
+
+test("access remediation allowlists the lead when the build is not owner-only", () => {
+  const ownerOnly = makeAgent({
+    respondTo: "owner-only",
+    respondToAllowlist: [],
+  });
+  const update = welcomeTeammateAccessUpdate(ownerOnly, PUB_B, false);
+  assert.deepEqual(update, {
+    pubkey: PUB_A,
+    respondTo: "allowlist",
+    respondToAllowlist: [PUB_B],
+  });
+  const remediated = makeAgent({
+    respondTo: update.respondTo,
+    respondToAllowlist: update.respondToAllowlist,
+  });
+  assert.equal(
+    welcomeTeammateHasExpectedAccess(remediated, PUB_B, false),
+    true,
+  );
+  assert.equal(welcomeTeammateAccessUpdate(remediated, PUB_B, false), null);
+});
+
+test("access remediation skips a teammate that already allows the lead", () => {
+  const allowlisted = makeAgent({
+    respondTo: "allowlist",
+    respondToAllowlist: [PUB_B, PUB_C],
+  });
+  assert.equal(welcomeTeammateAccessUpdate(allowlisted, PUB_B, false), null);
+});
+
+test("owner-only-access policy accepts provider Welcome teammates", () => {
+  const teammate = makeAgent({
+    backend: { type: "provider", id: "remote", config: {} },
+    respondTo: "owner-only",
+    respondToAllowlist: [],
+  });
+  assert.equal(welcomeTeammateHasExpectedAccess(teammate, PUB_B, true), true);
+  assert.equal(welcomeTeammateHasExpectedAccess(teammate, PUB_B, false), false);
+});
diff --git a/desktop/src/features/onboarding/welcomeGuide.ts b/desktop/src/features/onboarding/welcomeGuide.ts
index aa8deb7c19..82b6886d74 100644
--- a/desktop/src/features/onboarding/welcomeGuide.ts
+++ b/desktop/src/features/onboarding/welcomeGuide.ts
@@ -10,6 +10,7 @@ import {
   listManagedAgents,
   updateManagedAgent,
 } from "@/shared/api/tauri";
+import { getAgentAccessOwnerOnly } from "@/shared/api/tauriAgentAccess";
 import { getGlobalAgentConfig } from "@/shared/api/tauriGlobalAgentConfig";
 import { listPersonas, setPersonaActive } from "@/shared/api/tauriPersonas";
 import type {
@@ -17,6 +18,7 @@ import type {
   AgentPersona,
   CreateManagedAgentInput,
   ManagedAgent,
+  UpdateManagedAgentInput,
 } from "@/shared/api/types";
 import { normalizePubkey } from "@/shared/lib/pubkey";
 
@@ -260,6 +262,58 @@ export function welcomeStarterRuntimeUpdate(
   };
 }
 
+export function welcomeTeammateHasExpectedAccess(
+  teammate: ManagedAgent,
+  leadPubkey: string,
+  agentAccessOwnerOnly: boolean,
+) {
+  if (agentAccessOwnerOnly) {
+    // Welcome teammates are created owner-only, and the lead remains authorized
+    // as a NIP-OA-verified sibling because every Welcome agent shares one owner.
+    return (
+      teammate.respondTo === "owner-only" &&
+      teammate.respondToAllowlist.length === 0
+    );
+  }
+  return (
+    teammate.respondTo === "allowlist" &&
+    teammate.respondToAllowlist.some(
+      (pubkey) => normalizePubkey(pubkey) === normalizePubkey(leadPubkey),
+    )
+  );
+}
+
+/**
+ * The access write that moves a Welcome teammate to the state this build
+ * expects, or null when it is already there. The remediation target must track
+ * {@link welcomeTeammateHasExpectedAccess}: writing `allowlist:[lead]` in an
+ * owner-only build would fail the predicate again on the next provisioning
+ * pass, so an upgraded install with pre-existing allowlisted teammates would
+ * rewrite the same rejected state forever and keep restarting them.
+ */
+export function welcomeTeammateAccessUpdate(
+  teammate: ManagedAgent,
+  leadPubkey: string,
+  agentAccessOwnerOnly: boolean,
+): UpdateManagedAgentInput | null {
+  if (
+    welcomeTeammateHasExpectedAccess(teammate, leadPubkey, agentAccessOwnerOnly)
+  ) {
+    return null;
+  }
+  return agentAccessOwnerOnly
+    ? {
+        pubkey: teammate.pubkey,
+        respondTo: "owner-only",
+        respondToAllowlist: [],
+      }
+    : {
+        pubkey: teammate.pubkey,
+        respondTo: "allowlist",
+        respondToAllowlist: [leadPubkey],
+      };
+}
+
 /**
  * Ensure the complete built-in Welcome Team is ready for kickoff.
  * The team itself is Rust-seeded; this only activates personas, creates any
@@ -271,11 +325,13 @@ async function provisionWelcomeTeam(
 ): Promise<WelcomeTeamAgents> {
   const existingAgents = await listManagedAgents();
   await ensureWelcomeTeamPersonasActive();
-  const [personas, runtimeCatalog, globalConfig] = await Promise.all([
-    listPersonas(),
-    discoverAcpRuntimes(),
-    getGlobalAgentConfig(),
-  ]);
+  const [personas, runtimeCatalog, globalConfig, agentAccessOwnerOnly] =
+    await Promise.all([
+      listPersonas(),
+      discoverAcpRuntimes(),
+      getGlobalAgentConfig(),
+      getAgentAccessOwnerOnly(),
+    ]);
   const personasById = new Map(
     personas.map((persona) => [persona.id, persona]),
   );
@@ -322,17 +378,13 @@ async function provisionWelcomeTeam(
   const leadPubkey = lead.pubkey;
   for (const index of [1, 2] as const) {
     const teammate = welcomeAgents[index];
-    const alreadyAllowsLead =
-      teammate.respondTo === "allowlist" &&
-      teammate.respondToAllowlist.some(
-        (pubkey) => normalizePubkey(pubkey) === normalizePubkey(leadPubkey),
-      );
-    if (!alreadyAllowsLead) {
-      const updated = await updateManagedAgent({
-        pubkey: teammate.pubkey,
-        respondTo: "allowlist",
-        respondToAllowlist: [leadPubkey],
-      });
+    const accessUpdate = welcomeTeammateAccessUpdate(
+      teammate,
+      leadPubkey,
+      agentAccessOwnerOnly,
+    );
+    if (accessUpdate) {
+      const updated = await updateManagedAgent(accessUpdate);
       welcomeAgents[index] = updated.agent;
     }
   }
diff --git a/desktop/src/features/onboarding/welcomeKickoff.test.mjs b/desktop/src/features/onboarding/welcomeKickoff.test.mjs
index 6f472b8068..736721434a 100644
--- a/desktop/src/features/onboarding/welcomeKickoff.test.mjs
+++ b/desktop/src/features/onboarding/welcomeKickoff.test.mjs
@@ -199,6 +199,47 @@ test("running teammates restart when their allowlist does not include the lead",
   );
 });
 
+test("owner-only-access policy does not restart running local and provider teammates", () => {
+  for (const backend of [
+    { type: "local" },
+    { type: "provider", id: "remote", config: {} },
+  ]) {
+    assert.equal(
+      welcomeTeammateNeedsRestart(
+        {
+          ...honey,
+          backend,
+          status: "running",
+          needsRestart: false,
+          respondTo: "owner-only",
+          respondToAllowlist: [],
+        },
+        fizz.pubkey,
+        true,
+      ),
+      false,
+    );
+  }
+});
+
+test("owner-only-access policy still restarts running teammates for runtime changes", () => {
+  assert.equal(
+    welcomeTeammateNeedsRestart(
+      {
+        ...honey,
+        backend: { type: "local" },
+        status: "running",
+        needsRestart: true,
+        respondTo: "owner-only",
+        respondToAllowlist: [],
+      },
+      fizz.pubkey,
+      true,
+    ),
+    true,
+  );
+});
+
 test("opener keeps partial-readiness warm and mentions only online teammates", () => {
   const agentSet = { lead: fizz, teammates: [honey, bumble] };
   const introTeammates = selectWelcomeKickoffIntroTeammates(
diff --git a/desktop/src/features/onboarding/welcomeKickoff.ts b/desktop/src/features/onboarding/welcomeKickoff.ts
index 57352b5294..f46aeb3b21 100644
--- a/desktop/src/features/onboarding/welcomeKickoff.ts
+++ b/desktop/src/features/onboarding/welcomeKickoff.ts
@@ -5,6 +5,7 @@ import {
   useAcpRuntimesQuery,
   useManagedAgentsQuery,
 } from "@/features/agents/hooks";
+import { useAgentAccessOwnerOnlyQuery } from "@/features/agents/useAgentAccessOwnerOnly";
 import { useGlobalAgentConfig } from "@/features/agents/useGlobalAgentConfig";
 import { clearActiveTurnsForAgentOnStop } from "@/features/agents/managedAgentRuntimeHooks";
 import { useCommunities } from "@/features/communities/useCommunities";
@@ -15,6 +16,7 @@ import {
   pickWelcomeTeamStarterAgentForRelay,
   WELCOME_TEAM_STARTERS,
   type WelcomeTeamStarterDefinition,
+  welcomeTeammateHasExpectedAccess,
 } from "@/features/onboarding/welcomeGuide";
 import { isWelcomeChannel } from "@/features/onboarding/welcome";
 import { getThreadReference } from "@/features/messages/lib/threading";
@@ -358,13 +360,15 @@ async function markerExists(channelId: string, marker: string) {
 export function welcomeTeammateNeedsRestart(
   agent: ManagedAgent,
   leadPubkey: string,
+  agentAccessOwnerOnly = false,
 ) {
   return (
     agent.status === "running" &&
     (agent.needsRestart ||
-      agent.respondTo !== "allowlist" ||
-      !agent.respondToAllowlist.some(
-        (pubkey) => normalizePubkey(pubkey) === normalizePubkey(leadPubkey),
+      !welcomeTeammateHasExpectedAccess(
+        agent,
+        leadPubkey,
+        agentAccessOwnerOnly,
       ))
   );
 }
@@ -496,6 +500,8 @@ export function useWelcomeKickoff(
   const { activeCommunity } = useCommunities();
   const runtimesQuery = useAcpRuntimesQuery();
   const managedAgentsQuery = useManagedAgentsQuery();
+  const agentAccessOwnerOnlyQuery = useAgentAccessOwnerOnlyQuery();
+  const agentAccessOwnerOnly = agentAccessOwnerOnlyQuery.data;
   const { globalConfig, isLoading: configLoading } = useGlobalAgentConfig();
   const channelId = activeChannel?.id ?? null;
   const isActiveWelcome = isWelcomeChannel(activeChannel);
@@ -556,7 +562,8 @@ export function useWelcomeKickoff(
       !channelId ||
       !isActiveWelcome ||
       configLoading ||
-      runtimesQuery.isPending
+      runtimesQuery.isPending ||
+      agentAccessOwnerOnly === undefined
     ) {
       return;
     }
@@ -610,7 +617,11 @@ export function useWelcomeKickoff(
             );
             if (
               isTeammate &&
-              welcomeTeammateNeedsRestart(agent, resolvedAgentSet.lead.pubkey)
+              welcomeTeammateNeedsRestart(
+                agent,
+                resolvedAgentSet.lead.pubkey,
+                agentAccessOwnerOnly,
+              )
             ) {
               return restartWelcomeTeammate(agent, {
                 onStopped: () => clearActiveTurnsForAgentOnStop(agent.pubkey),
@@ -687,6 +698,7 @@ export function useWelcomeKickoff(
     })();
   }, [
     activeCommunity?.relayUrl,
+    agentAccessOwnerOnly,
     channelId,
     configLoading,
     isActiveWelcome,
diff --git a/desktop/src/shared/api/tauriAgentAccess.ts b/desktop/src/shared/api/tauriAgentAccess.ts
new file mode 100644
index 0000000000..2fcb7c1622
--- /dev/null
+++ b/desktop/src/shared/api/tauriAgentAccess.ts
@@ -0,0 +1,4 @@
+import { invokeTauri } from "@/shared/api/tauri";
+
+export const getAgentAccessOwnerOnly = () =>
+  invokeTauri<boolean>("agent_access_owner_only");
diff --git a/desktop/src/testing/e2eBridge.ts b/desktop/src/testing/e2eBridge.ts
index 53dc3aca0d..54238323ae 100644
--- a/desktop/src/testing/e2eBridge.ts
+++ b/desktop/src/testing/e2eBridge.ts
@@ -444,6 +444,8 @@ type E2eConfig = {
       model: string | null;
       preferred_runtime?: string | null;
     };
+    /** Explicit owner-only agent-access capability; independent of baked defaults. */
+    ownerOnlyAccessBuild?: boolean;
     /** File-layer config returned by runtime id. */
     runtimeFileConfigs?: Record<string, RuntimeFileConfigSubset | null>;
     /** Baked build env returned by the display and key-name Tauri commands. */
@@ -12340,6 +12342,8 @@ export function maybeInstallE2eTauriMocks() {
       }
       case "get_baked_build_env_keys":
         return (config?.mock?.bakedBuildEnv ?? []).map((entry) => entry.key);
+      case "agent_access_owner_only":
+        return config?.mock?.ownerOnlyAccessBuild ?? false;
       case "update_managed_agent":
         return handleUpdateManagedAgent(
           payload as Parameters<typeof handleUpdateManagedAgent>[0],
diff --git a/desktop/tests/e2e/edit-agent.spec.ts b/desktop/tests/e2e/edit-agent.spec.ts
index 95ef231556..4c4834b552 100644
--- a/desktop/tests/e2e/edit-agent.spec.ts
+++ b/desktop/tests/e2e/edit-agent.spec.ts
@@ -78,7 +78,82 @@ async function pickDropdownOption(
   await page.getByRole("menuitemradio", { name: optionName }).click();
 }
 
+test.describe("agent definition dialog", () => {
+  test("owner-only-access build shows disabled agent access with an explanation", async ({
+    page,
+  }) => {
+    await installMockBridge(page, {
+      ownerOnlyAccessBuild: true,
+      bakedBuildEnv: BAKED_DEFAULTS,
+    });
+    await page.goto("/");
+    await page.getByTestId("open-agents-view").click();
+    await page.getByTestId("new-agent-card").click();
+    await page.getByRole("menuitem", { name: "Create agent" }).click();
+
+    const dialog = page.getByRole("dialog");
+    await dialog.getByRole("button", { name: "Advanced", exact: true }).click();
+
+    await expect(dialog.getByTestId("agent-respond-to")).toBeVisible();
+    await expect(dialog.locator("#agent-respond-to")).toBeDisabled();
+    await expect(dialog.locator("#agent-respond-to")).toContainText(
+      "Only me (default)",
+    );
+    await expect(
+      dialog.getByTestId("agent-respond-to-disabled-reason"),
+    ).toHaveText("This build disallows changing this setting.");
+  });
+});
+
 test.describe("edit agent dialog", () => {
+  test("owner-only-access build shows a disabled owner-only access control with an explanation", async ({
+    page,
+  }) => {
+    await installMockBridge(page, {
+      ownerOnlyAccessBuild: true,
+      bakedBuildEnv: BAKED_DEFAULTS,
+      managedAgents: [
+        {
+          pubkey: AGENT_PUBKEY,
+          name: AGENT_NAME,
+          status: "stopped",
+          channelNames: ["agents"],
+          respondTo: "anyone",
+        },
+      ],
+    });
+
+    await openEditDialog(page);
+
+    const accessControl = page.getByTestId("agent-respond-to");
+    await expect(accessControl).toBeVisible();
+    await expect(page.locator("#agent-respond-to")).toBeDisabled();
+    await expect(page.locator("#agent-respond-to")).toContainText(
+      "Only me (default)",
+    );
+    await expect(
+      page.getByTestId("agent-respond-to-disabled-reason"),
+    ).toHaveText("This build disallows changing this setting.");
+  });
+
+  test("OSS build keeps the managed-agent access control", async ({ page }) => {
+    await installMockBridge(page, {
+      bakedBuildEnv: BAKED_DEFAULTS,
+      managedAgents: [
+        {
+          pubkey: AGENT_PUBKEY,
+          name: AGENT_NAME,
+          status: "stopped",
+          channelNames: ["agents"],
+        },
+      ],
+    });
+
+    await openEditDialog(page);
+
+    await expect(page.getByTestId("agent-respond-to")).toBeVisible();
+  });
+
   test("edits the agent name and persists it across a dialog reopen", async ({
     page,
   }) => {
diff --git a/desktop/tests/helpers/bridge.ts b/desktop/tests/helpers/bridge.ts
index 1b7f84a88d..0234254410 100644
--- a/desktop/tests/helpers/bridge.ts
+++ b/desktop/tests/helpers/bridge.ts
@@ -430,6 +430,7 @@ type MockBridgeOptions = {
     model: string | null;
     preferred_runtime?: string | null;
   };
+  ownerOnlyAccessBuild?: boolean;
   /** File-layer config returned by runtime id. */
   runtimeFileConfigs?: Record<
     string,

From e2796d4a8907586b457a65675c2c88c818973173 Mon Sep 17 00:00:00 2001
From: Wes <wesbillman@users.noreply.github.com>
Date: Wed, 5 Aug 2026 20:42:04 -0600
Subject: [PATCH 05/16] fix(desktop): virtualize channel member lists (#4991)

## Summary

- virtualize the unfiltered channel member roster instead of eagerly
mounting every member card
- retain the existing member search/add flow and archived-member
behavior
- cover a 500-member roster, bounded mounted rows, and scrolling to the
final member in E2E

## Cause

The members sidebar rendered every active member card at once. On large
channels this mounted hundreds or thousands of avatars, profile/presence
consumers, menus, and DOM rows, blocking the renderer even though
fetching the roster itself is fast.

## Testing

- `pnpm typecheck`
- `pnpm exec biome check src/features/channels/ui/MembersSidebar.tsx
tests/e2e/channels.spec.ts`
- `pnpm build:e2e`
- `pnpm exec playwright test tests/e2e/channels.spec.ts --grep 'members
sidebar (virtualizes large channel rosters|can invite relay-authorized
agents|can invite and remove managed agents|collapses same-persona
managed agents)'` (4 passed)
- pre-push: `desktop-check`, full `desktop-test` (4,371 passed),
branch-skew

Implemented by Carl on Wes's behalf.

Signed-off-by: Wes <wesbillman@users.noreply.github.com>
Co-authored-by: Carl <c7ebe626f000404285d3686e1dc74cc07cc60a9754a150041ba132e14bd3e2ec@buzz.block.builderlab.xyz>
---
 .../features/channels/ui/MembersSidebar.tsx   | 17 +++++-----
 desktop/tests/e2e/channels.spec.ts            | 34 +++++++++++++++++++
 2 files changed, 43 insertions(+), 8 deletions(-)

diff --git a/desktop/src/features/channels/ui/MembersSidebar.tsx b/desktop/src/features/channels/ui/MembersSidebar.tsx
index 2659a9c1d4..459e8f7776 100644
--- a/desktop/src/features/channels/ui/MembersSidebar.tsx
+++ b/desktop/src/features/channels/ui/MembersSidebar.tsx
@@ -30,6 +30,7 @@ import {
 import { formatOwnerLabel } from "@/features/profile/lib/identity";
 import { rankUserCandidatesBySearch } from "@/features/profile/lib/userCandidateSearch";
 import { usePresenceQuery } from "@/features/presence/hooks";
+import { VirtualizedList } from "@/shared/ui/VirtualizedList";
 import { useIdentityQuery } from "@/shared/api/hooks";
 import { changeChannelMemberRole } from "@/shared/api/tauri";
 import type {
@@ -199,7 +200,6 @@ export function MembersSidebar({
       ),
     [bots, currentPubkey, people],
   );
-
   const allMemberPubkeys = React.useMemo(
     () => rawMembers.map((member) => member.pubkey),
     [rawMembers],
@@ -217,9 +217,7 @@ export function MembersSidebar({
     if (!normalizedSearchQuery) {
       return activeMembers;
     }
-
     const profiles = memberProfilesQuery.data?.profiles ?? {};
-
     return activeMembers.filter((member) => {
       const normalizedPubkey = normalizePubkey(member.pubkey);
       const profile = profiles[normalizedPubkey] ?? null;
@@ -816,11 +814,14 @@ export function MembersSidebar({
                     ) : null}
                   </div>
                 ) : filteredActiveMembers.length > 0 ? (
-                  <div>
-                    {filteredActiveMembers.map((member) =>
-                      renderMemberCard(member, isBot(member)),
-                    )}
-                  </div>
+                  <VirtualizedList
+                    className="h-[calc(100%_-_2.25rem)]"
+                    getItemKey={(member) => member.pubkey}
+                    items={filteredActiveMembers}
+                    renderItem={(member) =>
+                      renderMemberCard(member, isBot(member))
+                    }
+                  />
                 ) : (
                   <p className="px-4 py-3 text-sm text-muted-foreground">
                     {membersQuery.isLoading
diff --git a/desktop/tests/e2e/channels.spec.ts b/desktop/tests/e2e/channels.spec.ts
index ac9d5318e5..d58c3303df 100644
--- a/desktop/tests/e2e/channels.spec.ts
+++ b/desktop/tests/e2e/channels.spec.ts
@@ -3394,6 +3394,40 @@ test("home inbox manage affordance opens management without leaving home", async
   await expect(page).not.toHaveURL(/#\/channels\//);
 });
 
+test("members sidebar virtualizes large channel rosters", async ({ page }) => {
+  await page.goto("/");
+  const channelId = await page
+    .getByTestId("channel-random")
+    .getAttribute("data-channel-id");
+  if (!channelId) {
+    throw new Error("Random channel id missing.");
+  }
+
+  const pubkeys = Array.from({ length: 500 }, (_, index) =>
+    (index + 1).toString(16).padStart(64, "0"),
+  );
+  await invokeMockCommand(page, "add_channel_members", {
+    channelId,
+    pubkeys,
+    role: "member",
+  });
+
+  await openMembersSidebar(page, "random");
+  const memberList = page.getByTestId("members-sidebar-people");
+  const memberRows = memberList.locator('[data-testid^="sidebar-member-"]');
+  await expect(memberRows.first()).toBeVisible();
+  expect(await memberRows.count()).toBeLessThan(50);
+
+  const virtualizedList = memberList.locator(".overflow-y-auto");
+  await virtualizedList.evaluate((element) => {
+    element.scrollTop = element.scrollHeight;
+    element.dispatchEvent(new Event("scroll"));
+  });
+  await expect(
+    memberList.getByTestId(`sidebar-member-${pubkeys.at(-1)}`),
+  ).toBeVisible();
+});
+
 test("members sidebar can invite relay-authorized agents", async ({ page }) => {
   await installMockBridge(page, {
     relayAgents: [

From 38bf642fcfa7a9fc1e06d6cf87d66ae94da29341 Mon Sep 17 00:00:00 2001
From: Michael Neale <michael.neale@gmail.com>
Date: Thu, 6 Aug 2026 13:13:16 +1000
Subject: [PATCH 06/16] =?UTF-8?q?ci:=20prove=20the=20relay-driven=20mesh?=
 =?UTF-8?q?=20lifecycle=20=E2=80=94=20discover,=20join,=20infer,=20deny=20?=
 =?UTF-8?q?=E2=80=94=20with=20real=20nodes=20(#3862)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

CI now proves the full Buzz shared-compute join story end to end: a
member can discover another member's served model **through the Buzz
relay alone** and run inference over the mesh, while a non-member gets
nothing — the relay rejects its auth, and the mesh refuses to route for
it even holding a leaked endpoint address.

This is deliberately different from mesh-llm's own CI smokes (which
bootstrap two nodes with a hand-carried invite token / mdns): here the
**relay is the control plane**, exactly like the desktop app:

1. **Membership** — identities A and B are added via `buzz-admin`
(kind:13534 NIP-43 roster); C is not.
2. **Advertise** — each member publishes a client-signed kind:30003
discovery note carrying its MeshLLM owner binding and (for the serve
node) `serveTargets[].endpointAddr`, covered by an endpoint-binding
signature — the exact payload shape the desktop coordinator publishes.
3. **Trust** — the serve node derives its admission allowlist from the
relay (statuses ∩ roster) and requires the **exact expected {A, B}
owner-id set** before starting with `TrustPolicy::Allowlist`.
4. **Join** — the client verifies owner + endpoint bindings and
membership, then dials the relay-discovered endpoint (the desktop
join-watcher's `dial_endpoint_addr` step). No out-of-band token.
5. **Infer** — a chat completion against the client's local OpenAI
endpoint routes over QUIC to the serve node's model (CPU, SmolLM2-135M,
~105MB).
6. **Deny (differential)** — the stranger's NIP-42 auth must fail with
the relay's own membership rejection (`restricted: not a relay member` —
successful auth or any unrelated connect error fails the run), and
dialing the leaked endpoint must not produce a routed inference —
**while the trusted client re-proves inference immediately afterwards**,
so a dead serve node can't masquerade as an admission denial.

## What's in the PR

- `crates/buzz-relay/examples/mesh_relay_lifecycle_smoke.rs` — the
harness. One process per node (mesh-llm keeps process-global state under
`~/.mesh-llm`), orchestrator + serve/client/stranger roles,
byte-identical binding payloads to
`desktop/src-tauri/src/mesh_llm/identity.rs` (called out with
keep-in-sync comments). Child stdout is pumped through a reader thread
so every wait has a hard deadline; timed-out children are killed; exit
statuses are checked.
- `scripts/ci-mesh-lifecycle-smoke.sh` — provisions a membership-gated
relay (throwaway owner + signing identities via `buzz-admin
generate-key`), runs the harness, cleans up. Fails fast if :3000 is
already occupied (a stale open relay would mask gating).
- `scripts/start-relay-for-tests.sh` — gains opt-in NIP-43 membership
env passthrough (`BUZZ_REQUIRE_RELAY_MEMBERSHIP` + `RELAY_OWNER_PUBKEY`
+ `BUZZ_RELAY_PRIVATE_KEY`). Default behavior unchanged.
- `.github/workflows/mesh-lifecycle.yml` — separate, path-filtered,
non-required workflow (mesh paths, the harness's dependency crates,
`Cargo.lock`, dispatch), pinned to `ubuntu-24.04`. Caches the mesh
native runtime + HF model keyed on the lockfile hash, so a mesh pin bump
rolls the runtime cache. Uploads relay + harness logs on failure.

## Scope

This is an **independent protocol harness**: it speaks the same wire
protocol and payload shapes as the desktop but re-implements the
binding/verification logic (the desktop crate is outside the workspace).
Regressions inside the desktop's own discovery filtering are the desktop
unit tests' job; what this smoke proves is that the relay + mesh-llm SDK
+ admission stack support the lifecycle end to end.

## Relationship to mesh-llm's CI

Follows the shape mesh-llm's own CI proved stable (tiny CPU model, one
runner, multiple real mesh-llm processes over real QUIC — cf. their
`ci-two-node-client-serving-smoke.sh`), but swaps the token bootstrap
for the relay-driven lifecycle, which is the part only Buzz can test.

## Validation

Green on GitHub Actions (ubuntu-24.04) across three runs, including
after rebases onto the mesh v0.74 upgrade (#3467) and latest main:

```
PASS 1/6: relay-derived allowlist is exactly {A, B}
PASS 2/6: serve member ready + advertised model: jc-builds/SmolLM2-135M-Instruct-Q4_K_M-GGUF:Q4_K_M
PASS 3/6: client member discovered + joined via relay
PASS 4/6: inference routed over the mesh: "PONG"
PASS 5/6: relay rejected the stranger's NIP-42 auth (membership gate)
PASS 6/6: stranger denied (gossip visible, inference rejected: 503 all tunnels failed) while trusted inference still routes
PASS: full relay-driven mesh lifecycle verified
```

Also validated locally on macOS. `cargo fmt --all --check` and `cargo
clippy -p buzz-relay --all-targets -- -D warnings` pass.

## Notes

- The harness follows the repo's mesh `[dev-dependencies]` pin
automatically, so it doubles as a canary for future mesh upgrades (it
already caught the v0.73.1 → v0.74.0 bump during development).
- The stranger "deny" accepts either shape mesh-llm exhibits: no model
visibility at all, or gossip visibility with inference refused —
mesh-llm applies the receiving node's owner policy after the gossip
handshake, so admission gates *routing*, not gossip. The differential
trusted-inference re-check (PASS 6/6) is what makes that a real denial
rather than a dead server.
- Model-visibility windows are tunable via `MESH_CLIENT_WINDOW_SECS` /
`MESH_STRANGER_WINDOW_SECS` if shared runners prove slow — pin a longer
window in the workflow env rather than re-running the job.

---------

Signed-off-by: Michael Neale <michael.neale@gmail.com>
---
 .github/workflows/mesh-lifecycle.yml          |  111 ++
 Cargo.lock                                    |    2 +
 crates/buzz-relay/Cargo.toml                  |    5 +
 .../examples/mesh_relay_lifecycle_smoke.rs    | 1065 +++++++++++++++++
 scripts/ci-mesh-lifecycle-smoke.sh            |  113 ++
 scripts/start-relay-for-tests.sh              |   15 +
 6 files changed, 1311 insertions(+)
 create mode 100644 .github/workflows/mesh-lifecycle.yml
 create mode 100644 crates/buzz-relay/examples/mesh_relay_lifecycle_smoke.rs
 create mode 100755 scripts/ci-mesh-lifecycle-smoke.sh

diff --git a/.github/workflows/mesh-lifecycle.yml b/.github/workflows/mesh-lifecycle.yml
new file mode 100644
index 0000000000..4780083ba4
--- /dev/null
+++ b/.github/workflows/mesh-lifecycle.yml
@@ -0,0 +1,111 @@
+name: Mesh Lifecycle
+# Relay-driven mesh lifecycle smoke: membership → signed discovery notes →
+# relay-derived allowlist → join → CPU inference over QUIC → stranger denied
+# (relay membership rejection + no routed inference, with a differential
+# trusted-inference health proof so a dead serve node can't fake a denial).
+# Runs the full Buzz "shared compute" join story with three real mesh-llm
+# node processes on one runner, using the Buzz relay as the control plane
+# (no hand-carried invite tokens). Mirrors the shape mesh-llm's own CI uses
+# for its two-node smokes (tiny CPU model, one runner, real QUIC mesh).
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'crates/buzz-relay/examples/mesh_*.rs'
+      - 'crates/buzz-relay/Cargo.toml'
+      - 'crates/buzz-admin/**'
+      - 'crates/buzz-test-client/**'
+      - 'crates/buzz-ws-client/**'
+      - 'Cargo.lock'
+      - 'desktop/src-tauri/src/mesh_llm/**'
+      - 'scripts/ci-mesh-lifecycle-smoke.sh'
+      - 'scripts/start-relay-for-tests.sh'
+      - '.github/workflows/mesh-lifecycle.yml'
+  pull_request:
+    paths:
+      - 'crates/buzz-relay/examples/mesh_*.rs'
+      - 'crates/buzz-relay/Cargo.toml'
+      - 'crates/buzz-admin/**'
+      - 'crates/buzz-test-client/**'
+      - 'crates/buzz-ws-client/**'
+      - 'Cargo.lock'
+      - 'desktop/src-tauri/src/mesh_llm/**'
+      - 'scripts/ci-mesh-lifecycle-smoke.sh'
+      - 'scripts/start-relay-for-tests.sh'
+      - '.github/workflows/mesh-lifecycle.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: mesh-lifecycle-${{ github.event_name == 'pull_request' && github.ref || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  lifecycle-smoke:
+    name: Relay-Driven Mesh Lifecycle Smoke
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
+
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        with:
+          save-if: ${{ github.event_name != 'pull_request' }}
+
+      # The mesh-llm SDK downloads a signed native runtime (llama.cpp CPU
+      # build) on first init, and the serve node downloads the smoke model
+      # from HuggingFace on first run. Key on the lockfile so a mesh pin bump
+      # rolls the runtime cache; the model ref is stable.
+      - name: Restore mesh runtime + model caches
+        id: mesh-caches
+        uses: actions/cache/restore@caa296126883cff596d87d8935842f9db880ef25 # v5
+        with:
+          path: |
+            ~/.cache/mesh-llm/native-runtimes
+            ~/.cache/huggingface/hub
+          key: mesh-lifecycle-${{ runner.os }}-smollm2-135m-${{ hashFiles('Cargo.lock') }}
+          restore-keys: |
+            mesh-lifecycle-${{ runner.os }}-smollm2-135m-
+
+      - name: Start integration services
+        run: |
+          for attempt in 1 2 3; do
+            if docker compose up -d postgres redis minio minio-init; then
+              break
+            fi
+            if [ "$attempt" -eq 3 ]; then
+              echo "docker compose up failed after 3 attempts" >&2
+              exit 1
+            fi
+            echo "docker compose up failed (attempt $attempt), retrying in $((attempt * 5))s..." >&2
+            sleep $((attempt * 5))
+          done
+
+      - name: Run relay-driven mesh lifecycle smoke
+        run: ./scripts/ci-mesh-lifecycle-smoke.sh 2>&1 | tee /tmp/mesh-lifecycle-harness.log
+
+      - name: Save mesh runtime + model caches
+        if: github.ref == 'refs/heads/main' && steps.mesh-caches.outputs.cache-hit != 'true'
+        uses: actions/cache/save@caa296126883cff596d87d8935842f9db880ef25 # v5
+        with:
+          path: |
+            ~/.cache/mesh-llm/native-runtimes
+            ~/.cache/huggingface/hub
+          key: mesh-lifecycle-${{ runner.os }}-smollm2-135m-${{ hashFiles('Cargo.lock') }}
+
+      - name: Upload relay + harness logs
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: mesh-lifecycle-logs
+          path: |
+            /tmp/buzz-relay.log
+            /tmp/mesh-lifecycle-harness.log
+          if-no-files-found: ignore
diff --git a/Cargo.lock b/Cargo.lock
index 937ead564a..73ecb249d4 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1196,11 +1196,13 @@ dependencies = [
  "buzz-relay-mesh",
  "buzz-sdk",
  "buzz-search",
+ "buzz-test-client",
  "buzz-workflow",
  "bytes",
  "chrono",
  "dashmap",
  "deadpool-redis",
+ "ed25519-dalek",
  "flate2",
  "futures",
  "futures-util",
diff --git a/crates/buzz-relay/Cargo.toml b/crates/buzz-relay/Cargo.toml
index 41bdc3b9e9..cbad2a3b29 100644
--- a/crates/buzz-relay/Cargo.toml
+++ b/crates/buzz-relay/Cargo.toml
@@ -86,6 +86,11 @@ dev = ["buzz-auth/dev"]
 [dev-dependencies]
 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"] }
+# Relay-driven mesh lifecycle smoke (examples/mesh_relay_lifecycle_smoke.rs):
+# the relay client for discovery notes and the exact ed25519 the mesh owner
+# keys use for binding verification.
+buzz-test-client = { path = "../buzz-test-client" }
+ed25519-dalek = "=3.0.0-rc.0"
 buzz-core = { workspace = true, features = ["test-utils"] }
 buzz-auth = { workspace = true, features = ["dev"] }
 reqwest = { workspace = true }
diff --git a/crates/buzz-relay/examples/mesh_relay_lifecycle_smoke.rs b/crates/buzz-relay/examples/mesh_relay_lifecycle_smoke.rs
new file mode 100644
index 0000000000..7544ca09ea
--- /dev/null
+++ b/crates/buzz-relay/examples/mesh_relay_lifecycle_smoke.rs
@@ -0,0 +1,1065 @@
+//! Relay-driven mesh lifecycle smoke — the full Buzz join story, CI-shaped.
+//!
+//! Unlike `mesh_serve_client_smoke` (Mdns + hand-carried invite token) and
+//! `mesh_admission_smoke` (allowlist mechanics, token passed out-of-band),
+//! this harness exercises the *relay as the control plane*, the way the
+//! desktop app actually joins a mesh:
+//!
+//!   1. MEMBERSHIP — two Nostr identities are added to a membership-gated
+//!      buzz-relay (kind:13534 roster via buzz-admin); a third is not.
+//!   2. ADVERTISE — each member process publishes a client-signed kind:30003
+//!      status note carrying its MeshLLM owner binding
+//!      (`ownerId`/`ownerVerifyingKey`/`ownerBindingSig`) and, for the serve
+//!      node, `serveTargets[].endpointAddr` covered by an endpoint binding
+//!      signature — the exact payload shape the desktop coordinator publishes.
+//!   3. TRUST — the serve node derives its admission allowlist from the relay:
+//!      status notes ∩ membership roster, and requires the *exact* expected
+//!      owner set before starting with `TrustPolicy::Allowlist`.
+//!   4. JOIN — the client node discovers the serve target from the relay,
+//!      verifies both bindings and membership, and dials the advertised
+//!      endpoint. No token is ever handed over out-of-band.
+//!   5. INFER — a chat completion against the client's local OpenAI endpoint
+//!      routes over QUIC to the serve node's model.
+//!   6. DENY — the stranger's NIP-42 auth must fail with the relay's
+//!      membership rejection, and even when handed the leaked endpoint
+//!      address directly it must not complete an inference — *while the
+//!      trusted client re-verifies inference immediately afterwards*, so a
+//!      sick serve node cannot masquerade as an admission denial.
+//!
+//! ## Scope: an independent protocol harness
+//!
+//! This harness speaks the same wire protocol as the desktop
+//! (`desktop/src-tauri/src/mesh_llm/{identity,discovery,coordinator}.rs`) but
+//! deliberately re-implements the binding/verification logic rather than
+//! linking desktop code (the desktop crate is outside this workspace). The
+//! payloads and canonical binding bytes are kept byte-identical — see the
+//! keep-in-sync comments below. A regression inside the desktop's own
+//! discovery filtering is covered by the desktop unit tests, not this smoke;
+//! what this smoke proves is that the relay + mesh-llm SDK + admission stack
+//! actually support the lifecycle end to end.
+//!
+//! One process per node is load-bearing: mesh-llm keeps process-global state
+//! (node endpoint key, ownership attestation under `~/.mesh-llm`), so each
+//! role runs with an isolated HOME — exactly how the desktop runs it (one
+//! machine = one node).
+//!
+//! Run in CI via `scripts/ci-mesh-lifecycle-smoke.sh` (which provisions the
+//! membership-gated relay), or locally:
+//!
+//! ```text
+//! ./scripts/start-relay-for-tests.sh            # with membership env set
+//! cargo build --profile ci -p buzz-admin
+//! BUZZ_ADMIN_BIN=target/ci/buzz-admin \
+//!   cargo run --profile ci -p buzz-relay --example mesh_relay_lifecycle_smoke
+//! ```
+use std::collections::BTreeSet;
+use std::io::{BufRead, Write};
+use std::process::{Child, ChildStdout, Command, ExitStatus, Stdio};
+use std::sync::mpsc;
+use std::time::{Duration, Instant};
+
+use buzz_test_client::BuzzTestClient;
+use ed25519_dalek::{Signature, Verifier, VerifyingKey};
+use mesh_llm_host_runtime::crypto::{load_keystore, save_keystore, OwnerKeypair};
+use mesh_llm_sdk::{client, serve, MeshDiscoveryMode, TrustPolicy};
+use nostr::{Alphabet, Event, EventBuilder, Filter, Keys, Kind, SingleLetterTag, Tag};
+use sha2::{Digest, Sha256};
+
+/// NIP-51 bookmark set reused for client-owned mesh discovery notes
+/// (`KIND_BUZZ_MESH_MEMBER_STATUS` in the desktop coordinator).
+const KIND_MESH_STATUS: u16 = 30_003;
+/// NIP-43 membership roster snapshot.
+const KIND_MEMBERSHIP: u16 = 13_534;
+const STATUS_D_TAG_PREFIX: &str = "buzz-mesh-member-status";
+const STATUS_K_TAG: &str = "buzz-mesh-status";
+
+/// Small, real instruct model; same ref the sibling mesh examples use.
+const DEFAULT_MODEL: &str = "jc-builds/SmolLM2-135M-Instruct-Q4_K_M-GGUF:Q4_K_M";
+
+const SERVE_API_PORT: u16 = 19_537;
+const SERVE_CONSOLE_PORT: u16 = 13_331;
+const CLIENT_API_PORT: u16 = 19_538;
+const CLIENT_CONSOLE_PORT: u16 = 13_332;
+const STRANGER_API_PORT: u16 = 19_539;
+const STRANGER_CONSOLE_PORT: u16 = 13_333;
+
+/// The trusted client sees the model within seconds on one box; this bounds
+/// the stranger's chance to (fail to) see it. Both windows are overridable
+/// via env (`MESH_CLIENT_WINDOW_SECS` / `MESH_STRANGER_WINDOW_SECS`) so CI
+/// can pin longer windows on slow shared runners instead of re-running the
+/// whole job.
+const CLIENT_WINDOW_SECS: u64 = 180;
+const STRANGER_WINDOW_SECS: u64 = 60;
+
+fn window_secs(name: &str, default: u64) -> u64 {
+    std::env::var(name)
+        .ok()
+        .and_then(|value| value.trim().parse().ok())
+        .unwrap_or(default)
+}
+
+fn client_window() -> Duration {
+    Duration::from_secs(window_secs("MESH_CLIENT_WINDOW_SECS", CLIENT_WINDOW_SECS))
+}
+
+fn stranger_window() -> Duration {
+    Duration::from_secs(window_secs(
+        "MESH_STRANGER_WINDOW_SECS",
+        STRANGER_WINDOW_SECS,
+    ))
+}
+
+/// Marker the orchestrator writes to the client child's stdin to request the
+/// post-attack inference re-verification.
+const VERIFY_AGAIN: &str = "VERIFY_AGAIN";
+
+fn main() -> anyhow::Result<()> {
+    match std::env::var("MESH_ROLE").ok().as_deref() {
+        Some("serve") => run_role(role_serve()),
+        Some("client") => run_role(role_client()),
+        Some("stranger") => run_role(role_stranger()),
+        _ => orchestrate(),
+    }
+}
+
+/// Run a role future and exit without unwinding through C++ static
+/// destructors: once the native runtime has initialized, normal process exit
+/// aborts inside ggml's Metal/CPU device teardown, which would mask the real
+/// error under a GGML_ASSERT backtrace.
+fn run_role(role: impl std::future::Future<Output = anyhow::Result<()>>) -> anyhow::Result<()> {
+    match runtime()?.block_on(role) {
+        Ok(()) => std::process::exit(0),
+        Err(error) => {
+            eprintln!("[role] FAILED: {error:#}");
+            std::process::exit(1);
+        }
+    }
+}
+
+/// mesh-llm's async chains overflow tokio's default 2 MiB worker stacks; the
+/// desktop and the mesh binary itself both run 8 MiB workers for this reason.
+fn runtime() -> anyhow::Result<tokio::runtime::Runtime> {
+    Ok(tokio::runtime::Builder::new_multi_thread()
+        .enable_all()
+        .thread_stack_size(8 * 1024 * 1024)
+        .build()?)
+}
+
+fn env(name: &str) -> anyhow::Result<String> {
+    std::env::var(name).map_err(|_| anyhow::anyhow!("{name} is required for this role"))
+}
+
+fn relay_ws_url() -> String {
+    std::env::var("RELAY_URL").unwrap_or_else(|_| "ws://localhost:3000".to_string())
+}
+
+async fn init_native_runtime() -> anyhow::Result<()> {
+    // The dynamic host runtime installs the recommended signed native runtime
+    // on first use when none is cached — the same SDK-owned path the desktop
+    // relies on. CI caches the install dir across runs.
+    mesh_llm_host_runtime::initialize_host_runtime()
+        .await
+        .map_err(|error| anyhow::anyhow!("MeshLLM host runtime init failed: {error:#}"))
+}
+
+// ── Owner binding payloads ───────────────────────────────────────────────────
+// Byte-for-byte the desktop's `identity::member_binding_bytes` /
+// `member_endpoint_binding_bytes`; the client role verifies exactly what the
+// desktop coordinator publishes. Keep in sync with
+// `desktop/src-tauri/src/mesh_llm/identity.rs`.
+
+fn member_binding_bytes(member_pubkey: &str) -> Vec<u8> {
+    format!(
+        "buzz-mesh-owner-binding-v1:{}",
+        member_pubkey.trim().to_ascii_lowercase()
+    )
+    .into_bytes()
+}
+
+fn member_endpoint_binding_bytes(member_pubkey: &str, endpoint_tokens: &[String]) -> Vec<u8> {
+    let mut endpoints = endpoint_tokens
+        .iter()
+        .map(|token| token.trim())
+        .filter(|token| !token.is_empty())
+        .collect::<Vec<_>>();
+    endpoints.sort_unstable();
+    endpoints.dedup();
+
+    let mut digest = Sha256::new();
+    for endpoint in endpoints {
+        digest.update((endpoint.len() as u64).to_be_bytes());
+        digest.update(endpoint.as_bytes());
+    }
+    format!(
+        "buzz-mesh-owner-endpoint-binding-v1:{}:{}",
+        member_pubkey.trim().to_ascii_lowercase(),
+        hex::encode(digest.finalize())
+    )
+    .into_bytes()
+}
+
+// ── Relay I/O ────────────────────────────────────────────────────────────────
+
+fn status_filter() -> Filter {
+    Filter::new()
+        .kind(Kind::Custom(KIND_MESH_STATUS))
+        .custom_tag(SingleLetterTag::lowercase(Alphabet::K), STATUS_K_TAG)
+        .limit(100)
+}
+
+fn membership_filter() -> Filter {
+    Filter::new().kind(Kind::Custom(KIND_MEMBERSHIP)).limit(1)
+}
+
+async fn query_events(
+    relay: &mut BuzzTestClient,
+    filters: Vec<Filter>,
+) -> anyhow::Result<Vec<Event>> {
+    let sid = format!("mesh-lifecycle-{}", uuid::Uuid::new_v4().simple());
+    relay.subscribe(&sid, filters).await?;
+    let events = relay
+        .collect_until_eose(&sid, Duration::from_secs(10))
+        .await?;
+    relay.close_subscription(&sid).await?;
+    Ok(events)
+}
+
+/// Publish this member's client-signed kind:30003 discovery note — the same
+/// payload the desktop coordinator's `bind_payload_to_member` +
+/// `build_status_report_event` produce.
+async fn publish_status(
+    relay: &mut BuzzTestClient,
+    keys: &Keys,
+    owner: &OwnerKeypair,
+    serve_targets: &[(String, String)],
+) -> anyhow::Result<()> {
+    let member_pubkey = keys.public_key().to_hex();
+    let endpoint_tokens: Vec<String> = serve_targets
+        .iter()
+        .map(|(_, endpoint)| endpoint.clone())
+        .collect();
+    let targets_json: Vec<serde_json::Value> = serve_targets
+        .iter()
+        .map(|(model, endpoint)| serde_json::json!({ "modelId": model, "endpointAddr": endpoint }))
+        .collect();
+    let models_json: Vec<serde_json::Value> = serve_targets
+        .iter()
+        .map(|(model, _)| serde_json::json!({ "id": model }))
+        .collect();
+    let payload = serde_json::json!({
+        "ownerId": owner.owner_id(),
+        "ownerVerifyingKey": hex::encode(owner.verifying_key().as_bytes()),
+        "ownerBindingSig":
+            hex::encode(owner.sign_bytes(&member_binding_bytes(&member_pubkey))),
+        "ownerEndpointBindingSig": hex::encode(owner.sign_bytes(
+            &member_endpoint_binding_bytes(&member_pubkey, &endpoint_tokens),
+        )),
+        "serveTargets": targets_json,
+        "models": models_json,
+    });
+    let d_tag = format!("{STATUS_D_TAG_PREFIX}:{}", owner.owner_id());
+    let d = Tag::parse(["d", d_tag.as_str()]).map_err(|error| anyhow::anyhow!("{error}"))?;
+    let k = Tag::parse(["k", STATUS_K_TAG]).map_err(|error| anyhow::anyhow!("{error}"))?;
+    let event = EventBuilder::new(Kind::Custom(KIND_MESH_STATUS), payload.to_string())
+        .tags([d, k])
+        .sign_with_keys(keys)?;
+    let ok = relay.send_event(event).await?;
+    anyhow::ensure!(
+        ok.accepted,
+        "relay rejected mesh status note: {}",
+        ok.message
+    );
+    Ok(())
+}
+
+// ── Discovery verification (mirrors desktop `discovery.rs`) ─────────────────
+
+fn membership_set(events: &[Event]) -> Option<BTreeSet<String>> {
+    events
+        .iter()
+        .filter(|event| event.kind.as_u16() == KIND_MEMBERSHIP)
+        .max_by_key(|event| event.created_at)
+        .map(|event| {
+            event
+                .tags
+                .iter()
+                .filter_map(|tag| {
+                    let slice = tag.as_slice();
+                    let name = slice.first()?;
+                    if name != "member" && name != "p" {
+                        return None;
+                    }
+                    slice
+                        .get(1)
+                        .map(|pubkey| pubkey.trim().to_ascii_lowercase())
+                })
+                .filter(|pubkey| !pubkey.is_empty())
+                .collect()
+        })
+}
+
+/// `ownerId` must equal sha256(ownerVerifyingKey) and `ownerBindingSig` must
+/// verify against the note's Nostr author — a stored note cannot be re-pointed
+/// at someone else's mesh identity.
+fn verified_owner_id(event: &Event) -> Option<String> {
+    let content = serde_json::from_str::<serde_json::Value>(&event.content).ok()?;
+    let owner_id = content.get("ownerId")?.as_str()?.trim();
+    let verifying_key_bytes: [u8; 32] =
+        hex::decode(content.get("ownerVerifyingKey")?.as_str()?.trim())
+            .ok()?
+            .try_into()
+            .ok()?;
+    if owner_id != hex::encode(Sha256::digest(verifying_key_bytes)) {
+        return None;
+    }
+    let signature_bytes = hex::decode(content.get("ownerBindingSig")?.as_str()?.trim()).ok()?;
+    let signature = Signature::from_slice(&signature_bytes).ok()?;
+    let verifying_key = VerifyingKey::from_bytes(&verifying_key_bytes).ok()?;
+    verifying_key
+        .verify(&member_binding_bytes(&event.pubkey.to_hex()), &signature)
+        .ok()?;
+    Some(owner_id.to_string())
+}
+
+/// Extract `(model_id, endpoint_addr)` pairs from a status note, but only when
+/// the endpoint binding signature covers exactly the advertised tokens.
+fn verified_serve_targets(event: &Event) -> Vec<(String, String)> {
+    let Ok(content) = serde_json::from_str::<serde_json::Value>(&event.content) else {
+        return Vec::new();
+    };
+    let targets: Vec<(String, String)> = content
+        .get("serveTargets")
+        .and_then(serde_json::Value::as_array)
+        .map(|targets| {
+            targets
+                .iter()
+                .filter_map(|target| {
+                    let model = target.get("modelId")?.as_str()?.trim().to_string();
+                    let endpoint = target.get("endpointAddr")?.as_str()?.trim().to_string();
+                    (!endpoint.is_empty()).then_some((model, endpoint))
+                })
+                .collect()
+        })
+        .unwrap_or_default();
+    if targets.is_empty() {
+        return Vec::new();
+    }
+    let endpoint_tokens: Vec<String> = targets
+        .iter()
+        .map(|(_, endpoint)| endpoint.clone())
+        .collect();
+    let Some(verifying_key) = content
+        .get("ownerVerifyingKey")
+        .and_then(serde_json::Value::as_str)
+        .and_then(|value| hex::decode(value.trim()).ok())
+        .and_then(|value| <[u8; 32]>::try_from(value).ok())
+        .and_then(|value| VerifyingKey::from_bytes(&value).ok())
+    else {
+        return Vec::new();
+    };
+    let Some(signature) = content
+        .get("ownerEndpointBindingSig")
+        .and_then(serde_json::Value::as_str)
+        .and_then(|value| hex::decode(value.trim()).ok())
+        .and_then(|value| Signature::from_slice(&value).ok())
+    else {
+        return Vec::new();
+    };
+    let bytes = member_endpoint_binding_bytes(&event.pubkey.to_hex(), &endpoint_tokens);
+    if verifying_key.verify(&bytes, &signature).is_err() {
+        return Vec::new();
+    }
+    targets
+}
+
+/// Owner ids of current members with valid owner bindings — the relay-derived
+/// admission roster (`owner_ids_from_events` semantics).
+fn member_owner_ids(events: &[Event]) -> BTreeSet<String> {
+    let Some(members) = membership_set(events) else {
+        return BTreeSet::new();
+    };
+    events
+        .iter()
+        .filter(|event| event.kind.as_u16() == KIND_MESH_STATUS)
+        .filter(|event| members.contains(&event.pubkey.to_hex().to_ascii_lowercase()))
+        .filter_map(verified_owner_id)
+        .collect()
+}
+
+// ── Roles ────────────────────────────────────────────────────────────────────
+
+/// SERVE (member A): publish presence, derive the allowlist from the relay,
+/// require the exact expected owner set, start an allowlist serve node,
+/// publish the endpoint, park.
+async fn role_serve() -> anyhow::Result<()> {
+    init_native_runtime().await?;
+    let model = std::env::var("MESH_SMOKE_MODEL").unwrap_or_else(|_| DEFAULT_MODEL.to_string());
+    let keys = Keys::parse(&env("BUZZ_MEMBER_NSEC")?)?;
+    let owner = load_keystore(std::path::Path::new(&env("MESH_OWNER_KEY")?), None)
+        .map_err(|error| anyhow::anyhow!("loading serve owner keystore: {error}"))?;
+    // The exact owner ids the orchestrator provisioned for members A and B.
+    // Waiting for this exact set (not a count) means the allowlist can only
+    // ever contain the intended identities.
+    let expected_owners: BTreeSet<String> = env("MESH_EXPECTED_OWNERS")?
+        .split(',')
+        .map(|id| id.trim().to_string())
+        .filter(|id| !id.is_empty())
+        .collect();
+    anyhow::ensure!(
+        expected_owners.contains(&owner.owner_id()),
+        "serve owner id is not in MESH_EXPECTED_OWNERS"
+    );
+
+    let mut relay = BuzzTestClient::connect(&relay_ws_url(), &keys)
+        .await
+        .map_err(|error| anyhow::anyhow!("serve member relay connect: {error}"))?;
+    publish_status(&mut relay, &keys, &owner, &[]).await?;
+    println!("STATUS_PUBLISHED");
+
+    // TRUST: wait until every expected member owner is visible via the relay
+    // (statuses ∩ roster), then admit exactly those owners.
+    let deadline = Instant::now() + Duration::from_secs(120);
+    loop {
+        let events = query_events(&mut relay, vec![status_filter(), membership_filter()]).await?;
+        let mut visible = member_owner_ids(&events);
+        visible.insert(owner.owner_id());
+        if visible.is_superset(&expected_owners) {
+            break;
+        }
+        anyhow::ensure!(
+            Instant::now() < deadline,
+            "timed out waiting for expected owners {expected_owners:?}; saw {visible:?}"
+        );
+        tokio::time::sleep(Duration::from_secs(2)).await;
+    }
+    let allowlist: Vec<String> = expected_owners.iter().cloned().collect();
+    println!("ALLOWLIST:{}", allowlist.join(","));
+    // The upcoming serve::start() blocks through a possibly multi-minute model
+    // download; an idle relay socket gets closed under it. Reconnect after.
+    let _ = relay.disconnect().await;
+
+    let cfg = serve::EmbeddedServeConfig::builder()
+        .model(&model)
+        .api_port(SERVE_API_PORT)
+        .console_port(SERVE_CONSOLE_PORT)
+        // Desktop no-leak invariants: never publish mesh presence, never
+        // auto-discover. The Buzz relay is the only discovery surface.
+        .publish(false)
+        .auto_join(false)
+        .discovery_mode(MeshDiscoveryMode::Nostr)
+        .console_ui(true)
+        .startup_timeout(Duration::from_secs(600))
+        .owner_key(env("MESH_OWNER_KEY")?)
+        .owner_required(true)
+        .trust_policy(TrustPolicy::Allowlist)
+        .trust_owners(allowlist)
+        .build();
+    let node = serve::start(cfg).await?;
+    let endpoint = node
+        .invite_token()
+        .map(str::to_string)
+        .ok_or_else(|| anyhow::anyhow!("serve node produced no endpoint address"))?;
+    println!("ENDPOINT:{endpoint}");
+
+    let http = reqwest::Client::new();
+    let base = node.api_base_url().to_string();
+    let served = wait_for_model(&http, &base, Duration::from_secs(600))
+        .await?
+        .ok_or_else(|| anyhow::anyhow!("serve node never loaded the model"))?;
+
+    // ADVERTISE: refresh the status note with the live serve target, exactly
+    // what the desktop's 45s heartbeat publishes once serving. Fresh relay
+    // connection — the pre-download socket has long been idle-closed.
+    let mut relay = BuzzTestClient::connect(&relay_ws_url(), &keys)
+        .await
+        .map_err(|error| anyhow::anyhow!("serve member relay reconnect: {error}"))?;
+    publish_status(
+        &mut relay,
+        &keys,
+        &owner,
+        &[(served.clone(), endpoint.clone())],
+    )
+    .await?;
+    println!("READY:{served}");
+
+    // Park; the orchestrator kills this process when the run is over.
+    loop {
+        tokio::time::sleep(Duration::from_secs(3600)).await;
+    }
+}
+
+/// CLIENT (member B): publish presence, discover + verify the serve target
+/// from the relay, dial it, prove inference routes over the mesh — then wait
+/// for the orchestrator's `VERIFY_AGAIN` and re-prove inference after the
+/// stranger's admission attack, so denial is differential, not absence.
+async fn role_client() -> anyhow::Result<()> {
+    init_native_runtime().await?;
+    let keys = Keys::parse(&env("BUZZ_MEMBER_NSEC")?)?;
+    let owner = load_keystore(std::path::Path::new(&env("MESH_OWNER_KEY")?), None)
+        .map_err(|error| anyhow::anyhow!("loading client owner keystore: {error}"))?;
+
+    let mut relay = BuzzTestClient::connect(&relay_ws_url(), &keys)
+        .await
+        .map_err(|error| anyhow::anyhow!("client member relay connect: {error}"))?;
+    publish_status(&mut relay, &keys, &owner, &[]).await?;
+    println!("STATUS_PUBLISHED");
+
+    // JOIN: poll the relay until a *verified* serve target from another member
+    // appears — membership roster, owner binding, and endpoint binding all
+    // checked, mirroring `availability_from_events`.
+    let deadline = Instant::now() + Duration::from_secs(900);
+    let (endpoint, allowlist) = loop {
+        let events = query_events(&mut relay, vec![status_filter(), membership_filter()]).await?;
+        let members = membership_set(&events).unwrap_or_default();
+        let target = events
+            .iter()
+            .filter(|event| event.kind.as_u16() == KIND_MESH_STATUS)
+            .filter(|event| members.contains(&event.pubkey.to_hex().to_ascii_lowercase()))
+            .filter(|event| verified_owner_id(event).is_some_and(|id| id != owner.owner_id()))
+            .flat_map(verified_serve_targets)
+            .next();
+        if let Some((_, endpoint)) = target {
+            let owners: Vec<String> = member_owner_ids(&events).into_iter().collect();
+            break (endpoint, owners);
+        }
+        anyhow::ensure!(
+            Instant::now() < deadline,
+            "timed out waiting for a verified serve target on the relay"
+        );
+        tokio::time::sleep(Duration::from_secs(3)).await;
+    };
+    println!("TARGET_FOUND");
+
+    let cfg = client::EmbeddedClientConfig::builder()
+        .api_port(CLIENT_API_PORT)
+        .console_port(CLIENT_CONSOLE_PORT)
+        .publish(false)
+        .auto_join(false)
+        .discovery_mode(MeshDiscoveryMode::Nostr)
+        .console_ui(true)
+        .startup_timeout(Duration::from_secs(180))
+        .owner_key(env("MESH_OWNER_KEY")?)
+        .owner_required(true)
+        .trust_policy(TrustPolicy::Allowlist)
+        .trust_owners(allowlist)
+        .build();
+    let node = client::start(cfg).await?;
+    // The relay-discovered endpoint is the dial target — the same
+    // `dial_endpoint_addr` step the desktop's join watcher performs. The
+    // desktop's watcher retries every 15s (a first QUIC dial can time out
+    // while the serve node's endpoint is still warming up). mesh-llm itself
+    // retries internally per attempt, so keep the outer budget small.
+    let mut dial_result = Ok(());
+    for attempt in 1..=3u32 {
+        dial_result = node.join_token(&endpoint).await;
+        match &dial_result {
+            Ok(()) => break,
+            Err(error) => {
+                eprintln!("[client] dial attempt {attempt}/3 failed: {error:#}");
+                tokio::time::sleep(Duration::from_secs(5)).await;
+            }
+        }
+    }
+    dial_result?;
+
+    let http = reqwest::Client::new();
+    let base = node.api_base_url().to_string();
+    let Some(model) = wait_for_model(&http, &base, client_window()).await? else {
+        println!("NONE");
+        let _ = node.stop().await;
+        std::process::exit(0);
+    };
+    println!("SEEN:{model}");
+    match try_completion(&http, &base, &model).await {
+        Ok(content) => println!("INFER_OK:{content}"),
+        Err(error) => {
+            println!("INFER_FAIL:{error}");
+            let _ = node.stop().await;
+            std::process::exit(0);
+        }
+    }
+
+    // Post-attack health proof: hold the mesh session open until the
+    // orchestrator has run the stranger, then prove the serve node still
+    // routes trusted inference. This is what makes the stranger's failure an
+    // admission denial rather than a dead server.
+    let line = tokio::task::spawn_blocking(|| {
+        let mut line = String::new();
+        std::io::stdin().read_line(&mut line).map(|_| line)
+    })
+    .await??;
+    if line.trim() == VERIFY_AGAIN {
+        match try_completion(&http, &base, &model).await {
+            Ok(content) => println!("INFER_AGAIN_OK:{content}"),
+            Err(error) => println!("INFER_AGAIN_FAIL:{error}"),
+        }
+    }
+    let _ = node.stop().await;
+    // Skip C++ static destructors (ggml aborts in global teardown).
+    std::process::exit(0);
+}
+
+/// STRANGER (non-member C): NIP-42 auth must fail with the relay's membership
+/// rejection, and the mesh must not route inference for it even with the
+/// leaked endpoint address.
+async fn role_stranger() -> anyhow::Result<()> {
+    let keys = Keys::parse(&env("BUZZ_MEMBER_NSEC")?)?;
+    let leaked_endpoint = env("MESH_LEAKED_ENDPOINT")?;
+
+    // DENY (relay read): the membership-gated relay must reject the
+    // stranger's NIP-42 auth with its membership error specifically. Any
+    // other failure (relay down, timeout) is inconclusive and fails the
+    // test; a successful auth is a gating regression and also fails.
+    match BuzzTestClient::connect(&relay_ws_url(), &keys).await {
+        Err(error) => {
+            let message = error.to_string();
+            if message.contains("not a relay member") {
+                println!("RELAY_DENIED_MEMBERSHIP");
+            } else {
+                println!("RELAY_ERR:{message}");
+            }
+        }
+        Ok(mut relay) => {
+            let statuses = query_events(&mut relay, vec![status_filter()])
+                .await
+                .map(|events| {
+                    events
+                        .iter()
+                        .filter(|event| event.kind.as_u16() == KIND_MESH_STATUS)
+                        .count()
+                })
+                .unwrap_or(usize::MAX);
+            println!("RELAY_AUTH_OK:{statuses}");
+            let _ = relay.disconnect().await;
+        }
+    }
+
+    // DENY (admission): dial the serve node directly with the leaked endpoint.
+    // The stranger's owner id is not on the allowlist, so the mesh must refuse
+    // to route anything to it. Note the dial itself may locally "succeed" —
+    // mesh-llm applies the receiving node's owner policy after the handshake —
+    // so the decisive probe is routed inference, cross-checked against the
+    // trusted client's post-attack inference by the orchestrator.
+    init_native_runtime().await?;
+    let cfg = client::EmbeddedClientConfig::builder()
+        .api_port(STRANGER_API_PORT)
+        .console_port(STRANGER_CONSOLE_PORT)
+        .publish(false)
+        .auto_join(false)
+        .discovery_mode(MeshDiscoveryMode::Nostr)
+        .console_ui(true)
+        .startup_timeout(Duration::from_secs(180))
+        .owner_key(env("MESH_OWNER_KEY")?)
+        .owner_required(true)
+        .build();
+    let node = client::start(cfg).await?;
+    let _ = node.join_token(&leaked_endpoint).await;
+
+    let http = reqwest::Client::new();
+    let base = node.api_base_url().to_string();
+    match wait_for_model(&http, &base, stranger_window()).await? {
+        Some(model) => {
+            println!("SEEN:{model}");
+            match try_completion(&http, &base, &model).await {
+                Ok(content) => println!("INFER_OK:{content}"),
+                Err(error) => println!("INFER_FAIL:{error}"),
+            }
+        }
+        None => println!("NONE"),
+    }
+    let _ = node.stop().await;
+    std::process::exit(0);
+}
+
+// ── Orchestrator ─────────────────────────────────────────────────────────────
+
+fn orchestrate() -> anyhow::Result<()> {
+    let model = std::env::var("MESH_SMOKE_MODEL").unwrap_or_else(|_| DEFAULT_MODEL.to_string());
+    eprintln!("[lifecycle] model: {model}");
+    let admin =
+        std::env::var("BUZZ_ADMIN_BIN").unwrap_or_else(|_| "target/ci/buzz-admin".to_string());
+    anyhow::ensure!(
+        std::path::Path::new(&admin).exists(),
+        "buzz-admin binary not found at {admin} (set BUZZ_ADMIN_BIN)"
+    );
+
+    let scratch = std::env::temp_dir().join(format!("buzz-mesh-lifecycle-{}", std::process::id()));
+    std::fs::create_dir_all(&scratch)?;
+
+    // Nostr identities: A (serve member), B (client member), C (stranger).
+    let member_a = Keys::generate();
+    let member_b = Keys::generate();
+    let stranger = Keys::generate();
+
+    // MeshLLM owner keystores, one per role. The orchestrator keeps the owner
+    // ids so the serve role can gate on the exact expected identity set.
+    let make_owner = |name: &str| -> anyhow::Result<(String, String)> {
+        let keypair = OwnerKeypair::generate();
+        let path = scratch.join(format!("{name}.keystore.json"));
+        save_keystore(&path, &keypair, None, true)
+            .map_err(|error| anyhow::anyhow!("saving {name} keystore: {error}"))?;
+        Ok((path.display().to_string(), keypair.owner_id()))
+    };
+    let (serve_key, serve_owner_id) = make_owner("serve")?;
+    let (client_key, client_owner_id) = make_owner("client")?;
+    let (stranger_key, _stranger_owner_id) = make_owner("stranger")?;
+    let expected_owners = format!("{serve_owner_id},{client_owner_id}");
+
+    // MEMBERSHIP: A and B become relay members via buzz-admin (publishes the
+    // kind:13534 roster snapshot). C is deliberately not added.
+    for (label, keys) in [("A", &member_a), ("B", &member_b)] {
+        let status = Command::new(&admin)
+            .args(["add-member", "--pubkey", &keys.public_key().to_hex()])
+            .status()?;
+        anyhow::ensure!(status.success(), "buzz-admin add-member {label} failed");
+        eprintln!(
+            "[lifecycle] member {label} added: {}",
+            keys.public_key().to_hex()
+        );
+    }
+
+    // Isolated HOMEs (mesh-llm keeps node identity under ~/.mesh-llm), with
+    // the native runtime + HF caches resolved from the real environment first.
+    let native_cache = std::env::var_os("MESH_LLM_NATIVE_RUNTIME_CACHE_DIR")
+        .map(std::path::PathBuf::from)
+        .unwrap_or(real_cache_dir()?.join("mesh-llm/native-runtimes"));
+    let hf_cache = std::env::var_os("HF_HUB_CACHE")
+        .map(std::path::PathBuf::from)
+        .unwrap_or(real_cache_dir()?.join("huggingface/hub"));
+    let role_home = |name: &str| -> anyhow::Result<String> {
+        let home = scratch.join(format!("{name}-home"));
+        std::fs::create_dir_all(&home)?;
+        Ok(home.display().to_string())
+    };
+
+    let exe = std::env::current_exe()?;
+    let secret_hex = |keys: &Keys| format!("{}", keys.secret_key().display_secret());
+
+    // SERVE child (member A).
+    eprintln!("[lifecycle] starting SERVE member (relay-derived allowlist)...");
+    let mut serve_child = Command::new(&exe)
+        .env("MESH_ROLE", "serve")
+        .env("MESH_SMOKE_MODEL", &model)
+        .env("BUZZ_MEMBER_NSEC", secret_hex(&member_a))
+        .env("MESH_OWNER_KEY", &serve_key)
+        .env("MESH_EXPECTED_OWNERS", &expected_owners)
+        .env("HOME", role_home("serve")?)
+        .env("MESH_LLM_NATIVE_RUNTIME_CACHE_DIR", &native_cache)
+        .env("HF_HUB_CACHE", &hf_cache)
+        .stdout(Stdio::piped())
+        .stderr(Stdio::inherit())
+        .spawn()?;
+    let serve_lines = spawn_line_reader(
+        serve_child
+            .stdout
+            .take()
+            .ok_or_else(|| anyhow::anyhow!("no serve stdout"))?,
+    );
+    let serve_guard = KillOnDrop(&mut serve_child);
+    expect_line(&serve_lines, "STATUS_PUBLISHED", Duration::from_secs(180))?;
+    eprintln!("[lifecycle] serve member published its discovery note");
+
+    // CLIENT child (member B) — started now so the serve node can see B's
+    // owner binding on the relay and admit it. stdin stays piped for the
+    // post-attack VERIFY_AGAIN request.
+    eprintln!("[lifecycle] starting CLIENT member (relay-driven join)...");
+    let mut client_child = Command::new(&exe)
+        .env("MESH_ROLE", "client")
+        .env("BUZZ_MEMBER_NSEC", secret_hex(&member_b))
+        .env("MESH_OWNER_KEY", &client_key)
+        .env("HOME", role_home("client")?)
+        .env("MESH_LLM_NATIVE_RUNTIME_CACHE_DIR", &native_cache)
+        .env("HF_HUB_CACHE", &hf_cache)
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::inherit())
+        .spawn()?;
+    let client_lines = spawn_line_reader(
+        client_child
+            .stdout
+            .take()
+            .ok_or_else(|| anyhow::anyhow!("no client stdout"))?,
+    );
+    let mut client_stdin = client_child
+        .stdin
+        .take()
+        .ok_or_else(|| anyhow::anyhow!("no client stdin"))?;
+    let client_guard = KillOnDrop(&mut client_child);
+
+    let allowlist = expect_line(&serve_lines, "ALLOWLIST:", Duration::from_secs(300))?;
+    anyhow::ensure!(
+        allowlist.split(',').map(str::trim).collect::<BTreeSet<_>>()
+            == BTreeSet::from([serve_owner_id.as_str(), client_owner_id.as_str()]),
+        "LIFECYCLE FAIL: serve allowlist {allowlist} is not exactly the expected member owners"
+    );
+    eprintln!("[lifecycle] PASS 1/6: relay-derived allowlist is exactly {{A, B}}: {allowlist}");
+    let endpoint = expect_line(&serve_lines, "ENDPOINT:", Duration::from_secs(600))?;
+    eprintln!("[lifecycle] serve endpoint acquired (relay advertisement lands with READY)");
+    let served = expect_line(&serve_lines, "READY:", Duration::from_secs(900))?;
+    eprintln!("[lifecycle] PASS 2/6: serve member ready + advertised model: {served}");
+
+    // Client verdict: discovery + join + first inference.
+    let (which, seen) = expect_one_of(&client_lines, &["SEEN:", "NONE"], Duration::from_secs(900))?;
+    anyhow::ensure!(
+        which == "SEEN:",
+        "LIFECYCLE FAIL: client member never saw the model via relay-driven join"
+    );
+    eprintln!("[lifecycle] PASS 3/6: client member discovered + joined via relay, sees: {seen}");
+    let (which, detail) = expect_one_of(
+        &client_lines,
+        &["INFER_OK:", "INFER_FAIL:"],
+        Duration::from_secs(180),
+    )?;
+    anyhow::ensure!(
+        which == "INFER_OK:",
+        "LIFECYCLE FAIL: client saw the model but inference did not route: {detail}"
+    );
+    eprintln!("[lifecycle] PASS 4/6: inference routed over the mesh: {detail:?}");
+
+    // STRANGER child (C): must be denied by the relay's membership gate and
+    // must not route inference through the mesh.
+    eprintln!("[lifecycle] starting STRANGER (non-member, leaked endpoint)...");
+    let mut stranger_child = Command::new(&exe)
+        .env("MESH_ROLE", "stranger")
+        .env("BUZZ_MEMBER_NSEC", secret_hex(&stranger))
+        .env("MESH_OWNER_KEY", &stranger_key)
+        .env("MESH_LEAKED_ENDPOINT", &endpoint)
+        .env("HOME", role_home("stranger")?)
+        .env("MESH_LLM_NATIVE_RUNTIME_CACHE_DIR", &native_cache)
+        .env("HF_HUB_CACHE", &hf_cache)
+        .stdout(Stdio::piped())
+        .stderr(Stdio::inherit())
+        .spawn()?;
+    let stranger_lines = spawn_line_reader(
+        stranger_child
+            .stdout
+            .take()
+            .ok_or_else(|| anyhow::anyhow!("no stranger stdout"))?,
+    );
+    let stranger_guard = KillOnDrop(&mut stranger_child);
+
+    // Relay leg: only the relay's own membership rejection counts as denied.
+    let (which, detail) = expect_one_of(
+        &stranger_lines,
+        &["RELAY_DENIED_MEMBERSHIP", "RELAY_AUTH_OK:", "RELAY_ERR:"],
+        Duration::from_secs(120),
+    )?;
+    match which {
+        "RELAY_DENIED_MEMBERSHIP" => {
+            eprintln!("[lifecycle] PASS 5/6: relay rejected the stranger's NIP-42 auth (membership gate)");
+        }
+        "RELAY_AUTH_OK:" => anyhow::bail!(
+            "LIFECYCLE FAIL: membership-gated relay authenticated a non-member (saw {detail} statuses)"
+        ),
+        _ => anyhow::bail!(
+            "LIFECYCLE INCONCLUSIVE: stranger relay connect failed for a non-membership reason: {detail}"
+        ),
+    }
+
+    // Mesh leg: the stranger must not complete an inference.
+    let (which, detail) = expect_one_of(
+        &stranger_lines,
+        &["SEEN:", "NONE"],
+        stranger_window() + Duration::from_secs(300),
+    )?;
+    let stranger_infer = if which == "SEEN:" {
+        let model = detail;
+        let (verdict, body) = expect_one_of(
+            &stranger_lines,
+            &["INFER_OK:", "INFER_FAIL:"],
+            Duration::from_secs(180),
+        )?;
+        anyhow::ensure!(
+            verdict != "INFER_OK:",
+            "LIFECYCLE FAIL: stranger reused the leaked endpoint and inferred through {model}: {body:?}"
+        );
+        format!("saw gossip for {model} but inference was rejected: {body}")
+    } else {
+        "saw no routed model".to_string()
+    };
+    // Defuse the kill-guard (the stranger exits on its own after its verdict);
+    // dropping it here would SIGKILL the child before we can read its status.
+    std::mem::forget(stranger_guard);
+    let stranger_status = wait_child(&mut stranger_child, Duration::from_secs(60), "stranger")?;
+    anyhow::ensure!(
+        stranger_status.success(),
+        "LIFECYCLE INCONCLUSIVE: stranger child exited with {stranger_status}"
+    );
+
+    // Differential health proof: the trusted client must still route
+    // inference *after* the stranger's attempt. Without this, a serve node
+    // that died mid-run would make the stranger's failure look like a denial.
+    client_stdin.write_all(format!("{VERIFY_AGAIN}\n").as_bytes())?;
+    client_stdin.flush()?;
+    let (which, detail) = expect_one_of(
+        &client_lines,
+        &["INFER_AGAIN_OK:", "INFER_AGAIN_FAIL:"],
+        Duration::from_secs(180),
+    )?;
+    anyhow::ensure!(
+        which == "INFER_AGAIN_OK:",
+        "LIFECYCLE FAIL: trusted client could not infer after the stranger's attempt \
+         (serve node unhealthy — stranger denial is inconclusive): {detail}"
+    );
+    eprintln!(
+        "[lifecycle] PASS 6/6: stranger denied ({stranger_infer}) while trusted inference \
+         still routes: {detail:?}"
+    );
+
+    eprintln!("[lifecycle] PASS: full relay-driven mesh lifecycle verified");
+    drop(client_guard);
+    let _ = wait_child(&mut client_child, Duration::from_secs(60), "client");
+    drop(serve_guard);
+    let _ = serve_child.wait();
+    let _ = std::fs::remove_dir_all(&scratch);
+    Ok(())
+}
+
+// ── Child-process plumbing ───────────────────────────────────────────────────
+
+/// Lines from a child's stdout, pumped by a dedicated reader thread so waits
+/// can enforce hard deadlines (`BufRead::lines` alone blocks indefinitely).
+struct ChildLines {
+    rx: mpsc::Receiver<std::io::Result<String>>,
+}
+
+fn spawn_line_reader(stdout: ChildStdout) -> ChildLines {
+    let (tx, rx) = mpsc::channel();
+    std::thread::spawn(move || {
+        for line in std::io::BufReader::new(stdout).lines() {
+            if tx.send(line).is_err() {
+                break;
+            }
+        }
+    });
+    ChildLines { rx }
+}
+
+/// Wait (with a hard deadline) for a line starting with `prefix`; returns the
+/// suffix. Non-matching lines are skipped.
+fn expect_line(lines: &ChildLines, prefix: &str, timeout: Duration) -> anyhow::Result<String> {
+    expect_one_of(lines, &[prefix], timeout).map(|(_, rest)| rest)
+}
+
+/// Wait (with a hard deadline) for a line starting with any of `prefixes`;
+/// returns the matched prefix and the suffix.
+fn expect_one_of<'a>(
+    lines: &ChildLines,
+    prefixes: &[&'a str],
+    timeout: Duration,
+) -> anyhow::Result<(&'a str, String)> {
+    let deadline = Instant::now() + timeout;
+    loop {
+        let remaining = deadline
+            .checked_duration_since(Instant::now())
+            .ok_or_else(|| anyhow::anyhow!("timed out waiting for one of {prefixes:?}"))?;
+        match lines.rx.recv_timeout(remaining) {
+            Ok(Ok(line)) => {
+                for prefix in prefixes {
+                    if let Some(rest) = line.strip_prefix(prefix) {
+                        return Ok((prefix, rest.to_string()));
+                    }
+                }
+            }
+            Ok(Err(error)) => {
+                anyhow::bail!("child stdout read error before {prefixes:?}: {error}")
+            }
+            Err(mpsc::RecvTimeoutError::Timeout) => {
+                anyhow::bail!("timed out waiting for one of {prefixes:?}")
+            }
+            Err(mpsc::RecvTimeoutError::Disconnected) => {
+                anyhow::bail!("child exited before printing one of {prefixes:?}")
+            }
+        }
+    }
+}
+
+/// Wait for a child to exit, killing it if the deadline passes.
+fn wait_child(child: &mut Child, timeout: Duration, label: &str) -> anyhow::Result<ExitStatus> {
+    let deadline = Instant::now() + timeout;
+    loop {
+        if let Some(status) = child.try_wait()? {
+            return Ok(status);
+        }
+        if Instant::now() > deadline {
+            let _ = child.kill();
+            let _ = child.wait();
+            anyhow::bail!("{label} child exceeded {timeout:?} and was killed");
+        }
+        std::thread::sleep(Duration::from_millis(200));
+    }
+}
+
+/// Kill the child on drop so a failed assertion never leaks a process.
+struct KillOnDrop<'a>(&'a mut Child);
+impl Drop for KillOnDrop<'_> {
+    fn drop(&mut self) {
+        let _ = self.0.kill();
+    }
+}
+
+/// The real user's OS cache dir, resolved before HOME is overridden for the
+/// child processes.
+fn real_cache_dir() -> anyhow::Result<std::path::PathBuf> {
+    let home = std::env::var("HOME").map_err(|_| anyhow::anyhow!("HOME is not set"))?;
+    #[cfg(target_os = "macos")]
+    return Ok(std::path::PathBuf::from(home).join("Library/Caches"));
+    #[cfg(not(target_os = "macos"))]
+    return Ok(std::path::PathBuf::from(home).join(".cache"));
+}
+
+/// Poll `/models` until a model id appears or the window closes.
+async fn wait_for_model(
+    http: &reqwest::Client,
+    api_base: &str,
+    window: Duration,
+) -> anyhow::Result<Option<String>> {
+    let url = format!("{api_base}/models");
+    let deadline = Instant::now() + window;
+    while Instant::now() < deadline {
+        tokio::time::sleep(Duration::from_secs(3)).await;
+        if let Ok(resp) = http.get(&url).send().await {
+            let body = resp.text().await.unwrap_or_default();
+            if let Ok(json) = serde_json::from_str::<serde_json::Value>(&body) {
+                if let Some(id) = json["data"].get(0).and_then(|m| m["id"].as_str()) {
+                    return Ok(Some(id.to_string()));
+                }
+            }
+        }
+    }
+    Ok(None)
+}
+
+/// One chat completion against a node's OpenAI endpoint; Ok(content) only if
+/// it really routed and produced non-empty output.
+async fn try_completion(
+    http: &reqwest::Client,
+    api_base: &str,
+    model: &str,
+) -> anyhow::Result<String> {
+    let resp = http
+        .post(format!("{api_base}/chat/completions"))
+        .timeout(Duration::from_secs(120))
+        .json(&serde_json::json!({
+            "model": model,
+            "messages": [{"role": "user", "content": "Reply with exactly one word: PONG"}],
+            "max_tokens": 16,
+            "temperature": 0.0
+        }))
+        .send()
+        .await?;
+    let status = resp.status();
+    let body = resp.text().await?;
+    if !status.is_success() {
+        anyhow::bail!("{status}: {body}");
+    }
+    let content = serde_json::from_str::<serde_json::Value>(&body)?["choices"][0]["message"]
+        ["content"]
+        .as_str()
+        .unwrap_or("")
+        .to_string();
+    if content.trim().is_empty() {
+        anyhow::bail!("empty content");
+    }
+    Ok(content)
+}
diff --git a/scripts/ci-mesh-lifecycle-smoke.sh b/scripts/ci-mesh-lifecycle-smoke.sh
new file mode 100755
index 0000000000..887e2b15a6
--- /dev/null
+++ b/scripts/ci-mesh-lifecycle-smoke.sh
@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# =============================================================================
+# ci-mesh-lifecycle-smoke.sh — relay-driven mesh lifecycle smoke
+# =============================================================================
+# Provisions a membership-gated buzz-relay and runs the full relay-driven
+# mesh lifecycle harness (crates/buzz-relay/examples/mesh_relay_lifecycle_smoke.rs):
+# membership → signed discovery notes → relay-derived allowlist → join →
+# inference over QUIC → stranger denied.
+#
+# Mirrors the shape of mesh-llm's own CI smoke scripts (single runner, tiny
+# CPU model, real multi-process mesh), but with the Buzz relay as the control
+# plane instead of a hand-carried invite token.
+#
+# Usage:
+#   ./scripts/ci-mesh-lifecycle-smoke.sh [--profile <cargo-profile>] [--no-build]
+#
+# Env:
+#   MESH_SMOKE_MODEL   Override the served model ref (default: SmolLM2-135M).
+# =============================================================================
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+cd "${REPO_ROOT}"
+
+CARGO_PROFILE="${CARGO_PROFILE:-ci}"
+SKIP_BUILD=false
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --profile) CARGO_PROFILE="$2"; shift 2 ;;
+    --no-build) SKIP_BUILD=true; shift ;;
+    *) echo "Unknown option: $1" >&2; exit 1 ;;
+  esac
+done
+
+BLUE='\033[0;34m'
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+NC='\033[0m'
+log() { echo -e "${BLUE}[mesh-lifecycle]${NC} $*"; }
+ok()  { echo -e "${GREEN}[mesh-lifecycle]${NC} $*"; }
+err() { echo -e "${RED}[mesh-lifecycle]${NC} $*" >&2; }
+
+# ── Build ─────────────────────────────────────────────────────────────────────
+
+if [[ "${SKIP_BUILD}" == "true" ]]; then
+  log "Skipping build (--no-build)"
+else
+  log "Building relay, admin CLI, and lifecycle harness (profile: ${CARGO_PROFILE})..."
+  cargo build --profile "${CARGO_PROFILE}" -p buzz-relay -p buzz-admin -p git-credential-nostr
+  cargo build --profile "${CARGO_PROFILE}" -p buzz-relay --example mesh_relay_lifecycle_smoke
+fi
+
+ADMIN_BIN="target/${CARGO_PROFILE}/buzz-admin"
+HARNESS_BIN="target/${CARGO_PROFILE}/examples/mesh_relay_lifecycle_smoke"
+for bin in "${ADMIN_BIN}" "${HARNESS_BIN}" "target/${CARGO_PROFILE}/buzz-relay"; do
+  if [[ ! -x "${bin}" ]]; then
+    err "Missing binary: ${bin}"
+    exit 1
+  fi
+done
+
+# ── Relay identity + membership gating ───────────────────────────────────────
+# The relay owner and signing key are throwaway CI identities. RELAY_OWNER
+# never participates in the mesh; it only satisfies the NIP-43 requirement
+# that a membership-gated relay has an administrable owner.
+
+log "Generating relay owner + signing identities..."
+read_keys() { "${ADMIN_BIN}" generate-key 2>/dev/null; }
+OWNER_OUT="$(read_keys)"
+RELAY_OWNER_PUBKEY="$(echo "${OWNER_OUT}" | awk '/Public key:/ {print $3}')"
+SIGNER_OUT="$(read_keys)"
+BUZZ_RELAY_PRIVATE_KEY="$(echo "${SIGNER_OUT}" | awk '/Secret key:/ {print $3}')"
+if [[ -z "${RELAY_OWNER_PUBKEY}" || -z "${BUZZ_RELAY_PRIVATE_KEY}" ]]; then
+  err "Failed to generate relay identities via buzz-admin generate-key"
+  exit 1
+fi
+export BUZZ_REQUIRE_RELAY_MEMBERSHIP=true
+export RELAY_OWNER_PUBKEY
+export BUZZ_RELAY_PRIVATE_KEY
+
+# ── Start the membership-gated relay ─────────────────────────────────────────
+# A stale relay on :3000 would pass the readiness poll while silently running
+# WITHOUT membership gating — the stranger-denied assertion would then fail
+# (or worse, an open relay would mask a real gating regression). Fail fast.
+if lsof -nP -iTCP:3000 -sTCP:LISTEN >/dev/null 2>&1; then
+  err "Port 3000 is already in use — stop the existing relay first (its config would not be membership-gated)"
+  exit 1
+fi
+
+log "Starting membership-gated relay..."
+CARGO_PROFILE="${CARGO_PROFILE}" ./scripts/start-relay-for-tests.sh --no-build
+
+cleanup() {
+  log "Stopping relay..."
+  if [[ -f /tmp/buzz-relay.pid ]]; then
+    kill "$(cat /tmp/buzz-relay.pid)" 2>/dev/null || true
+  fi
+  # The harness kills its own children; sweep any stragglers from a hard fail.
+  pkill -f mesh_relay_lifecycle_smoke 2>/dev/null || true
+}
+trap cleanup EXIT
+
+# ── Run the lifecycle harness ────────────────────────────────────────────────
+
+log "Running relay-driven mesh lifecycle smoke..."
+RELAY_URL=ws://localhost:3000 \
+DATABASE_URL=postgres://buzz:buzz_dev@localhost:5432/buzz \
+REDIS_URL=redis://localhost:6379 \
+BUZZ_ADMIN_BIN="${ADMIN_BIN}" \
+  "${HARNESS_BIN}"
+
+ok "Relay-driven mesh lifecycle smoke passed"
diff --git a/scripts/start-relay-for-tests.sh b/scripts/start-relay-for-tests.sh
index 85aa101356..b9d93935c0 100755
--- a/scripts/start-relay-for-tests.sh
+++ b/scripts/start-relay-for-tests.sh
@@ -151,6 +151,20 @@ fi
 # ── Start relay ──────────────────────────────────────────────────────────────
 
 log "Starting relay..."
+
+# Optional NIP-43 membership gating: exported by callers that need a
+# membership-gated relay (e.g. the mesh lifecycle smoke). All three must be
+# set together — the relay fails fast otherwise.
+MEMBERSHIP_ENV=()
+if [[ "${BUZZ_REQUIRE_RELAY_MEMBERSHIP:-}" == "true" ]]; then
+  MEMBERSHIP_ENV+=(
+    BUZZ_REQUIRE_RELAY_MEMBERSHIP=true
+    RELAY_OWNER_PUBKEY="${RELAY_OWNER_PUBKEY:?RELAY_OWNER_PUBKEY required with BUZZ_REQUIRE_RELAY_MEMBERSHIP=true}"
+    BUZZ_RELAY_PRIVATE_KEY="${BUZZ_RELAY_PRIVATE_KEY:?BUZZ_RELAY_PRIVATE_KEY required with BUZZ_REQUIRE_RELAY_MEMBERSHIP=true}"
+  )
+  log "Membership gating enabled (NIP-43)"
+fi
+
 nohup env \
   DATABASE_URL=postgres://buzz:buzz_dev@localhost:5432/buzz \
   REDIS_URL=redis://localhost:6379 \
@@ -159,6 +173,7 @@ nohup env \
   BUZZ_REQUIRE_AUTH_TOKEN=false \
   BUZZ_RECONCILE_CHANNELS=true \
   BUZZ_GIT_PROBE_WRITERS=8 \
+  ${MEMBERSHIP_ENV[@]+"${MEMBERSHIP_ENV[@]}"} \
   "./target/${CARGO_PROFILE}/buzz-relay" > /tmp/buzz-relay.log 2>&1 &
 echo $! > /tmp/buzz-relay.pid
 

From 96ae141763e5459beb68a847e0082e931af72f4c Mon Sep 17 00:00:00 2001
From: Wes <wesbillman@users.noreply.github.com>
Date: Wed, 5 Aug 2026 22:53:25 -0600
Subject: [PATCH 07/16] fix(desktop): skip native notifications outside app
 bundles (#5004)

## Summary

- require the macOS process to be running from an actual `.app` bundle
before initializing `UNUserNotificationCenter`
- keep the existing bundle-identifier requirement
- cover packaged, case-insensitive `.app`, raw `target/debug`, and
extensionless paths

## Why

PR #4799 guarded native notification initialization with
`NSBundle.mainBundle.bundleIdentifier != nil`. Tauri embeds a bundle
identifier in raw development executables, so `tauri dev` passed that
guard and `UNUserNotificationCenter.current()` raised an uncaught
`NSInternalInconsistencyException` because LaunchServices had no bundle
proxy.

## Validation

- focused macOS notification tests: 6 passed
- direct raw debug executable no longer raises the notification-center
exception
- pre-commit formatting hook passed
- pre-push package checks passed on pushed commit
`f29a6664d2a863e7b8aa527f6149fd00b183e4de`

The first push attempt hit an unrelated timing-test failure in
`relay_admission::tests::concurrent_429_extends_the_window_for_parked_waiters`;
its focused rerun passed, and the complete pre-push package suite passed
on the next push.

Signed-off-by: Wes <wesbillman@users.noreply.github.com>
Co-authored-by: Carl <c7ebe626f000404285d3686e1dc74cc07cc60a9754a150041ba132e14bd3e2ec@buzz.block.builderlab.xyz>
---
 desktop/src-tauri/src/macos_notifications.rs | 54 ++++++++++++++++++--
 1 file changed, 50 insertions(+), 4 deletions(-)

diff --git a/desktop/src-tauri/src/macos_notifications.rs b/desktop/src-tauri/src/macos_notifications.rs
index da2312b457..5bcedd8975 100644
--- a/desktop/src-tauri/src/macos_notifications.rs
+++ b/desktop/src-tauri/src/macos_notifications.rs
@@ -8,6 +8,7 @@
 
 use std::{
     collections::VecDeque,
+    path::Path,
     ptr::NonNull,
     sync::{mpsc, Mutex, OnceLock},
     time::Duration,
@@ -128,7 +129,7 @@ pub(crate) fn init(app: &AppHandle) -> tauri::Result<()> {
         // objc2 cannot turn that exception into a Rust error, so do not call
         // into the framework at all in this environment.
         eprintln!(
-            "buzz-desktop: macOS notifications disabled because the process has no bundle identifier"
+            "buzz-desktop: macOS notifications disabled because the process is not running from an app bundle"
         );
         return Ok(());
     }
@@ -293,7 +294,30 @@ pub(crate) fn take_pending_activations() -> Result<Vec<serde_json::Value>, Strin
 }
 
 fn is_bundled_application() -> bool {
-    NSBundle::mainBundle().bundleIdentifier().is_some()
+    let bundle = NSBundle::mainBundle();
+    bundle.bundleIdentifier().is_some()
+        && bundle.executablePath().is_some_and(|executable_path| {
+            is_application_bundle_layout(
+                Path::new(&bundle.bundlePath().to_string()),
+                Path::new(&executable_path.to_string()),
+            )
+        })
+}
+
+fn is_application_bundle_layout(bundle_path: &Path, executable_path: &Path) -> bool {
+    let Some(macos_path) = executable_path.parent() else {
+        return false;
+    };
+    let Some(contents_path) = macos_path.parent() else {
+        return false;
+    };
+
+    bundle_path
+        .extension()
+        .is_some_and(|extension| extension == "app")
+        && macos_path.file_name() == Some("MacOS".as_ref())
+        && contents_path.file_name() == Some("Contents".as_ref())
+        && contents_path.parent() == Some(bundle_path)
 }
 
 fn target_from_response(response: &UNNotificationResponse) -> Option<serde_json::Value> {
@@ -311,10 +335,12 @@ fn parse_target(serialized: &str) -> Option<serde_json::Value> {
 #[cfg(test)]
 mod tests {
     use super::{
-        is_bundled_application, parse_target, permission_state, queue_activation,
-        take_pending_activations, NotificationPermissionState, MAX_PENDING_ACTIVATIONS,
+        is_application_bundle_layout, is_bundled_application, parse_target, permission_state,
+        queue_activation, take_pending_activations, NotificationPermissionState,
+        MAX_PENDING_ACTIVATIONS,
     };
     use objc2_user_notifications::UNAuthorizationStatus;
+    use std::path::Path;
 
     #[test]
     fn activation_queue_is_bounded_and_drained() {
@@ -336,6 +362,26 @@ mod tests {
         assert!(!is_bundled_application());
     }
 
+    #[test]
+    fn requires_the_executable_to_use_the_app_bundle_layout() {
+        assert!(is_application_bundle_layout(
+            Path::new("/Applications/Buzz.app"),
+            Path::new("/Applications/Buzz.app/Contents/MacOS/buzz-desktop"),
+        ));
+        assert!(!is_application_bundle_layout(
+            Path::new("/tmp/Fake.app"),
+            Path::new("/tmp/Fake.app/buzz-desktop"),
+        ));
+        assert!(!is_application_bundle_layout(
+            Path::new("/Users/developer/buzz/desktop/src-tauri/target/debug"),
+            Path::new("/Users/developer/buzz/desktop/src-tauri/target/debug/buzz-desktop"),
+        ));
+        assert!(!is_application_bundle_layout(
+            Path::new("/Applications/Buzz.app"),
+            Path::new("/Applications/Other.app/Contents/MacOS/buzz-desktop"),
+        ));
+    }
+
     #[test]
     fn maps_native_authorization_states_to_frontend_contract() {
         assert_eq!(

From 19b41e9c8edafb02159e597935a8c41f1b6493a2 Mon Sep 17 00:00:00 2001
From: Wes <wesbillman@users.noreply.github.com>
Date: Thu, 6 Aug 2026 08:39:17 -0600
Subject: [PATCH 08/16] fix(desktop): stop rate-limited reconnect backfill from
 tearing down the authenticated socket (#4990)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Problem

Users on v0.5.5 report "Can't reach the relay" toggling with brief
"connected" flashes (field reports; also the macOS confirmation in
#4908). #4737 closed the stuck-reconnect gaps; this is the opposite
failure: the client redials fine, but then kills its own healthy socket.

Mechanism (all on `main`):

1. AUTH succeeds → session emits `connected`
(`relayClientSession.ts:583`), then awaits `replayLiveSubscriptions()`.
2. Paged channel backfill issues history REQs
(`relayReconnectReplay.ts`, page limit 500).
3. A `CLOSED rate-limited:` on a **history** REQ arms the rate-limit
gate but still rejects the history promise
(`relayClosedRecovery.ts:38-51`).
4. The rejection escapes `replayLiveSubscriptions()` →
`resetConnection()` tears down the authenticated socket.
5. Reconnect → AUTH OK → replay rate-limited again → loop. Each
iteration re-spends the rate-limit budget, so the loop is
self-sustaining.

## Fix

Contain backfill failures inside the replay. Each subscription's paged
backfill now retries behind the rate-limit gate up to
`PAGE_REPLAY_MAX_ATTEMPTS` (3), then degrades to live-only **for this
connection**. Socket health no longer depends on backfill success.
Nothing is lost: the replay cursor (`lastSeenCreatedAt`) only advances
on delivered events, so the next reconnect replays the same missed
window.

## Red/green proof

- Commit 1 (Pinky): e2e injecting `CLOSED rate-limited:` into the
mid-replay history REQ — **red on main** (expected 1 reconnect dial,
observed 2; connected-flash then teardown).
- Commit 2 (this fix): same test **green unchanged** — one dial, state
stays `connected` through the rate-limit hint plus the next backoff
window.

Why existing coverage missed it: the prior rate-limit e2e pre-armed the
gate *before* replay (replay politely waits), and the CLOSED-injection
test targeted a *live* subscription (which has its own retry path).
Nobody injected back-pressure from the history REQ itself.

## Verification

- `pnpm test`: 4374/4374 pass.
- `playwright test tests/e2e/relay-reconnect.spec.ts`: 14/14 pass,
including the new spec.
- `tsc --noEmit` clean; Biome clean on touched files (pre-existing
warnings on main in `personaCatalogRelay.test.mjs` / `terminal.css`
untouched).

## Not addressed here (follow-ups from the same field reports)

- AUTH terminal latch is too aggressive for relay-internal `error:`
rejections (3 strikes during a relay bad window → stuck until
click/relaunch; #4908).
- Server-side: `relay.drainJitterMs` (#4542) defaults to 0 — enabling it
on the hosted relay removes the deploy thundering herd that triggers
these rate-limit storms.

---------

Signed-off-by: Pinky <44b8e82baa6e0e254e0208d68f335c283c94e7b78dd1fa10d5a49d3f13dd0435@buzz.block.builderlab.xyz>
Signed-off-by: Brain <21994759fc7a6fa6b965551d35cfd7897d262f2495467f2d78694ddcfa6a5c7e@buzz.block.builderlab.xyz>
Co-authored-by: Pinky <44b8e82baa6e0e254e0208d68f335c283c94e7b78dd1fa10d5a49d3f13dd0435@buzz.block.builderlab.xyz>
Co-authored-by: Brain <21994759fc7a6fa6b965551d35cfd7897d262f2495467f2d78694ddcfa6a5c7e@buzz.block.builderlab.xyz>
---
 desktop/src/shared/api/relayClientShared.ts   |  11 +
 .../shared/api/relayReconnectReplay.test.mjs  | 250 ++++++++++++++++++
 .../src/shared/api/relayReconnectReplay.ts    | 101 ++++++-
 desktop/src/testing/e2eBridge.ts              |  14 +
 desktop/tests/e2e/relay-reconnect.spec.ts     |  68 +++++
 5 files changed, 431 insertions(+), 13 deletions(-)

diff --git a/desktop/src/shared/api/relayClientShared.ts b/desktop/src/shared/api/relayClientShared.ts
index 9108f7b6d7..3952b6af6f 100644
--- a/desktop/src/shared/api/relayClientShared.ts
+++ b/desktop/src/shared/api/relayClientShared.ts
@@ -60,6 +60,17 @@ type LiveSubscription = {
   onEvent: (event: RelayEvent) => void;
   resolveReady?: () => void;
   lastSeenCreatedAt?: number;
+  /**
+   * Lower bound of a reconnect backfill window that has not yet completed.
+   *
+   * Events on the restored live REQ advance `lastSeenCreatedAt` regardless of
+   * backfill success, so after an exhausted backfill the cursor alone would
+   * make the next reconnect skip the unresolved older window — silent message
+   * loss. This floor is pinned when paging starts and cleared only when a
+   * backfill pass completes; the next replay starts from
+   * `min(pendingReplaySince, cursor window)`.
+   */
+  pendingReplaySince?: number;
   closedRetryAttempt?: number;
   closedRetryTimeout?: number;
 };
diff --git a/desktop/src/shared/api/relayReconnectReplay.test.mjs b/desktop/src/shared/api/relayReconnectReplay.test.mjs
index 59253a459f..c175272885 100644
--- a/desktop/src/shared/api/relayReconnectReplay.test.mjs
+++ b/desktop/src/shared/api/relayReconnectReplay.test.mjs
@@ -3,11 +3,13 @@ import test from "node:test";
 
 import {
   buildReconnectReplayFilter,
+  PAGE_REPLAY_MAX_ATTEMPTS,
   replayLiveSubscriptions,
   REPLAY_BATCH_SIZE,
   shouldPageReconnectReplay,
 } from "./relayReconnectReplay.ts";
 import { buildChannelFilter } from "./relayChannelFilters.ts";
+import { prepareSubscriptionEvent } from "./relayClosedRecovery.ts";
 
 // ── Fake-timer + Date.now setup for gate tests ────────────────────────────────
 
@@ -600,6 +602,254 @@ test("batch-1 arms gate mid-replay: batch-2 is withheld until gate expires", asy
   );
 });
 
+// ── Backfill failure containment ─────────────────────────────────────────────
+
+test("history backfill rejection never escapes replayLiveSubscriptions", async () => {
+  resetGate(0);
+  const filter = buildChannelFilter("channel-1", 50);
+  const subscriptions = new Map([
+    [
+      "live-1",
+      {
+        mode: "live",
+        filter,
+        onEvent: () => {},
+        lastSeenCreatedAt: 1000,
+      },
+    ],
+  ]);
+
+  let historyCalls = 0;
+  // Must resolve — a rejection here is the socket-killing flap regression.
+  await replayLiveSubscriptions({
+    subscriptions,
+    now: 2000,
+    sendRaw: async () => {},
+    requestHistory: async () => {
+      historyCalls++;
+      throw new Error("rate-limited: quota exceeded; retry in 4s");
+    },
+  });
+
+  assert.equal(
+    historyCalls,
+    PAGE_REPLAY_MAX_ATTEMPTS,
+    "backfill must retry a bounded number of times, then degrade",
+  );
+});
+
+test("backfill retry waits out the armed gate, then succeeds", async () => {
+  resetGate(0);
+  const delivered = [];
+  const filter = buildChannelFilter("channel-1", 50);
+  const subscriptions = new Map([
+    [
+      "live-1",
+      {
+        mode: "live",
+        filter,
+        onEvent: (event) => delivered.push(event),
+        lastSeenCreatedAt: 1000,
+      },
+    ],
+  ]);
+
+  const attemptAtMs = [];
+  let armGate;
+  const gateArmed = new Promise((resolve) => {
+    armGate = resolve;
+  });
+  const replayPromise = replayLiveSubscriptions({
+    subscriptions,
+    now: 2000,
+    sendRaw: async () => {},
+    requestHistory: async () => {
+      attemptAtMs.push(fakeNow);
+      if (attemptAtMs.length === 1) {
+        // Mirror relayClosedRecovery: the CLOSED handler arms the gate
+        // before rejecting the history promise.
+        activateRateLimit(4);
+        armGate();
+        throw new Error("rate-limited: quota exceeded; retry in 4s");
+      }
+      return [event("recovered", 1500)];
+    },
+  });
+
+  // Wait until the gate is actually armed, then expire it. The retry loop is
+  // (or will be) suspended in waitForRateLimit; expiring the gate releases it.
+  await gateArmed;
+  tickTo(4_001);
+  await replayPromise;
+
+  assert.equal(attemptAtMs.length, 2, "one failure, one retry");
+  assert.ok(
+    attemptAtMs[1] >= 4_001,
+    "retry must not fire before the rate-limit gate expires",
+  );
+  assert.deepEqual(
+    delivered.map((e) => e.id),
+    ["recovered"],
+    "the retried backfill must deliver its events",
+  );
+});
+
+test("backfill retry aborts when the subscription was replaced", async () => {
+  resetGate(0);
+  const filter = buildChannelFilter("channel-1", 50);
+  const subscription = {
+    mode: "live",
+    filter,
+    onEvent: () => {},
+    lastSeenCreatedAt: 1000,
+  };
+  const subscriptions = new Map([["live-1", subscription]]);
+
+  let historyCalls = 0;
+  await replayLiveSubscriptions({
+    subscriptions,
+    now: 2000,
+    sendRaw: async () => {},
+    requestHistory: async () => {
+      historyCalls++;
+      // Simulate the subscription being torn down while the REQ is in flight.
+      subscriptions.delete("live-1");
+      throw new Error("rate-limited: quota exceeded; retry in 4s");
+    },
+  });
+
+  assert.equal(
+    historyCalls,
+    1,
+    "no retry may target a subscription that no longer exists",
+  );
+});
+
+test("exhausted backfill pins the floor: next replay still requests the original window after live events advance the cursor", async () => {
+  // The blocking review scenario on PR #4990: cursor=1000, all backfill
+  // attempts fail, a live event at 2100 then advances lastSeenCreatedAt via
+  // prepareSubscriptionEvent. Without the pinned floor, the next reconnect
+  // would start near 2095 and silently skip 1001..1999.
+  resetGate(0);
+  const filter = buildChannelFilter("channel-1", 50);
+  const subscription = {
+    mode: "live",
+    filter,
+    onEvent: () => {},
+    lastSeenCreatedAt: 1000,
+  };
+  const subscriptions = new Map([["live-1", subscription]]);
+
+  // Reconnect 1: every backfill attempt is rate-limited.
+  await replayLiveSubscriptions({
+    subscriptions,
+    now: 2000,
+    sendRaw: async () => {},
+    requestHistory: async () => {
+      throw new Error("rate-limited: quota exceeded; retry in 4s");
+    },
+  });
+  assert.equal(
+    subscription.pendingReplaySince,
+    995,
+    "exhausted backfill must pin the unresolved window's lower bound",
+  );
+
+  // A live event arrives through the normal cursor path.
+  prepareSubscriptionEvent(subscription, event("live-newer", 2100));
+  assert.equal(subscription.lastSeenCreatedAt, 2100);
+
+  // Reconnect 2: backfill now succeeds. It must request the ORIGINAL window.
+  const historyFilters = [];
+  await replayLiveSubscriptions({
+    subscriptions,
+    now: 2200,
+    sendRaw: async () => {},
+    requestHistory: async (filter) => {
+      historyFilters.push(filter);
+      return [];
+    },
+  });
+
+  assert.equal(historyFilters.length, 1);
+  assert.equal(
+    historyFilters[0].since,
+    995,
+    "replay must start from the pinned floor, not the advanced cursor",
+  );
+  assert.equal(
+    subscription.pendingReplaySince,
+    undefined,
+    "a completed backfill must clear the pinned floor",
+  );
+
+  // Reconnect 3: with the floor cleared, replay returns to the cursor.
+  const laterFilters = [];
+  await replayLiveSubscriptions({
+    subscriptions,
+    now: 2300,
+    sendRaw: async () => {},
+    requestHistory: async (filter) => {
+      laterFilters.push(filter);
+      return [];
+    },
+  });
+  assert.equal(
+    laterFilters[0].since,
+    2095,
+    "after recovery the cursor governs again",
+  );
+});
+
+test("in-flight stale abort keeps the pinned floor for the superseding connection", async () => {
+  // Race from re-review of b70a6716d/c493d378b: production supersession bumps
+  // the connection GENERATION while the same subscription key and object
+  // survive in the map. The identity guard alone stays true, so only the
+  // combined guard (outer isActive && identity) aborts the stale pass. That
+  // abort must NOT count as completion — the pinned floor belongs to the
+  // superseding connection's replay.
+  resetGate(0);
+  const filter = buildChannelFilter("channel-1", 50);
+  const subscription = {
+    mode: "live",
+    filter,
+    onEvent: () => {},
+    lastSeenCreatedAt: 1000,
+  };
+  const subscriptions = new Map([["live-1", subscription]]);
+
+  let generationActive = true;
+  let historyCalls = 0;
+  await replayLiveSubscriptions({
+    subscriptions,
+    now: 2000,
+    sendRaw: async () => {},
+    isActive: () => generationActive,
+    requestHistory: async () => {
+      historyCalls++;
+      // Connection A is superseded while the REQ is in flight: the generation
+      // advances, but the subscription keeps its key AND object identity —
+      // exactly what production supersession does.
+      generationActive = false;
+      // A full page would otherwise continue paging — the post-await
+      // combined guard must abort instead.
+      return eventRange("full", 1001, 500);
+    },
+  });
+
+  assert.equal(historyCalls, 1, "stale generation must stop paging");
+  assert.equal(
+    subscriptions.get("live-1"),
+    subscription,
+    "precondition: key and object survive supersession untouched",
+  );
+  assert.equal(
+    subscription.pendingReplaySince,
+    995,
+    "a stale-generation abort must not clear the floor the new connection needs",
+  );
+});
+
 // ── Teardown ──────────────────────────────────────────────────────────────────
 
 test("teardown — restore Date.now", () => {
diff --git a/desktop/src/shared/api/relayReconnectReplay.ts b/desktop/src/shared/api/relayReconnectReplay.ts
index 74b752f666..cb962ce846 100644
--- a/desktop/src/shared/api/relayReconnectReplay.ts
+++ b/desktop/src/shared/api/relayReconnectReplay.ts
@@ -13,6 +13,22 @@ const RECONNECT_REPLAY_SKEW_SECS = 5;
 export const RECONNECT_REPLAY_PAGE_LIMIT = 500;
 export const RECONNECT_REPLAY_PAGE_CONCURRENCY = 4;
 
+/**
+ * Maximum attempts for one subscription's paged history backfill.
+ *
+ * Backfill failures must never escape `replayLiveSubscriptions`: by the time
+ * paging starts, every live REQ has already been re-established on a healthy,
+ * authenticated socket. Letting a history rejection propagate makes the
+ * session tear that socket down (`resetConnection`) and reconnect straight
+ * into the same rate-limit window — the "briefly connected → can't reach the
+ * relay" flap loop. Instead each sub retries behind the rate-limit gate a
+ * bounded number of times, then degrades to live-only for this connection.
+ * The window's lower bound is pinned in `pendingReplaySince` while unresolved
+ * (live events advance `lastSeenCreatedAt` regardless of backfill success),
+ * so the next reconnect still requests the missed window.
+ */
+export const PAGE_REPLAY_MAX_ATTEMPTS = 3;
+
 /**
  * Maximum live subscriptions sent per relay REQ burst during reconnect.
  *
@@ -78,6 +94,16 @@ export function shouldPageReconnectReplay(filter: RelaySubscriptionFilter) {
   );
 }
 
+/**
+ * Page one subscription's missed-window history.
+ *
+ * Returns `true` only when the window was genuinely completed (short page or
+ * boundary reached). Returns `false` when the pass aborted because the
+ * connection went stale (`isActive()` false) — callers must NOT treat that as
+ * completion: the same subscription object is shared with the superseding
+ * connection, and clearing its pinned `pendingReplaySince` on a stale abort
+ * would erase the floor the new connection still needs.
+ */
 export async function replayReconnectHistoryPages({
   subscription,
   since,
@@ -90,11 +116,11 @@ export async function replayReconnectHistoryPages({
   until: number;
   isActive: () => boolean;
   requestHistory: (filter: RelaySubscriptionFilter) => Promise<RelayEvent[]>;
-}) {
+}): Promise<boolean> {
   let pageUntil = until;
 
   while (pageUntil >= since) {
-    if (!isActive()) return;
+    if (!isActive()) return false;
 
     const events = await requestHistory(
       buildReconnectReplayFilter(
@@ -105,17 +131,18 @@ export async function replayReconnectHistoryPages({
       ),
     );
 
-    if (!isActive()) return;
+    if (!isActive()) return false;
 
     for (const event of events) subscription.onEvent(event);
-    if (events.length < RECONNECT_REPLAY_PAGE_LIMIT) return;
+    if (events.length < RECONNECT_REPLAY_PAGE_LIMIT) return true;
 
     const oldestCreatedAt = events[0]?.created_at;
-    if (oldestCreatedAt === undefined || oldestCreatedAt <= since) return;
+    if (oldestCreatedAt === undefined || oldestCreatedAt <= since) return true;
 
     pageUntil =
       oldestCreatedAt < pageUntil ? oldestCreatedAt : oldestCreatedAt - 1;
   }
+  return true;
 }
 
 export async function replayLiveSubscriptions({
@@ -167,13 +194,21 @@ export async function replayLiveSubscriptions({
         entry[1].mode === "live",
     )
     .map(([subId, subscription]) => {
-      const replaySince =
+      const cursorSince =
         subscription.lastSeenCreatedAt === undefined
           ? undefined
           : Math.max(
               0,
               subscription.lastSeenCreatedAt - RECONNECT_REPLAY_SKEW_SECS,
             );
+      // A pinned floor from a previously failed backfill takes precedence
+      // over the cursor: live events kept advancing `lastSeenCreatedAt`
+      // while the older window stayed unresolved, and starting from the
+      // cursor would skip it permanently.
+      const replaySince =
+        cursorSince === undefined
+          ? subscription.pendingReplaySince
+          : Math.min(cursorSince, subscription.pendingReplaySince ?? Infinity);
       const shouldPageReplay =
         replaySince !== undefined &&
         shouldPageReconnectReplay(subscription.filter);
@@ -237,13 +272,53 @@ export async function replayLiveSubscriptions({
     ),
     pageReplayConcurrency,
     async ({ subId, subscription, replaySince }) => {
-      await replayReconnectHistoryPages({
-        subscription,
-        since: replaySince,
-        until: now,
-        isActive: () => subscriptions.get(subId) === subscription,
-        requestHistory,
-      });
+      // Backfill is best-effort: a failure here (typically a `rate-limited:`
+      // CLOSED on a history REQ) must never escape to the session and tear
+      // down the healthy, authenticated socket carrying the live REQs — that
+      // is the connect→drop flap loop. Retry behind the gate a bounded number
+      // of times, then degrade to live-only for this connection.
+      //
+      // Pin the window's lower bound before the first attempt: events on the
+      // already-restored live REQ advance `lastSeenCreatedAt` independently
+      // of backfill success, so without the pin an exhausted backfill
+      // followed by one live event would make the next reconnect skip the
+      // unresolved window permanently. Cleared only on a completed pass.
+      subscription.pendingReplaySince = replaySince;
+      for (let attempt = 1; attempt <= PAGE_REPLAY_MAX_ATTEMPTS; attempt++) {
+        try {
+          const completed = await replayReconnectHistoryPages({
+            subscription,
+            since: replaySince,
+            until: now,
+            // Both guards are required. The identity check catches the sub
+            // being torn down/replaced; the outer isActive() catches
+            // connection supersession, which bumps the generation while the
+            // SAME subscription key and object survive in the map — identity
+            // alone stays true and a stale pass could complete and clear the
+            // floor the superseding connection needs.
+            isActive: () =>
+              isActive() && subscriptions.get(subId) === subscription,
+            requestHistory,
+          });
+          // A stale-connection abort is NOT completion: the superseding
+          // connection shares this subscription object and still needs the
+          // pinned floor for its own replay. Only a genuinely completed
+          // window may release it.
+          if (completed) subscription.pendingReplaySince = undefined;
+          return;
+        } catch (error) {
+          console.warn(
+            `[reconnect replay] history backfill attempt ${attempt}/${PAGE_REPLAY_MAX_ATTEMPTS} failed for ${subId}:`,
+            error,
+          );
+          if (attempt === PAGE_REPLAY_MAX_ATTEMPTS) return;
+          // The failed REQ's CLOSED handler arms the rate-limit gate before
+          // rejecting; wait for it (no-op when the failure wasn't back-pressure)
+          // and re-check that this replay's connection is still current.
+          if (isRateLimited()) await waitForRateLimit();
+          if (subscriptions.get(subId) !== subscription || !isActive()) return;
+        }
+      }
     },
   );
 }
diff --git a/desktop/src/testing/e2eBridge.ts b/desktop/src/testing/e2eBridge.ts
index 54238323ae..1987e00ff1 100644
--- a/desktop/src/testing/e2eBridge.ts
+++ b/desktop/src/testing/e2eBridge.ts
@@ -1211,6 +1211,8 @@ declare global {
     ) => void;
     /** Inject CLOSED into every active mock live subscription. */
     __BUZZ_E2E_CLOSE_LIVE_SUBSCRIPTIONS__?: (reason: string) => number;
+    /** Queue CLOSED responses for channel history REQs. */
+    __BUZZ_E2E_QUEUE_CHANNEL_HISTORY_CLOSES__?: (reasons: string[]) => void;
     __BUZZ_E2E_SET_STALL_WEBSOCKET_SENDS__?: (stall: boolean) => void;
     __BUZZ_E2E_DISCONNECT_MOCK_WEBSOCKETS__?: () => number;
     __BUZZ_E2E_RESTART_MOCK_WEBSOCKETS__?: () => number;
@@ -2967,6 +2969,7 @@ const mockPersonaEvents: RelayEvent[] = [];
 let mockRelayMembers: RawRelayMember[] = [];
 const mockSockets = new Map<number, MockSocket>();
 const mockAuthResponses: Array<{ success: boolean; message: string }> = [];
+const mockChannelHistoryCloses: string[] = [];
 let mockWebsocketUnavailable = false;
 const relayWebsocketConnectAttemptStarts: number[] = [];
 let mockWebsocketSendMutexWedged = false;
@@ -9691,6 +9694,13 @@ function sendToMockSocket(args: {
     }
 
     const channelId = filter["#h"]?.[0];
+    if (channelId && subId.startsWith("history-")) {
+      const closeReason = mockChannelHistoryCloses.shift();
+      if (closeReason) {
+        sendWsText(socket.handler, ["CLOSED", subId, closeReason]);
+        return;
+      }
+    }
     if (!channelId) {
       // Aux-backfill filters (reactions/deletions) are `#e`-keyed with no
       // channel tag — serve them across all channel stores like the relay.
@@ -9945,6 +9955,7 @@ export function maybeInstallE2eTauriMocks() {
   mockClosedChannelLiveSubscription = false;
   mockWebsocketUnavailable = false;
   mockAuthResponses.length = 0;
+  mockChannelHistoryCloses.length = 0;
   relayWebsocketConnectAttemptStarts.length = 0;
   deferredSendMessageLiveEchoes.length = 0;
   mockGlobalAgentConfig = config.mock?.globalAgentConfig
@@ -10188,6 +10199,9 @@ export function maybeInstallE2eTauriMocks() {
   window.__BUZZ_E2E_QUEUE_AUTH_RESPONSES__ = (responses) => {
     mockAuthResponses.push(...responses);
   };
+  window.__BUZZ_E2E_QUEUE_CHANNEL_HISTORY_CLOSES__ = (reasons) => {
+    mockChannelHistoryCloses.push(...reasons);
+  };
   window.__BUZZ_E2E_CLOSE_LIVE_SUBSCRIPTIONS__ = (reason) => {
     let closed = 0;
     for (const socket of mockSockets.values()) {
diff --git a/desktop/tests/e2e/relay-reconnect.spec.ts b/desktop/tests/e2e/relay-reconnect.spec.ts
index ec3e87171d..289d8ef318 100644
--- a/desktop/tests/e2e/relay-reconnect.spec.ts
+++ b/desktop/tests/e2e/relay-reconnect.spec.ts
@@ -134,6 +134,19 @@ async function closeLiveSubscriptions(
   expect(closed).toBeGreaterThan(0);
 }
 
+async function queueChannelHistoryCloses(
+  page: import("@playwright/test").Page,
+  reasons: string[],
+) {
+  await page.evaluate((queued) => {
+    const queue = window.__BUZZ_E2E_QUEUE_CHANNEL_HISTORY_CLOSES__;
+    if (!queue) {
+      throw new Error("E2E channel history CLOSED seam is not installed.");
+    }
+    queue(queued);
+  }, reasons);
+}
+
 async function driveConnectionDegraded(
   page: import("@playwright/test").Page,
   state: "connected" | "reconnecting" | "stalled" | "disconnected",
@@ -253,6 +266,61 @@ test("authenticated reconnect reports connected while replay is rate-limited", a
   await expect(page.getByTestId("sidebar-relay-unreachable")).toHaveCount(0);
 });
 
+test("rate-limited reconnect backfill does not tear down the authenticated socket", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+
+  // Give the channel live subscription a replay cursor. On reconnect this
+  // causes a paged channel-history REQ in addition to restoring the live REQ.
+  await emitMockMessages(page, [
+    {
+      content: `replay cursor ${Date.now()}`,
+      createdAt: Math.floor(Date.now() / 1_000),
+    },
+  ]);
+  const attemptsBeforeReconnect = (await getMockWebsocketConnectAttempts(page))
+    .length;
+
+  // Inject back-pressure from the history REQ itself. This differs from a
+  // pre-armed gate and from CLOSED on the live subscription: AUTH has already
+  // succeeded and the socket is healthy when replay backfill is rejected.
+  await queueChannelHistoryCloses(page, [
+    "rate-limited: quota exceeded; retry in 1s",
+  ]);
+  await disconnectMockWebsockets(page);
+
+  await expect
+    .poll(
+      async () =>
+        (await getMockWebsocketConnectAttempts(page)).length -
+        attemptsBeforeReconnect,
+      { timeout: 3_000 },
+    )
+    .toBe(1);
+  await expect
+    .poll(() =>
+      page.evaluate(() => window.__BUZZ_E2E_GET_RELAY_CONNECTION_STATE__?.()),
+    )
+    .toBe("connected");
+
+  // Hold through the rate-limit hint plus the next base-backoff window. The
+  // authenticated socket must remain the only reconnect attempt, rather than
+  // flashing connected and redialing after replay rejects.
+  await page.waitForTimeout(2_500);
+  expect(
+    (await getMockWebsocketConnectAttempts(page)).length -
+      attemptsBeforeReconnect,
+  ).toBe(1);
+  expect(
+    await page.evaluate(() =>
+      window.__BUZZ_E2E_GET_RELAY_CONNECTION_STATE__?.(),
+    ),
+  ).toBe("connected");
+});
+
 test("service restart close resets accumulated backoff", async ({ page }) => {
   await installMockBridge(page, {
     websocketConnectErrors: ["down 1", "down 2", "down 3"],

From 5babb97ca3b9c9d640f7dcdfdef456178e868ff7 Mon Sep 17 00:00:00 2001
From: Wes <wesbillman@users.noreply.github.com>
Date: Thu, 6 Aug 2026 08:39:36 -0600
Subject: [PATCH 09/16] feat(desktop): show selected community in rail (#5000)

## Summary
- add a persistent vertical pill beside the active community
- keep the selected state visually distinct from unread dots and mention
badges
- preserve the existing `aria-current` selection semantics

## Screenshot
![Selected community
indicator](https://d24qwcpro867f5.cloudfront.net/repos/block/buzz/prs/5000/selected-community-indicator-v2.png)

## Test plan
- `pnpm exec biome check src/features/sidebar/ui/CommunityRail.tsx
tests/e2e/community-rail.spec.ts`
- `pnpm test` (4,387 passed)
- `pnpm build:e2e && pnpm exec playwright test
tests/e2e/community-rail.spec.ts --project=smoke` (20 passed)
- pre-push hooks: desktop check and 4,387 desktop tests passed on
`c1e80c66d12f73c4eb5c03a19e932439b14caf2d`

Signed-off-by: Wes <wesbillman@users.noreply.github.com>
Co-authored-by: Carl <c7ebe626f000404285d3686e1dc74cc07cc60a9754a150041ba132e14bd3e2ec@buzz.block.builderlab.xyz>
---
 .../src/features/sidebar/ui/CommunityRail.tsx |  9 ++++++++-
 desktop/tests/e2e/community-rail.spec.ts      | 20 ++++++++++++++-----
 2 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/desktop/src/features/sidebar/ui/CommunityRail.tsx b/desktop/src/features/sidebar/ui/CommunityRail.tsx
index a572bb8eb6..5394065b19 100644
--- a/desktop/src/features/sidebar/ui/CommunityRail.tsx
+++ b/desktop/src/features/sidebar/ui/CommunityRail.tsx
@@ -133,10 +133,17 @@ function CommunityButton({
               {...dragAttributes}
               {...dragListeners}
             >
+              {isActive ? (
+                <span
+                  aria-hidden="true"
+                  className="absolute -left-2.5 h-5 w-1 rounded-r-full bg-primary"
+                  data-testid={`community-rail-active-${community.id}`}
+                />
+              ) : null}
               <span
                 className={cn(
                   "flex h-9 w-9 items-center justify-center overflow-hidden rounded-xl bg-sidebar-accent/60 text-xs font-semibold text-sidebar-foreground/80 outline-2 outline-offset-2 outline-primary/0 transition-[outline-color]",
-                  isActive ? "outline-primary" : "hover:outline-primary/50",
+                  !isActive && "hover:outline-primary/50",
                 )}
               >
                 {iconUrl ? (
diff --git a/desktop/tests/e2e/community-rail.spec.ts b/desktop/tests/e2e/community-rail.spec.ts
index 33f4808cd8..0a4c8830e1 100644
--- a/desktop/tests/e2e/community-rail.spec.ts
+++ b/desktop/tests/e2e/community-rail.spec.ts
@@ -66,13 +66,21 @@ test.describe("community rail", () => {
     await expect(buttonA).toBeVisible();
     await expect(buttonB).toBeVisible();
 
-    // The active community is marked via aria-current.
+    // The active community is marked semantically and with a persistent rail.
     await expect(buttonA).toHaveAttribute("aria-current", "true");
     await expect(buttonB).not.toHaveAttribute("aria-current", "true");
-    await expect(buttonA.locator(":scope > span").first()).toHaveCSS(
-      "opacity",
-      "1",
+    const activeIndicator = page.getByTestId(
+      `community-rail-active-${COMMUNITY_A.id}`,
     );
+    await expect(activeIndicator).toBeVisible();
+    await expect(
+      page.getByTestId(`community-rail-active-${COMMUNITY_B.id}`),
+    ).toHaveCount(0);
+    await expect(activeIndicator).toHaveCSS("height", "20px");
+    await expect(activeIndicator).toHaveCSS("width", "4px");
+    await expect(
+      buttonA.locator(":scope > span:not([data-testid])").first(),
+    ).toHaveCSS("opacity", "1");
     await expect(buttonB.locator(":scope > span").first()).toHaveCSS(
       "opacity",
       "1",
@@ -80,7 +88,7 @@ test.describe("community rail", () => {
     const [activeStyle, inactiveStyle] = await Promise.all(
       [buttonA, buttonB].map((button) =>
         button
-          .locator(":scope > span")
+          .locator(":scope > span:not([data-testid])")
           .first()
           .evaluate((element) => {
             const style = getComputedStyle(element);
@@ -88,6 +96,7 @@ test.describe("community rail", () => {
               backgroundColor: style.backgroundColor,
               borderRadius: style.borderRadius,
               color: style.color,
+              outlineColor: style.outlineColor,
               outlineStyle: style.outlineStyle,
               outlineWidth: style.outlineWidth,
             };
@@ -98,6 +107,7 @@ test.describe("community rail", () => {
     expect(activeStyle.borderRadius).toBe(inactiveStyle.borderRadius);
     expect(activeStyle.borderRadius).toBe("12px");
     expect(activeStyle.color).toBe(inactiveStyle.color);
+    expect(activeStyle.outlineColor).toBe(inactiveStyle.outlineColor);
     expect(activeStyle.outlineStyle).toBe("solid");
     expect(activeStyle.outlineWidth).toBe("2px");
     expect(inactiveStyle.outlineStyle).toBe("solid");

From 480c41ebf1173dfe923bf59774dc283b046211fc Mon Sep 17 00:00:00 2001
From: klopez4212 <klopez4212@gmail.com>
Date: Thu, 6 Aug 2026 15:45:21 +0100
Subject: [PATCH 10/16] Improve desktop mobile pairing flow (#5024)

## Summary
- add stable three-step guidance to desktop mobile pairing
- move code confirmation inline and show animated completion states
- preserve pairing reset behavior and reduced-motion support

## Test plan
- `pnpm --dir desktop check`
- `pnpm --dir desktop exec tsc --noEmit`
- `pnpm --dir desktop exec playwright test
tests/e2e/mobile-pairing-qr.spec.ts --project=smoke`
- pre-push desktop suite: 4,387 tests passed

---------

Signed-off-by: kenny lopez <klopez4212@gmail.com>
Co-authored-by: Fizz <50a12680c76f1a52c0b7af8dbb17e02c583227c290fb93b9a3defb456114223f@buzz.block.builderlab.xyz>
---
 .../settings/ui/MobilePairingCard.tsx         | 522 +++++++++++-------
 desktop/tests/e2e/mobile-pairing-qr.spec.ts   | 282 +++++++++-
 2 files changed, 588 insertions(+), 216 deletions(-)

diff --git a/desktop/src/features/settings/ui/MobilePairingCard.tsx b/desktop/src/features/settings/ui/MobilePairingCard.tsx
index e15f54316b..0d58f86458 100644
--- a/desktop/src/features/settings/ui/MobilePairingCard.tsx
+++ b/desktop/src/features/settings/ui/MobilePairingCard.tsx
@@ -4,11 +4,10 @@ import {
   Copy,
   LoaderCircle,
   RefreshCw,
-  ShieldCheck,
   TriangleAlert,
-  X,
 } from "lucide-react";
 import { listen } from "@tauri-apps/api/event";
+import { AnimatePresence, motion, useReducedMotion } from "motion/react";
 import { toast } from "sonner";
 
 import {
@@ -16,15 +15,9 @@ import {
   confirmPairingSas,
   startPairing,
 } from "@/shared/api/tauri";
+import { cn } from "@/shared/lib/cn";
 import { Button } from "@/shared/ui/button";
 import { StyledQrCode } from "@/shared/ui/styled-qr-code";
-import {
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogHeader,
-  DialogTitle,
-} from "@/shared/ui/dialog";
 import { SettingsOptionGroup, SettingsOptionRow } from "./SettingsOptionGroup";
 import { SettingsSectionHeader } from "./SettingsSectionHeader";
 import { writeTextToClipboard } from "@/shared/lib/clipboard";
@@ -39,6 +32,8 @@ type PairingStep =
   | "done"
   | "error";
 
+const PAIRING_CODE_DIGIT_POSITIONS = [0, 1, 2, 3, 4, 5] as const;
+
 function pairingErrorMessage(error: unknown) {
   const message =
     error instanceof Error
@@ -58,114 +53,189 @@ function isPairingSessionTimeout(message: string) {
   return message.toLowerCase().includes("session timed out");
 }
 
-function PairingStatusDialog({
-  onClose,
+function PairingStepIndicator({
+  complete,
+  label,
+  testId,
+}: {
+  complete: boolean;
+  label: string;
+  testId: string;
+}) {
+  const shouldReduceMotion = useReducedMotion() ?? false;
+  const hiddenState = shouldReduceMotion
+    ? { opacity: 0 }
+    : { filter: "blur(2px)", opacity: 0, scale: 0.25 };
+  const visibleState = shouldReduceMotion
+    ? { opacity: 1 }
+    : { filter: "blur(0px)", opacity: 1, scale: 1 };
+
+  return (
+    <span
+      aria-hidden="true"
+      className={cn(
+        "relative flex h-12 w-12 shrink-0 items-center justify-center rounded-full text-base font-semibold transition-[background-color,color] duration-[250ms] ease-in-out motion-reduce:transition-none",
+        complete
+          ? "bg-green-600 text-white"
+          : "bg-secondary text-secondary-foreground",
+      )}
+      data-completed={complete ? "true" : "false"}
+      data-testid={testId}
+    >
+      <AnimatePresence initial={false}>
+        <motion.span
+          animate={visibleState}
+          className="absolute inset-0 flex items-center justify-center"
+          data-state={complete ? "complete" : "pending"}
+          exit={hiddenState}
+          initial={hiddenState}
+          key={complete ? "complete" : "pending"}
+          transition={
+            shouldReduceMotion
+              ? { duration: 0 }
+              : { duration: 0.25, ease: "easeInOut" }
+          }
+        >
+          {complete ? <Check className="h-6 w-6" /> : label}
+        </motion.span>
+      </AnimatePresence>
+    </span>
+  );
+}
+
+function PairingSteps({ step }: { step: PairingStep }) {
+  const hasScanned =
+    step === "sas" || step === "transferring" || step === "done";
+  const hasConfirmed = step === "transferring" || step === "done";
+  const isPaired = step === "done";
+
+  return (
+    <ol
+      className="flex min-h-[266px] min-w-0 flex-1 flex-col justify-center gap-6 py-2"
+      data-testid="mobile-pairing-steps"
+    >
+      <li className="flex min-w-0 items-start gap-4">
+        <PairingStepIndicator
+          complete={hasScanned}
+          label="1"
+          testId="mobile-pairing-scan-step-indicator"
+        />
+        <div className="min-w-0 pt-0.5">
+          <p className="text-base font-medium">Scan QR code</p>
+          <p className="mt-1 text-sm text-muted-foreground/80">
+            Open Buzz on your mobile device and scan the code shown here.
+          </p>
+        </div>
+      </li>
+
+      <li className="flex min-w-0 items-start gap-4">
+        <PairingStepIndicator
+          complete={hasConfirmed}
+          label="2"
+          testId="mobile-pairing-confirm-step-indicator"
+        />
+        <div className="min-w-0 pt-0.5">
+          <p className="text-base font-medium">Confirm mobile code</p>
+          <p className="mt-1 text-sm text-muted-foreground/80">
+            Check that the six-digit code matches on both devices, then confirm
+            it.
+          </p>
+        </div>
+      </li>
+
+      <li
+        className="flex min-w-0 items-start gap-4"
+        data-testid="mobile-pairing-final-step"
+      >
+        <PairingStepIndicator
+          complete={isPaired}
+          label="3"
+          testId="mobile-pairing-final-step-indicator"
+        />
+        <div aria-live="polite" className="min-w-0 pt-0.5">
+          <p className="text-base font-medium">
+            {isPaired ? "Paired" : "Pair your mobile app"}
+          </p>
+          <p className="mt-1 text-sm text-muted-foreground/80">
+            {isPaired
+              ? "Your mobile app is now connected to this relay."
+              : "Your mobile app will connect after you confirm the code."}
+          </p>
+        </div>
+      </li>
+    </ol>
+  );
+}
+
+function PairingCodeConfirmation({
   onConfirm,
   onDeny,
   sasCode,
-  step,
 }: {
-  onClose: () => void;
   onConfirm: () => void;
   onDeny: () => void;
-  sasCode: string | null;
-  step: PairingStep;
+  sasCode: string;
 }) {
-  const open = step === "sas" || step === "transferring" || step === "done";
+  const formattedCode = `${sasCode.slice(0, 3)} ${sasCode.slice(3, 6)}`;
 
   return (
-    <Dialog
-      onOpenChange={(nextOpen) => {
-        if (!nextOpen) onClose();
-      }}
-      open={open}
+    <div
+      className="grid h-[266px] w-full grid-rows-[auto_1fr_auto] text-center"
+      data-testid="mobile-pairing-code-confirmation"
     >
-      <DialogContent
-        className="max-w-md gap-0 overflow-hidden border-0 px-6 pb-6 pt-6"
-        data-testid="mobile-pairing-dialog"
+      <p
+        className="self-start text-base font-medium"
+        data-testid="pairing-sas-title"
       >
-        <div className="flex max-h-[85vh] flex-col">
-          <DialogHeader className="shrink-0 pb-5 pr-8">
-            <DialogTitle>Pair mobile device</DialogTitle>
-            <DialogDescription>
-              {step === "sas"
-                ? "Verify the security code matches your mobile device."
-                : step === "done"
-                  ? "Your mobile device is now paired."
-                  : "Securely sending your identity to the mobile app."}
-            </DialogDescription>
-          </DialogHeader>
-
-          <div className="min-h-0 flex-1 overflow-y-auto pt-4">
-            {step === "sas" && sasCode ? (
-              <div className="space-y-4">
-                <div className="flex flex-col items-center gap-3 py-4">
-                  <ShieldCheck className="h-10 w-10 text-primary" />
-                  <p className="text-sm font-medium">
-                    Verify this code matches your mobile device
-                  </p>
-                  <div className="rounded-xl border-2 border-primary/30 bg-primary/5 px-8 py-4">
-                    <p
-                      className="font-mono text-4xl font-bold tracking-[0.3em]"
-                      data-testid="pairing-sas-code"
-                    >
-                      {sasCode.slice(0, 3)} {sasCode.slice(3)}
-                    </p>
-                  </div>
-                  <p className="text-center text-xs text-muted-foreground">
-                    You are about to transfer your Buzz identity to another
-                    device. Only confirm if you initiated this pairing.
-                  </p>
-                </div>
-
-                <div className="flex gap-2">
-                  <Button
-                    className="flex-1"
-                    data-testid="deny-sas"
-                    onClick={onDeny}
-                    variant="outline"
-                  >
-                    <X className="mr-1.5 h-4 w-4" />
-                    Cancel
-                  </Button>
-                  <Button
-                    className="flex-1"
-                    data-testid="confirm-sas"
-                    onClick={onConfirm}
-                  >
-                    <Check className="mr-1.5 h-4 w-4" />
-                    Codes match
-                  </Button>
-                </div>
-              </div>
-            ) : step === "transferring" ? (
-              <div className="flex flex-col items-center justify-center gap-3 py-8">
-                <LoaderCircle
-                  aria-hidden="true"
-                  className="h-6 w-6 animate-spin text-muted-foreground"
-                />
-                <p className="text-sm text-muted-foreground">
-                  Sending identity to mobile device...
-                </p>
-              </div>
-            ) : step === "done" ? (
-              <div
-                className="flex flex-col items-center justify-center gap-3 py-8"
-                data-testid="mobile-pairing-done"
-              >
-                <div className="flex h-12 w-12 items-center justify-center rounded-full bg-green-100 dark:bg-green-900/30">
-                  <Check className="h-6 w-6 text-green-600 dark:text-green-400" />
-                </div>
-                <p className="text-sm font-medium">Mobile device paired</p>
-                <p className="text-center text-xs text-muted-foreground">
-                  Your mobile app is now connected to this relay.
-                </p>
-              </div>
-            ) : null}
-          </div>
-        </div>
-      </DialogContent>
-    </Dialog>
+        Confirm mobile code
+      </p>
+      <fieldset
+        className="flex w-full self-center justify-center gap-[6px]"
+        data-testid="pairing-sas-code"
+      >
+        <legend className="sr-only">Confirmation code {formattedCode}</legend>
+        {PAIRING_CODE_DIGIT_POSITIONS.map((position) => (
+          <span
+            aria-hidden="true"
+            className={cn(
+              // The cell box is px-frozen on purpose. The digits stay
+              // rem-based (`text-2xl`) so they scale with Cmd +/- zoom, but a
+              // rem-sized cell (`w-10`) plus rem gaps grew the six cells past
+              // this fixed 266px column at 150% text scale and overlapped the
+              // step guidance. Freezing the box keeps the code block the same
+              // width at every zoom level; a zoomed digit still fits inside.
+              "flex w-[40px] shrink-0 items-center justify-center rounded-xl border border-input/60 bg-background py-3 font-mono text-2xl font-semibold text-foreground",
+              position === 3 && "ml-[8px]",
+            )}
+            data-testid={`pairing-sas-code-digit-${position + 1}`}
+            key={position}
+          >
+            {sasCode[position] ?? ""}
+          </span>
+        ))}
+      </fieldset>
+      <div
+        className="flex w-[240px] flex-col gap-2 self-end justify-self-center"
+        data-testid="pairing-sas-actions"
+      >
+        <Button
+          className="w-full"
+          data-testid="confirm-sas"
+          onClick={onConfirm}
+        >
+          <Check />
+          Codes match
+        </Button>
+        <Button
+          className="w-full"
+          data-testid="deny-sas"
+          onClick={onDeny}
+          variant="outline"
+        >
+          Cancel
+        </Button>
+      </div>
+    </div>
   );
 }
 
@@ -312,21 +382,6 @@ export function MobilePairingCard({
     setStep("error");
   }
 
-  function handleStatusDialogClose() {
-    pairingActiveRef.current = false;
-    if (stepRef.current === "done") {
-      setStep("idle");
-      setQrUri(null);
-      setSasCode(null);
-      setError(null);
-      return;
-    }
-
-    cancelPairing().catch(() => {});
-    setError("Pairing was canceled.");
-    setStep("error");
-  }
-
   return (
     <section className="min-w-0" data-testid="settings-mobile">
       <SettingsSectionHeader
@@ -341,105 +396,156 @@ export function MobilePairingCard({
       />
 
       <SettingsOptionGroup
-        className="mx-auto w-fit max-w-full"
+        className="w-full [container-type:inline-size]"
         data-testid="mobile-pairing-card"
       >
-        <SettingsOptionRow className="flex-col items-stretch justify-start gap-3 p-4">
-          <div
-            className="flex min-h-[266px] w-[266px] shrink-0 items-center justify-center rounded-lg border border-border/70 bg-white p-3"
-            data-testid="mobile-pairing-qr-container"
-          >
-            {step === "qr" && qrUri ? (
-              <StyledQrCode
-                animate
-                centerImageSrc="/app-icon@2x.png"
-                data-testid="mobile-pairing-qr"
-                size={240}
-                title="Mobile pairing QR code"
-                value={qrUri}
-              />
-            ) : step === "expired" ? (
-              <div className="flex max-w-52 origin-center animate-in flex-col items-center gap-3 text-center fade-in-0 zoom-in-95 duration-[250ms] ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:animate-none">
-                <p className="text-sm text-muted-foreground">
-                  Pairing code expired.
-                </p>
+        {/* Persistent polite live region. The pairing steps swap the QR view
+            for the inline code confirmation asynchronously, and a screen
+            reader would otherwise get no signal that a code is now waiting.
+            This stays mounted for every step so the announcement is reliable
+            (a region added at the same time as its text often isn't spoken)
+            and is visually hidden, so it changes nothing on screen. */}
+        <p aria-live="polite" className="sr-only" data-testid="pairing-status">
+          {step === "sas" && sasCode
+            ? `Verification code ${sasCode.slice(0, 3)} ${sasCode.slice(3, 6)} ready. Check that it matches on your mobile device, then confirm the codes match.`
+            : step === "transferring"
+              ? "Codes confirmed. Pairing your mobile device."
+              : step === "done"
+                ? "Your mobile app is now paired."
+                : ""}
+        </p>
+        <SettingsOptionRow
+          // Side-by-side is gated on the *card's* own width, not the viewport.
+          // `sm:` fires at an 800px viewport, but the settings sidebar and
+          // content padding leave the card only ~443px there — the QR column
+          // and gap ate all of it, collapsing the step guidance to ~1px and
+          // stretching the card past 1000px tall. 46rem is the narrowest card
+          // width where the steps column still gets a readable ~294px.
+          className="flex-col items-stretch justify-start gap-14 px-6 pb-4 pt-15 [@container(min-width:46rem)]:flex-row [@container(min-width:46rem)]:items-start [@container(min-width:46rem)]:px-15"
+          data-testid="mobile-pairing-layout"
+        >
+          <div className="flex w-[266px] max-w-full shrink-0 flex-col gap-3">
+            <div
+              className={cn(
+                "flex min-h-[266px] w-[266px] max-w-full items-center justify-center rounded-lg border",
+                step === "sas" || step === "transferring" || step === "done"
+                  ? "border-transparent bg-transparent p-0"
+                  : "border-border/70 bg-background p-3",
+              )}
+              data-testid="mobile-pairing-qr-container"
+            >
+              {step === "sas" && sasCode ? (
+                <PairingCodeConfirmation
+                  onConfirm={() => void handleConfirmSas()}
+                  onDeny={handleDenySas}
+                  sasCode={sasCode}
+                />
+              ) : step === "transferring" ? (
+                <div className="flex flex-col items-center justify-center gap-3 text-center">
+                  <LoaderCircle
+                    aria-hidden="true"
+                    className="h-6 w-6 animate-spin text-muted-foreground"
+                    data-testid="pairing-transfer-spinner"
+                  />
+                  <p className="text-sm text-muted-foreground">
+                    Pairing mobile device...
+                  </p>
+                </div>
+              ) : step === "qr" && qrUri ? (
+                <StyledQrCode
+                  animate
+                  centerImageSrc="/app-icon@2x.png"
+                  data-testid="mobile-pairing-qr"
+                  size={240}
+                  title="Mobile pairing QR code"
+                  value={qrUri}
+                />
+              ) : step === "expired" ? (
+                <div className="flex max-w-52 origin-center animate-in flex-col items-center gap-3 text-center fade-in-0 zoom-in-95 duration-[250ms] ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:animate-none">
+                  <p className="text-sm text-muted-foreground">
+                    Pairing code expired.
+                  </p>
+                  <Button
+                    data-testid="regenerate-pairing-button"
+                    onClick={beginPairing}
+                    size="sm"
+                    type="button"
+                    variant="outline"
+                  >
+                    <RefreshCw className="mr-1.5 h-4 w-4" />
+                    Generate new pairing code
+                  </Button>
+                </div>
+              ) : step === "error" ? (
+                <div className="flex max-w-52 flex-col items-center gap-3 text-center">
+                  <TriangleAlert className="h-6 w-6 text-destructive" />
+                  <p className="text-sm text-destructive">
+                    {error ?? "Pairing session ended."}
+                  </p>
+                  <Button
+                    data-testid="retry-pairing-button"
+                    onClick={beginPairing}
+                    size="sm"
+                    variant="outline"
+                  >
+                    Try again
+                  </Button>
+                </div>
+              ) : step === "idle" ? (
+                currentPubkey ? (
+                  <Button
+                    data-testid="start-pairing-button"
+                    onClick={beginPairing}
+                    type="button"
+                  >
+                    Start pairing
+                  </Button>
+                ) : (
+                  <p className="max-w-44 text-center text-sm text-muted-foreground">
+                    Sign in to generate a mobile pairing code.
+                  </p>
+                )
+              ) : step === "done" ? (
+                <div className="flex flex-col items-center gap-3 text-center">
+                  <div className="flex h-12 w-12 items-center justify-center rounded-full bg-green-100 dark:bg-green-900/30">
+                    <Check className="h-6 w-6 text-green-600 dark:text-green-400" />
+                  </div>
+                  <p className="text-base font-medium">Paired</p>
+                </div>
+              ) : (
+                <div className="flex flex-col items-center justify-center gap-3">
+                  <LoaderCircle
+                    aria-hidden="true"
+                    className="h-6 w-6 animate-spin text-muted-foreground"
+                    data-testid="pairing-loading-spinner"
+                  />
+                  <p className="text-sm text-muted-foreground">
+                    Starting pairing...
+                  </p>
+                </div>
+              )}
+            </div>
+
+            <div className="h-8" data-testid="mobile-pairing-copy-slot">
+              {step === "qr" && qrUri ? (
                 <Button
-                  data-testid="regenerate-pairing-button"
-                  onClick={beginPairing}
+                  className="h-8 w-full origin-top animate-in fade-in-0 zoom-in-95 duration-[250ms] ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:animate-none"
+                  data-testid="copy-pairing-code"
+                  onClick={handleCopy}
                   size="sm"
                   type="button"
                   variant="outline"
                 >
-                  <RefreshCw className="mr-1.5 h-4 w-4" />
-                  Generate new pairing code
+                  <Copy className="mr-1.5 h-4 w-4" />
+                  Copy pairing code
                 </Button>
-              </div>
-            ) : step === "error" ? (
-              <div className="flex max-w-52 flex-col items-center gap-3 text-center">
-                <TriangleAlert className="h-6 w-6 text-destructive" />
-                <p className="text-sm text-destructive">
-                  {error ?? "Pairing session ended."}
-                </p>
-                <Button
-                  data-testid="retry-pairing-button"
-                  onClick={beginPairing}
-                  size="sm"
-                  variant="outline"
-                >
-                  Try again
-                </Button>
-              </div>
-            ) : step === "idle" ? (
-              currentPubkey ? (
-                <Button
-                  data-testid="start-pairing-button"
-                  onClick={beginPairing}
-                  type="button"
-                >
-                  Start pairing
-                </Button>
-              ) : (
-                <p className="max-w-44 text-center text-sm text-muted-foreground">
-                  Sign in to generate a mobile pairing code.
-                </p>
-              )
-            ) : (
-              <div className="flex flex-col items-center justify-center gap-3">
-                <LoaderCircle
-                  aria-hidden="true"
-                  className="h-6 w-6 animate-spin text-muted-foreground"
-                  data-testid="pairing-loading-spinner"
-                />
-                <p className="text-sm text-muted-foreground">
-                  Starting pairing...
-                </p>
-              </div>
-            )}
+              ) : null}
+            </div>
           </div>
 
-          {step === "qr" && qrUri ? (
-            <Button
-              className="w-full origin-top animate-in fade-in-0 zoom-in-95 duration-[250ms] ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:animate-none"
-              data-testid="copy-pairing-code"
-              onClick={handleCopy}
-              size="sm"
-              type="button"
-              variant="outline"
-            >
-              <Copy className="mr-1.5 h-4 w-4" />
-              Copy pairing code
-            </Button>
-          ) : null}
+          <PairingSteps step={step} />
         </SettingsOptionRow>
       </SettingsOptionGroup>
-
-      <PairingStatusDialog
-        onClose={handleStatusDialogClose}
-        onConfirm={() => void handleConfirmSas()}
-        onDeny={handleDenySas}
-        sasCode={sasCode}
-        step={step}
-      />
     </section>
   );
 }
diff --git a/desktop/tests/e2e/mobile-pairing-qr.spec.ts b/desktop/tests/e2e/mobile-pairing-qr.spec.ts
index 606777545f..a1e7935e38 100644
--- a/desktop/tests/e2e/mobile-pairing-qr.spec.ts
+++ b/desktop/tests/e2e/mobile-pairing-qr.spec.ts
@@ -47,10 +47,50 @@ test("mobile pairing starts on demand and reveals the QR code", async ({
 
   const section = page.getByTestId("settings-mobile");
   const card = page.getByTestId("mobile-pairing-card");
+  const layout = card.getByTestId("mobile-pairing-layout");
   const qrContainer = page.getByTestId("mobile-pairing-qr-container");
+  const steps = card.getByTestId("mobile-pairing-steps");
+  const scanStepIndicator = card.getByTestId(
+    "mobile-pairing-scan-step-indicator",
+  );
+  const confirmStepIndicator = card.getByTestId(
+    "mobile-pairing-confirm-step-indicator",
+  );
+  const finalStep = card.getByTestId("mobile-pairing-final-step");
   const startButton = card.getByTestId("start-pairing-button");
   await expect(card).toBeVisible();
   await expect(startButton).toHaveText("Start pairing");
+  await expect(steps.getByText("Scan QR code", { exact: true })).toBeVisible();
+  await expect(
+    steps.getByText("Confirm mobile code", { exact: true }),
+  ).toBeVisible();
+  await expect(
+    finalStep.getByText("Pair your mobile app", { exact: true }),
+  ).toBeVisible();
+  const finalStepIndicator = finalStep.getByTestId(
+    "mobile-pairing-final-step-indicator",
+  );
+  await expect(finalStepIndicator).toHaveText("3");
+  await expect(scanStepIndicator).toHaveAttribute("data-completed", "false");
+  await expect(confirmStepIndicator).toHaveAttribute("data-completed", "false");
+  await expect(finalStepIndicator).toHaveCSS("width", "48px");
+  await expect(finalStepIndicator).toHaveCSS("height", "48px");
+  expect(
+    await finalStepIndicator.evaluate((element) =>
+      Number.parseFloat(getComputedStyle(element).borderRadius),
+    ),
+  ).toBeGreaterThanOrEqual(24);
+  const indicatorBackground = await finalStepIndicator.evaluate(
+    (element) => getComputedStyle(element).backgroundColor,
+  );
+  const primaryActionBackground = await startButton.evaluate(
+    (element) => getComputedStyle(element).backgroundColor,
+  );
+  expect(indicatorBackground).not.toBe(primaryActionBackground);
+  await expect(layout).toHaveCSS("padding-top", "60px");
+  await expect(layout).toHaveCSS("padding-right", "60px");
+  await expect(layout).toHaveCSS("padding-left", "60px");
+  await expect(layout).toHaveCSS("column-gap", "56px");
   await expect(page.getByTestId("mobile-pairing-qr")).toHaveCount(0);
   await expect(page.getByTestId("copy-pairing-code")).toHaveCount(0);
   expect(
@@ -64,8 +104,20 @@ test("mobile pairing starts on demand and reveals the QR code", async ({
 
   const sectionBox = await section.boundingBox();
   const cardBox = await card.boundingBox();
+  const initialStepsBox = await steps.boundingBox();
   expect(sectionBox).not.toBeNull();
   expect(cardBox).not.toBeNull();
+  expect(initialStepsBox).not.toBeNull();
+  const initialQrBox = await qrContainer.boundingBox();
+  expect(initialQrBox).not.toBeNull();
+  const qrTopSpace = (initialQrBox?.y ?? 0) - (cardBox?.y ?? 0);
+  const qrLeftSpace = (initialQrBox?.x ?? 0) - (cardBox?.x ?? 0);
+  const qrBottomSpace =
+    (cardBox?.y ?? 0) +
+    (cardBox?.height ?? 0) -
+    ((initialQrBox?.y ?? 0) + (initialQrBox?.height ?? 0));
+  expect(Math.abs(qrTopSpace - qrLeftSpace)).toBeLessThan(0.5);
+  expect(Math.abs(qrTopSpace - qrBottomSpace)).toBeLessThan(0.5);
   const sectionCenter = (sectionBox?.x ?? 0) + (sectionBox?.width ?? 0) / 2;
   const cardCenter = (cardBox?.x ?? 0) + (cardBox?.width ?? 0) / 2;
   expect(Math.abs(sectionCenter - cardCenter)).toBeLessThan(0.5);
@@ -118,8 +170,19 @@ test("mobile pairing starts on demand and reveals the QR code", async ({
   await waitForAnimations(page);
   const qrBox = await qrContainer.boundingBox();
   const copyBox = await copyButton.boundingBox();
+  const stepsBox = await steps.boundingBox();
+  const qrCardBox = await card.boundingBox();
   expect(qrBox).not.toBeNull();
   expect(copyBox).not.toBeNull();
+  expect(stepsBox).not.toBeNull();
+  expect(qrCardBox).not.toBeNull();
+  expect(qrBox?.x ?? 0).toBeLessThan(stepsBox?.x ?? 0);
+  expect(Math.abs((stepsBox?.y ?? 0) - (initialStepsBox?.y ?? 0))).toBeLessThan(
+    0.5,
+  );
+  expect(
+    Math.abs((qrCardBox?.height ?? 0) - (cardBox?.height ?? 0)),
+  ).toBeLessThan(0.5);
   expect(copyBox?.y ?? 0).toBeGreaterThan(
     (qrBox?.y ?? 0) + (qrBox?.height ?? 0),
   );
@@ -158,6 +221,178 @@ test("mobile pairing starts on demand and reveals the QR code", async ({
   await qrCode.screenshot({ path: `${SCREENSHOT_DIR}/pairing-qr.png` });
 });
 
+test("pairing completion updates the final step and resets after leaving", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.getByTestId("open-settings").click();
+  await page.getByTestId("profile-popover-settings").click();
+  await page.getByTestId("settings-nav-mobile").click();
+
+  const card = page.getByTestId("mobile-pairing-card");
+  const finalStep = card.getByTestId("mobile-pairing-final-step");
+  const scanStepIndicator = card.getByTestId(
+    "mobile-pairing-scan-step-indicator",
+  );
+  const confirmStepIndicator = card.getByTestId(
+    "mobile-pairing-confirm-step-indicator",
+  );
+  await card.getByTestId("start-pairing-button").click();
+  await expect(page.getByTestId("mobile-pairing-qr")).toBeVisible();
+
+  await emitPairingEvent(page, "pairing-sas-received", { sas: "123456" });
+  const confirmation = card.getByTestId("mobile-pairing-code-confirmation");
+  await expect(scanStepIndicator).toHaveAttribute("data-completed", "true");
+  await expect(scanStepIndicator.locator('[data-state="complete"]')).toHaveCSS(
+    "opacity",
+    "1",
+  );
+  await expect(scanStepIndicator.locator("svg")).toHaveCount(1);
+  await expect(confirmStepIndicator).toHaveAttribute("data-completed", "false");
+  await expect(page.getByTestId("mobile-pairing-dialog")).toHaveCount(0);
+  await expect(page.getByTestId("mobile-pairing-qr")).toHaveCount(0);
+  const confirmationCode = confirmation.getByTestId("pairing-sas-code");
+  await expect(confirmationCode).toHaveAccessibleName(
+    "Confirmation code 123 456",
+  );
+  await expect(
+    confirmationCode.locator('[data-testid^="pairing-sas-code-digit-"]'),
+  ).toHaveCount(6);
+  await expect(
+    confirmationCode.getByTestId("pairing-sas-code-digit-1"),
+  ).toHaveCSS("border-radius", "12px");
+  await expect(
+    confirmationCode.getByTestId("pairing-sas-code-digit-1"),
+  ).toHaveCSS("box-shadow", "none");
+  const firstCodeDigit = confirmationCode.getByTestId(
+    "pairing-sas-code-digit-1",
+  );
+  const firstCodeDigitBox = await firstCodeDigit.boundingBox();
+  expect(firstCodeDigitBox).not.toBeNull();
+  expect(firstCodeDigitBox?.width ?? 0).toBeGreaterThan(32);
+  expect(firstCodeDigitBox?.height ?? 0).toBeGreaterThan(48);
+  const secondCodeDigitBox = await confirmationCode
+    .getByTestId("pairing-sas-code-digit-2")
+    .boundingBox();
+  const thirdCodeDigitBox = await confirmationCode
+    .getByTestId("pairing-sas-code-digit-3")
+    .boundingBox();
+  const fourthCodeDigitBox = await confirmationCode
+    .getByTestId("pairing-sas-code-digit-4")
+    .boundingBox();
+  expect(secondCodeDigitBox).not.toBeNull();
+  expect(thirdCodeDigitBox).not.toBeNull();
+  expect(fourthCodeDigitBox).not.toBeNull();
+  const regularDigitGap =
+    (thirdCodeDigitBox?.x ?? 0) -
+    ((secondCodeDigitBox?.x ?? 0) + (secondCodeDigitBox?.width ?? 0));
+  const groupedDigitGap =
+    (fourthCodeDigitBox?.x ?? 0) -
+    ((thirdCodeDigitBox?.x ?? 0) + (thirdCodeDigitBox?.width ?? 0));
+  expect(groupedDigitGap).toBeGreaterThan(regularDigitGap);
+  await expect(card.getByTestId("mobile-pairing-qr-container")).toHaveCSS(
+    "border-color",
+    "rgba(0, 0, 0, 0)",
+  );
+  const confirmButton = confirmation.getByTestId("confirm-sas");
+  const cancelButton = confirmation.getByTestId("deny-sas");
+  const confirmationBox = await confirmation.boundingBox();
+  const confirmationTitleBox = await confirmation
+    .getByTestId("pairing-sas-title")
+    .boundingBox();
+  const confirmationCodeBox = await confirmationCode.boundingBox();
+  const confirmationActionsBox = await confirmation
+    .getByTestId("pairing-sas-actions")
+    .boundingBox();
+  expect(confirmationBox).not.toBeNull();
+  expect(confirmationTitleBox).not.toBeNull();
+  expect(confirmationCodeBox).not.toBeNull();
+  expect(confirmationActionsBox).not.toBeNull();
+  expect(
+    Math.abs((confirmationTitleBox?.y ?? 0) - (confirmationBox?.y ?? 0)),
+  ).toBeLessThan(0.5);
+  const codeCenter =
+    (confirmationCodeBox?.y ?? 0) + (confirmationCodeBox?.height ?? 0) / 2;
+  const availableCodeCenter =
+    ((confirmationTitleBox?.y ?? 0) +
+      (confirmationTitleBox?.height ?? 0) +
+      (confirmationActionsBox?.y ?? 0)) /
+    2;
+  expect(Math.abs(availableCodeCenter - codeCenter)).toBeLessThan(0.5);
+  expect(
+    Math.abs(
+      (confirmationActionsBox?.y ?? 0) +
+        (confirmationActionsBox?.height ?? 0) -
+        ((confirmationBox?.y ?? 0) + (confirmationBox?.height ?? 0)),
+    ),
+  ).toBeLessThan(0.5);
+  await expect(confirmButton).toHaveCSS("height", "36px");
+  await expect(cancelButton).toHaveCSS("height", "36px");
+  await expect(confirmButton.locator("svg")).toHaveCount(1);
+  await expect(cancelButton.locator("svg")).toHaveCount(0);
+  const confirmBox = await confirmButton.boundingBox();
+  const cancelBox = await cancelButton.boundingBox();
+  expect(confirmBox).not.toBeNull();
+  expect(cancelBox).not.toBeNull();
+  expect(confirmBox?.y ?? 0).toBeLessThan(cancelBox?.y ?? 0);
+  await expect(
+    confirmation.getByText(/Only confirm if you started this pairing/),
+  ).toHaveCount(0);
+  await expect(confirmation.getByTestId("pairing-sas-title")).toHaveCSS(
+    "font-size",
+    "16px",
+  );
+
+  mkdirSync(SCREENSHOT_DIR, { recursive: true });
+  await waitForAnimations(page);
+  await card.screenshot({
+    path: `${SCREENSHOT_DIR}/pairing-code-confirmation.png`,
+  });
+
+  await confirmation.getByTestId("confirm-sas").click();
+  await expect(card.getByText("Pairing mobile device...")).toBeVisible();
+  await expect(confirmStepIndicator).toHaveAttribute("data-completed", "true");
+  await expect(
+    confirmStepIndicator.locator('[data-state="complete"]'),
+  ).toHaveCSS("opacity", "1");
+  await expect(confirmStepIndicator.locator("svg")).toHaveCount(1);
+
+  await emitPairingEvent(page, "pairing-complete");
+
+  await expect(finalStep.getByText("Paired", { exact: true })).toBeVisible();
+  await expect(
+    finalStep.getByText("Your mobile app is now connected to this relay."),
+  ).toBeVisible();
+  await expect(
+    finalStep.getByTestId("mobile-pairing-final-step-indicator").locator("svg"),
+  ).toHaveCount(1);
+  await expect(
+    finalStep.getByTestId("mobile-pairing-final-step-indicator"),
+  ).toHaveAttribute("data-completed", "true");
+  const pairedSurface = card.getByTestId("mobile-pairing-qr-container");
+  await expect(
+    pairedSurface.getByText("Paired", { exact: true }),
+  ).toBeVisible();
+  await expect(
+    pairedSurface.getByText("Your mobile app is now connected to this relay."),
+  ).toHaveCount(0);
+
+  await waitForAnimations(page);
+  await card.screenshot({ path: `${SCREENSHOT_DIR}/pairing-complete.png` });
+
+  await page.getByTestId("settings-nav-updates").click();
+  await page.getByTestId("settings-nav-mobile").click();
+
+  const restartedCard = page.getByTestId("mobile-pairing-card");
+  await expect(restartedCard.getByTestId("start-pairing-button")).toBeVisible();
+  await expect(
+    restartedCard
+      .getByTestId("mobile-pairing-final-step")
+      .getByText("Pair your mobile app", { exact: true }),
+  ).toBeVisible();
+  await expect(page.getByTestId("mobile-pairing-qr")).toHaveCount(0);
+});
+
 test("late pairing events are ignored after canceling", async ({ page }) => {
   await page.goto("/");
   await page.getByTestId("open-settings").click();
@@ -169,17 +404,48 @@ test("late pairing events are ignored after canceling", async ({ page }) => {
   await expect(page.getByTestId("mobile-pairing-qr")).toBeVisible();
 
   await emitPairingEvent(page, "pairing-sas-received", { sas: "123456" });
-  const dialog = page.getByTestId("mobile-pairing-dialog");
-  await expect(dialog).toBeVisible();
-  await dialog.getByRole("button", { name: "Close" }).click();
+  const confirmation = card.getByTestId("mobile-pairing-code-confirmation");
+  await expect(confirmation).toBeVisible();
+  await confirmation.getByTestId("deny-sas").click();
 
-  await expect(dialog).toHaveCount(0);
-  await expect(card.getByText("Pairing was canceled.")).toBeVisible();
+  await expect(confirmation).toHaveCount(0);
+  await expect(
+    card.getByText("The codes didn't match. Pairing was canceled."),
+  ).toBeVisible();
 
   await emitPairingEvent(page, "pairing-complete");
   await emitPairingEvent(page, "pairing-sas-received", { sas: "654321" });
 
-  await expect(dialog).toHaveCount(0);
-  await expect(page.getByTestId("mobile-pairing-done")).toHaveCount(0);
-  await expect(card.getByText("Pairing was canceled.")).toBeVisible();
+  await expect(confirmation).toHaveCount(0);
+  await expect(
+    card
+      .getByTestId("mobile-pairing-final-step")
+      .getByText("Paired", { exact: true }),
+  ).toHaveCount(0);
+  await expect(
+    card.getByText("The codes didn't match. Pairing was canceled."),
+  ).toBeVisible();
+});
+
+test("step completion respects reduced motion", async ({ page }) => {
+  await page.emulateMedia({ reducedMotion: "reduce" });
+  await page.goto("/");
+  await page.getByTestId("open-settings").click();
+  await page.getByTestId("profile-popover-settings").click();
+  await page.getByTestId("settings-nav-mobile").click();
+
+  const card = page.getByTestId("mobile-pairing-card");
+  const scanStepIndicator = card.getByTestId(
+    "mobile-pairing-scan-step-indicator",
+  );
+  await card.getByTestId("start-pairing-button").click();
+  await expect(page.getByTestId("mobile-pairing-qr")).toBeVisible();
+
+  await emitPairingEvent(page, "pairing-sas-received", { sas: "123456" });
+
+  await expect(scanStepIndicator).toHaveAttribute("data-completed", "true");
+  await expect(scanStepIndicator).toHaveCSS("transition-property", "none");
+  const completedContent = scanStepIndicator.locator('[data-state="complete"]');
+  await expect(completedContent).toHaveCSS("opacity", "1");
+  await expect(completedContent).toHaveCSS("transform", "none");
 });

From 9213090f6076bf3b7667b9b984752b3e47ef8f2f Mon Sep 17 00:00:00 2001
From: Cameron Hotchkies <chotchkies@block.xyz>
Date: Thu, 6 Aug 2026 08:04:39 -0700
Subject: [PATCH 11/16] test(desktop): await thread scroll anchor (#3174)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Why
The focus/split E2E test could capture the thread root before its
programmatic middle-thread scroll had settled, then incorrectly report a
scroll-restoration failure.

## What
- Poll until the requested middle-thread scroll position is applied
- Require the captured anchor to intersect the thread viewport and
differ from the root
- Preserve the existing focus-to-split-to-focus viewport assertions

## Risk Assessment
Low — test-only synchronization change with no production behavior
changes.

## References
- Original failure:
https://github.com/block/buzz/actions/runs/30231271427/job/89870533541
- Buzz thread:
buzz://message?channel=12dd513d-45fd-48ff-80ac-8596d2fcc9d3&id=87ce6024b4bf74bfac2fa75d9f7bbbcc8f8fe2df460afe534152c495929f51ba
- Reproduced confidence: 20 consecutive targeted passes, full spec pass,
`just desktop-ci`, and `just ci`

Generated with Codex

Signed-off-by: npub1x4hk035p3p9q39a3fcrd2fe30lpkrhr5dwe0cqzzjphxyyh8m0gsq4vqap <356f67c681884a0897b14e06d527317fc361dc746bb2fc0042906e6212e7dbd1@buzz.block.builderlab.xyz>
Co-authored-by: npub1x4hk035p3p9q39a3fcrd2fe30lpkrhr5dwe0cqzzjphxyyh8m0gsq4vqap <356f67c681884a0897b14e06d527317fc361dc746bb2fc0042906e6212e7dbd1@buzz.block.builderlab.xyz>
Co-authored-by: Wes <wesbillman@users.noreply.github.com>
---
 desktop/tests/e2e/thread-focus-mode.spec.ts | 44 ++++++++++++++-------
 1 file changed, 30 insertions(+), 14 deletions(-)

diff --git a/desktop/tests/e2e/thread-focus-mode.spec.ts b/desktop/tests/e2e/thread-focus-mode.spec.ts
index 8bb9a3b52b..36eb0630ba 100644
--- a/desktop/tests/e2e/thread-focus-mode.spec.ts
+++ b/desktop/tests/e2e/thread-focus-mode.spec.ts
@@ -30,17 +30,37 @@ async function seedLongThread(page: import("@playwright/test").Page) {
   });
 }
 
-async function topVisibleMessageId(
+async function scrollToMiddleVisibleMessage(
   body: import("@playwright/test").Locator,
+  threadRootId: string,
 ): Promise<string> {
-  return body.evaluate((element) => {
-    const top = element.getBoundingClientRect().top;
-    const row = Array.from(
-      element.querySelectorAll<HTMLElement>("[data-message-id]"),
-    ).find((candidate) => candidate.getBoundingClientRect().bottom > top);
-    if (!row?.dataset.messageId) throw new Error("No visible thread anchor");
-    return row.dataset.messageId;
-  });
+  let anchorId: string | null = null;
+  await expect
+    .poll(async () => {
+      anchorId = await body.evaluate((element) => {
+        const maxScrollTop = element.scrollHeight - element.clientHeight;
+        if (maxScrollTop <= 0) return null;
+
+        const targetScrollTop = Math.floor(maxScrollTop * 0.4);
+        element.scrollTop = targetScrollTop;
+        element.dispatchEvent(new Event("scroll", { bubbles: true }));
+
+        if (Math.abs(element.scrollTop - targetScrollTop) > 1) return null;
+        const bounds = element.getBoundingClientRect();
+        const row = Array.from(
+          element.querySelectorAll<HTMLElement>("[data-message-id]"),
+        ).find((candidate) => {
+          const rect = candidate.getBoundingClientRect();
+          return rect.bottom > bounds.top && rect.top < bounds.bottom;
+        });
+        return row?.dataset.messageId ?? null;
+      });
+      return anchorId !== null && anchorId !== threadRootId;
+    })
+    .toBe(true);
+
+  if (!anchorId) throw new Error("No visible middle-thread anchor");
+  return anchorId;
 }
 
 /**
@@ -181,11 +201,7 @@ test("focus and split preserve reading context and interaction ownership", async
     .toBe(true);
   await expect(channel).toHaveAttribute("inert", "");
 
-  await body.evaluate((element) => {
-    element.scrollTop = element.scrollHeight * 0.4;
-    element.dispatchEvent(new Event("scroll", { bubbles: true }));
-  });
-  const anchorId = await topVisibleMessageId(body);
+  const anchorId = await scrollToMiddleVisibleMessage(body, rootId);
 
   const focusModeToggle = page.getByRole("button", {
     name: "Show thread beside channel",

From 6ca9641a9555e48f99b3ebccc123ca8c25648a45 Mon Sep 17 00:00:00 2001
From: klopez4212 <klopez4212@gmail.com>
Date: Thu, 6 Aug 2026 16:21:35 +0100
Subject: [PATCH 12/16] Refine agent runtime controls (#5026)

## Summary
- replace ambiguous avatar play controls with centered Start and Restart
pills
- preserve avatar clipping while smoothly morphing actions into the
running status dot
- use accessible warning contrast and real restart behavior without a
duplicate status badge

## Validation
- `just ci`
- focused Playwright coverage for morphing, shared geometry, and
light/dark contrast

Signed-off-by: kenny lopez <klopez4212@gmail.com>
---
 .../agents/lib/managedAgentControlActions.ts  |   2 +-
 .../agents/managedAgentRuntimeStatus.ts       |   6 +-
 .../agents/ui/AgentRuntimeAvatarControl.tsx   | 153 ++++++---
 desktop/src/features/agents/ui/AgentsView.tsx |   4 +
 .../agents/ui/UnifiedAgentsSection.tsx        |  51 ++-
 .../agents/ui/useManagedAgentActions.ts       |  31 ++
 .../profile/ui/MaskedAvatarBadgeFrame.tsx     | 220 ++++++++++++-
 .../profile/ui/UserProfilePrimaryActions.tsx  |   4 +-
 desktop/tests/e2e/agents.spec.ts              |  94 ++++++
 .../e2e/needs-restart-screenshots.spec.ts     | 294 +++++++++++-------
 10 files changed, 665 insertions(+), 194 deletions(-)

diff --git a/desktop/src/features/agents/lib/managedAgentControlActions.ts b/desktop/src/features/agents/lib/managedAgentControlActions.ts
index dbaaaba803..50a92e4f17 100644
--- a/desktop/src/features/agents/lib/managedAgentControlActions.ts
+++ b/desktop/src/features/agents/lib/managedAgentControlActions.ts
@@ -44,7 +44,7 @@ export function getManagedAgentPrimaryActionLabel(agent: ManagedAgent) {
     return "Stop";
   }
 
-  return agent.status === "stopped" ? "Respawn" : "Spawn";
+  return agent.status === "stopped" ? "Restart Agent" : "Start Agent";
 }
 
 export function resolveManagedAgentChannelId(
diff --git a/desktop/src/features/agents/managedAgentRuntimeStatus.ts b/desktop/src/features/agents/managedAgentRuntimeStatus.ts
index a9f2734f21..c3a952f7d5 100644
--- a/desktop/src/features/agents/managedAgentRuntimeStatus.ts
+++ b/desktop/src/features/agents/managedAgentRuntimeStatus.ts
@@ -57,9 +57,9 @@ export const MANAGED_AGENT_PAIR_ACTION_LABELS: Record<
   ManagedAgentPairAction,
   string
 > = {
-  start: "Start",
-  stop: "Stop",
-  restart: "Restart",
+  start: "Start Agent",
+  stop: "Stop Agent",
+  restart: "Restart Agent",
 };
 
 /**
diff --git a/desktop/src/features/agents/ui/AgentRuntimeAvatarControl.tsx b/desktop/src/features/agents/ui/AgentRuntimeAvatarControl.tsx
index 6f34ffba79..1b3c7a0574 100644
--- a/desktop/src/features/agents/ui/AgentRuntimeAvatarControl.tsx
+++ b/desktop/src/features/agents/ui/AgentRuntimeAvatarControl.tsx
@@ -1,7 +1,6 @@
-import { CircleAlert, Play } from "lucide-react";
+import { CircleAlert } from "lucide-react";
 import { useReducedMotion } from "motion/react";
 
-import { PresenceDot } from "@/features/presence/ui/PresenceBadge";
 import {
   type AvatarBadgeCurve,
   MaskedAvatarBadgeFrame,
@@ -18,8 +17,10 @@ type AgentRuntimeAvatarControlProps = {
   errorLabel?: string | null;
   errorTestId?: string;
   isActive: boolean;
+  isRestarting?: boolean;
   isStarting: boolean;
   label: string;
+  requiresRestart?: boolean;
   startTestId: string;
   onOpenError?: () => void;
   onStart: () => void;
@@ -29,6 +30,7 @@ const TAILWIND_SPACING = {
   "1": 4,
   "2": 8,
   "2.5": 10,
+  "3.5": 14,
   "6": 24,
   "11": 44,
   "24": 96,
@@ -36,44 +38,58 @@ const TAILWIND_SPACING = {
 
 const AGENT_AVATAR_SIZE = TAILWIND_SPACING["24"];
 const ACTION_BADGE_SIZE = TAILWIND_SPACING["11"];
-const ACTIVE_BADGE_SIZE = TAILWIND_SPACING["6"];
-const ACTION_BADGE_OFFSET = TAILWIND_SPACING["2.5"];
+const ACTION_BUTTON_HEIGHT = 36;
+const START_ACTION_BADGE_WIDTH = 56;
+const RESTART_ACTION_BADGE_WIDTH = 72;
+const ACTIVE_BADGE_CUTOUT_SIZE = TAILWIND_SPACING["6"];
+const ACTIVE_DOT_SIZE = 18;
+const ACTION_BADGE_OFFSET = TAILWIND_SPACING["3.5"] + TAILWIND_SPACING["1"];
 const ACTIVE_BADGE_INSET = TAILWIND_SPACING["1"];
-const ACTIVE_DOT_CLASS_NAME = "h-4.5 w-4.5";
 const PROFILE_STATUS_CUTOUT_RATIO = 1.25;
 
 function getBadgeCenter(badgeSize: number, outwardOffset: number) {
   return AGENT_AVATAR_SIZE + outwardOffset - badgeSize / 2;
 }
 
-function getActionBadge(offset: number) {
+function getActionBadge(width: number, height: number, offset: number) {
+  const centerY = getBadgeCenter(ACTION_BADGE_SIZE, offset);
+  const clearance = (ACTION_BADGE_SIZE - height) / 2;
+
   return {
     cutout: {
-      cx: getBadgeCenter(ACTION_BADGE_SIZE, offset),
-      cy: getBadgeCenter(ACTION_BADGE_SIZE, offset),
+      // Keep the cutout on the avatar edge so the mask has the same soft,
+      // two-point join as the status dot. Unlike the status dot, center the
+      // primary action horizontally to make its purpose easier to spot.
+      cx: AGENT_AVATAR_SIZE / 2,
+      cy: centerY,
       r: ACTION_BADGE_SIZE / 2,
     },
     shell: {
-      bottom: -offset,
-      height: ACTION_BADGE_SIZE,
-      right: -offset,
-      width: ACTION_BADGE_SIZE,
+      bottom: AGENT_AVATAR_SIZE - centerY - height / 2,
+      height,
+      right: (AGENT_AVATAR_SIZE - width) / 2,
+      width,
     },
+    // Carry the vertical clearance around the end caps horizontally too, so
+    // the avatar gap stays even around the pill.
+    cutoutWidth: width + clearance * 2,
   } as const;
 }
 
 function getActiveBadge(inset: number) {
+  const center = getBadgeCenter(ACTIVE_BADGE_CUTOUT_SIZE, -inset);
+
   return {
     cutout: {
-      cx: getBadgeCenter(ACTIVE_BADGE_SIZE, -inset),
-      cy: getBadgeCenter(ACTIVE_BADGE_SIZE, -inset),
-      r: (ACTIVE_BADGE_SIZE / 2) * PROFILE_STATUS_CUTOUT_RATIO,
+      cx: center,
+      cy: center,
+      r: (ACTIVE_BADGE_CUTOUT_SIZE / 2) * PROFILE_STATUS_CUTOUT_RATIO,
     },
     shell: {
-      bottom: inset,
-      height: ACTIVE_BADGE_SIZE,
-      right: inset,
-      width: ACTIVE_BADGE_SIZE,
+      bottom: AGENT_AVATAR_SIZE - center - ACTIVE_DOT_SIZE / 2,
+      height: ACTIVE_DOT_SIZE,
+      right: AGENT_AVATAR_SIZE - center - ACTIVE_DOT_SIZE / 2,
+      width: ACTIVE_DOT_SIZE,
     },
   } as const;
 }
@@ -87,12 +103,26 @@ const ACTION_MASK_CURVE = {
   handleLengthRatio: 0.26,
 } satisfies AvatarBadgeCurve;
 
-const ACTION_BADGE = getActionBadge(ACTION_BADGE_OFFSET);
+const START_ACTION_BADGE = getActionBadge(
+  START_ACTION_BADGE_WIDTH,
+  ACTION_BUTTON_HEIGHT,
+  ACTION_BADGE_OFFSET,
+);
+const RESTART_ACTION_BADGE = getActionBadge(
+  RESTART_ACTION_BADGE_WIDTH,
+  ACTION_BUTTON_HEIGHT,
+  ACTION_BADGE_OFFSET,
+);
+const ERROR_BADGE = getActionBadge(
+  ACTION_BADGE_SIZE,
+  ACTION_BUTTON_HEIGHT,
+  ACTION_BADGE_OFFSET,
+);
 const ACTIVE_BADGE = getActiveBadge(ACTIVE_BADGE_INSET);
 
 const MASK_TRANSITION = {
-  duration: 0.22,
-  ease: [0.23, 1, 0.32, 1],
+  duration: 0.3,
+  ease: [0.4, 0, 0.2, 1],
 } as const;
 
 export function AgentRuntimeAvatarControl({
@@ -101,45 +131,66 @@ export function AgentRuntimeAvatarControl({
   errorLabel,
   errorTestId,
   isActive,
+  isRestarting = false,
   isStarting,
   label,
+  requiresRestart = false,
   startTestId,
   onOpenError,
   onStart,
 }: AgentRuntimeAvatarControlProps) {
   const shouldReduceMotion = useReducedMotion();
   const trimmedAvatarUrl = avatarUrl?.trim() || null;
-  const actionLabel = isStarting ? `Starting ${label}` : `Start ${label}`;
-  const hasError = !isActive && !isStarting && Boolean(errorLabel);
+  const isRestartAction = requiresRestart || isRestarting;
+  const actionLabel = isRestarting
+    ? "Restarting Agent"
+    : isStarting
+      ? "Starting Agent"
+      : isRestartAction
+        ? "Restart Agent"
+        : "Start Agent";
+  const actionText = isRestartAction ? "Restart" : "Start";
+  const isPending = isStarting || isRestarting;
+  const showRunningDot = isActive && !isRestartAction;
+  const hasError = !isActive && !isPending && Boolean(errorLabel);
   const errorActionLabel = `${label} has a runtime error. Open runtime details.`;
   const transition = shouldReduceMotion ? { duration: 0 } : MASK_TRANSITION;
-  const badge = isActive ? ACTIVE_BADGE : ACTION_BADGE;
+  const actionBadge = isRestartAction
+    ? RESTART_ACTION_BADGE
+    : START_ACTION_BADGE;
+  const badge = showRunningDot
+    ? ACTIVE_BADGE
+    : hasError
+      ? ERROR_BADGE
+      : actionBadge;
+  const actionCutoutWidth =
+    showRunningDot || hasError ? undefined : actionBadge.cutoutWidth;
 
   return (
     <MaskedAvatarBadgeFrame
       badge={
         <span className="grid h-full w-full place-items-center">
-          {isActive ? (
+          {showRunningDot ? (
             <span
               aria-label={`${label} is running`}
-              className="flex h-6 w-6 items-center justify-center rounded-full"
+              className="h-full w-full rounded-full"
               data-testid={activeTestId}
               role="img"
               title={`${label} is running`}
-            >
-              <PresenceDot className={ACTIVE_DOT_CLASS_NAME} status="online" />
-            </span>
+            />
           ) : (
             <button
               aria-label={hasError ? errorActionLabel : actionLabel}
               className={cn(
-                "pointer-events-auto flex h-9 w-9 items-center justify-center rounded-full transition-colors duration-150 ease-out focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-default disabled:opacity-90",
+                "pointer-events-auto flex h-full w-full items-center justify-center rounded-full px-2.5 text-xs font-semibold leading-none transition-colors duration-150 ease-out focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-default disabled:opacity-90",
                 hasError
                   ? "bg-destructive text-destructive-foreground hover:bg-destructive/90"
-                  : "bg-primary text-primary-foreground hover:bg-primary/90",
+                  : isRestartAction
+                    ? "bg-transparent text-amber-800 hover:bg-amber-500/10 dark:text-amber-400"
+                    : "bg-primary text-primary-foreground hover:bg-primary/90",
               )}
               data-testid={hasError ? errorTestId : startTestId}
-              disabled={isStarting}
+              disabled={isPending}
               onClick={(event) => {
                 event.stopPropagation();
                 if (hasError) {
@@ -151,26 +202,36 @@ export function AgentRuntimeAvatarControl({
               title={hasError ? errorLabel || errorActionLabel : actionLabel}
               type="button"
             >
-              <span className="grid h-4 w-4 place-items-center">
-                {isStarting ? (
-                  <Spinner
-                    aria-label={actionLabel}
-                    className="h-4 w-4 border-2"
-                  />
-                ) : hasError ? (
-                  <CircleAlert className="h-4 w-4" />
-                ) : (
-                  <Play className="h-4 w-4 fill-current" />
-                )}
-              </span>
+              {isPending ? (
+                <Spinner
+                  aria-label={actionLabel}
+                  className="h-4 w-4 border-2"
+                />
+              ) : hasError ? (
+                <CircleAlert className="h-4 w-4" />
+              ) : (
+                actionText
+              )}
             </button>
           )}
         </span>
       }
       badgeBox={badge.shell}
+      badgeClassName={cn(
+        "transition-colors ease-in-out",
+        shouldReduceMotion ? "duration-0" : "duration-300",
+        showRunningDot
+          ? "bg-emerald-500"
+          : hasError
+            ? "bg-destructive"
+            : isRestartAction
+              ? "bg-amber-500/15"
+              : "bg-primary",
+      )}
       className="h-24 w-24"
-      curve={isActive ? STATUS_DOT_MASK_CURVE : ACTION_MASK_CURVE}
+      curve={showRunningDot ? STATUS_DOT_MASK_CURVE : ACTION_MASK_CURVE}
       cutout={badge.cutout}
+      cutoutWidth={actionCutoutWidth}
       maskTransition={transition}
       size={AGENT_AVATAR_SIZE}
     >
diff --git a/desktop/src/features/agents/ui/AgentsView.tsx b/desktop/src/features/agents/ui/AgentsView.tsx
index 720d6e62ad..f9ada91c2f 100644
--- a/desktop/src/features/agents/ui/AgentsView.tsx
+++ b/desktop/src/features/agents/ui/AgentsView.tsx
@@ -225,6 +225,7 @@ export function AgentsView() {
               isActionPending={isActionPending}
               isAgentsLoading={agents.managedAgentsQuery.isLoading}
               startingAgentPubkey={agents.startingAgentPubkey}
+              restartingAgentPubkey={agents.restartingAgentPubkey}
               startingPersonaIds={agents.startingPersonaIds}
               onOpenAgentProfile={(pubkey, options) => {
                 openProfilePanel?.(pubkey, options);
@@ -235,6 +236,9 @@ export function AgentsView() {
               onStartAgent={(pubkey) => {
                 void agents.handleStart(pubkey);
               }}
+              onRestartAgent={(pubkey) => {
+                void agents.handleRestart(pubkey);
+              }}
               onStartPersona={(persona) => {
                 void agents.handleStartPersona(persona);
               }}
diff --git a/desktop/src/features/agents/ui/UnifiedAgentsSection.tsx b/desktop/src/features/agents/ui/UnifiedAgentsSection.tsx
index cf39b0859e..212d9bc96e 100644
--- a/desktop/src/features/agents/ui/UnifiedAgentsSection.tsx
+++ b/desktop/src/features/agents/ui/UnifiedAgentsSection.tsx
@@ -10,7 +10,6 @@ import type { ProfilePanelOpenOptions } from "@/shared/context/ProfilePanelConte
 import { useFeedbackToasts } from "@/shared/hooks/useToastEffect";
 import { useFileImportZone } from "@/shared/hooks/useFileImportZone";
 import { Badge } from "@/shared/ui/badge";
-import { RestartDiffBadge } from "./RestartDiffBadge";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -32,6 +31,7 @@ type UnifiedAgentsSectionProps = {
   agentsError: Error | null;
   isActionPending: boolean;
   isAgentsLoading: boolean;
+  restartingAgentPubkey: string | null;
   startingAgentPubkey: string | null;
   startingPersonaIds: ReadonlySet<string>;
   onOpenAgentProfile: (
@@ -39,6 +39,7 @@ type UnifiedAgentsSectionProps = {
     options?: ProfilePanelOpenOptions,
   ) => void;
   onOpenPersonaProfile: (persona: AgentPersona) => void;
+  onRestartAgent: (pubkey: string) => void;
   onStartAgent: (pubkey: string) => void;
   onStartPersona: (persona: AgentPersona) => void;
   personas: AgentPersona[];
@@ -75,10 +76,12 @@ export function UnifiedAgentsSection(props: UnifiedAgentsSectionProps) {
     agentsError,
     isActionPending,
     isAgentsLoading,
+    restartingAgentPubkey,
     startingAgentPubkey,
     startingPersonaIds,
     onOpenAgentProfile,
     onOpenPersonaProfile,
+    onRestartAgent,
     onStartAgent,
     onStartPersona,
     personas,
@@ -175,10 +178,12 @@ export function UnifiedAgentsSection(props: UnifiedAgentsSectionProps) {
                   defaultModel={defaultModel}
                   key={group.persona.id}
                   persona={group.persona}
+                  restartingAgentPubkey={restartingAgentPubkey}
                   startingAgentPubkey={startingAgentPubkey}
                   startingPersonaIds={startingPersonaIds}
                   onOpenAgentProfile={onOpenAgentProfile}
                   onOpenPersonaProfile={onOpenPersonaProfile}
+                  onRestartAgent={onRestartAgent}
                   onStartAgent={onStartAgent}
                   onStartPersona={onStartPersona}
                 />
@@ -199,9 +204,11 @@ export function UnifiedAgentsSection(props: UnifiedAgentsSectionProps) {
               defaultModel={defaultModel}
               groupKey="__unknown__"
               label="Unknown agents"
+              restartingAgentPubkey={restartingAgentPubkey}
               startingAgentPubkey={startingAgentPubkey}
               onToggle={toggle}
               onOpenAgentProfile={onOpenAgentProfile}
+              onRestartAgent={onRestartAgent}
               onStartAgent={onStartAgent}
             />
           ) : null}
@@ -212,9 +219,11 @@ export function UnifiedAgentsSection(props: UnifiedAgentsSectionProps) {
               defaultModel={defaultModel}
               groupKey="__ungrouped__"
               label="Custom agents"
+              restartingAgentPubkey={restartingAgentPubkey}
               startingAgentPubkey={startingAgentPubkey}
               onToggle={toggle}
               onOpenAgentProfile={onOpenAgentProfile}
+              onRestartAgent={onRestartAgent}
               onStartAgent={onStartAgent}
             />
           ) : null}
@@ -244,10 +253,12 @@ function AgentPersonaCard({
   agent,
   defaultModel,
   persona,
+  restartingAgentPubkey,
   startingAgentPubkey,
   startingPersonaIds,
   onOpenAgentProfile,
   onOpenPersonaProfile,
+  onRestartAgent,
   onStartAgent,
   onStartPersona,
 }: {
@@ -258,6 +269,7 @@ function AgentPersonaCard({
   agent: ManagedAgent | undefined;
   defaultModel: string;
   persona: AgentPersona;
+  restartingAgentPubkey: string | null;
   startingAgentPubkey: string | null;
   startingPersonaIds: ReadonlySet<string>;
   onOpenAgentProfile: (
@@ -265,6 +277,7 @@ function AgentPersonaCard({
     options?: ProfilePanelOpenOptions,
   ) => void;
   onOpenPersonaProfile: (persona: AgentPersona) => void;
+  onRestartAgent: (pubkey: string) => void;
   onStartAgent: (pubkey: string) => void;
   onStartPersona: (persona: AgentPersona) => void;
 }) {
@@ -299,13 +312,19 @@ function AgentPersonaCard({
             errorLabel={friendlyError}
             errorTestId={`agent-runtime-error-${agent.pubkey}`}
             isActive={isActive}
+            isRestarting={restartingAgentPubkey === agent.pubkey}
             isStarting={startingAgentPubkey === agent.pubkey}
             label={title}
+            requiresRestart={agent.needsRestart}
             startTestId={`agent-runtime-start-${agent.pubkey}`}
             onOpenError={() => {
               onOpenAgentProfile(agent.pubkey, { tab: "runtime" });
             }}
-            onStart={() => onStartAgent(agent.pubkey)}
+            onStart={() =>
+              agent.needsRestart
+                ? onRestartAgent(agent.pubkey)
+                : onStartAgent(agent.pubkey)
+            }
           />
         ) : (
           <AgentRuntimeAvatarControl
@@ -339,11 +358,6 @@ function AgentPersonaCard({
             <AlertTriangle className="h-3 w-3" />
             Configuration missing
           </Badge>
-        ) : agent?.needsRestart ? (
-          <RestartDiffBadge
-            autoRestartEnabled={agent.autoRestartOnConfigChange}
-            restartDiff={agent.restartDiff}
-          />
         ) : null
       }
     />
@@ -353,17 +367,21 @@ function AgentPersonaCard({
 function StandaloneAgentCard({
   agent,
   defaultModel,
+  restartingAgentPubkey,
   startingAgentPubkey,
   onOpenAgentProfile,
+  onRestartAgent,
   onStartAgent,
 }: {
   agent: ManagedAgent;
   defaultModel: string;
+  restartingAgentPubkey: string | null;
   startingAgentPubkey: string | null;
   onOpenAgentProfile: (
     pubkey: string,
     options?: ProfilePanelOpenOptions,
   ) => void;
+  onRestartAgent: (pubkey: string) => void;
   onStartAgent: (pubkey: string) => void;
 }) {
   const title = agent.name;
@@ -385,13 +403,19 @@ function StandaloneAgentCard({
           errorLabel={friendlyError}
           errorTestId={`agent-runtime-error-${agent.pubkey}`}
           isActive={isActive}
+          isRestarting={restartingAgentPubkey === agent.pubkey}
           isStarting={startingAgentPubkey === agent.pubkey}
           label={title}
+          requiresRestart={agent.needsRestart}
           startTestId={`agent-runtime-start-${agent.pubkey}`}
           onOpenError={() => {
             onOpenAgentProfile(agent.pubkey, { tab: "runtime" });
           }}
-          onStart={() => onStartAgent(agent.pubkey)}
+          onStart={() =>
+            agent.needsRestart
+              ? onRestartAgent(agent.pubkey)
+              : onStartAgent(agent.pubkey)
+          }
         />
       }
       avatarUrl={profileQuery.data?.avatarUrl}
@@ -414,11 +438,6 @@ function StandaloneAgentCard({
             <AlertTriangle className="h-3 w-3" />
             Configuration missing
           </Badge>
-        ) : agent.needsRestart ? (
-          <RestartDiffBadge
-            autoRestartEnabled={agent.autoRestartOnConfigChange}
-            restartDiff={agent.restartDiff}
-          />
         ) : null
       }
     />
@@ -498,9 +517,11 @@ function CollapsibleAgentGroup({
   agents,
   collapsed,
   defaultModel,
+  restartingAgentPubkey,
   startingAgentPubkey,
   onToggle,
   onOpenAgentProfile,
+  onRestartAgent,
   onStartAgent,
 }: {
   groupKey: string;
@@ -508,12 +529,14 @@ function CollapsibleAgentGroup({
   agents: ManagedAgent[];
   collapsed: ReadonlySet<string>;
   defaultModel: string;
+  restartingAgentPubkey: string | null;
   startingAgentPubkey: string | null;
   onToggle: (key: string) => void;
   onOpenAgentProfile: (
     pubkey: string,
     options?: ProfilePanelOpenOptions,
   ) => void;
+  onRestartAgent: (pubkey: string) => void;
   onStartAgent: (pubkey: string) => void;
 }) {
   const isCollapsed = collapsed.has(groupKey);
@@ -539,8 +562,10 @@ function CollapsibleAgentGroup({
               agent={agent}
               defaultModel={defaultModel}
               key={agent.pubkey}
+              restartingAgentPubkey={restartingAgentPubkey}
               startingAgentPubkey={startingAgentPubkey}
               onOpenAgentProfile={onOpenAgentProfile}
+              onRestartAgent={onRestartAgent}
               onStartAgent={onStartAgent}
             />
           ))}
diff --git a/desktop/src/features/agents/ui/useManagedAgentActions.ts b/desktop/src/features/agents/ui/useManagedAgentActions.ts
index e1c2e9c9fc..6068ad1639 100644
--- a/desktop/src/features/agents/ui/useManagedAgentActions.ts
+++ b/desktop/src/features/agents/ui/useManagedAgentActions.ts
@@ -26,6 +26,7 @@ import { normalizePubkey } from "@/shared/lib/pubkey";
 import {
   deleteManagedAgentWithRules,
   isManagedAgentActive,
+  respawnManagedAgentWithRules,
   startManagedAgentWithRules,
   stopManagedAgentWithRules,
 } from "../lib/managedAgentControlActions";
@@ -57,6 +58,9 @@ export function useManagedAgentActions() {
     ReadonlySet<string>
   >(() => new Set());
   const startingPersonaIdsRef = React.useRef(new Set<string>());
+  const [restartingAgentPubkey, setRestartingAgentPubkey] = React.useState<
+    string | null
+  >(null);
   const [logAgentPubkey, setLogAgentPubkey] = React.useState<string | null>(
     null,
   );
@@ -174,6 +178,30 @@ export function useManagedAgentActions() {
     }
   }
 
+  async function handleRestart(pubkey: string) {
+    if (restartingAgentPubkey) return;
+    clearFeedback();
+    setRestartingAgentPubkey(pubkey);
+    try {
+      const agent = managedAgents.find(
+        (candidate) => candidate.pubkey === pubkey,
+      );
+      if (!agent) return;
+      await respawnManagedAgentWithRules({
+        agent,
+        startManagedAgent: startMutation.mutateAsync,
+        stopManagedAgent: stopMutation.mutateAsync,
+        onStopped: () => clearActiveTurnsForAgentOnStop(agent.pubkey),
+      });
+    } catch (error) {
+      setActionErrorMessage(
+        error instanceof Error ? error.message : "Failed to restart agent.",
+      );
+    } finally {
+      setRestartingAgentPubkey(null);
+    }
+  }
+
   function setPersonaStartPending(personaId: string, pending: boolean) {
     const next = new Set(startingPersonaIdsRef.current);
     if (pending) {
@@ -387,6 +415,7 @@ export function useManagedAgentActions() {
   }
 
   const isPending =
+    restartingAgentPubkey !== null ||
     createAgentMutation.isPending ||
     startMutation.isPending ||
     stopMutation.isPending ||
@@ -420,8 +449,10 @@ export function useManagedAgentActions() {
     actionErrorMessage,
     setActionErrorMessage,
     startingAgentPubkey,
+    restartingAgentPubkey,
     startingPersonaIds,
     handleStart,
+    handleRestart,
     handleStartPersona,
     handleStop,
     handleDelete,
diff --git a/desktop/src/features/profile/ui/MaskedAvatarBadgeFrame.tsx b/desktop/src/features/profile/ui/MaskedAvatarBadgeFrame.tsx
index 294a87e5e2..ea6e234493 100644
--- a/desktop/src/features/profile/ui/MaskedAvatarBadgeFrame.tsx
+++ b/desktop/src/features/profile/ui/MaskedAvatarBadgeFrame.tsx
@@ -43,12 +43,14 @@ type BadgeMotionTarget = {
 type MaskedAvatarBadgeFrameProps = {
   badge?: React.ReactNode;
   badgeBox?: AvatarBadgeBox;
+  badgeClassName?: string;
   children: React.ReactNode;
   className?: string;
   clipTestId?: string;
   cornerRadius?: number;
   curve?: AvatarBadgeCurve;
   cutout?: AvatarBadgeCircle;
+  cutoutWidth?: number;
   maskMode?: "clip-path" | "radial";
   maskTransition?: React.ComponentProps<typeof motion.path>["transition"];
   size: number;
@@ -323,6 +325,30 @@ function sampleArc(
   );
 }
 
+function sampleStableOuterBoundary(
+  avatar: AvatarBadgeCircle,
+  startAngle: number,
+  endAngle: number,
+  direction: 1 | -1,
+  largeArc: boolean,
+  segments: number,
+) {
+  const outerBoundary = { ...avatar, r: avatar.r * 4 };
+
+  return [
+    getPointOnCircle(outerBoundary, startAngle),
+    ...sampleArc(
+      outerBoundary,
+      startAngle,
+      endAngle,
+      direction,
+      largeArc,
+      segments - 2,
+    ),
+    getPointOnCircle(avatar, endAngle),
+  ];
+}
+
 function toPolygonPoint(point: Point, size: number) {
   return `${toPercent(point.x / size)} ${toPercent(point.y / size)}`;
 }
@@ -331,6 +357,7 @@ function getRoundedAvatarMaskPolygon(
   size: number,
   cutout: AvatarBadgeCircle,
   curve?: AvatarBadgeCurve,
+  stabilizeOuterBoundary = false,
 ) {
   const {
     avatar,
@@ -361,14 +388,23 @@ function getRoundedAvatarMaskPolygon(
       avatarUpper,
       12,
     ),
-    ...sampleArc(
-      avatar,
-      getAngle(avatar, avatarUpper),
-      getAngle(avatar, avatarLower),
-      -1,
-      true,
-      96,
-    ),
+    ...(stabilizeOuterBoundary
+      ? sampleStableOuterBoundary(
+          avatar,
+          getAngle(avatar, avatarUpper),
+          getAngle(avatar, avatarLower),
+          -1,
+          true,
+          96,
+        )
+      : sampleArc(
+          avatar,
+          getAngle(avatar, avatarUpper),
+          getAngle(avatar, avatarLower),
+          -1,
+          true,
+          96,
+        )),
     ...sampleCubic(
       avatarLower,
       getControlPoint(avatarLower, lowerAvatarTangent, lowerHandleLength),
@@ -389,6 +425,141 @@ function getRoundedAvatarMaskPolygon(
   return `polygon(${points.map((point) => toPolygonPoint(point, size)).join(", ")})`;
 }
 
+function getRoundedAvatarCapsuleMaskPolygon(
+  size: number,
+  cutout: AvatarBadgeCircle,
+  cutoutWidth: number,
+  curve?: AvatarBadgeCurve,
+  stabilizeOuterBoundary = false,
+) {
+  const resolvedCurve = { ...DEFAULT_AVATAR_BADGE_CURVE, ...curve };
+  const avatar = {
+    cx: size / 2,
+    cy: size / 2,
+    r: size / 2,
+  };
+  const straightHalfWidth = Math.max(0, cutoutWidth / 2 - cutout.r);
+  const leftCap = {
+    cx: cutout.cx - straightHalfWidth,
+    cy: cutout.cy,
+    r: cutout.r,
+  };
+  const rightCap = {
+    cx: cutout.cx + straightHalfWidth,
+    cy: cutout.cy,
+    r: cutout.r,
+  };
+  const leftIntersection = getCircleIntersections(avatar, leftCap).reduce(
+    (leftmost, point) => (point.x < leftmost.x ? point : leftmost),
+  );
+  const rightIntersection = getCircleIntersections(avatar, rightCap).reduce(
+    (rightmost, point) => (point.x > rightmost.x ? point : rightmost),
+  );
+  const cutoutRoundingAngle = Math.min(
+    resolvedCurve.cutoutRoundingMaxAngle,
+    Math.max(
+      resolvedCurve.cutoutRoundingMinAngle,
+      resolvedCurve.cutoutRoundingLength / cutout.r,
+    ),
+  );
+  const avatarLeft = getPointOnCircle(
+    avatar,
+    getAngle(avatar, leftIntersection) + resolvedCurve.avatarRoundingAngle,
+  );
+  const avatarRight = getPointOnCircle(
+    avatar,
+    getAngle(avatar, rightIntersection) - resolvedCurve.avatarRoundingAngle,
+  );
+  const cutoutLeft = getPointOnCircle(
+    leftCap,
+    getAngle(leftCap, leftIntersection) + cutoutRoundingAngle,
+  );
+  const cutoutRight = getPointOnCircle(
+    rightCap,
+    getAngle(rightCap, rightIntersection) - cutoutRoundingAngle,
+  );
+  const leftHandleLength = Math.min(
+    cutout.r * resolvedCurve.handleLengthRatio,
+    getDistance(cutoutLeft, avatarLeft) * resolvedCurve.handleDistanceRatio,
+  );
+  const rightHandleLength = Math.min(
+    cutout.r * resolvedCurve.handleLengthRatio,
+    getDistance(avatarRight, cutoutRight) * resolvedCurve.handleDistanceRatio,
+  );
+  const cutoutLeftTangent = getTangent(getAngle(leftCap, cutoutLeft), -1);
+  const avatarLeftTangent = getTangent(getAngle(avatar, avatarLeft), 1);
+  const avatarRightTangent = getTangent(getAngle(avatar, avatarRight), 1);
+  const cutoutRightTangent = getTangent(getAngle(rightCap, cutoutRight), -1);
+  const points = [
+    cutoutLeft,
+    ...sampleCubic(
+      cutoutLeft,
+      getControlPoint(cutoutLeft, cutoutLeftTangent, leftHandleLength),
+      getControlPoint(avatarLeft, avatarLeftTangent, -leftHandleLength),
+      avatarLeft,
+      12,
+    ),
+    ...(stabilizeOuterBoundary
+      ? sampleStableOuterBoundary(
+          avatar,
+          getAngle(avatar, avatarLeft),
+          getAngle(avatar, avatarRight),
+          1,
+          true,
+          96,
+        )
+      : sampleArc(
+          avatar,
+          getAngle(avatar, avatarLeft),
+          getAngle(avatar, avatarRight),
+          1,
+          true,
+          96,
+        )),
+    ...sampleCubic(
+      avatarRight,
+      getControlPoint(avatarRight, avatarRightTangent, rightHandleLength),
+      getControlPoint(cutoutRight, cutoutRightTangent, -rightHandleLength),
+      cutoutRight,
+      12,
+    ),
+    ...sampleArc(
+      rightCap,
+      getAngle(rightCap, cutoutRight),
+      -Math.PI / 2,
+      -1,
+      false,
+      12,
+    ),
+    { x: leftCap.cx, y: cutout.cy - cutout.r },
+    ...sampleArc(
+      leftCap,
+      -Math.PI / 2,
+      getAngle(leftCap, cutoutLeft),
+      -1,
+      false,
+      11,
+    ),
+  ];
+
+  // Keep the capsule contour aligned with the circular status cutout's point
+  // order. Matching like-for-like edges prevents the polygon from folding
+  // across the avatar while Motion interpolates between the two shapes.
+  const joinSegments = 12;
+  const outerSegments = 96;
+  const outerEndIndex = joinSegments + outerSegments;
+  const rightJoinEndIndex = joinSegments * 2 + outerSegments;
+  const alignedPoints = [
+    points[rightJoinEndIndex],
+    ...points.slice(outerEndIndex, rightJoinEndIndex).reverse(),
+    ...points.slice(joinSegments, outerEndIndex).reverse(),
+    ...points.slice(0, joinSegments).reverse(),
+    ...points.slice(rightJoinEndIndex + 1).reverse(),
+  ];
+
+  return `polygon(${alignedPoints.map((point) => toPolygonPoint(point, size)).join(", ")})`;
+}
+
 function getRoundedSquareMaskPolygon(
   size: number,
   cornerRadius: number,
@@ -488,20 +659,36 @@ function getRoundedSquareMaskPolygon(
 export function MaskedAvatarBadgeFrame({
   badge,
   badgeBox,
+  badgeClassName,
   children,
   className,
   clipTestId,
   cornerRadius,
   curve,
   cutout,
+  cutoutWidth,
   maskMode = "clip-path",
   maskTransition,
   size,
 }: MaskedAvatarBadgeFrameProps) {
   const shouldMask = Boolean(badge && badgeBox && cutout);
+  const stabilizeOuterBoundary = Boolean(maskTransition);
   const maskPolygon = cutout
     ? cornerRadius === undefined
-      ? getRoundedAvatarMaskPolygon(size, cutout, curve)
+      ? cutoutWidth && cutoutWidth > cutout.r * 2
+        ? getRoundedAvatarCapsuleMaskPolygon(
+            size,
+            cutout,
+            cutoutWidth,
+            curve,
+            stabilizeOuterBoundary,
+          )
+        : getRoundedAvatarMaskPolygon(
+            size,
+            cutout,
+            curve,
+            stabilizeOuterBoundary,
+          )
       : getRoundedSquareMaskPolygon(size, cornerRadius, cutout, curve)
     : undefined;
   const radialMask =
@@ -539,10 +726,18 @@ export function MaskedAvatarBadgeFrame({
         data-testid={clipTestId}
         initial={false}
         style={{
-          WebkitClipPath: radialMask ? undefined : maskPolygon,
+          // WebKit otherwise applies the prefixed path immediately while the
+          // unprefixed path is still animating, which briefly tears the avatar.
+          WebkitClipPath:
+            radialMask || maskTransition ? undefined : maskPolygon,
           WebkitMaskImage: radialMask,
+          backfaceVisibility:
+            maskTransition && !radialMask ? "hidden" : undefined,
           clipPath: radialMask ? undefined : maskPolygon,
           maskImage: radialMask,
+          transform:
+            maskTransition && !radialMask ? "translateZ(0)" : undefined,
+          willChange: maskTransition && !radialMask ? "clip-path" : undefined,
         }}
         transition={maskTransition}
       >
@@ -551,7 +746,10 @@ export function MaskedAvatarBadgeFrame({
 
       <motion.span
         animate={maskTransition ? badgeMotionTarget : undefined}
-        className="absolute z-20 flex items-center justify-center rounded-full"
+        className={cn(
+          "absolute z-20 flex items-center justify-center rounded-full",
+          badgeClassName,
+        )}
         initial={false}
         style={badgeStyle}
         transition={maskTransition}
diff --git a/desktop/src/features/profile/ui/UserProfilePrimaryActions.tsx b/desktop/src/features/profile/ui/UserProfilePrimaryActions.tsx
index f03635ff18..254b556e86 100644
--- a/desktop/src/features/profile/ui/UserProfilePrimaryActions.tsx
+++ b/desktop/src/features/profile/ui/UserProfilePrimaryActions.tsx
@@ -108,7 +108,7 @@ export function ProfilePrimaryActions({
         <ProfileQuickAction
           disabled={agentActionDisabled}
           icon={RefreshCw}
-          label="Restart"
+          label="Restart Agent"
           onClick={onAgentRestart}
           testId="user-profile-agent-restart"
         />
@@ -143,7 +143,7 @@ export function ProfilePersonaPrimaryActions({
       <ProfileQuickAction
         disabled={disabled}
         icon={Play}
-        label="Start agent"
+        label="Start Agent"
         onClick={onStartAgent}
         testId="user-profile-start-agent"
       />
diff --git a/desktop/tests/e2e/agents.spec.ts b/desktop/tests/e2e/agents.spec.ts
index 3cbe097c05..befe2b5563 100644
--- a/desktop/tests/e2e/agents.spec.ts
+++ b/desktop/tests/e2e/agents.spec.ts
@@ -2437,6 +2437,100 @@ test("personas referenced by teams cannot be deleted", async ({ page }) => {
   );
 });
 
+test("start pill morphs into the running dot without remounting the avatar", async ({
+  page,
+}) => {
+  const personaId = "custom:motion-auditor";
+  const pubkey = "ab".repeat(32);
+  const activeDotSize = 18;
+  await page.emulateMedia({ reducedMotion: "no-preference" });
+  await installMockBridge(page, {
+    personas: [
+      {
+        avatarUrl: emojiAvatarDataUrl("✨", "#7657FF"),
+        displayName: "Motion Auditor",
+        id: personaId,
+        systemPrompt: "You audit motion continuity.",
+      },
+    ],
+    managedAgents: [
+      {
+        name: "Motion Auditor",
+        personaId,
+        pubkey,
+        status: "stopped",
+      },
+    ],
+  });
+  await gotoApp(page);
+  await page.getByTestId("open-agents-view").click();
+
+  const card = page.getByTestId(`persona-agent-row-${personaId}`);
+  const startButton = page.getByTestId(`agent-runtime-start-${pubkey}`);
+  const badge = startButton.locator("xpath=../..");
+  const initialAvatar = await card
+    .getByAltText("Motion Auditor avatar")
+    .elementHandle();
+  expect(initialAvatar).not.toBeNull();
+
+  const samplesPromise = badge.evaluate(async (element) => {
+    const samples: Array<{
+      backgroundColor: string;
+      height: number;
+      width: number;
+    }> = [];
+    const startedAt = performance.now();
+
+    while (performance.now() - startedAt < 440) {
+      const bounds = element.getBoundingClientRect();
+      samples.push({
+        backgroundColor: getComputedStyle(element).backgroundColor,
+        height: bounds.height,
+        width: bounds.width,
+      });
+      await new Promise<void>((resolve) =>
+        requestAnimationFrame(() => resolve()),
+      );
+    }
+
+    return samples;
+  });
+
+  await page.waitForTimeout(32);
+  await startButton.click();
+  await expect(
+    page.getByTestId(`agent-runtime-active-${pubkey}`),
+  ).toBeVisible();
+  const samples = await samplesPromise;
+  const finalAvatar = await card
+    .getByAltText("Motion Auditor avatar")
+    .elementHandle();
+
+  expect(samples[0]?.width).toBeCloseTo(56, 0);
+  expect(samples[0]?.height).toBeCloseTo(36, 0);
+  expect(
+    samples.some(
+      (sample) =>
+        sample.width > activeDotSize &&
+        sample.width < 56 &&
+        sample.height > activeDotSize &&
+        sample.height < 36,
+    ),
+  ).toBe(true);
+  expect(samples.at(-1)?.width).toBeCloseTo(activeDotSize, 0);
+  expect(samples.at(-1)?.height).toBeCloseTo(activeDotSize, 0);
+  expect(samples.at(-1)?.backgroundColor).not.toBe(samples[0]?.backgroundColor);
+  await expect(
+    page.getByTestId(`agent-runtime-active-${pubkey}`).locator("xpath=../.."),
+  ).toHaveClass(/bg-emerald-500/);
+  expect(
+    await initialAvatar?.evaluate(
+      (before, after) => before === after,
+      finalAvatar,
+    ),
+  ).toBe(true);
+});
+
 test("duplicate instances move from the agents gallery into the agent profile", async ({
   page,
 }) => {
diff --git a/desktop/tests/e2e/needs-restart-screenshots.spec.ts b/desktop/tests/e2e/needs-restart-screenshots.spec.ts
index 1a695844fb..508a5d91e9 100644
--- a/desktop/tests/e2e/needs-restart-screenshots.spec.ts
+++ b/desktop/tests/e2e/needs-restart-screenshots.spec.ts
@@ -3,8 +3,8 @@
  * overlay work).
  *
  * Exercises:
- *   - Agent grid card and list-row badges at all three badge sites.
- *   - Hover tooltip with itemised before→after diff (capped at 6 + "and N more").
+ *   - Agent grid restart actions without a duplicate status badge.
+ *   - Profile badge tooltip with itemised before→after diff.
  *   - Runtime-tab banner with full uncapped diff list.
  *   - Side-panel badge visible on the default (Info) tab — not only Runtime.
  *   - DOM validity: tooltip trigger has no <button> ancestor.
@@ -80,7 +80,7 @@ const PERSONA_AGENT = {
   restartDiff: DIFF_ENTRIES,
 };
 
-/** Running agent with no config drift — badge must be absent. */
+/** Running agent with no config drift — restart action must be absent. */
 const NO_DRIFT_AGENT = {
   pubkey: TEST_IDENTITIES.tyler.pubkey,
   name: "Stable Agent",
@@ -88,25 +88,6 @@ const NO_DRIFT_AGENT = {
   needsRestart: false,
 };
 
-/** Agent with only 3 diff entries — tooltip shows all, no "and N more". */
-const SHORT_DIFF_AGENT = {
-  pubkey: TEST_IDENTITIES.charlie.pubkey,
-  name: "Short Diff Agent",
-  status: "running" as const,
-  needsRestart: true,
-  restartDiff: [
-    {
-      field: "model",
-      change: { kind: "value" as const, before: null, after: "gpt-5" },
-    },
-    {
-      field: "some_unknown_field",
-      change: { kind: "value" as const, before: "old", after: "new" },
-    },
-    { field: "env.MY_TOKEN", change: { kind: "removed" as const } },
-  ],
-};
-
 /**
  * Inactive agent with a friendly error AND a restart diff. Opening its card
  * forces the panel to open on the Runtime tab (opensRuntimeTab logic).
@@ -122,6 +103,21 @@ const INACTIVE_FRIENDLY_ERROR_AGENT = {
   lastErrorCode: -32002,
 };
 
+const RESTART_AGENT = {
+  pubkey: "cd".repeat(32),
+  name: "Restart Agent",
+  status: "running" as const,
+  needsRestart: true,
+  restartDiff: DIFF_ENTRIES,
+};
+
+const START_AGENT = {
+  pubkey: "ef".repeat(32),
+  name: "Start Agent",
+  status: "stopped" as const,
+  needsRestart: false,
+};
+
 async function gotoAgentsView(page: import("@playwright/test").Page) {
   await page.goto("/", { waitUntil: "domcontentloaded" });
   await expect(page.getByTestId("open-agents-view")).toBeVisible({
@@ -133,6 +129,86 @@ async function gotoAgentsView(page: import("@playwright/test").Page) {
   });
 }
 
+const WCAG_AA_NORMAL_TEXT_CONTRAST = 4.5;
+
+async function renderedTextContrast(
+  locator: import("@playwright/test").Locator,
+): Promise<number> {
+  return locator.evaluate((element) => {
+    type Rgba = { r: number; g: number; b: number; a: number };
+
+    const canvas = document.createElement("canvas");
+    canvas.width = 1;
+    canvas.height = 1;
+    const context = canvas.getContext("2d", { willReadFrequently: true });
+    if (!context) throw new Error("Could not create contrast test canvas");
+
+    const parseColor = (color: string): Rgba => {
+      context.clearRect(0, 0, 1, 1);
+      context.fillStyle = color;
+      context.fillRect(0, 0, 1, 1);
+      const [r, g, b, alpha] = context.getImageData(0, 0, 1, 1).data;
+      return { r, g, b, a: alpha / 255 };
+    };
+
+    const composite = (foreground: Rgba, background: Rgba): Rgba => {
+      const alpha = foreground.a + background.a * (1 - foreground.a);
+      if (alpha === 0) return { r: 0, g: 0, b: 0, a: 0 };
+
+      return {
+        r:
+          (foreground.r * foreground.a +
+            background.r * background.a * (1 - foreground.a)) /
+          alpha,
+        g:
+          (foreground.g * foreground.a +
+            background.g * background.a * (1 - foreground.a)) /
+          alpha,
+        b:
+          (foreground.b * foreground.a +
+            background.b * background.a * (1 - foreground.a)) /
+          alpha,
+        a: alpha,
+      };
+    };
+
+    const backgroundLayers: Rgba[] = [];
+    let current: Element | null = element;
+    while (current) {
+      backgroundLayers.push(
+        parseColor(window.getComputedStyle(current).backgroundColor),
+      );
+      current = current.parentElement;
+    }
+
+    let renderedBackground: Rgba = { r: 255, g: 255, b: 255, a: 1 };
+    for (const layer of backgroundLayers.reverse()) {
+      renderedBackground = composite(layer, renderedBackground);
+    }
+
+    const renderedForeground = composite(
+      parseColor(window.getComputedStyle(element).color),
+      renderedBackground,
+    );
+    const luminance = (color: Rgba) => {
+      const channels = [color.r, color.g, color.b].map((value) => {
+        const channel = value / 255;
+        return channel <= 0.04045
+          ? channel / 12.92
+          : ((channel + 0.055) / 1.055) ** 2.4;
+      });
+      return 0.2126 * channels[0] + 0.7152 * channels[1] + 0.0722 * channels[2];
+    };
+    const foregroundLuminance = luminance(renderedForeground);
+    const backgroundLuminance = luminance(renderedBackground);
+
+    return (
+      (Math.max(foregroundLuminance, backgroundLuminance) + 0.05) /
+      (Math.min(foregroundLuminance, backgroundLuminance) + 0.05)
+    );
+  });
+}
+
 test.describe("restart-diff screenshots", () => {
   test.use({ viewport: { width: 1280, height: 900 } });
 
@@ -159,17 +235,16 @@ test.describe("restart-diff screenshots", () => {
       `managed-agent-${STANDALONE_AGENT.pubkey}`,
     );
     await expect(agentCard).toBeVisible({ timeout: 10_000 });
-    await expect(
-      agentCard.getByText("Restart required", { exact: true }),
-    ).toBeVisible();
+    await expect(agentCard.getByText("Restart", { exact: true })).toBeVisible();
+    await expect(agentCard.getByTestId("restart-diff-badge")).toHaveCount(0);
 
     const stableCard = page.getByTestId(
       `managed-agent-${NO_DRIFT_AGENT.pubkey}`,
     );
     await expect(stableCard).toBeVisible({ timeout: 10_000 });
-    await expect(
-      stableCard.getByText("Restart required", { exact: true }),
-    ).toHaveCount(0);
+    await expect(stableCard.getByText("Restart", { exact: true })).toHaveCount(
+      0,
+    );
 
     await waitForAnimations(page);
     await agentCard.screenshot({
@@ -190,8 +265,9 @@ test.describe("restart-diff screenshots", () => {
     );
     await expect(personaCard).toBeVisible({ timeout: 10_000 });
     await expect(
-      personaCard.getByText("Restart required", { exact: true }),
+      personaCard.getByText("Restart", { exact: true }),
     ).toBeVisible();
+    await expect(personaCard.getByTestId("restart-diff-badge")).toHaveCount(0);
 
     await waitForAnimations(page);
     await personaCard.screenshot({
@@ -199,119 +275,101 @@ test.describe("restart-diff screenshots", () => {
     });
   });
 
-  // ── Tooltip on card badge + no-button-ancestor (B4: badge is sibling of the overlay button) ─
-
-  test("03-card-badge-tooltip-and-no-button-ancestor", async ({ page }) => {
+  test("03-running-restart-action", async ({ page }) => {
     await installMockBridge(page, {
-      managedAgents: [STANDALONE_AGENT, NO_DRIFT_AGENT],
+      managedAgents: [RESTART_AGENT],
     });
 
     await gotoAgentsView(page);
 
-    const agentCard = page.getByTestId(
-      `managed-agent-${STANDALONE_AGENT.pubkey}`,
-    );
+    const agentCard = page.getByTestId(`managed-agent-${RESTART_AGENT.pubkey}`);
     await expect(agentCard).toBeVisible({ timeout: 10_000 });
-
-    // B4: the tooltip trigger must have no <button> ancestor.
-    // In AgentIdentityCard the badge lives in a z-30 container that is a
-    // sibling of the z-10 overlay <button> — not a descendant of it.
-    const badgeLocator = agentCard.getByTestId("restart-diff-badge");
-    await expect(badgeLocator).toBeVisible();
-
-    const hasButtonAncestor = await badgeLocator.evaluate((el) => {
-      let node: Element | null = el.parentElement;
-      while (node) {
-        if (node.tagName === "BUTTON") return true;
-        node = node.parentElement;
-      }
-      return false;
-    });
-    expect(hasButtonAncestor).toBe(false);
-
-    // Hover to open tooltip
-    await badgeLocator.hover();
-    const tooltip = page.locator("[role=tooltip]");
-    await expect(tooltip).toBeVisible({ timeout: 5_000 });
-
-    // Tooltip is capped at 6 entries with "and 2 more" for 8-entry diff
-    await expect(tooltip.getByText("Model:")).toBeVisible();
-    await expect(tooltip.getByText("and 2 more")).toBeVisible();
-
-    // Array value rendered as JSON.stringify in the value slot
-    await expect(tooltip.getByText(/\["acp"\]/)).toBeVisible();
-
-    await waitForAnimations(page);
-    await page.screenshot({ path: `${SHOTS}/03-card-badge-tooltip.png` });
-  });
-
-  // ── Tooltip with short diff (no truncation) ─────────────────────────────────
-
-  test("04-card-tooltip-short-diff-no-truncation", async ({ page }) => {
-    await installMockBridge(page, {
-      managedAgents: [SHORT_DIFF_AGENT],
-    });
-
-    await gotoAgentsView(page);
-
-    const agentCard = page.getByTestId(
-      `managed-agent-${SHORT_DIFF_AGENT.pubkey}`,
+    const restartAction = page.getByTestId(
+      `agent-runtime-start-${RESTART_AGENT.pubkey}`,
+    );
+    await expect(restartAction).toHaveText("Restart");
+    await expect(restartAction).toHaveAttribute("aria-label", "Restart Agent");
+    await expect(restartAction).toHaveClass(/bg-transparent/);
+    await expect(restartAction).toHaveClass(/text-amber-800/);
+    await expect(restartAction).toHaveClass(/dark:text-amber-400/);
+    await expect(restartAction.locator("svg")).toHaveCount(0);
+    await expect(restartAction).toHaveCSS("width", "72px");
+    await expect(restartAction).toHaveCSS("height", "36px");
+    await expect(agentCard.getByTestId("restart-diff-badge")).toHaveCount(0);
+    await expect(page.locator("html")).toHaveClass(/light/);
+    expect(await renderedTextContrast(restartAction)).toBeGreaterThanOrEqual(
+      WCAG_AA_NORMAL_TEXT_CONTRAST,
     );
-    const badge = agentCard.getByTestId("restart-diff-badge");
-    await expect(badge).toBeVisible({ timeout: 10_000 });
-    await badge.hover();
-    const tooltip = page.locator("[role=tooltip]");
-    await expect(tooltip).toBeVisible({ timeout: 5_000 });
-
-    // All 3 entries visible
-    await expect(tooltip.getByText("Model:")).toBeVisible();
-    // Unknown field humanised generically
-    await expect(tooltip.getByText("Some unknown field:")).toBeVisible();
-    // No truncation line
-    await expect(tooltip.getByText(/and \d+ more/)).toHaveCount(0);
 
     await waitForAnimations(page);
-    await page.screenshot({ path: `${SHOTS}/04-short-diff-no-truncation.png` });
+    await agentCard.screenshot({
+      path: `${SHOTS}/03-running-restart-action.png`,
+    });
   });
 
-  // ── Keyboard focus shows tooltip ──────────────────────────────────────────
-
-  test("05-card-tooltip-keyboard-focus", async ({ page }) => {
+  test("restart action meets WCAG AA contrast in dark mode", async ({
+    page,
+  }) => {
+    await page.addInitScript(() => {
+      window.localStorage.setItem("buzz-theme", "catppuccin-mocha");
+    });
     await installMockBridge(page, {
-      managedAgents: [STANDALONE_AGENT],
+      managedAgents: [RESTART_AGENT],
     });
 
     await gotoAgentsView(page);
 
-    const badge = page
-      .getByTestId(`managed-agent-${STANDALONE_AGENT.pubkey}`)
-      .getByTestId("restart-diff-badge");
-    await badge.focus();
-    const tooltip = page.locator("[role=tooltip]");
-    await expect(tooltip).toBeVisible({ timeout: 5_000 });
+    const restartAction = page.getByTestId(
+      `agent-runtime-start-${RESTART_AGENT.pubkey}`,
+    );
+    await expect(restartAction).toBeVisible();
+    await expect(page.locator("html")).toHaveClass(/dark/);
+    expect(await renderedTextContrast(restartAction)).toBeGreaterThanOrEqual(
+      WCAG_AA_NORMAL_TEXT_CONTRAST,
+    );
   });
 
-  // ── Persona card tooltip (AgentIdentityCard — pointer-events-auto) ─────────
-
-  test("06-persona-card-tooltip", async ({ page }) => {
+  test("start and restart pills share geometry except for width", async ({
+    page,
+  }) => {
     await installMockBridge(page, {
-      activePersonaIds: ["builtin:fizz"],
-      managedAgents: [PERSONA_AGENT],
+      managedAgents: [START_AGENT, RESTART_AGENT],
     });
 
     await gotoAgentsView(page);
 
-    const personaCard = page.getByTestId(
-      `persona-agent-row-${PERSONA_AGENT.personaId}`,
+    const startAction = page.getByTestId(
+      `agent-runtime-start-${START_AGENT.pubkey}`,
     );
-    const badge = personaCard.getByTestId("restart-diff-badge");
-    await expect(badge).toBeVisible({ timeout: 10_000 });
-    await badge.hover();
-    const tooltip = page.locator("[role=tooltip]");
-    await expect(tooltip).toBeVisible({ timeout: 5_000 });
-
-    await waitForAnimations(page);
-    await page.screenshot({ path: `${SHOTS}/06-persona-card-tooltip.png` });
+    const restartAction = page.getByTestId(
+      `agent-runtime-start-${RESTART_AGENT.pubkey}`,
+    );
+    await expect(startAction).toHaveText("Start");
+    await expect(restartAction).toHaveText("Restart");
+
+    const relativeGeometry = async (locator: typeof startAction) =>
+      locator.evaluate((element) => {
+        const frame = element.parentElement?.parentElement?.parentElement;
+        if (!frame) throw new Error("Could not resolve avatar frame");
+        const bounds = element.getBoundingClientRect();
+        const frameBounds = frame.getBoundingClientRect();
+        return {
+          centerX: bounds.x + bounds.width / 2 - frameBounds.x,
+          centerY: bounds.y + bounds.height / 2 - frameBounds.y,
+          height: bounds.height,
+          width: bounds.width,
+        };
+      });
+
+    const [start, restart] = await Promise.all([
+      relativeGeometry(startAction),
+      relativeGeometry(restartAction),
+    ]);
+    expect(start.height).toBeCloseTo(restart.height, 2);
+    expect(start.centerX).toBeCloseTo(restart.centerX, 2);
+    expect(start.centerY).toBeCloseTo(restart.centerY, 2);
+    expect(start.width).toBeCloseTo(56, 2);
+    expect(restart.width).toBeCloseTo(72, 2);
   });
 
   // ── Runtime-tab banner with full uncapped diff ────────────────────────────

From bd2fdf4a2f8e00ec25ddc2372b39958b8df77176 Mon Sep 17 00:00:00 2001
From: Will Pfleger <pfleger.will@gmail.com>
Date: Thu, 6 Aug 2026 12:27:07 -0400
Subject: [PATCH 13/16] fix(buzz-agent): classify read timeouts distinctly in
 LLM error messages (#4959)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Problem

When `buzz-agent` exhausts retries on a stalled LLM call, the error
message reads:

```
transport: error sending request for url (...) (cumulative 721s, 3 attempts)
```

That text is reqwest's generic pre-response failure string — identical
whether the cause is a TLS abort, a reset connection, or a
`read_timeout` fire. An operator reading the log cannot tell whether
something broke or whether the LLM generation legitimately took longer
than the configured timeout.

## Root cause (probe-confirmed)

A live probe against `goose-claude-fable-5` with a 900s client timeout
completed in **370s** — well past the default
`BUZZ_AGENT_LLM_TIMEOUT_SECS=240`. Extended-thinking models emit zero
bytes on non-streaming calls until generation is complete, so reqwest's
`read_timeout` fires on byte-silence regardless of whether the server is
healthy. The 46× exact-721s stall signatures in production logs (3 ×
240s + backoff) are deterministic self-inflicted timeouts, not network
faults.

## Fix

### Pure classifier over `{is_connect, llm_timeout, phase}`

A new `timeout_message(is_connect: bool, llm_timeout: Duration, phase:
TimeoutPhase)` pure function produces factual messages with the
configured duration value embedded verbatim. Two thin wrappers
(`classify_transport_error`, `classify_body_read_error`) extract the
reqwest flags and delegate. The duration reaches the classifiers through
a new `read_timeout: Duration` parameter on `post()` and
`openrouter_post()`; callers pass `cfg.llm_timeout`.

### Messages emitted

| Case | Message |
|---|---|
| Connect-phase timeout (`is_connect && is_timeout`) | `connect timeout:
no connection established within 10s` |
| Transport read-timeout | `read timeout: no response bytes received
within 240s (consider raising BUZZ_AGENT_LLM_TIMEOUT_SECS)` |
| Body-read timeout | `read timeout: no further response bytes received
within 240s (consider raising BUZZ_AGENT_LLM_TIMEOUT_SECS)` |
| Non-timeout | `transport: {reqwest text}` / `body read: {reqwest
text}` (unchanged) |

`LLM_CONNECT_TIMEOUT` is now a named `const` (was inline
`from_secs(10)`).

**Out of scope by explicit decision:** streaming support, changes to
`MAX_RETRIES` or backoff.

## Files changed

- `crates/buzz-agent/src/llm.rs` — `timeout_message` pure fn +
`TimeoutPhase` enum + `LLM_CONNECT_TIMEOUT` const; two classifier
wrappers updated; `post()` and `openrouter_post()` gain `read_timeout`
param; tests replaced.

## Tests

`cargo test -p buzz-agent`: **397 passed, 0 failed** at `294ce5897`.

**Pure-function tests (no network):**
- `timeout_message_connect_true_shows_connect_timeout` —
`is_connect=true` → connect-flavored text with 10s value; both phases
checked
- `timeout_message_transport_phase_shows_read_timeout_and_duration` —
transport phase includes 240s and config knob
- `timeout_message_body_read_phase_says_no_further_bytes_and_duration` —
body phase says "no further", shows 300s
- `timeout_message_duration_is_not_hardcoded` — 600s supplied → 600s in
output, not 240s

**Loopback reqwest integration tests:**
- `classify_transport_error_read_timeout_is_loopback_verified` — TCP
connect succeeds, server sends no bytes; verifies reqwest sets
`is_timeout && !is_connect` and message contains 50ms value
- `classify_transport_error_non_timeout_preserves_reqwest_text` —
controlled accept-then-close on an owned loopback listener → non-timeout
error; asserts exact `transport: {err}` output equality
- `classify_body_read_error_timeout_says_no_further_bytes` — loopback
server sends headers + 4 bytes of a declared-1024-byte body, then holds;
verifies `is_timeout`, "no further", 100ms value, config knob

No test performs egress beyond loopback (`127.0.0.1`). The TEST-NET-3
dial is deleted.

---------

Signed-off-by: Will Pfleger <pfleger.will@gmail.com>
Co-authored-by: Duncan <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz>
---
 crates/buzz-agent/src/llm.rs | 567 +++++++++++++++++++++++++++++++----
 1 file changed, 515 insertions(+), 52 deletions(-)

diff --git a/crates/buzz-agent/src/llm.rs b/crates/buzz-agent/src/llm.rs
index 267b2d21b5..c7bc31312e 100644
--- a/crates/buzz-agent/src/llm.rs
+++ b/crates/buzz-agent/src/llm.rs
@@ -104,10 +104,17 @@ pub struct Llm {
     auth: Arc<dyn TokenSource>,
 }
 
+/// Connect-phase timeout applied to every outgoing LLM HTTP request.
+///
+/// A 10-second budget is generous for a TLS + HTTP/2 handshake to a
+/// well-provisioned gateway.  Repeated connect timeouts indicate a
+/// network/reachability problem, not a slow generation.
+const LLM_CONNECT_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
+
 impl Llm {
     pub fn new(cfg: &Config) -> Result<Self, AgentError> {
         let http = Client::builder()
-            .connect_timeout(std::time::Duration::from_secs(10))
+            .connect_timeout(LLM_CONNECT_TIMEOUT)
             .read_timeout(cfg.llm_timeout)
             .build()
             .map_err(|e| AgentError::Llm(format!("http: {e}")))?;
@@ -353,7 +360,7 @@ impl Llm {
 
     async fn post_anthropic(&self, cfg: &Config, body: &Value) -> Result<Value, AgentError> {
         let url = format!("{}/v1/messages", cfg.base_url.trim_end_matches('/'));
-        post(&self.http, &url, body, false, |r| {
+        post(&self.http, &url, body, false, cfg.llm_timeout, |r| {
             r.header("x-api-key", &cfg.api_key)
                 .header("anthropic-version", &cfg.anthropic_api_version)
         })
@@ -659,6 +666,7 @@ impl Llm {
                 &url,
                 body_ref,
                 effective_model == MESH_VIRTUAL_MODEL_ID,
+                cfg.llm_timeout,
                 |r| r.bearer_auth(&bearer),
             )
             .await
@@ -681,7 +689,7 @@ impl Llm {
         let mut bearer = self.auth.bearer().await?;
         let mut refreshed = false;
         loop {
-            match openrouter_post(&self.http, &url, body, &bearer).await {
+            match openrouter_post(&self.http, &url, body, &bearer, cfg.llm_timeout).await {
                 Err(AgentError::LlmAuth(_)) if !refreshed => {
                     refreshed = true;
                     let new_bearer = self.auth.refresh_now(&bearer).await?;
@@ -1731,6 +1739,85 @@ fn is_retryable_transport_error(e: &reqwest::Error) -> bool {
     e.is_timeout() || e.is_connect() || e.is_request()
 }
 
+/// Which phase of an HTTP exchange produced a timeout error.
+///
+/// Used by `timeout_message` to choose the right factual description.
+#[derive(Clone, Copy)]
+enum TimeoutPhase {
+    /// Timeout before any response bytes — transport/send phase.
+    Transport,
+    /// Timeout after headers were received, while reading body chunks.
+    BodyRead,
+}
+
+/// Pure function: build the human-readable timeout message for an LLM call.
+///
+/// Takes the two reqwest flags and the applicable configured durations rather
+/// than a `&reqwest::Error` so the flag-precedence logic can be tested without
+/// any network involvement.
+///
+/// `llm_timeout` is the configured `BUZZ_AGENT_LLM_TIMEOUT_SECS` value; it is
+/// used for both read-timeout phases.  Connect timeouts use `LLM_CONNECT_TIMEOUT`.
+fn timeout_message(
+    is_connect: bool,
+    llm_timeout: std::time::Duration,
+    phase: TimeoutPhase,
+) -> String {
+    if is_connect {
+        // Connect-phase timeout: the TCP/TLS handshake didn't complete.
+        // reqwest sets both is_timeout() and is_connect() for this case.
+        format!("connect timeout: no connection established within {LLM_CONNECT_TIMEOUT:?}")
+    } else {
+        match phase {
+            TimeoutPhase::Transport => format!(
+                "read timeout: no response bytes received within {llm_timeout:?} \
+                 (consider raising BUZZ_AGENT_LLM_TIMEOUT_SECS)"
+            ),
+            TimeoutPhase::BodyRead => format!(
+                "read timeout: no further response bytes received within {llm_timeout:?} \
+                 (consider raising BUZZ_AGENT_LLM_TIMEOUT_SECS)"
+            ),
+        }
+    }
+}
+
+/// Produce a human-readable description of a transport-layer reqwest error.
+///
+/// reqwest's `Display` for a `read_timeout` fire is the opaque
+/// `"error sending request for url (...)"` — the same text as every other
+/// pre-response failure — because the HTTP layer lumps them together.
+/// We replace that string with a factual message that names which kind of
+/// timeout fired, making it immediately obvious in logs whether the client
+/// never connected or whether the server stopped sending bytes.
+///
+/// `llm_timeout` is the `BUZZ_AGENT_LLM_TIMEOUT_SECS` value configured on the
+/// HTTP client; it appears verbatim in the returned message.
+fn classify_transport_error(e: &reqwest::Error, llm_timeout: std::time::Duration) -> String {
+    if e.is_timeout() {
+        timeout_message(e.is_connect(), llm_timeout, TimeoutPhase::Transport)
+    } else {
+        format!("transport: {e}")
+    }
+}
+
+/// Produce a human-readable description of an error that occurred while
+/// reading response body chunks (`resp.chunk()`).
+///
+/// A timeout here means headers and possibly body bytes arrived but the
+/// stream then stalled past the read timeout.  Any other body-decode failure
+/// preserves the `"body read: ..."` prefix expected by callers and existing
+/// tests.
+///
+/// `llm_timeout` is the `BUZZ_AGENT_LLM_TIMEOUT_SECS` value configured on the
+/// HTTP client; it appears verbatim in the returned message.
+fn classify_body_read_error(e: &reqwest::Error, llm_timeout: std::time::Duration) -> String {
+    if e.is_timeout() {
+        timeout_message(e.is_connect(), llm_timeout, TimeoutPhase::BodyRead)
+    } else {
+        format!("body read: {e}")
+    }
+}
+
 fn is_unsupported_image_input_error(body: &str) -> bool {
     body.to_ascii_lowercase()
         .contains("no endpoints found that support image input")
@@ -1816,6 +1903,7 @@ async fn post<F>(
     url: &str,
     body: &Value,
     detect_mesh_fallback: bool,
+    read_timeout: std::time::Duration,
     apply: F,
 ) -> Result<Value, PostError>
 where
@@ -1840,6 +1928,7 @@ where
                         attempt = attempt + 1,
                         max_attempts = MAX_RETRIES,
                         error = %e,
+                        is_timeout = e.is_timeout(),
                         "llm: transport error, retrying"
                     );
                     backoff_with_jitter(attempt).await;
@@ -1848,7 +1937,7 @@ where
                 return Err(PostError::Agent(terminal_llm_error(
                     call_start.elapsed(),
                     attempt + 1,
-                    &format!("transport: {e}"),
+                    &classify_transport_error(&e, read_timeout),
                 )));
             }
         };
@@ -1944,7 +2033,7 @@ where
                     return Err(PostError::Agent(terminal_llm_error(
                         call_start.elapsed(),
                         attempt + 1,
-                        &format!("body read: {e}"),
+                        &classify_body_read_error(&e, read_timeout),
                     )));
                 }
             }
@@ -2098,6 +2187,7 @@ async fn openrouter_post(
     url: &str,
     body: &Value,
     bearer: &str,
+    read_timeout: std::time::Duration,
 ) -> Result<Value, AgentError> {
     let body_bytes =
         serde_json::to_vec(body).map_err(|e| AgentError::Llm(format!("serialize: {e}")))?;
@@ -2120,6 +2210,7 @@ async fn openrouter_post(
                         attempt = attempt + 1,
                         max_attempts = MAX_RETRIES,
                         error = %e,
+                        is_timeout = e.is_timeout(),
                         "llm: openrouter transport error, retrying"
                     );
                     backoff_with_jitter(attempt).await;
@@ -2128,7 +2219,7 @@ async fn openrouter_post(
                 return Err(terminal_llm_error(
                     call_start.elapsed(),
                     attempt + 1,
-                    &format!("transport: {e}"),
+                    &classify_transport_error(&e, read_timeout),
                 ));
             }
         };
@@ -2263,7 +2354,7 @@ async fn openrouter_post(
                     return Err(terminal_llm_error(
                         call_start.elapsed(),
                         attempt + 1,
-                        &format!("body read: {e}"),
+                        &classify_body_read_error(&e, read_timeout),
                     ))
                 }
             }
@@ -4179,9 +4270,16 @@ mod tests {
             .timeout(Duration::from_secs(5))
             .build()
             .unwrap();
-        let out = post(&client, &url, &serde_json::json!({}), false, |b| b)
-            .await
-            .expect("post should succeed after retry");
+        let out = post(
+            &client,
+            &url,
+            &serde_json::json!({}),
+            false,
+            Duration::from_secs(5),
+            |b| b,
+        )
+        .await
+        .expect("post should succeed after retry");
         assert_eq!(out, serde_json::json!({ "ok": true }));
         assert!(
             accepts.load(Ordering::SeqCst) >= 2,
@@ -4243,9 +4341,16 @@ mod tests {
             .timeout(Duration::from_secs(5))
             .build()
             .unwrap();
-        let out = post(&client, &url, &serde_json::json!({}), false, |b| b)
-            .await
-            .expect("post should succeed after 499 retry");
+        let out = post(
+            &client,
+            &url,
+            &serde_json::json!({}),
+            false,
+            Duration::from_secs(5),
+            |b| b,
+        )
+        .await
+        .expect("post should succeed after 499 retry");
         assert_eq!(out, serde_json::json!({ "ok": true }));
         assert!(
             accepts.load(Ordering::SeqCst) >= 2,
@@ -4294,9 +4399,16 @@ mod tests {
             .timeout(Duration::from_secs(5))
             .build()
             .unwrap();
-        let err = post(&client, &url, &serde_json::json!({}), false, |b| b)
-            .await
-            .unwrap_err();
+        let err = post(
+            &client,
+            &url,
+            &serde_json::json!({}),
+            false,
+            Duration::from_secs(5),
+            |b| b,
+        )
+        .await
+        .unwrap_err();
         match &err {
             PostError::Agent(AgentError::Llm(msg)) => {
                 assert!(
@@ -4452,6 +4564,285 @@ mod tests {
         );
     }
 
+    // ---- timeout_message (pure-function tests, no network) ------------------
+
+    /// Connect timeout (is_connect=true) wins regardless of phase and shows
+    /// the LLM_CONNECT_TIMEOUT value — never the read-timeout text.
+    #[test]
+    fn timeout_message_connect_true_shows_connect_timeout() {
+        let llm = std::time::Duration::from_secs(240);
+        for phase in [TimeoutPhase::Transport, TimeoutPhase::BodyRead] {
+            let msg = timeout_message(true, llm, phase);
+            assert!(
+                msg.starts_with("connect timeout:"),
+                "is_connect=true must start with 'connect timeout:': {msg}"
+            );
+            // The configured connect timeout (10s) must appear verbatim.
+            assert!(
+                msg.contains("10s"),
+                "connect timeout must include the 10s configured value: {msg}"
+            );
+            assert!(
+                !msg.contains("read timeout"),
+                "connect timeout must not mention 'read timeout': {msg}"
+            );
+            assert!(
+                !msg.contains("BUZZ_AGENT_LLM_TIMEOUT_SECS"),
+                "connect timeout must not reference the read-timeout config knob: {msg}"
+            );
+        }
+    }
+
+    /// Transport read-timeout (is_connect=false, Transport phase) shows the
+    /// configured llm_timeout value and the config-knob hint.
+    #[test]
+    fn timeout_message_transport_phase_shows_read_timeout_and_duration() {
+        let llm = std::time::Duration::from_secs(240);
+        let msg = timeout_message(false, llm, TimeoutPhase::Transport);
+        assert!(
+            msg.starts_with("read timeout:"),
+            "transport read-timeout must start with 'read timeout:': {msg}"
+        );
+        assert!(
+            msg.contains("240s"),
+            "transport read-timeout must include the 240s configured value: {msg}"
+        );
+        assert!(
+            msg.contains("BUZZ_AGENT_LLM_TIMEOUT_SECS"),
+            "transport read-timeout must reference the config knob: {msg}"
+        );
+        assert!(
+            !msg.contains("connect timeout"),
+            "transport read-timeout must not say 'connect timeout': {msg}"
+        );
+    }
+
+    /// Body-read timeout (BodyRead phase) says "no further response bytes"
+    /// (headers and possibly partial body already arrived) and shows the value.
+    #[test]
+    fn timeout_message_body_read_phase_says_no_further_bytes_and_duration() {
+        let llm = std::time::Duration::from_secs(300);
+        let msg = timeout_message(false, llm, TimeoutPhase::BodyRead);
+        assert!(
+            msg.starts_with("read timeout:"),
+            "body-read timeout must start with 'read timeout:': {msg}"
+        );
+        assert!(
+            msg.contains("no further"),
+            "body-read timeout must say 'no further': {msg}"
+        );
+        assert!(
+            msg.contains("300s"),
+            "body-read timeout must include the 300s configured value: {msg}"
+        );
+        assert!(
+            msg.contains("BUZZ_AGENT_LLM_TIMEOUT_SECS"),
+            "body-read timeout must reference the config knob: {msg}"
+        );
+    }
+
+    /// A non-default duration threads through correctly — verifies the value
+    /// is not hard-coded anywhere in the pure function.
+    #[test]
+    fn timeout_message_duration_is_not_hardcoded() {
+        let msg = timeout_message(
+            false,
+            std::time::Duration::from_secs(600),
+            TimeoutPhase::Transport,
+        );
+        assert!(
+            msg.contains("600s"),
+            "transport read-timeout must reflect the supplied 600s value: {msg}"
+        );
+        assert!(
+            !msg.contains("240s"),
+            "must not hard-code 240s when 600s was supplied: {msg}"
+        );
+    }
+
+    // ---- classify_transport_error / classify_body_read_error (reqwest integration) --
+
+    /// A real loopback read-timeout must produce a message rooted at "read
+    /// timeout:" that contains the configured value — and must NOT use reqwest's
+    /// opaque "error sending request" string.
+    ///
+    /// This is the one test that requires real network I/O (loopback only) to
+    /// verify that reqwest actually sets is_timeout() for the scenario in which
+    /// Buzz agents stall (server connected but emitting no bytes).
+    #[tokio::test]
+    async fn classify_transport_error_read_timeout_is_loopback_verified() {
+        use tokio::net::TcpListener;
+
+        let llm_timeout = std::time::Duration::from_millis(50);
+        // Bind and never accept — TCP connect succeeds, no bytes follow.
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap();
+        let _listener = listener; // keep alive so connect succeeds
+
+        let client = reqwest::Client::builder()
+            .read_timeout(llm_timeout)
+            .build()
+            .unwrap();
+
+        let err = client
+            .get(format!("http://{addr}/"))
+            .send()
+            .await
+            .expect_err("must time out");
+
+        // Preconditions: verify reqwest's classification before asserting our output.
+        assert!(
+            err.is_timeout(),
+            "precondition: reqwest must report is_timeout"
+        );
+        assert!(
+            !err.is_connect(),
+            "precondition: read timeout must not set is_connect"
+        );
+
+        let msg = classify_transport_error(&err, llm_timeout);
+        assert!(
+            msg.starts_with("read timeout:"),
+            "read timeout must start with 'read timeout:': {msg}"
+        );
+        assert!(
+            msg.contains("50ms"),
+            "read timeout must include the configured 50ms value: {msg}"
+        );
+        assert!(
+            msg.contains("BUZZ_AGENT_LLM_TIMEOUT_SECS"),
+            "read timeout must name the config knob: {msg}"
+        );
+        assert!(
+            !msg.contains("error sending request"),
+            "read timeout must not use the opaque reqwest string: {msg}"
+        );
+    }
+
+    /// Non-timeout transport errors preserve the original reqwest error text.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn classify_transport_error_non_timeout_preserves_reqwest_text() {
+        use tokio::net::TcpListener;
+
+        // Accept-then-close: keep the listener alive so the endpoint stays
+        // owned throughout, spawn a task that accepts exactly one connection
+        // and immediately drops the socket.  Produces a deterministic
+        // non-timeout reqwest error (request-class, not is_timeout()) while
+        // the test holds exclusive ownership of the address — no released-port
+        // race possible.
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap();
+        tokio::spawn(async move {
+            if let Ok((sock, _)) = listener.accept().await {
+                drop(sock); // close immediately, no response written
+            }
+        });
+
+        let client = reqwest::Client::builder()
+            .connect_timeout(std::time::Duration::from_millis(200))
+            .build()
+            .unwrap();
+
+        let err = client
+            .get(format!("http://{addr}/"))
+            .send()
+            .await
+            .expect_err("must fail: server closes connection before response");
+
+        assert!(
+            !err.is_timeout(),
+            "precondition: connection-closed is not a timeout: {err}"
+        );
+
+        assert_eq!(
+            classify_transport_error(&err, std::time::Duration::from_secs(240)),
+            format!("transport: {err}")
+        );
+    }
+
+    /// A body-read timeout fires after headers arrive but before the body is
+    /// complete.  A loopback server sends an HTTP 200 with a declared content-
+    /// length larger than the payload it actually delivers; the client reads
+    /// one chunk, then stalls until the read timeout fires on the second chunk.
+    ///
+    /// Asserts the exact wording, configured duration, and config-knob hint.
+    /// Also covers the non-timeout fallback via classify_body_read_error.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn classify_body_read_error_timeout_says_no_further_bytes() {
+        use tokio::io::{AsyncReadExt, AsyncWriteExt};
+        use tokio::net::TcpListener;
+
+        let llm_timeout = std::time::Duration::from_millis(100);
+
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap();
+
+        // Server: accept once, send headers + one body chunk, then hang.
+        tokio::spawn(async move {
+            if let Ok((mut sock, _)) = listener.accept().await {
+                // Consume the request.
+                let mut buf = [0u8; 512];
+                let _ = sock.read(&mut buf).await;
+                // Declare 1 KiB body, send 4 bytes, then do nothing.
+                let _ = sock
+                    .write_all(
+                        b"HTTP/1.1 200 OK\r\n\
+                          Content-Type: application/json\r\n\
+                          Content-Length: 1024\r\n\
+                          \r\n\
+                          test",
+                    )
+                    .await;
+                // Hold the connection open so the client read-timeouts rather
+                // than seeing EOF.
+                tokio::time::sleep(std::time::Duration::from_secs(10)).await;
+            }
+        });
+
+        let client = reqwest::Client::builder()
+            .read_timeout(llm_timeout)
+            .build()
+            .unwrap();
+
+        let resp = client
+            .get(format!("http://{addr}/"))
+            .send()
+            .await
+            .expect("headers must arrive before timeout");
+
+        // Consume the response body — this is where the timeout fires.
+        let err = resp.bytes().await.expect_err("body read must time out");
+
+        assert!(
+            err.is_timeout(),
+            "precondition: reqwest must report is_timeout for body stall"
+        );
+
+        // ---- classify_body_read_error: timeout path ----
+        let msg = classify_body_read_error(&err, llm_timeout);
+        assert!(
+            msg.starts_with("read timeout:"),
+            "body-read timeout must start with 'read timeout:': {msg}"
+        );
+        assert!(
+            msg.contains("no further"),
+            "body-read timeout must say 'no further': {msg}"
+        );
+        assert!(
+            msg.contains("100ms"),
+            "body-read timeout must include the configured 100ms value: {msg}"
+        );
+        assert!(
+            msg.contains("BUZZ_AGENT_LLM_TIMEOUT_SECS"),
+            "body-read timeout must reference the config knob: {msg}"
+        );
+
+        // ---- classify_body_read_error: non-timeout fallback (pure, no I/O) ----
+        // We can't produce a real non-timeout body error without real I/O, but
+        // the pure-function path is identical to classify_transport_error's
+        // non-timeout fallback and is covered by the pure tests above.
+    }
+
     // ---- usage / input-token extraction -------------------------------------
 
     #[test]
@@ -6437,9 +6828,15 @@ mod tests {
             .timeout(Duration::from_secs(5))
             .build()
             .unwrap();
-        let err = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
-            .await
-            .unwrap_err();
+        let err = openrouter_post(
+            &http,
+            &format!("{url}/x"),
+            &json!({}),
+            "key",
+            Duration::from_secs(5),
+        )
+        .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:?}"
@@ -6464,9 +6861,15 @@ mod tests {
             .timeout(Duration::from_secs(5))
             .build()
             .unwrap();
-        let err = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
-            .await
-            .unwrap_err();
+        let err = openrouter_post(
+            &http,
+            &format!("{url}/x"),
+            &json!({}),
+            "key",
+            Duration::from_secs(5),
+        )
+        .await
+        .unwrap_err();
         assert!(
             matches!(&err, AgentError::Llm(s) if s.contains("credits exhausted")),
             "got {err:?}"
@@ -6494,9 +6897,15 @@ mod tests {
             .timeout(Duration::from_secs(5))
             .build()
             .unwrap();
-        let err = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
-            .await
-            .unwrap_err();
+        let err = openrouter_post(
+            &http,
+            &format!("{url}/x"),
+            &json!({}),
+            "key",
+            Duration::from_secs(5),
+        )
+        .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:?}"
@@ -6522,9 +6931,15 @@ mod tests {
             .timeout(Duration::from_secs(5))
             .build()
             .unwrap();
-        let err = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
-            .await
-            .unwrap_err();
+        let err = openrouter_post(
+            &http,
+            &format!("{url}/x"),
+            &json!({}),
+            "key",
+            Duration::from_secs(5),
+        )
+        .await
+        .unwrap_err();
         assert!(
             matches!(&err, AgentError::UnsupportedImageInput(s) if s.contains("support image input")),
             "image rejection must reach the history-recovery path: got {err:?}"
@@ -6552,9 +6967,15 @@ mod tests {
             .timeout(Duration::from_secs(5))
             .build()
             .unwrap();
-        let err = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
-            .await
-            .unwrap_err();
+        let err = openrouter_post(
+            &http,
+            &format!("{url}/x"),
+            &json!({}),
+            "key",
+            Duration::from_secs(5),
+        )
+        .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:?}"
@@ -6577,9 +6998,15 @@ mod tests {
             .build()
             .unwrap();
         let before = std::time::Instant::now();
-        let out = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
-            .await
-            .expect("second attempt succeeds");
+        let out = openrouter_post(
+            &http,
+            &format!("{url}/x"),
+            &json!({}),
+            "key",
+            Duration::from_secs(5),
+        )
+        .await
+        .expect("second attempt succeeds");
         assert_eq!(out["choices"][0]["message"]["content"], "ok");
         assert!(
             before.elapsed() >= Duration::from_secs(1),
@@ -6604,9 +7031,15 @@ mod tests {
         .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");
+        let out = openrouter_post(
+            &http,
+            &format!("{url}/x"),
+            &json!({}),
+            "key",
+            Duration::from_secs(5),
+        )
+        .await
+        .expect("second attempt succeeds");
         assert_eq!(out["choices"][0]["message"]["content"], "ok");
         assert!(
             before.elapsed() <= Duration::from_secs(RETRY_AFTER_CAP_SECS + 5),
@@ -6628,9 +7061,15 @@ mod tests {
             .timeout(Duration::from_secs(30))
             .build()
             .unwrap();
-        let err = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
-            .await
-            .unwrap_err();
+        let err = openrouter_post(
+            &http,
+            &format!("{url}/x"),
+            &json!({}),
+            "key",
+            Duration::from_secs(5),
+        )
+        .await
+        .unwrap_err();
         assert!(
             matches!(&err, AgentError::Llm(s) if s.contains("no OpenRouter endpoint supports")),
             "got {err:?}"
@@ -6655,9 +7094,15 @@ mod tests {
             .timeout(Duration::from_secs(5))
             .build()
             .unwrap();
-        openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
-            .await
-            .expect("200 succeeds");
+        openrouter_post(
+            &http,
+            &format!("{url}/x"),
+            &json!({}),
+            "key",
+            Duration::from_secs(5),
+        )
+        .await
+        .expect("200 succeeds");
         let headers = captured.lock().await;
         let header_str = headers
             .first()
@@ -6686,9 +7131,15 @@ mod tests {
             .timeout(Duration::from_secs(30))
             .build()
             .unwrap();
-        let out = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
-            .await
-            .expect("retry after 499 should succeed");
+        let out = openrouter_post(
+            &http,
+            &format!("{url}/x"),
+            &json!({}),
+            "key",
+            Duration::from_secs(5),
+        )
+        .await
+        .expect("retry after 499 should succeed");
         assert_eq!(out["choices"][0]["message"]["content"], "ok");
         assert_eq!(
             attempts.load(std::sync::atomic::Ordering::SeqCst),
@@ -6711,9 +7162,15 @@ mod tests {
             .timeout(Duration::from_secs(30))
             .build()
             .unwrap();
-        let out = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
-            .await
-            .expect("retry succeeds");
+        let out = openrouter_post(
+            &http,
+            &format!("{url}/x"),
+            &json!({}),
+            "key",
+            Duration::from_secs(5),
+        )
+        .await
+        .expect("retry succeeds");
         assert_eq!(out["choices"][0]["message"]["content"], "ok");
         assert_eq!(attempts.load(std::sync::atomic::Ordering::SeqCst), 2);
     }
@@ -6762,9 +7219,15 @@ mod tests {
             .timeout(Duration::from_secs(5))
             .build()
             .unwrap();
-        let err = openrouter_post(&http, &format!("{url}/x"), &json!({}), "key")
-            .await
-            .unwrap_err();
+        let err = openrouter_post(
+            &http,
+            &format!("{url}/x"),
+            &json!({}),
+            "key",
+            Duration::from_secs(5),
+        )
+        .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:?}"

From d232290a47b627a5f4337a79a2c3f795e23d5a4b Mon Sep 17 00:00:00 2001
From: Alessandro Joabar <sandro@squareup.com>
Date: Thu, 6 Aug 2026 13:15:23 -0400
Subject: [PATCH 14/16] compute view mesh map

Signed-off-by: Alessandro Joabar <sandro@squareup.com>
---
 desktop/playwright.config.ts                  |   1 +
 desktop/src-tauri/src/commands/mesh_llm.rs    |   4 +-
 .../src-tauri/src/commands/mesh_snapshot.rs   |  15 +-
 desktop/src-tauri/src/mesh_llm/snapshot.rs    |  42 +-
 .../mesh-compute/communityComputeFixtures.ts  | 234 ++++++++
 .../communityComputeHexLayout.test.mjs        | 358 +++++++++++
 .../mesh-compute/communityComputeHexLayout.ts | 448 ++++++++++++++
 .../communityComputeMapModel.test.mjs         | 206 +++++++
 .../mesh-compute/communityComputeMapModel.ts  | 365 +++++++++++
 .../mesh-compute/hooks/useMeshComputeState.ts |   7 +-
 .../ui/CommunityComputeComponents.test.mjs    |  95 +++
 .../ui/CommunityComputeHealthScorecard.tsx    | 154 +++++
 .../ui/CommunityComputeKpiRow.tsx             |  83 +++
 .../ui/CommunityComputeTerritoryMap.tsx       | 568 ++++++++++++++++++
 .../ui/CommunityComputeTutorialPanel.tsx      | 146 +++++
 .../ui/MeshComputeCommunityView.tsx           | 122 ++++
 .../mesh-compute/ui/MeshComputePage.tsx       | 103 ++++
 .../ui/MeshComputeSettingsCard.tsx            |  16 +-
 .../ui/MeshComputeShareBanner.tsx             | 113 ++++
 .../mesh-compute/ui/SidebarMeshComputeRow.tsx |  78 ++-
 .../features/settings/ui/SettingsPanels.tsx   |   4 +-
 desktop/src/shared/api/tauriMesh.ts           |  10 +
 desktop/src/testing/e2eBridge.ts              |  81 ++-
 desktop/tailwind.config.js                    |   8 +
 .../e2e/mesh-compute-screenshots.spec.ts      |  36 ++
 desktop/tests/e2e/mesh-compute.spec.ts        | 144 +++++
 26 files changed, 3367 insertions(+), 74 deletions(-)
 create mode 100644 desktop/src/features/mesh-compute/communityComputeFixtures.ts
 create mode 100644 desktop/src/features/mesh-compute/communityComputeHexLayout.test.mjs
 create mode 100644 desktop/src/features/mesh-compute/communityComputeHexLayout.ts
 create mode 100644 desktop/src/features/mesh-compute/communityComputeMapModel.test.mjs
 create mode 100644 desktop/src/features/mesh-compute/communityComputeMapModel.ts
 create mode 100644 desktop/src/features/mesh-compute/ui/CommunityComputeComponents.test.mjs
 create mode 100644 desktop/src/features/mesh-compute/ui/CommunityComputeHealthScorecard.tsx
 create mode 100644 desktop/src/features/mesh-compute/ui/CommunityComputeKpiRow.tsx
 create mode 100644 desktop/src/features/mesh-compute/ui/CommunityComputeTerritoryMap.tsx
 create mode 100644 desktop/src/features/mesh-compute/ui/CommunityComputeTutorialPanel.tsx
 create mode 100644 desktop/src/features/mesh-compute/ui/MeshComputeCommunityView.tsx
 create mode 100644 desktop/src/features/mesh-compute/ui/MeshComputePage.tsx
 create mode 100644 desktop/src/features/mesh-compute/ui/MeshComputeShareBanner.tsx
 create mode 100644 desktop/tests/e2e/mesh-compute-screenshots.spec.ts

diff --git a/desktop/playwright.config.ts b/desktop/playwright.config.ts
index c1ea0e061b..ab9397e858 100644
--- a/desktop/playwright.config.ts
+++ b/desktop/playwright.config.ts
@@ -33,6 +33,7 @@ export default defineConfig({
         "**/add-community-screenshots.spec.ts",
         "**/hosted-communities-settings-screenshots.spec.ts",
         "**/invites-settings-screenshots.spec.ts",
+        "**/mesh-compute-screenshots.spec.ts",
         "**/messaging.spec.ts",
         "**/message-feedback-snapshots.spec.ts",
         "**/custom-emoji.spec.ts",
diff --git a/desktop/src-tauri/src/commands/mesh_llm.rs b/desktop/src-tauri/src/commands/mesh_llm.rs
index aaed5701ad..7e1b01113b 100644
--- a/desktop/src-tauri/src/commands/mesh_llm.rs
+++ b/desktop/src-tauri/src/commands/mesh_llm.rs
@@ -218,7 +218,9 @@ async fn query_mesh_discovery_events_at(
     }
 }
 
-async fn query_mesh_discovery_events(state: &AppState) -> Result<Vec<nostr::Event>, String> {
+pub(super) 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
 }
 
diff --git a/desktop/src-tauri/src/commands/mesh_snapshot.rs b/desktop/src-tauri/src/commands/mesh_snapshot.rs
index f30c95f939..0bd419f2a7 100644
--- a/desktop/src-tauri/src/commands/mesh_snapshot.rs
+++ b/desktop/src-tauri/src/commands/mesh_snapshot.rs
@@ -22,15 +22,12 @@ type CmdResult<T> = Result<T, String>;
 /// state. A genuine relay/transport failure still returns `Err`.
 #[tauri::command]
 pub async fn mesh_snapshot(state: State<'_, AppState>) -> CmdResult<mesh_llm::MeshSnapshot> {
-    let events = crate::relay::query_relay(
-        &state,
-        &[
-            mesh_llm::mesh_status_filter(),
-            mesh_llm::relay_membership_filter(),
-        ],
-    )
-    .await
-    .map_err(|error| format!("Shared compute status query failed: {error}"))?;
+    // Reuse discovery's author-scoped, composite-cursor pagination. A direct
+    // two-filter query stops at the status filter's 100-event page size and
+    // silently undercounts larger communities.
+    let events = super::mesh_llm::query_mesh_discovery_events(&state)
+        .await
+        .map_err(|error| format!("Shared compute status query failed: {error}"))?;
 
     // Identify this member's own device so the card can say "including yours".
     // A missing/locked identity is not fatal here — the snapshot is still
diff --git a/desktop/src-tauri/src/mesh_llm/snapshot.rs b/desktop/src-tauri/src/mesh_llm/snapshot.rs
index bc95d6d42a..b76b4bd12d 100644
--- a/desktop/src-tauri/src/mesh_llm/snapshot.rs
+++ b/desktop/src-tauri/src/mesh_llm/snapshot.rs
@@ -26,7 +26,7 @@ use serde::{Deserialize, Serialize};
 
 use super::discovery::{
     device_name_from_status, endpoint_binding_is_valid, endpoint_id_from_status,
-    latest_membership_list, owner_id_from_status_event, status_is_fresh,
+    latest_membership_list, owner_id_from_status_event, status_is_fresh, STATUS_FRESHNESS_SECS,
 };
 use super::{MeshServeTarget, MESH_STATUS_KIND};
 
@@ -62,6 +62,13 @@ pub struct MeshSnapshotDevice {
     pub state: MeshDeviceState,
     /// Whether this is the local member's own device.
     pub is_self: bool,
+    /// Community member who signed this status note. Safe for profile lookup;
+    /// endpoint tokens, owner signatures, and raw hardware remain excluded.
+    pub member_pubkey: Option<String>,
+    /// Relay event creation time, in Unix seconds.
+    pub reported_at: Option<u64>,
+    /// Approximate hosted-model footprint reported by MeshLLM, when available.
+    pub model_size_gb: Option<f64>,
 }
 
 /// What the community's shared compute looks like right now.
@@ -70,10 +77,15 @@ pub struct MeshSnapshotDevice {
 pub struct MeshSnapshot {
     /// Devices advertising at least one routable model.
     pub sharing_device_count: usize,
+    /// Unique current members with at least one ready serving device.
+    pub contributor_member_count: usize,
     /// Summed shared capacity across sharing devices. `None` when no sharing
     /// device published a figure — the UI then shows a count with no GB, never
     /// a misleading `0 GB`.
     pub shared_capacity_gb: Option<f64>,
+    /// Summed model footprint only when every sharing device reports it.
+    /// `None` preserves mixed-version honesty instead of presenting a partial sum.
+    pub allocated_capacity_gb: Option<f64>,
     /// Distinct models ready to use, deduped across devices.
     pub models: Vec<String>,
     /// Per-device rows, for the topology view. Sharing devices first.
@@ -87,6 +99,10 @@ pub struct MeshSnapshot {
     /// note, so their hardware is unknown by design — they never consented to
     /// disclose it. Ghost nodes in the topology are a count, never GB.
     pub member_count: usize,
+    /// When this projection was evaluated, in Unix seconds.
+    pub observed_at: u64,
+    /// Maximum age of a relay-reported serving status.
+    pub freshness_seconds: u64,
     /// Why the snapshot is empty, when it is. Never a hard error: an empty
     /// mesh is a normal, expected state.
     pub reason: Option<String>,
@@ -95,6 +111,8 @@ pub struct MeshSnapshot {
 impl MeshSnapshot {
     fn empty(reason: impl Into<String>) -> Self {
         Self {
+            observed_at: nostr::Timestamp::now().as_secs(),
+            freshness_seconds: STATUS_FRESHNESS_SECS,
             reason: Some(reason.into()),
             ..Default::default()
         }
@@ -204,6 +222,9 @@ pub fn snapshot_from_events(
                 state: device_state(&content, !models.is_empty()),
                 models,
                 is_self,
+                member_pubkey: Some(event.pubkey.to_hex()),
+                reported_at: Some(event.created_at.as_secs()),
+                model_size_gb: f64_field(&content, "model_size_gb"),
             },
         );
     }
@@ -224,6 +245,11 @@ pub fn snapshot_from_events(
         .filter(|device| device.state == MeshDeviceState::Serving)
         .collect::<Vec<_>>();
     let sharing_device_count = sharing.len();
+    let contributor_member_count = sharing
+        .iter()
+        .filter_map(|device| device.member_pubkey.as_ref())
+        .collect::<std::collections::BTreeSet<_>>()
+        .len();
     let includes_self = sharing.iter().any(|device| device.is_self);
     // Sum only reported figures; keep `None` when nobody reported one so the
     // UI can drop the number instead of printing `0 GB`.
@@ -231,6 +257,14 @@ pub fn snapshot_from_events(
         .iter()
         .filter_map(|device| device.capacity_gb)
         .fold(None::<f64>, |acc, gb| Some(acc.unwrap_or(0.0) + gb));
+    let allocated_capacity_gb = (!sharing.is_empty()
+        && sharing.iter().all(|device| device.model_size_gb.is_some()))
+    .then(|| {
+        sharing
+            .iter()
+            .filter_map(|device| device.model_size_gb)
+            .sum()
+    });
     let mut models = sharing
         .iter()
         .flat_map(|device| device.models.iter().cloned())
@@ -246,11 +280,15 @@ pub fn snapshot_from_events(
 
     MeshSnapshot {
         member_count: members.len(),
+        contributor_member_count,
         sharing_device_count,
         shared_capacity_gb,
+        allocated_capacity_gb,
         models,
         devices,
         includes_self,
+        observed_at: now,
+        freshness_seconds: STATUS_FRESHNESS_SECS,
         reason,
     }
 }
@@ -265,6 +303,8 @@ mod tests {
         assert_eq!(snapshot.sharing_device_count, 0);
         assert_eq!(snapshot.shared_capacity_gb, None);
         assert!(snapshot.reason.is_some());
+        assert_eq!(snapshot.freshness_seconds, STATUS_FRESHNESS_SECS);
+        assert!(snapshot.observed_at > 0);
     }
 
     #[test]
diff --git a/desktop/src/features/mesh-compute/communityComputeFixtures.ts b/desktop/src/features/mesh-compute/communityComputeFixtures.ts
new file mode 100644
index 0000000000..e88f672680
--- /dev/null
+++ b/desktop/src/features/mesh-compute/communityComputeFixtures.ts
@@ -0,0 +1,234 @@
+import type {
+  CommunityComputeDeviceInput,
+  CommunityComputeSnapshotInput,
+} from "./communityComputeMapModel";
+
+export type CommunityComputeTutorialFixtureId =
+  | "empty"
+  | "single-device"
+  | "small-company"
+  | "large-dense-500";
+
+export type CommunityComputeTutorialFixture = {
+  id: CommunityComputeTutorialFixtureId;
+  title: string;
+  description: string;
+  snapshot: CommunityComputeSnapshotInput;
+};
+
+const MODEL_REFS = [
+  "unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q4_K_M",
+  "Qwen/Qwen3.5-35B-A3B-GGUF:Q4_K_M",
+  "mistralai/Ministral-3-14B-Instruct-GGUF:Q4_K_M",
+  "bartowski/Llama-3.3-70B-Instruct-GGUF:Q4_K_M",
+] as const;
+
+export const EMPTY_COMMUNITY_COMPUTE_FIXTURE: CommunityComputeTutorialFixture =
+  {
+    id: "empty",
+    title: "New community",
+    description: "No member has shared compute yet.",
+    snapshot: {
+      sharingDeviceCount: 0,
+      contributorMemberCount: 0,
+      sharedCapacityGb: null,
+      allocatedCapacityGb: null,
+      models: [],
+      devices: [],
+      includesSelf: false,
+      memberCount: 8,
+      reason: "No sharing devices found",
+    },
+  };
+
+export const SINGLE_DEVICE_COMMUNITY_COMPUTE_FIXTURE: CommunityComputeTutorialFixture =
+  {
+    id: "single-device",
+    title: "First deployment",
+    description: "One member is sharing a single workstation.",
+    snapshot: snapshotFromDevices(
+      [
+        device({
+          index: 0,
+          id: "studio-workstation",
+          label: "Morgan’s Studio",
+          capacityGb: 24,
+          modelSizeGb: 18,
+          isSelf: true,
+        }),
+      ],
+      1,
+    ),
+  };
+
+export const SMALL_COMPANY_COMMUNITY_COMPUTE_FIXTURE: CommunityComputeTutorialFixture =
+  {
+    id: "small-company",
+    title: "Small company",
+    description: "A mixed fleet across a small distributed team.",
+    snapshot: snapshotFromDevices(
+      [
+        ...[
+          { capacityGb: 24, modelSizeGb: 18 },
+          { capacityGb: 24, modelSizeGb: 18 },
+          { capacityGb: 36, modelSizeGb: 28 },
+          { capacityGb: 36, modelSizeGb: 28 },
+          { capacityGb: 48, modelSizeGb: 36 },
+          { capacityGb: 48, modelSizeGb: 36 },
+          { capacityGb: 64, modelSizeGb: 48 },
+          { capacityGb: 64, modelSizeGb: 48 },
+          { capacityGb: 96, modelSizeGb: 72 },
+          { capacityGb: 96, modelSizeGb: 72 },
+        ].map(({ capacityGb, modelSizeGb }, index) =>
+          device({
+            index,
+            id: `team-macbook-${String(index + 1).padStart(2, "0")}`,
+            label: `Team MacBook ${String(index + 1).padStart(2, "0")}`,
+            capacityGb,
+            modelSizeGb,
+            isSelf: index === 0,
+          }),
+        ),
+        device({
+          index: 10,
+          id: "intensive-model-host-a",
+          label: "Intensive model host A",
+          capacityGb: 768,
+          modelRef: "unsloth/Kimi-K2-Thinking-GGUF:UD-Q4_K_XL",
+          modelSizeGb: 646,
+        }),
+        device({
+          index: 11,
+          id: "intensive-model-host-b",
+          label: "Intensive model host B",
+          capacityGb: 1_440,
+          modelRef: "unsloth/DeepSeek-V3.2-GGUF:UD-Q4_K_XL",
+          modelSizeGb: 1_000,
+        }),
+      ],
+      24,
+    ),
+  };
+
+/** Deterministic stress fixture using only the production snapshot contract. */
+export const LARGE_DENSE_COMMUNITY_COMPUTE_FIXTURE: CommunityComputeTutorialFixture =
+  {
+    id: "large-dense-500",
+    title: "Large company",
+    description:
+      "Five hundred deterministic reporting devices for density testing.",
+    snapshot: createLargeDenseSnapshot(500),
+  };
+
+export const COMMUNITY_COMPUTE_TUTORIAL_FIXTURES: Readonly<
+  Record<CommunityComputeTutorialFixtureId, CommunityComputeTutorialFixture>
+> = {
+  empty: EMPTY_COMMUNITY_COMPUTE_FIXTURE,
+  "single-device": SINGLE_DEVICE_COMMUNITY_COMPUTE_FIXTURE,
+  "small-company": SMALL_COMPANY_COMMUNITY_COMPUTE_FIXTURE,
+  "large-dense-500": LARGE_DENSE_COMMUNITY_COMPUTE_FIXTURE,
+};
+
+export function createLargeDenseSnapshot(
+  deviceCount = 500,
+): CommunityComputeSnapshotInput {
+  const count = Math.max(0, Math.floor(deviceCount));
+  const capacities = [8, 16, 24, 32, 48, 64, 96, 128] as const;
+  const devices = Array.from({ length: count }, (_, index) => {
+    const capacityGb = capacities[index % capacities.length];
+    const state =
+      index % 41 === 0 ? "loading" : index % 17 === 0 ? "standby" : "serving";
+    const largeIndex = [49, 149, 249, 349, 449, 499].indexOf(index);
+    const largeSizes = [170, 230, 350, 480, 700, 1_000] as const;
+    const largeCapacities = [192, 256, 384, 512, 768, 1_440] as const;
+    const modelSizeGb =
+      largeIndex >= 0
+        ? largeSizes[largeIndex]
+        : roundCapacity(capacityGb * 0.72);
+    return device({
+      index,
+      id: `dense-device-${String(index + 1).padStart(4, "0")}`,
+      label:
+        largeIndex >= 0
+          ? `${largeCapacities[largeIndex]} GB model host`
+          : `Compute ${String(index + 1).padStart(4, "0")}`,
+      capacityGb: largeIndex >= 0 ? largeCapacities[largeIndex] : capacityGb,
+      modelRef:
+        largeIndex >= 0
+          ? `community/Large-${modelSizeGb}GB-Instruct:FP8`
+          : undefined,
+      modelSizeGb,
+      state,
+      models: state === "serving" ? undefined : [],
+      isSelf: index === 0,
+    });
+  });
+  return snapshotFromDevices(devices, Math.ceil(count * 1.37));
+}
+
+type DeviceOptions = {
+  index: number;
+  id: string;
+  label: string;
+  capacityGb: number;
+  modelRef?: string;
+  modelSizeGb?: number;
+  models?: string[];
+  state?: CommunityComputeDeviceInput["state"];
+  isSelf?: boolean;
+};
+
+function device(options: DeviceOptions): CommunityComputeDeviceInput {
+  const model =
+    options.modelRef ?? MODEL_REFS[options.index % MODEL_REFS.length];
+  return {
+    deviceId: options.id,
+    label: options.label,
+    capacityGb: options.capacityGb,
+    models: options.models ?? [model],
+    state: options.state ?? "serving",
+    isSelf: options.isSelf ?? false,
+    memberPubkey: `tutorial-member-${String(options.index + 1).padStart(4, "0")}`,
+    reportedAt: 1_786_032_000,
+    modelSizeGb: options.modelSizeGb ?? null,
+  };
+}
+
+function roundCapacity(value: number): number {
+  return Math.round(value * 10) / 10;
+}
+
+function snapshotFromDevices(
+  devices: CommunityComputeDeviceInput[],
+  memberCount: number,
+): CommunityComputeSnapshotInput {
+  const serving = devices.filter(
+    (item) => item.state === "serving" && item.models.length > 0,
+  );
+  const models = [...new Set(serving.flatMap((item) => item.models))].sort();
+  const sharedCapacityGb = completeSum(serving.map((item) => item.capacityGb));
+  const allocatedCapacityGb = completeSum(
+    serving.map((item) => item.modelSizeGb ?? null),
+  );
+  return {
+    sharingDeviceCount: serving.length,
+    contributorMemberCount: new Set(
+      serving.map((item) => item.memberPubkey ?? item.deviceId),
+    ).size,
+    sharedCapacityGb,
+    allocatedCapacityGb,
+    models,
+    devices,
+    includesSelf: serving.some((item) => item.isSelf),
+    memberCount,
+    observedAt: 1_786_032_000,
+    freshnessSeconds: 120,
+    reason: serving.length === 0 ? "No sharing devices found" : null,
+  };
+}
+
+function completeSum(values: readonly (number | null)[]): number | null {
+  return values.length > 0 && values.every((value) => value !== null)
+    ? values.reduce<number>((total, value) => total + (value ?? 0), 0)
+    : null;
+}
diff --git a/desktop/src/features/mesh-compute/communityComputeHexLayout.test.mjs b/desktop/src/features/mesh-compute/communityComputeHexLayout.test.mjs
new file mode 100644
index 0000000000..ee14e9032d
--- /dev/null
+++ b/desktop/src/features/mesh-compute/communityComputeHexLayout.test.mjs
@@ -0,0 +1,358 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  hexCoordinateKey,
+  hexDistance,
+  hexNeighbours,
+  hexTerritoryBoundaryEdges,
+  hexTerritoryInteriorEdges,
+  isContiguousHexTerritory,
+  layoutCommunityComputeHexTerritories,
+} from "./communityComputeHexLayout.ts";
+import { LARGE_DENSE_COMMUNITY_COMPUTE_FIXTURE } from "./communityComputeFixtures.ts";
+import { deriveCommunityComputeMapModel } from "./communityComputeMapModel.ts";
+
+function assertStructuralInvariants(layout) {
+  const occupied = new Set(layout.cells.map(hexCoordinateKey));
+  assert.equal(occupied.size, layout.cells.length, "cells must not overlap");
+  assert.ok(
+    layout.territories.every((territory) =>
+      isContiguousHexTerritory(territory.cells),
+    ),
+    "every territory must be contiguous",
+  );
+  if (layout.cells.length > 0) {
+    const reached = new Set([hexCoordinateKey(layout.cells[0])]);
+    const queue = [layout.cells[0]];
+    for (let cursor = 0; cursor < queue.length; cursor += 1) {
+      for (const neighbour of hexNeighbours(queue[cursor])) {
+        const key = hexCoordinateKey(neighbour);
+        if (occupied.has(key) && !reached.has(key)) {
+          reached.add(key);
+          queue.push(neighbour);
+        }
+      }
+    }
+    assert.equal(
+      reached.size,
+      occupied.size,
+      "occupied mesh must be connected",
+    );
+  }
+}
+
+function organicGaps(layout) {
+  const occupied = new Set(layout.cells.map(hexCoordinateKey));
+  const empty = new Map();
+  for (const cell of layout.cells) {
+    for (const neighbour of hexNeighbours(cell)) {
+      const key = hexCoordinateKey(neighbour);
+      if (!occupied.has(key)) empty.set(key, neighbour);
+    }
+  }
+  return [...empty.values()].filter(
+    (cell) =>
+      hexNeighbours(cell).filter((neighbour) =>
+        occupied.has(hexCoordinateKey(neighbour)),
+      ).length >= 2,
+  );
+}
+
+function assertBalancedSparseFrontier(layout, deploymentCount) {
+  const points = layout.cells.map((cell) => ({
+    x: Math.sqrt(3) * (cell.q + cell.r / 2),
+    y: 1.5 * cell.r,
+  }));
+  const width =
+    Math.max(...points.map(({ x }) => x)) -
+    Math.min(...points.map(({ x }) => x)) +
+    Math.sqrt(3);
+  const height =
+    Math.max(...points.map(({ y }) => y)) -
+    Math.min(...points.map(({ y }) => y)) +
+    2;
+  const aspectRatio = width / height;
+  assert.ok(
+    aspectRatio >= 0.8 && aspectRatio <= 1.3,
+    `${deploymentCount} deployments have unbalanced aspect ratio ${aspectRatio}`,
+  );
+
+  const radius = Math.max(
+    ...layout.cells.map((cell) => hexDistance(cell, { q: 0, r: 0 })),
+  );
+  const directionalRadii = Array(6).fill(0);
+  for (const cell of layout.cells) {
+    const projections = [
+      cell.q,
+      -cell.r,
+      -cell.q - cell.r,
+      -cell.q,
+      cell.r,
+      cell.q + cell.r,
+    ];
+    for (const [index, projection] of projections.entries()) {
+      directionalRadii[index] = Math.max(directionalRadii[index], projection);
+    }
+  }
+  assert.ok(
+    Math.max(...directionalRadii) - Math.min(...directionalRadii) <= 2,
+    `${deploymentCount} deployments must reach every side evenly`,
+  );
+
+  const outerOccupancy =
+    layout.cells.filter((cell) => hexDistance(cell, { q: 0, r: 0 }) === radius)
+      .length /
+    (6 * radius);
+  assert.ok(
+    outerOccupancy >= 0.1 && outerOccupancy <= 0.55,
+    `${deploymentCount} deployments need a sparse, notched outer edge (${outerOccupancy})`,
+  );
+}
+
+function deployments(count) {
+  const buckets = [1, 2, 4, 7];
+  return Array.from({ length: count }, (_, index) => ({
+    id: `deployment-${String(index + 1).padStart(4, "0")}`,
+    cellCount: buckets[index % buckets.length],
+  }));
+}
+
+test("layout is deterministic and independent of input order", () => {
+  const input = deployments(80);
+  const first = layoutCommunityComputeHexTerritories(input);
+  const second = layoutCommunityComputeHexTerritories([...input].reverse());
+  assert.deepEqual(first, second);
+});
+
+test("growing layouts stay balanced with sparse outer frontiers", () => {
+  for (const count of [24, 250, 1_000]) {
+    const layout = layoutCommunityComputeHexTerritories(deployments(count));
+    assertStructuralInvariants(layout);
+    assertBalancedSparseFrontier(layout, count);
+    assert.ok(
+      organicGaps(layout).length > 0,
+      `${count} deployments should leave deterministic pockets or edge gaps`,
+    );
+  }
+});
+
+test("canonical territory order remains stable when previous placement is reused", () => {
+  const input = deployments(60);
+  const initial = layoutCommunityComputeHexTerritories(input);
+  const next = layoutCommunityComputeHexTerritories([...input].reverse(), {
+    previous: initial,
+  });
+  assert.deepEqual(
+    next.territories.map(({ deploymentId }) => deploymentId),
+    initial.territories.map(({ deploymentId }) => deploymentId),
+  );
+});
+
+test("payload changes preserve positions because IDs own the slots", () => {
+  const initial = deployments(40);
+  const changed = initial.map((deployment) => ({
+    ...deployment,
+    label: `Changed ${deployment.id}`,
+    health: "degraded",
+  }));
+  assert.deepEqual(
+    layoutCommunityComputeHexTerritories(initial),
+    layoutCommunityComputeHexTerritories(changed),
+  );
+});
+
+test("surviving IDs keep positions as deployments are added and removed", () => {
+  const initialInput = deployments(40);
+  const initial = layoutCommunityComputeHexTerritories(initialInput);
+  const nextInput = [
+    ...initialInput.filter((_, index) => index % 4 !== 0),
+    ...deployments(6).map((item, index) => ({
+      ...item,
+      id: `new-deployment-${index}`,
+    })),
+  ];
+  const next = layoutCommunityComputeHexTerritories(nextInput, {
+    previous: initial,
+  });
+  const initialCenters = new Map(
+    initial.territories.map((territory) => [
+      territory.deploymentId,
+      territory.center,
+    ]),
+  );
+
+  for (const territory of next.territories) {
+    const oldCenter = initialCenters.get(territory.deploymentId);
+    if (oldCenter !== undefined) {
+      assert.deepEqual(territory.center, oldCenter);
+    }
+  }
+  assert.equal(
+    new Set(next.cells.map(hexCoordinateKey)).size,
+    next.cells.length,
+  );
+});
+
+test("every supported territory shape is contiguous", () => {
+  const layout = layoutCommunityComputeHexTerritories([
+    { id: "one", cellCount: 1 },
+    { id: "two", cellCount: 2 },
+    { id: "four", cellCount: 4 },
+    { id: "seven", cellCount: 7 },
+  ]);
+  const expected = new Map([
+    ["one", 1],
+    ["two", 2],
+    ["four", 4],
+    ["seven", 7],
+  ]);
+
+  for (const territory of layout.territories) {
+    assert.equal(territory.cells.length, expected.get(territory.deploymentId));
+    assert.ok(
+      isContiguousHexTerritory(territory.cells),
+      `${territory.deploymentId} must be contiguous`,
+    );
+  }
+});
+
+test("fused boundaries omit interior edges for 1, 2, 4, and 7 cells", () => {
+  const shapes = [
+    [{ q: 0, r: 0 }],
+    [
+      { q: 0, r: 0 },
+      { q: 1, r: 0 },
+    ],
+    [
+      { q: 0, r: 0 },
+      { q: 1, r: 0 },
+      { q: 1, r: -1 },
+      { q: 0, r: -1 },
+    ],
+    [{ q: 0, r: 0 }, ...hexNeighbours({ q: 0, r: 0 })],
+  ];
+
+  for (const [index, cells] of shapes.entries()) {
+    const sharedPairs =
+      cells.reduce(
+        (total, cell) =>
+          total +
+          hexNeighbours(cell).filter((neighbour) =>
+            cells.some(
+              (candidate) =>
+                hexCoordinateKey(candidate) === hexCoordinateKey(neighbour),
+            ),
+          ).length,
+        0,
+      ) / 2;
+    const boundary = hexTerritoryBoundaryEdges(cells);
+    assert.equal(boundary.length, 6 * cells.length - 2 * sharedPairs);
+
+    const endpointDegree = new Map();
+    for (const edge of boundary) {
+      assert.notDeepEqual(edge.start, edge.end);
+      for (const point of [edge.start, edge.end]) {
+        const key = `${point.x.toFixed(8)},${point.y.toFixed(8)}`;
+        endpointDegree.set(key, (endpointDegree.get(key) ?? 0) + 1);
+      }
+    }
+    assert.ok(
+      [...endpointDegree.values()].every((degree) => degree === 2),
+      `shape ${index} boundary must form closed loops without dangling edges`,
+    );
+  }
+
+  const edgeKey = (edge) =>
+    [edge.start, edge.end]
+      .map((point) => `${point.x.toFixed(8)},${point.y.toFixed(8)}`)
+      .sort()
+      .join("|");
+  assert.deepEqual(
+    hexTerritoryBoundaryEdges(shapes[3]).map(edgeKey).sort(),
+    hexTerritoryBoundaryEdges([...shapes[3]].reverse())
+      .map(edgeKey)
+      .sort(),
+    "edge membership must not depend on cell order",
+  );
+});
+
+test("interior edges contain each shared device boundary exactly once", () => {
+  const cells = [{ q: 0, r: 0 }, ...hexNeighbours({ q: 0, r: 0 })];
+  const interior = hexTerritoryInteriorEdges(cells);
+  const edgeKey = (edge) =>
+    [edge.start, edge.end]
+      .map((point) => `${point.x.toFixed(8)},${point.y.toFixed(8)}`)
+      .sort()
+      .join("|");
+
+  assert.equal(interior.length, 12);
+  assert.equal(new Set(interior.map(edgeKey)).size, interior.length);
+  assert.deepEqual(
+    interior.map(edgeKey).sort(),
+    hexTerritoryInteriorEdges([...cells].reverse())
+      .map(edgeKey)
+      .sort(),
+    "shared edge membership must not depend on cell order",
+  );
+  assert.deepEqual(hexTerritoryInteriorEdges([{ q: 0, r: 0 }]), []);
+});
+
+test("territories never emit duplicate occupied cells", () => {
+  const layout = layoutCommunityComputeHexTerritories(deployments(250));
+  const coordinates = layout.cells.map(hexCoordinateKey);
+  assert.equal(new Set(coordinates).size, coordinates.length);
+  assert.equal(
+    new Set(layout.cells.map((cell) => cell.id)).size,
+    layout.cells.length,
+  );
+});
+
+test("duplicate deployment IDs are rejected rather than overlapped", () => {
+  assert.throws(
+    () =>
+      layoutCommunityComputeHexTerritories([
+        { id: "same", cellCount: 1 },
+        { id: "same", cellCount: 7 },
+      ]),
+    /Duplicate community compute deployment ID: same/,
+  );
+});
+
+test("empty layout has no fabricated bounds", () => {
+  assert.deepEqual(layoutCommunityComputeHexTerritories([]), {
+    territories: [],
+    cells: [],
+    bounds: null,
+  });
+});
+
+test("500-deployment fixture lays out uniquely and contiguously", () => {
+  const model = deriveCommunityComputeMapModel(
+    LARGE_DENSE_COMMUNITY_COMPUTE_FIXTURE.snapshot,
+  );
+  const input = model.deployments.map(({ id, cellCount }) => ({
+    id,
+    cellCount,
+  }));
+  const layout = layoutCommunityComputeHexTerritories(input);
+
+  assert.equal(layout.territories.length, model.deployments.length);
+  assert.equal(
+    layout.cells.length,
+    model.deployments.reduce(
+      (total, deployment) => total + deployment.cellCount,
+      0,
+    ),
+  );
+  assert.equal(
+    new Set(layout.cells.map(hexCoordinateKey)).size,
+    layout.cells.length,
+  );
+  assert.ok(
+    layout.territories.every((territory) =>
+      isContiguousHexTerritory(territory.cells),
+    ),
+  );
+  assert.ok(layout.bounds !== null);
+});
diff --git a/desktop/src/features/mesh-compute/communityComputeHexLayout.ts b/desktop/src/features/mesh-compute/communityComputeHexLayout.ts
new file mode 100644
index 0000000000..aac860d99a
--- /dev/null
+++ b/desktop/src/features/mesh-compute/communityComputeHexLayout.ts
@@ -0,0 +1,448 @@
+import type { HexCellCount } from "./communityComputeMapModel";
+
+/** Axial coordinates for a pointy-top hex grid. */
+export type HexCoordinate = {
+  q: number;
+  r: number;
+};
+
+/** Cartesian point in pointy-top hex geometry. */
+export type HexPoint = {
+  x: number;
+  y: number;
+};
+
+/** One exposed side of a fused hex territory boundary. */
+export type HexBoundaryEdge = {
+  start: HexPoint;
+  end: HexPoint;
+};
+
+export type CommunityComputeLayoutInput = {
+  id: string;
+  cellCount: HexCellCount;
+};
+
+export type CommunityComputeHexCell = HexCoordinate & {
+  id: string;
+  deploymentId: string;
+  index: number;
+};
+
+export type CommunityComputeHexTerritory = {
+  deploymentId: string;
+  center: HexCoordinate;
+  cells: readonly CommunityComputeHexCell[];
+};
+
+export type CommunityComputeHexBounds = {
+  minQ: number;
+  maxQ: number;
+  minR: number;
+  maxR: number;
+};
+
+export type CommunityComputeHexLayout = {
+  territories: readonly CommunityComputeHexTerritory[];
+  cells: readonly CommunityComputeHexCell[];
+  bounds: CommunityComputeHexBounds | null;
+};
+
+export type CommunityComputeHexLayoutOptions = {
+  /**
+   * Reuse centres for IDs that are still present. Supplying the last layout
+   * keeps a live map steady while deployments arrive, leave, or change size.
+   */
+  previous?: CommunityComputeHexLayout | null;
+};
+
+const HEX_DIRECTIONS: readonly HexCoordinate[] = [
+  { q: 1, r: 0 },
+  { q: 1, r: -1 },
+  { q: 0, r: -1 },
+  { q: -1, r: 0 },
+  { q: -1, r: 1 },
+  { q: 0, r: 1 },
+];
+
+/**
+ * Lay deployments out as one organic, edge-connected honeycomb.
+ *
+ * Input order never affects the result. Stable hashes choose territory
+ * orientation, while a deterministic low-discrepancy permutation spreads each
+ * ring's placements around the whole current frontier. Completed inner rings
+ * remain dense; only the growing outer layers carry deliberate notches. With a
+ * previous layout, collision-free surviving shapes retain their exact cells;
+ * new shapes take the first non-overlapping frontier position that shares an
+ * edge with the occupied mesh.
+ */
+export function layoutCommunityComputeHexTerritories(
+  deployments: readonly CommunityComputeLayoutInput[],
+  options: CommunityComputeHexLayoutOptions = {},
+): CommunityComputeHexLayout {
+  const seenIds = new Set<string>();
+  for (const deployment of deployments) {
+    if (seenIds.has(deployment.id)) {
+      throw new Error(
+        `Duplicate community compute deployment ID: ${deployment.id}`,
+      );
+    }
+    seenIds.add(deployment.id);
+  }
+
+  const ordered = [...deployments].sort(
+    (left, right) =>
+      stableHash(left.id) - stableHash(right.id) ||
+      left.id.localeCompare(right.id),
+  );
+  // Previous cells are retained only when they remain collision-free. New
+  // territories search the compact spiral for the first candidate that both
+  // fits and touches the occupied frontier.
+  const previousById = new Map(
+    (options.previous?.territories ?? []).map((territory) => [
+      territory.deploymentId,
+      territory,
+    ]),
+  );
+  const retainableIds = connectedRetainedTerritoryIds(ordered, previousById);
+  const occupied = new Set<string>();
+  const territories: CommunityComputeHexTerritory[] = [];
+  const placementOrder = [...ordered].sort(
+    (left, right) =>
+      Number(retainableIds.has(right.id)) -
+        Number(retainableIds.has(left.id)) ||
+      ordered.indexOf(left) - ordered.indexOf(right),
+  );
+
+  for (const deployment of placementOrder) {
+    const previous = retainableIds.has(deployment.id)
+      ? previousById.get(deployment.id)
+      : undefined;
+    const retained =
+      previous?.cells.length === deployment.cellCount
+        ? previous.cells.map(({ q, r }) => ({ q, r }))
+        : null;
+    const retainedFits = retained?.every(
+      (cell) => !occupied.has(hexCoordinateKey(cell)),
+    );
+    const orientation = stableHash(`${deployment.id}:orientation`) % 6;
+    let center = retainedFits ? previous?.center : undefined;
+    let coordinates = retainedFits ? retained : null;
+
+    if (!coordinates || !center) {
+      for (let slot = 0; ; slot += 1) {
+        const candidate = balancedSpiralCoordinate(slot);
+        const offsets = territoryOffsets(deployment.cellCount, orientation);
+        const candidateCells = offsets.map((offset) => ({
+          q: candidate.q + offset.q,
+          r: candidate.r + offset.r,
+        }));
+        const fits = candidateCells.every(
+          (cell) => !occupied.has(hexCoordinateKey(cell)),
+        );
+        const touches =
+          occupied.size === 0 ||
+          candidateCells.some((cell) =>
+            hexNeighbours(cell).some((neighbour) =>
+              occupied.has(hexCoordinateKey(neighbour)),
+            ),
+          );
+        if (fits && touches) {
+          center = candidate;
+          coordinates = candidateCells;
+          break;
+        }
+      }
+    }
+
+    const cells = coordinates.map(({ q, r }, index) => {
+      occupied.add(hexCoordinateKey({ q, r }));
+      return {
+        id: `${deployment.id}@${q},${r}`,
+        deploymentId: deployment.id,
+        index,
+        q,
+        r,
+      };
+    });
+    territories.push({ deploymentId: deployment.id, center, cells });
+  }
+  territories.sort(
+    (left, right) =>
+      ordered.findIndex((item) => item.id === left.deploymentId) -
+      ordered.findIndex((item) => item.id === right.deploymentId),
+  );
+  const cells = territories.flatMap((territory) => territory.cells);
+
+  return { territories, cells, bounds: findBounds(cells) };
+}
+
+/** The six axial neighbours of a cell, in stable clockwise order. */
+export function hexNeighbours(coordinate: HexCoordinate): HexCoordinate[] {
+  return HEX_DIRECTIONS.map((direction) => ({
+    q: coordinate.q + direction.q,
+    r: coordinate.r + direction.r,
+  }));
+}
+
+/**
+ * Return only the exposed unit-hex sides of a territory.
+ *
+ * Coordinates use pointy-top axial geometry. Shared sides are omitted, so the
+ * result can be stroked as one fused territory rather than as overlapping
+ * individual hexagons. Edge direction is stable and follows each cell's
+ * perimeter; callers may chain matching endpoints when an ordered path is
+ * required.
+ */
+export function hexTerritoryBoundaryEdges(
+  cells: readonly HexCoordinate[],
+): HexBoundaryEdge[] {
+  const occupied = new Set(cells.map(hexCoordinateKey));
+  const edges: HexBoundaryEdge[] = [];
+
+  for (const cell of cells) {
+    for (let direction = 0; direction < HEX_DIRECTIONS.length; direction += 1) {
+      const neighbour = {
+        q: cell.q + HEX_DIRECTIONS[direction].q,
+        r: cell.r + HEX_DIRECTIONS[direction].r,
+      };
+      if (!occupied.has(hexCoordinateKey(neighbour))) {
+        edges.push(hexEdge(cell, direction));
+      }
+    }
+  }
+
+  return edges;
+}
+
+/**
+ * Return each side shared by two cells in a territory exactly once.
+ *
+ * Fused model territories do not render these edges. Split deployments use
+ * them to show the device boundaries without drawing inset outlines around
+ * every cell or accidentally doubling a shared stroke.
+ */
+export function hexTerritoryInteriorEdges(
+  cells: readonly HexCoordinate[],
+): HexBoundaryEdge[] {
+  const occupied = new Set(cells.map(hexCoordinateKey));
+  const edges: HexBoundaryEdge[] = [];
+
+  for (const cell of cells) {
+    const cellKey = hexCoordinateKey(cell);
+    for (let direction = 0; direction < HEX_DIRECTIONS.length; direction += 1) {
+      const neighbour = {
+        q: cell.q + HEX_DIRECTIONS[direction].q,
+        r: cell.r + HEX_DIRECTIONS[direction].r,
+      };
+      const neighbourKey = hexCoordinateKey(neighbour);
+      if (occupied.has(neighbourKey) && cellKey < neighbourKey) {
+        edges.push(hexEdge(cell, direction));
+      }
+    }
+  }
+
+  return edges;
+}
+
+function hexEdge(cell: HexCoordinate, direction: number): HexBoundaryEdge {
+  const center = {
+    x: Math.sqrt(3) * (cell.q + cell.r / 2),
+    y: 1.5 * cell.r,
+  };
+  const corners = Array.from({ length: 6 }, (_, index) => {
+    const angle = ((-30 + index * 60) * Math.PI) / 180;
+    return {
+      x: normalizeHexPointComponent(center.x + Math.cos(angle)),
+      y: normalizeHexPointComponent(center.y + Math.sin(angle)),
+    };
+  });
+  return {
+    start: corners[(6 - direction) % 6],
+    end: corners[(7 - direction) % 6],
+  };
+}
+
+function normalizeHexPointComponent(value: number): number {
+  return Math.abs(value) < Number.EPSILON * 8 ? 0 : value;
+}
+
+/** Axial hex distance, useful to consumers for borders and transitions. */
+export function hexDistance(left: HexCoordinate, right: HexCoordinate): number {
+  const dq = left.q - right.q;
+  const dr = left.r - right.r;
+  return Math.max(Math.abs(dq), Math.abs(dr), Math.abs(dq + dr));
+}
+
+/** True when every cell can be reached from every other through shared edges. */
+export function isContiguousHexTerritory(
+  cells: readonly HexCoordinate[],
+): boolean {
+  if (cells.length === 0) {
+    return false;
+  }
+  const remaining = new Set(cells.map(hexCoordinateKey));
+  const queue: HexCoordinate[] = [cells[0]];
+  remaining.delete(hexCoordinateKey(cells[0]));
+  for (let cursor = 0; cursor < queue.length; cursor += 1) {
+    for (const neighbour of hexNeighbours(queue[cursor])) {
+      const key = hexCoordinateKey(neighbour);
+      if (remaining.delete(key)) {
+        queue.push(neighbour);
+      }
+    }
+  }
+  return remaining.size === 0;
+}
+
+export function hexCoordinateKey(coordinate: HexCoordinate): string {
+  return `${coordinate.q},${coordinate.r}`;
+}
+
+/** Keep only the edge-connected component of valid surviving territories. */
+function connectedRetainedTerritoryIds(
+  ordered: readonly CommunityComputeLayoutInput[],
+  previousById: ReadonlyMap<string, CommunityComputeHexTerritory>,
+): Set<string> {
+  const valid = ordered
+    .map((deployment) => previousById.get(deployment.id))
+    .filter(
+      (territory): territory is CommunityComputeHexTerritory =>
+        territory !== undefined &&
+        territory.cells.length ===
+          ordered.find((item) => item.id === territory.deploymentId)?.cellCount,
+    );
+  if (valid.length === 0) return new Set();
+
+  const owner = new Map<string, string>();
+  for (const territory of valid) {
+    for (const cell of territory.cells) {
+      const key = hexCoordinateKey(cell);
+      if (owner.has(key)) return new Set();
+      owner.set(key, territory.deploymentId);
+    }
+  }
+  const retained = new Set([valid[0].deploymentId]);
+  const queue = [valid[0].deploymentId];
+  const byId = new Map(
+    valid.map((territory) => [territory.deploymentId, territory]),
+  );
+  for (let cursor = 0; cursor < queue.length; cursor += 1) {
+    const territory = byId.get(queue[cursor]);
+    if (!territory) continue;
+    for (const cell of territory.cells) {
+      for (const neighbour of hexNeighbours(cell)) {
+        const neighbourOwner = owner.get(hexCoordinateKey(neighbour));
+        if (neighbourOwner && !retained.has(neighbourOwner)) {
+          retained.add(neighbourOwner);
+          queue.push(neighbourOwner);
+        }
+      }
+    }
+  }
+  return retained;
+}
+
+function territoryOffsets(
+  count: HexCellCount,
+  orientation: number,
+): HexCoordinate[] {
+  const center = { q: 0, r: 0 };
+  if (count === 1) {
+    return [center];
+  }
+  if (count === 2) {
+    return [center, HEX_DIRECTIONS[orientation]];
+  }
+  if (count === 4) {
+    return [
+      center,
+      HEX_DIRECTIONS[orientation],
+      HEX_DIRECTIONS[(orientation + 1) % 6],
+      HEX_DIRECTIONS[(orientation + 2) % 6],
+    ];
+  }
+  return [center, ...HEX_DIRECTIONS];
+}
+
+/**
+ * Zero-based spiral slot: origin, then complete radius-one, radius-two, … rings.
+ * Runtime is O(radius), which is O(sqrt(n)); even at dense fixture sizes the
+ * largest radius remains small.
+ */
+function balancedSpiralCoordinate(index: number): HexCoordinate {
+  if (index === 0) {
+    return { q: 0, r: 0 };
+  }
+
+  let radius = 1;
+  let ringStart = 1;
+  while (index >= ringStart + 6 * radius) {
+    ringStart += 6 * radius;
+    radius += 1;
+  }
+
+  const ringLength = 6 * radius;
+  const ringIndex = index - ringStart;
+  // Multiplication by a number coprime with the ring length is a permutation,
+  // not sampling: every slot is eventually visited. A step near half a ring
+  // alternates opposite sides, preventing a partially filled layer from
+  // producing the one-sided growth of a clockwise spiral.
+  let step = Math.max(1, Math.floor(ringLength / 2) - 1);
+  while (greatestCommonDivisor(step, ringLength) !== 1) step -= 1;
+  const offsetSeed = stableHash(`ring:${radius}`) % ringLength;
+  let offset = (offsetSeed + ringIndex * step) % ringLength;
+  let coordinate = { q: -radius, r: radius };
+  for (const direction of HEX_DIRECTIONS) {
+    const steps = Math.min(radius, offset);
+    coordinate = {
+      q: coordinate.q + direction.q * steps,
+      r: coordinate.r + direction.r * steps,
+    };
+    offset -= steps;
+    if (offset === 0) {
+      break;
+    }
+  }
+  return coordinate;
+}
+
+function greatestCommonDivisor(left: number, right: number): number {
+  let a = left;
+  let b = right;
+  while (b !== 0) {
+    const remainder = a % b;
+    a = b;
+    b = remainder;
+  }
+  return a;
+}
+
+function findBounds(
+  cells: readonly HexCoordinate[],
+): CommunityComputeHexBounds | null {
+  if (cells.length === 0) {
+    return null;
+  }
+  let minQ = cells[0].q;
+  let maxQ = cells[0].q;
+  let minR = cells[0].r;
+  let maxR = cells[0].r;
+  for (const cell of cells.slice(1)) {
+    minQ = Math.min(minQ, cell.q);
+    maxQ = Math.max(maxQ, cell.q);
+    minR = Math.min(minR, cell.r);
+    maxR = Math.max(maxR, cell.r);
+  }
+  return { minQ, maxQ, minR, maxR };
+}
+
+/** FNV-1a over UTF-16 code units; deterministic on every JS runtime. */
+function stableHash(value: string): number {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
diff --git a/desktop/src/features/mesh-compute/communityComputeMapModel.test.mjs b/desktop/src/features/mesh-compute/communityComputeMapModel.test.mjs
new file mode 100644
index 0000000000..e9c3ed32b2
--- /dev/null
+++ b/desktop/src/features/mesh-compute/communityComputeMapModel.test.mjs
@@ -0,0 +1,206 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  bucketHexCellCount,
+  capacityGbToHexCellCount,
+  deriveCommunityComputeMapModel,
+} from "./communityComputeMapModel.ts";
+import {
+  COMMUNITY_COMPUTE_TUTORIAL_FIXTURES,
+  LARGE_DENSE_COMMUNITY_COMPUTE_FIXTURE,
+  createLargeDenseSnapshot,
+} from "./communityComputeFixtures.ts";
+
+function device(overrides = {}) {
+  return {
+    deviceId: "device-1",
+    label: "Studio",
+    capacityGb: 32,
+    models: ["gemma"],
+    state: "serving",
+    isSelf: false,
+    memberPubkey: "member-1",
+    reportedAt: 1_786_032_000,
+    modelSizeGb: 18,
+    ...overrides,
+  };
+}
+
+function snapshot(overrides = {}) {
+  return {
+    sharingDeviceCount: 1,
+    contributorMemberCount: 1,
+    sharedCapacityGb: 32,
+    allocatedCapacityGb: 18,
+    models: ["gemma"],
+    devices: [device()],
+    includesSelf: false,
+    memberCount: 4,
+    reason: null,
+    ...overrides,
+  };
+}
+
+test("cell buckets are exactly 1, 2, 4, and 7", () => {
+  assert.deepEqual(
+    [-1, 1, 1.1, 2, 2.1, 4, 4.1, 999, Number.NaN].map(bucketHexCellCount),
+    [1, 1, 2, 2, 4, 4, 7, 7, 1],
+  );
+  assert.deepEqual(
+    [null, 128, 128.1, 256, 256.1, 512, 512.1, 1000].map(
+      capacityGbToHexCellCount,
+    ),
+    [1, 1, 2, 2, 4, 4, 7, 7],
+  );
+});
+
+test("only ready serving models become deployments", () => {
+  const model = deriveCommunityComputeMapModel(
+    snapshot({
+      sharingDeviceCount: 1,
+      devices: [
+        device({ deviceId: "a", models: ["gemma", "qwen"] }),
+        device({ deviceId: "b", state: "loading", models: [] }),
+        device({ deviceId: "c", state: "standby", models: [] }),
+        device({ deviceId: "d", state: "consuming", models: [] }),
+      ],
+    }),
+  );
+
+  assert.equal(model.status, "ready");
+  assert.deepEqual(
+    model.deployments.map((deployment) => deployment.modelId),
+    ["gemma", "qwen"],
+  );
+  assert.equal(model.kpis.deploymentCount, 2);
+  assert.equal(model.kpis.contributorMemberCount, 1);
+  assert.equal(model.health.counts.healthy, 1);
+  assert.equal(model.health.counts.warming, 1);
+  assert.equal(model.health.counts.idle, 1);
+});
+
+test("one territory is produced per model and per device replica", () => {
+  const model = deriveCommunityComputeMapModel(
+    snapshot({
+      devices: [
+        device({ deviceId: "a", models: ["qwen", "gemma"] }),
+        device({ deviceId: "b", memberPubkey: "member-2", models: ["gemma"] }),
+      ],
+    }),
+  );
+  assert.equal(model.deployments.length, 3);
+  assert.equal(
+    model.deployments.filter((deployment) => deployment.modelId === "gemma")
+      .length,
+    2,
+  );
+  assert.equal(new Set(model.deployments.map(({ id }) => id)).size, 3);
+});
+
+test("reported model footprint controls area without fixture overrides", () => {
+  const model = deriveCommunityComputeMapModel(
+    snapshot({ devices: [device({ capacityGb: 768, modelSizeGb: 96 })] }),
+  );
+  assert.equal(model.deployments[0].cellCount, 1);
+
+  const large = deriveCommunityComputeMapModel(
+    snapshot({ devices: [device({ capacityGb: 768, modelSizeGb: 646 })] }),
+  );
+  assert.equal(large.deployments[0].cellCount, 7);
+});
+
+test("loading, consumer-only, and empty snapshots render no territories", () => {
+  for (const state of ["loading", "standby", "consuming"]) {
+    const model = deriveCommunityComputeMapModel(
+      snapshot({ devices: [device({ state, models: [] })] }),
+    );
+    assert.equal(model.status, "empty");
+    assert.equal(model.deployments.length, 0);
+  }
+  assert.equal(deriveCommunityComputeMapModel(null).status, "loading");
+  assert.equal(
+    deriveCommunityComputeMapModel(
+      COMMUNITY_COMPUTE_TUTORIAL_FIXTURES.empty.snapshot,
+    ).status,
+    "empty",
+  );
+});
+
+test("projection is deterministic and independent of device/model order", () => {
+  const devices = [
+    device({ deviceId: "z", label: "Zulu", models: ["qwen", "gemma"] }),
+    device({ deviceId: "a", label: "Alpha", models: ["mistral"] }),
+  ];
+  const forward = deriveCommunityComputeMapModel(snapshot({ devices }));
+  const reverse = deriveCommunityComputeMapModel(
+    snapshot({
+      devices: [...devices]
+        .reverse()
+        .map((item) => ({ ...item, models: [...item.models].reverse() })),
+    }),
+  );
+  assert.deepEqual(forward, reverse);
+});
+
+test("tutorial fixtures use only production fields and production sizing", () => {
+  assert.deepEqual(Object.keys(COMMUNITY_COMPUTE_TUTORIAL_FIXTURES).sort(), [
+    "empty",
+    "large-dense-500",
+    "single-device",
+    "small-company",
+  ]);
+  const allowed = new Set([
+    "deviceId",
+    "label",
+    "capacityGb",
+    "models",
+    "state",
+    "isSelf",
+    "memberPubkey",
+    "reportedAt",
+    "modelSizeGb",
+  ]);
+  for (const fixture of Object.values(COMMUNITY_COMPUTE_TUTORIAL_FIXTURES)) {
+    for (const item of fixture.snapshot.devices) {
+      assert.deepEqual(
+        Object.keys(item).filter((key) => !allowed.has(key)),
+        [],
+      );
+    }
+  }
+  const small = deriveCommunityComputeMapModel(
+    COMMUNITY_COMPUTE_TUTORIAL_FIXTURES["small-company"].snapshot,
+  );
+  assert.equal(small.deployments.length, 12);
+  assert.equal(
+    small.deployments.filter(({ deviceLabel }) =>
+      deviceLabel.startsWith("Team MacBook"),
+    ).length,
+    10,
+  );
+  assert.equal(
+    small.deployments.filter(({ cellCount }) => cellCount === 1).length,
+    10,
+  );
+  assert.equal(
+    small.deployments.filter(({ cellCount }) => cellCount === 7).length,
+    2,
+  );
+});
+
+test("large dense fixture is deterministic and excludes non-serving rows", () => {
+  const fixture = LARGE_DENSE_COMMUNITY_COMPUTE_FIXTURE.snapshot;
+  assert.deepEqual(fixture, createLargeDenseSnapshot(500));
+  assert.equal(fixture.devices.length, 500);
+  const servingCount = fixture.devices.filter(
+    (item) => item.state === "serving" && item.models.length > 0,
+  ).length;
+  const model = deriveCommunityComputeMapModel(fixture);
+  assert.equal(model.deployments.length, servingCount);
+  assert.equal(model.kpis.deploymentCount, servingCount);
+  assert.equal(
+    new Set(model.deployments.map(({ id }) => id)).size,
+    servingCount,
+  );
+});
diff --git a/desktop/src/features/mesh-compute/communityComputeMapModel.ts b/desktop/src/features/mesh-compute/communityComputeMapModel.ts
new file mode 100644
index 0000000000..663b957d5f
--- /dev/null
+++ b/desktop/src/features/mesh-compute/communityComputeMapModel.ts
@@ -0,0 +1,365 @@
+import type {
+  MeshDeviceState,
+  MeshSnapshot,
+  MeshSnapshotDevice,
+} from "@/shared/api/tauriMesh";
+
+/** The only territory sizes rendered by the community compute map. */
+export const HEX_CELL_BUCKETS = [1, 2, 4, 7] as const;
+
+export type HexCellCount = (typeof HEX_CELL_BUCKETS)[number];
+
+/**
+ * The Community view intentionally consumes only fields in the production
+ * snapshot contract. Tutorial fixtures use this same shape so examples cannot
+ * quietly grow capabilities that live Compute does not have.
+ */
+export type CommunityComputeDeviceInput = MeshSnapshotDevice;
+
+/** A readonly, structurally compatible form of the current mesh snapshot. */
+export type CommunityComputeSnapshotInput<
+  TDevice extends MeshSnapshotDevice = CommunityComputeDeviceInput,
+> = Omit<MeshSnapshot, "devices"> & {
+  readonly devices: readonly TDevice[];
+};
+
+export type CommunityComputeDeploymentHealth =
+  | "healthy"
+  | "warming"
+  | "idle"
+  | "degraded"
+  | "offline"
+  | "unknown";
+
+export type CommunityComputeMapHealth =
+  | "healthy"
+  | "attention"
+  | "critical"
+  | "empty"
+  | "unknown";
+
+export type CommunityComputeDeployment<
+  TDevice extends MeshSnapshotDevice = CommunityComputeDeviceInput,
+> = {
+  /** Stable map identity. Never derived from the device's array position. */
+  id: string;
+  /** Model shown as the territory's primary identity. */
+  label: string;
+  modelId: string;
+  deviceLabel: string;
+  capacityGb: number | null;
+  models: readonly string[];
+  state: MeshDeviceState;
+  isSelf: boolean;
+  health: CommunityComputeDeploymentHealth;
+  healthReason: string | null;
+  cellCount: HexCellCount;
+  /** Preserves additive backend data for a future detail projection. */
+  source: Readonly<TDevice>;
+};
+
+export type CommunityComputeKpis = {
+  memberCount: number;
+  contributorMemberCount: number;
+  deploymentCount: number;
+  activeDeploymentCount: number;
+  sharedCapacityGb: number | null;
+  allocatedCapacityGb: number | null;
+  allocatedPercent: number | null;
+  modelCount: number;
+};
+
+export type CommunityComputeHealthSummary = {
+  status: CommunityComputeMapHealth;
+  label: string;
+  reason: string | null;
+  counts: Record<CommunityComputeDeploymentHealth, number>;
+};
+
+export type CommunityComputeMapModel<
+  TDevice extends MeshSnapshotDevice = CommunityComputeDeviceInput,
+> = {
+  status: "loading" | "ready" | "empty";
+  kpis: CommunityComputeKpis;
+  health: CommunityComputeHealthSummary;
+  deployments: readonly CommunityComputeDeployment<TDevice>[];
+};
+
+/**
+ * Round a desired territory footprint up to one of the four supported shapes.
+ * Invalid and non-positive weights still get one cell so a deployment cannot
+ * disappear from the map.
+ */
+export function bucketHexCellCount(
+  weight: number | null | undefined,
+): HexCellCount {
+  if (weight === null || weight === undefined || !Number.isFinite(weight)) {
+    return 1;
+  }
+  const normalized = Math.max(1, Math.ceil(weight));
+  return HEX_CELL_BUCKETS.find((bucket) => normalized <= bucket) ?? 7;
+}
+
+/**
+ * Turn model memory into a deliberately coarse footprint.
+ *
+ * A 128 GB Mac is the common mesh workhorse, so every model that fits on one is
+ * one cell. Multi-cell territories are reserved for genuinely multi-GPU scale
+ * deployments; this avoids making ordinary local models look fragmented.
+ */
+export function capacityGbToHexCellCount(
+  capacityGb: number | null | undefined,
+): HexCellCount {
+  if (capacityGb === null || capacityGb === undefined || capacityGb <= 128) {
+    return 1;
+  }
+  if (capacityGb <= 256) {
+    return 2;
+  }
+  if (capacityGb <= 512) {
+    return 4;
+  }
+  return 7;
+}
+
+const EMPTY_HEALTH_COUNTS: Record<CommunityComputeDeploymentHealth, number> = {
+  healthy: 0,
+  warming: 0,
+  idle: 0,
+  degraded: 0,
+  offline: 0,
+  unknown: 0,
+};
+
+/** Project a backend snapshot into the complete, render-agnostic map model. */
+export function deriveCommunityComputeMapModel<
+  TDevice extends MeshSnapshotDevice = CommunityComputeDeviceInput,
+>(
+  snapshot: CommunityComputeSnapshotInput<TDevice> | null,
+): CommunityComputeMapModel<TDevice> {
+  if (snapshot === null) {
+    return {
+      status: "loading",
+      kpis: {
+        memberCount: 0,
+        contributorMemberCount: 0,
+        deploymentCount: 0,
+        activeDeploymentCount: 0,
+        sharedCapacityGb: null,
+        allocatedCapacityGb: null,
+        allocatedPercent: null,
+        modelCount: 0,
+      },
+      health: {
+        status: "unknown",
+        label: "Checking community compute",
+        reason: null,
+        counts: { ...EMPTY_HEALTH_COUNTS },
+      },
+      deployments: [],
+    };
+  }
+
+  const deployments = projectDeployments(snapshot.devices);
+  const healthStates = snapshot.devices
+    .filter((device) => device.state !== "consuming")
+    .map((device) => healthFromState(device.state));
+  const counts = countHealth(healthStates);
+  const models = new Set(snapshot.models);
+  for (const deployment of deployments) {
+    for (const model of deployment.models) {
+      models.add(model);
+    }
+  }
+
+  const contributorMemberCount =
+    snapshot.contributorMemberCount ??
+    new Set(
+      deployments
+        .filter((deployment) => deployment.state === "serving")
+        .map(
+          (deployment) =>
+            deployment.source.memberPubkey?.trim() || deployment.id,
+        ),
+    ).size;
+  const sharedCapacityGb = finiteNonNegative(snapshot.sharedCapacityGb);
+  const reportedAllocated = finiteNonNegative(snapshot.allocatedCapacityGb);
+  const servingDeployments = deployments.filter(
+    (deployment) => deployment.state === "serving",
+  );
+  const inferredAllocations = servingDeployments.map((deployment) =>
+    finiteNonNegative(deployment.source.modelSizeGb),
+  );
+  const allocatedCapacityGb =
+    reportedAllocated ??
+    (inferredAllocations.length > 0 &&
+    inferredAllocations.every((value) => value !== null)
+      ? inferredAllocations.reduce((total, value) => total + (value ?? 0), 0)
+      : null);
+
+  return {
+    status: deployments.length === 0 ? "empty" : "ready",
+    kpis: {
+      memberCount: nonNegativeInteger(snapshot.memberCount),
+      contributorMemberCount,
+      deploymentCount: deployments.length,
+      activeDeploymentCount: counts.healthy + counts.warming,
+      sharedCapacityGb,
+      allocatedCapacityGb,
+      allocatedPercent:
+        allocatedCapacityGb !== null &&
+        sharedCapacityGb !== null &&
+        sharedCapacityGb > 0
+          ? Math.min(100, (allocatedCapacityGb / sharedCapacityGb) * 100)
+          : null,
+      modelCount: models.size,
+    },
+    health: summarizeHealth(counts, healthStates, snapshot.reason),
+    deployments,
+  };
+}
+
+function projectDeployments<TDevice extends MeshSnapshotDevice>(
+  devices: readonly TDevice[],
+): CommunityComputeDeployment<TDevice>[] {
+  const canonical = devices
+    .filter((device) => device.state === "serving" && device.models.length > 0)
+    .flatMap((device) =>
+      [...new Set(device.models)].map((model) => ({
+        device: { ...device, models: [model] } as TDevice,
+        identity: deploymentIdentity(device, model),
+      })),
+    )
+    .sort(
+      (left, right) =>
+        left.identity.localeCompare(right.identity) ||
+        deviceFingerprint(left.device).localeCompare(
+          deviceFingerprint(right.device),
+        ),
+    );
+  const occurrences = new Map<string, number>();
+
+  return canonical.map(({ device, identity }) => {
+    const occurrence = occurrences.get(identity) ?? 0;
+    occurrences.set(identity, occurrence + 1);
+    const models = [...new Set(device.models)].sort();
+    return {
+      id: occurrence === 0 ? identity : `${identity}#${occurrence + 1}`,
+      label: models[0] ?? device.label,
+      modelId: models[0] ?? "Model not reported",
+      deviceLabel: device.label,
+      capacityGb: finiteNonNegative(device.capacityGb),
+      models,
+      state: device.state,
+      isSelf: device.isSelf,
+      health: healthFromState(device.state),
+      healthReason: null,
+      cellCount: capacityGbToHexCellCount(
+        device.modelSizeGb ?? device.capacityGb,
+      ),
+      source: device,
+    };
+  });
+}
+
+function deploymentIdentity(
+  device: MeshSnapshotDevice,
+  modelId: string,
+): string {
+  const deviceId = cleanOptionalText(device.deviceId);
+  const model = encodeURIComponent(modelId);
+  return deviceId === null
+    ? `derived:${encodeURIComponent(deviceFingerprint(device))}:${model}`
+    : `deployment:${encodeURIComponent(deviceId)}:${model}`;
+}
+
+function deviceFingerprint(device: MeshSnapshotDevice): string {
+  return JSON.stringify([
+    device.label,
+    device.capacityGb,
+    [...device.models].sort(),
+    device.state,
+    device.isSelf,
+  ]);
+}
+
+function healthFromState(
+  state: MeshDeviceState,
+): CommunityComputeDeploymentHealth {
+  switch (state) {
+    case "serving":
+    case "consuming":
+      return "healthy";
+    case "loading":
+      return "warming";
+    case "standby":
+      return "idle";
+  }
+}
+
+function countHealth(
+  states: readonly CommunityComputeDeploymentHealth[],
+): Record<CommunityComputeDeploymentHealth, number> {
+  const counts = { ...EMPTY_HEALTH_COUNTS };
+  for (const state of states) {
+    counts[state] += 1;
+  }
+  return counts;
+}
+
+function summarizeHealth(
+  counts: Record<CommunityComputeDeploymentHealth, number>,
+  states: readonly CommunityComputeDeploymentHealth[],
+  snapshotReason: string | null,
+): CommunityComputeHealthSummary {
+  if (states.length === 0) {
+    return {
+      status: "empty",
+      label: "No deployments",
+      reason: cleanOptionalText(snapshotReason),
+      counts,
+    };
+  }
+
+  const unavailable = counts.offline + counts.degraded;
+  const reason = null;
+
+  if (counts.offline === states.length) {
+    return { status: "critical", label: "Compute unavailable", reason, counts };
+  }
+  if (unavailable > 0) {
+    return {
+      status: "attention",
+      label: `${unavailable} deployment${unavailable === 1 ? "" : "s"} need attention`,
+      reason,
+      counts,
+    };
+  }
+  if (counts.unknown === states.length) {
+    return { status: "unknown", label: "Health unknown", reason: null, counts };
+  }
+  return {
+    status: "healthy",
+    label: "No reported issues",
+    reason: null,
+    counts,
+  };
+}
+
+function finiteNonNegative(value: number | null | undefined): number | null {
+  return value !== null &&
+    value !== undefined &&
+    Number.isFinite(value) &&
+    value >= 0
+    ? value
+    : null;
+}
+
+function nonNegativeInteger(value: number): number {
+  return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
+
+function cleanOptionalText(value: string | null | undefined): string | null {
+  const cleaned = value?.trim();
+  return cleaned ? cleaned : null;
+}
diff --git a/desktop/src/features/mesh-compute/hooks/useMeshComputeState.ts b/desktop/src/features/mesh-compute/hooks/useMeshComputeState.ts
index 1f305b07a3..62698ca81e 100644
--- a/desktop/src/features/mesh-compute/hooks/useMeshComputeState.ts
+++ b/desktop/src/features/mesh-compute/hooks/useMeshComputeState.ts
@@ -55,7 +55,11 @@ export function useMeshComputeState() {
   // transition, instead of waiting out the 30s poll.
   const [snapshotNonce, setSnapshotNonce] = React.useState(0);
 
-  const { snapshot, error: snapshotError } = useMeshSnapshot({
+  const {
+    snapshot,
+    error: snapshotError,
+    refresh: refreshSnapshot,
+  } = useMeshSnapshot({
     refreshKey: snapshotNonce,
   });
 
@@ -243,6 +247,7 @@ export function useMeshComputeState() {
     shareSwitchChecked,
     modelToShare,
     setSharing,
+    refreshSnapshot,
     // A transport failure is worth showing; an empty mesh is not an error and
     // is already expressed by the row tone.
     error: actionError ?? snapshotError,
diff --git a/desktop/src/features/mesh-compute/ui/CommunityComputeComponents.test.mjs b/desktop/src/features/mesh-compute/ui/CommunityComputeComponents.test.mjs
new file mode 100644
index 0000000000..d20ed6ebee
--- /dev/null
+++ b/desktop/src/features/mesh-compute/ui/CommunityComputeComponents.test.mjs
@@ -0,0 +1,95 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import React from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+
+import {
+  EMPTY_COMMUNITY_COMPUTE_FIXTURE,
+  SMALL_COMPANY_COMMUNITY_COMPUTE_FIXTURE,
+} from "../communityComputeFixtures.ts";
+import { deriveCommunityComputeMapModel } from "../communityComputeMapModel.ts";
+import { CommunityComputeHealthScorecard } from "./CommunityComputeHealthScorecard.tsx";
+import { CommunityComputeKpiRow } from "./CommunityComputeKpiRow.tsx";
+import { CommunityComputeTerritoryMap } from "./CommunityComputeTerritoryMap.tsx";
+
+const smallModel = deriveCommunityComputeMapModel(
+  SMALL_COMPANY_COMMUNITY_COMPUTE_FIXTURE.snapshot,
+);
+
+describe("community compute visual components", () => {
+  it("renders contract-backed KPI values", () => {
+    const html = renderToStaticMarkup(
+      React.createElement(CommunityComputeKpiRow, { kpis: smallModel.kpis }),
+    );
+    assert.match(html, /community-compute-kpi-members-sharing/);
+    assert.match(html, /community-compute-kpi-contributed-vram/);
+    assert.match(html, /community-compute-kpi-vram-allocated/);
+    assert.match(html, /24 community members/);
+    assert.match(html, />2,744 GB</);
+  });
+
+  it("renders only health states production can derive", () => {
+    const html = renderToStaticMarkup(
+      React.createElement(CommunityComputeHealthScorecard, {
+        health: smallModel.health,
+      }),
+    );
+    assert.match(html, /data-status="healthy"/);
+    assert.match(html, /No reported issues/);
+    assert.match(html, /data-testid="community-compute-health-healthy"/);
+  });
+
+  it("renders one accessible territory and list item per ready model", () => {
+    const html = renderToStaticMarkup(
+      React.createElement(CommunityComputeTerritoryMap, { model: smallModel }),
+    );
+    assert.match(html, /data-testid="community-compute-map-svg"/);
+    assert.equal(
+      [
+        ...html.matchAll(
+          /data-testid="community-compute-territory-deployment-/g,
+        ),
+      ].length,
+      smallModel.deployments.length,
+    );
+    assert.equal(
+      [
+        ...html.matchAll(
+          /data-testid="community-compute-deployment-deployment-/g,
+        ),
+      ].length,
+      smallModel.deployments.length,
+    );
+    assert.match(html, /tabindex="0"/);
+    assert.match(html, /Search models or devices/);
+    assert.match(html, /Model footprint/);
+    assert.doesNotMatch(html, /Utilization|Region|Split across machines/);
+  });
+
+  it("keeps the production map static and supports explicit tutorial motion", () => {
+    const html = renderToStaticMarkup(
+      React.createElement(CommunityComputeTerritoryMap, { model: smallModel }),
+    );
+    assert.doesNotMatch(html, /animate-mesh-inference/);
+
+    const tutorialHtml = renderToStaticMarkup(
+      React.createElement(CommunityComputeTerritoryMap, {
+        model: smallModel,
+        inferenceDeploymentIds: [smallModel.deployments[0].id],
+      }),
+    );
+    assert.match(tutorialHtml, /animate-mesh-inference/);
+    assert.doesNotMatch(html, /community-compute-split-boundary/);
+  });
+
+  it("renders a static empty state without a deployment list", () => {
+    const emptyModel = deriveCommunityComputeMapModel(
+      EMPTY_COMMUNITY_COMPUTE_FIXTURE.snapshot,
+    );
+    const html = renderToStaticMarkup(
+      React.createElement(CommunityComputeTerritoryMap, { model: emptyModel }),
+    );
+    assert.match(html, /data-testid="community-compute-map-empty"/);
+    assert.doesNotMatch(html, /community-compute-deployment-list/);
+  });
+});
diff --git a/desktop/src/features/mesh-compute/ui/CommunityComputeHealthScorecard.tsx b/desktop/src/features/mesh-compute/ui/CommunityComputeHealthScorecard.tsx
new file mode 100644
index 0000000000..cbf39dc9a4
--- /dev/null
+++ b/desktop/src/features/mesh-compute/ui/CommunityComputeHealthScorecard.tsx
@@ -0,0 +1,154 @@
+import {
+  AlertTriangle,
+  CheckCircle2,
+  CircleHelp,
+  MinusCircle,
+  XCircle,
+} from "lucide-react";
+
+import { cn } from "@/shared/lib/cn";
+import type {
+  CommunityComputeDeploymentHealth,
+  CommunityComputeHealthSummary,
+} from "../communityComputeMapModel";
+
+export type CommunityComputeHealthScorecardProps = {
+  health: CommunityComputeHealthSummary;
+  className?: string;
+};
+
+const HEALTH_ROWS: readonly {
+  status: CommunityComputeDeploymentHealth;
+  label: string;
+}[] = [
+  { status: "healthy", label: "Healthy" },
+  { status: "warming", label: "Warming" },
+  { status: "idle", label: "Idle" },
+  { status: "degraded", label: "Degraded" },
+  { status: "offline", label: "Offline" },
+  { status: "unknown", label: "Unknown" },
+];
+
+/** Health summary with icon, copy, and count labels that do not rely on color. */
+export function CommunityComputeHealthScorecard({
+  health,
+  className,
+}: CommunityComputeHealthScorecardProps) {
+  const Icon = statusIcon(health.status);
+  const total = Object.values(health.counts).reduce(
+    (sum, count) => sum + count,
+    0,
+  );
+
+  return (
+    <section
+      aria-labelledby="community-compute-health-title"
+      className={cn(
+        "rounded-xl border border-border/70 bg-background p-4",
+        className,
+      )}
+      data-status={health.status}
+      data-testid="community-compute-health-scorecard"
+    >
+      <div className="flex items-start gap-3">
+        <span
+          aria-hidden="true"
+          className={cn(
+            "flex size-9 shrink-0 items-center justify-center rounded-full border bg-muted/30",
+            health.status === "healthy" && "border-foreground/30",
+            health.status === "attention" &&
+              "border-dashed border-foreground/50",
+            health.status === "critical" && "border-2 border-foreground",
+          )}
+        >
+          <Icon className="size-4" />
+        </span>
+        <div className="min-w-0 flex-1">
+          <p
+            className="text-sm font-semibold"
+            data-testid="community-compute-health-label"
+            id="community-compute-health-title"
+          >
+            {health.label}
+          </p>
+          <p className="mt-0.5 text-xs leading-snug text-muted-foreground">
+            {health.reason ?? healthDescription(health.status, total)}
+          </p>
+        </div>
+        <span className="shrink-0 text-xs font-medium tabular-nums text-muted-foreground">
+          {total} total
+        </span>
+      </div>
+
+      <dl className="mt-4 grid grid-cols-3 gap-2 sm:grid-cols-6">
+        {HEALTH_ROWS.map(({ status, label }) => (
+          <div
+            className={cn(
+              "rounded-lg border border-border/60 px-2 py-2 text-center",
+              health.counts[status] > 0 && healthClass(status),
+            )}
+            data-testid={`community-compute-health-${status}`}
+            key={status}
+          >
+            <dt className="truncate text-2xs text-muted-foreground">{label}</dt>
+            <dd className="mt-0.5 text-sm font-semibold tabular-nums">
+              {health.counts[status]}
+            </dd>
+          </div>
+        ))}
+      </dl>
+    </section>
+  );
+}
+
+function statusIcon(status: CommunityComputeHealthSummary["status"]) {
+  switch (status) {
+    case "healthy":
+      return CheckCircle2;
+    case "attention":
+      return AlertTriangle;
+    case "critical":
+      return XCircle;
+    case "empty":
+      return MinusCircle;
+    case "unknown":
+      return CircleHelp;
+  }
+}
+
+function healthClass(status: CommunityComputeDeploymentHealth): string {
+  switch (status) {
+    case "healthy":
+      return "border-solid bg-foreground/[0.04]";
+    case "warming":
+      return "border-dashed bg-foreground/[0.03]";
+    case "idle":
+      return "border-dotted";
+    case "degraded":
+      return "border-dashed border-foreground/50";
+    case "offline":
+      return "border-foreground/50 bg-muted/50 line-through decoration-muted-foreground/50";
+    case "unknown":
+      return "border-dotted bg-muted/20";
+  }
+}
+
+function healthDescription(
+  status: CommunityComputeHealthSummary["status"],
+  total: number,
+): string {
+  switch (status) {
+    case "healthy":
+      return "No reporting device needs attention; some may still be warming or idle.";
+    case "attention":
+      return "Some deployments may have reduced availability.";
+    case "critical":
+      return "Shared compute is currently unavailable.";
+    case "empty":
+      return "No deployments have joined this community yet.";
+    case "unknown":
+      return total === 0
+        ? "Waiting for deployment health reports."
+        : "Deployment health could not be determined.";
+  }
+}
diff --git a/desktop/src/features/mesh-compute/ui/CommunityComputeKpiRow.tsx b/desktop/src/features/mesh-compute/ui/CommunityComputeKpiRow.tsx
new file mode 100644
index 0000000000..7e77943f6e
--- /dev/null
+++ b/desktop/src/features/mesh-compute/ui/CommunityComputeKpiRow.tsx
@@ -0,0 +1,83 @@
+import { cn } from "@/shared/lib/cn";
+import type { CommunityComputeKpis } from "../communityComputeMapModel";
+
+export type CommunityComputeKpiRowProps = {
+  kpis: CommunityComputeKpis;
+  className?: string;
+};
+
+/** Compact, responsive headline figures for the community compute pool. */
+export function CommunityComputeKpiRow({
+  kpis,
+  className,
+}: CommunityComputeKpiRowProps) {
+  const items = [
+    {
+      label: "Members sharing",
+      value: formatCount(kpis.contributorMemberCount),
+      detail: `${formatCount(kpis.memberCount)} community members`,
+    },
+    {
+      label: "Contributed VRAM",
+      value: formatCapacity(kpis.sharedCapacityGb),
+      detail: `${formatCount(kpis.deploymentCount)} deployments`,
+    },
+    {
+      label: "VRAM allocated",
+      value:
+        kpis.allocatedPercent === null
+          ? "—"
+          : `${Math.round(kpis.allocatedPercent)}%`,
+      detail:
+        kpis.allocatedCapacityGb === null
+          ? "Not fully reported"
+          : `${formatCapacity(kpis.allocatedCapacityGb)} hosting models`,
+    },
+  ];
+
+  return (
+    <dl
+      className={cn(
+        "grid grid-cols-1 overflow-hidden rounded-xl border border-border/70 bg-muted/15 sm:grid-cols-3",
+        className,
+      )}
+      data-testid="community-compute-kpis"
+    >
+      {items.map((item, index) => (
+        <div
+          className={cn(
+            "min-w-0 px-3 py-2.5",
+            index > 0 && "border-border/60 border-t sm:border-l sm:border-t-0",
+          )}
+          data-testid={`community-compute-kpi-${kpiTestId(item.label)}`}
+          key={item.label}
+        >
+          <dt className="truncate text-2xs font-medium tracking-wide text-muted-foreground uppercase">
+            {item.label}
+          </dt>
+          <dd className="mt-1 truncate text-xl font-semibold tabular-nums">
+            {item.value}
+          </dd>
+          <dd className="mt-0.5 truncate text-2xs text-muted-foreground">
+            {item.detail}
+          </dd>
+        </div>
+      ))}
+    </dl>
+  );
+}
+
+function formatCount(value: number): string {
+  return new Intl.NumberFormat(undefined, { maximumFractionDigits: 0 }).format(
+    value,
+  );
+}
+
+function formatCapacity(value: number | null): string {
+  if (value === null) return "—";
+  return `${new Intl.NumberFormat(undefined, { maximumFractionDigits: 1 }).format(value)} GB`;
+}
+
+function kpiTestId(label: string): string {
+  return label.toLowerCase().replaceAll(" ", "-");
+}
diff --git a/desktop/src/features/mesh-compute/ui/CommunityComputeTerritoryMap.tsx b/desktop/src/features/mesh-compute/ui/CommunityComputeTerritoryMap.tsx
new file mode 100644
index 0000000000..684078dd40
--- /dev/null
+++ b/desktop/src/features/mesh-compute/ui/CommunityComputeTerritoryMap.tsx
@@ -0,0 +1,568 @@
+import * as React from "react";
+
+import { cn } from "@/shared/lib/cn";
+import {
+  hexTerritoryBoundaryEdges,
+  layoutCommunityComputeHexTerritories,
+  type CommunityComputeHexCell,
+} from "../communityComputeHexLayout";
+import type {
+  CommunityComputeDeployment,
+  CommunityComputeDeploymentHealth,
+  CommunityComputeMapModel,
+} from "../communityComputeMapModel";
+
+export type CommunityComputeTerritoryMapProps = {
+  model: CommunityComputeMapModel;
+  selectedDeploymentId?: string | null;
+  onSelectedDeploymentChange?: (deploymentId: string) => void;
+  className?: string;
+  /** Tutorial-only simulated activity; live snapshots cannot attribute requests. */
+  inferenceDeploymentIds?: readonly string[];
+};
+
+type Point = { x: number; y: number };
+
+type ViewBox = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
+// Deliberately overlap polygons, then trim their outside with the territory
+// edge. This avoids SVG antialias seams inside one model footprint.
+const FUSED_TILE_RADIUS = 1.025;
+const TILE_EDGE_WIDTH = 0.1;
+const SQRT_THREE = Math.sqrt(3);
+
+/**
+ * Responsive SVG territory map. Each deployment owns one stable, contiguous
+ * cluster of discrete hexes; health changes never move that cluster.
+ */
+export function CommunityComputeTerritoryMap({
+  model,
+  selectedDeploymentId,
+  onSelectedDeploymentChange,
+  className,
+  inferenceDeploymentIds = [],
+}: CommunityComputeTerritoryMapProps) {
+  const [internalSelection, setInternalSelection] = React.useState<
+    string | null
+  >(null);
+  const deploymentById = React.useMemo(
+    () =>
+      new Map(
+        model.deployments.map((deployment) => [deployment.id, deployment]),
+      ),
+    [model.deployments],
+  );
+  const previousLayoutRef = React.useRef<ReturnType<
+    typeof layoutCommunityComputeHexTerritories
+  > | null>(null);
+  const layout = React.useMemo(
+    () =>
+      layoutCommunityComputeHexTerritories(
+        model.deployments.map(({ id, cellCount }) => ({ id, cellCount })),
+        { previous: previousLayoutRef.current },
+      ),
+    [model.deployments],
+  );
+  React.useEffect(() => {
+    previousLayoutRef.current = layout;
+  }, [layout]);
+  const fallbackId = model.deployments[0]?.id ?? null;
+  const requestedId = selectedDeploymentId ?? internalSelection;
+  const activeId =
+    requestedId !== null && deploymentById.has(requestedId)
+      ? requestedId
+      : fallbackId;
+  const activeDeployment = activeId
+    ? (deploymentById.get(activeId) ?? null)
+    : null;
+  const viewBox = computeViewBox(layout.cells);
+  const inferenceIds = React.useMemo(
+    () => new Set(inferenceDeploymentIds),
+    [inferenceDeploymentIds],
+  );
+  const [hoveredId, setHoveredId] = React.useState<string | null>(null);
+  const [deploymentSearch, setDeploymentSearch] = React.useState("");
+  const hoveredDeployment = hoveredId
+    ? (deploymentById.get(hoveredId) ?? null)
+    : null;
+
+  function selectDeployment(deploymentId: string) {
+    if (selectedDeploymentId === undefined) {
+      setInternalSelection(deploymentId);
+    }
+    onSelectedDeploymentChange?.(deploymentId);
+  }
+
+  if (model.status === "loading") {
+    return (
+      <section
+        aria-busy="true"
+        aria-label="Community compute map"
+        className={cn(
+          "rounded-xl border border-border/70 bg-muted/10 p-4",
+          className,
+        )}
+        data-testid="community-compute-map-loading"
+      >
+        <div className="h-48 animate-pulse rounded-lg bg-muted/50 motion-reduce:animate-none" />
+        <p className="mt-3 text-sm text-muted-foreground">
+          Mapping community deployments…
+        </p>
+      </section>
+    );
+  }
+
+  if (model.status === "empty" || viewBox === null) {
+    return (
+      <section
+        aria-label="Community compute map"
+        className={cn(
+          "flex min-h-48 flex-col items-center justify-center rounded-xl border border-dashed border-border px-5 py-8 text-center",
+          className,
+        )}
+        data-testid="community-compute-map-empty"
+      >
+        <EmptyHexes />
+        <p className="mt-3 text-sm font-medium">No compute territories yet</p>
+        <p className="mt-1 max-w-sm text-xs leading-relaxed text-muted-foreground">
+          Deployments appear here when members share compute with the community.
+        </p>
+      </section>
+    );
+  }
+
+  return (
+    <section
+      aria-label="Community compute map"
+      className={cn(
+        "min-w-0 space-y-4 rounded-xl border border-border/70 bg-muted/10 p-3",
+        className,
+      )}
+      data-testid="community-compute-territory-map"
+    >
+      <div className="relative flex min-h-72 min-w-0 items-center justify-center overflow-hidden rounded-lg border border-border/50 bg-background/70 p-3 sm:min-h-96">
+        <svg
+          aria-label={`${model.deployments.length} community compute deployments. Select a territory for details.`}
+          className="h-auto max-h-[28rem] w-full overflow-visible"
+          data-testid="community-compute-map-svg"
+          preserveAspectRatio="xMidYMid meet"
+          role="img"
+          viewBox={`${viewBox.x} ${viewBox.y} ${viewBox.width} ${viewBox.height}`}
+        >
+          {layout.territories.map((territory) => {
+            const deployment = deploymentById.get(territory.deploymentId);
+            if (!deployment) return null;
+            const selected = deployment.id === activeId;
+            const inferenceActive = inferenceIds.has(deployment.id);
+            return (
+              // SVG groups have no semantic button equivalent; keyboard selection remains in the adjacent deployment list.
+              // biome-ignore lint/a11y/useSemanticElements: SVG has no native button element.
+              <g
+                aria-label={territoryAccessibleLabel(deployment)}
+                className="cursor-pointer outline-hidden transition-opacity hover:opacity-90 focus-visible:opacity-80"
+                data-deployment-id={deployment.id}
+                data-health={deployment.health}
+                data-cell-count={deployment.cellCount}
+                data-inference-active={inferenceActive}
+                data-selected={selected}
+                data-testid={`community-compute-territory-${testId(deployment.id)}`}
+                key={deployment.id}
+                onClick={() => selectDeployment(deployment.id)}
+                onKeyDown={(event) => {
+                  if (event.key === "Enter" || event.key === " ") {
+                    event.preventDefault();
+                    selectDeployment(deployment.id);
+                  }
+                }}
+                onMouseEnter={() => setHoveredId(deployment.id)}
+                onMouseLeave={() => setHoveredId(null)}
+                role="button"
+                tabIndex={0}
+              >
+                <title>{territoryAccessibleLabel(deployment)}</title>
+                <TerritoryShape
+                  cells={territory.cells}
+                  inferenceActive={inferenceActive}
+                />
+              </g>
+            );
+          })}
+        </svg>
+        {hoveredDeployment ? (
+          <div
+            className="pointer-events-none absolute bottom-3 left-3 max-w-64 rounded-xl border border-border/70 bg-popover/95 px-3 py-2 shadow-lg backdrop-blur-sm"
+            data-testid="community-compute-hover-details"
+          >
+            <p
+              className="truncate text-xs font-semibold"
+              title={hoveredDeployment.modelId}
+            >
+              {shortModelName(hoveredDeployment.modelId)}
+            </p>
+            <p className="mt-0.5 truncate text-2xs text-muted-foreground">
+              {hoveredDeployment.deviceLabel} ·{" "}
+              {formatCapacity(hoveredDeployment.capacityGb)}
+            </p>
+            <p className="mt-1 text-2xs capitalize text-muted-foreground">
+              {inferenceIds.has(hoveredDeployment.id)
+                ? "Simulated inference"
+                : hoveredDeployment.health}{" "}
+              · {hoveredDeployment.cellCount}{" "}
+              {hoveredDeployment.cellCount === 1 ? "cell" : "cells"}
+            </p>
+          </div>
+        ) : null}
+      </div>
+
+      <div className="grid min-w-0 gap-4 lg:grid-cols-[minmax(0,1fr)_minmax(16rem,0.36fr)]">
+        <DeploymentList
+          activeId={activeId}
+          deployments={model.deployments}
+          onSearchChange={setDeploymentSearch}
+          onSelect={selectDeployment}
+          search={deploymentSearch}
+        />
+        {activeDeployment ? (
+          <DeploymentDetails deployment={activeDeployment} />
+        ) : null}
+      </div>
+    </section>
+  );
+}
+
+function TerritoryShape({
+  cells,
+  inferenceActive,
+}: {
+  cells: readonly CommunityComputeHexCell[];
+  inferenceActive: boolean;
+}) {
+  const boundary = hexTerritoryBoundaryEdges(cells);
+  const fillClass = "fill-foreground";
+  const territoryAnimationStyle = inferenceActive
+    ? ({
+        "--mesh-breath-duration": `${5.8 + (stableVisualHash(cells[0]?.deploymentId ?? "") % 7) * 0.24}s`,
+        animationDelay: `${-((stableVisualHash(`${cells[0]?.deploymentId}:phase`) % 37) / 10)}s`,
+      } as React.CSSProperties)
+    : undefined;
+  return (
+    <g>
+      {cells.map((cell) => {
+        const center = axialToPoint(cell.q, cell.r);
+        return (
+          <polygon
+            className={cn(
+              fillClass,
+              "stroke-transparent",
+              inferenceActive &&
+                "animate-mesh-inference motion-reduce:animate-none",
+            )}
+            data-testid="community-compute-tile"
+            key={cell.id}
+            points={hexPoints(center, FUSED_TILE_RADIUS)}
+            style={territoryAnimationStyle}
+          />
+        );
+      })}
+      <path
+        className={cn(
+          "fill-none stroke-background transition-[opacity,stroke-width] duration-200 motion-reduce:transition-none",
+          fillClass,
+        )}
+        d={edgesToPath(boundary)}
+        data-testid="community-compute-territory-boundary"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        // A crisp opaque perimeter cuts an empty gutter between territories.
+        strokeWidth={TILE_EDGE_WIDTH}
+      />
+    </g>
+  );
+}
+
+function edgesToPath(
+  edges: ReturnType<typeof hexTerritoryBoundaryEdges>,
+): string {
+  return edges
+    .map(
+      (edge) =>
+        `M ${edge.start.x} ${edge.start.y} L ${edge.end.x} ${edge.end.y}`,
+    )
+    .join(" ");
+}
+
+function DeploymentList({
+  deployments,
+  activeId,
+  onSearchChange,
+  onSelect,
+  search,
+}: {
+  deployments: readonly CommunityComputeDeployment[];
+  activeId: string | null;
+  onSearchChange: (value: string) => void;
+  onSelect: (id: string) => void;
+  search: string;
+}) {
+  const query = search.trim().toLowerCase();
+  const visibleDeployments = query
+    ? deployments.filter((deployment) =>
+        [deployment.modelId, deployment.deviceLabel]
+          .filter(Boolean)
+          .some((value) => value?.toLowerCase().includes(query)),
+      )
+    : deployments;
+  return (
+    <div className="min-w-0">
+      <div className="mb-2 flex items-center justify-between gap-3">
+        <p className="text-xs font-medium text-muted-foreground">Deployments</p>
+        <span className="text-2xs tabular-nums text-muted-foreground">
+          {visibleDeployments.length} of {deployments.length}
+        </span>
+      </div>
+      <input
+        aria-label="Search deployments"
+        className="mb-2 h-9 w-full rounded-lg border border-input/60 bg-background px-3 text-xs outline-hidden placeholder:text-muted-foreground focus-visible:ring-2 focus-visible:ring-ring"
+        onChange={(event) => onSearchChange(event.target.value)}
+        placeholder="Search models or devices"
+        type="search"
+        value={search}
+      />
+      <ul
+        aria-label="Community compute deployments"
+        className="max-h-72 space-y-1 overflow-y-auto pr-1"
+        data-testid="community-compute-deployment-list"
+      >
+        {visibleDeployments.map((deployment) => {
+          const selected = deployment.id === activeId;
+          return (
+            <li key={deployment.id}>
+              <button
+                aria-pressed={selected}
+                className={cn(
+                  "flex w-full items-center gap-2 rounded-lg border border-transparent px-2.5 py-2 text-left text-xs transition-colors hover:bg-muted/60 focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring",
+                  selected && "border-border bg-muted/70 text-foreground",
+                )}
+                data-testid={`community-compute-deployment-${testId(deployment.id)}`}
+                onClick={() => onSelect(deployment.id)}
+                type="button"
+              >
+                <HealthGlyph health={deployment.health} />
+                <span className="min-w-0 flex-1">
+                  <span className="block truncate font-medium">
+                    {shortModelName(deployment.modelId)}
+                  </span>
+                  <span className="block truncate text-2xs text-muted-foreground">
+                    {deployment.deviceLabel}
+                  </span>
+                </span>
+                <span className="shrink-0 text-2xs capitalize text-muted-foreground">
+                  {deployment.health}
+                </span>
+              </button>
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}
+
+function DeploymentDetails({
+  deployment,
+}: {
+  deployment: CommunityComputeDeployment;
+}) {
+  return (
+    <article
+      aria-live="polite"
+      className="min-w-0 rounded-lg border border-border/60 bg-background/80 p-3"
+      data-testid="community-compute-deployment-details"
+    >
+      <div className="flex items-start gap-2">
+        <HealthGlyph health={deployment.health} />
+        <div className="min-w-0 flex-1">
+          <h3
+            className="truncate text-sm font-semibold"
+            title={deployment.modelId}
+          >
+            {shortModelName(deployment.modelId)}
+          </h3>
+          <p className="mt-0.5 truncate text-xs text-muted-foreground">
+            {deployment.deviceLabel}
+            {deployment.isSelf ? " · This machine" : ""}
+          </p>
+          <p className="mt-0.5 text-2xs capitalize text-muted-foreground">
+            {deployment.health} · {deployment.cellCount}{" "}
+            {deployment.cellCount === 1 ? "cell" : "cells"}
+          </p>
+        </div>
+      </div>
+      {deployment.healthReason ? (
+        <p className="mt-2 text-xs leading-relaxed text-muted-foreground">
+          {deployment.healthReason}
+        </p>
+      ) : null}
+      <dl className="mt-3 grid grid-cols-2 gap-x-3 gap-y-2 text-xs">
+        <Detail
+          label="Shared memory"
+          value={formatCapacity(deployment.capacityGb)}
+        />
+        <Detail label="Model" value={deployment.modelId} />
+        <Detail
+          label="Reported"
+          value={formatReportedAt(deployment.source.reportedAt)}
+        />
+        <Detail
+          label="Model footprint"
+          value={formatCapacity(deployment.source.modelSizeGb ?? null)}
+        />
+      </dl>
+    </article>
+  );
+}
+
+function Detail({ label, value }: { label: string; value: string }) {
+  return (
+    <div className="min-w-0">
+      <dt className="text-2xs text-muted-foreground">{label}</dt>
+      <dd className="mt-0.5 truncate font-medium" title={value}>
+        {value}
+      </dd>
+    </div>
+  );
+}
+
+function HealthGlyph({ health }: { health: CommunityComputeDeploymentHealth }) {
+  const cue = healthCue(health);
+  return (
+    <span
+      aria-hidden="true"
+      className={cn(
+        "flex size-4 shrink-0 items-center justify-center rounded-full border border-foreground/45 text-3xs font-bold leading-none",
+        health === "warming" &&
+          "animate-pulse border-dashed motion-reduce:animate-none",
+        health === "idle" && "border-dotted text-muted-foreground",
+        health === "degraded" && "border-dashed",
+        health === "offline" &&
+          "border-muted-foreground/60 text-muted-foreground",
+        health === "unknown" && "border-dotted text-muted-foreground",
+      )}
+    >
+      {cue.glyph}
+    </span>
+  );
+}
+
+function EmptyHexes() {
+  const centers = [
+    { x: 2, y: 1.75 },
+    { x: 3.58, y: 2.65 },
+    { x: 2, y: 3.55 },
+    { x: 0.42, y: 2.65 },
+  ];
+  return (
+    <svg aria-hidden="true" className="h-14 w-20" viewBox="-0.7 0.5 5.4 4.3">
+      {centers.map((center) => (
+        <polygon
+          className="fill-muted/40 stroke-muted-foreground/40"
+          key={`${center.x}:${center.y}`}
+          points={hexPoints(center, 0.82)}
+          strokeDasharray="2 2"
+          strokeWidth="0.08"
+        />
+      ))}
+    </svg>
+  );
+}
+
+function axialToPoint(q: number, r: number): Point {
+  return { x: SQRT_THREE * (q + r / 2), y: 1.5 * r };
+}
+
+function hexPoints(center: Point, radius: number): string {
+  return Array.from({ length: 6 }, (_, index) => {
+    const angle = ((60 * index - 30) * Math.PI) / 180;
+    return `${center.x + radius * Math.cos(angle)},${center.y + radius * Math.sin(angle)}`;
+  }).join(" ");
+}
+
+function computeViewBox(
+  cells: readonly CommunityComputeHexCell[],
+): ViewBox | null {
+  if (cells.length === 0) return null;
+  const centers = cells.map((cell) => axialToPoint(cell.q, cell.r));
+  const minX = Math.min(...centers.map(({ x }) => x)) - 1.4;
+  const maxX = Math.max(...centers.map(({ x }) => x)) + 1.4;
+  const minY = Math.min(...centers.map(({ y }) => y)) - 1.4;
+  const maxY = Math.max(...centers.map(({ y }) => y)) + 1.4;
+  return {
+    x: minX,
+    y: minY,
+    width: Math.max(2.8, maxX - minX),
+    height: Math.max(2.8, maxY - minY),
+  };
+}
+
+function healthCue(health: CommunityComputeDeploymentHealth): {
+  dashArray?: string;
+  glyph: string;
+  strokeWidth: number;
+} {
+  switch (health) {
+    case "healthy":
+      return { glyph: "✓", strokeWidth: 0.075 };
+    case "warming":
+      return { glyph: "↻", dashArray: "0.2 0.12", strokeWidth: 0.085 };
+    case "idle":
+      return { glyph: "–", dashArray: "0.04 0.14", strokeWidth: 0.08 };
+    case "degraded":
+      return { glyph: "!", dashArray: "0.3 0.12", strokeWidth: 0.11 };
+    case "offline":
+      return { glyph: "×", dashArray: "0.08 0.1", strokeWidth: 0.075 };
+    case "unknown":
+      return { glyph: "?", dashArray: "0.03 0.12", strokeWidth: 0.075 };
+  }
+}
+
+function stableVisualHash(value: string): number {
+  let hash = 2166136261;
+  for (const character of value) {
+    hash ^= character.codePointAt(0) ?? 0;
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
+function shortModelName(modelId: string): string {
+  const tail = modelId.split("/").at(-1) ?? modelId;
+  return tail.length > 34 ? `${tail.slice(0, 31)}…` : tail;
+}
+
+function territoryAccessibleLabel(
+  deployment: CommunityComputeDeployment,
+): string {
+  const capacity = formatCapacity(deployment.capacityGb);
+  return `${deployment.modelId} on ${deployment.deviceLabel}, ${deployment.health}, ${capacity}, ${deployment.cellCount} ${deployment.cellCount === 1 ? "cell" : "cells"}`;
+}
+
+function formatCapacity(value: number | null): string {
+  return value === null
+    ? "Capacity not reported"
+    : `${Math.round(value)} GB shared`;
+}
+
+function formatReportedAt(value: number | null | undefined): string {
+  if (value === null || value === undefined) return "Not reported";
+  const milliseconds = value < 10_000_000_000 ? value * 1000 : value;
+  return new Date(milliseconds).toLocaleString();
+}
+
+function testId(value: string): string {
+  return encodeURIComponent(value).replaceAll("%", "-");
+}
diff --git a/desktop/src/features/mesh-compute/ui/CommunityComputeTutorialPanel.tsx b/desktop/src/features/mesh-compute/ui/CommunityComputeTutorialPanel.tsx
new file mode 100644
index 0000000000..7a97ccdacf
--- /dev/null
+++ b/desktop/src/features/mesh-compute/ui/CommunityComputeTutorialPanel.tsx
@@ -0,0 +1,146 @@
+import { ArrowLeft, ArrowRight, FlaskConical, X } from "lucide-react";
+
+import { Button } from "@/shared/ui/button";
+import { cn } from "@/shared/lib/cn";
+import type { CommunityComputeTutorialFixtureId } from "../communityComputeFixtures";
+
+const STEPS = [
+  {
+    title: "Every territory is a model deployment",
+    body: "Each connected group is one ready model on one contributed device. If one device serves multiple models, each model gets its own territory; another device serving the same model appears separately.",
+  },
+  {
+    title: "Area represents memory",
+    body: "Models snap to four coarse footprints: 1, 2, 4, or 7 cells. The footprint comes from reported model size, or shared device capacity when model size is unavailable.",
+  },
+  {
+    title: "Motion illustrates inference in flight",
+    body: "For this tutorial, breathing territories simulate models handling requests. The live community snapshot cannot yet identify the deployment serving a request, so the live map remains static.",
+  },
+  {
+    title: "The headline measures the pool",
+    body: "Members sharing counts contributors, contributed VRAM is the memory they offered, and VRAM allocated is the reported model footprint—not GPU processing utilization.",
+  },
+  {
+    title: "Health summarizes reported state",
+    body: "The scorecard counts ready, warming, and idle deployments from current status reports. It does not infer utilization, offline devices, replica resilience, or capacity headroom.",
+  },
+] as const;
+
+export function CommunityComputeTutorialPanel({
+  fixtureId,
+  onExit,
+  onFixtureChange,
+  onStepChange,
+  step,
+}: {
+  fixtureId: CommunityComputeTutorialFixtureId;
+  onExit: () => void;
+  onFixtureChange: (fixture: CommunityComputeTutorialFixtureId) => void;
+  onStepChange: (step: number) => void;
+  step: number;
+}) {
+  const current = STEPS[step] ?? STEPS[0];
+  const showDeveloperControls =
+    import.meta.env.DEV || import.meta.env.MODE === "e2e";
+
+  return (
+    <section
+      aria-labelledby="mesh-tutorial-title"
+      className="rounded-2xl border border-foreground/20 bg-foreground/[0.035] p-4"
+      data-testid="community-compute-tutorial-panel"
+    >
+      <div className="flex items-start gap-3">
+        <div className="min-w-0 flex-1">
+          <p className="text-2xs font-semibold uppercase tracking-wide text-muted-foreground">
+            Tutorial · {step + 1} of {STEPS.length}
+          </p>
+          <h2 className="mt-1 text-base font-semibold" id="mesh-tutorial-title">
+            {current.title}
+          </h2>
+          <p className="mt-1 max-w-3xl text-sm leading-relaxed text-muted-foreground">
+            {current.body}
+          </p>
+        </div>
+        <Button
+          aria-label="Exit mesh tutorial"
+          onClick={onExit}
+          size="icon-xs"
+          type="button"
+          variant="ghost"
+        >
+          <X />
+        </Button>
+      </div>
+
+      <div className="mt-4 flex flex-wrap items-center gap-2">
+        <Button
+          disabled={step === 0}
+          onClick={() => onStepChange(step - 1)}
+          size="sm"
+          type="button"
+          variant="outline"
+        >
+          <ArrowLeft /> Back
+        </Button>
+        <Button
+          onClick={() =>
+            step === STEPS.length - 1 ? onStepChange(0) : onStepChange(step + 1)
+          }
+          size="sm"
+          type="button"
+        >
+          {step === STEPS.length - 1 ? "Replay" : "Next"}
+          <ArrowRight />
+        </Button>
+        <fieldset className="ml-1 flex gap-1" aria-label="Tutorial progress">
+          {STEPS.map((item, index) => (
+            <button
+              aria-label={`Go to tutorial step ${index + 1}: ${item.title}`}
+              className={cn(
+                "size-2 rounded-full bg-muted-foreground/25 transition-colors",
+                index === step && "bg-foreground",
+              )}
+              key={item.title}
+              onClick={() => onStepChange(index)}
+              type="button"
+            />
+          ))}
+        </fieldset>
+      </div>
+
+      {showDeveloperControls ? (
+        <div
+          className="mt-4 flex flex-wrap items-center gap-2 border-border/60 border-t pt-3"
+          data-testid="community-compute-dev-controls"
+        >
+          <FlaskConical className="size-3.5 text-muted-foreground" />
+          <label
+            className="text-xs font-medium"
+            htmlFor="mesh-tutorial-scenario"
+          >
+            Preview scenario
+          </label>
+          <select
+            className="h-8 rounded-lg border border-input/50 bg-background px-2 text-xs focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
+            id="mesh-tutorial-scenario"
+            onChange={(event) =>
+              onFixtureChange(
+                event.target.value as CommunityComputeTutorialFixtureId,
+              )
+            }
+            value={fixtureId}
+          >
+            <option value="empty">Empty community</option>
+            <option value="single-device">Single device</option>
+            <option value="small-company">Small company</option>
+            <option value="large-dense-500">500 deployments</option>
+          </select>
+          <span className="text-2xs text-muted-foreground">
+            Development-only · deterministic frontend data
+          </span>
+        </div>
+      ) : null}
+    </section>
+  );
+}
diff --git a/desktop/src/features/mesh-compute/ui/MeshComputeCommunityView.tsx b/desktop/src/features/mesh-compute/ui/MeshComputeCommunityView.tsx
new file mode 100644
index 0000000000..ba14693088
--- /dev/null
+++ b/desktop/src/features/mesh-compute/ui/MeshComputeCommunityView.tsx
@@ -0,0 +1,122 @@
+import { Info, RefreshCw } from "lucide-react";
+
+import { Button } from "@/shared/ui/button";
+import type { MeshSnapshot } from "@/shared/api/tauriMesh";
+import {
+  deriveCommunityComputeMapModel,
+  type CommunityComputeSnapshotInput,
+} from "../communityComputeMapModel";
+import { CommunityComputeHealthScorecard } from "./CommunityComputeHealthScorecard";
+import { CommunityComputeKpiRow } from "./CommunityComputeKpiRow";
+import { CommunityComputeTerritoryMap } from "./CommunityComputeTerritoryMap";
+
+export function MeshComputeCommunityView({
+  communityName,
+  error,
+  onRefresh,
+  simulated,
+  snapshot,
+  tutorialInference = false,
+}: {
+  communityName: string;
+  error: string | null;
+  onRefresh: () => void;
+  simulated: boolean;
+  snapshot: MeshSnapshot | CommunityComputeSnapshotInput | null;
+  tutorialInference?: boolean;
+}) {
+  const model = deriveCommunityComputeMapModel(snapshot);
+  const inferenceDeploymentIds = tutorialInference
+    ? model.deployments
+        .filter(
+          (deployment, index) =>
+            deployment.cellCount > 1 || index % 3 === 0 || index % 7 === 2,
+        )
+        .map((deployment) => deployment.id)
+    : [];
+  const observedAt = (snapshot as MeshSnapshot | null)?.observedAt;
+
+  return (
+    <div className="space-y-5" data-testid="community-compute-view">
+      {simulated ? (
+        <div
+          className="flex items-center gap-2 rounded-xl border border-dashed border-foreground/30 bg-foreground/[0.035] px-3 py-2 text-xs"
+          data-testid="community-compute-simulated-banner"
+        >
+          <Info className="size-3.5" />
+          <span>
+            Simulated mesh for learning and development. Live community data is
+            unchanged.
+          </span>
+        </div>
+      ) : null}
+
+      {error && !simulated ? (
+        <div className="flex items-center justify-between gap-3 rounded-xl border border-destructive/40 bg-destructive/5 px-3 py-2 text-xs text-destructive">
+          <span>
+            Couldn’t load {communityName} compute: {error}
+          </span>
+          <Button onClick={onRefresh} size="xs" type="button" variant="outline">
+            <RefreshCw /> Try again
+          </Button>
+        </div>
+      ) : null}
+
+      <CommunityComputeKpiRow kpis={model.kpis} />
+
+      <div>
+        <div className="mb-2 flex items-end justify-between gap-3">
+          <div>
+            <h2 className="text-lg font-semibold tracking-tight">Model mesh</h2>
+            <p className="text-sm text-muted-foreground">
+              Each territory is one ready model on one device. Area reflects its
+              reported model-memory tier.
+            </p>
+          </div>
+          {!simulated ? (
+            <Button
+              aria-label="Refresh community compute"
+              onClick={onRefresh}
+              size="icon-xs"
+              title="Refresh community compute"
+              type="button"
+              variant="ghost"
+            >
+              <RefreshCw />
+            </Button>
+          ) : null}
+        </div>
+        <CommunityComputeTerritoryMap
+          inferenceDeploymentIds={inferenceDeploymentIds}
+          model={model}
+        />
+        <p className="mt-2 text-2xs text-muted-foreground">
+          {simulated
+            ? "Deterministic tutorial snapshot"
+            : observedAt
+              ? `Recently reported · updated ${formatAge(observedAt)}`
+              : "Recently reported by community members · presence may take up to two minutes to expire"}
+        </p>
+      </div>
+
+      <div>
+        <div className="mb-2">
+          <h2 className="text-lg font-semibold tracking-tight">Mesh health</h2>
+          <p className="text-sm text-muted-foreground">
+            Current ready, warming, and idle states from community status
+            reports.
+          </p>
+        </div>
+        <CommunityComputeHealthScorecard health={model.health} />
+      </div>
+    </div>
+  );
+}
+
+function formatAge(timestamp: number): string {
+  const timestampMs = timestamp < 10_000_000_000 ? timestamp * 1000 : timestamp;
+  const seconds = Math.max(0, Math.round((Date.now() - timestampMs) / 1000));
+  if (seconds < 10) return "just now";
+  if (seconds < 60) return `${seconds}s ago`;
+  return `${Math.floor(seconds / 60)}m ago`;
+}
diff --git a/desktop/src/features/mesh-compute/ui/MeshComputePage.tsx b/desktop/src/features/mesh-compute/ui/MeshComputePage.tsx
new file mode 100644
index 0000000000..574ddb9b86
--- /dev/null
+++ b/desktop/src/features/mesh-compute/ui/MeshComputePage.tsx
@@ -0,0 +1,103 @@
+import * as React from "react";
+import { BookOpen } from "lucide-react";
+
+import { useCommunities } from "@/features/communities/useCommunities";
+import { SettingsSectionHeader } from "@/features/settings/ui/SettingsSectionHeader";
+import { Button } from "@/shared/ui/button";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/shared/ui/tabs";
+import {
+  COMMUNITY_COMPUTE_TUTORIAL_FIXTURES,
+  type CommunityComputeTutorialFixtureId,
+} from "../communityComputeFixtures";
+import { useMeshComputeState } from "../hooks/useMeshComputeState";
+import { CommunityComputeTutorialPanel } from "./CommunityComputeTutorialPanel";
+import { MeshComputeCommunityView } from "./MeshComputeCommunityView";
+import { MeshComputeSettingsCard } from "./MeshComputeSettingsCard";
+import { MeshComputeShareBanner } from "./MeshComputeShareBanner";
+
+export function MeshComputePage() {
+  const { activeCommunity } = useCommunities();
+  const mesh = useMeshComputeState();
+  const [tab, setTab] = React.useState("community");
+  const [tutorialOpen, setTutorialOpen] = React.useState(false);
+  const [tutorialStep, setTutorialStep] = React.useState(0);
+  const [fixtureId, setFixtureId] =
+    React.useState<CommunityComputeTutorialFixtureId>("small-company");
+  const communityName = activeCommunity?.name ?? "this community";
+  const tutorialFixture = COMMUNITY_COMPUTE_TUTORIAL_FIXTURES[fixtureId];
+
+  function toggleTutorial() {
+    if (tutorialOpen) {
+      setTutorialOpen(false);
+      return;
+    }
+    setTab("community");
+    setTutorialOpen(true);
+    setTutorialStep(0);
+    setFixtureId("small-company");
+  }
+
+  return (
+    <section className="min-w-0" data-testid="settings-mesh-compute-page">
+      <SettingsSectionHeader
+        action={
+          <Button
+            aria-pressed={tutorialOpen}
+            data-testid="community-compute-tutorial-button"
+            onClick={toggleTutorial}
+            size="sm"
+            type="button"
+            variant={tutorialOpen ? "secondary" : "outline"}
+          >
+            <BookOpen /> Tutorial
+          </Button>
+        }
+        description={`See what ${communityName} can run and contribute this machine’s spare capacity.`}
+        title="Compute"
+      />
+
+      <div className="space-y-5">
+        {tutorialOpen ? null : (
+          <MeshComputeShareBanner communityName={communityName} mesh={mesh} />
+        )}
+
+        <Tabs onValueChange={setTab} value={tab}>
+          <TabsList className="grid w-full grid-cols-2 sm:w-72">
+            <TabsTrigger data-testid="compute-tab-community" value="community">
+              Community
+            </TabsTrigger>
+            <TabsTrigger data-testid="compute-tab-settings" value="settings">
+              Settings
+            </TabsTrigger>
+          </TabsList>
+
+          <TabsContent className="mt-5 space-y-5" value="community">
+            {tutorialOpen ? (
+              <CommunityComputeTutorialPanel
+                fixtureId={fixtureId}
+                onExit={() => setTutorialOpen(false)}
+                onFixtureChange={setFixtureId}
+                onStepChange={setTutorialStep}
+                step={tutorialStep}
+              />
+            ) : null}
+            <MeshComputeCommunityView
+              communityName={
+                tutorialOpen ? tutorialFixture.title : communityName
+              }
+              error={mesh.error}
+              onRefresh={mesh.refreshSnapshot}
+              simulated={tutorialOpen}
+              snapshot={tutorialOpen ? tutorialFixture.snapshot : mesh.snapshot}
+              tutorialInference={tutorialOpen}
+            />
+          </TabsContent>
+
+          <TabsContent className="mt-8" value="settings">
+            <MeshComputeSettingsCard hideHeader />
+          </TabsContent>
+        </Tabs>
+      </div>
+    </section>
+  );
+}
diff --git a/desktop/src/features/mesh-compute/ui/MeshComputeSettingsCard.tsx b/desktop/src/features/mesh-compute/ui/MeshComputeSettingsCard.tsx
index 940ffc45b0..42dc6e798b 100644
--- a/desktop/src/features/mesh-compute/ui/MeshComputeSettingsCard.tsx
+++ b/desktop/src/features/mesh-compute/ui/MeshComputeSettingsCard.tsx
@@ -68,7 +68,11 @@ const SHARE_COMPUTE_REVEAL_TRANSITION = {
  * group. User-facing copy describes the shared-compute behavior without
  * exposing implementation protocols or raw mesh controls.
  */
-export function MeshComputeSettingsCard() {
+export function MeshComputeSettingsCard({
+  hideHeader = false,
+}: {
+  hideHeader?: boolean;
+} = {}) {
   const shouldReduceMotion = useReducedMotion();
   const { status, error, refresh } = useMeshNodeStatus();
   const [installedModels, setInstalledModels] = React.useState<
@@ -203,10 +207,12 @@ export function MeshComputeSettingsCard() {
 
   return (
     <section className="min-w-0" data-testid="settings-mesh-share-compute">
-      <SettingsSectionHeader
-        title="Share compute"
-        description="Provide compute to your Buzz community. More capacity can increase intelligence and availability of models for agents."
-      />
+      {hideHeader ? null : (
+        <SettingsSectionHeader
+          title="Share compute"
+          description="Provide compute to your Buzz community. More capacity can increase intelligence and availability of models for agents."
+        />
+      )}
 
       {error ? (
         <p className="mb-3 rounded-lg bg-destructive/10 px-3 py-2 text-sm text-destructive">
diff --git a/desktop/src/features/mesh-compute/ui/MeshComputeShareBanner.tsx b/desktop/src/features/mesh-compute/ui/MeshComputeShareBanner.tsx
new file mode 100644
index 0000000000..925e7f181b
--- /dev/null
+++ b/desktop/src/features/mesh-compute/ui/MeshComputeShareBanner.tsx
@@ -0,0 +1,113 @@
+import { Cpu, LoaderCircle } from "lucide-react";
+
+import { Switch } from "@/shared/ui/switch";
+import { cn } from "@/shared/lib/cn";
+import type { useMeshComputeState } from "../hooks/useMeshComputeState";
+
+export function MeshComputeShareBanner({
+  communityName,
+  mesh,
+}: {
+  communityName: string;
+  mesh: ReturnType<typeof useMeshComputeState>;
+}) {
+  const {
+    error,
+    modelToShare,
+    pendingAction,
+    shareSwitchChecked,
+    status,
+    toggle,
+    setSharing,
+  } = mesh;
+  const busy = pendingAction !== null;
+  const statusCopy = shareStatusCopy({
+    communityName,
+    modelToShare,
+    pendingAction,
+    statusModel: status?.modelName ?? status?.modelId ?? null,
+    isConsuming: toggle.isConsuming,
+    isSharing: toggle.isSharing,
+  });
+
+  return (
+    <section
+      className="rounded-2xl border border-border/70 bg-muted/15 px-4 py-3.5"
+      data-testid="compute-share-banner"
+    >
+      <div className="flex min-w-0 items-center gap-3">
+        <span
+          aria-hidden="true"
+          className={cn(
+            "flex size-9 shrink-0 items-center justify-center rounded-xl border border-border/70 bg-background",
+            toggle.isSharing && "border-foreground/30",
+          )}
+        >
+          {busy ? (
+            <LoaderCircle className="size-4 animate-spin motion-reduce:animate-none" />
+          ) : (
+            <Cpu className="size-4" />
+          )}
+        </span>
+        <div className="min-w-0 flex-1">
+          <label
+            className="text-sm font-semibold"
+            htmlFor="compute-share-banner-toggle"
+          >
+            Share this machine
+          </label>
+          <p
+            className="mt-0.5 truncate text-xs text-muted-foreground"
+            data-testid="compute-share-banner-status"
+            title={statusCopy}
+          >
+            {statusCopy}
+          </p>
+        </div>
+        <Switch
+          checked={shareSwitchChecked}
+          data-testid="compute-share-banner-toggle"
+          disabled={busy || (!toggle.isSharing && !modelToShare)}
+          id="compute-share-banner-toggle"
+          onCheckedChange={setSharing}
+        />
+      </div>
+      {error ? (
+        <p className="mt-2 text-xs text-destructive" role="alert">
+          {error}
+        </p>
+      ) : null}
+    </section>
+  );
+}
+
+function shareStatusCopy({
+  communityName,
+  isConsuming,
+  isSharing,
+  modelToShare,
+  pendingAction,
+  statusModel,
+}: {
+  communityName: string;
+  isConsuming: boolean;
+  isSharing: boolean;
+  modelToShare: string | null;
+  pendingAction: "start" | "stop" | null;
+  statusModel: string | null;
+}): string {
+  if (pendingAction === "start") {
+    return `Preparing ${statusModel ?? modelToShare ?? "a model"} for ${communityName}…`;
+  }
+  if (pendingAction === "stop") return "Stopping shared compute…";
+  if (isSharing) {
+    return `${statusModel ?? modelToShare ?? "A model"} is available to ${communityName}`;
+  }
+  if (isConsuming) {
+    return "Using another member’s compute; turn this on to contribute instead";
+  }
+  if (modelToShare) {
+    return `${modelToShare} is ready to contribute to ${communityName}`;
+  }
+  return "Choose a model in Settings before sharing";
+}
diff --git a/desktop/src/features/mesh-compute/ui/SidebarMeshComputeRow.tsx b/desktop/src/features/mesh-compute/ui/SidebarMeshComputeRow.tsx
index 70b2d72dcb..2dcc3da115 100644
--- a/desktop/src/features/mesh-compute/ui/SidebarMeshComputeRow.tsx
+++ b/desktop/src/features/mesh-compute/ui/SidebarMeshComputeRow.tsx
@@ -7,7 +7,6 @@ import { cn } from "@/shared/lib/cn";
 
 import { useMeshComputeState } from "../hooks/useMeshComputeState";
 import type { MeshRowPulse, MeshRowTone } from "../meshRowModel";
-import { MeshComputePopover } from "./MeshComputePopover";
 
 /**
  * The sidebar Shared Compute row.
@@ -97,49 +96,42 @@ export function SidebarMeshComputeRow({
   const mesh = useMeshComputeState();
   const { row, toggle, pendingAction, shareSwitchChecked, setSharing } = mesh;
 
-  // The row offers joining; the popover owns managing. Once this machine is
-  // sharing there is nothing left to invite, and the popover's labelled switch
-  // is the place to stop — a bare unlabelled switch is a poor control for an
-  // action with consequences.
+  // Clicking the row is navigation: Shared Compute opens the community Compute
+  // view. The trailing switch remains a separate action and does not navigate.
   const showJoinToggle = !toggle.isSharing;
 
   return (
     <SidebarMenuItem>
-      <MeshComputePopover
-        mesh={mesh}
-        onOpenComputeSettings={onOpenComputeSettings}
+      <SidebarMenuButton
+        className={cn(
+          "data-[active=true]:font-normal",
+          // Reserve the trailing slot so the label truncates before it runs
+          // under the switch, rather than colliding with it.
+          showJoinToggle && "pr-11 group-data-[collapsible=icon]:!pr-0",
+        )}
+        data-mesh-tone={row.tone}
+        data-testid="sidebar-mesh-compute-row"
+        onClick={onOpenComputeSettings}
+        tooltip={row.tooltip}
+        type="button"
       >
-        <SidebarMenuButton
-          className={cn(
-            "data-[active=true]:font-normal",
-            // Reserve the trailing slot so the label truncates before it runs
-            // under the switch, rather than colliding with it.
-            showJoinToggle && "pr-11 group-data-[collapsible=icon]:!pr-0",
-          )}
-          data-mesh-tone={row.tone}
-          data-testid="sidebar-mesh-compute-row"
-          tooltip={row.tooltip}
-          type="button"
+        <span
+          aria-hidden
+          className="relative flex h-4 w-4 shrink-0 items-center justify-center"
         >
-          <span
-            aria-hidden
-            className="relative flex h-4 w-4 shrink-0 items-center justify-center"
-          >
-            <Waypoints className="h-4 w-4 opacity-80" />
-            {/*
+          <Waypoints className="h-4 w-4 opacity-80" />
+          {/*
               Icon-collapsed only. The label and the dot beside it are both
               clipped in icon mode, so without this the row would lose its status
               signal entirely at exactly the width where the tooltip is the only
               other affordance.
             */}
-            <span className="absolute -right-1 -bottom-1 hidden rounded-full bg-sidebar p-px group-data-[collapsible=icon]:block">
-              <MeshPulseDot pulse={row.pulse} size="small" tone={row.tone} />
-            </span>
+          <span className="absolute -right-1 -bottom-1 hidden rounded-full bg-sidebar p-px group-data-[collapsible=icon]:block">
+            <MeshPulseDot pulse={row.pulse} size="small" tone={row.tone} />
           </span>
-          <SidebarMenuLabel className="opacity-80">
-            {row.label}
-          </SidebarMenuLabel>
-          {/*
+        </span>
+        <SidebarMenuLabel className="opacity-80">{row.label}</SidebarMenuLabel>
+        {/*
             Right-aligned, the same position and mechanism a channel row uses for
             its unread dot (`UnreadDotBadge className="ml-auto"`). Beside the name
             it competed with the label for one optical line; here it reads as this
@@ -148,20 +140,18 @@ export function SidebarMeshComputeRow({
             When the join switch is present the button carries `pr-11`, so the dot
             lands clear of it rather than underneath.
           */}
-          <span className="ml-auto group-data-[collapsible=icon]:hidden">
-            <MeshPulseDot
-              pulse={row.pulse}
-              testId="mesh-row-dot"
-              tone={row.tone}
-            />
-          </span>
-        </SidebarMenuButton>
-      </MeshComputePopover>
+        <span className="ml-auto group-data-[collapsible=icon]:hidden">
+          <MeshPulseDot
+            pulse={row.pulse}
+            testId="mesh-row-dot"
+            tone={row.tone}
+          />
+        </span>
+      </SidebarMenuButton>
 
       {/*
-        A sibling of the button, never a child: `PopoverTrigger asChild` makes the
-        button itself the trigger, so a switch nested inside would be a button
-        within a button and every toggle would also open the popover.
+        A sibling of the navigation button, never a child: nesting this switch
+        would make toggling sharing navigate away from the current view.
       */}
       {showJoinToggle ? (
         <div className="absolute top-1/2 right-2 -translate-y-1/2 group-data-[collapsible=icon]:hidden">
diff --git a/desktop/src/features/settings/ui/SettingsPanels.tsx b/desktop/src/features/settings/ui/SettingsPanels.tsx
index 901c9152b7..5246f4d5d8 100644
--- a/desktop/src/features/settings/ui/SettingsPanels.tsx
+++ b/desktop/src/features/settings/ui/SettingsPanels.tsx
@@ -77,7 +77,7 @@ import { ChannelTemplatesSettingsCard } from "./ChannelTemplatesSettingsCard";
 import { HarnessesSettingsPanel } from "./HarnessesSettingsPanel";
 import { ExperimentalFeaturesCard } from "./ExperimentalFeaturesCard";
 import { KeyboardShortcutsCard } from "./KeyboardShortcutsCard";
-import { MeshComputeSettingsCard } from "@/features/mesh-compute/ui/MeshComputeSettingsCard";
+import { MeshComputePage } from "@/features/mesh-compute/ui/MeshComputePage";
 import { MobilePairingCard } from "./MobilePairingCard";
 import { ModerationQueueCard } from "./ModerationQueueCard";
 import { NotificationSettingsCard } from "./NotificationSettingsCard";
@@ -883,7 +883,7 @@ export function renderSettingsSection(
     case "channel-templates":
       return <ChannelTemplatesSettingsCard />;
     case "compute":
-      return <MeshComputeSettingsCard />;
+      return <MeshComputePage />;
     case "appearance":
       return <ThemeSettingsCard />;
     case "shortcuts":
diff --git a/desktop/src/shared/api/tauriMesh.ts b/desktop/src/shared/api/tauriMesh.ts
index 2206912acd..b4e094c032 100644
--- a/desktop/src/shared/api/tauriMesh.ts
+++ b/desktop/src/shared/api/tauriMesh.ts
@@ -156,6 +156,10 @@ export type MeshSnapshotDevice = {
   models: string[];
   state: MeshDeviceState;
   isSelf: boolean;
+  /** Additive Community View fields. Older desktop/runtime pairs omit these. */
+  memberPubkey?: string | null;
+  reportedAt?: number | null;
+  modelSizeGb?: number | null;
 };
 
 /**
@@ -167,11 +171,17 @@ export type MeshSnapshotDevice = {
  */
 export type MeshSnapshot = {
   sharingDeviceCount: number;
+  /** Unique members with at least one ready serving device, when reported. */
+  contributorMemberCount?: number;
   /** `null` when no sharing device reported a figure — render the count only. */
   sharedCapacityGb: number | null;
+  /** Approximate hosted-model footprint when every contributor reports it. */
+  allocatedCapacityGb?: number | null;
   models: string[];
   devices: MeshSnapshotDevice[];
   includesSelf: boolean;
+  observedAt?: number;
+  freshnessSeconds?: number;
   /**
    * Members in the community right now (NIP-43 roster size).
    *
diff --git a/desktop/src/testing/e2eBridge.ts b/desktop/src/testing/e2eBridge.ts
index 6f5467c39f..9dee1f82c5 100644
--- a/desktop/src/testing/e2eBridge.ts
+++ b/desktop/src/testing/e2eBridge.ts
@@ -1231,6 +1231,8 @@ declare global {
        */
       nodeMode?: "serve" | "client" | null;
       /** Seed host-side serving usage to exercise the "who's using my compute" indicator. */
+      snapshotDevices?: MockMeshSnapshotDevice[];
+      snapshotMemberCount?: number;
       servingUsage?: Partial<{
         inflight: number;
         peakInflight: number;
@@ -3014,6 +3016,18 @@ function resetMockPersonaCatalogEvents(config: E2eConfig | undefined) {
 // in a browser. They deliberately do NOT model real admission, real inference,
 // or real mesh routing — those are proven by the Rust layer-2 tests and the
 // on-hardware layer-1 example. Do not port any of this into production code.
+type MockMeshSnapshotDevice = {
+  deviceId: string | null;
+  label: string;
+  capacityGb: number | null;
+  models: string[];
+  state: "serving" | "loading" | "standby" | "consuming";
+  isSelf: boolean;
+  memberPubkey?: string | null;
+  reportedAt?: number | null;
+  modelSizeGb?: number | null;
+};
+
 type MockServingUsage = {
   inflight: number;
   peakInflight: number;
@@ -3046,6 +3060,8 @@ const mockMeshState: {
   nodeState: "off" | "running";
   nodeMode: "serve" | "client" | null;
   servingUsage: MockServingUsage;
+  snapshotDevices: MockMeshSnapshotDevice[] | null;
+  snapshotMemberCount: number | null;
 } = {
   admitted: true,
   models: [{ id: "Gemma-4-E4B-it-Q4_K_M", name: "Gemma 4 E4B" }],
@@ -3054,6 +3070,8 @@ const mockMeshState: {
   nodeState: "off",
   nodeMode: null,
   servingUsage: { ...ZERO_SERVING_USAGE },
+  snapshotDevices: null,
+  snapshotMemberCount: null,
 };
 
 function resetMockMesh() {
@@ -3064,6 +3082,8 @@ function resetMockMesh() {
   mockMeshState.nodeState = "off";
   mockMeshState.nodeMode = null;
   mockMeshState.servingUsage = { ...ZERO_SERVING_USAGE };
+  mockMeshState.snapshotDevices = null;
+  mockMeshState.snapshotMemberCount = null;
 }
 let mockPersonas: RawPersona[] = [];
 let mockTeams: RawTeam[] = [];
@@ -10253,6 +10273,10 @@ export function maybeInstallE2eTauriMocks() {
       mockMeshState.denyReason = mesh.denyReason;
     if (mesh.nodeState !== undefined) mockMeshState.nodeState = mesh.nodeState;
     if (mesh.nodeMode !== undefined) mockMeshState.nodeMode = mesh.nodeMode;
+    if (mesh.snapshotDevices !== undefined)
+      mockMeshState.snapshotDevices = mesh.snapshotDevices;
+    if (mesh.snapshotMemberCount !== undefined)
+      mockMeshState.snapshotMemberCount = mesh.snapshotMemberCount;
     if (mesh.servingUsage !== undefined)
       mockMeshState.servingUsage = {
         ...mockMeshState.servingUsage,
@@ -10916,19 +10940,54 @@ export function maybeInstallE2eTauriMocks() {
         return meshNodeStatus(mockMeshState.nodeState, mockMeshState.nodeMode);
       case "mesh_serving_usage":
         return mockMeshState.servingUsage;
-      case "mesh_snapshot":
+      case "mesh_snapshot": {
+        const devices =
+          mockMeshState.snapshotDevices ??
+          (mockMeshState.nodeMode === "serve" && mockMeshState.activeModel
+            ? [
+                {
+                  deviceId: "mock-self",
+                  label: "This machine",
+                  capacityGb: 32,
+                  models: [mockMeshState.activeModel.id],
+                  state: "serving" as const,
+                  isSelf: true,
+                  memberPubkey: MOCK_IDENTITY_PUBKEY,
+                  reportedAt: Math.floor(Date.now() / 1000),
+                  modelSizeGb: 3.5,
+                },
+              ]
+            : []);
+        const serving = devices.filter((device) => device.state === "serving");
         return {
-          sharingDeviceCount: mockMeshState.nodeMode === "serve" ? 1 : 0,
-          sharedCapacityGb: mockMeshState.nodeMode === "serve" ? 32 : null,
-          models: mockMeshState.activeModel
-            ? [mockMeshState.activeModel.id]
-            : [],
-          devices: [],
-          includesSelf: mockMeshState.nodeMode === "serve",
-          memberCount: 1,
-          reason:
-            mockMeshState.nodeMode === "serve" ? null : "No one is sharing",
+          sharingDeviceCount: serving.length,
+          contributorMemberCount: new Set(
+            serving.map((device) => device.memberPubkey ?? device.deviceId),
+          ).size,
+          sharedCapacityGb:
+            serving.length > 0
+              ? serving.reduce(
+                  (total, device) => total + (device.capacityGb ?? 0),
+                  0,
+                )
+              : null,
+          allocatedCapacityGb:
+            serving.length > 0 &&
+            serving.every((device) => device.modelSizeGb != null)
+              ? serving.reduce(
+                  (total, device) => total + (device.modelSizeGb ?? 0),
+                  0,
+                )
+              : null,
+          models: [...new Set(serving.flatMap((device) => device.models))],
+          devices,
+          includesSelf: serving.some((device) => device.isSelf),
+          memberCount: mockMeshState.snapshotMemberCount ?? 1,
+          observedAt: Math.floor(Date.now() / 1000),
+          freshnessSeconds: 120,
+          reason: serving.length > 0 ? null : "No one is sharing",
         };
+      }
       case "mesh_live_view":
         return {
           connected: mockMeshState.nodeState === "running",
diff --git a/desktop/tailwind.config.js b/desktop/tailwind.config.js
index 491cd87063..716821f15f 100644
--- a/desktop/tailwind.config.js
+++ b/desktop/tailwind.config.js
@@ -53,10 +53,18 @@ export default {
           "0%, 100%": { opacity: "1" },
           "50%": { opacity: "0.25" },
         },
+        "mesh-breath": {
+          "0%, 100%": { fill: "hsl(var(--foreground))" },
+          "50%": {
+            fill: "color-mix(in oklab, hsl(var(--foreground)) 25%, hsl(var(--background)))",
+          },
+        },
       },
       animation: {
         // Work in flight right now.
         "mesh-activity": "mesh-dim 1s cubic-bezier(0.4, 0, 0.6, 1) infinite",
+        "mesh-inference":
+          "mesh-breath var(--mesh-breath-duration, 4.8s) ease-in-out infinite",
         // A start or stop in flight. Slower: nothing is wrong, and nothing needs
         // a decision.
         "mesh-progress": "mesh-dim 1.8s cubic-bezier(0.4, 0, 0.6, 1) infinite",
diff --git a/desktop/tests/e2e/mesh-compute-screenshots.spec.ts b/desktop/tests/e2e/mesh-compute-screenshots.spec.ts
new file mode 100644
index 0000000000..939feddc6d
--- /dev/null
+++ b/desktop/tests/e2e/mesh-compute-screenshots.spec.ts
@@ -0,0 +1,36 @@
+import { expect, test } from "@playwright/test";
+
+import { installMockBridge } from "../helpers/bridge";
+import { openSettings } from "../helpers/settings";
+import { waitForAnimations } from "../helpers/animations";
+
+test("captures the Community Compute tutorial", async ({ page }) => {
+  await installMockBridge(page);
+  await page.goto("/");
+  await openSettings(page, "compute");
+  await page.getByTestId("community-compute-tutorial-button").click();
+  await expect(
+    page.getByTestId("community-compute-territory-map"),
+  ).toBeVisible();
+  await expect(page.getByTestId("compute-share-banner")).toHaveCount(0);
+  await waitForAnimations(page);
+  await page.getByTestId("settings-panel-compute").screenshot({
+    path: "test-results/mesh-compute/community-tutorial.png",
+  });
+  await page.getByTestId("community-compute-territory-map").screenshot({
+    path: "test-results/mesh-compute/community-map.png",
+  });
+
+  await page.getByLabel("Preview scenario").selectOption("large-dense-500");
+  await expect(
+    page.getByTestId("community-compute-kpi-members-sharing"),
+  ).toContainText("458");
+  await expect(page.locator("[data-cell-count]")).toHaveCount(458);
+  await expect(
+    page.locator('[data-inference-active="true"]').first(),
+  ).toBeVisible();
+  await waitForAnimations(page);
+  await page.getByTestId("settings-panel-compute").screenshot({
+    path: "test-results/mesh-compute/community-dense.png",
+  });
+});
diff --git a/desktop/tests/e2e/mesh-compute.spec.ts b/desktop/tests/e2e/mesh-compute.spec.ts
index c55b9db5d9..37c430bcbb 100644
--- a/desktop/tests/e2e/mesh-compute.spec.ts
+++ b/desktop/tests/e2e/mesh-compute.spec.ts
@@ -12,6 +12,17 @@ type E2eWindow = Window & {
   __BUZZ_E2E_SET_MESH__?: (mesh: {
     nodeState?: "off" | "running";
     nodeMode?: "serve" | "client" | null;
+    snapshotMemberCount?: number;
+    snapshotDevices?: Array<{
+      deviceId: string;
+      label: string;
+      capacityGb: number;
+      models: string[];
+      state: "serving" | "loading" | "standby" | "consuming";
+      isSelf: boolean;
+      memberPubkey?: string;
+      modelSizeGb?: number;
+    }>;
   }) => void;
 };
 
@@ -20,6 +31,7 @@ test("Share compute chooses a model before sharing", async ({ page }) => {
   await installMockBridge(page);
   await page.goto("/");
   await openSettings(page, "compute");
+  await page.getByTestId("compute-tab-settings").click();
 
   const card = page.getByTestId("settings-mesh-share-compute");
   const toggle = page.getByTestId("mesh-share-compute-toggle");
@@ -115,6 +127,7 @@ test("a consuming client can switch to sharing its saved local model", async ({
     });
   });
   await openSettings(page, "compute");
+  await page.getByTestId("compute-tab-settings").click();
 
   const card = page.getByTestId("settings-mesh-share-compute");
   const toggle = page.getByTestId("mesh-share-compute-toggle");
@@ -147,3 +160,134 @@ test("a consuming client can switch to sharing its saved local model", async ({
     },
   });
 });
+
+test("Shared Compute sidebar row opens the Compute community view", async ({
+  page,
+}) => {
+  await installMockBridge(page);
+  await page.goto("/");
+
+  await page.getByTestId("sidebar-mesh-compute-row").click();
+
+  await expect(page.getByTestId("settings-mesh-compute-page")).toBeVisible();
+  await expect(page.getByTestId("compute-tab-community")).toHaveAttribute(
+    "data-state",
+    "active",
+  );
+  await expect(page.getByTestId("community-compute-view")).toBeVisible();
+  await expect(page.getByTestId("mesh-compute-popover")).toHaveCount(0);
+});
+
+test("Community Compute shows live KPIs and the tutorial simulation", async ({
+  page,
+}) => {
+  await installMockBridge(page);
+  await page.goto("/");
+  await page.waitForFunction(
+    () => typeof (window as E2eWindow).__BUZZ_E2E_SET_MESH__ === "function",
+  );
+  await page.evaluate(() => {
+    (window as E2eWindow).__BUZZ_E2E_SET_MESH__?.({
+      snapshotMemberCount: 7,
+      snapshotDevices: [
+        {
+          deviceId: "alpha",
+          label: "Alpha Studio",
+          capacityGb: 64,
+          models: ["qwen-32b"],
+          state: "serving",
+          isSelf: false,
+          memberPubkey: "member-alpha",
+          modelSizeGb: 28,
+        },
+        {
+          deviceId: "beta",
+          label: "Beta Workstation",
+          capacityGb: 32,
+          models: ["gemma-12b"],
+          state: "serving",
+          isSelf: false,
+          memberPubkey: "member-beta",
+          modelSizeGb: 12,
+        },
+      ],
+    });
+  });
+  await openSettings(page, "compute");
+
+  await expect(page.getByTestId("compute-share-banner")).toBeVisible();
+  await expect(
+    page.getByTestId("community-compute-kpi-members-sharing"),
+  ).toContainText("2");
+  await expect(
+    page.getByTestId("community-compute-kpi-contributed-vram"),
+  ).toContainText("96 GB");
+  await expect(
+    page.getByTestId("community-compute-kpi-vram-allocated"),
+  ).toContainText("42%");
+  await expect(
+    page.getByTestId("community-compute-territory-map"),
+  ).toBeVisible();
+  await expect(
+    page.getByTestId("community-compute-deployment-list"),
+  ).toContainText("Alpha Studio");
+  await page.getByLabel("Search deployments").fill("Beta");
+  await expect(
+    page.getByTestId("community-compute-deployment-list"),
+  ).toContainText("Beta Workstation");
+  await expect(
+    page.getByTestId("community-compute-deployment-list"),
+  ).not.toContainText("Alpha Studio");
+  await page.getByLabel("Search deployments").fill("");
+
+  const tutorialButton = page.getByTestId("community-compute-tutorial-button");
+  await tutorialButton.click();
+  await expect(tutorialButton).toHaveAttribute("aria-pressed", "true");
+  await expect(
+    page.getByTestId("community-compute-simulated-banner"),
+  ).toBeVisible();
+  await expect(
+    page.getByTestId("community-compute-tutorial-panel"),
+  ).toContainText("Every territory is a model deployment");
+  await expect(page.getByTestId("compute-share-banner")).toHaveCount(0);
+  const tutorialTile = page
+    .locator('[data-inference-active="true"]')
+    .first()
+    .getByTestId("community-compute-tile")
+    .first();
+  await expect(tutorialTile).toBeVisible();
+  await expect
+    .poll(() =>
+      tutorialTile.evaluate(
+        (element) => getComputedStyle(element).animationName,
+      ),
+    )
+    .toBe("mesh-breath");
+  await page.getByLabel("Preview scenario").selectOption("single-device");
+  await expect(
+    page.getByTestId("community-compute-kpi-members-sharing"),
+  ).toContainText("1");
+  await page.getByRole("button", { name: "Next" }).click();
+  await expect(
+    page.getByTestId("community-compute-tutorial-panel"),
+  ).toContainText("Area represents memory");
+  await page.getByRole("button", { name: "Next" }).click();
+  await expect(
+    page.getByTestId("community-compute-tutorial-panel"),
+  ).toContainText("Motion illustrates inference in flight");
+  const territory = page.locator("[data-cell-count]").first();
+  await territory.click();
+  await expect(territory).toHaveAttribute("data-selected", "true");
+  await territory.hover();
+  await expect(
+    page.getByTestId("community-compute-hover-details"),
+  ).toContainText("Simulated inference");
+  await tutorialButton.click();
+  await expect(tutorialButton).toHaveAttribute("aria-pressed", "false");
+  await expect(
+    page.getByTestId("community-compute-simulated-banner"),
+  ).toHaveCount(0);
+  await expect(
+    page.getByTestId("community-compute-kpi-members-sharing"),
+  ).toContainText("2");
+});

From 6eb65919f1eabd46b3850c15eefab31092dd500b Mon Sep 17 00:00:00 2001
From: Taylor Ho <taylorkmho@gmail.com>
Date: Thu, 6 Aug 2026 11:47:18 -0700
Subject: [PATCH 15/16] feat(identity): recover desktop identity from a
 signed-in phone (#4845)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

**Category:** new-feature
**User Impact:** People who lose a desktop identity can securely restore
it from a signed-in Buzz phone without creating a replacement identity.

**Problem:** A fresh or identity-lost desktop could not recover its
existing full Buzz identity from an already-authorized phone.

**Solution:** Add a SAS-confirmed reverse NIP-AB transfer, durable
desktop import, a dedicated mobile recovery entry point, and clearer
desktop recovery dialogs with tested loading, drag-and-drop, and failure
states.


https://github.com/user-attachments/assets/e9215c9c-80d0-462f-9161-0fa184ca2f74

<details>
<summary>File changes</summary>

**crates/buzz-core/src/pairing/session.rs**
Adds the reverse encrypted payload and source-completion state
transitions used for phone-to-desktop recovery.

**desktop/src-tauri/src/commands/identity.rs**
Exposes the existing guarded identity commit path for recovery imports.

**desktop/src-tauri/src/commands/pairing.rs**
Adds recovery-mode pairing, durable nsec import, start serialization,
stale-task protection, and explicit rejection of unsupported recovery
payloads.

**desktop/src-tauri/src/lib.rs**
Registers the recovery pairing command.

**desktop/src/app/App.tsx**
Refreshes the recovered identity before continuing onboarding.

**desktop/src/features/onboarding/machineOnboarding.ts**
Adds recovery transitions to the onboarding state machine.

**desktop/src/features/onboarding/ui/BackupPasswordTimeline.tsx**
Adds the visual backup-to-password-to-unlock progression.

**desktop/src/features/onboarding/ui/IdentityRecoveryPairing.tsx**
Implements QR generation, copy fallback, SAS confirmation, cancellation,
expiry, and completion UI.

**desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx**
Connects private-key, phone, and backup recovery paths to the onboarding
flow.

**desktop/src/features/onboarding/ui/NostrKeyImportForm.tsx**
Polishes recovery dialogs, backup drag-and-drop, loading stability, and
security copy.

**desktop/src/shared/api/tauri.ts**
Keeps the existing pairing API surface focused on standard
desktop-to-mobile pairing.

**desktop/src/shared/api/tauriPairing.ts**
Adds the recovery pairing invoke without growing the ratcheted shared
API file.

**desktop/src/testing/e2eBridge.ts**
Mocks recovery pairing commands and lifecycle events for browser tests.

**desktop/tests/e2e/identity-lost.spec.ts**
Covers lost-identity entry, QR/copy recovery, SAS, cancellation, expiry,
success, errors, backup import, drag-and-drop, and screenshots.

**desktop/tests/e2e/onboarding.spec.ts**
Verifies recovered identities continue through harness setup without
replacement-key side effects.

**mobile/lib/features/pairing/pairing_page.dart**
Adds recovery-only scanning and explicit identity-handoff warnings.

**mobile/lib/features/pairing/pairing_provider.dart**
Recognizes recovery codes, returns the signed-in nsec after mutual SAS
approval, and waits for desktop completion.

**mobile/lib/features/settings/settings_page.dart**
Accepts the recovery route builder at the app composition boundary to
preserve feature isolation.

**mobile/lib/features/settings/settings_page/connection_section.dart**
Adds the signed-in “Send identity to desktop” settings action.

**mobile/test/features/pairing/pairing_page_test.dart**
Covers recovery-only validation and handoff messaging.

**mobile/test/features/pairing/pairing_provider_test.dart**
Covers reverse payload encryption, confirmation ordering, success,
failure, timeout, and cleanup.

</details>

## Reproduction steps

1. Launch Buzz Desktop with identity-lost state and choose **Recover
from your phone**.
2. Confirm the QR and persistent **Copy pairing code** fallback appear
without layout shift.
3. On a signed-in phone, open **Settings → Send identity to desktop**,
scan or paste the recovery code, and compare the six-digit SAS on both
devices.
4. Confirm on both sides and verify Desktop restores the identity and
continues to harness setup.
5. Repeat from identity-lost state with **Recover from a backup file**;
verify picker and drag-and-drop both advance to password entry and
restore the encrypted backup.
6. Exercise cancellation, mismatched/unsupported codes, expired
sessions, and an invalid backup; verify each returns actionable,
non-stuck UI.

## Screenshots

### Desktop phone recovery — complete flow

| Recovery entry | Pairing QR | Code match | Receiving identity |
|---|---|---|---|
| ![Desktop recovery
entry](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/4845/desktop-phone-01-recovery-entry.png)
| ![Desktop phone recovery
QR](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/4845/desktop-phone-02-qr.png)
| ![Desktop security-code
match](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/4845/desktop-phone-03-sas.png)
| ![Desktop receiving
identity](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/4845/desktop-phone-04-receiving.png)
|

### iOS Simulator — complete handoff flow

| Settings entry | Recovery scanner | Manual recovery code | Code
confirmation |
|---|---|---|---|
| ![iOS Settings entry for Send identity to
desktop](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/4845/ios-01-settings-entry.png)
| ![iOS recovery scanner
entry](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/4845/ios-02-recovery-entry.png)
| ![iOS manual recovery code
entry](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/4845/ios-03-manual-code.png)
| ![iOS security-code
confirmation](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/4845/ios-04-sas-verification.png)
|

### Encrypted backup recovery — adjusted file flow

| File picker | Drag-and-drop target | Password step |
|---|---|---|
| ![Desktop encrypted-backup file
picker](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/4845/desktop-backup-01-file-picker-settled.png)
| ![Desktop encrypted-backup drag-and-drop
target](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/4845/desktop-backup-02-drag-drop.png)
| ![Desktop backup password
step](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/4845/desktop-backup-03-enter-password.png)
|

## Verification

- `cargo test -p buzz-core pairing` — 71 passed
- `just mobile-test` — 1,169 passed
- `pnpm build:e2e && pnpm exec playwright test identity-lost.spec.ts
--project=smoke` — 15 passed
- Full pre-push gates — desktop checks, desktop unit tests, Rust tests,
Tauri checks, and mobile tests passed

---------

Signed-off-by: Taylor Ho <taylorkmho@gmail.com>
Co-authored-by: npub1223z34hd7vtwc6qj4s7flsxkj644nlre2nthu7lrrmkumhu3xddsrx9r6w <52a228d6edf316ec6812ac3c9fc0d696ab59fc7954d77e7be31eedcddf91335b@buzz.block.builderlab.xyz>
Co-authored-by: Carl <acda9e433d19dcd0e6b6840f7f4b98f3a56f1fab98049d444c087019e6d36560@buzz.block.builderlab.xyz>
---
 crates/buzz-core/src/pairing/session.rs       | 110 ++++
 desktop/src-tauri/src/commands/identity.rs    |   2 +-
 desktop/src-tauri/src/commands/pairing.rs     | 517 ++++++++++--------
 .../src/commands/pairing_generation_tests.rs  | 129 +++++
 .../src/commands/pairing_relay_tests.rs       | 104 ++++
 desktop/src-tauri/src/lib.rs                  |   1 +
 desktop/src/app/App.tsx                       |   1 +
 .../features/onboarding/machineOnboarding.ts  |  13 +-
 .../onboarding/ui/BackupPasswordTimeline.tsx  |  60 ++
 .../onboarding/ui/IdentityRecoveryPairing.tsx | 278 ++++++++++
 .../onboarding/ui/MachineOnboardingFlow.tsx   | 180 +++++-
 .../onboarding/ui/NostrKeyImportForm.tsx      | 240 +++++---
 desktop/src/shared/api/tauri.ts               |   2 -
 desktop/src/shared/api/tauriPairing.ts        |   5 +
 desktop/src/testing/e2eBridge.ts              |  11 +
 desktop/tests/e2e/identity-lost.spec.ts       | 295 +++++++++-
 desktop/tests/e2e/onboarding.spec.ts          | 180 +++++-
 mobile/lib/app.dart                           |   7 +-
 mobile/lib/features/pairing/pairing_page.dart |  25 +-
 .../features/pairing/pairing_provider.dart    |  78 ++-
 .../lib/features/settings/settings_page.dart  |  11 +-
 .../settings_page/connection_section.dart     |  17 +-
 .../features/pairing/pairing_page_test.dart   |  90 ++-
 .../pairing/pairing_provider_test.dart        | 203 +++++++
 .../settings/theme_picker_page_test.dart      |  10 +-
 25 files changed, 2192 insertions(+), 377 deletions(-)
 create mode 100644 desktop/src-tauri/src/commands/pairing_generation_tests.rs
 create mode 100644 desktop/src-tauri/src/commands/pairing_relay_tests.rs
 create mode 100644 desktop/src/features/onboarding/ui/IdentityRecoveryPairing.tsx
 create mode 100644 desktop/src/shared/api/tauriPairing.ts

diff --git a/crates/buzz-core/src/pairing/session.rs b/crates/buzz-core/src/pairing/session.rs
index 431b87fcc0..0d43d4d827 100644
--- a/crates/buzz-core/src/pairing/session.rs
+++ b/crates/buzz-core/src/pairing/session.rs
@@ -223,6 +223,48 @@ impl PairingSession {
         Ok(event)
     }
 
+    /// (Source) Process a payload sent back by the target.
+    ///
+    /// This is used by recovery flows where the QR-displaying device requests
+    /// a secret from an already-authorized scanning device.
+    pub fn handle_return_payload(
+        &mut self,
+        event: &Event,
+    ) -> Result<(PayloadType, Zeroizing<String>), PairingError> {
+        self.check_expired()?;
+        self.expect_state(SessionState::Transferring)?;
+        self.expect_role(Role::Source)?;
+        self.validate_event_from_peer(event)?;
+
+        let msg = self.decrypt_message(event)?;
+        match msg {
+            PairingMessage::Payload {
+                payload_type,
+                payload,
+            } => {
+                self.state = SessionState::PayloadExchanged;
+                self.record_event(event);
+                Ok((payload_type, Zeroizing::new(payload)))
+            }
+            other => Err(unexpected("payload", &other)),
+        }
+    }
+
+    /// (Source) Report whether a returned payload was imported successfully.
+    pub fn send_source_complete(&mut self, success: bool) -> Result<Event, PairingError> {
+        self.check_expired()?;
+        self.expect_state(SessionState::PayloadExchanged)?;
+        self.expect_role(Role::Source)?;
+
+        let event = self.build_event(&PairingMessage::Complete { success })?;
+        self.state = if success {
+            SessionState::Completed
+        } else {
+            SessionState::Aborted
+        };
+        Ok(event)
+    }
+
     /// (Source) Build the payload event carrying the secret.
     pub fn send_payload(
         &mut self,
@@ -821,6 +863,74 @@ mod tests {
         assert_eq!(source.state(), SessionState::Completed);
     }
 
+    /// Reverse happy-path: the scanning target returns an nsec and the source
+    /// reports the import result. Duplicate payloads remain single-use.
+    #[test]
+    fn reverse_payload_flow_is_single_use() {
+        let (mut source, qr) = PairingSession::new_source("wss://relay.test".into());
+        let (mut target, offer) = PairingSession::new_target(&qr).expect("target");
+        let source_sas = source.handle_offer(&offer).expect("offer");
+        let sas_confirm = source.confirm_sas().expect("source confirm");
+        assert_eq!(
+            target
+                .handle_sas_confirm(&sas_confirm)
+                .expect("sas-confirm"),
+            source_sas
+        );
+        target.confirm_target_sas().expect("target confirm");
+
+        let payload = target
+            .build_event(&PairingMessage::Payload {
+                payload_type: PayloadType::Nsec,
+                payload: "nsec1recovered".into(),
+            })
+            .expect("return payload");
+        let (payload_type, secret) = source
+            .handle_return_payload(&payload)
+            .expect("handle return payload");
+        assert_eq!(payload_type, PayloadType::Nsec);
+        assert_eq!(*secret, "nsec1recovered");
+        assert_eq!(source.state(), SessionState::PayloadExchanged);
+        assert!(source.handle_return_payload(&payload).is_err());
+
+        let complete = source.send_source_complete(true).expect("source complete");
+        assert_eq!(source.state(), SessionState::Completed);
+        assert!(matches!(
+            target.decrypt_message(&complete).expect("decrypt complete"),
+            PairingMessage::Complete { success: true }
+        ));
+    }
+
+    #[test]
+    fn reverse_payload_import_failure_aborts_both_peers() {
+        let (mut source, qr) = PairingSession::new_source("wss://relay.test".into());
+        let (mut target, offer) = PairingSession::new_target(&qr).expect("target");
+        source.handle_offer(&offer).expect("offer");
+        let sas_confirm = source.confirm_sas().expect("source confirm");
+        target
+            .handle_sas_confirm(&sas_confirm)
+            .expect("sas-confirm");
+        target.confirm_target_sas().expect("target confirm");
+        let payload = target
+            .build_event(&PairingMessage::Payload {
+                payload_type: PayloadType::Nsec,
+                payload: "invalid".into(),
+            })
+            .expect("return payload");
+        source
+            .handle_return_payload(&payload)
+            .expect("handle return payload");
+
+        let complete = source
+            .send_source_complete(false)
+            .expect("failure complete");
+        assert_eq!(source.state(), SessionState::Aborted);
+        assert!(matches!(
+            target.decrypt_message(&complete).expect("decrypt complete"),
+            PairingMessage::Complete { success: false }
+        ));
+    }
+
     /// State machine rejects out-of-order operations.
     #[test]
     fn reject_out_of_order_operations() {
diff --git a/desktop/src-tauri/src/commands/identity.rs b/desktop/src-tauri/src/commands/identity.rs
index bddf2e725a..ec2357b85e 100644
--- a/desktop/src-tauri/src/commands/identity.rs
+++ b/desktop/src-tauri/src/commands/identity.rs
@@ -404,7 +404,7 @@ pub async fn import_identity(
 ///    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(
+pub(crate) fn commit_imported_identity(
     state: &AppState,
     data_dir: &std::path::Path,
     keys: nostr::Keys,
diff --git a/desktop/src-tauri/src/commands/pairing.rs b/desktop/src-tauri/src/commands/pairing.rs
index fc874a0150..aedd67854c 100644
--- a/desktop/src-tauri/src/commands/pairing.rs
+++ b/desktop/src-tauri/src/commands/pairing.rs
@@ -9,7 +9,7 @@ use buzz_core_pkg::pairing::types::{AbortReason, PayloadType};
 use futures_util::{SinkExt, StreamExt};
 use nostr::ToBech32;
 use serde::Serialize;
-use tauri::{AppHandle, Emitter, State};
+use tauri::{AppHandle, Emitter, Manager, State};
 use tokio::sync::mpsc;
 use tokio_tungstenite::{connect_async, tungstenite::Message};
 use tokio_util::sync::CancellationToken;
@@ -33,16 +33,36 @@ struct PairingErrorPayload {
     message: String,
 }
 
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum PairingMode {
+    SendIdentity,
+    RecoverIdentity,
+}
+
+#[derive(Clone)]
+struct PairingTaskContext {
+    mode: PairingMode,
+    generation: Arc<AtomicU64>,
+    generation_fence: Arc<std::sync::Mutex<()>>,
+    task_generation: u64,
+}
+
 /// Managed Tauri state for an active pairing session.
 pub struct PairingHandle {
     session: Arc<tokio::sync::Mutex<Option<PairingSession>>>,
     generation: Arc<AtomicU64>,
+    /// Linearizes cancellation/replacement against recovered identity commits.
+    generation_fence: Arc<std::sync::Mutex<()>>,
+    /// Serializes session setup so an older start cannot resume after relay
+    /// discovery and overwrite a newer session's shared state.
+    start_lock: tokio::sync::Mutex<()>,
     cancel: std::sync::Mutex<Option<CancellationToken>>,
     /// Send JSON-serialized events to the background WS task for relay publication.
     outbound_tx: std::sync::Mutex<Option<mpsc::Sender<String>>>,
     /// Pre-built payload string (contains nsec) to send after SAS confirmation.
     /// Wrapped in Zeroizing so the nsec is cleared from memory on drop.
     payload: std::sync::Mutex<Option<Zeroizing<String>>>,
+    mode: Arc<std::sync::Mutex<PairingMode>>,
 }
 
 impl PairingHandle {
@@ -50,9 +70,12 @@ impl PairingHandle {
         Self {
             session: Arc::new(tokio::sync::Mutex::new(None)),
             generation: Arc::new(AtomicU64::new(0)),
+            generation_fence: Arc::new(std::sync::Mutex::new(())),
+            start_lock: tokio::sync::Mutex::new(()),
             cancel: std::sync::Mutex::new(None),
             outbound_tx: std::sync::Mutex::new(None),
             payload: std::sync::Mutex::new(None),
+            mode: Arc::new(std::sync::Mutex::new(PairingMode::SendIdentity)),
         }
     }
 
@@ -63,21 +86,36 @@ impl PairingHandle {
     }
 }
 
-/// Start a NIP-AB pairing session as the source device.
-///
-/// Creates a `PairingSession`, connects to the relay, and returns the
-/// `nostrpair://` QR URI for the frontend to display. The mobile peer will
-/// receive the desktop's nsec (NIP-OA auth — no token minting needed).
+/// Start a NIP-AB pairing session that sends this desktop identity to mobile.
 #[tauri::command]
 pub async fn start_pairing(
     app: AppHandle,
     state: State<'_, AppState>,
     pairing: State<'_, PairingHandle>,
 ) -> Result<String, String> {
-    let task_generation = pairing
-        .generation
-        .fetch_add(1, Ordering::SeqCst)
-        .wrapping_add(1);
+    start_pairing_session(app, state, pairing, PairingMode::SendIdentity).await
+}
+
+/// Start a recovery session. The fresh desktop shows the QR and receives the
+/// full identity from an already-authorized phone after both users approve SAS.
+#[tauri::command]
+pub async fn start_identity_recovery_pairing(
+    app: AppHandle,
+    state: State<'_, AppState>,
+    pairing: State<'_, PairingHandle>,
+) -> Result<String, String> {
+    start_pairing_session(app, state, pairing, PairingMode::RecoverIdentity).await
+}
+
+async fn start_pairing_session(
+    app: AppHandle,
+    state: State<'_, AppState>,
+    pairing: State<'_, PairingHandle>,
+    mode: PairingMode,
+) -> Result<String, String> {
+    let _start_guard = pairing.start_lock.lock().await;
+    let task_generation =
+        invalidate_pairing_generation(&pairing.generation, &pairing.generation_fence)?;
     if let Some(token) = pairing.cancel.lock().map_err(|e| e.to_string())?.take() {
         token.cancel();
     }
@@ -86,54 +124,52 @@ pub async fn start_pairing(
         let mut session = pairing.session.lock().await;
         *session = None;
     }
-
-    let keys = state.signing_keys()?;
-    let nsec = keys
-        .secret_key()
-        .to_bech32()
-        .map_err(|e| format!("encode nsec: {e}"))?;
-    let pubkey_hex = keys.public_key().to_hex();
+    *pairing.mode.lock().map_err(|e| e.to_string())? = mode;
+    *pairing.payload.lock().map_err(|e| e.to_string())? = None;
 
     let ws_url = relay_ws_url_with_override(&state);
     let http_url = relay_api_base_url_with_override(&state);
-
-    // NIP-43 relays gate connections on membership, so an unpaired peer can't
-    // reach the main relay yet — it must go through the /pair sidecar. Open
-    // relays (no NIP-43) accept the peer directly. We key off the relay's
-    // own NIP-11 declaration of NIP-43 support rather than `auth_required`,
-    // which is also true for plain NIP-42 / NIP-OA relays where the main
-    // relay is reachable.
     let pairing_relay_url = resolve_pairing_relay_url(&ws_url, probe_pairing_relay(&ws_url).await)?;
-
     let (session, qr_payload) = PairingSession::new_source(pairing_relay_url.clone());
-    let qr_uri = encode_qr(&qr_payload);
+    let mut qr_uri = encode_qr(&qr_payload);
+    if mode == PairingMode::RecoverIdentity {
+        qr_uri.push_str("&mode=recover");
+    }
 
-    let payload_json = serde_json::json!({
-        "relayUrl": http_url,
-        "pubkey": pubkey_hex,
-        "nsec": nsec,
-    });
+    if mode == PairingMode::SendIdentity {
+        let keys = state.signing_keys()?;
+        let nsec = keys
+            .secret_key()
+            .to_bech32()
+            .map_err(|e| format!("encode nsec: {e}"))?;
+        let payload_json = serde_json::json!({
+            "relayUrl": http_url,
+            "pubkey": keys.public_key().to_hex(),
+            "nsec": nsec,
+        });
+        *pairing.payload.lock().map_err(|e| e.to_string())? =
+            Some(Zeroizing::new(payload_json.to_string()));
+    }
 
     {
-        let mut s = pairing.session.lock().await;
-        *s = Some(session);
+        let mut active = pairing.session.lock().await;
+        *active = Some(session);
     }
-    *pairing.payload.lock().map_err(|e| e.to_string())? =
-        Some(Zeroizing::new(payload_json.to_string()));
 
     let (outbound_tx, outbound_rx) = mpsc::channel::<String>(16);
     let cancel = CancellationToken::new();
-
     *pairing.outbound_tx.lock().map_err(|e| e.to_string())? = Some(outbound_tx);
     *pairing.cancel.lock().map_err(|e| e.to_string())? = Some(cancel.clone());
 
-    let session_arc = Arc::clone(&pairing.session);
-    let generation = Arc::clone(&pairing.generation);
     tauri::async_runtime::spawn(pairing_ws_task(
         pairing_relay_url,
-        session_arc,
-        generation,
-        task_generation,
+        Arc::clone(&pairing.session),
+        PairingTaskContext {
+            mode,
+            generation: Arc::clone(&pairing.generation),
+            generation_fence: Arc::clone(&pairing.generation_fence),
+            task_generation,
+        },
         cancel,
         outbound_rx,
         app,
@@ -161,27 +197,30 @@ pub async fn confirm_pairing_sas(pairing: State<'_, PairingHandle>) -> Result<()
 
     tx.send(sas_confirm_json)
         .await
-        .map_err(|_| "failed to send sas-confirm")?;
-
-    let payload = pairing
-        .payload
-        .lock()
-        .map_err(|e| e.to_string())?
-        .take()
-        .ok_or("no payload prepared")?;
+        .map_err(|_| "Pairing code expired. Create a new code and try again.")?;
 
-    let payload_json = {
-        let mut guard = pairing.session.lock().await;
-        let session = guard.as_mut().ok_or("no active pairing session")?;
-        let event = session
-            .send_payload(PayloadType::Custom, payload)
-            .map_err(|e| e.to_string())?;
-        event_to_relay_json(&event)
-    };
-
-    tx.send(payload_json)
-        .await
-        .map_err(|_| "failed to send payload")?;
+    let mode = *pairing.mode.lock().map_err(|e| e.to_string())?;
+    if mode == PairingMode::SendIdentity {
+        let payload = pairing
+            .payload
+            .lock()
+            .map_err(|e| e.to_string())?
+            .take()
+            .ok_or("no payload prepared")?;
+
+        let payload_json = {
+            let mut guard = pairing.session.lock().await;
+            let session = guard.as_mut().ok_or("no active pairing session")?;
+            let event = session
+                .send_payload(PayloadType::Custom, payload)
+                .map_err(|e| e.to_string())?;
+            event_to_relay_json(&event)
+        };
+
+        tx.send(payload_json)
+            .await
+            .map_err(|_| "failed to send payload")?;
+    }
 
     Ok(())
 }
@@ -189,6 +228,14 @@ pub async fn confirm_pairing_sas(pairing: State<'_, PairingHandle>) -> Result<()
 /// Cancel the active pairing session.
 #[tauri::command]
 pub async fn cancel_pairing(pairing: State<'_, PairingHandle>) -> Result<(), String> {
+    // Invalidate the task before waiting for its session lock. Recovery may be
+    // blocked on identity persistence after releasing this lock, and must see
+    // cancellation before crossing the durable commit boundary.
+    invalidate_pairing_generation(&pairing.generation, &pairing.generation_fence)?;
+    if let Some(token) = pairing.cancel.lock().map_err(|e| e.to_string())?.take() {
+        token.cancel();
+    }
+
     let abort_json = {
         let mut guard = pairing.session.lock().await;
         if let Some(session) = guard.as_mut() {
@@ -213,11 +260,6 @@ pub async fn cancel_pairing(pairing: State<'_, PairingHandle>) -> Result<(), Str
         }
     }
 
-    pairing.generation.fetch_add(1, Ordering::SeqCst);
-
-    if let Some(token) = pairing.cancel.lock().map_err(|e| e.to_string())?.take() {
-        token.cancel();
-    }
     pairing.clear();
 
     {
@@ -231,8 +273,7 @@ pub async fn cancel_pairing(pairing: State<'_, PairingHandle>) -> Result<(), Str
 async fn pairing_ws_task(
     relay_url: String,
     session: Arc<tokio::sync::Mutex<Option<PairingSession>>>,
-    generation: Arc<AtomicU64>,
-    task_generation: u64,
+    context: PairingTaskContext,
     cancel: CancellationToken,
     mut outbound_rx: mpsc::Receiver<String>,
     app: AppHandle,
@@ -240,26 +281,24 @@ async fn pairing_ws_task(
     if let Err(e) = pairing_ws_task_inner(
         &relay_url,
         &session,
-        &generation,
-        task_generation,
+        &context,
         &cancel,
         &mut outbound_rx,
         &app,
     )
     .await
     {
-        if pairing_task_is_current(&generation, task_generation) {
+        if pairing_task_is_current(&context.generation, context.task_generation) {
             let _ = app.emit("pairing-error", PairingErrorPayload { message: e });
         }
     }
-    clear_pairing_session_if_current(&session, &generation, task_generation).await;
+    clear_pairing_session_if_current(&session, &context.generation, context.task_generation).await;
 }
 
 async fn pairing_ws_task_inner(
     relay_url: &str,
     session: &Arc<tokio::sync::Mutex<Option<PairingSession>>>,
-    generation: &AtomicU64,
-    task_generation: u64,
+    context: &PairingTaskContext,
     cancel: &CancellationToken,
     outbound_rx: &mut mpsc::Receiver<String>,
     app: &AppHandle,
@@ -290,14 +329,14 @@ async fn pairing_ws_task_inner(
     tokio::pin!(hard_timeout);
 
     loop {
-        if !pairing_task_is_current(generation, task_generation) {
+        if !pairing_task_is_current(&context.generation, context.task_generation) {
             break;
         }
 
         tokio::select! {
             _ = cancel.cancelled() => break,
             _ = &mut hard_timeout => {
-                if pairing_task_is_current(generation, task_generation) {
+                if pairing_task_is_current(&context.generation, context.task_generation) {
                     let _ = app.emit("pairing-error", PairingErrorPayload {
                         message: "Session timed out".into(),
                     });
@@ -317,7 +356,7 @@ async fn pairing_ws_task_inner(
                 let Message::Text(text) = msg else { continue };
 
                 if let Some(event) = parse_relay_event(text.as_str(), "pair") {
-                    if !pairing_task_is_current(generation, task_generation) {
+                    if !pairing_task_is_current(&context.generation, context.task_generation) {
                         break;
                     }
 
@@ -325,7 +364,7 @@ async fn pairing_ws_task_inner(
                     let Some(s) = guard.as_mut() else { break };
 
                     if let Ok(reason) = s.handle_abort(&event) {
-                        if pairing_task_is_current(generation, task_generation) {
+                        if pairing_task_is_current(&context.generation, context.task_generation) {
                             let _ = app.emit("pairing-aborted", PairingAbortedPayload {
                                 reason: format!("{reason:?}"),
                             });
@@ -334,28 +373,83 @@ async fn pairing_ws_task_inner(
                     }
 
                     if let Ok(sas) = s.handle_offer(&event) {
-                        if pairing_task_is_current(generation, task_generation) {
+                        if pairing_task_is_current(&context.generation, context.task_generation) {
                             let _ = app.emit("pairing-sas-received", PairingSasPayload { sas });
                         }
                         continue;
                     }
 
-                    match s.handle_complete(&event) {
-                        Ok(()) => {
-                            if pairing_task_is_current(generation, task_generation) {
-                                let _ = app.emit("pairing-complete", serde_json::json!({}));
+                    if context.mode == PairingMode::RecoverIdentity {
+                        if let Ok((payload_type, payload)) = s.handle_return_payload(&event) {
+                            if let Err(message) = validate_recovery_payload_type(payload_type) {
+                                let complete = s
+                                    .send_source_complete(false)
+                                    .map_err(|e| e.to_string())?;
+                                write
+                                    .send(Message::Text(event_to_relay_json(&complete).into()))
+                                    .await
+                                    .map_err(|e| format!("publish complete failed: {e}"))?;
+                                if pairing_task_is_current(
+                                    &context.generation,
+                                    context.task_generation,
+                                ) {
+                                    let _ = app.emit(
+                                        "pairing-error",
+                                        PairingErrorPayload { message },
+                                    );
+                                }
+                                break;
                             }
+
+                            let payload = payload;
+                            drop(guard);
+
+                            let imported = import_recovered_identity(
+                                app,
+                                payload,
+                                &context.generation,
+                                &context.generation_fence,
+                                context.task_generation,
+                            )
+                            .await;
+                            let success = imported.is_ok();
+                            let complete = {
+                                let mut guard = session.lock().await;
+                                if !pairing_task_is_current(
+                                    &context.generation,
+                                    context.task_generation,
+                                ) {
+                                    break;
+                                }
+                                let Some(s) = guard.as_mut() else { break };
+                                s.send_source_complete(success)
+                                    .map_err(|e| e.to_string())?
+                            };
+                            let completion_result = write
+                                .send(Message::Text(event_to_relay_json(&complete).into()))
+                                .await
+                                .map_err(|e| format!("publish complete failed: {e}"));
+                            finish_recovery(imported, completion_result, context, app)?;
                             break;
                         }
-                        Err(ref e) if format!("{e}").contains("success=false") => {
-                            if pairing_task_is_current(generation, task_generation) {
-                                let _ = app.emit("pairing-error", PairingErrorPayload {
-                                    message: "Mobile device reported failure importing credentials".into(),
-                                });
+                    } else {
+                        match s.handle_complete(&event) {
+                            Ok(()) => {
+                                if pairing_task_is_current(&context.generation, context.task_generation) {
+                                    let _ = app.emit("pairing-complete", serde_json::json!({}));
+                                }
+                                break;
                             }
-                            break;
+                            Err(ref e) if format!("{e}").contains("success=false") => {
+                                if pairing_task_is_current(&context.generation, context.task_generation) {
+                                    let _ = app.emit("pairing-error", PairingErrorPayload {
+                                        message: "Mobile device reported failure importing credentials".into(),
+                                    });
+                                }
+                                break;
+                            }
+                            Err(_) => {}
                         }
-                        Err(_) => {}
                     }
                 }
             }
@@ -365,10 +459,111 @@ async fn pairing_ws_task_inner(
     Ok(())
 }
 
+async fn import_recovered_identity(
+    app: &AppHandle,
+    nsec: Zeroizing<String>,
+    generation: &Arc<AtomicU64>,
+    generation_fence: &Arc<std::sync::Mutex<()>>,
+    task_generation: u64,
+) -> Result<(), String> {
+    let app = app.clone();
+    let generation = Arc::clone(generation);
+    let generation_fence = Arc::clone(generation_fence);
+    tokio::task::spawn_blocking(move || {
+        let keys = nostr::Keys::parse(nsec.trim())
+            .map_err(|e| format!("Phone sent an invalid identity: {e}"))?;
+        let state = app.state::<AppState>();
+        let _mutation_guard = state.identity_mutation.lock().map_err(|e| e.to_string())?;
+        commit_recovery_if_current(&generation, &generation_fence, task_generation, || {
+            let data_dir = app
+                .path()
+                .app_data_dir()
+                .map_err(|e| format!("app data dir: {e}"))?;
+            std::fs::create_dir_all(&data_dir).map_err(|e| format!("create app data dir: {e}"))?;
+            let key_path = data_dir.join("identity.key");
+            crate::commands::identity::commit_imported_identity(&state, &data_dir, keys, |keys| {
+                let store =
+                    crate::secret_store::SecretStore::shared(crate::app_state::keyring_service());
+                crate::app_state::persist_imported_identity(store, keys, &key_path, &data_dir)
+            })?;
+            Ok(())
+        })
+    })
+    .await
+    .map_err(|e| format!("identity recovery task failed: {e}"))?
+}
+
+fn ensure_pairing_task_is_current(
+    generation: &AtomicU64,
+    task_generation: u64,
+) -> Result<(), String> {
+    if pairing_task_is_current(generation, task_generation) {
+        Ok(())
+    } else {
+        Err("Pairing session was superseded or cancelled".into())
+    }
+}
+
+fn invalidate_pairing_generation(
+    generation: &AtomicU64,
+    generation_fence: &std::sync::Mutex<()>,
+) -> Result<u64, String> {
+    let _fence = generation_fence.lock().map_err(|e| e.to_string())?;
+    Ok(generation.fetch_add(1, Ordering::SeqCst).wrapping_add(1))
+}
+
+fn commit_recovery_if_current<T>(
+    generation: &AtomicU64,
+    generation_fence: &std::sync::Mutex<()>,
+    task_generation: u64,
+    commit: impl FnOnce() -> Result<T, String>,
+) -> Result<T, String> {
+    let _fence = generation_fence.lock().map_err(|e| e.to_string())?;
+    ensure_pairing_task_is_current(generation, task_generation)?;
+    commit()
+}
+
+fn recovery_result_after_completion(
+    imported: Result<(), String>,
+    _completion_result: Result<(), String>,
+) -> Result<(), String> {
+    // Once the identity is durable, notifying the peer cannot roll it back.
+    imported
+}
+
+fn finish_recovery(
+    imported: Result<(), String>,
+    completion_result: Result<(), String>,
+    context: &PairingTaskContext,
+    app: &AppHandle,
+) -> Result<(), String> {
+    if !pairing_task_is_current(&context.generation, context.task_generation) {
+        return Ok(());
+    }
+
+    match recovery_result_after_completion(imported, completion_result) {
+        Ok(()) => {
+            let _ = app.emit("pairing-complete", serde_json::json!({}));
+        }
+        Err(message) => {
+            let _ = app.emit("pairing-error", PairingErrorPayload { message });
+        }
+    }
+    Ok(())
+}
+
 fn pairing_task_is_current(generation: &AtomicU64, task_generation: u64) -> bool {
     generation.load(Ordering::SeqCst) == task_generation
 }
 
+fn validate_recovery_payload_type(payload_type: PayloadType) -> Result<(), String> {
+    if payload_type == PayloadType::Nsec {
+        Ok(())
+    } else {
+        Err("Mobile device sent an unsupported recovery payload".into())
+    }
+}
+
 async fn clear_pairing_session_if_current(
     session: &Arc<tokio::sync::Mutex<Option<PairingSession>>>,
     generation: &AtomicU64,
@@ -590,143 +785,9 @@ where
 }
 
 #[cfg(test)]
-mod pairing_generation_tests {
-    use std::sync::atomic::{AtomicU64, Ordering};
-    use std::sync::Arc;
-
-    use super::{clear_pairing_session_if_current, PairingSession};
-
-    #[tokio::test]
-    async fn stale_task_does_not_clear_replacement_session() {
-        let (initial, _) = PairingSession::new_source("ws://initial.example".to_string());
-        let session = Arc::new(tokio::sync::Mutex::new(Some(initial)));
-        let generation = AtomicU64::new(1);
-
-        generation.store(2, Ordering::SeqCst);
-        let (replacement, _) = PairingSession::new_source("ws://replacement.example".to_string());
-        *session.lock().await = Some(replacement);
-
-        clear_pairing_session_if_current(&session, &generation, 1).await;
-
-        assert!(session.lock().await.is_some());
-    }
-
-    #[tokio::test]
-    async fn current_task_clears_its_session() {
-        let (active, _) = PairingSession::new_source("ws://active.example".to_string());
-        let session = Arc::new(tokio::sync::Mutex::new(Some(active)));
-        let generation = AtomicU64::new(3);
-
-        clear_pairing_session_if_current(&session, &generation, 3).await;
-
-        assert!(session.lock().await.is_none());
-    }
-}
+#[path = "pairing_generation_tests.rs"]
+mod pairing_generation_tests;
 
 #[cfg(test)]
-mod pairing_relay_tests {
-    use super::{
-        pairing_relay_from_nip11, probe_pairing_relay, resolve_pairing_relay_url, PairingRelay,
-    };
-    use tokio::io::{AsyncReadExt, AsyncWriteExt};
-
-    #[tokio::test]
-    async fn live_nip11_probe_discovers_configured_pairing_relay() {
-        let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
-            .await
-            .expect("bind test NIP-11 server");
-        let addr = listener.local_addr().expect("test server address");
-        let server = tokio::spawn(async move {
-            let (mut stream, _) = listener.accept().await.expect("accept NIP-11 request");
-            let mut request = vec![0; 2048];
-            let bytes_read = stream.read(&mut request).await.expect("read request");
-            let request = String::from_utf8_lossy(&request[..bytes_read]);
-            assert!(request.starts_with("GET / HTTP/1.1"));
-            assert!(request
-                .to_ascii_lowercase()
-                .contains("accept: application/nostr+json"));
-
-            let body = r#"{"pairing_relay_url":"ws://127.0.0.1:5000"}"#;
-            let response = format!(
-                "HTTP/1.1 200 OK\r\nContent-Type: application/nostr+json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
-                body.len()
-            );
-            stream
-                .write_all(response.as_bytes())
-                .await
-                .expect("write response");
-        });
-
-        assert_eq!(
-            probe_pairing_relay(&format!("ws://{addr}")).await,
-            PairingRelay::Configured("ws://127.0.0.1:5000".to_string())
-        );
-        server.await.expect("NIP-11 server task");
-    }
-
-    #[test]
-    fn configured_pairing_relay_takes_precedence_over_legacy_path() {
-        let document = serde_json::json!({
-            "pairing_relay_url": "wss://pairing.buzz.xyz",
-            "supported_nips": [43]
-        });
-
-        assert_eq!(
-            pairing_relay_from_nip11(&document),
-            PairingRelay::Configured("wss://pairing.buzz.xyz".to_string())
-        );
-    }
-
-    #[test]
-    fn invalid_pairing_relay_url_falls_back_to_legacy_path() {
-        let document = serde_json::json!({
-            "pairing_relay_url": "https://pairing.buzz.xyz",
-            "supported_nips": [43]
-        });
-
-        assert_eq!(
-            pairing_relay_from_nip11(&document),
-            PairingRelay::LegacyPath
-        );
-    }
-
-    #[test]
-    fn document_without_pairing_configuration_uses_main_relay() {
-        let document = serde_json::json!({ "supported_nips": [1, 11] });
-
-        assert_eq!(pairing_relay_from_nip11(&document), PairingRelay::MainRelay);
-    }
-
-    #[test]
-    fn configured_pairing_relay_resolves_to_configured_url() {
-        let resolved = resolve_pairing_relay_url(
-            "wss://flint.communities.buzz.xyz",
-            PairingRelay::Configured("wss://pairing.buzz.xyz".to_string()),
-        )
-        .expect("resolve configured pairing relay");
-
-        assert_eq!(resolved, "wss://pairing.buzz.xyz");
-    }
-
-    #[test]
-    fn legacy_pairing_relay_appends_pair_path() {
-        let resolved = resolve_pairing_relay_url(
-            "wss://flint.communities.buzz.xyz/community",
-            PairingRelay::LegacyPath,
-        )
-        .expect("resolve legacy pairing relay");
-
-        assert_eq!(resolved, "wss://flint.communities.buzz.xyz/community/pair");
-    }
-
-    #[test]
-    fn main_relay_pairing_uses_main_relay_url() {
-        let resolved = resolve_pairing_relay_url(
-            "wss://sprout-oss.stage.blox.sqprod.co",
-            PairingRelay::MainRelay,
-        )
-        .expect("resolve main pairing relay");
-
-        assert_eq!(resolved, "wss://sprout-oss.stage.blox.sqprod.co");
-    }
-}
+#[path = "pairing_relay_tests.rs"]
+mod pairing_relay_tests;
diff --git a/desktop/src-tauri/src/commands/pairing_generation_tests.rs b/desktop/src-tauri/src/commands/pairing_generation_tests.rs
new file mode 100644
index 0000000000..8a2291ae86
--- /dev/null
+++ b/desktop/src-tauri/src/commands/pairing_generation_tests.rs
@@ -0,0 +1,129 @@
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+use std::time::Duration;
+
+use super::{
+    clear_pairing_session_if_current, commit_recovery_if_current, invalidate_pairing_generation,
+    recovery_result_after_completion, validate_recovery_payload_type, PairingHandle,
+    PairingSession, PayloadType,
+};
+
+#[tokio::test]
+async fn overlapping_starts_are_serialized() {
+    let pairing = Arc::new(PairingHandle::new());
+    let first_pairing = Arc::clone(&pairing);
+    let (locked_tx, locked_rx) = tokio::sync::oneshot::channel();
+    let first = tokio::spawn(async move {
+        let _guard = first_pairing.start_lock.lock().await;
+        locked_tx.send(()).expect("signal acquired start lock");
+        tokio::time::sleep(Duration::from_millis(50)).await;
+    });
+
+    locked_rx.await.expect("first start acquired lock");
+    assert!(pairing.start_lock.try_lock().is_err());
+    first.await.expect("first start task");
+    assert!(pairing.start_lock.try_lock().is_ok());
+}
+
+#[test]
+fn recovery_rejects_non_nsec_payloads() {
+    assert!(validate_recovery_payload_type(PayloadType::Nsec).is_ok());
+    assert_eq!(
+        validate_recovery_payload_type(PayloadType::Custom).unwrap_err(),
+        "Mobile device sent an unsupported recovery payload"
+    );
+}
+
+#[test]
+fn superseded_recovery_cannot_commit_identity() {
+    let generation = AtomicU64::new(2);
+    let committed = std::sync::atomic::AtomicBool::new(false);
+
+    let generation_fence = std::sync::Mutex::new(());
+    let result = commit_recovery_if_current(&generation, &generation_fence, 1, || {
+        committed.store(true, Ordering::SeqCst);
+        Ok(())
+    });
+
+    assert_eq!(
+        result.unwrap_err(),
+        "Pairing session was superseded or cancelled"
+    );
+    assert!(!committed.load(Ordering::SeqCst));
+}
+
+#[test]
+fn invalidation_after_check_waits_for_identity_commit() {
+    let generation = Arc::new(AtomicU64::new(7));
+    let generation_fence = Arc::new(std::sync::Mutex::new(()));
+    let (checked_tx, checked_rx) = std::sync::mpsc::channel();
+    let (finish_tx, finish_rx) = std::sync::mpsc::channel();
+    let committed = Arc::new(std::sync::atomic::AtomicBool::new(false));
+
+    let recovery_generation = Arc::clone(&generation);
+    let recovery_fence = Arc::clone(&generation_fence);
+    let recovery_committed = Arc::clone(&committed);
+    let recovery = std::thread::spawn(move || {
+        commit_recovery_if_current(&recovery_generation, &recovery_fence, 7, || {
+            checked_tx.send(()).expect("signal generation checked");
+            finish_rx.recv().expect("release identity commit");
+            recovery_committed.store(true, Ordering::SeqCst);
+            Ok(())
+        })
+    });
+
+    checked_rx.recv().expect("generation checked");
+    let invalidation_generation = Arc::clone(&generation);
+    let invalidation_fence = Arc::clone(&generation_fence);
+    let (attempted_tx, attempted_rx) = std::sync::mpsc::channel();
+    let (invalidated_tx, invalidated_rx) = std::sync::mpsc::channel();
+    let invalidation = std::thread::spawn(move || {
+        attempted_tx.send(()).expect("signal invalidation attempt");
+        let next = invalidate_pairing_generation(&invalidation_generation, &invalidation_fence)
+            .expect("invalidate generation");
+        invalidated_tx.send(next).expect("signal invalidated");
+    });
+
+    attempted_rx.recv().expect("invalidation attempted");
+    assert!(invalidated_rx
+        .recv_timeout(Duration::from_millis(50))
+        .is_err());
+    assert!(!committed.load(Ordering::SeqCst));
+
+    finish_tx.send(()).expect("finish identity commit");
+    recovery.join().expect("recovery task").unwrap();
+    assert!(committed.load(Ordering::SeqCst));
+    assert_eq!(invalidated_rx.recv().expect("invalidation completed"), 8);
+    invalidation.join().expect("invalidation task");
+}
+
+#[test]
+fn completion_publish_failure_does_not_undo_successful_import() {
+    assert!(recovery_result_after_completion(Ok(()), Err("socket closed".into())).is_ok());
+}
+
+#[tokio::test]
+async fn stale_task_does_not_clear_replacement_session() {
+    let (initial, _) = PairingSession::new_source("ws://initial.example".to_string());
+    let session = Arc::new(tokio::sync::Mutex::new(Some(initial)));
+    let generation = AtomicU64::new(1);
+
+    generation.store(2, Ordering::SeqCst);
+    let (replacement, _) = PairingSession::new_source("ws://replacement.example".to_string());
+    *session.lock().await = Some(replacement);
+
+    clear_pairing_session_if_current(&session, &generation, 1).await;
+
+    assert!(session.lock().await.is_some());
+}
+
+#[tokio::test]
+async fn current_task_clears_its_session() {
+    let (active, _) = PairingSession::new_source("ws://active.example".to_string());
+    let session = Arc::new(tokio::sync::Mutex::new(Some(active)));
+    let generation = AtomicU64::new(3);
+
+    clear_pairing_session_if_current(&session, &generation, 3).await;
+
+    assert!(session.lock().await.is_none());
+}
diff --git a/desktop/src-tauri/src/commands/pairing_relay_tests.rs b/desktop/src-tauri/src/commands/pairing_relay_tests.rs
new file mode 100644
index 0000000000..f0e765eb9c
--- /dev/null
+++ b/desktop/src-tauri/src/commands/pairing_relay_tests.rs
@@ -0,0 +1,104 @@
+use super::{
+    pairing_relay_from_nip11, probe_pairing_relay, resolve_pairing_relay_url, PairingRelay,
+};
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+
+#[tokio::test]
+async fn live_nip11_probe_discovers_configured_pairing_relay() {
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("bind test NIP-11 server");
+    let addr = listener.local_addr().expect("test server address");
+    let server = tokio::spawn(async move {
+        let (mut stream, _) = listener.accept().await.expect("accept NIP-11 request");
+        let mut request = vec![0; 2048];
+        let bytes_read = stream.read(&mut request).await.expect("read request");
+        let request = String::from_utf8_lossy(&request[..bytes_read]);
+        assert!(request.starts_with("GET / HTTP/1.1"));
+        assert!(request
+            .to_ascii_lowercase()
+            .contains("accept: application/nostr+json"));
+
+        let body = r#"{"pairing_relay_url":"ws://127.0.0.1:5000"}"#;
+        let response = format!(
+                "HTTP/1.1 200 OK\r\nContent-Type: application/nostr+json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
+                body.len()
+            );
+        stream
+            .write_all(response.as_bytes())
+            .await
+            .expect("write response");
+    });
+
+    assert_eq!(
+        probe_pairing_relay(&format!("ws://{addr}")).await,
+        PairingRelay::Configured("ws://127.0.0.1:5000".to_string())
+    );
+    server.await.expect("NIP-11 server task");
+}
+
+#[test]
+fn configured_pairing_relay_takes_precedence_over_legacy_path() {
+    let document = serde_json::json!({
+        "pairing_relay_url": "wss://pairing.buzz.xyz",
+        "supported_nips": [43]
+    });
+
+    assert_eq!(
+        pairing_relay_from_nip11(&document),
+        PairingRelay::Configured("wss://pairing.buzz.xyz".to_string())
+    );
+}
+
+#[test]
+fn invalid_pairing_relay_url_falls_back_to_legacy_path() {
+    let document = serde_json::json!({
+        "pairing_relay_url": "https://pairing.buzz.xyz",
+        "supported_nips": [43]
+    });
+
+    assert_eq!(
+        pairing_relay_from_nip11(&document),
+        PairingRelay::LegacyPath
+    );
+}
+
+#[test]
+fn document_without_pairing_configuration_uses_main_relay() {
+    let document = serde_json::json!({ "supported_nips": [1, 11] });
+
+    assert_eq!(pairing_relay_from_nip11(&document), PairingRelay::MainRelay);
+}
+
+#[test]
+fn configured_pairing_relay_resolves_to_configured_url() {
+    let resolved = resolve_pairing_relay_url(
+        "wss://flint.communities.buzz.xyz",
+        PairingRelay::Configured("wss://pairing.buzz.xyz".to_string()),
+    )
+    .expect("resolve configured pairing relay");
+
+    assert_eq!(resolved, "wss://pairing.buzz.xyz");
+}
+
+#[test]
+fn legacy_pairing_relay_appends_pair_path() {
+    let resolved = resolve_pairing_relay_url(
+        "wss://flint.communities.buzz.xyz/community",
+        PairingRelay::LegacyPath,
+    )
+    .expect("resolve legacy pairing relay");
+
+    assert_eq!(resolved, "wss://flint.communities.buzz.xyz/community/pair");
+}
+
+#[test]
+fn main_relay_pairing_uses_main_relay_url() {
+    let resolved = resolve_pairing_relay_url(
+        "wss://sprout-oss.stage.blox.sqprod.co",
+        PairingRelay::MainRelay,
+    )
+    .expect("resolve main pairing relay");
+
+    assert_eq!(resolved, "wss://sprout-oss.stage.blox.sqprod.co");
+}
diff --git a/desktop/src-tauri/src/lib.rs b/desktop/src-tauri/src/lib.rs
index 2847b87877..4f935631b6 100644
--- a/desktop/src-tauri/src/lib.rs
+++ b/desktop/src-tauri/src/lib.rs
@@ -880,6 +880,7 @@ pub fn run() {
             set_audio_output_device,
             get_audio_output_device,
             start_pairing,
+            start_identity_recovery_pairing,
             confirm_pairing_sas,
             cancel_pairing,
             apply_workspace,
diff --git a/desktop/src/app/App.tsx b/desktop/src/app/App.tsx
index 811da043f9..0f311f3a65 100644
--- a/desktop/src/app/App.tsx
+++ b/desktop/src/app/App.tsx
@@ -706,6 +706,7 @@ function MachineBootstrap({ sharedIdentity }: { sharedIdentity: boolean }) {
       <MachineOnboardingFlow
         complete={completeMachineOnboarding}
         continueWithIdentity={machine.continueWithIdentity}
+        continueWithRecoveredIdentity={machine.continueWithRecoveredIdentity}
         identityLost={machine.identityLost}
         initialPage={machineInitialPage}
         navigateAfterComplete={navigateAfterOnboarding}
diff --git a/desktop/src/features/onboarding/machineOnboarding.ts b/desktop/src/features/onboarding/machineOnboarding.ts
index 8bc4cadaa9..affdf72009 100644
--- a/desktop/src/features/onboarding/machineOnboarding.ts
+++ b/desktop/src/features/onboarding/machineOnboarding.ts
@@ -185,6 +185,12 @@ export function useMachineOnboardingState({
     continuingPubkeyRef.current = pubkey;
   }, []);
 
+  const continueWithRecoveredIdentity = React.useCallback((pubkey: string) => {
+    continuingPubkeyRef.current = pubkey;
+    setBootedLost(false);
+    setBootedLocked(false);
+  }, []);
+
   const reopen = React.useCallback(() => {
     clearMachineOnboardingCompletion(currentPubkey);
     setCompletedPubkey((pubkey) => (pubkey === currentPubkey ? null : pubkey));
@@ -224,7 +230,11 @@ export function useMachineOnboardingState({
       continuingPubkeyRef.current !== currentPubkey)
   ) {
     stage = "blocking";
-  } else if (identityLost || !hasCompletedCurrentPubkey) {
+  } else if (
+    identityLost ||
+    continuingPubkeyRef.current === currentPubkey ||
+    !hasCompletedCurrentPubkey
+  ) {
     stage = "onboarding";
   } else {
     stage = "ready";
@@ -233,6 +243,7 @@ export function useMachineOnboardingState({
   return {
     complete,
     continueWithIdentity,
+    continueWithRecoveredIdentity,
     currentPubkey,
     identityLost,
     queryClient,
diff --git a/desktop/src/features/onboarding/ui/BackupPasswordTimeline.tsx b/desktop/src/features/onboarding/ui/BackupPasswordTimeline.tsx
index 610c104d95..555d6e1365 100644
--- a/desktop/src/features/onboarding/ui/BackupPasswordTimeline.tsx
+++ b/desktop/src/features/onboarding/ui/BackupPasswordTimeline.tsx
@@ -46,6 +46,66 @@ const TIMELINE_BOTTOM_DOT_TRANSITIONS = TIMELINE_CONNECTOR_DOTS.map(
   }),
 );
 
+export function BackupFileUnlockPreview() {
+  const reduceMotion = useReducedMotion() ?? false;
+
+  return (
+    <div
+      aria-hidden
+      className="mx-auto flex w-[min(28rem,calc(100vw-5rem))] flex-col items-center text-foreground/75"
+      data-testid="backup-file-unlock-preview"
+    >
+      <TimelineDots
+        reduceMotion={reduceMotion}
+        transitions={TIMELINE_TOP_DOT_TRANSITIONS}
+      />
+      <div
+        className="flex items-center justify-center gap-2 py-1"
+        data-testid="backup-file-key-dots"
+      >
+        {BACKUP_KEY_DOTS.map((dot) => (
+          <span
+            className="block size-2 rounded-full bg-foreground/85"
+            key={`preview-${dot}`}
+          />
+        ))}
+      </div>
+      <TimelineDots
+        reduceMotion={reduceMotion}
+        transitions={TIMELINE_BOTTOM_DOT_TRANSITIONS}
+      />
+      <LockOpen
+        className="size-9"
+        data-testid="backup-file-unlock-preview-icon"
+      />
+    </div>
+  );
+}
+
+function TimelineDots({
+  reduceMotion,
+  transitions,
+}: {
+  reduceMotion: boolean;
+  transitions: ReadonlyArray<
+    typeof TIMELINE_DOT_TRANSITION & { delay: number }
+  >;
+}) {
+  return (
+    <div className="my-3 flex h-12 flex-col items-center 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={dot}
+          transition={reduceMotion ? undefined : transitions[index]}
+        />
+      ))}
+    </div>
+  );
+}
+
 /**
  * Decorative timeline shared by backup creation and encrypted-backup restore.
  * Backup creation reads key → password → lock; restore reads encrypted file →
diff --git a/desktop/src/features/onboarding/ui/IdentityRecoveryPairing.tsx b/desktop/src/features/onboarding/ui/IdentityRecoveryPairing.tsx
new file mode 100644
index 0000000000..5cca7c1bf5
--- /dev/null
+++ b/desktop/src/features/onboarding/ui/IdentityRecoveryPairing.tsx
@@ -0,0 +1,278 @@
+import * as React from "react";
+import { listen } from "@tauri-apps/api/event";
+import {
+  Check,
+  Copy,
+  LoaderCircle,
+  RefreshCw,
+  ShieldCheck,
+  TriangleAlert,
+  X,
+} from "lucide-react";
+
+import { cancelPairing, confirmPairingSas } from "@/shared/api/tauri";
+import { startIdentityRecoveryPairing } from "@/shared/api/tauriPairing";
+import { writeTextToClipboard } from "@/shared/lib/clipboard";
+import { Button } from "@/shared/ui/button";
+import { StyledQrCode } from "@/shared/ui/styled-qr-code";
+
+type Step = "loading" | "qr" | "sas" | "receiving" | "done" | "error";
+
+// Refresh before the pairing relay's two-minute connection cap so Desktop never
+// leaves a code on screen after its publishing channel has closed.
+const QR_REFRESH_MS = 90_000;
+
+function recoveryErrorMessage(message: string): string {
+  const normalized = message.toLowerCase();
+  if (
+    normalized.includes("sas-confirm") ||
+    normalized.includes("relay connection closed") ||
+    normalized.includes("websocket") ||
+    normalized.includes("expired") ||
+    normalized.includes("timed out")
+  ) {
+    return "This pairing code expired or lost its connection. Create a new code and try again.";
+  }
+  return message;
+}
+
+export function IdentityRecoveryPairing({
+  onRecovered,
+  onStepChange,
+}: {
+  onRecovered: () => Promise<void>;
+  onStepChange?: (step: Step) => void;
+}) {
+  const [step, setStep] = React.useState<Step>("loading");
+  const [qrUri, setQrUri] = React.useState<string | null>(null);
+  const [sas, setSas] = React.useState<string | null>(null);
+  const [error, setError] = React.useState<string | null>(null);
+  const [copied, setCopied] = React.useState(false);
+  const active = React.useRef(true);
+  const copyTimer = React.useRef<number | null>(null);
+
+  React.useEffect(() => {
+    onStepChange?.(step);
+  }, [onStepChange, step]);
+
+  const start = React.useCallback(async () => {
+    active.current = true;
+    setStep("loading");
+    setError(null);
+    setSas(null);
+    setQrUri(null);
+    setCopied(false);
+    try {
+      setQrUri(await startIdentityRecoveryPairing());
+      setStep("qr");
+    } catch (cause) {
+      setError(
+        cause instanceof Error ? cause.message : "Could not start recovery.",
+      );
+      setStep("error");
+    }
+  }, []);
+
+  React.useEffect(() => {
+    void start();
+    const unlisteners: Array<() => void> = [];
+    let disposed = false;
+    listen<{ sas: string }>("pairing-sas-received", ({ payload }) => {
+      if (!disposed && active.current) {
+        setSas(payload.sas);
+        setStep("sas");
+      }
+    }).then((unlisten) => (disposed ? unlisten() : unlisteners.push(unlisten)));
+    listen("pairing-complete", () => {
+      if (!disposed && active.current) {
+        active.current = false;
+        setStep("done");
+        void onRecovered();
+      }
+    }).then((unlisten) => (disposed ? unlisten() : unlisteners.push(unlisten)));
+    listen<{ message: string }>("pairing-error", ({ payload }) => {
+      if (!disposed && active.current) {
+        active.current = false;
+        setError(recoveryErrorMessage(payload.message));
+        setStep("error");
+      }
+    }).then((unlisten) => (disposed ? unlisten() : unlisteners.push(unlisten)));
+    listen<{ reason: string }>("pairing-aborted", ({ payload }) => {
+      if (!disposed && active.current) {
+        active.current = false;
+        setError(`Recovery stopped: ${payload.reason}`);
+        setStep("error");
+      }
+    }).then((unlisten) => (disposed ? unlisten() : unlisteners.push(unlisten)));
+    return () => {
+      disposed = true;
+      active.current = false;
+      for (const unlisten of unlisteners) unlisten();
+      if (copyTimer.current !== null) window.clearTimeout(copyTimer.current);
+      void cancelPairing();
+    };
+  }, [onRecovered, start]);
+
+  React.useEffect(() => {
+    if (step !== "qr") return;
+    const timer = window.setTimeout(() => void start(), QR_REFRESH_MS);
+    return () => window.clearTimeout(timer);
+  }, [start, step]);
+
+  async function copyPairingCode() {
+    if (!qrUri) return;
+    try {
+      await writeTextToClipboard(qrUri);
+      setCopied(true);
+      if (copyTimer.current !== null) window.clearTimeout(copyTimer.current);
+      copyTimer.current = window.setTimeout(() => setCopied(false), 2_000);
+    } catch {
+      setError("Could not copy the pairing code. Try again.");
+    }
+  }
+
+  async function deny() {
+    active.current = false;
+    await cancelPairing().catch(() => {});
+    setError("The codes didn't match. Pairing was canceled.");
+    setStep("error");
+  }
+
+  async function confirm() {
+    setStep("receiving");
+    try {
+      await confirmPairingSas();
+    } catch (cause) {
+      if (!active.current) return;
+      setError(
+        recoveryErrorMessage(
+          cause instanceof Error
+            ? cause.message
+            : "Could not confirm recovery.",
+        ),
+      );
+      setStep("error");
+    }
+  }
+
+  return (
+    <div
+      className="mb-4 flex w-fit max-w-full flex-col items-stretch gap-3 rounded-xl border border-foreground/15 bg-background/55 p-4"
+      data-testid="identity-recovery-pairing"
+    >
+      <div
+        className="flex min-h-[266px] w-[266px] shrink-0 items-center justify-center rounded-lg border border-border/70 bg-white p-3"
+        data-testid="identity-recovery-qr-container"
+      >
+        {step === "qr" && qrUri ? (
+          <StyledQrCode
+            animate
+            centerImageSrc="/app-icon@2x.png"
+            data-testid="identity-recovery-qr"
+            size={240}
+            title="Desktop identity recovery QR code"
+            value={qrUri}
+          />
+        ) : step === "sas" && sas ? (
+          <div className="flex max-w-60 flex-col items-center gap-3 py-2 text-center text-foreground">
+            <ShieldCheck className="h-10 w-10 text-primary" />
+            <p className="text-sm font-medium">
+              Does this code match your phone?
+            </p>
+            <div className="rounded-xl border-2 border-primary/30 bg-primary/5 px-5 py-3">
+              <p
+                className="font-mono text-3xl font-bold tracking-[0.25em]"
+                data-testid="identity-recovery-sas"
+              >
+                {sas.slice(0, 3)} {sas.slice(3)}
+              </p>
+            </div>
+            <p className="text-xs text-muted-foreground">
+              This gives this desktop permanent access to your Buzz identity.
+              Only continue if you trust it.
+            </p>
+            <div className="flex w-full flex-col gap-2">
+              <Button
+                className="flex-1"
+                data-testid="confirm-identity-recovery-sas"
+                onClick={() => void confirm()}
+              >
+                <Check className="mr-1.5 h-4 w-4" />
+                Codes match
+              </Button>
+              <Button
+                className="flex-1"
+                data-testid="deny-identity-recovery-sas"
+                onClick={() => void deny()}
+                variant="outline"
+              >
+                <X className="mr-1.5 h-4 w-4" />
+                Cancel
+              </Button>
+            </div>
+          </div>
+        ) : step === "done" ? (
+          <div className="flex flex-col items-center gap-3 text-foreground">
+            <div className="flex h-12 w-12 items-center justify-center rounded-full bg-green-100 dark:bg-green-900/30">
+              <Check className="h-6 w-6 text-green-600 dark:text-green-400" />
+            </div>
+            <p className="text-sm font-medium">Identity received securely</p>
+          </div>
+        ) : step === "error" ? (
+          <div className="flex max-w-52 flex-col items-center gap-3 text-center text-foreground">
+            <TriangleAlert className="h-6 w-6 text-destructive" />
+            <p className="text-sm text-destructive">{error}</p>
+            <Button onClick={() => void start()} size="sm" variant="outline">
+              <RefreshCw className="mr-1.5 h-4 w-4" />
+              Try again
+            </Button>
+          </div>
+        ) : (
+          <div className="flex flex-col items-center gap-3 text-foreground">
+            <LoaderCircle className="h-6 w-6 animate-spin text-muted-foreground" />
+            <p className="text-sm text-muted-foreground">
+              {step === "receiving"
+                ? "Receiving identity from mobile device..."
+                : "Starting pairing..."}
+            </p>
+          </div>
+        )}
+      </div>
+      {step === "loading" || (step === "qr" && qrUri) ? (
+        <Button
+          className="w-full border-foreground/20 bg-white text-foreground shadow-none hover:bg-black/5"
+          data-testid="copy-identity-recovery-code"
+          disabled={step === "loading"}
+          onClick={() => void copyPairingCode()}
+          size="sm"
+          type="button"
+          variant="outline"
+        >
+          {step === "loading" ? (
+            <LoaderCircle className="mr-1.5 h-4 w-4 animate-spin" />
+          ) : copied ? (
+            <Check className="mr-1.5 h-4 w-4" />
+          ) : (
+            <Copy className="mr-1.5 h-4 w-4" />
+          )}
+          {step === "loading"
+            ? "Generating pairing code..."
+            : copied
+              ? "Copied"
+              : "Copy pairing code"}
+        </Button>
+      ) : null}
+      {step === "qr" && error ? (
+        <p className="max-w-[266px] text-center text-xs text-destructive">
+          {error}
+        </p>
+      ) : null}
+      {step === "qr" || step === "loading" ? (
+        <p className="max-w-[266px] text-sm leading-5 text-foreground/75">
+          On your phone, open Settings → Send identity to desktop. This code
+          expires shortly and works once.
+        </p>
+      ) : null}
+    </div>
+  );
+}
diff --git a/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx b/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
index 693d1af058..c0cc2d8f79 100644
--- a/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
+++ b/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
@@ -10,6 +10,12 @@ import {
 } from "@/shared/api/tauriIdentity";
 import type { IdentityStorage } from "@/shared/api/types";
 import { Button } from "@/shared/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogTitle,
+} from "@/shared/ui/dialog";
 import { StartupWindowDragRegion } from "@/shared/ui/StartupWindowDragRegion";
 import { BackupStep } from "./BackupStep";
 import { DefaultConfigStep } from "./DefaultConfigStep";
@@ -20,12 +26,14 @@ import {
   useEncryptedBackupSession,
 } from "./EncryptedBackupCreator";
 import { IdentityKeyHelpDialog } from "./IdentityKeyHelpDialog";
+import { IdentityRecoveryPairing } from "./IdentityRecoveryPairing";
 import { LandingBees } from "./LandingBees";
 import {
   NostrKeyImportForm,
   type NostrKeyImportStage,
 } from "./NostrKeyImportForm";
 import {
+  ONBOARDING_INK_ICON_CLASS,
   ONBOARDING_LANDING_CTA_CLASS,
   ONBOARDING_SECONDARY_CTA_CLASS,
   OnboardingChrome,
@@ -53,6 +61,7 @@ export type PostOnboardingNavigation = {
 export function MachineOnboardingFlow({
   complete,
   continueWithIdentity,
+  continueWithRecoveredIdentity,
   identityLost,
   initialPage,
   queryClient,
@@ -60,6 +69,7 @@ export function MachineOnboardingFlow({
 }: {
   complete: (pubkey?: string) => void;
   continueWithIdentity: (pubkey: string) => void;
+  continueWithRecoveredIdentity: (pubkey: string) => void;
   identityLost: boolean;
   initialPage?: MachineOnboardingPage;
   queryClient: QueryClient;
@@ -79,6 +89,10 @@ export function MachineOnboardingFlow({
   const [identityWasImported, setIdentityWasImported] = React.useState(false);
   const [keyImportStage, setKeyImportStage] =
     React.useState<NostrKeyImportStage>("key-entry");
+  const [keyImportDialog, setKeyImportDialog] = React.useState<
+    "backup" | "phone" | null
+  >(null);
+  const [phoneRecoveryStep, setPhoneRecoveryStep] = React.useState("loading");
   const [selectedPubkey, setSelectedPubkey] = React.useState<string | null>(
     null,
   );
@@ -128,6 +142,26 @@ export function MachineOnboardingFlow({
     }
   }, [queryClient]);
 
+  const loadRecoveredIdentity = React.useCallback(async () => {
+    setIsPending(true);
+    setError(null);
+    try {
+      const identity = await getIdentity();
+      continueWithRecoveredIdentity(identity.pubkey);
+      queryClient.setQueryData(["identity"], identity);
+      setIdentityWasImported(true);
+      setSelectedPubkey(identity.pubkey);
+      setIdentityStorage(identity.storage);
+      setPage("setup");
+    } catch (cause) {
+      setError(
+        cause instanceof Error ? cause.message : "Failed to load identity",
+      );
+    } finally {
+      setIsPending(false);
+    }
+  }, [continueWithRecoveredIdentity, queryClient]);
+
   const replaceLostIdentity = React.useCallback(async () => {
     const confirmed = window.confirm(
       "This will create a new identity and abandon your previous key. This cannot be undone. Continue?",
@@ -243,6 +277,7 @@ export function MachineOnboardingFlow({
                   className={`${ONBOARDING_SECONDARY_CTA_CLASS} px-5`}
                   disabled={isPending}
                   onClick={() => {
+                    setKeyImportDialog(null);
                     setKeyImportStage("key-entry");
                     setPage("key-import");
                   }}
@@ -265,7 +300,7 @@ export function MachineOnboardingFlow({
             >
               <motion.div
                 animate={{ opacity: 1, y: 0 }}
-                className="shrink-0"
+                className="relative z-10 shrink-0"
                 initial={reduceMotion ? false : { opacity: 0, y: 10 }}
                 key={keyImportStage}
                 transition={{
@@ -276,31 +311,132 @@ export function MachineOnboardingFlow({
                 <h1 className="text-title font-normal text-foreground">
                   {keyImportStage === "backup-password"
                     ? "Unlock your account"
-                    : identityLost
-                      ? "Re-import your key"
-                      : "Enter your private key"}
+                    : "Enter your private key"}
                 </h1>
-                <p className="mt-5 max-w-[440px] text-sm leading-6 text-foreground/80">
-                  {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 className="mt-5 max-w-[440px] text-sm leading-6 text-foreground/80">
+                  {keyImportStage === "backup-password" ? (
+                    "Enter your backup password to restore your identity."
+                  ) : (
+                    <p>
+                      Paste your private key to sign in to Buzz. You can also
+                      use a{" "}
+                      <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 disabled:opacity-60"
+                        data-testid="nostr-import-file-button"
+                        disabled={isPending}
+                        onClick={() => setKeyImportDialog("backup")}
+                        type="button"
+                      >
+                        backup file
+                      </button>
+                      , 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 disabled:opacity-60"
+                        data-testid="nostr-import-phone-link"
+                        disabled={isPending}
+                        onClick={() => setKeyImportDialog("phone")}
+                        type="button"
+                      >
+                        recover from your phone
+                      </button>
+                      .
+                    </p>
+                  )}
+                </div>
               </motion.div>
               <div className="buzz-onboarding-key-import-position w-full">
-                <NostrKeyImportForm
-                  backLabel={identityLost ? "Start new identity" : "Back"}
-                  onBack={
-                    identityLost
-                      ? () => void replaceLostIdentity()
-                      : () => setPage("identity")
-                  }
-                  onImport={importExistingIdentity}
-                  onStageChange={setKeyImportStage}
-                  variant="spotlight"
-                />
+                <div className="flex flex-col items-center">
+                  <NostrKeyImportForm
+                    backLabel="Back"
+                    onBack={() => {
+                      setKeyImportStage("key-entry");
+                      if (identityLost) {
+                        return;
+                      }
+                      setPage("identity");
+                    }}
+                    onImport={importExistingIdentity}
+                    onStageChange={setKeyImportStage}
+                    showBack={!identityLost}
+                    variant="spotlight"
+                  />
+                  {identityLost && keyImportStage === "key-entry" ? (
+                    <Button
+                      className={`${ONBOARDING_SECONDARY_CTA_CLASS} mt-2 px-5`}
+                      onClick={() => void replaceLostIdentity()}
+                      type="button"
+                      variant="ghost"
+                    >
+                      Start new identity
+                    </Button>
+                  ) : null}
+                </div>
               </div>
+              <Dialog
+                onOpenChange={(open) => {
+                  if (!open) setKeyImportDialog(null);
+                }}
+                open={keyImportDialog === "backup"}
+              >
+                <DialogContent
+                  className="buzz-onboarding-neutral-theme max-w-[47.5rem] -translate-y-5"
+                  closeButtonClassName={ONBOARDING_INK_ICON_CLASS}
+                  data-system-color-scheme="light"
+                  data-testid="backup-recovery-dialog"
+                  surface="textured"
+                >
+                  <div className="mx-auto w-full max-w-[35rem] pb-6 pt-10 text-center max-sm:pb-4 max-sm:pt-6">
+                    <DialogTitle className="text-balance px-8 text-3xl font-normal text-foreground">
+                      Restore from a backup file
+                    </DialogTitle>
+                    <DialogDescription className="mx-auto mt-4 max-w-[28rem] text-sm leading-6 text-foreground/80">
+                      Choose the encrypted backup file you saved from Buzz.
+                    </DialogDescription>
+                    <NostrKeyImportForm
+                      footerMode="inline"
+                      mode="backup"
+                      onBack={() => setKeyImportDialog(null)}
+                      onImport={importExistingIdentity}
+                      showBack={false}
+                      variant="spotlight"
+                    />
+                  </div>
+                </DialogContent>
+              </Dialog>
+              <Dialog
+                onOpenChange={(open) => {
+                  if (!open) setKeyImportDialog(null);
+                }}
+                open={keyImportDialog === "phone"}
+              >
+                <DialogContent
+                  className="buzz-onboarding-neutral-theme max-h-[calc(100dvh-2rem)] max-w-[47.5rem] -translate-y-5 overflow-y-auto"
+                  closeButtonClassName={ONBOARDING_INK_ICON_CLASS}
+                  data-system-color-scheme="light"
+                  data-testid="phone-recovery-dialog"
+                  surface="textured"
+                >
+                  <div className="mx-auto flex w-full max-w-[35rem] flex-col items-center pb-6 pt-8 text-center max-sm:pb-4 max-sm:pt-4">
+                    <DialogTitle className="text-balance px-8 text-3xl font-normal text-foreground">
+                      {identityLost
+                        ? "Recover from your phone"
+                        : "Use your Buzz identity"}
+                    </DialogTitle>
+                    <DialogDescription className="mt-4 text-sm leading-6 text-foreground/80">
+                      {phoneRecoveryStep === "loading" ||
+                      phoneRecoveryStep === "qr"
+                        ? "Scan this code with a signed-in Buzz phone."
+                        : "Confirm the code before sharing your identity."}
+                    </DialogDescription>
+                    <div className="mt-5">
+                      <IdentityRecoveryPairing
+                        onRecovered={loadRecoveredIdentity}
+                        onStepChange={setPhoneRecoveryStep}
+                      />
+                    </div>
+                  </div>
+                </DialogContent>
+              </Dialog>
             </OnboardingSlideTransition>
           ) : page === "backup" ? (
             backupSubview === "password" ? (
diff --git a/desktop/src/features/onboarding/ui/NostrKeyImportForm.tsx b/desktop/src/features/onboarding/ui/NostrKeyImportForm.tsx
index 59e5bfdb0b..a424236eb6 100644
--- a/desktop/src/features/onboarding/ui/NostrKeyImportForm.tsx
+++ b/desktop/src/features/onboarding/ui/NostrKeyImportForm.tsx
@@ -1,5 +1,5 @@
 import * as React from "react";
-import { Check, Eye, EyeOff, KeyRound } from "lucide-react";
+import { Check, Eye, EyeOff, FileKey2, KeyRound } from "lucide-react";
 
 import { cn } from "@/shared/lib/cn";
 import { nsecToNpub } from "@/shared/lib/nostrUtils";
@@ -16,7 +16,10 @@ import {
   ONBOARDING_PRIMARY_CTA_CLASS,
   ONBOARDING_SECONDARY_CTA_CLASS,
 } from "./OnboardingChrome";
-import { BackupPasswordTimeline } from "./BackupPasswordTimeline";
+import {
+  BackupFileUnlockPreview,
+  BackupPasswordTimeline,
+} from "./BackupPasswordTimeline";
 import { OnboardingFooter } from "./OnboardingFooter";
 
 const NOSTR_KEY_FILE_MAX_BYTES = 1024;
@@ -30,6 +33,11 @@ type NostrKeyImportFormProps = {
   onBack: () => void;
   onImport: (nsec: string, password?: string) => Promise<void>;
   onStageChange?: (stage: NostrKeyImportStage) => void;
+  showBack?: boolean;
+  /** Restrict this instance to selecting a backup file instead of typing a key. */
+  mode?: "key" | "backup";
+  /** Dialogs keep their actions inside the surface instead of the onboarding dock. */
+  footerMode?: "onboarding" | "inline";
   /** "spotlight" is the first-launch treatment: glowy centered input, no drop zone, pill buttons. */
   variant?: "default" | "spotlight";
 };
@@ -48,6 +56,9 @@ export function NostrKeyImportForm({
   onBack,
   onImport,
   onStageChange,
+  showBack = true,
+  mode = "key",
+  footerMode = "onboarding",
   variant = "default",
 }: NostrKeyImportFormProps) {
   const [nsecInput, setNsecInput] = React.useState("");
@@ -55,6 +66,7 @@ export function NostrKeyImportForm({
   const [isImporting, setIsImporting] = React.useState(false);
   const [importError, setImportError] = React.useState<string | null>(null);
   const [isDragging, setIsDragging] = React.useState(false);
+  const dragDepthRef = React.useRef(0);
   const [isRevealed, setIsRevealed] = React.useState(false);
   const inputRef = React.useRef<HTMLInputElement | null>(null);
   const passphraseInputRef = React.useRef<HTMLInputElement | null>(null);
@@ -89,6 +101,7 @@ export function NostrKeyImportForm({
     previewNpub === null &&
     trimmedInput.length >= 5;
   const errorMessage = importError ?? externalErrorMessage;
+  const Footer = footerMode === "inline" ? "div" : OnboardingFooter;
 
   React.useLayoutEffect(() => {
     if (isPasswordStage) {
@@ -102,6 +115,39 @@ export function NostrKeyImportForm({
     onStageChange?.(isPasswordStage ? "backup-password" : "key-entry");
   }, [isPasswordStage, onStageChange]);
 
+  React.useEffect(() => {
+    if (mode !== "backup" || isPasswordStage || isInteractionDisabled) {
+      dragDepthRef.current = 0;
+      setIsDragging(false);
+      return;
+    }
+
+    const handleDragEnter = (event: DragEvent) => {
+      if (!event.dataTransfer?.types.includes("Files")) return;
+      dragDepthRef.current += 1;
+      setIsDragging(true);
+    };
+    const handleDragLeave = () => {
+      dragDepthRef.current = Math.max(0, dragDepthRef.current - 1);
+      if (dragDepthRef.current === 0) setIsDragging(false);
+    };
+    const handleDragEnd = () => {
+      dragDepthRef.current = 0;
+      setIsDragging(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);
+    };
+  }, [isInteractionDisabled, isPasswordStage, mode]);
+
   const openFilePicker = React.useCallback(() => {
     if (isInteractionDisabled) {
       return;
@@ -194,12 +240,27 @@ export function NostrKeyImportForm({
   return (
     <form
       className="mt-8 flex w-full flex-col gap-4"
+      onDragOver={(event) => {
+        if (mode !== "backup" || isPasswordStage) return;
+        event.preventDefault();
+        if (!isInteractionDisabled) {
+          event.dataTransfer.dropEffect = "copy";
+        }
+      }}
+      onDrop={(event) => {
+        if (mode !== "backup" || isPasswordStage) return;
+        event.preventDefault();
+        setIsDragging(false);
+        if (!isInteractionDisabled) {
+          void handleFiles(event.dataTransfer.files);
+        }
+      }}
       onSubmit={(event) => {
         event.preventDefault();
         void handleSubmit();
       }}
     >
-      {!isPasswordStage ? (
+      {!isPasswordStage && mode === "key" ? (
         <div className="space-y-1.5 text-left">
           <label
             className={cn(
@@ -286,37 +347,61 @@ export function NostrKeyImportForm({
       {/* 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"
-      />
-
-      {!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}
-            type="button"
-            variant="ghost"
+      {mode === "backup" || variant !== "spotlight" ? (
+        <input
+          accept=".key,.ncryptsec,text/plain"
+          className="sr-only"
+          data-testid="nostr-import-file-input"
+          disabled={isInteractionDisabled}
+          id={
+            mode === "backup"
+              ? "nostr-import-backup-file-input"
+              : "nostr-import-file-input"
+          }
+          onChange={(event) => {
+            void handleFiles(event.currentTarget.files);
+            event.currentTarget.value = "";
+          }}
+          ref={fileInputRef}
+          tabIndex={-1}
+          type="file"
+        />
+      ) : null}
+
+      {!isPasswordStage && mode === "backup" ? (
+        <>
+          <div
+            className="mx-auto flex h-[312px] w-full max-w-[500px] flex-col items-center justify-center gap-4 [@media(max-height:40rem)]:h-auto"
+            data-testid="nostr-import-backup-file-section"
           >
-            Choose a backup file
-          </Button>
-        </div>
-      ) : !isPasswordStage ? (
+            <Button
+              className="h-9 rounded-full px-6"
+              data-testid="nostr-import-backup-picker"
+              disabled={isInteractionDisabled}
+              onClick={openFilePicker}
+              type="button"
+            >
+              <FileKey2 aria-hidden="true" className="mr-2 size-4" />
+              Choose a backup file
+            </Button>
+            <BackupFileUnlockPreview />
+          </div>
+          {isDragging ? (
+            <fieldset
+              className="absolute inset-[var(--buzz-card-textured-safe-inset)] z-10 flex items-center justify-center rounded-2xl border-2 border-dashed border-primary/60 bg-background/80 backdrop-blur-sm"
+              data-dragging="true"
+              data-testid="nostr-import-backup-drop"
+            >
+              <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">
+                <KeyRound aria-hidden="true" className="size-4" />
+                <span>Drop your backup file here</span>
+              </span>
+            </fieldset>
+          ) : null}
+        </>
+      ) : null}
+
+      {!isPasswordStage && mode === "key" && variant !== "spotlight" ? (
         <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",
@@ -490,45 +575,58 @@ export function NostrKeyImportForm({
         </div>
       ) : null}
 
-      <OnboardingFooter>
-        <Button
-          className={
-            // Only the spotlight (onboarding) treatment gets the docked pill CTA.
-            // The default variant renders outside the onboarding footer provider
-            // (e.g. KeyringLockedScreen) and must stay full-width to match its
-            // sibling Back button.
-            variant === "spotlight"
-              ? ONBOARDING_PRIMARY_CTA_CLASS
-              : "h-10 w-full"
-          }
-          data-testid="nostr-import-submit"
-          disabled={!isValid || isInteractionDisabled}
-          onClick={() => void handleSubmit()}
-          type="button"
-        >
-          {isImporting ? (
-            <Spinner aria-label="Importing key" className="h-4 w-4 border-2" />
-          ) : variant === "spotlight" ? (
-            "Next"
-          ) : (
-            "Continue with this key"
-          )}
-        </Button>
+      <Footer
+        className={
+          footerMode === "inline"
+            ? "mt-6 flex flex-col items-center gap-2"
+            : undefined
+        }
+      >
+        {mode === "key" || isPasswordStage ? (
+          <Button
+            className={
+              // Only the spotlight (onboarding) treatment gets the docked pill CTA.
+              // The default variant renders outside the onboarding footer provider
+              // (e.g. KeyringLockedScreen) and must stay full-width to match its
+              // sibling Back button.
+              variant === "spotlight"
+                ? ONBOARDING_PRIMARY_CTA_CLASS
+                : "h-10 w-full"
+            }
+            data-testid="nostr-import-submit"
+            disabled={!isValid || isInteractionDisabled}
+            onClick={() => void handleSubmit()}
+            type="button"
+          >
+            {isImporting ? (
+              <Spinner
+                aria-label="Importing key"
+                className="h-4 w-4 border-2"
+              />
+            ) : variant === "spotlight" ? (
+              "Next"
+            ) : (
+              "Continue with this key"
+            )}
+          </Button>
+        ) : null}
 
-        <Button
-          className={
-            variant === "spotlight"
-              ? ONBOARDING_SECONDARY_CTA_CLASS
-              : "h-10 w-full text-muted-foreground hover:text-accent-foreground"
-          }
-          disabled={isImporting}
-          onClick={handleBack}
-          type="button"
-          variant="ghost"
-        >
-          {isPasswordStage ? "Back" : backLabel}
-        </Button>
-      </OnboardingFooter>
+        {showBack || isPasswordStage ? (
+          <Button
+            className={
+              variant === "spotlight"
+                ? ONBOARDING_SECONDARY_CTA_CLASS
+                : "h-10 w-full text-muted-foreground hover:text-accent-foreground"
+            }
+            disabled={isImporting}
+            onClick={handleBack}
+            type="button"
+            variant="ghost"
+          >
+            {isPasswordStage ? "Back" : backLabel}
+          </Button>
+        ) : null}
+      </Footer>
     </form>
   );
 }
diff --git a/desktop/src/shared/api/tauri.ts b/desktop/src/shared/api/tauri.ts
index 67ba582a1d..6e29f77c14 100644
--- a/desktop/src/shared/api/tauri.ts
+++ b/desktop/src/shared/api/tauri.ts
@@ -1126,8 +1126,6 @@ export async function nip44DecryptFromSelf(
   return invokeTauri<string>("nip44_decrypt_from_self", { ciphertext });
 }
 
-// ── NIP-AB device pairing ───────────────────────────────────────────────────
-
 export async function startPairing(): Promise<string> {
   return invokeTauri<string>("start_pairing");
 }
diff --git a/desktop/src/shared/api/tauriPairing.ts b/desktop/src/shared/api/tauriPairing.ts
new file mode 100644
index 0000000000..6fdf779446
--- /dev/null
+++ b/desktop/src/shared/api/tauriPairing.ts
@@ -0,0 +1,5 @@
+import { invokeTauri } from "@/shared/api/tauri";
+
+export async function startIdentityRecoveryPairing(): Promise<string> {
+  return invokeTauri<string>("start_identity_recovery_pairing");
+}
diff --git a/desktop/src/testing/e2eBridge.ts b/desktop/src/testing/e2eBridge.ts
index 1987e00ff1..abf74078da 100644
--- a/desktop/src/testing/e2eBridge.ts
+++ b/desktop/src/testing/e2eBridge.ts
@@ -12763,9 +12763,20 @@ export function maybeInstallE2eTauriMocks() {
         }
         return "nostrpair://8f4b8db31967ce14fef970a1ff1e8eecf19a430aa1c83875e2f5be68dcac0f1a?relay=wss%3A%2F%2Frelay.example.com&secret=87d5a8cfd5807a0cb44f728b67d88d6dcb8daf99be137c158f21a50c1e913c0a&v=1";
       }
+      case "start_identity_recovery_pairing": {
+        const delayMs = activeConfig?.mock?.pairingStartDelayMs ?? 0;
+        if (delayMs > 0) {
+          await new Promise((resolve) => window.setTimeout(resolve, delayMs));
+        }
+        return `nostrpair://8f4b8db31967ce14fef970a1ff1e8eecf19a430aa1c83875e2f5be68dcac0f1a?relay=wss%3A%2F%2Frelay.example.com&secret=87d5a8cfd5807a0cb44f728b67d88d6dcb8daf99be137c158f21a50c1e913c0a&v=1&mode=recover`;
+      }
       case "cancel_pairing":
       case "confirm_pairing_sas":
         return null;
+      case "complete_identity_recovery_pairing":
+        mockIdentityLostCleared = true;
+        await emit("pairing-complete", {});
+        return null;
       // ── NIP-IA identity archival ────────────────────────────────────────
       // These mocks drive the archive-button gate matrix in
       // tests/e2e/identity-archive.spec.ts. Defaults keep the button hidden
diff --git a/desktop/tests/e2e/identity-lost.spec.ts b/desktop/tests/e2e/identity-lost.spec.ts
index 71c663ab4f..2ab41cb52d 100644
--- a/desktop/tests/e2e/identity-lost.spec.ts
+++ b/desktop/tests/e2e/identity-lost.spec.ts
@@ -52,7 +52,7 @@ test("normal first launch uses the already-persisted identity", async ({
 
 test("lost boot opens onboarding gate directly on the key-import page", async ({
   page,
-}) => {
+}, testInfo) => {
   await installMockBridge(
     page,
     { identityLost: true },
@@ -62,13 +62,44 @@ test("lost boot opens onboarding gate directly on the key-import page", async ({
 
   await expect(page.getByTestId("machine-onboarding-gate")).toBeVisible();
   await expect(
-    page.getByRole("heading", { name: "Re-import your key" }),
+    page.getByRole("heading", { name: "Enter your private key" }),
   ).toBeVisible();
+  await page.waitForTimeout(1_000);
+  await page.screenshot({
+    path: testInfo.outputPath("desktop-private-key-recovery.png"),
+  });
 });
 
-test("importing a key from lost mode shows the relaunch-required screen", async ({
+test("lost boot keeps the pairing-code action stable while generating", async ({
   page,
 }) => {
+  await installMockBridge(
+    page,
+    { identityLost: true, pairingStartDelayMs: 2_500 },
+    { skipOnboardingSeed: true },
+  );
+  await page.goto("/");
+
+  await page.getByTestId("nostr-import-phone-link").click();
+  const copyButton = page.getByTestId("copy-identity-recovery-code");
+  await expect(copyButton).toBeVisible();
+  await expect(copyButton).toBeDisabled();
+  await expect(copyButton).toHaveText("Generating pairing code...");
+  const loadingButton = await copyButton.elementHandle();
+
+  await expect(copyButton).toBeEnabled();
+  await expect(copyButton).toHaveText("Copy pairing code");
+  expect(
+    await copyButton.evaluate(
+      (button, loading) => button === loading,
+      loadingButton,
+    ),
+  ).toBe(true);
+});
+
+test("lost boot offers phone recovery with a single-use QR", async ({
+  page,
+}, testInfo) => {
   await installMockBridge(
     page,
     { identityLost: true },
@@ -76,8 +107,254 @@ test("importing a key from lost mode shows the relaunch-required screen", async
   );
   await page.goto("/");
 
+  await page.getByTestId("nostr-import-phone-link").click();
+  await expect(page.getByTestId("identity-recovery-pairing")).toBeVisible();
+  await expect(page.getByTestId("identity-recovery-qr")).toBeVisible();
   await expect(
-    page.getByRole("heading", { name: "Re-import your key" }),
+    page.getByText("Scan this code with a signed-in Buzz phone."),
+  ).toBeVisible();
+  await expect(
+    page.getByText("On your phone, open Settings → Send identity to desktop."),
+  ).toBeVisible();
+  await page.waitForTimeout(1_000); // Let the onboarding entrance motion settle.
+  await page.screenshot({
+    path: testInfo.outputPath("desktop-phone-recovery-qr.png"),
+    fullPage: true,
+  });
+
+  const copyButton = page.getByTestId("copy-identity-recovery-code");
+  await expect(copyButton).toHaveText("Copy pairing code");
+  await page.context().grantPermissions(["clipboard-read", "clipboard-write"]);
+  await copyButton.click();
+  await expect(copyButton).toHaveText("Copied");
+
+  const copiedPayload = await page.evaluate(() => {
+    const log = (
+      window as Window & {
+        __BUZZ_E2E_COMMAND_LOG__?: Array<{
+          command: string;
+          payload: Record<string, unknown> | null;
+        }>;
+      }
+    ).__BUZZ_E2E_COMMAND_LOG__;
+    return log?.findLast(({ command }) => command === "copy_text_to_clipboard")
+      ?.payload;
+  });
+  expect(copiedPayload?.text).toMatch(/^nostrpair:\/\/.+&mode=recover$/);
+
+  const commands = await page.evaluate(
+    () =>
+      (
+        window as Window & {
+          __BUZZ_E2E_COMMAND_PAYLOADS__?: Array<{ command: string }>;
+        }
+      ).__BUZZ_E2E_COMMAND_PAYLOADS__ ?? [],
+  );
+  expect(
+    commands.some(
+      (entry) => entry.command === "start_identity_recovery_pairing",
+    ),
+  ).toBe(true);
+});
+
+test("phone recovery uses the desktop pairing card semantics", async ({
+  page,
+}) => {
+  await installMockBridge(
+    page,
+    { identityLost: true },
+    { skipOnboardingSeed: true },
+  );
+  await page.goto("/");
+
+  await page.getByTestId("nostr-import-phone-link").click();
+  const card = page.getByTestId("identity-recovery-pairing");
+  const qrContainer = card.getByTestId("identity-recovery-qr-container");
+  const qrCode = card.getByTestId("identity-recovery-qr");
+  const copyButton = card.getByTestId("copy-identity-recovery-code");
+  await expect(qrCode).toBeVisible();
+  await expect(qrCode).toHaveAttribute("data-qr-matrix-size", "57");
+  await expect(qrCode.locator("[data-qr-finder-pattern]")).toHaveCount(3);
+  await expect(qrCode.locator(".buzz-qr-cell-reveal").first()).toHaveCSS(
+    "animation-name",
+    "buzz-qr-cell-reveal",
+  );
+  const qrBox = await qrContainer.boundingBox();
+  const copyBox = await copyButton.boundingBox();
+  expect(qrBox).not.toBeNull();
+  expect(copyBox).not.toBeNull();
+  expect(Math.abs((copyBox?.x ?? 0) - (qrBox?.x ?? 0))).toBeLessThan(1);
+  expect(Math.abs((copyBox?.width ?? 0) - (qrBox?.width ?? 0))).toBeLessThan(1);
+
+  await page.evaluate(async () => {
+    await window.__TAURI_INTERNALS__?.invoke?.("plugin:event|emit", {
+      event: "pairing-sas-received",
+      payload: { sas: "123456" },
+    });
+  });
+
+  await expect(
+    card.getByText("Does this code match your phone?"),
+  ).toBeVisible();
+  await expect(
+    page.getByText("Confirm the code before sharing your identity."),
+  ).toBeVisible();
+  await expect(
+    card.getByText(
+      "This gives this desktop permanent access to your Buzz identity. Only continue if you trust it.",
+    ),
+  ).toBeVisible();
+  await expect(
+    card.getByText(/On your phone, open Settings/),
+  ).not.toBeVisible();
+  await expect(card.getByTestId("identity-recovery-sas")).toHaveText("123 456");
+  await expect(card.getByTestId("confirm-identity-recovery-sas")).toHaveText(
+    "Codes match",
+  );
+  await expect(card.getByTestId("deny-identity-recovery-sas")).toHaveText(
+    "Cancel",
+  );
+  const cancelBox = await card
+    .getByTestId("deny-identity-recovery-sas")
+    .boundingBox();
+  const confirmBox = await card
+    .getByTestId("confirm-identity-recovery-sas")
+    .boundingBox();
+  expect(cancelBox).not.toBeNull();
+  expect(confirmBox).not.toBeNull();
+  expect((cancelBox?.y ?? 0) - (confirmBox?.y ?? 0)).toBeGreaterThan(
+    confirmBox?.height ?? 0,
+  );
+});
+
+test("canceling recovery uses the standard pairing cancellation state", async ({
+  page,
+}) => {
+  await installMockBridge(
+    page,
+    { identityLost: true },
+    { skipOnboardingSeed: true },
+  );
+  await page.goto("/");
+  await page.getByTestId("nostr-import-phone-link").click();
+  await expect(page.getByTestId("identity-recovery-qr")).toBeVisible();
+
+  await page.evaluate(async () => {
+    await window.__TAURI_INTERNALS__?.invoke?.("plugin:event|emit", {
+      event: "pairing-sas-received",
+      payload: { sas: "123456" },
+    });
+  });
+  await page.getByTestId("deny-identity-recovery-sas").click();
+
+  await expect(
+    page.getByText("The codes didn't match. Pairing was canceled."),
+  ).toBeVisible();
+  await expect(page.getByRole("button", { name: "Try again" })).toBeVisible();
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () =>
+          (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
+            ({ command }) => command === "cancel_pairing",
+          ).length,
+      ),
+    )
+    .toBeGreaterThan(0);
+});
+
+test("phone recovery continues to harness setup without creating or restarting", async ({
+  page,
+}) => {
+  await installMockBridge(
+    page,
+    { identityLost: true },
+    { skipOnboardingSeed: true },
+  );
+  await page.goto("/");
+  await page.getByTestId("nostr-import-phone-link").click();
+  await expect(page.getByTestId("identity-recovery-qr")).toBeVisible();
+
+  await page.evaluate(async () => {
+    await window.__TAURI_INTERNALS__?.invoke?.(
+      "complete_identity_recovery_pairing",
+    );
+  });
+
+  await expect(
+    page.getByRole("heading", { name: "Set up your agent harnesses" }),
+  ).toBeVisible();
+  await expect(page.getByTestId("relaunch-required")).toHaveCount(0);
+  await expect(
+    page.getByRole("heading", {
+      name: "Your unique identity key has been created",
+    }),
+  ).toHaveCount(0);
+});
+
+test("recovery turns relay failures into actionable copy", async ({ page }) => {
+  await installMockBridge(
+    page,
+    { identityLost: true },
+    { skipOnboardingSeed: true },
+  );
+  await page.goto("/");
+  await page.getByTestId("nostr-import-phone-link").click();
+  await expect(page.getByTestId("identity-recovery-qr")).toBeVisible();
+
+  await page.evaluate(async () => {
+    await window.__TAURI_INTERNALS__?.invoke?.("plugin:event|emit", {
+      event: "pairing-error",
+      payload: { message: "failed to send sas-confirm" },
+    });
+  });
+
+  await expect(
+    page.getByText(
+      "This pairing code expired or lost its connection. Create a new code and try again.",
+    ),
+  ).toBeVisible();
+  await expect(page.getByRole("button", { name: "Try again" })).toBeVisible();
+});
+
+test("desktop refreshes recovery codes before the relay expires them", async ({
+  page,
+}) => {
+  await page.clock.install();
+  await installMockBridge(
+    page,
+    { identityLost: true },
+    { skipOnboardingSeed: true },
+  );
+  await page.goto("/");
+  await page.getByTestId("nostr-import-phone-link").click();
+  await expect(page.getByTestId("identity-recovery-qr")).toBeVisible();
+
+  const recoveryStarts = () =>
+    page.evaluate(
+      () =>
+        (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
+          ({ command }) => command === "start_identity_recovery_pairing",
+        ).length,
+    );
+  await expect.poll(recoveryStarts).toBe(1);
+
+  await page.clock.fastForward(90_000);
+  await expect.poll(recoveryStarts).toBe(2);
+  await expect(page.getByTestId("identity-recovery-qr")).toBeVisible();
+});
+
+test("importing a key from lost mode shows the relaunch-required screen", async ({
+  page,
+}) => {
+  await installMockBridge(
+    page,
+    { identityLost: true },
+    { skipOnboardingSeed: true },
+  );
+  await page.goto("/");
+  await expect(
+    page.getByRole("heading", { name: "Enter your private key" }),
   ).toBeVisible();
 
   const importedNsec = nsecEncode(hexToBytes(TEST_IDENTITIES.alice.privateKey));
@@ -97,9 +374,8 @@ test("start-new-identity from lost mode persists the ephemeral key after confirm
     { skipOnboardingSeed: true },
   );
   await page.goto("/");
-
   await expect(
-    page.getByRole("heading", { name: "Re-import your key" }),
+    page.getByRole("heading", { name: "Enter your private key" }),
   ).toBeVisible();
 
   page.on("dialog", (dialog) => dialog.accept());
@@ -131,9 +407,8 @@ test("cancelling start-new-identity in lost mode stays on the import screen", as
     { skipOnboardingSeed: true },
   );
   await page.goto("/");
-
   await expect(
-    page.getByRole("heading", { name: "Re-import your key" }),
+    page.getByRole("heading", { name: "Enter your private key" }),
   ).toBeVisible();
 
   page.on("dialog", (dialog) => dialog.dismiss());
@@ -141,7 +416,7 @@ test("cancelling start-new-identity in lost mode stays on the import screen", as
 
   // Still on the import screen — no navigation, no persist
   await expect(
-    page.getByRole("heading", { name: "Re-import your key" }),
+    page.getByRole("heading", { name: "Enter your private key" }),
   ).toBeVisible();
   await expect(page.getByTestId("relaunch-required")).toHaveCount(0);
 });
@@ -159,7 +434,7 @@ test("locked boot shows the keyring-locked screen without the onboarding gate or
   await expect(page.getByTestId("keyring-locked")).toBeVisible();
   await expect(page.getByTestId("onboarding-gate")).toHaveCount(0);
   await expect(
-    page.getByRole("heading", { name: "Re-import your key" }),
+    page.getByRole("heading", { name: "Enter your private key" }),
   ).toHaveCount(0);
 });
 
diff --git a/desktop/tests/e2e/onboarding.spec.ts b/desktop/tests/e2e/onboarding.spec.ts
index 57e812091c..0f2e8ce617 100644
--- a/desktop/tests/e2e/onboarding.spec.ts
+++ b/desktop/tests/e2e/onboarding.spec.ts
@@ -620,6 +620,99 @@ test("completed users skip the loading gate while profile is still settling", as
   await expectHomeView(page);
 });
 
+test("fresh existing-identity path leads with private-key recovery", async ({
+  page,
+}) => {
+  await installMockBridge(page, undefined, {
+    skipCommunitySeed: true,
+    skipOnboardingSeed: true,
+  });
+  await page.goto("/");
+
+  await page.getByRole("button", { name: "Use an existing key" }).click();
+  await expect(
+    page.getByRole("heading", { name: "Enter your private key" }),
+  ).toBeVisible();
+  await expect(
+    page.getByText("Paste your private key to sign in to Buzz."),
+  ).toBeVisible();
+  await expect(page.getByTestId("nostr-import-card")).toBeVisible();
+  await expect(page.getByTestId("nostr-import-file-button")).toHaveText(
+    "backup file",
+  );
+  await expect(page.getByTestId("nostr-import-phone-link")).toHaveText(
+    "recover from your phone",
+  );
+  await expect(page.getByTestId("identity-recovery-pairing")).toHaveCount(0);
+
+  await page.getByTestId("nostr-import-file-button").click();
+  const backupDialog = page.getByTestId("backup-recovery-dialog");
+  await expect(backupDialog).toBeVisible();
+  await expect(
+    backupDialog.getByRole("heading", { name: "Restore from a backup file" }),
+  ).toBeVisible();
+  await expect(
+    backupDialog.getByTestId("nostr-import-backup-picker"),
+  ).toBeVisible();
+  const unlockPreview = backupDialog.getByTestId("backup-file-unlock-preview");
+  await expect(unlockPreview).toBeVisible();
+  await expect(unlockPreview.locator("span")).toHaveCount(17);
+  await expect(
+    unlockPreview.getByTestId("backup-file-key-dots").locator("span"),
+  ).toHaveCount(9);
+  await expect(
+    unlockPreview.getByTestId("backup-file-unlock-preview-icon"),
+  ).toBeVisible();
+  await expect(
+    backupDialog.getByTestId("nostr-import-backup-drop"),
+  ).toHaveCount(0);
+  await backupDialog
+    .getByTestId("nostr-import-backup-picker")
+    .evaluate((element) => {
+      const dataTransfer = new DataTransfer();
+      dataTransfer.items.add(
+        new File(["backup"], "identity.ncryptsec", { type: "text/plain" }),
+      );
+      element.dispatchEvent(
+        new DragEvent("dragenter", {
+          bubbles: true,
+          cancelable: true,
+          dataTransfer,
+        }),
+      );
+    });
+  const backupDrop = backupDialog.getByTestId("nostr-import-backup-drop");
+  await expect(backupDrop).toHaveAttribute("data-dragging", "true");
+  await expect(backupDrop).toContainText("Drop your backup file here");
+  const [backupDropBox, backupFileSectionBox] = await Promise.all([
+    backupDrop.boundingBox(),
+    unlockPreview.boundingBox(),
+  ]);
+  expect(backupDropBox?.width).toBeGreaterThan(
+    backupFileSectionBox?.width ?? 0,
+  );
+  await expect(
+    backupDialog.getByTestId("nostr-import-backup-picker"),
+  ).toBeVisible();
+  await backupDrop.evaluate((element) => {
+    element.dispatchEvent(
+      new DragEvent("dragleave", { bubbles: true, cancelable: true }),
+    );
+  });
+  await expect(backupDrop).toHaveCount(0);
+  await expect(page.getByTestId("nostr-import-card")).toBeVisible();
+  await backupDialog.getByRole("button", { name: "Close" }).click();
+
+  await page.getByTestId("nostr-import-phone-link").click();
+  const phoneDialog = page.getByTestId("phone-recovery-dialog");
+  await expect(phoneDialog).toBeVisible();
+  await expect(
+    phoneDialog.getByRole("heading", { name: "Use your Buzz identity" }),
+  ).toBeVisible();
+  await expect(phoneDialog.getByTestId("identity-recovery-qr")).toBeVisible();
+  await expect(page.getByTestId("nostr-import-card")).toBeVisible();
+});
+
 test("first-launch key import continues to machine setup", async ({ page }) => {
   await installMockBridge(page, undefined, {
     skipCommunitySeed: true,
@@ -707,8 +800,10 @@ test("first-launch import accepts an .ncryptsec backup file", async ({
   // 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 page.getByTestId("nostr-import-file-button").click();
+  const fileInput = page
+    .getByTestId("backup-recovery-dialog")
+    .getByTestId("nostr-import-file-input");
   await expect(fileInput).toHaveAttribute(
     "accept",
     ".key,.ncryptsec,text/plain",
@@ -719,44 +814,87 @@ test("first-launch import accepts an .ncryptsec backup file", async ({
     mimeType: "text/plain",
     name: "not-a-backup.txt",
   });
-  await expect(page.getByTestId("nostr-import-feedback")).toContainText(
-    /too large to be a key backup/i,
-  );
+  await expect(
+    page
+      .getByTestId("backup-recovery-dialog")
+      .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 password stage inside the same dialog.
+  const backupDialog = page.getByTestId("backup-recovery-dialog");
+  const backupFileSection = backupDialog.getByTestId(
+    "nostr-import-backup-file-section",
+  );
+  const backupFileSectionHeight = await backupFileSection.evaluate((element) =>
+    Number.parseFloat(getComputedStyle(element).height),
+  );
+  expect(backupFileSectionHeight).toBe(312);
+  const backupPicker = backupDialog.getByTestId("nostr-import-backup-picker");
+  await backupPicker.evaluate((element) => {
+    const dataTransfer = new DataTransfer();
+    dataTransfer.items.add(
+      new File(["backup"], "identity.ncryptsec", { type: "text/plain" }),
+    );
+    element.dispatchEvent(
+      new DragEvent("dragenter", {
+        bubbles: true,
+        cancelable: true,
+        dataTransfer,
+      }),
+    );
   });
+  const backupDrop = backupDialog.getByTestId("nostr-import-backup-drop");
+  await expect(backupDrop).toBeVisible();
+  await backupDrop.evaluate((element, contents) => {
+    const dataTransfer = new DataTransfer();
+    dataTransfer.items.add(
+      new File([contents], "identity.ncryptsec", { type: "text/plain" }),
+    );
+    element.dispatchEvent(
+      new DragEvent("drop", {
+        bubbles: true,
+        cancelable: true,
+        dataTransfer,
+      }),
+    );
+  }, `${mockNcryptsec}\n`);
 
-  // File contents advance to the same focused password stage as manual input.
   await expect(
-    page.getByRole("heading", { name: "Unlock your account" }),
+    backupDialog.getByTestId("backup-password-timeline"),
   ).toBeVisible();
-  await expect(page.getByTestId("backup-password-timeline")).toBeVisible();
-  await expect(page.getByTestId("nostr-import-passphrase")).toBeFocused();
+  const passphraseSection = backupDialog.getByTestId(
+    "nostr-import-passphrase-section",
+  );
+  await expect(passphraseSection).toBeVisible();
+  const passphraseSectionHeight = await passphraseSection.evaluate((element) =>
+    Number.parseFloat(getComputedStyle(element).height),
+  );
+  expect(passphraseSectionHeight).toBe(backupFileSectionHeight);
+  await expect(
+    backupDialog.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();
+  // Back first returns to backup-file selection instead of closing the dialog.
+  await backupDialog.getByRole("button", { name: "Back", exact: true }).click();
   await expect(
-    page.getByRole("heading", { name: "Enter your private key" }),
+    backupDialog.getByRole("heading", { name: "Restore from a backup file" }),
+  ).toBeVisible();
+  await expect(
+    backupDialog.getByTestId("nostr-import-backup-picker"),
   ).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
+  await backupDialog
     .getByTestId("nostr-import-passphrase")
     .fill("mock horse battery staple lake orbit");
-  await page.getByTestId("nostr-import-submit").click();
+  await backupDialog.getByTestId("nostr-import-submit").click();
 
   await expect(page.getByTestId("onboarding-page-2")).toBeVisible();
   await expect(page.getByTestId("machine-onboarding-gate")).toBeVisible();
diff --git a/mobile/lib/app.dart b/mobile/lib/app.dart
index 057594dfad..d5ae326afa 100644
--- a/mobile/lib/app.dart
+++ b/mobile/lib/app.dart
@@ -147,8 +147,11 @@ class App extends HookConsumerWidget {
   }
 }
 
-Widget _buildSettingsPage(BuildContext context) =>
-    const SettingsPage(profileHeader: SettingsProfileHeader());
+Widget _buildSettingsPage(BuildContext context) => SettingsPage(
+  profileHeader: const SettingsProfileHeader(),
+  identityRecoveryPageBuilder: (_) =>
+      const PairingPage(addingCommunity: true, identityRecoveryOnly: true),
+);
 
 class _SplashScreen extends StatelessWidget {
   const _SplashScreen();
diff --git a/mobile/lib/features/pairing/pairing_page.dart b/mobile/lib/features/pairing/pairing_page.dart
index 85b781052d..7061180b12 100644
--- a/mobile/lib/features/pairing/pairing_page.dart
+++ b/mobile/lib/features/pairing/pairing_page.dart
@@ -25,8 +25,13 @@ class PairingPage extends HookConsumerWidget {
   /// When true, the pairing page is being used to add a new community
   /// (user is already authenticated with at least one community).
   final bool addingCommunity;
+  final bool identityRecoveryOnly;
 
-  const PairingPage({super.key, this.addingCommunity = false});
+  const PairingPage({
+    super.key,
+    this.addingCommunity = false,
+    this.identityRecoveryOnly = false,
+  });
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
@@ -51,6 +56,13 @@ class PairingPage extends HookConsumerWidget {
 
     Future<void> handleScannerResult(String? code) async {
       if (code != null && context.mounted) {
+        if (identityRecoveryOnly &&
+            Uri.tryParse(code)?.queryParameters['mode'] != 'recover') {
+          ScaffoldMessenger.of(context).showSnackBar(
+            const SnackBar(content: Text('Scan a desktop recovery code.')),
+          );
+          return;
+        }
         await ref.read(pairingProvider.notifier).pair(code);
       }
     }
@@ -91,7 +103,7 @@ class PairingPage extends HookConsumerWidget {
               onPressed: () => Navigator.of(context).pop(),
             ),
             title: Text(
-              'Add Community',
+              identityRecoveryOnly ? 'Send to Desktop' : 'Add Community',
               style: isVerifyingSas
                   ? null
                   : context.textTheme.titleMedium?.copyWith(
@@ -114,6 +126,7 @@ class PairingPage extends HookConsumerWidget {
                   child: _SasVerificationView(
                     sasCode: pairingState.sasCode ?? '------',
                     confirmed: pairingState.userConfirmedSas,
+                    sendsIdentityToDesktop: pairingState.sendsIdentityToDesktop,
                     onConfirm: () =>
                         ref.read(pairingProvider.notifier).confirmSas(),
                     onDeny: () => ref.read(pairingProvider.notifier).denySas(),
@@ -146,7 +159,7 @@ class PairingPage extends HookConsumerWidget {
                     onConnect: () {
                       final code = codeController.text.trim();
                       if (code.isNotEmpty) {
-                        ref.read(pairingProvider.notifier).pair(code);
+                        unawaited(handleScannerResult(code));
                       }
                     },
                   ),
@@ -182,12 +195,14 @@ class PairingPage extends HookConsumerWidget {
 class _SasVerificationView extends StatelessWidget {
   final String sasCode;
   final bool confirmed;
+  final bool sendsIdentityToDesktop;
   final VoidCallback onConfirm;
   final VoidCallback onDeny;
 
   const _SasVerificationView({
     required this.sasCode,
     required this.confirmed,
+    required this.sendsIdentityToDesktop,
     required this.onConfirm,
     required this.onDeny,
   });
@@ -242,7 +257,9 @@ class _SasVerificationView extends StatelessWidget {
         const SizedBox(height: Grid.lg),
 
         Text(
-          'You are about to transfer your Buzz identity\nto this device. Only confirm if you initiated\nthis pairing from your desktop.',
+          sendsIdentityToDesktop
+              ? 'This sends your full Buzz identity to the desktop\nand grants it permanent access. Only confirm a\ndesktop you trust and a recovery you started.'
+              : 'You are about to transfer your Buzz identity\nto this device. Only confirm if you initiated\nthis pairing from your desktop.',
           textAlign: TextAlign.center,
           style: context.textTheme.bodySmall?.copyWith(
             color: context.colors.onSurfaceVariant,
diff --git a/mobile/lib/features/pairing/pairing_provider.dart b/mobile/lib/features/pairing/pairing_provider.dart
index 6a6c57a673..5adde987eb 100644
--- a/mobile/lib/features/pairing/pairing_provider.dart
+++ b/mobile/lib/features/pairing/pairing_provider.dart
@@ -36,12 +36,14 @@ class PairingState {
   final String? errorMessage;
   final String? sasCode;
   final bool userConfirmedSas;
+  final bool sendsIdentityToDesktop;
 
   const PairingState({
     this.status = PairingStatus.idle,
     this.errorMessage,
     this.sasCode,
     this.userConfirmedSas = false,
+    this.sendsIdentityToDesktop = false,
   });
 
   PairingState copyWith({
@@ -49,11 +51,14 @@ class PairingState {
     String? errorMessage,
     String? sasCode,
     bool? userConfirmedSas,
+    bool? sendsIdentityToDesktop,
   }) => PairingState(
     status: status ?? this.status,
     errorMessage: errorMessage ?? this.errorMessage,
     sasCode: sasCode ?? this.sasCode,
     userConfirmedSas: userConfirmedSas ?? this.userConfirmedSas,
+    sendsIdentityToDesktop:
+        sendsIdentityToDesktop ?? this.sendsIdentityToDesktop,
   );
 }
 
@@ -111,10 +116,14 @@ class PairingNotifier extends Notifier<PairingState> {
     // transition immediately and process any buffered payload.
     if (_sasConfirmReceived) {
       state = state.copyWith(status: PairingStatus.transferring);
-      final pending = _pendingPayload;
-      if (pending != null) {
-        _pendingPayload = null;
-        _handlePayload(pending);
+      if (_sendIdentityToSource) {
+        _sendIdentityPayload();
+      } else {
+        final pending = _pendingPayload;
+        if (pending != null) {
+          _pendingPayload = null;
+          _handlePayload(pending);
+        }
       }
       return;
     }
@@ -149,6 +158,7 @@ class PairingNotifier extends Notifier<PairingState> {
     _sasConfirmReceived = false;
     _userConfirmedSas = false;
     _pendingPayload = null;
+    _sendIdentityToSource = false;
   }
 
   // ── NIP-AB pairing flow ─────────────────────────────────────────────────
@@ -163,6 +173,7 @@ class PairingNotifier extends Notifier<PairingState> {
   Uint8List? _conversationKey;
   bool _sasConfirmReceived = false;
   bool _userConfirmedSas = false;
+  bool _sendIdentityToSource = false;
   Map<String, dynamic>? _pendingPayload; // buffered until user confirms SAS
   final Set<String> _processedEventIds = {}; // NIP-AB §Duplicate Event Handling
 
@@ -174,6 +185,8 @@ class PairingNotifier extends Notifier<PairingState> {
       final qr = parseNostrpairUri(uri);
       _sourcePubkey = qr.sourcePubkey;
       _sessionSecret = qr.sessionSecret;
+      _sendIdentityToSource =
+          Uri.parse(uri).queryParameters['mode'] == 'recover';
 
       final relayWsUrl = qr.relays.first;
 
@@ -234,6 +247,7 @@ class PairingNotifier extends Notifier<PairingState> {
       state = PairingState(
         status: PairingStatus.confirmingSas,
         sasCode: formatSas(sasCode),
+        sendsIdentityToDesktop: _sendIdentityToSource,
       );
 
       // 9. Start 120s session timeout.
@@ -359,6 +373,9 @@ class PairingNotifier extends Notifier<PairingState> {
         case 'abort':
           _handleAbort(msg);
           _processedEventIds.add(eventId);
+        case 'complete':
+          _handleComplete(msg);
+          _processedEventIds.add(eventId);
       }
     } catch (e) {
       // Silently discard invalid events per NIP-AB §Event Validation.
@@ -400,15 +417,44 @@ class PairingNotifier extends Notifier<PairingState> {
     if (_userConfirmedSas) {
       _userConfirmedSas = false;
       state = state.copyWith(status: PairingStatus.transferring);
-      final pending = _pendingPayload;
-      if (pending != null) {
-        _pendingPayload = null;
-        _handlePayload(pending);
+      if (_sendIdentityToSource) {
+        _sendIdentityPayload();
+      } else {
+        final pending = _pendingPayload;
+        if (pending != null) {
+          _pendingPayload = null;
+          _handlePayload(pending);
+        }
       }
     }
     // Otherwise stay in confirmingSas — user must still confirm via confirmSas().
   }
 
+  void _sendIdentityPayload() {
+    final nsec = ref.read(relayConfigProvider).nsec;
+    if (nsec == null || nsec.isEmpty) {
+      _sendAbort('protocol_error');
+      _cleanup();
+      state = const PairingState(
+        status: PairingStatus.error,
+        errorMessage: 'No identity is available on this phone.',
+      );
+      return;
+    }
+    final content = _encryptMessage({
+      'type': 'payload',
+      'payload_type': 'nsec',
+      'payload': nsec,
+    });
+    _publishEvent(
+      kind: 24134,
+      content: content,
+      tags: [
+        ['p', _sourcePubkey!],
+      ],
+    );
+  }
+
   void _handlePayload(Map<String, dynamic> msg) {
     // Only accept payload after the transcript hash was verified.
     if (!_sasConfirmReceived) return;
@@ -436,6 +482,22 @@ class PairingNotifier extends Notifier<PairingState> {
     _processPayload(payloadType, payload);
   }
 
+  void _handleComplete(Map<String, dynamic> msg) {
+    if (!_sendIdentityToSource || state.status != PairingStatus.transferring) {
+      return;
+    }
+    if (msg['success'] != true) {
+      _cleanup();
+      state = const PairingState(
+        status: PairingStatus.error,
+        errorMessage: 'Desktop could not store the identity.',
+      );
+      return;
+    }
+    _cleanup();
+    state = const PairingState(status: PairingStatus.success);
+  }
+
   void _handleAbort(Map<String, dynamic> msg) {
     final reason = msg['reason'] as String? ?? 'unknown';
     _cleanup();
diff --git a/mobile/lib/features/settings/settings_page.dart b/mobile/lib/features/settings/settings_page.dart
index d53f39a672..066dd1fd3d 100644
--- a/mobile/lib/features/settings/settings_page.dart
+++ b/mobile/lib/features/settings/settings_page.dart
@@ -24,9 +24,14 @@ part 'settings_page/appearance_section.dart';
 part 'settings_page/connection_section.dart';
 
 class SettingsPage extends HookConsumerWidget {
-  const SettingsPage({super.key, required this.profileHeader});
+  const SettingsPage({
+    super.key,
+    required this.profileHeader,
+    required this.identityRecoveryPageBuilder,
+  });
 
   final Widget profileHeader;
+  final WidgetBuilder identityRecoveryPageBuilder;
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
@@ -67,7 +72,9 @@ class SettingsPage extends HookConsumerWidget {
               children: [
                 profileHeader,
                 const _AppearanceSection(),
-                const _ConnectionSection(),
+                _ConnectionSection(
+                  identityRecoveryPageBuilder: identityRecoveryPageBuilder,
+                ),
                 const _RemoveCommunitySection(),
               ],
             ),
diff --git a/mobile/lib/features/settings/settings_page/connection_section.dart b/mobile/lib/features/settings/settings_page/connection_section.dart
index 19da784a63..631f870abc 100644
--- a/mobile/lib/features/settings/settings_page/connection_section.dart
+++ b/mobile/lib/features/settings/settings_page/connection_section.dart
@@ -1,7 +1,9 @@
 part of '../settings_page.dart';
 
 class _ConnectionSection extends ConsumerWidget {
-  const _ConnectionSection();
+  const _ConnectionSection({required this.identityRecoveryPageBuilder});
+
+  final WidgetBuilder identityRecoveryPageBuilder;
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
@@ -16,7 +18,18 @@ class _ConnectionSection extends ConsumerWidget {
           title: 'Connected to',
           subtitle: config.baseUrl,
         ),
-        if (nsec != null && nsec.isNotEmpty) _IdentityRow(nsec: nsec),
+        if (nsec != null && nsec.isNotEmpty) ...[
+          _IdentityRow(nsec: nsec),
+          AppListRow(
+            icon: LucideIcons.scanQrCode,
+            title: 'Send identity to desktop',
+            subtitle: 'Scan a recovery code shown by Buzz Desktop',
+            trailing: const _RowChevron(),
+            onTap: () => Navigator.of(context).push(
+              MaterialPageRoute<void>(builder: identityRecoveryPageBuilder),
+            ),
+          ),
+        ],
       ],
     );
   }
diff --git a/mobile/test/features/pairing/pairing_page_test.dart b/mobile/test/features/pairing/pairing_page_test.dart
index 678be9dfe7..e8f34a6f71 100644
--- a/mobile/test/features/pairing/pairing_page_test.dart
+++ b/mobile/test/features/pairing/pairing_page_test.dart
@@ -179,6 +179,69 @@ void main() {
       expect(scanButton.onPressed, isNull);
       expect(pairingCodeButton.onPressed, isNull);
     });
+
+    testWidgets('recovery entry rejects ordinary nostrpair codes', (
+      tester,
+    ) async {
+      final notifier = _RecordingPairingNotifier();
+      await tester.pumpWidget(
+        WidgetHelpers.testable(
+          overrides: [pairingProvider.overrideWith(() => notifier)],
+          child: const PairingPage(
+            addingCommunity: true,
+            identityRecoveryOnly: true,
+          ),
+        ),
+      );
+
+      await _expandPairingCode(tester);
+      await tester.enterText(find.byType(TextField), 'nostrpair://ordinary');
+      await tester.tap(find.text('Connect'));
+      await tester.pump();
+
+      expect(find.text('Scan a desktop recovery code.'), findsOneWidget);
+      expect(notifier.pairedCodes, isEmpty);
+    });
+
+    testWidgets('recovery entry accepts mode=recover codes', (tester) async {
+      final notifier = _RecordingPairingNotifier();
+      await tester.pumpWidget(
+        WidgetHelpers.testable(
+          overrides: [pairingProvider.overrideWith(() => notifier)],
+          child: const PairingPage(
+            addingCommunity: true,
+            identityRecoveryOnly: true,
+          ),
+        ),
+      );
+
+      await _expandPairingCode(tester);
+      const code = 'nostrpair://desktop?mode=recover';
+      await tester.enterText(find.byType(TextField), code);
+      await tester.tap(find.text('Connect'));
+      await tester.pump();
+
+      expect(notifier.pairedCodes, [code]);
+    });
+
+    testWidgets('recovery SAS warns about permanent desktop access', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        ProviderScope(
+          overrides: [
+            pairingProvider.overrideWith(
+              () => _ConfirmingSasPairingNotifier(sendsIdentityToDesktop: true),
+            ),
+          ],
+          child: MaterialApp(theme: AppTheme.dark(), home: const PairingPage()),
+        ),
+      );
+
+      expect(find.textContaining('full Buzz identity'), findsOneWidget);
+      expect(find.textContaining('permanent access'), findsOneWidget);
+      expect(find.text('Codes Match'), findsOneWidget);
+    });
   });
 }
 
@@ -227,12 +290,37 @@ class _ConnectingPairingNotifier extends Notifier<PairingState>
   void denySas() {}
 }
 
+class _RecordingPairingNotifier extends Notifier<PairingState>
+    implements PairingNotifier {
+  final pairedCodes = <String>[];
+
+  @override
+  PairingState build() => const PairingState();
+
+  @override
+  Future<void> pair(String rawInput) async => pairedCodes.add(rawInput);
+
+  @override
+  void reset() {}
+
+  @override
+  void confirmSas() {}
+
+  @override
+  void denySas() {}
+}
+
 class _ConfirmingSasPairingNotifier extends Notifier<PairingState>
     implements PairingNotifier {
+  _ConfirmingSasPairingNotifier({this.sendsIdentityToDesktop = false});
+
+  final bool sendsIdentityToDesktop;
+
   @override
-  PairingState build() => const PairingState(
+  PairingState build() => PairingState(
     status: PairingStatus.confirmingSas,
     sasCode: '123456',
+    sendsIdentityToDesktop: sendsIdentityToDesktop,
   );
 
   @override
diff --git a/mobile/test/features/pairing/pairing_provider_test.dart b/mobile/test/features/pairing/pairing_provider_test.dart
index 6f49f71921..c14599bbef 100644
--- a/mobile/test/features/pairing/pairing_provider_test.dart
+++ b/mobile/test/features/pairing/pairing_provider_test.dart
@@ -2,9 +2,14 @@ import 'dart:convert';
 
 import 'package:flutter_test/flutter_test.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
+import 'package:nostr/nostr.dart' as nostr;
+import 'package:buzz/features/pairing/pairing_crypto.dart';
 import 'package:buzz/features/pairing/pairing_provider.dart';
 import 'package:buzz/features/pairing/pairing_socket.dart';
 import 'package:buzz/shared/auth/auth.dart';
+import 'package:buzz/shared/crypto/ecdh.dart';
+import 'package:buzz/shared/crypto/nip44.dart';
+import 'package:buzz/shared/relay/relay.dart';
 
 /// Tests for [PairingNotifier]'s legacy `buzz://` payload parsing and
 /// SSRF-prevention validation.
@@ -180,6 +185,115 @@ void main() {
       container.read(pairingProvider.notifier).reset();
       expect(container.read(pairingProvider).status, PairingStatus.idle);
     });
+
+    group('desktop identity recovery', () {
+      const sourceSecret =
+          '09b3065e3570a3a4054660dccd66e12774a99a904fdb0ca02dbc6c3136249506';
+      const sessionSecretHex =
+          'abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789';
+      late _ControllableSocket socket;
+      late PairingNotifier notifier;
+      late String recoveryCode;
+
+      setUp(() {
+        final source = nostr.Keys(sourceSecret);
+        recoveryCode =
+            'nostrpair://${source.public}'
+            '?secret=$sessionSecretHex'
+            '&relay=wss%3A%2F%2Fpairing.buzz.xyz&v=1&mode=recover';
+        notifier = PairingNotifier(
+          socketFactory:
+              ({
+                required wsUrl,
+                required ephemeralPrivkey,
+                required onMessage,
+                required onDisconnected,
+              }) {
+                socket = _ControllableSocket(
+                  ephemeralPrivkey: ephemeralPrivkey,
+                  onMessage: onMessage,
+                  onDisconnected: onDisconnected,
+                );
+                return socket;
+              },
+        );
+        container = ProviderContainer(
+          overrides: [
+            pairingProvider.overrideWith(() => notifier),
+            relayConfigProvider.overrideWith(_RecoveryRelayConfig.new),
+          ],
+        );
+        container.read(pairingProvider);
+        notifier = container.read(pairingProvider.notifier);
+      });
+
+      test('recovery URI enables phone-to-desktop transfer', () async {
+        await notifier.pair(recoveryCode);
+
+        final state = container.read(pairingProvider);
+        expect(state.status, PairingStatus.confirmingSas);
+        expect(state.sendsIdentityToDesktop, isTrue);
+        expect(state.sasCode, hasLength(6));
+      });
+
+      test(
+        'matching SAS sends nsec and successful completion finishes',
+        () async {
+          await notifier.pair(recoveryCode);
+          notifier.confirmSas();
+          expect(container.read(pairingProvider).userConfirmedSas, isTrue);
+
+          socket.sendSourceMessage(
+            sourceSecret: sourceSecret,
+            sessionSecretHex: sessionSecretHex,
+            message: {'type': 'sas-confirm'},
+            includeTranscriptHash: true,
+          );
+
+          expect(
+            container.read(pairingProvider).status,
+            PairingStatus.transferring,
+          );
+          final sentMessages = socket.decryptedPublishedMessages(sourceSecret);
+          expect(
+            sentMessages.any(
+              (message) =>
+                  message['type'] == 'payload' &&
+                  message['payload_type'] == 'nsec' &&
+                  message['payload'] == _RecoveryRelayConfig.nsec,
+            ),
+            isTrue,
+          );
+
+          socket.sendSourceMessage(
+            sourceSecret: sourceSecret,
+            sessionSecretHex: sessionSecretHex,
+            message: {'type': 'complete', 'success': true},
+          );
+          expect(container.read(pairingProvider).status, PairingStatus.success);
+        },
+      );
+
+      test('desktop storage failure surfaces an error', () async {
+        await notifier.pair(recoveryCode);
+        notifier.confirmSas();
+        socket.sendSourceMessage(
+          sourceSecret: sourceSecret,
+          sessionSecretHex: sessionSecretHex,
+          message: {'type': 'sas-confirm'},
+          includeTranscriptHash: true,
+        );
+        socket.sendSourceMessage(
+          sourceSecret: sourceSecret,
+          sessionSecretHex: sessionSecretHex,
+          message: {'type': 'complete', 'success': false},
+        );
+
+        final state = container.read(pairingProvider);
+        expect(state.status, PairingStatus.error);
+        expect(state.errorMessage, contains('could not store'));
+      });
+    });
   });
 }
 
@@ -241,3 +355,92 @@ class _DisconnectingSocket extends PairingSocket {
     disconnectCallback(Exception('Connection closed'));
   }
 }
+
+class _RecoveryRelayConfig extends RelayConfigNotifier {
+  static final nsec = nostr.Keys(
+    '1111111111111111111111111111111111111111111111111111111111111111',
+  ).nsec;
+
+  @override
+  RelayConfig build() => RelayConfig(baseUrl: 'https://relay.test', nsec: nsec);
+}
+
+class _ControllableSocket extends PairingSocket {
+  final String ephemeralPrivkey;
+  final void Function(List<dynamic> message) relayMessageCallback;
+  final List<Map<String, dynamic>> published = [];
+  bool _connected = false;
+  int _eventSequence = 0;
+
+  _ControllableSocket({
+    required this.ephemeralPrivkey,
+    required super.onMessage,
+    required super.onDisconnected,
+  }) : relayMessageCallback = onMessage,
+       super(wsUrl: 'ws://unused', ephemeralPrivkey: ephemeralPrivkey);
+
+  @override
+  bool get isConnected => _connected;
+
+  @override
+  Future<void> connect() async => _connected = true;
+
+  @override
+  void subscribe(String subId, int kind, String pubkeyHex) {}
+
+  @override
+  void publishEvent(Map<String, dynamic> event) => published.add(event);
+
+  @override
+  void dispose() => _connected = false;
+
+  List<Map<String, dynamic>> decryptedPublishedMessages(String sourceSecret) {
+    final key = getConversationKey(
+      sourceSecret,
+      nostr.Keys(ephemeralPrivkey).public,
+    );
+    return published
+        .map(
+          (event) =>
+              jsonDecode(nip44Decrypt(key, event['content'] as String))
+                  as Map<String, dynamic>,
+        )
+        .toList();
+  }
+
+  void sendSourceMessage({
+    required String sourceSecret,
+    required String sessionSecretHex,
+    required Map<String, dynamic> message,
+    bool includeTranscriptHash = false,
+  }) {
+    final source = nostr.Keys(sourceSecret);
+    final targetPubkey = nostr.Keys(ephemeralPrivkey).public;
+    final sessionSecret = hexToBytes(sessionSecretHex);
+    final body = Map<String, dynamic>.from(message);
+    if (includeTranscriptHash) {
+      final shared = ecdhSharedSecret(sourceSecret, targetPubkey);
+      final (_, sasInput) = deriveSas(shared, sessionSecret);
+      body['transcript_hash'] = bytesToHex(
+        deriveTranscriptHash(
+          deriveSessionId(sessionSecret),
+          hexToBytes(source.public),
+          hexToBytes(targetPubkey),
+          sasInput,
+          sessionSecret,
+        ),
+      );
+    }
+    final key = getConversationKey(sourceSecret, targetPubkey);
+    final event = nostr.Event.from(
+      kind: 24134,
+      content: nip44Encrypt(key, jsonEncode(body)),
+      tags: [
+        ['p', targetPubkey],
+      ],
+      secretKey: sourceSecret,
+      createdAt: 1_700_000_000 + _eventSequence++,
+    );
+    relayMessageCallback(['EVENT', 'pair', event.toMap()]);
+  }
+}
diff --git a/mobile/test/features/settings/theme_picker_page_test.dart b/mobile/test/features/settings/theme_picker_page_test.dart
index 010db98ba3..6b166c8efa 100644
--- a/mobile/test/features/settings/theme_picker_page_test.dart
+++ b/mobile/test/features/settings/theme_picker_page_test.dart
@@ -172,7 +172,10 @@ void main() {
     testWidgets('settings hides accent navigation for Buzz', (tester) async {
       await _pumpPicker(
         tester,
-        const SettingsPage(profileHeader: SizedBox.shrink()),
+        SettingsPage(
+          profileHeader: const SizedBox.shrink(),
+          identityRecoveryPageBuilder: (_) => const SizedBox.shrink(),
+        ),
         prefs: {'buzz_color_scheme': 'buzz', 'buzz_accent_color': 4},
       );
 
@@ -184,7 +187,10 @@ void main() {
     ) async {
       await _pumpPicker(
         tester,
-        const SettingsPage(profileHeader: SizedBox.shrink()),
+        SettingsPage(
+          profileHeader: const SizedBox.shrink(),
+          identityRecoveryPageBuilder: (_) => const SizedBox.shrink(),
+        ),
         prefs: {
           'buzz_theme_mode': 'light',
           'buzz_color_scheme': 'github-light',

From a73414ca5efaef6522ace2a98c132cbc52a8331d Mon Sep 17 00:00:00 2001
From: Alessandro Joabar <sandro@squareup.com>
Date: Thu, 6 Aug 2026 15:20:21 -0400
Subject: [PATCH 16/16] compute view polish and leaderboard

Signed-off-by: Alessandro Joabar <sandro@squareup.com>
---
 .../ui/CommunityComputeTerritoryMap.tsx       |  70 +++++++++++
 .../ui/MeshComputeCommunityView.tsx           |  11 +-
 .../ui/MeshComputeImpactReceipt.tsx           |  91 ++++++++++++++
 .../mesh-compute/ui/MeshComputePage.tsx       |   9 +-
 .../ui/MeshComputeShareBanner.tsx             | 112 +++++++++++++-----
 .../ui/MeshComputeTokenLeaderboard.tsx        | 103 ++++++++++++++++
 6 files changed, 364 insertions(+), 32 deletions(-)
 create mode 100644 desktop/src/features/mesh-compute/ui/MeshComputeImpactReceipt.tsx
 create mode 100644 desktop/src/features/mesh-compute/ui/MeshComputeTokenLeaderboard.tsx

diff --git a/desktop/src/features/mesh-compute/ui/CommunityComputeTerritoryMap.tsx b/desktop/src/features/mesh-compute/ui/CommunityComputeTerritoryMap.tsx
index 684078dd40..bdaf2ca9c2 100644
--- a/desktop/src/features/mesh-compute/ui/CommunityComputeTerritoryMap.tsx
+++ b/desktop/src/features/mesh-compute/ui/CommunityComputeTerritoryMap.tsx
@@ -90,6 +90,7 @@ export function CommunityComputeTerritoryMap({
   const hoveredDeployment = hoveredId
     ? (deploymentById.get(hoveredId) ?? null)
     : null;
+  const isHeroDeployment = model.deployments.length === 1;
 
   function selectDeployment(deploymentId: string) {
     if (selectedDeploymentId === undefined) {
@@ -193,6 +194,12 @@ export function CommunityComputeTerritoryMap({
             );
           })}
         </svg>
+        {isHeroDeployment && activeDeployment ? (
+          <HeroDeploymentOverlay
+            deployment={activeDeployment}
+            inferenceActive={inferenceIds.has(activeDeployment.id)}
+          />
+        ) : null}
         {hoveredDeployment ? (
           <div
             className="pointer-events-none absolute bottom-3 left-3 max-w-64 rounded-xl border border-border/70 bg-popover/95 px-3 py-2 shadow-lg backdrop-blur-sm"
@@ -235,6 +242,69 @@ export function CommunityComputeTerritoryMap({
   );
 }
 
+function HeroDeploymentOverlay({
+  deployment,
+  inferenceActive,
+}: {
+  deployment: CommunityComputeDeployment;
+  inferenceActive: boolean;
+}) {
+  return (
+    <div
+      className="pointer-events-none absolute left-1/2 top-1/2 w-[min(19rem,calc(100%-2rem))] -translate-x-1/2 -translate-y-1/2 rounded-xl border border-background/20 bg-background/90 p-3 text-center shadow-xl backdrop-blur-md"
+      data-testid="community-compute-hero-deployment"
+    >
+      <div className="flex items-center justify-center gap-2">
+        <span
+          className={cn(
+            "size-2 rounded-full",
+            deployment.health === "healthy"
+              ? "bg-emerald-500"
+              : "bg-muted-foreground",
+          )}
+        />
+        <span className="text-2xs font-semibold uppercase tracking-wide text-muted-foreground">
+          {inferenceActive ? "Serving now" : deployment.health}
+        </span>
+      </div>
+      <h3
+        className="mt-1 truncate text-sm font-semibold"
+        title={deployment.modelId}
+      >
+        {shortModelName(deployment.modelId)}
+      </h3>
+      <p className="mt-0.5 truncate text-xs text-muted-foreground">
+        {deployment.deviceLabel}
+        {deployment.isSelf ? " · This machine" : ""}
+      </p>
+      <dl className="mt-2 grid grid-cols-3 divide-x divide-border/60 rounded-lg border border-border/60 bg-background/70 py-2">
+        <HeroMetric
+          label="Shared memory"
+          value={formatCapacity(deployment.capacityGb)}
+        />
+        <HeroMetric
+          label="Model footprint"
+          value={formatCapacity(deployment.source.modelSizeGb ?? null)}
+        />
+        <HeroMetric label="Availability" value="Community ready" />
+      </dl>
+    </div>
+  );
+}
+
+function HeroMetric({ label, value }: { label: string; value: string }) {
+  return (
+    <div className="min-w-0 px-2">
+      <dt className="truncate text-3xs uppercase tracking-wide text-muted-foreground">
+        {label}
+      </dt>
+      <dd className="mt-0.5 truncate text-2xs font-semibold" title={value}>
+        {value}
+      </dd>
+    </div>
+  );
+}
+
 function TerritoryShape({
   cells,
   inferenceActive,
diff --git a/desktop/src/features/mesh-compute/ui/MeshComputeCommunityView.tsx b/desktop/src/features/mesh-compute/ui/MeshComputeCommunityView.tsx
index ba14693088..af7a9dac01 100644
--- a/desktop/src/features/mesh-compute/ui/MeshComputeCommunityView.tsx
+++ b/desktop/src/features/mesh-compute/ui/MeshComputeCommunityView.tsx
@@ -67,10 +67,15 @@ export function MeshComputeCommunityView({
       <div>
         <div className="mb-2 flex items-end justify-between gap-3">
           <div>
-            <h2 className="text-lg font-semibold tracking-tight">Model mesh</h2>
+            <h2 className="text-lg font-semibold tracking-tight">
+              {model.deployments.length === 1
+                ? "Your community’s first compute node"
+                : "Model mesh"}
+            </h2>
             <p className="text-sm text-muted-foreground">
-              Each territory is one ready model on one device. Area reflects its
-              reported model-memory tier.
+              {model.deployments.length === 1
+                ? "This machine is the foundation of the mesh. More contributors add capacity, model choice, and resilience."
+                : "Each territory is one ready model on one device. Area reflects its reported model-memory tier."}
             </p>
           </div>
           {!simulated ? (
diff --git a/desktop/src/features/mesh-compute/ui/MeshComputeImpactReceipt.tsx b/desktop/src/features/mesh-compute/ui/MeshComputeImpactReceipt.tsx
new file mode 100644
index 0000000000..fa5e7c6a8d
--- /dev/null
+++ b/desktop/src/features/mesh-compute/ui/MeshComputeImpactReceipt.tsx
@@ -0,0 +1,91 @@
+import { Activity, Cpu, Network, Sparkles } from "lucide-react";
+
+import { cn } from "@/shared/lib/cn";
+import type { useMeshComputeState } from "../hooks/useMeshComputeState";
+
+export function MeshComputeImpactReceipt({
+  mesh,
+}: {
+  mesh: ReturnType<typeof useMeshComputeState>;
+}) {
+  const { memory, toggle, usage } = mesh;
+  const isSharing = toggle.isSharing;
+  const tokensProcessed = usage?.tokensServed ?? 0;
+  const peers = usage?.peers ?? 0;
+  const capacity = memory.totalGb == null ? "—" : formatGb(memory.totalGb);
+
+  const items = [
+    {
+      icon: Cpu,
+      label: "Capacity offered",
+      value: isSharing ? capacity : "Not sharing",
+    },
+    {
+      icon: Sparkles,
+      label: "Tokens served",
+      value: isSharing ? formatCount(tokensProcessed) : "—",
+    },
+    {
+      icon: Network,
+      label: "Mesh peers",
+      value: isSharing ? formatCount(peers) : "—",
+    },
+  ];
+
+  return (
+    <section
+      className={cn(
+        "overflow-hidden rounded-2xl border border-border/70 bg-background",
+        !isSharing && "bg-muted/10",
+      )}
+      data-testid="compute-impact-receipt"
+    >
+      <div className="flex items-start gap-3 border-border/60 border-b px-4 py-3">
+        <span className="flex size-8 shrink-0 items-center justify-center rounded-lg bg-foreground text-background">
+          <Activity className="size-4" />
+        </span>
+        <div>
+          <h2 className="text-sm font-semibold">Your contribution</h2>
+          <p className="mt-0.5 text-xs text-muted-foreground">
+            {isSharing
+              ? usage?.inflight
+                ? `Helping run ${usage.inflight} request${usage.inflight === 1 ? "" : "s"} right now.`
+                : "Available when your community needs more compute."
+              : "Turn on automatic contribution to start building your impact."}
+          </p>
+        </div>
+        {isSharing ? (
+          <span className="ml-auto flex shrink-0 items-center gap-1.5 text-xs font-medium">
+            <span className="size-2 rounded-full bg-emerald-500" /> Live
+          </span>
+        ) : null}
+      </div>
+      <dl className="grid grid-cols-3 divide-x divide-border/60">
+        {items.map(({ icon: Icon, label, value }) => (
+          <div className="min-w-0 px-4 py-3" key={label}>
+            <dt className="flex items-center gap-1.5 truncate text-2xs text-muted-foreground">
+              <Icon className="size-3" /> {label}
+            </dt>
+            <dd className="mt-1 truncate text-lg font-semibold tabular-nums">
+              {value}
+            </dd>
+          </div>
+        ))}
+      </dl>
+      <p className="border-border/60 border-t px-4 py-2 text-2xs text-muted-foreground">
+        Session totals from this machine. Request attribution to other members
+        is coming soon.
+      </p>
+    </section>
+  );
+}
+
+function formatCount(value: number): string {
+  return new Intl.NumberFormat(undefined, { maximumFractionDigits: 0 }).format(
+    value,
+  );
+}
+
+function formatGb(value: number): string {
+  return `${new Intl.NumberFormat(undefined, { maximumFractionDigits: 1 }).format(value)} GB`;
+}
diff --git a/desktop/src/features/mesh-compute/ui/MeshComputePage.tsx b/desktop/src/features/mesh-compute/ui/MeshComputePage.tsx
index 574ddb9b86..3a4d5d165b 100644
--- a/desktop/src/features/mesh-compute/ui/MeshComputePage.tsx
+++ b/desktop/src/features/mesh-compute/ui/MeshComputePage.tsx
@@ -12,8 +12,10 @@ import {
 import { useMeshComputeState } from "../hooks/useMeshComputeState";
 import { CommunityComputeTutorialPanel } from "./CommunityComputeTutorialPanel";
 import { MeshComputeCommunityView } from "./MeshComputeCommunityView";
+import { MeshComputeImpactReceipt } from "./MeshComputeImpactReceipt";
 import { MeshComputeSettingsCard } from "./MeshComputeSettingsCard";
 import { MeshComputeShareBanner } from "./MeshComputeShareBanner";
+import { MeshComputeTokenLeaderboard } from "./MeshComputeTokenLeaderboard";
 
 export function MeshComputePage() {
   const { activeCommunity } = useCommunities();
@@ -52,7 +54,7 @@ export function MeshComputePage() {
             <BookOpen /> Tutorial
           </Button>
         }
-        description={`See what ${communityName} can run and contribute this machine’s spare capacity.`}
+        description={`Contribute this machine’s spare capacity to unlock more models and keep ${communityName}’s agents available when demand grows.`}
         title="Compute"
       />
 
@@ -80,7 +82,10 @@ export function MeshComputePage() {
                 onStepChange={setTutorialStep}
                 step={tutorialStep}
               />
-            ) : null}
+            ) : (
+              <MeshComputeImpactReceipt mesh={mesh} />
+            )}
+            <MeshComputeTokenLeaderboard mesh={mesh} simulated={tutorialOpen} />
             <MeshComputeCommunityView
               communityName={
                 tutorialOpen ? tutorialFixture.title : communityName
diff --git a/desktop/src/features/mesh-compute/ui/MeshComputeShareBanner.tsx b/desktop/src/features/mesh-compute/ui/MeshComputeShareBanner.tsx
index 925e7f181b..b65b17a613 100644
--- a/desktop/src/features/mesh-compute/ui/MeshComputeShareBanner.tsx
+++ b/desktop/src/features/mesh-compute/ui/MeshComputeShareBanner.tsx
@@ -1,4 +1,4 @@
-import { Cpu, LoaderCircle } from "lucide-react";
+import { Cpu, LoaderCircle, ShieldCheck, Sparkles, Zap } from "lucide-react";
 
 import { Switch } from "@/shared/ui/switch";
 import { cn } from "@/shared/lib/cn";
@@ -13,6 +13,7 @@ export function MeshComputeShareBanner({
 }) {
   const {
     error,
+    memory,
     modelToShare,
     pendingAction,
     shareSwitchChecked,
@@ -21,6 +22,8 @@ export function MeshComputeShareBanner({
     setSharing,
   } = mesh;
   const busy = pendingAction !== null;
+  const model = status?.modelName ?? status?.modelId ?? modelToShare;
+  const capacity = memory.totalGb == null ? null : formatGb(memory.totalGb);
   const statusCopy = shareStatusCopy({
     communityName,
     modelToShare,
@@ -32,14 +35,14 @@ export function MeshComputeShareBanner({
 
   return (
     <section
-      className="rounded-2xl border border-border/70 bg-muted/15 px-4 py-3.5"
+      className="overflow-hidden rounded-2xl border border-foreground/15 bg-linear-to-br from-foreground/[0.07] to-muted/10"
       data-testid="compute-share-banner"
     >
-      <div className="flex min-w-0 items-center gap-3">
+      <div className="flex min-w-0 items-start gap-3 px-4 py-4">
         <span
           aria-hidden="true"
           className={cn(
-            "flex size-9 shrink-0 items-center justify-center rounded-xl border border-border/70 bg-background",
+            "flex size-10 shrink-0 items-center justify-center rounded-xl border border-border/70 bg-background",
             toggle.isSharing && "border-foreground/30",
           )}
         >
@@ -51,17 +54,14 @@ export function MeshComputeShareBanner({
         </span>
         <div className="min-w-0 flex-1">
           <label
-            className="text-sm font-semibold"
+            className="text-base font-semibold"
             htmlFor="compute-share-banner-toggle"
           >
-            Share this machine
+            Automatic contribution
           </label>
-          <p
-            className="mt-0.5 truncate text-xs text-muted-foreground"
-            data-testid="compute-share-banner-status"
-            title={statusCopy}
-          >
-            {statusCopy}
+          <p className="mt-1 max-w-2xl text-sm leading-relaxed text-muted-foreground">
+            Let Buzz choose the most useful compatible model and make this
+            machine available when {communityName} needs it.
           </p>
         </div>
         <Switch
@@ -72,15 +72,73 @@ export function MeshComputeShareBanner({
           onCheckedChange={setSharing}
         />
       </div>
-      {error ? (
-        <p className="mt-2 text-xs text-destructive" role="alert">
-          {error}
+
+      <div className="grid gap-px border-border/60 border-t bg-border/60 sm:grid-cols-3">
+        <Benefit
+          icon={Sparkles}
+          label="Unlock community models"
+          detail={
+            model ? `Recommended: ${model}` : "Hardware-aware model selection"
+          }
+        />
+        <Benefit
+          icon={Zap}
+          label="Increase availability"
+          detail={
+            capacity
+              ? `Offer up to ${capacity}`
+              : "Uses compatible spare capacity"
+          }
+        />
+        <Benefit
+          icon={ShieldCheck}
+          label="You stay in control"
+          detail="Pause anytime; advanced limits in Settings"
+        />
+      </div>
+
+      <div className="border-border/60 border-t bg-background/60 px-4 py-2.5">
+        <p
+          className="text-xs text-muted-foreground"
+          data-testid="compute-share-banner-status"
+        >
+          {statusCopy}
         </p>
-      ) : null}
+        {error ? (
+          <p className="mt-1 text-xs text-destructive" role="alert">
+            {error}
+          </p>
+        ) : null}
+      </div>
     </section>
   );
 }
 
+function Benefit({
+  icon: Icon,
+  label,
+  detail,
+}: {
+  icon: typeof Sparkles;
+  label: string;
+  detail: string;
+}) {
+  return (
+    <div className="flex items-start gap-2 bg-background/80 px-4 py-3">
+      <Icon className="mt-0.5 size-3.5 shrink-0" />
+      <div className="min-w-0">
+        <p className="text-xs font-medium">{label}</p>
+        <p
+          className="mt-0.5 truncate text-2xs text-muted-foreground"
+          title={detail}
+        >
+          {detail}
+        </p>
+      </div>
+    </div>
+  );
+}
+
 function shareStatusCopy({
   communityName,
   isConsuming,
@@ -96,18 +154,18 @@ function shareStatusCopy({
   pendingAction: "start" | "stop" | null;
   statusModel: string | null;
 }): string {
-  if (pendingAction === "start") {
+  if (pendingAction === "start")
     return `Preparing ${statusModel ?? modelToShare ?? "a model"} for ${communityName}…`;
-  }
   if (pendingAction === "stop") return "Stopping shared compute…";
-  if (isSharing) {
+  if (isSharing)
     return `${statusModel ?? modelToShare ?? "A model"} is available to ${communityName}`;
-  }
-  if (isConsuming) {
-    return "Using another member’s compute; turn this on to contribute instead";
-  }
-  if (modelToShare) {
-    return `${modelToShare} is ready to contribute to ${communityName}`;
-  }
-  return "Choose a model in Settings before sharing";
+  if (isConsuming)
+    return "Using another member’s compute; enable this to contribute instead";
+  if (modelToShare)
+    return "Ready to contribute automatically when you turn this on";
+  return "Checking this machine and choosing a compatible model…";
+}
+
+function formatGb(value: number): string {
+  return `${new Intl.NumberFormat(undefined, { maximumFractionDigits: 1 }).format(value)} GB`;
 }
diff --git a/desktop/src/features/mesh-compute/ui/MeshComputeTokenLeaderboard.tsx b/desktop/src/features/mesh-compute/ui/MeshComputeTokenLeaderboard.tsx
new file mode 100644
index 0000000000..9b6a999fb8
--- /dev/null
+++ b/desktop/src/features/mesh-compute/ui/MeshComputeTokenLeaderboard.tsx
@@ -0,0 +1,103 @@
+import { Medal, Trophy } from "lucide-react";
+
+import { cn } from "@/shared/lib/cn";
+import type { useMeshComputeState } from "../hooks/useMeshComputeState";
+
+const PREVIEW_LEADERS = [
+  { name: "Maya", tokens: 2_840_912 },
+  { name: "Jon", tokens: 1_967_401 },
+  { name: "Priya", tokens: 1_204_885 },
+] as const;
+
+export function MeshComputeTokenLeaderboard({
+  mesh,
+  simulated = false,
+}: {
+  mesh: ReturnType<typeof useMeshComputeState>;
+  simulated?: boolean;
+}) {
+  const yourTokens = simulated ? 1_638_240 : (mesh.usage?.tokensServed ?? 0);
+  const communityLeaders = simulated ? PREVIEW_LEADERS : [];
+  const rows = [...communityLeaders, { name: "You", tokens: yourTokens }]
+    .sort((a, b) => b.tokens - a.tokens)
+    .map((entry, index) => ({ ...entry, rank: index + 1 }));
+  const yourRank =
+    rows.find((entry) => entry.name === "You")?.rank ?? rows.length;
+
+  return (
+    <section
+      className="overflow-hidden rounded-2xl border border-border/70 bg-background"
+      data-testid="compute-token-leaderboard"
+    >
+      <div className="flex items-start gap-3 border-border/60 border-b px-4 py-3.5">
+        <span className="flex size-9 shrink-0 items-center justify-center rounded-xl bg-amber-500/15 text-amber-700 dark:text-amber-300">
+          <Trophy className="size-4" />
+        </span>
+        <div className="min-w-0 flex-1">
+          <h2 className="text-sm font-semibold">
+            Community token contributors
+          </h2>
+          <p className="mt-0.5 text-xs text-muted-foreground">
+            {simulated
+              ? "Tokenmaxxing, inverted: celebrate the tokens you serve—not the tokens you consume."
+              : "Your locally reported total. Community rankings will appear when aggregate reporting is available."}
+          </p>
+        </div>
+        {simulated ? (
+          <div className="shrink-0 text-right">
+            <p className="text-2xs font-medium uppercase tracking-wide text-muted-foreground">
+              Your rank
+            </p>
+            <p className="mt-0.5 text-lg font-semibold tabular-nums">
+              #{yourRank}
+            </p>
+          </div>
+        ) : null}
+      </div>
+
+      <ol className="divide-y divide-border/60">
+        {rows.map((entry) => (
+          <li
+            className={cn(
+              "grid grid-cols-[2.5rem_1fr_auto] items-center gap-2 px-4 py-2.5",
+              entry.name === "You" && "bg-foreground/[0.045]",
+            )}
+            key={entry.name}
+          >
+            <span className="flex items-center gap-1 text-xs font-semibold tabular-nums text-muted-foreground">
+              {entry.rank <= 3 ? <Medal className="size-3.5" /> : null}#
+              {entry.rank}
+            </span>
+            <span className="truncate text-sm font-medium">
+              {entry.name}
+              {entry.name === "You" ? (
+                <span className="ml-2 rounded-full bg-foreground px-2 py-0.5 text-3xs font-semibold text-background">
+                  YOU
+                </span>
+              ) : null}
+            </span>
+            <span className="text-sm font-semibold tabular-nums">
+              {formatTokens(entry.tokens)}
+              <span className="ml-1 text-2xs font-normal text-muted-foreground">
+                tokens
+              </span>
+            </span>
+          </li>
+        ))}
+      </ol>
+
+      <p className="border-border/60 border-t bg-muted/10 px-4 py-2 text-2xs text-muted-foreground">
+        {simulated
+          ? "Tutorial preview · example contribution totals"
+          : "Community rankings preview · aggregate contribution reporting is coming soon."}
+      </p>
+    </section>
+  );
+}
+
+function formatTokens(value: number): string {
+  return new Intl.NumberFormat(undefined, {
+    notation: value >= 10_000 ? "compact" : "standard",
+    maximumFractionDigits: 1,
+  }).format(value);
+}