From f6e6617a9dcc2308d5039f8afaab974b49fb9577 Mon Sep 17 00:00:00 2001
From: Will Pfleger <pfleger.will@gmail.com>
Date: Mon, 24 Aug 2026 16:13:03 -0400
Subject: [PATCH 1/9] fix(desktop): bound thread /query and surface load
 errors, not false-empty (#6447)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Long threads in the desktop app sometimes never load (stuck on a
skeleton until you close and reopen the panel), and a failed load
silently renders as "No replies in this branch yet" — presenting a
broken fetch as an authoritative empty thread with no way to recover.
This fixes both, the two IMPORTANT findings from the thread-load
investigation.

## Defect 1 — unbounded `/query` request

The shared `reqwest::Client` in `relay.rs` sets no timeout, and neither
`/query` request builder set a per-request `.timeout(...)`. A stalled or
half-open connection (headers or body never arrive) leaves the request
pending forever, so a thread-history load hangs on the skeleton
indefinitely.

Fix: a 30s per-request deadline on both `/query` builders, funnelled
through one `send_query_request` helper so the timeout can never be
applied to one builder and dropped from the other. Scoped per-request
rather than client-level because the same client also serves STT/TTS
model downloads, builderlab auth, and the media proxy — a client-level
timeout would cut those off. The deadline sits above the 25s WS
`HISTORY_TIMEOUT_MS` so a slow-but-live relay isn't cut off before the
WebSocket path would be. A timeout surfaces through
`classify_request_error` as the stable `"relay unreachable: request
timed out"` string.

`send()` resolves as soon as response headers arrive, so a relay that
returns headers and then stalls the body trips the deadline during body
consumption, not at `send()` — and that consumption happens on two
paths: `parse_json_response` for 2xx, and `relay_error_message` for a
non-success status (500/429/…). Both paths route their body-consumption
error through one shared `classify_body_timeout` helper so they can't
drift: a stalled body surfaces the stable `"relay unreachable: request
timed out"` string on either path rather than the malformed-response
bucket (2xx) or a bare `"relay returned 500"` status label (non-2xx). A
genuinely non-stalled error still keeps its status classification.

## Defect 2 — terminal error painted as empty

`ChannelScreen` consumed only `isPending`/`data` from the thread-replies
query. Once React Query exhausted its one retry, `isPending` was false
and the zero-length data fell through `selectDeferredListRenderState` to
the `"empty"` state — indistinguishable from a genuinely empty branch,
with no retry affordance.

Fix: plumb `isError` + `refetch` through `ChannelScreen` → `ChannelPane`
→ `MessageThreadPanel`. A pure `selectThreadRepliesSurface` helper
decides the paint in strict precedence — the load-bearing invariant is
that a terminal error **never** resolves to `"empty"`, and cached
replies stay visible non-destructively under a later error (the error
card only surfaces when there is nothing to show). The panel renders an
explicit "Couldn't load replies" + Retry card (testids
`message-thread-replies-error` / `message-thread-replies-retry`).

`ProjectConversationPanel` is a second producer of the same shared panel
and used to hard-code `threadRepliesPending={false}` with no
error/retry, so a failed load in a Projects conversation still painted
the false-empty. It now propagates the same
`isPending`/`isError`/`refetch` from its `useThreadReplies` query.

The multi-root `useThreadRepliesForRoots` hook (the Huddle transcript
and Projects-agent conversation surfaces) had the same gap in its
`useQueries` `combine`: it returned only `{ events, isPending }`, so a
failed reply subtree contributed zero rows and vanished. The combine is
now a pure, unit-testable `combineThreadRepliesResults` that exposes
aggregate `isError`/`error` plus a `refetch` that re-runs only the
failed subtrees. Both multi-root consumers render the shared "Couldn't
load replies" + Retry card when a subtree fails: the Projects-agent
conversation after its transcript, and the Huddle transcript as a
non-destructive banner above the timeline. `useHuddleChannelMessages`
used to read only `.events` and discard the aggregate state, so one
summarized root failing left the flattened transcript presenting as
complete; it now propagates `threadRepliesError`/`onRetryThreadReplies`
through `ChannelScreen` into `ChannelPane`, where successful rows stay
visible and `onRetry` re-runs only the failed subtrees.

The error card carries `role="alert"` so its asynchronous appearance is
announced to assistive tech — without a live region a screen-reader user
parked in the composer never learns the load failed or that Retry became
available.

## Tests

- `stalled_query_request_times_out_with_classified_error` — a loopback
server that never responds; asserts the stable classified timeout
string.
- `stalled_response_body_times_out_with_classified_error` — a loopback
server that writes valid 2xx JSON headers then stalls the body past the
deadline; asserts the classified timeout string, not the malformed
bucket.
- `stalled_error_response_body_times_out_with_classified_error` — a
loopback that writes `500` headers promising a body it never sends;
asserts the classified timeout string rather than the `500` status
label.
- `non_stalled_error_response_yields_status_message` — a promptly-served
`500` still surfaces `"relay returned 500 Internal Server Error"`,
pinning that timeout preservation is scoped to actual timeouts.
- `selectThreadRepliesSurface` — pending→skeleton, terminal error→error
(never empty), page-2 failure never empty, cached rows stay visible
under error, successful-empty→empty, retry-success→list,
streaming→pending, and huddle-transcript collapse.
- `MessageThreadReplyState` mounted test — terminal error renders the
error card (asserting `role="alert"`), never the empty card.
- `combineThreadRepliesResults` — multi-root aggregation/order, a failed
subtree surfaces the aggregate error and never drops rows, aggregate
pending, refetch re-runs only failed queries, all-success yields no
error.
- `thread-load-failure.spec.ts` (smoke E2E) — binds the real
channel-thread panel wiring: forces a terminal `get_thread_replies`
failure at the IPC boundary, asserts the error card renders (never the
false-empty) and Retry recovers.
- `project-conversation-load-failure.spec.ts` (smoke E2E) — the same
guard for the Projects conversation producer, driven through the
Projects Channels-tab row.
- `huddle-thread-load-failure.spec.ts` (smoke E2E) — the consumer-level
guard the combine unit test can't provide: drives the real Huddle wiring
(`useHuddleChannelMessages` → `ChannelScreen` → `ChannelPane`) with two
summarized roots, fails one subtree's fetch at the IPC boundary, asserts
the surviving root's reply stays visible while the retry alert surfaces,
then Retry recovers the failed subtree and clears the alert.

## Structure

To stay under the desktop file-size ratchet, `relay.rs`'s inline test
module moved to `relay/tests.rs`, and two pure pieces were extracted
from the panel: the empty/error reply cards (`MessageThreadReplyState`)
and the per-row branch-highlight derivation
(`selectThreadRowHighlight`).

---------

Signed-off-by: Will Pfleger <pfleger.will@gmail.com>
Co-authored-by: Duncan <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz>
---
 desktop/playwright.config.ts                  |   3 +
 desktop/src-tauri/src/relay.rs                | 501 +++-----------
 desktop/src-tauri/src/relay/tests.rs          | 615 ++++++++++++++++++
 .../src/features/channels/ui/ChannelPane.tsx  |  12 +
 .../features/channels/ui/ChannelPane.types.ts |  10 +
 .../features/channels/ui/ChannelScreen.tsx    |  13 +-
 .../channels/ui/useHuddleChannelMessages.ts   |  10 +-
 .../combineThreadRepliesResults.test.mjs      | 104 +++
 .../src/features/messages/lib/threadPanel.ts  |  56 ++
 .../lib/threadReplyHighlight.test.mjs         |  86 +++
 .../messages/lib/threadReplyHighlight.ts      |  45 ++
 .../messages/lib/timelineSnapshot.test.mjs    | 121 ++++
 .../features/messages/lib/timelineSnapshot.ts |  68 ++
 .../messages/ui/MessageThreadPanel.tsx        | 394 +++++------
 .../ui/MessageThreadReplyState.test.mjs       | 162 +++++
 .../messages/ui/MessageThreadReplyState.tsx   | 127 ++++
 .../src/features/messages/useThreadReplies.ts |  38 +-
 .../projects/ui/ProjectConversationPanel.tsx  |   6 +-
 .../projects/ui/ProjectsAgentPromptPage.tsx   |   4 +
 .../e2e/huddle-thread-load-failure.spec.ts    | 182 ++++++
 .../project-conversation-load-failure.spec.ts | 192 ++++++
 desktop/tests/e2e/thread-load-failure.spec.ts | 161 +++++
 22 files changed, 2273 insertions(+), 637 deletions(-)
 create mode 100644 desktop/src-tauri/src/relay/tests.rs
 create mode 100644 desktop/src/features/messages/combineThreadRepliesResults.test.mjs
 create mode 100644 desktop/src/features/messages/lib/threadReplyHighlight.test.mjs
 create mode 100644 desktop/src/features/messages/lib/threadReplyHighlight.ts
 create mode 100644 desktop/src/features/messages/ui/MessageThreadReplyState.test.mjs
 create mode 100644 desktop/src/features/messages/ui/MessageThreadReplyState.tsx
 create mode 100644 desktop/tests/e2e/huddle-thread-load-failure.spec.ts
 create mode 100644 desktop/tests/e2e/project-conversation-load-failure.spec.ts
 create mode 100644 desktop/tests/e2e/thread-load-failure.spec.ts

diff --git a/desktop/playwright.config.ts b/desktop/playwright.config.ts
index 9099beff69..69250c4b53 100644
--- a/desktop/playwright.config.ts
+++ b/desktop/playwright.config.ts
@@ -86,6 +86,9 @@ export default defineConfig({
         "**/home-collapsed-top-chrome.spec.ts",
         "**/top-chrome-zoom-clearance.spec.ts",
         "**/thread-unread.spec.ts",
+        "**/thread-load-failure.spec.ts",
+        "**/project-conversation-load-failure.spec.ts",
+        "**/huddle-thread-load-failure.spec.ts",
         "**/workspace-rail.spec.ts",
         "**/community-rail.spec.ts",
         "**/boot-splash.spec.ts",
diff --git a/desktop/src-tauri/src/relay.rs b/desktop/src-tauri/src/relay.rs
index bd3fefb125..f408ef2afd 100644
--- a/desktop/src-tauri/src/relay.rs
+++ b/desktop/src-tauri/src/relay.rs
@@ -16,6 +16,19 @@ const DEFAULT_RELAY_WS_URL: &str = "ws://localhost:3000";
 // classifier keys on. Extracted to a const so a test can pin that contract.
 const MALFORMED_RESPONSE_MESSAGE: &str = "relay returned malformed response: not valid JSON";
 
+// Per-request deadline for the `POST /query` HTTP bridge, covering both the
+// header exchange and full body consumption. The shared `http_client` sets no
+// client-level timeout — deliberately, because it is also used for long-running
+// STT/TTS model downloads, builderlab auth, and the media proxy — so a stalled
+// or half-open `/query` connection would otherwise leave the request pending
+// forever, hanging the caller (e.g. a thread-history load that never resolves
+// and shows a permanent skeleton). A per-request timeout scoped to `/query`
+// bounds that without affecting the client's other users. A timeout surfaces
+// through `classify_request_error` as the stable `"relay unreachable: request
+// timed out"` string. Set above the 25s WS history timeout so a slow-but-live
+// relay is not cut off before the WebSocket path would be.
+const QUERY_REQUEST_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
+
 fn configured_env_var(name: &str) -> Option<String> {
     std::env::var(name)
         .ok()
@@ -167,6 +180,22 @@ pub(crate) fn classify_request_error(e: &reqwest::Error) -> String {
     }
 }
 
+/// Preserve a body-consumption timeout as the stable connectivity classification.
+///
+/// `send()` resolves once response headers arrive, so a body that stalls past
+/// the request deadline trips the timeout during body consumption rather than
+/// at `send()`. That is a connectivity failure, not a malformed body or a plain
+/// status error. Both body-consumption paths — the 2xx `parse_json_response`
+/// and the non-2xx `relay_error_message` — route their consumption error
+/// through this one helper so a stalled body can never be classified as
+/// "request timed out" on one path while the other buries it under a malformed
+/// or status label. Returns `Some("relay unreachable: request timed out")` for
+/// a timeout; `None` otherwise, leaving the caller to apply its own non-timeout
+/// label.
+fn classify_body_timeout(e: &reqwest::Error) -> Option<String> {
+    e.is_timeout().then(|| classify_request_error(e))
+}
+
 /// Detect responses that were intercepted by a captive portal or auth proxy.
 ///
 /// Returns `Some(msg)` when the response clearly did not come from the relay:
@@ -230,10 +259,16 @@ pub(crate) async fn parse_json_response<T: DeserializeOwned>(
     // "relay unreachable:" bucket so it surfaces loudly instead of being treated
     // as a transient unreachable-relay condition. The reqwest error detail is
     // dropped because it contains the raw URL.
-    response
-        .json::<T>()
-        .await
-        .map_err(|_| MALFORMED_RESPONSE_MESSAGE.to_string())
+    //
+    // A body-consumption timeout is the exception: `send()` resolves once
+    // headers arrive, so a body that stalls past the request deadline trips the
+    // timeout HERE rather than at send(). That is a connectivity failure, not a
+    // malformed body, so route it through `classify_body_timeout` — the same
+    // helper the non-2xx error-body path uses — to preserve the stable
+    // "relay unreachable: request timed out" label.
+    response.json::<T>().await.map_err(|e| {
+        classify_body_timeout(&e).unwrap_or_else(|| MALFORMED_RESPONSE_MESSAGE.to_string())
+    })
 }
 
 /// Extract the `retry in Ns` hint from a rate-limit error string.
@@ -264,7 +299,21 @@ pub async fn relay_error_message(response: reqwest::Response) -> String {
     }
 
     // Real relay error: extract the structured message field if available.
-    let body = response.text().await.unwrap_or_default();
+    // `text()` consumes the body, which — like the 2xx path — can trip the
+    // request deadline if the relay sends status headers then stalls the body.
+    // Preserve that timeout as the stable connectivity classification via the
+    // shared helper instead of letting `unwrap_or_default` swallow it into a
+    // bare status label. A non-timeout body error still degrades to an empty
+    // body → status-only message, exactly as before.
+    let body = match response.text().await {
+        Ok(body) => body,
+        Err(e) => {
+            if let Some(timeout) = classify_body_timeout(&e) {
+                return timeout;
+            }
+            String::new()
+        }
+    };
 
     // 429 Too Many Requests → typed `relay rate-limited:` prefix so the TS
     // client can activate the rate-limit gate without confusing it with a
@@ -328,22 +377,15 @@ pub async fn query_relay_at(
     let body_bytes =
         serde_json::to_vec(filters).map_err(|e| format!("filter serialization failed: {e}"))?;
     let auth = build_nip98_auth_header(&Method::POST, &url, &body_bytes, state)?;
-
-    let response = state
-        .http_client
-        .post(&url)
-        .header("Authorization", auth)
-        .header("Content-Type", "application/json")
-        .body(body_bytes)
-        .send()
-        .await
-        .map_err(|e| classify_request_error(&e))?;
-
-    if !response.status().is_success() {
-        return Err(relay_error_message(response).await);
-    }
-
-    parse_json_response(response).await
+    send_query_request(
+        &state.http_client,
+        &url,
+        &auth,
+        None,
+        body_bytes,
+        QUERY_REQUEST_TIMEOUT,
+    )
+    .await
 }
 
 pub async fn query_relay_at_with_keys(
@@ -358,11 +400,38 @@ pub async fn query_relay_at_with_keys(
     let body_bytes =
         serde_json::to_vec(filters).map_err(|e| format!("filter serialization failed: {e}"))?;
     let auth = build_nip98_auth_header_for_keys(keys, &Method::POST, &url, &body_bytes)?;
-    let mut request = state
-        .http_client
-        .post(&url)
+    send_query_request(
+        &state.http_client,
+        &url,
+        &auth,
+        auth_tag,
+        body_bytes,
+        QUERY_REQUEST_TIMEOUT,
+    )
+    .await
+}
+
+/// Issue an authenticated `POST /query` and parse the response, applying the
+/// per-request `timeout` that bounds a stalled or half-open relay connection.
+///
+/// Both `/query` builders funnel through this one helper so the timeout can
+/// never be applied to one builder and dropped from the other, and so a test
+/// can drive the real send/timeout/classify path with a short deadline against
+/// a stalled loopback. A timeout surfaces through `classify_request_error` as
+/// the stable `"relay unreachable: request timed out"` string.
+async fn send_query_request(
+    http_client: &reqwest::Client,
+    url: &str,
+    auth: &str,
+    auth_tag: Option<&str>,
+    body_bytes: Vec<u8>,
+    timeout: std::time::Duration,
+) -> Result<Vec<nostr::Event>, String> {
+    let mut request = http_client
+        .post(url)
         .header("Authorization", auth)
-        .header("Content-Type", "application/json");
+        .header("Content-Type", "application/json")
+        .timeout(timeout);
     if let Some(tag) = auth_tag {
         request = request.header("x-auth-tag", tag);
     }
@@ -611,384 +680,4 @@ pub async fn submit_signed_event_with_keys(
 // ── Tests ───────────────────────────────────────────────────────────────────
 
 #[cfg(test)]
-mod tests {
-    use super::{
-        build_profile_event, classify_intercepted_response, effective_agent_relay_url,
-        extract_retry_in_hint, parse_command_response, relay_http_base_url,
-        MALFORMED_RESPONSE_MESSAGE,
-    };
-    use serde::Deserialize;
-
-    // ── extract_retry_in_hint ────────────────────────────────────────────────
-
-    #[test]
-    fn extracts_hint_from_429_body() {
-        assert_eq!(
-            extract_retry_in_hint(r#"{"error":"rate-limited: quota exceeded; retry in 4s"}"#),
-            Some(4)
-        );
-    }
-
-    #[test]
-    fn extracts_hint_when_no_json_wrapper() {
-        assert_eq!(extract_retry_in_hint("retry in 30s"), Some(30));
-    }
-
-    #[test]
-    fn returns_none_when_no_hint_present() {
-        assert_eq!(
-            extract_retry_in_hint(r#"{"error":"rate-limited: quota exceeded"}"#),
-            None
-        );
-        assert_eq!(extract_retry_in_hint(""), None);
-    }
-
-    #[test]
-    fn overlong_digit_string_returns_none() {
-        // A digit sequence that exceeds u64::MAX cannot be parsed; the function
-        // must return None (→ caller uses the default) rather than panicking.
-        assert_eq!(
-            extract_retry_in_hint("retry in 99999999999999999999999s"),
-            None
-        );
-    }
-
-    // ── relay_error_message: hint capping ────────────────────────────────────
-    //
-    // Verify that an oversized relay hint is capped in the returned message
-    // string, not just inside `activate_rate_limit()`. This guarantees every
-    // consumer — including the TS gate via `applyTauriRateLimitIfNeeded` —
-    // receives the capped value rather than the raw untrusted relay value.
-
-    #[tokio::test]
-    async fn oversized_hint_is_capped_in_relay_error_message_string() {
-        use crate::relay_admission::{reset_rate_limit_gate, MAX_HINT_SECONDS, TEST_SERIAL};
-        use std::io::{Read as _, Write as _};
-
-        let _serial = TEST_SERIAL.lock().await;
-        reset_rate_limit_gate();
-
-        // Use a std::net listener on a std::thread — the same pattern as the
-        // relay_admission loopback tests. This avoids two races that cause CI
-        // failures with tokio::net + into_std():
-        //  1. No request read: the client is still sending when the response
-        //     arrives → hyper `UnexpectedMessage`/`Canceled` under load.
-        //  2. into_std() leaves the socket in nonblocking mode → write_all
-        //     may return WouldBlock and silently drop the response.
-        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
-        let addr = listener.local_addr().unwrap();
-
-        // Serve a 429 with a hint far exceeding MAX_HINT_SECONDS (300).
-        let oversized = 1_000_000u64;
-        let body = format!(r#"{{"error":"rate-limited: quota exceeded; retry in {oversized}s"}}"#);
-        let body_len = body.len();
-        std::thread::spawn(move || {
-            if let Ok((mut stream, _)) = listener.accept() {
-                // Read the request first so the client finishes sending before
-                // we write the response — mirrors relay_admission.rs pattern.
-                let mut buf = [0u8; 4096];
-                let _ = stream.read(&mut buf);
-                let response = format!(
-                    "HTTP/1.1 429 Too Many Requests\r\nContent-Type: application/json\r\nContent-Length: {body_len}\r\nConnection: close\r\n\r\n{body}"
-                );
-                let _ = stream.write_all(response.as_bytes());
-                let _ = stream.flush();
-            }
-        });
-
-        let client = reqwest::Client::new();
-        let response = client
-            .get(format!("http://{addr}/"))
-            .send()
-            .await
-            .expect("request must succeed");
-
-        let msg = super::relay_error_message(response).await;
-
-        // The message must embed the CAPPED hint, not the raw 1 000 000.
-        assert_eq!(
-            msg,
-            format!("relay rate-limited: retry in {MAX_HINT_SECONDS}s"),
-            "relay_error_message must embed the capped hint, not the raw untrusted value"
-        );
-        assert!(
-            !msg.contains(&oversized.to_string()),
-            "raw oversized hint must not appear in the message string"
-        );
-        reset_rate_limit_gate();
-    }
-
-    // ── effective_agent_relay_url: legacy pin ignored ─────────────────────────
-
-    #[test]
-    fn stored_relay_pin_is_ignored() {
-        // Zero-touch cutover (#2122): a creation-era per-record relay pin is
-        // parsed and persisted but never consulted — the workspace relay wins.
-        assert_eq!(
-            effective_agent_relay_url("wss://relay.other.com", "wss://staging.example.com"),
-            "wss://staging.example.com"
-        );
-    }
-
-    #[test]
-    fn empty_relay_resolves_to_workspace() {
-        // A never-set record resolves to the active workspace relay at read-time,
-        // so a stale stored default can never make it load-bearing.
-        assert_eq!(
-            effective_agent_relay_url("", "wss://staging.example.com"),
-            "wss://staging.example.com"
-        );
-    }
-
-    #[test]
-    fn whitespace_only_relay_resolves_to_workspace() {
-        // Whitespace-only behaves identically — no value survives.
-        assert_eq!(
-            effective_agent_relay_url("   ", "wss://staging.example.com"),
-            "wss://staging.example.com"
-        );
-    }
-
-    // ── relay_http_base_url scheme conversion ────────────────────────────────
-
-    #[test]
-    fn loopback_ws_localhost_preserves_authority() {
-        // Tenant host-binding keys off the HTTP Host/authority. The desktop must
-        // not rewrite localhost to 127.0.0.1, or local dev HTTP calls target a
-        // different unmapped community than the WebSocket URL.
-        assert_eq!(
-            relay_http_base_url("ws://localhost:3000"),
-            "http://localhost:3000"
-        );
-    }
-
-    #[test]
-    fn loopback_trailing_slash_removed_authority_preserved() {
-        assert_eq!(
-            relay_http_base_url("ws://localhost:3000/"),
-            "http://localhost:3000"
-        );
-    }
-
-    #[test]
-    fn remote_wss_host_unchanged() {
-        assert_eq!(
-            relay_http_base_url("wss://relay.example.com"),
-            "https://relay.example.com"
-        );
-    }
-
-    #[test]
-    fn loopback_ipv4_literal_unchanged() {
-        assert_eq!(
-            relay_http_base_url("ws://127.0.0.1:3000"),
-            "http://127.0.0.1:3000"
-        );
-    }
-
-    #[test]
-    fn localhost_substring_host_unchanged() {
-        assert_eq!(
-            relay_http_base_url("ws://localhost.evil.com:3000"),
-            "http://localhost.evil.com:3000"
-        );
-    }
-
-    #[test]
-    fn loopback_wss_localhost_preserves_authority() {
-        assert_eq!(
-            relay_http_base_url("wss://localhost:3000"),
-            "https://localhost:3000"
-        );
-    }
-
-    // ── classify_intercepted_response ────────────────────────────────────────
-
-    #[test]
-    fn intercepted_cloudflare_host_returns_some() {
-        let result = classify_intercepted_response("sqprod.cloudflareaccess.com", "text/html");
-        assert!(result.is_some());
-        let msg = result.unwrap();
-        assert!(
-            msg.starts_with("relay unreachable:"),
-            "should have unreachable prefix"
-        );
-        assert!(msg.contains("Cloudflare"), "should mention Cloudflare");
-    }
-
-    #[test]
-    fn intercepted_cloudflare_apex_host_returns_some() {
-        // The apex domain itself should also match.
-        let result = classify_intercepted_response("cloudflareaccess.com", "application/json");
-        assert!(result.is_some());
-        let msg = result.unwrap();
-        assert!(msg.starts_with("relay unreachable:"));
-        assert!(msg.contains("Cloudflare"));
-    }
-
-    #[test]
-    fn intercepted_non_cloudflare_html_returns_some() {
-        let result =
-            classify_intercepted_response("proxy.corporate.example", "text/html; charset=utf-8");
-        assert!(result.is_some());
-        let msg = result.unwrap();
-        assert!(msg.starts_with("relay unreachable:"));
-    }
-
-    #[test]
-    fn normal_relay_json_returns_none() {
-        let result = classify_intercepted_response("relay.myapp.example.com", "application/json");
-        assert!(result.is_none());
-    }
-
-    #[test]
-    fn content_type_case_insensitive() {
-        // Uppercase content-type must still be detected.
-        let result = classify_intercepted_response("proxy.example.com", "TEXT/HTML");
-        assert!(result.is_some());
-        assert!(result.unwrap().starts_with("relay unreachable:"));
-    }
-
-    #[test]
-    fn evil_suffix_does_not_match_cloudflare() {
-        // A host whose suffix happens to contain the Cloudflare string but is
-        // not actually a subdomain must NOT match.
-        let result = classify_intercepted_response(
-            "notcloudflareaccess.com.evil.example",
-            "application/json",
-        );
-        assert!(
-            result.is_none(),
-            "false suffix match should not trigger Cloudflare branch"
-        );
-    }
-
-    // classify_request_error requires a real reqwest::Error (not publicly
-    // constructable) — tested indirectly through integration; skipped here.
-
-    // ── parse_json_response malformed-body contract ──────────────────────────
-
-    #[test]
-    fn malformed_response_message_stays_off_unreachable_bucket() {
-        // A reached-but-malformed 2xx body is not a connectivity failure. If this
-        // message ever regains the "relay unreachable:" prefix, the frontend
-        // classifier would misroute it as unreachable — pin that it never does.
-        assert!(
-            !MALFORMED_RESPONSE_MESSAGE.starts_with("relay unreachable:"),
-            "malformed-response message must not match the unreachable prefix"
-        );
-    }
-
-    // ── parse_command_response ───────────────────────────────────────────────
-
-    #[derive(Debug, Deserialize, PartialEq)]
-    struct ChannelCreated {
-        channel_id: String,
-    }
-
-    #[test]
-    fn parse_command_response_decodes_typed_payload() {
-        let msg = r#"response:{"channel_id":"abc123"}"#;
-        let parsed: ChannelCreated = parse_command_response(msg).expect("should parse");
-        assert_eq!(
-            parsed,
-            ChannelCreated {
-                channel_id: "abc123".to_string()
-            }
-        );
-    }
-
-    #[test]
-    fn parse_command_response_accepts_raw_json_fallback() {
-        // Backward-compat: relays that emit raw JSON (no prefix) still work.
-        let msg = r#"{"channel_id":"abc"}"#;
-        let parsed: ChannelCreated = parse_command_response(msg).expect("fallback parse");
-        assert_eq!(
-            parsed,
-            ChannelCreated {
-                channel_id: "abc".to_string()
-            }
-        );
-    }
-
-    #[test]
-    fn parse_command_response_rejects_invalid_prefixed_json() {
-        let msg = "response:not-json";
-        let result: Result<ChannelCreated, _> = parse_command_response(msg);
-        assert!(result.is_err());
-        assert!(result.unwrap_err().contains("response parse failed"));
-    }
-
-    #[test]
-    fn parse_command_response_rejects_garbage() {
-        let msg = "totally not json or response";
-        let result: Result<ChannelCreated, _> = parse_command_response(msg);
-        assert!(result.is_err());
-    }
-
-    // ── build_profile_event ──────────────────────────────────────────────────
-
-    /// Generate a valid NIP-OA auth tag JSON string signed by a fresh owner key
-    /// and addressed to `agent_keys`.
-    ///
-    /// Uses `nostr_compat` (nostr 0.36) for the owner keys because
-    /// `buzz_sdk_pkg::nip_oa::compute_auth_tag` expects nostr 0.36 types.
-    /// The agent pubkey is bridged via hex encoding.
-    fn make_valid_auth_tag(agent_keys: &nostr::Keys) -> String {
-        let owner_keys = nostr::Keys::generate();
-        let agent_pubkey_hex = agent_keys.public_key().to_hex();
-        let agent_compat_pubkey =
-            nostr::PublicKey::from_hex(&agent_pubkey_hex).expect("valid hex pubkey should parse");
-        buzz_sdk_pkg::nip_oa::compute_auth_tag(&owner_keys, &agent_compat_pubkey, "")
-            .expect("compute_auth_tag should not fail with distinct keys")
-    }
-
-    #[test]
-    fn profile_event_with_valid_auth_tag() {
-        let agent_keys = nostr::Keys::generate();
-        let tag_json = make_valid_auth_tag(&agent_keys);
-        let event = build_profile_event(&agent_keys, "TestBot", None, Some(&tag_json))
-            .expect("should succeed with a valid auth tag");
-
-        // Exactly one "auth" tag must be present.
-        let auth_tags: Vec<_> = event
-            .tags
-            .iter()
-            .filter(|t| t.as_slice().first().map(|s| s.as_str()) == Some("auth"))
-            .collect();
-        assert_eq!(auth_tags.len(), 1, "expected exactly 1 auth tag");
-
-        // Must be a kind:0 (Metadata) event.
-        assert_eq!(event.kind, nostr::Kind::Metadata);
-    }
-
-    #[test]
-    fn profile_event_without_auth_tag() {
-        let agent_keys = nostr::Keys::generate();
-        let event = build_profile_event(&agent_keys, "TestBot", None, None)
-            .expect("should succeed without an auth tag");
-
-        // No "auth" tags should be present.
-        let auth_tags: Vec<_> = event
-            .tags
-            .iter()
-            .filter(|t| t.as_slice().first().map(|s| s.as_str()) == Some("auth"))
-            .collect();
-        assert_eq!(auth_tags.len(), 0, "expected no auth tags");
-
-        assert_eq!(event.kind, nostr::Kind::Metadata);
-    }
-
-    #[test]
-    fn profile_event_rejects_invalid_auth_tag() {
-        let agent_keys = nostr::Keys::generate();
-        // Structurally valid JSON array but with a bogus signature — verification must fail.
-        let bad_json = format!(r#"["auth","{}","","{}"]"#, "a".repeat(64), "b".repeat(128));
-        let result = build_profile_event(&agent_keys, "TestBot", None, Some(&bad_json));
-        assert!(result.is_err(), "should reject an invalid auth tag");
-        assert!(
-            result.unwrap_err().contains("verification failed"),
-            "error message should mention verification failure"
-        );
-    }
-}
+mod tests;
diff --git a/desktop/src-tauri/src/relay/tests.rs b/desktop/src-tauri/src/relay/tests.rs
new file mode 100644
index 0000000000..4ae3924932
--- /dev/null
+++ b/desktop/src-tauri/src/relay/tests.rs
@@ -0,0 +1,615 @@
+//! Unit tests for the relay HTTP/command bridge helpers.
+//! Extracted from `relay.rs` to keep that module under the file-size ratchet.
+
+use super::{
+    build_profile_event, classify_intercepted_response, effective_agent_relay_url,
+    extract_retry_in_hint, parse_command_response, relay_http_base_url, MALFORMED_RESPONSE_MESSAGE,
+};
+use serde::Deserialize;
+
+// ── extract_retry_in_hint ────────────────────────────────────────────────
+
+#[test]
+fn extracts_hint_from_429_body() {
+    assert_eq!(
+        extract_retry_in_hint(r#"{"error":"rate-limited: quota exceeded; retry in 4s"}"#),
+        Some(4)
+    );
+}
+
+#[test]
+fn extracts_hint_when_no_json_wrapper() {
+    assert_eq!(extract_retry_in_hint("retry in 30s"), Some(30));
+}
+
+#[test]
+fn returns_none_when_no_hint_present() {
+    assert_eq!(
+        extract_retry_in_hint(r#"{"error":"rate-limited: quota exceeded"}"#),
+        None
+    );
+    assert_eq!(extract_retry_in_hint(""), None);
+}
+
+#[test]
+fn overlong_digit_string_returns_none() {
+    // A digit sequence that exceeds u64::MAX cannot be parsed; the function
+    // must return None (→ caller uses the default) rather than panicking.
+    assert_eq!(
+        extract_retry_in_hint("retry in 99999999999999999999999s"),
+        None
+    );
+}
+
+// ── relay_error_message: hint capping ────────────────────────────────────
+//
+// Verify that an oversized relay hint is capped in the returned message
+// string, not just inside `activate_rate_limit()`. This guarantees every
+// consumer — including the TS gate via `applyTauriRateLimitIfNeeded` —
+// receives the capped value rather than the raw untrusted relay value.
+
+#[tokio::test]
+async fn oversized_hint_is_capped_in_relay_error_message_string() {
+    use crate::relay_admission::{reset_rate_limit_gate, MAX_HINT_SECONDS, TEST_SERIAL};
+    use std::io::{Read as _, Write as _};
+
+    let _serial = TEST_SERIAL.lock().await;
+    reset_rate_limit_gate();
+
+    // Use a std::net listener on a std::thread — the same pattern as the
+    // relay_admission loopback tests. This avoids two races that cause CI
+    // failures with tokio::net + into_std():
+    //  1. No request read: the client is still sending when the response
+    //     arrives → hyper `UnexpectedMessage`/`Canceled` under load.
+    //  2. into_std() leaves the socket in nonblocking mode → write_all
+    //     may return WouldBlock and silently drop the response.
+    let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
+    let addr = listener.local_addr().unwrap();
+
+    // Serve a 429 with a hint far exceeding MAX_HINT_SECONDS (300).
+    let oversized = 1_000_000u64;
+    let body = format!(r#"{{"error":"rate-limited: quota exceeded; retry in {oversized}s"}}"#);
+    let body_len = body.len();
+    std::thread::spawn(move || {
+        if let Ok((mut stream, _)) = listener.accept() {
+            // Read the request first so the client finishes sending before
+            // we write the response — mirrors relay_admission.rs pattern.
+            let mut buf = [0u8; 4096];
+            let _ = stream.read(&mut buf);
+            let response = format!(
+                "HTTP/1.1 429 Too Many Requests\r\nContent-Type: application/json\r\nContent-Length: {body_len}\r\nConnection: close\r\n\r\n{body}"
+            );
+            let _ = stream.write_all(response.as_bytes());
+            let _ = stream.flush();
+        }
+    });
+
+    let client = reqwest::Client::new();
+    let response = client
+        .get(format!("http://{addr}/"))
+        .send()
+        .await
+        .expect("request must succeed");
+
+    let msg = super::relay_error_message(response).await;
+
+    // The message must embed the CAPPED hint, not the raw 1 000 000.
+    assert_eq!(
+        msg,
+        format!("relay rate-limited: retry in {MAX_HINT_SECONDS}s"),
+        "relay_error_message must embed the capped hint, not the raw untrusted value"
+    );
+    assert!(
+        !msg.contains(&oversized.to_string()),
+        "raw oversized hint must not appear in the message string"
+    );
+    reset_rate_limit_gate();
+}
+
+// ── effective_agent_relay_url: legacy pin ignored ─────────────────────────
+
+#[test]
+fn stored_relay_pin_is_ignored() {
+    // Zero-touch cutover (#2122): a creation-era per-record relay pin is
+    // parsed and persisted but never consulted — the workspace relay wins.
+    assert_eq!(
+        effective_agent_relay_url("wss://relay.other.com", "wss://staging.example.com"),
+        "wss://staging.example.com"
+    );
+}
+
+#[test]
+fn empty_relay_resolves_to_workspace() {
+    // A never-set record resolves to the active workspace relay at read-time,
+    // so a stale stored default can never make it load-bearing.
+    assert_eq!(
+        effective_agent_relay_url("", "wss://staging.example.com"),
+        "wss://staging.example.com"
+    );
+}
+
+#[test]
+fn whitespace_only_relay_resolves_to_workspace() {
+    // Whitespace-only behaves identically — no value survives.
+    assert_eq!(
+        effective_agent_relay_url("   ", "wss://staging.example.com"),
+        "wss://staging.example.com"
+    );
+}
+
+// ── relay_http_base_url scheme conversion ────────────────────────────────
+
+#[test]
+fn loopback_ws_localhost_preserves_authority() {
+    // Tenant host-binding keys off the HTTP Host/authority. The desktop must
+    // not rewrite localhost to 127.0.0.1, or local dev HTTP calls target a
+    // different unmapped community than the WebSocket URL.
+    assert_eq!(
+        relay_http_base_url("ws://localhost:3000"),
+        "http://localhost:3000"
+    );
+}
+
+#[test]
+fn loopback_trailing_slash_removed_authority_preserved() {
+    assert_eq!(
+        relay_http_base_url("ws://localhost:3000/"),
+        "http://localhost:3000"
+    );
+}
+
+#[test]
+fn remote_wss_host_unchanged() {
+    assert_eq!(
+        relay_http_base_url("wss://relay.example.com"),
+        "https://relay.example.com"
+    );
+}
+
+#[test]
+fn loopback_ipv4_literal_unchanged() {
+    assert_eq!(
+        relay_http_base_url("ws://127.0.0.1:3000"),
+        "http://127.0.0.1:3000"
+    );
+}
+
+#[test]
+fn localhost_substring_host_unchanged() {
+    assert_eq!(
+        relay_http_base_url("ws://localhost.evil.com:3000"),
+        "http://localhost.evil.com:3000"
+    );
+}
+
+#[test]
+fn loopback_wss_localhost_preserves_authority() {
+    assert_eq!(
+        relay_http_base_url("wss://localhost:3000"),
+        "https://localhost:3000"
+    );
+}
+
+// ── classify_intercepted_response ────────────────────────────────────────
+
+#[test]
+fn intercepted_cloudflare_host_returns_some() {
+    let result = classify_intercepted_response("sqprod.cloudflareaccess.com", "text/html");
+    assert!(result.is_some());
+    let msg = result.unwrap();
+    assert!(
+        msg.starts_with("relay unreachable:"),
+        "should have unreachable prefix"
+    );
+    assert!(msg.contains("Cloudflare"), "should mention Cloudflare");
+}
+
+#[test]
+fn intercepted_cloudflare_apex_host_returns_some() {
+    // The apex domain itself should also match.
+    let result = classify_intercepted_response("cloudflareaccess.com", "application/json");
+    assert!(result.is_some());
+    let msg = result.unwrap();
+    assert!(msg.starts_with("relay unreachable:"));
+    assert!(msg.contains("Cloudflare"));
+}
+
+#[test]
+fn intercepted_non_cloudflare_html_returns_some() {
+    let result =
+        classify_intercepted_response("proxy.corporate.example", "text/html; charset=utf-8");
+    assert!(result.is_some());
+    let msg = result.unwrap();
+    assert!(msg.starts_with("relay unreachable:"));
+}
+
+#[test]
+fn normal_relay_json_returns_none() {
+    let result = classify_intercepted_response("relay.myapp.example.com", "application/json");
+    assert!(result.is_none());
+}
+
+#[test]
+fn content_type_case_insensitive() {
+    // Uppercase content-type must still be detected.
+    let result = classify_intercepted_response("proxy.example.com", "TEXT/HTML");
+    assert!(result.is_some());
+    assert!(result.unwrap().starts_with("relay unreachable:"));
+}
+
+#[test]
+fn evil_suffix_does_not_match_cloudflare() {
+    // A host whose suffix happens to contain the Cloudflare string but is
+    // not actually a subdomain must NOT match.
+    let result =
+        classify_intercepted_response("notcloudflareaccess.com.evil.example", "application/json");
+    assert!(
+        result.is_none(),
+        "false suffix match should not trigger Cloudflare branch"
+    );
+}
+
+// classify_request_error requires a real reqwest::Error (not publicly
+// constructable) — tested indirectly through integration; skipped here.
+
+// ── /query per-request timeout → classified error ────────────────────────
+//
+// A stalled `/query` connection (headers never arrive) must not hang the
+// caller forever. Both production `/query` builders funnel through
+// `send_query_request`, which owns the per-request `.timeout(...)`; this test
+// drives that exact helper against a loopback server that accepts the
+// connection but never responds. It asserts two things the frontend depends
+// on: (1) the helper returns instead of hanging, and (2) the failure is the
+// stable `"relay unreachable: request timed out"` classified string.
+//
+// The outer `tokio::time::timeout` is the regression guard: if the production
+// `.timeout(...)` is ever removed from `send_query_request`, this call would
+// hang forever, so the guard fires and the test fails fast rather than
+// stalling CI. A short 200ms deadline keeps the happy path fast.
+#[tokio::test]
+async fn stalled_query_request_times_out_with_classified_error() {
+    use std::io::Read as _;
+    use std::time::Duration;
+
+    // A listener that accepts the connection and then holds it open without
+    // ever writing a response — the "headers never arrive" stall.
+    let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
+    let addr = listener.local_addr().unwrap();
+    let handle = std::thread::spawn(move || {
+        if let Ok((mut stream, _)) = listener.accept() {
+            // Drain the request but deliberately never respond, then hold
+            // the socket until the client aborts on its own timeout.
+            let mut buf = [0u8; 4096];
+            let _ = stream.read(&mut buf);
+            std::thread::sleep(Duration::from_secs(2));
+        }
+    });
+
+    let client = reqwest::Client::new();
+    let url = format!("http://{addr}/query");
+    let result = tokio::time::timeout(
+        Duration::from_secs(5),
+        super::send_query_request(
+            &client,
+            &url,
+            "Nostr test-auth",
+            None,
+            b"[]".to_vec(),
+            Duration::from_millis(200),
+        ),
+    )
+    .await
+    .expect(
+        "send_query_request must honor its per-request timeout and resolve within 5s; \
+         if this guard fires, the production .timeout(...) was lost",
+    );
+
+    let err = result.expect_err("a stalled /query must surface an error, not succeed");
+    assert_eq!(
+        err, "relay unreachable: request timed out",
+        "a timed-out /query must surface the stable classified string"
+    );
+
+    let _ = handle.join();
+}
+
+// ── /query body-stall timeout → classified error (not malformed) ─────────
+//
+// `send()` resolves once response headers arrive, so a relay that returns a
+// valid 2xx JSON header block and then stalls the body trips the request
+// deadline inside `response.json()` — the branch the pre-header stall above
+// cannot reach. That is a connectivity failure, not a malformed body, so it
+// must surface the stable "relay unreachable: request timed out" string rather
+// than the malformed-response bucket. This drives `send_query_request` against
+// a loopback that writes headers promising a body it never sends.
+#[tokio::test]
+async fn stalled_response_body_times_out_with_classified_error() {
+    use std::io::{Read as _, Write as _};
+    use std::time::Duration;
+
+    // Accept, drain the request, write a complete 2xx JSON header block that
+    // promises a body (Content-Length), then send nothing and hold the socket
+    // — the "headers arrive, body stalls" half-open case.
+    let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
+    let addr = listener.local_addr().unwrap();
+    let handle = std::thread::spawn(move || {
+        if let Ok((mut stream, _)) = listener.accept() {
+            let mut buf = [0u8; 4096];
+            let _ = stream.read(&mut buf);
+            let _ = stream.write_all(
+                b"HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: 64\r\n\r\n",
+            );
+            let _ = stream.flush();
+            // Never write the promised body; hold past the client deadline.
+            std::thread::sleep(Duration::from_secs(2));
+        }
+    });
+
+    let client = reqwest::Client::new();
+    let url = format!("http://{addr}/query");
+    let result = tokio::time::timeout(
+        Duration::from_secs(5),
+        super::send_query_request(
+            &client,
+            &url,
+            "Nostr test-auth",
+            None,
+            b"[]".to_vec(),
+            Duration::from_millis(200),
+        ),
+    )
+    .await
+    .expect(
+        "send_query_request must honor its per-request timeout through body \
+         consumption and resolve within 5s",
+    );
+
+    let err = result.expect_err("a stalled response body must surface an error, not succeed");
+    assert_eq!(
+        err, "relay unreachable: request timed out",
+        "a body-stall timeout must surface the classified timeout string, not the \
+         malformed-response bucket"
+    );
+
+    let _ = handle.join();
+}
+
+// ── /query non-2xx body-stall timeout → classified error (not status) ────
+//
+// The 2xx path is not the only body-consuming path. A relay that returns a
+// non-success status (500, 429, …) routes through `relay_error_message`, which
+// consumes the body via `text()` to extract the structured error field. If the
+// relay sends the status headers and then stalls the promised body, that
+// consumption trips the same request deadline — and it must surface the stable
+// "relay unreachable: request timed out" classification, not a bare
+// "relay returned 500" that hides the connectivity failure. This drives
+// `send_query_request` against a loopback that writes 500 headers promising a
+// body it never sends.
+#[tokio::test]
+async fn stalled_error_response_body_times_out_with_classified_error() {
+    use std::io::{Read as _, Write as _};
+    use std::time::Duration;
+
+    let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
+    let addr = listener.local_addr().unwrap();
+    let handle = std::thread::spawn(move || {
+        if let Ok((mut stream, _)) = listener.accept() {
+            let mut buf = [0u8; 4096];
+            let _ = stream.read(&mut buf);
+            // 500 status headers promising a body (Content-Length) that never
+            // arrives — the "error headers arrive, body stalls" half-open case.
+            let _ = stream.write_all(
+                b"HTTP/1.1 500 Internal Server Error\r\nContent-Type: application/json\r\nContent-Length: 64\r\n\r\n",
+            );
+            let _ = stream.flush();
+            std::thread::sleep(Duration::from_secs(2));
+        }
+    });
+
+    let client = reqwest::Client::new();
+    let url = format!("http://{addr}/query");
+    let result = tokio::time::timeout(
+        Duration::from_secs(5),
+        super::send_query_request(
+            &client,
+            &url,
+            "Nostr test-auth",
+            None,
+            b"[]".to_vec(),
+            Duration::from_millis(200),
+        ),
+    )
+    .await
+    .expect(
+        "send_query_request must honor its per-request timeout through error-body \
+         consumption and resolve within 5s",
+    );
+
+    let err = result.expect_err("a stalled error-response body must surface an error, not succeed");
+    assert_eq!(
+        err, "relay unreachable: request timed out",
+        "a non-2xx body-stall timeout must surface the classified timeout string, not the \
+         status bucket"
+    );
+
+    let _ = handle.join();
+}
+
+// ── /query non-stalled 500 → status message (timeout preservation is scoped) ─
+//
+// The timeout preservation above must not swallow genuine relay errors: a 500
+// whose body arrives promptly still surfaces as "relay returned 500". This
+// pins that `classify_body_timeout` only fires on an actual timeout, so the
+// error-classification path stays intact for live relay failures.
+#[tokio::test]
+async fn non_stalled_error_response_yields_status_message() {
+    use std::io::{Read as _, Write as _};
+    use std::time::Duration;
+
+    let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
+    let addr = listener.local_addr().unwrap();
+    let handle = std::thread::spawn(move || {
+        if let Ok((mut stream, _)) = listener.accept() {
+            let mut buf = [0u8; 4096];
+            let _ = stream.read(&mut buf);
+            // A complete 500 with a non-JSON body delivered immediately.
+            let body = "internal error";
+            let response = format!(
+                "HTTP/1.1 500 Internal Server Error\r\nContent-Type: text/plain\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
+                body.len()
+            );
+            let _ = stream.write_all(response.as_bytes());
+            let _ = stream.flush();
+        }
+    });
+
+    let client = reqwest::Client::new();
+    let url = format!("http://{addr}/query");
+    let result = tokio::time::timeout(
+        Duration::from_secs(5),
+        super::send_query_request(
+            &client,
+            &url,
+            "Nostr test-auth",
+            None,
+            b"[]".to_vec(),
+            Duration::from_millis(200),
+        ),
+    )
+    .await
+    .expect("a promptly-served 500 must resolve well within 5s");
+
+    let err = result.expect_err("a 500 must surface an error, not succeed");
+    assert_eq!(
+        err, "relay returned 500 Internal Server Error",
+        "a non-stalled 500 must keep its status classification, not be reclassified as a timeout"
+    );
+
+    let _ = handle.join();
+}
+
+// ── parse_json_response malformed-body contract ──────────────────────────
+
+#[test]
+fn malformed_response_message_stays_off_unreachable_bucket() {
+    // A reached-but-malformed 2xx body is not a connectivity failure. If this
+    // message ever regains the "relay unreachable:" prefix, the frontend
+    // classifier would misroute it as unreachable — pin that it never does.
+    assert!(
+        !MALFORMED_RESPONSE_MESSAGE.starts_with("relay unreachable:"),
+        "malformed-response message must not match the unreachable prefix"
+    );
+}
+
+// ── parse_command_response ───────────────────────────────────────────────
+
+#[derive(Debug, Deserialize, PartialEq)]
+struct ChannelCreated {
+    channel_id: String,
+}
+
+#[test]
+fn parse_command_response_decodes_typed_payload() {
+    let msg = r#"response:{"channel_id":"abc123"}"#;
+    let parsed: ChannelCreated = parse_command_response(msg).expect("should parse");
+    assert_eq!(
+        parsed,
+        ChannelCreated {
+            channel_id: "abc123".to_string()
+        }
+    );
+}
+
+#[test]
+fn parse_command_response_accepts_raw_json_fallback() {
+    // Backward-compat: relays that emit raw JSON (no prefix) still work.
+    let msg = r#"{"channel_id":"abc"}"#;
+    let parsed: ChannelCreated = parse_command_response(msg).expect("fallback parse");
+    assert_eq!(
+        parsed,
+        ChannelCreated {
+            channel_id: "abc".to_string()
+        }
+    );
+}
+
+#[test]
+fn parse_command_response_rejects_invalid_prefixed_json() {
+    let msg = "response:not-json";
+    let result: Result<ChannelCreated, _> = parse_command_response(msg);
+    assert!(result.is_err());
+    assert!(result.unwrap_err().contains("response parse failed"));
+}
+
+#[test]
+fn parse_command_response_rejects_garbage() {
+    let msg = "totally not json or response";
+    let result: Result<ChannelCreated, _> = parse_command_response(msg);
+    assert!(result.is_err());
+}
+
+// ── build_profile_event ──────────────────────────────────────────────────
+
+/// Generate a valid NIP-OA auth tag JSON string signed by a fresh owner key
+/// and addressed to `agent_keys`.
+///
+/// Uses `nostr_compat` (nostr 0.36) for the owner keys because
+/// `buzz_sdk_pkg::nip_oa::compute_auth_tag` expects nostr 0.36 types.
+/// The agent pubkey is bridged via hex encoding.
+fn make_valid_auth_tag(agent_keys: &nostr::Keys) -> String {
+    let owner_keys = nostr::Keys::generate();
+    let agent_pubkey_hex = agent_keys.public_key().to_hex();
+    let agent_compat_pubkey =
+        nostr::PublicKey::from_hex(&agent_pubkey_hex).expect("valid hex pubkey should parse");
+    buzz_sdk_pkg::nip_oa::compute_auth_tag(&owner_keys, &agent_compat_pubkey, "")
+        .expect("compute_auth_tag should not fail with distinct keys")
+}
+
+#[test]
+fn profile_event_with_valid_auth_tag() {
+    let agent_keys = nostr::Keys::generate();
+    let tag_json = make_valid_auth_tag(&agent_keys);
+    let event = build_profile_event(&agent_keys, "TestBot", None, Some(&tag_json))
+        .expect("should succeed with a valid auth tag");
+
+    // Exactly one "auth" tag must be present.
+    let auth_tags: Vec<_> = event
+        .tags
+        .iter()
+        .filter(|t| t.as_slice().first().map(|s| s.as_str()) == Some("auth"))
+        .collect();
+    assert_eq!(auth_tags.len(), 1, "expected exactly 1 auth tag");
+
+    // Must be a kind:0 (Metadata) event.
+    assert_eq!(event.kind, nostr::Kind::Metadata);
+}
+
+#[test]
+fn profile_event_without_auth_tag() {
+    let agent_keys = nostr::Keys::generate();
+    let event = build_profile_event(&agent_keys, "TestBot", None, None)
+        .expect("should succeed without an auth tag");
+
+    // No "auth" tags should be present.
+    let auth_tags: Vec<_> = event
+        .tags
+        .iter()
+        .filter(|t| t.as_slice().first().map(|s| s.as_str()) == Some("auth"))
+        .collect();
+    assert_eq!(auth_tags.len(), 0, "expected no auth tags");
+
+    assert_eq!(event.kind, nostr::Kind::Metadata);
+}
+
+#[test]
+fn profile_event_rejects_invalid_auth_tag() {
+    let agent_keys = nostr::Keys::generate();
+    // Structurally valid JSON array but with a bogus signature — verification must fail.
+    let bad_json = format!(r#"["auth","{}","","{}"]"#, "a".repeat(64), "b".repeat(128));
+    let result = build_profile_event(&agent_keys, "TestBot", None, Some(&bad_json));
+    assert!(result.is_err(), "should reject an invalid auth tag");
+    assert!(
+        result.unwrap_err().contains("verification failed"),
+        "error message should mention verification failure"
+    );
+}
diff --git a/desktop/src/features/channels/ui/ChannelPane.tsx b/desktop/src/features/channels/ui/ChannelPane.tsx
index dbdb2ed234..4086a4e1c1 100644
--- a/desktop/src/features/channels/ui/ChannelPane.tsx
+++ b/desktop/src/features/channels/ui/ChannelPane.tsx
@@ -14,6 +14,7 @@ import { useRelaySelfQuery } from "@/features/moderation/hooks";
 import { DropZoneOverlay } from "@/features/messages/ui/ComposerAttachments";
 import { MessageThreadPanel } from "@/features/messages/ui/MessageThreadPanel";
 import { MessageThreadPanelSkeleton } from "@/features/messages/ui/MessageThreadPanelSkeleton";
+import { ThreadRepliesErrorCard } from "@/features/messages/ui/MessageThreadReplyState";
 import {
   MessageTimeline,
   type MessageTimelineHandle,
@@ -97,6 +98,8 @@ export const ChannelPane = React.memo(function ChannelPane({
   welcomeKickoffSettingUp = false,
   messages,
   threadSummaries,
+  huddleThreadRepliesError = false,
+  onRetryHuddleThreadReplies,
   firstUnreadMessageId = null,
   unreadCount = 0,
   canResetThreadPanelWidth,
@@ -153,6 +156,8 @@ export const ChannelPane = React.memo(function ChannelPane({
   threadHeadMessage,
   threadMessages,
   threadMessagesPending = false,
+  threadMessagesError = false,
+  onRetryThreadReplies,
   threadPanelWidthPx,
   threadScrollTargetId,
   threadTypingPubkeys,
@@ -624,6 +629,11 @@ export const ChannelPane = React.memo(function ChannelPane({
           }
         >
           {isHuddleTranscript ? null : header}
+          {isHuddleTranscript && huddleThreadRepliesError ? (
+            <div className="px-5 pt-3">
+              <ThreadRepliesErrorCard onRetry={onRetryHuddleThreadReplies} />
+            </div>
+          ) : null}
           <div className="relative isolate flex min-h-0 min-w-0 flex-1 flex-col">
             <MessageTimeline
               ref={messageTimelineRef}
@@ -889,6 +899,8 @@ export const ChannelPane = React.memo(function ChannelPane({
                 widthPx={threadPanelWidthPx}
                 threadReplies={threadMessages}
                 threadRepliesPending={threadMessagesPending}
+                threadRepliesError={threadMessagesError}
+                onRetryThreadReplies={onRetryThreadReplies}
                 threadUnreadCount={threadUnreadCounts?.get(
                   threadHeadMessage.id,
                 )}
diff --git a/desktop/src/features/channels/ui/ChannelPane.types.ts b/desktop/src/features/channels/ui/ChannelPane.types.ts
index 7ac3930b84..0296822168 100644
--- a/desktop/src/features/channels/ui/ChannelPane.types.ts
+++ b/desktop/src/features/channels/ui/ChannelPane.types.ts
@@ -58,6 +58,14 @@ export type ChannelPaneProps = {
   welcomeKickoffSettingUp?: boolean;
   messages: TimelineMessage[];
   threadSummaries?: ReadonlyMap<string, ChannelWindowThreadSummary>;
+  /**
+   * A Huddle transcript flattens summarized reply subtrees into the chat
+   * timeline. When one of those subtree loads fails, this reports the aggregate
+   * failure so the transcript can surface a non-destructive retry alert instead
+   * of silently presenting a partial conversation as complete.
+   */
+  huddleThreadRepliesError?: boolean;
+  onRetryHuddleThreadReplies?: () => void;
   firstUnreadMessageId?: string | null;
   unreadCount?: number;
   canResetThreadPanelWidth: boolean;
@@ -163,6 +171,8 @@ export type ChannelPaneProps = {
   threadAllMessages: TimelineMessage[];
   threadMessages: MainTimelineEntry[];
   threadMessagesPending?: boolean;
+  threadMessagesError?: boolean;
+  onRetryThreadReplies?: () => void;
   threadPanelWidthPx: number;
   threadTypingPubkeys: string[];
   threadReplyTargetMessage: TimelineMessage | null;
diff --git a/desktop/src/features/channels/ui/ChannelScreen.tsx b/desktop/src/features/channels/ui/ChannelScreen.tsx
index aac93d7f8d..240a9ad70c 100644
--- a/desktop/src/features/channels/ui/ChannelScreen.tsx
+++ b/desktop/src/features/channels/ui/ChannelScreen.tsx
@@ -254,7 +254,12 @@ export function ChannelScreen({
   const deleteMessageMutation = useDeleteMessageMutation(activeChannel);
   const editMessageMutation = useEditMessageMutation(activeChannel);
   const joinChannelMutation = useJoinChannelMutation(activeChannelId);
-  const { resolvedMessages, threadSummaries } = useHuddleChannelMessages({
+  const {
+    resolvedMessages,
+    threadSummaries,
+    threadRepliesError: huddleThreadRepliesError,
+    onRetryThreadReplies: onRetryHuddleThreadReplies,
+  } = useHuddleChannelMessages({
     activeChannel,
     isHuddleTranscript,
     messages: messagesQuery.data ?? EMPTY_RELAY_EVENTS,
@@ -896,6 +901,8 @@ export function ChannelScreen({
                   isTimelineLoading={isTimelineLoading}
                   messages={timelineMessages}
                   threadSummaries={threadSummaries}
+                  huddleThreadRepliesError={huddleThreadRepliesError}
+                  onRetryHuddleThreadReplies={onRetryHuddleThreadReplies}
                   onCancelEdit={handleCancelEdit}
                   onCancelThreadReply={handleCancelThreadReply}
                   onChannelManagementDeleted={handleChannelManagementDeleted}
@@ -967,6 +974,10 @@ export function ChannelScreen({
                   threadHeadMessage={displayedThreadHeadMessage}
                   threadMessages={displayedThreadMessages}
                   threadMessagesPending={threadRepliesQuery.isPending}
+                  threadMessagesError={threadRepliesQuery.isError}
+                  onRetryThreadReplies={() => {
+                    void threadRepliesQuery.refetch();
+                  }}
                   threadPanelWidthPx={threadPanelWidthPx}
                   threadTypingPubkeys={threadTypingPubkeys}
                   threadReplyTargetMessage={displayedThreadReplyTargetMessage}
diff --git a/desktop/src/features/channels/ui/useHuddleChannelMessages.ts b/desktop/src/features/channels/ui/useHuddleChannelMessages.ts
index 2a90971dde..5a3a7c4041 100644
--- a/desktop/src/features/channels/ui/useHuddleChannelMessages.ts
+++ b/desktop/src/features/channels/ui/useHuddleChannelMessages.ts
@@ -66,5 +66,13 @@ export function useHuddleChannelMessages({
     [huddleThreadReplies.events, isHuddleTranscript, resolvedChannelMessages],
   );
 
-  return { resolvedMessages, threadSummaries };
+  return {
+    resolvedMessages,
+    threadSummaries,
+    // A summarized reply subtree failing must not leave the transcript reading
+    // as complete: surface the aggregate failure so the consumer can show a
+    // non-destructive retry alert alongside the rows that did load.
+    threadRepliesError: isHuddleTranscript && huddleThreadReplies.isError,
+    onRetryThreadReplies: huddleThreadReplies.refetch,
+  };
 }
diff --git a/desktop/src/features/messages/combineThreadRepliesResults.test.mjs b/desktop/src/features/messages/combineThreadRepliesResults.test.mjs
new file mode 100644
index 0000000000..47beb1c7a8
--- /dev/null
+++ b/desktop/src/features/messages/combineThreadRepliesResults.test.mjs
@@ -0,0 +1,104 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { combineThreadRepliesResults } from "./useThreadReplies.ts";
+
+const CHANNEL_A = "a".repeat(64);
+const CHANNEL_B = "b".repeat(64);
+
+function event(id, createdAt) {
+  return {
+    id,
+    pubkey: "c".repeat(64),
+    kind: 9,
+    created_at: createdAt,
+    content: "reply",
+    tags: [],
+    sig: "sig",
+  };
+}
+
+function ok(data) {
+  return {
+    data,
+    isPending: false,
+    isError: false,
+    error: null,
+    refetch: () => {
+      throw new Error("a successful subtree must not be refetched");
+    },
+  };
+}
+
+function failed(refetch) {
+  return {
+    data: undefined,
+    isPending: false,
+    isError: true,
+    error: new Error("subtree load failed"),
+    refetch,
+  };
+}
+
+function pending() {
+  return {
+    data: undefined,
+    isPending: true,
+    isError: false,
+    error: null,
+    refetch: () => {},
+  };
+}
+
+test("aggregates events across roots in chronological order", () => {
+  const combined = combineThreadRepliesResults([
+    ok([event(CHANNEL_A, 200)]),
+    ok([event(CHANNEL_B, 100)]),
+  ]);
+  assert.deepEqual(
+    combined.events.map((e) => e.created_at),
+    [100, 200],
+  );
+  assert.equal(combined.isPending, false);
+  assert.equal(combined.isError, false);
+  assert.equal(combined.error, null);
+});
+
+test("a failed subtree surfaces aggregate error and never silently drops", () => {
+  // The load-bearing contract: one failed root among successful roots must make
+  // the aggregate report isError so the consumer can surface a failure instead
+  // of presenting a partial transcript as complete.
+  const combined = combineThreadRepliesResults([
+    ok([event(CHANNEL_A, 100)]),
+    failed(() => {}),
+  ]);
+  assert.equal(combined.isError, true);
+  assert.ok(combined.error instanceof Error);
+  // Successful rows still contribute their events (non-destructive).
+  assert.equal(combined.events.length, 1);
+});
+
+test("isPending reflects any still-loading root", () => {
+  const combined = combineThreadRepliesResults([ok([]), pending()]);
+  assert.equal(combined.isPending, true);
+});
+
+test("refetch re-runs only the failed subtrees, not the successful ones", () => {
+  let failedRefetched = 0;
+  const combined = combineThreadRepliesResults([
+    ok([event(CHANNEL_A, 100)]),
+    failed(() => {
+      failedRefetched += 1;
+    }),
+  ]);
+  // ok().refetch throws if called, so a partial-success refetch that touched
+  // every query would throw here; it must only touch the failed one.
+  combined.refetch();
+  assert.equal(failedRefetched, 1);
+});
+
+test("all-success aggregate reports no error", () => {
+  const combined = combineThreadRepliesResults([ok([]), ok([])]);
+  assert.equal(combined.isError, false);
+  assert.equal(combined.error, null);
+});
diff --git a/desktop/src/features/messages/lib/threadPanel.ts b/desktop/src/features/messages/lib/threadPanel.ts
index ebc1b35ae7..6dc1190910 100644
--- a/desktop/src/features/messages/lib/threadPanel.ts
+++ b/desktop/src/features/messages/lib/threadPanel.ts
@@ -542,3 +542,59 @@ export function buildThreadPanelData(
     expandedReplyIds,
   );
 }
+
+function hasLaterVisibleSibling(
+  entries: readonly MainTimelineEntry[],
+  entryIndex: number,
+): boolean {
+  const depth = entries[entryIndex]?.message.depth;
+  if (depth == null) {
+    return false;
+  }
+
+  for (let index = entryIndex + 1; index < entries.length; index += 1) {
+    const nextDepth = entries[index].message.depth;
+    if (nextDepth <= depth) {
+      return nextDepth === depth;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Depths at which a vertical thread-branch guide should continue past `message`
+ * because an ancestor on its path still has a later visible sibling. Pure so
+ * the branch-guide geometry is unit-tested without the panel.
+ */
+export function getActiveContinuationDepths({
+  ancestors,
+  entries,
+  index,
+  message,
+}: {
+  ancestors: readonly { index: number; message: TimelineMessage }[];
+  entries: readonly MainTimelineEntry[];
+  index: number;
+  message: TimelineMessage;
+}): number[] {
+  const depths: number[] = [];
+
+  for (const ancestor of ancestors) {
+    if (ancestor.message.depth === 0) {
+      continue;
+    }
+
+    const childDepth = ancestor.message.depth + 1;
+    const pathChild =
+      message.depth === childDepth
+        ? { index, message }
+        : ancestors.find((candidate) => candidate.message.depth === childDepth);
+
+    if (pathChild && hasLaterVisibleSibling(entries, pathChild.index)) {
+      depths.push(ancestor.message.depth);
+    }
+  }
+
+  return depths;
+}
diff --git a/desktop/src/features/messages/lib/threadReplyHighlight.test.mjs b/desktop/src/features/messages/lib/threadReplyHighlight.test.mjs
new file mode 100644
index 0000000000..bad72b3339
--- /dev/null
+++ b/desktop/src/features/messages/lib/threadReplyHighlight.test.mjs
@@ -0,0 +1,86 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { selectThreadRowHighlight } from "./threadReplyHighlight.ts";
+
+// The hovered branch spans rows in the half-open range (startIndex, endIndex].
+const branch = { id: "b", depth: 1, startIndex: 2, endIndex: 5 };
+
+test("row-highlight: null branch highlights nothing", () => {
+  assert.deepEqual(
+    selectThreadRowHighlight({
+      branch: null,
+      index: 3,
+      messageId: "x",
+      messageDepth: 2,
+      showGuides: true,
+    }),
+    {
+      isBranchOwner: false,
+      isInsideBranch: false,
+      isDirectChild: false,
+      lineDepths: undefined,
+    },
+  );
+});
+
+test("row-highlight: the branch owner is flagged but is not inside its own range", () => {
+  const h = selectThreadRowHighlight({
+    branch,
+    index: 2,
+    messageId: "b",
+    messageDepth: 1,
+    showGuides: true,
+  });
+  assert.equal(h.isBranchOwner, true);
+  // startIndex is excluded, so the owner row itself is not "inside".
+  assert.equal(h.isInsideBranch, false);
+  assert.equal(h.lineDepths, undefined);
+});
+
+test("row-highlight: a direct child inside the branch draws the guide line", () => {
+  const h = selectThreadRowHighlight({
+    branch,
+    index: 3,
+    messageId: "c",
+    messageDepth: 2,
+    showGuides: true,
+  });
+  assert.equal(h.isInsideBranch, true);
+  assert.equal(h.isDirectChild, true);
+  assert.deepEqual(h.lineDepths, [1]);
+});
+
+test("row-highlight: a deeper descendant is inside but not a direct child", () => {
+  const h = selectThreadRowHighlight({
+    branch,
+    index: 4,
+    messageId: "d",
+    messageDepth: 3,
+    showGuides: true,
+  });
+  assert.equal(h.isInsideBranch, true);
+  assert.equal(h.isDirectChild, false);
+});
+
+test("row-highlight: a row past endIndex is outside the branch", () => {
+  const h = selectThreadRowHighlight({
+    branch,
+    index: 6,
+    messageId: "e",
+    messageDepth: 2,
+    showGuides: true,
+  });
+  assert.equal(h.isInsideBranch, false);
+});
+
+test("row-highlight: guides suppressed → no line depths even inside the branch", () => {
+  const h = selectThreadRowHighlight({
+    branch,
+    index: 3,
+    messageId: "c",
+    messageDepth: 2,
+    showGuides: false,
+  });
+  assert.equal(h.isInsideBranch, true);
+  assert.equal(h.lineDepths, undefined);
+});
diff --git a/desktop/src/features/messages/lib/threadReplyHighlight.ts b/desktop/src/features/messages/lib/threadReplyHighlight.ts
new file mode 100644
index 0000000000..0ce446daec
--- /dev/null
+++ b/desktop/src/features/messages/lib/threadReplyHighlight.ts
@@ -0,0 +1,45 @@
+/**
+ * The hovered collapse-branch range, or null when nothing is hovered. Rows whose
+ * index falls inside `(startIndex, endIndex]` belong to the branch.
+ */
+export type HighlightedThreadBranch = {
+  id: string;
+  depth: number;
+  startIndex: number;
+  endIndex: number;
+} | null;
+
+/** Per-row branch-highlight flags derived from the hovered collapse branch. */
+export type ThreadRowHighlight = {
+  isBranchOwner: boolean;
+  isInsideBranch: boolean;
+  isDirectChild: boolean;
+  lineDepths: number[] | undefined;
+};
+
+/**
+ * Which highlight decorations a reply row shows for the hovered collapse branch.
+ * Pure so the index-range logic is unit-testable without rendering the panel.
+ */
+export function selectThreadRowHighlight({
+  branch,
+  index,
+  messageId,
+  messageDepth,
+  showGuides,
+}: {
+  branch: HighlightedThreadBranch;
+  index: number;
+  messageId: string;
+  messageDepth: number;
+  showGuides: boolean;
+}): ThreadRowHighlight {
+  const isBranchOwner = branch?.id === messageId;
+  const isInsideBranch =
+    branch != null && index > branch.startIndex && index <= branch.endIndex;
+  const isDirectChild =
+    isInsideBranch && branch != null && messageDepth === branch.depth + 1;
+  const lineDepths =
+    showGuides && isInsideBranch && branch ? [branch.depth] : undefined;
+  return { isBranchOwner, isInsideBranch, isDirectChild, lineDepths };
+}
diff --git a/desktop/src/features/messages/lib/timelineSnapshot.test.mjs b/desktop/src/features/messages/lib/timelineSnapshot.test.mjs
index a0374fbe2b..5334d58875 100644
--- a/desktop/src/features/messages/lib/timelineSnapshot.test.mjs
+++ b/desktop/src/features/messages/lib/timelineSnapshot.test.mjs
@@ -14,6 +14,7 @@ import {
   selectLatestMessageKey,
   selectTimelineBodySurface,
   selectTimelineIntroSurface,
+  selectThreadRepliesSurface,
 } from "./timelineSnapshot.ts";
 
 // Local-midnight unix-second timestamps so isSameDay (local time) is stable
@@ -399,6 +400,126 @@ test("deferred-render: keys the empty decision off the live count, not deferred"
   assert.equal(selectDeferredListRenderState(0, 1), "pending");
 });
 
+// ── selectThreadRepliesSurface ──────────────────────────────────────────────
+// PR-1 defect 2: a terminal thread-load error must NEVER be presented as the
+// authoritative "No replies in this branch yet" empty state. These pin the
+// paint precedence that gates that in MessageThreadPanel.
+
+test("thread-surface: pending query paints the skeleton", () => {
+  assert.equal(
+    selectThreadRepliesSurface({
+      isPending: true,
+      isError: false,
+      renderState: "empty",
+    }),
+    "skeleton",
+  );
+});
+
+test("thread-surface: terminal error with no data paints error, never empty", () => {
+  // The core false-empty guard: the load failed (isError) and there is nothing
+  // cached (renderState "empty"). This MUST be "error" so the UI shows
+  // "Couldn't load replies" + Retry instead of an authoritative empty thread.
+  const surface = selectThreadRepliesSurface({
+    isPending: false,
+    isError: true,
+    renderState: "empty",
+  });
+  assert.equal(surface, "error");
+  assert.notEqual(surface, "empty");
+});
+
+test("thread-surface: page-2 failure with no committed rows never claims empty", () => {
+  // A later-page fetch rejects the whole attempt; partial rows are never
+  // committed, so the deferred+live lists are empty and isError is set. The
+  // surface must be "error", never "empty" — the thread is not known-empty.
+  assert.equal(
+    selectThreadRepliesSurface({
+      isPending: false,
+      isError: true,
+      renderState: "empty",
+    }),
+    "error",
+  );
+});
+
+test("thread-surface: cached rows stay visible even under a load error", () => {
+  // An error with cached replies (renderState "list") keeps painting the rows
+  // non-destructively rather than blanking them for the error card.
+  assert.equal(
+    selectThreadRepliesSurface({
+      isPending: false,
+      isError: true,
+      renderState: "list",
+    }),
+    "list",
+  );
+});
+
+test("thread-surface: successful empty load paints the empty state", () => {
+  // No error, genuinely no replies → the real empty affordance is correct.
+  assert.equal(
+    selectThreadRepliesSurface({
+      isPending: false,
+      isError: false,
+      renderState: "empty",
+    }),
+    "empty",
+  );
+});
+
+test("thread-surface: retry success renders the reply list", () => {
+  // After a Retry re-fetch succeeds, isError clears and rows commit
+  // (renderState "list") → the list body paints, replacing the error card.
+  assert.equal(
+    selectThreadRepliesSurface({
+      isPending: false,
+      isError: false,
+      renderState: "list",
+    }),
+    "list",
+  );
+});
+
+test("thread-surface: streaming-in rows paint nothing (pending), not empty", () => {
+  assert.equal(
+    selectThreadRepliesSurface({
+      isPending: false,
+      isError: false,
+      renderState: "pending",
+    }),
+    "pending",
+  );
+});
+
+test("thread-surface: huddle transcripts collapse non-list surfaces to pending", () => {
+  // Huddle transcripts flatten replies into the chat timeline, so they never
+  // show the skeleton/error/empty affordances — only the list body or nothing.
+  for (const isError of [false, true]) {
+    for (const renderState of ["empty", "pending"]) {
+      assert.equal(
+        selectThreadRepliesSurface({
+          isPending: false,
+          isError,
+          renderState,
+          isHuddleTranscript: true,
+        }),
+        "pending",
+      );
+    }
+  }
+  // The list body still paints for a transcript with rows.
+  assert.equal(
+    selectThreadRepliesSurface({
+      isPending: false,
+      isError: false,
+      renderState: "list",
+      isHuddleTranscript: true,
+    }),
+    "list",
+  );
+});
+
 test("timeline-body-surface: loading and deferred-pending both paint the single static skeleton", () => {
   assert.equal(
     selectTimelineBodySurface({
diff --git a/desktop/src/features/messages/lib/timelineSnapshot.ts b/desktop/src/features/messages/lib/timelineSnapshot.ts
index 3bfd934947..4e23fb2245 100644
--- a/desktop/src/features/messages/lib/timelineSnapshot.ts
+++ b/desktop/src/features/messages/lib/timelineSnapshot.ts
@@ -209,6 +209,74 @@ export function selectTimelineBodySurface({
   return renderState;
 }
 
+/**
+ * Which surface the thread-reply body should paint, in strict precedence.
+ *
+ * Extracted as a pure function so the load-bearing invariant — a terminal fetch
+ * error must NEVER be shown as the "empty" (no-replies) state — is unit-tested
+ * without a DOM. The precedence mirrors the JSX branch order in
+ * `MessageThreadPanel`:
+ *
+ *   1. "skeleton" → the query is still pending (first load, no cache)
+ *   2. "list"     → the deferred snapshot has rows; paint them (even under a
+ *                   later error, cached replies stay visible non-destructively)
+ *   3. "error"    → the load terminally failed and there is nothing to show;
+ *                   paint "Couldn't load replies" + Retry, never the empty state
+ *   4. "empty"    → the load succeeded and the branch is genuinely empty
+ *   5. "pending"  → deferred is empty but the live list has content; paint
+ *                   nothing yet (rows are streaming in on the deferred commit)
+ *
+ * Huddle transcripts flatten replies into the chat timeline and never show the
+ * skeleton/error/empty affordances, so their non-list surfaces collapse to
+ * "pending" (render nothing).
+ */
+export type ThreadRepliesSurface =
+  | "skeleton"
+  | "list"
+  | "error"
+  | "empty"
+  | "pending";
+
+export function selectThreadRepliesSurface({
+  isPending,
+  isError,
+  renderState,
+  isHuddleTranscript = false,
+}: {
+  isPending: boolean;
+  isError: boolean;
+  renderState: DeferredListRenderState;
+  isHuddleTranscript?: boolean;
+}): ThreadRepliesSurface {
+  const surface = resolveThreadRepliesSurface({
+    isPending,
+    isError,
+    renderState,
+  });
+  return isHuddleTranscript && surface !== "list" ? "pending" : surface;
+}
+
+function resolveThreadRepliesSurface({
+  isPending,
+  isError,
+  renderState,
+}: {
+  isPending: boolean;
+  isError: boolean;
+  renderState: DeferredListRenderState;
+}): ThreadRepliesSurface {
+  if (isPending) {
+    return "skeleton";
+  }
+  if (renderState === "list") {
+    return "list";
+  }
+  if (isError) {
+    return "error";
+  }
+  return renderState;
+}
+
 export type TimelineMessageDelta = "prepend" | "append" | "replace" | "none";
 
 export function classifyTimelineMessageDelta({
diff --git a/desktop/src/features/messages/ui/MessageThreadPanel.tsx b/desktop/src/features/messages/ui/MessageThreadPanel.tsx
index d2650c84ac..01fbcda7ff 100644
--- a/desktop/src/features/messages/ui/MessageThreadPanel.tsx
+++ b/desktop/src/features/messages/ui/MessageThreadPanel.tsx
@@ -4,6 +4,7 @@ import { ArrowDown } from "lucide-react";
 import { HuddleTranscriptIntro } from "@/features/huddle/components/HuddleTranscriptIntro";
 import {
   buildThreadSummaryFromVisibleEntries,
+  getActiveContinuationDepths,
   hasNestedThreadBranches,
   type MainTimelineEntry,
 } from "@/features/messages/lib/threadPanel";
@@ -41,12 +42,14 @@ import {
 import type { ThreadDepthGuideAction } from "./MessageRow";
 import { MessageThreadRow } from "./MessageThreadRow";
 import { MessageThreadSummaryRow } from "./MessageThreadSummaryRow";
+import { ThreadReplyRegion } from "./MessageThreadReplyState";
 import { TypingIndicatorRow } from "./TypingIndicatorRow";
 import { UnreadDivider } from "./UnreadDivider";
 import { useComposerHeightPadding } from "./useComposerHeightPadding";
 import { useStableSendToChannel } from "./useStableSendToChannel";
 import { useAnchoredScroll } from "./useAnchoredScroll";
 import { selectDeferredListRenderState } from "@/features/messages/lib/timelineSnapshot";
+import { selectThreadRowHighlight } from "@/features/messages/lib/threadReplyHighlight";
 
 type MessageThreadPanelProps = ThreadPanelLayoutProps & {
   channel: Channel | null;
@@ -106,6 +109,10 @@ type MessageThreadPanelProps = ThreadPanelLayoutProps & {
   threadHead: TimelineMessage | null;
   threadReplies: MainTimelineEntry[];
   threadRepliesPending?: boolean;
+  /** True when the thread-reply query terminally failed (all retries exhausted). */
+  threadRepliesError?: boolean;
+  /** Retries the failed thread-reply load; wired to the query's `refetch`. */
+  onRetryThreadReplies?: () => void;
   threadUnreadCount?: number;
   threadReplyUnreadCounts?: ReadonlyMap<string, number>;
   threadTypingPubkeys: string[];
@@ -131,57 +138,6 @@ type MessageThreadPanelProps = ThreadPanelLayoutProps & {
 const EMPTY_THREAD_REPLIES: MainTimelineEntry[] = [];
 const THREAD_PANEL_SUMMARY_INDENT_OFFSET_REM = 0;
 
-function hasLaterVisibleSibling(
-  entries: readonly MainTimelineEntry[],
-  entryIndex: number,
-): boolean {
-  const depth = entries[entryIndex]?.message.depth;
-  if (depth == null) {
-    return false;
-  }
-
-  for (let index = entryIndex + 1; index < entries.length; index += 1) {
-    const nextDepth = entries[index].message.depth;
-    if (nextDepth <= depth) {
-      return nextDepth === depth;
-    }
-  }
-
-  return false;
-}
-
-function getActiveContinuationDepths({
-  ancestors,
-  entries,
-  index,
-  message,
-}: {
-  ancestors: readonly { index: number; message: TimelineMessage }[];
-  entries: readonly MainTimelineEntry[];
-  index: number;
-  message: TimelineMessage;
-}): number[] {
-  const depths: number[] = [];
-
-  for (const ancestor of ancestors) {
-    if (ancestor.message.depth === 0) {
-      continue;
-    }
-
-    const childDepth = ancestor.message.depth + 1;
-    const pathChild =
-      message.depth === childDepth
-        ? { index, message }
-        : ancestors.find((candidate) => candidate.message.depth === childDepth);
-
-    if (pathChild && hasLaterVisibleSibling(entries, pathChild.index)) {
-      depths.push(ancestor.message.depth);
-    }
-  }
-
-  return depths;
-}
-
 export function MessageThreadPanel({
   channel,
   channelId,
@@ -233,6 +189,8 @@ export function MessageThreadPanel({
   videoReviewPresentation,
   threadReplies,
   threadRepliesPending = false,
+  threadRepliesError = false,
+  onRetryThreadReplies,
   threadUnreadCount,
   threadReplyUnreadCounts,
   threadTypingPubkeys,
@@ -629,199 +587,187 @@ export function MessageThreadPanel({
           className={cn(THREAD_PANEL_MESSAGE_GUTTER_CLASS, "pb-3 pt-0")}
           data-testid="message-thread-replies"
         >
-          {threadRepliesPending && !isHuddleTranscript ? (
-            <div
-              className="space-y-2.5 pt-1"
-              data-testid="message-thread-replies-loading"
-            >
-              <ThreadMessageSkeleton />
-              <ThreadMessageSkeleton />
-            </div>
-          ) : repliesRenderState === "list" ? (
-            visibleThreadHeadSummary ? (
+          <ThreadReplyRegion
+            isPending={threadRepliesPending}
+            isError={threadRepliesError}
+            deferredCount={deferredThreadReplies.length}
+            liveCount={threadReplies.length}
+            isHuddleTranscript={isHuddleTranscript}
+            onRetry={onRetryThreadReplies}
+            renderSkeleton={() => (
               <div
-                className="space-y-0"
-                data-render-pending={isRepliesPending ? "true" : undefined}
+                className="space-y-2.5 pt-1"
+                data-testid="message-thread-replies-loading"
               >
-                <MessageThreadSummaryRow
-                  depth={threadHead.depth}
-                  message={threadHead}
-                  onOpenThread={expandThreadHeadReplies}
-                  summary={visibleThreadHeadSummary}
-                  summaryIndentOffsetRem={
-                    THREAD_PANEL_SUMMARY_INDENT_OFFSET_REM
-                  }
-                  unreadCount={threadUnreadCount}
-                />
+                <ThreadMessageSkeleton />
+                <ThreadMessageSkeleton />
               </div>
-            ) : (
-              <div
-                className="space-y-0"
-                data-render-pending={isRepliesPending ? "true" : undefined}
-              >
-                {threadReplyRenderItems.map((item) => {
-                  const {
-                    collapseDepthGuideActions,
-                    connectsToVisibleChild,
-                    continuationDepths,
-                    entry,
-                    index,
-                    isContinuation,
-                  } = item;
-                  const showUnreadDivider =
-                    index > 0 && entry.message.id === firstUnreadReplyId;
-                  const isHighlightedBranchOwner =
-                    highlightedBranch?.id === entry.message.id;
-                  const isInsideHighlightedBranch =
-                    highlightedBranch != null &&
-                    index > highlightedBranch.startIndex &&
-                    index <= highlightedBranch.endIndex;
-                  const isDirectChildOfHighlightedBranch =
-                    isInsideHighlightedBranch &&
-                    highlightedBranch != null &&
-                    index > highlightedBranch.startIndex &&
-                    index <= highlightedBranch.endIndex &&
-                    entry.message.depth === highlightedBranch.depth + 1;
-                  const highlightedLineDepths =
-                    shouldShowThreadBranchGuides &&
-                    isInsideHighlightedBranch &&
-                    highlightedBranch
-                      ? [highlightedBranch.depth]
-                      : undefined;
-                  return (
-                    <div
-                      className={cn(
-                        "flex flex-col gap-0",
-                        entry.summary &&
-                          "group/message rounded-2xl px-0 py-0.5 transition-colors hover:bg-muted/50 focus-within:bg-muted/50",
-                      )}
-                      key={entry.message.renderKey ?? entry.message.id}
-                    >
-                      {showUnreadDivider ? <UnreadDivider /> : null}
-                      <MessageThreadRow
-                        channelId={channelId}
-                        currentPubkey={currentPubkey}
-                        collapseDepthGuideActions={collapseDepthGuideActions}
-                        collapseDescendantsLabel="Collapse replies"
-                        connectDescendants={
-                          shouldShowThreadBranchGuides && connectsToVisibleChild
-                        }
-                        depthGuideDepths={
-                          shouldShowThreadBranchGuides
-                            ? continuationDepths
-                            : undefined
-                        }
-                        highlightDescendantRail={
-                          shouldShowThreadBranchGuides &&
-                          isHighlightedBranchOwner &&
-                          connectsToVisibleChild
-                        }
-                        highlightReplyConnector={
-                          shouldShowThreadBranchGuides &&
-                          isDirectChildOfHighlightedBranch
-                        }
-                        highlightThreadLineDepths={highlightedLineDepths}
-                        hoverBackground={!entry.summary}
-                        huddleMemberPubkeys={huddleMemberPubkeys}
-                        huddleMemberPubkeysPending={huddleMemberPubkeysPending}
-                        isContinuation={isContinuation}
-                        isUnread={isMessageUnreadById?.(entry.message.id)}
-                        message={entry.message}
-                        onCollapseDepthGuide={handleCollapseDepthGuide}
-                        onCollapseDepthGuideHoverChange={
-                          handleCollapseBranchHoverChange
-                        }
-                        onCollapseDescendants={
-                          shouldShowThreadBranchGuides &&
-                          connectsToVisibleChild &&
-                          !entry.summary
-                            ? onExpandReplies
-                            : undefined
-                        }
-                        onCollapseDescendantsHoverChange={
-                          handleCollapseBranchHoverChange
-                        }
-                        onDelete={
-                          onDelete &&
-                          canManageMessageForCurrentUser(
-                            entry.message,
-                            currentPubkey,
-                            profiles,
-                          )
-                            ? onDelete
-                            : undefined
-                        }
-                        onEdit={
-                          onEdit &&
-                          canManageMessageForCurrentUser(
-                            entry.message,
-                            currentPubkey,
-                            profiles,
-                          )
-                            ? onEdit
-                            : undefined
-                        }
-                        onMarkUnread={onMarkUnread}
-                        onMarkRead={onMarkRead}
-                        onReply={onSelectReplyTarget}
-                        onSendToChannel={stableSendToChannel}
-                        onToggleReaction={onToggleReaction}
-                        profiles={profiles}
-                        showDepthGuides={shouldShowThreadBranchGuides}
-                        videoReviewCommentRootId={videoReviewPresentation?.commentRootIdsByMessageId.get(
-                          entry.message.id,
+            )}
+            renderList={() =>
+              visibleThreadHeadSummary ? (
+                <div
+                  className="space-y-0"
+                  data-render-pending={isRepliesPending ? "true" : undefined}
+                >
+                  <MessageThreadSummaryRow
+                    depth={threadHead.depth}
+                    message={threadHead}
+                    onOpenThread={expandThreadHeadReplies}
+                    summary={visibleThreadHeadSummary}
+                    summaryIndentOffsetRem={
+                      THREAD_PANEL_SUMMARY_INDENT_OFFSET_REM
+                    }
+                    unreadCount={threadUnreadCount}
+                  />
+                </div>
+              ) : (
+                <div
+                  className="space-y-0"
+                  data-render-pending={isRepliesPending ? "true" : undefined}
+                >
+                  {threadReplyRenderItems.map((item) => {
+                    const {
+                      collapseDepthGuideActions,
+                      connectsToVisibleChild,
+                      continuationDepths,
+                      entry,
+                      index,
+                      isContinuation,
+                    } = item;
+                    const showUnreadDivider =
+                      index > 0 && entry.message.id === firstUnreadReplyId;
+                    const highlight = selectThreadRowHighlight({
+                      branch: highlightedBranch,
+                      index,
+                      messageId: entry.message.id,
+                      messageDepth: entry.message.depth,
+                      showGuides: shouldShowThreadBranchGuides,
+                    });
+                    return (
+                      <div
+                        className={cn(
+                          "flex flex-col gap-0",
+                          entry.summary &&
+                            "group/message rounded-2xl px-0 py-0.5 transition-colors hover:bg-muted/50 focus-within:bg-muted/50",
                         )}
-                        videoReviewContext={videoReviewPresentation?.contextsByMessageId.get(
-                          entry.message.id,
-                        )}
-                      />
-                      {entry.summary ? (
-                        <MessageThreadSummaryRow
+                        key={entry.message.renderKey ?? entry.message.id}
+                      >
+                        {showUnreadDivider ? <UnreadDivider /> : null}
+                        <MessageThreadRow
+                          channelId={channelId}
+                          currentPubkey={currentPubkey}
                           collapseDepthGuideActions={collapseDepthGuideActions}
-                          depth={entry.message.depth}
+                          collapseDescendantsLabel="Collapse replies"
+                          connectDescendants={
+                            shouldShowThreadBranchGuides &&
+                            connectsToVisibleChild
+                          }
                           depthGuideDepths={
                             shouldShowThreadBranchGuides
                               ? continuationDepths
                               : undefined
                           }
-                          highlightThreadLineDepths={highlightedLineDepths}
+                          highlightDescendantRail={
+                            shouldShowThreadBranchGuides &&
+                            highlight.isBranchOwner &&
+                            connectsToVisibleChild
+                          }
+                          highlightReplyConnector={
+                            shouldShowThreadBranchGuides &&
+                            highlight.isDirectChild
+                          }
+                          highlightThreadLineDepths={highlight.lineDepths}
+                          hoverBackground={!entry.summary}
+                          huddleMemberPubkeys={huddleMemberPubkeys}
+                          huddleMemberPubkeysPending={
+                            huddleMemberPubkeysPending
+                          }
+                          isContinuation={isContinuation}
+                          isUnread={isMessageUnreadById?.(entry.message.id)}
                           message={entry.message}
                           onCollapseDepthGuide={handleCollapseDepthGuide}
                           onCollapseDepthGuideHoverChange={
                             handleCollapseBranchHoverChange
                           }
-                          onOpenThread={onExpandReplies}
-                          summary={entry.summary}
-                          summaryIndentOffsetRem={
-                            THREAD_PANEL_SUMMARY_INDENT_OFFSET_REM
+                          onCollapseDescendants={
+                            shouldShowThreadBranchGuides &&
+                            connectsToVisibleChild &&
+                            !entry.summary
+                              ? onExpandReplies
+                              : undefined
                           }
+                          onCollapseDescendantsHoverChange={
+                            handleCollapseBranchHoverChange
+                          }
+                          onDelete={
+                            onDelete &&
+                            canManageMessageForCurrentUser(
+                              entry.message,
+                              currentPubkey,
+                              profiles,
+                            )
+                              ? onDelete
+                              : undefined
+                          }
+                          onEdit={
+                            onEdit &&
+                            canManageMessageForCurrentUser(
+                              entry.message,
+                              currentPubkey,
+                              profiles,
+                            )
+                              ? onEdit
+                              : undefined
+                          }
+                          onMarkUnread={onMarkUnread}
+                          onMarkRead={onMarkRead}
+                          onReply={onSelectReplyTarget}
+                          onSendToChannel={stableSendToChannel}
+                          onToggleReaction={onToggleReaction}
+                          profiles={profiles}
                           showDepthGuides={shouldShowThreadBranchGuides}
-                          unreadCount={threadReplyUnreadCounts?.get(
+                          videoReviewCommentRootId={videoReviewPresentation?.commentRootIdsByMessageId.get(
+                            entry.message.id,
+                          )}
+                          videoReviewContext={videoReviewPresentation?.contextsByMessageId.get(
                             entry.message.id,
                           )}
                         />
-                      ) : null}
-                    </div>
-                  );
-                })}
-              </div>
-            )
-          ) : repliesRenderState === "empty" && !isHuddleTranscript ? (
-            // Only show the empty state when the thread is GENUINELY empty.
-            // Keying off `deferredThreadReplies` would flash "No replies" for a
-            // frame while a non-empty list streams in on the deferred commit.
-            <div className="rounded-2xl border border-dashed border-border/70 bg-card/40 px-4 py-6 text-center">
-              <p className="text-sm font-medium text-foreground/80">
-                No replies in this branch yet
-              </p>
-              <p className="mt-1 text-xs text-muted-foreground">
-                Reply in the thread to continue this branch.
-              </p>
-            </div>
-          ) : // "pending": deferred list is empty but the live list has content —
-          // rows are streaming in on the deferred commit. Paint nothing rather
-          // than flashing the empty state.
-          null}
+                        {entry.summary ? (
+                          <MessageThreadSummaryRow
+                            collapseDepthGuideActions={
+                              collapseDepthGuideActions
+                            }
+                            depth={entry.message.depth}
+                            depthGuideDepths={
+                              shouldShowThreadBranchGuides
+                                ? continuationDepths
+                                : undefined
+                            }
+                            highlightThreadLineDepths={highlight.lineDepths}
+                            message={entry.message}
+                            onCollapseDepthGuide={handleCollapseDepthGuide}
+                            onCollapseDepthGuideHoverChange={
+                              handleCollapseBranchHoverChange
+                            }
+                            onOpenThread={onExpandReplies}
+                            summary={entry.summary}
+                            summaryIndentOffsetRem={
+                              THREAD_PANEL_SUMMARY_INDENT_OFFSET_REM
+                            }
+                            showDepthGuides={shouldShowThreadBranchGuides}
+                            unreadCount={threadReplyUnreadCounts?.get(
+                              entry.message.id,
+                            )}
+                          />
+                        ) : null}
+                      </div>
+                    );
+                  })}
+                </div>
+              )
+            }
+          />
         </div>
       </div>
     </AuxiliaryPanelBody>
diff --git a/desktop/src/features/messages/ui/MessageThreadReplyState.test.mjs b/desktop/src/features/messages/ui/MessageThreadReplyState.test.mjs
new file mode 100644
index 0000000000..f70143f87b
--- /dev/null
+++ b/desktop/src/features/messages/ui/MessageThreadReplyState.test.mjs
@@ -0,0 +1,162 @@
+/**
+ * Mount regressions for the thread reply region, wired through the
+ * panel-owned ThreadReplyRegion dispatcher.
+ *
+ * Bug this pins: a terminal thread-replies fetch error used to fall through to
+ * the "No replies in this branch yet" empty card, silently presenting a broken
+ * load as an authoritative empty branch with no recovery. The fix maps a
+ * terminal error to the retry card and NEVER the empty card, and routes the
+ * Retry button back to the query's refetch.
+ *
+ * Why this component, and why raw inputs: ThreadReplyRegion now owns BOTH the
+ * surface selection (selectThreadRepliesSurface, also unit-tested against its
+ * 8-case matrix in timelineSnapshot.test.mjs) AND the surface→content dispatch.
+ * MessageThreadPanel passes only its raw query/render state — the pending/error
+ * flags and the deferred vs. live reply counts — so there is no precomputed
+ * `surface` prop at the panel boundary to statically mis-set. This file mounts
+ * ThreadReplyRegion and drives the real raw-state→surface→content mapping, so a
+ * false-empty regression cannot land at either the selection or the dispatch
+ * with these tests green. Mounting the full panel is infeasible in node:test
+ * (its Tiptap composer / React Query stack is unavailable, see
+ * MessageComposerAutoSend.test.mjs); the render callbacks keep that heavy
+ * construction in the panel and out of this cheap mount.
+ *
+ * CI surface: pnpm test (node:test with @testing-library/react over JSDOM).
+ */
+
+import assert from "node:assert/strict";
+import { after, afterEach, before, test } from "node:test";
+
+import { JSDOM } from "jsdom";
+
+const dom = new JSDOM("<!doctype html><html><body></body></html>", {
+  url: "http://localhost",
+});
+
+before(() => {
+  Object.assign(globalThis, {
+    document: dom.window.document,
+    HTMLElement: dom.window.HTMLElement,
+    IS_REACT_ACT_ENVIRONMENT: true,
+    window: dom.window,
+  });
+  dom.window.matchMedia = () => ({
+    matches: false,
+    addEventListener() {},
+    removeEventListener() {},
+  });
+});
+
+afterEach(async () => {
+  const { cleanup } = await import("@testing-library/react");
+  cleanup();
+});
+
+after(() => dom.window.close());
+
+// Sentinels for the two heavy branches the panel owns. If ThreadReplyRegion
+// ever routes error/empty/pending through a render callback, these appear where
+// a card is expected and the assertions catch it.
+const SKELETON_MARK = "SKELETON_BRANCH_MARKER";
+const LIST_MARK = "LIST_BRANCH_MARKER";
+
+async function renderRegion(props) {
+  const { createElement } = await import("react");
+  const { render } = await import("@testing-library/react");
+  const { ThreadReplyRegion } = await import("./MessageThreadReplyState.tsx");
+  return render(
+    createElement(ThreadReplyRegion, {
+      isPending: false,
+      isError: false,
+      deferredCount: 0,
+      liveCount: 0,
+      renderSkeleton: () => createElement("div", null, SKELETON_MARK),
+      renderList: () => createElement("div", null, LIST_MARK),
+      ...props,
+    }),
+  );
+}
+
+test("terminal error renders the retry card, never the empty card", async () => {
+  const { screen } = await import("@testing-library/react");
+  // Raw terminal-failure state: not pending, load errored, nothing to show.
+  await renderRegion({ isError: true, onRetry: () => {} });
+
+  const card = screen.getByTestId("message-thread-replies-error");
+  assert.ok(card, "a terminal error must render the error card");
+  // The card appears asynchronously (after the query/retry lifecycle), so it
+  // must be an alert live region or a screen-reader user never hears it.
+  assert.equal(
+    card.getAttribute("role"),
+    "alert",
+    "the async error card must be an alert live region for assistive tech",
+  );
+  assert.equal(
+    document.body.textContent.includes("No replies in this branch yet"),
+    false,
+    "a terminal error must NEVER render the empty state",
+  );
+});
+
+test("Retry button invokes the supplied refetch callback", async () => {
+  const { fireEvent, screen } = await import("@testing-library/react");
+  let retryCount = 0;
+  await renderRegion({
+    isError: true,
+    onRetry: () => {
+      retryCount += 1;
+    },
+  });
+
+  fireEvent.click(screen.getByTestId("message-thread-replies-retry"));
+
+  assert.equal(retryCount, 1, "clicking Retry must call the refetch callback");
+});
+
+test("genuine empty surface renders the empty card, not the error card", async () => {
+  const { screen } = await import("@testing-library/react");
+  // Load succeeded (no error), branch is genuinely empty.
+  await renderRegion({});
+
+  assert.ok(
+    document.body.textContent.includes("No replies in this branch yet"),
+    "a genuine empty branch must render the empty card",
+  );
+  assert.equal(
+    screen.queryByTestId("message-thread-replies-error"),
+    null,
+    "a genuine empty branch must NOT render the error card",
+  );
+});
+
+test("pending surface paints nothing", async () => {
+  // Deferred snapshot is empty but the live list has content: rows are
+  // streaming in on the deferred commit, so paint nothing yet.
+  const { container } = await renderRegion({ deferredCount: 0, liveCount: 1 });
+
+  assert.equal(
+    container.textContent,
+    "",
+    "the pending surface must render nothing while rows stream in",
+  );
+});
+
+test("skeleton surface renders the panel's skeleton branch", async () => {
+  const { container } = await renderRegion({ isPending: true });
+
+  assert.equal(
+    container.textContent,
+    SKELETON_MARK,
+    "the skeleton surface must render the panel's skeleton branch",
+  );
+});
+
+test("list surface renders the panel's list branch", async () => {
+  const { container } = await renderRegion({ deferredCount: 1, liveCount: 1 });
+
+  assert.equal(
+    container.textContent,
+    LIST_MARK,
+    "the list surface must render the panel's list branch",
+  );
+});
diff --git a/desktop/src/features/messages/ui/MessageThreadReplyState.tsx b/desktop/src/features/messages/ui/MessageThreadReplyState.tsx
new file mode 100644
index 0000000000..a13d46286e
--- /dev/null
+++ b/desktop/src/features/messages/ui/MessageThreadReplyState.tsx
@@ -0,0 +1,127 @@
+import type { ReactNode } from "react";
+
+import {
+  selectDeferredListRenderState,
+  selectThreadRepliesSurface,
+} from "@/features/messages/lib/timelineSnapshot";
+import { Button } from "@/shared/ui/button";
+
+/**
+ * Terminal empty/error states for the thread reply region.
+ *
+ * These are the two non-list, non-loading outcomes of a thread-reply load. They
+ * live here (rather than inline in `MessageThreadPanel`) so the load-bearing
+ * distinction between them stays legible: a genuinely empty branch and a failed
+ * fetch look similar but must never be confused — see `selectThreadRepliesSurface`.
+ */
+
+/**
+ * A terminal load failure. This must NEVER be painted as the empty state — that
+ * silently presents a broken fetch as an authoritative "no replies" and offers
+ * no recovery. Any cached replies still render via the panel's "list" branch, so
+ * this only surfaces when the failed load left nothing to show.
+ *
+ * `role="alert"` (implicit `aria-live="assertive"`, `aria-atomic="true"`) makes
+ * the asynchronous failure audible to assistive tech: the card appears only after
+ * the query/retry lifecycle reaches a terminal error, so without a live region a
+ * screen-reader user parked in the composer never learns the load failed or that
+ * Retry became available.
+ */
+export function ThreadRepliesErrorCard({ onRetry }: { onRetry?: () => void }) {
+  return (
+    <div
+      className="rounded-2xl border border-dashed border-destructive/50 bg-destructive/5 px-4 py-6 text-center"
+      data-testid="message-thread-replies-error"
+      role="alert"
+    >
+      <p className="text-sm font-medium text-foreground/80">
+        Couldn&apos;t load replies
+      </p>
+      <p className="mt-1 text-xs text-muted-foreground">
+        The thread history didn&apos;t load. Check your connection and try
+        again.
+      </p>
+      {onRetry ? (
+        <Button
+          className="mt-3"
+          data-testid="message-thread-replies-retry"
+          onClick={onRetry}
+          size="sm"
+          type="button"
+          variant="outline"
+        >
+          Retry
+        </Button>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * A branch that genuinely has no replies (the load succeeded and returned none).
+ * Only ever painted off the committed render state, never the raw deferred list,
+ * so it can't flash while a non-empty list streams in on the deferred commit.
+ */
+export function ThreadRepliesEmptyCard() {
+  return (
+    <div className="rounded-2xl border border-dashed border-border/70 bg-card/40 px-4 py-6 text-center">
+      <p className="text-sm font-medium text-foreground/80">
+        No replies in this branch yet
+      </p>
+      <p className="mt-1 text-xs text-muted-foreground">
+        Reply in the thread to continue this branch.
+      </p>
+    </div>
+  );
+}
+
+/**
+ * The single paint decision for the thread reply region. This unit owns BOTH
+ * the surface selection (`selectThreadRepliesSurface`, keyed off the same raw
+ * query/render state the panel already holds) AND the surface→content dispatch.
+ * Fusing them here removes the last falsifiable seam: the panel passes only its
+ * raw state — pending/error flags, the deferred vs. live reply counts, and the
+ * huddle-transcript flag — so there is no precomputed `surface` prop at the
+ * panel boundary to statically mis-set (e.g. a stray `surface="empty"` that would
+ * silently restore the false-empty bug on every fetch failure). The load-bearing
+ * invariant holds by construction: a terminal fetch "error" renders the retry
+ * card and NEVER the "empty" "No replies" state, while "pending" paints nothing
+ * (rows stream in on the deferred commit).
+ *
+ * The two heavy branches take render callbacks so the panel keeps ownership of
+ * its skeleton and list construction (Tiptap/React-Query bound, not mountable in
+ * node:test) without dragging them into this component. The mount test drives
+ * the real raw-state→surface→content mapping through this exported unit, so both
+ * the selection and the dispatch are covered under a cheap mount.
+ */
+export function ThreadReplyRegion({
+  isPending,
+  isError,
+  deferredCount,
+  liveCount,
+  isHuddleTranscript = false,
+  onRetry,
+  renderSkeleton,
+  renderList,
+}: {
+  isPending: boolean;
+  isError: boolean;
+  deferredCount: number;
+  liveCount: number;
+  isHuddleTranscript?: boolean;
+  onRetry?: () => void;
+  renderSkeleton: () => ReactNode;
+  renderList: () => ReactNode;
+}) {
+  const surface = selectThreadRepliesSurface({
+    isPending,
+    isError,
+    renderState: selectDeferredListRenderState(deferredCount, liveCount),
+    isHuddleTranscript,
+  });
+  if (surface === "skeleton") return <>{renderSkeleton()}</>;
+  if (surface === "list") return <>{renderList()}</>;
+  if (surface === "error") return <ThreadRepliesErrorCard onRetry={onRetry} />;
+  if (surface === "empty") return <ThreadRepliesEmptyCard />;
+  return null;
+}
diff --git a/desktop/src/features/messages/useThreadReplies.ts b/desktop/src/features/messages/useThreadReplies.ts
index 25a6b68986..4d602348f9 100644
--- a/desktop/src/features/messages/useThreadReplies.ts
+++ b/desktop/src/features/messages/useThreadReplies.ts
@@ -67,6 +67,39 @@ export function useThreadReplies(
   });
 }
 
+/**
+ * Aggregate a set of per-root thread-reply query results into one view for a
+ * multi-root consumer. Pure over the results array so the load-bearing
+ * error-surfacing contract is unit-testable without a live QueryClient.
+ *
+ * `isError`/`error` expose aggregate terminal failure so a consumer never
+ * silently drops a failed reply subtree — the same false-empty class the
+ * single-root panel guards against. `error` carries the first failed subtree's
+ * error; `refetch` re-runs only the failed queries so a partial success is not
+ * needlessly re-fetched.
+ */
+export function combineThreadRepliesResults(
+  results: readonly {
+    data?: RelayEvent[];
+    isPending: boolean;
+    isError: boolean;
+    error: unknown;
+    refetch: () => unknown;
+  }[],
+) {
+  return {
+    events: sortMessages(results.flatMap((result) => result.data ?? [])),
+    isPending: results.some((result) => result.isPending),
+    isError: results.some((result) => result.isError),
+    error: results.find((result) => result.isError)?.error ?? null,
+    refetch: () => {
+      for (const result of results) {
+        if (result.isError) void result.refetch();
+      }
+    },
+  };
+}
+
 /**
  * Load every summarized reply subtree for a channel-style Huddle transcript.
  * Ordinary channels keep replies in their thread panels; Huddles flatten those
@@ -87,9 +120,6 @@ export function useThreadRepliesForRoots(
       staleTime: 0,
       gcTime: 60 * 60 * 1_000,
     })),
-    combine: (results) => ({
-      events: sortMessages(results.flatMap((result) => result.data ?? [])),
-      isPending: results.some((result) => result.isPending),
-    }),
+    combine: combineThreadRepliesResults,
   });
 }
diff --git a/desktop/src/features/projects/ui/ProjectConversationPanel.tsx b/desktop/src/features/projects/ui/ProjectConversationPanel.tsx
index 59f3264b02..11344ea574 100644
--- a/desktop/src/features/projects/ui/ProjectConversationPanel.tsx
+++ b/desktop/src/features/projects/ui/ProjectConversationPanel.tsx
@@ -279,7 +279,11 @@ export function ProjectConversationPanel({
         scrollTargetId={scrollTargetId}
         threadHead={panelData.threadHead}
         threadReplies={panelData.visibleReplies}
-        threadRepliesPending={false}
+        threadRepliesPending={threadRepliesQuery.isPending}
+        threadRepliesError={threadRepliesQuery.isError}
+        onRetryThreadReplies={() => {
+          void threadRepliesQuery.refetch();
+        }}
         threadTypingPubkeys={[]}
         widthPx={widthPx}
       />,
diff --git a/desktop/src/features/projects/ui/ProjectsAgentPromptPage.tsx b/desktop/src/features/projects/ui/ProjectsAgentPromptPage.tsx
index 9a465d3da0..f667fcd2a2 100644
--- a/desktop/src/features/projects/ui/ProjectsAgentPromptPage.tsx
+++ b/desktop/src/features/projects/ui/ProjectsAgentPromptPage.tsx
@@ -37,6 +37,7 @@ import {
 } from "@/features/messages/lib/useRichTextEditor";
 import { FormattingToolbar } from "@/features/messages/ui/FormattingToolbar";
 import { MessageThreadTranscript } from "@/features/messages/ui/MessageThreadTranscript";
+import { ThreadRepliesErrorCard } from "@/features/messages/ui/MessageThreadReplyState";
 import type { TimelineMessage } from "@/features/messages/types";
 import { useThreadRepliesForRoots } from "@/features/messages/useThreadReplies";
 import { useProfileQuery, useUsersBatchQuery } from "@/features/profile/hooks";
@@ -363,6 +364,9 @@ export function ConversationThread({
         profiles={profiles}
         renderAfterMessage={renderSubmittedContext}
       />
+      {threadReplies.isError ? (
+        <ThreadRepliesErrorCard onRetry={threadReplies.refetch} />
+      ) : null}
       {agentWorking.working ? (
         <div className="flex items-center gap-2 pl-11 text-sm text-muted-foreground">
           <Loader2 className="h-3.5 w-3.5 animate-spin" />
diff --git a/desktop/tests/e2e/huddle-thread-load-failure.spec.ts b/desktop/tests/e2e/huddle-thread-load-failure.spec.ts
new file mode 100644
index 0000000000..8d3777201a
--- /dev/null
+++ b/desktop/tests/e2e/huddle-thread-load-failure.spec.ts
@@ -0,0 +1,182 @@
+import { expect, test, type Page } from "@playwright/test";
+
+import { installMockBridge, TEST_IDENTITIES } from "../helpers/bridge";
+
+/**
+ * Consumer-level guard for the false-empty thread-load bug on the Huddle
+ * transcript (PR #6447, Carl r3). The transcript flattens summarized reply
+ * subtrees into the chat timeline via `useThreadRepliesForRoots`, whose combine
+ * now reports an aggregate `isError`/`refetch`. `useHuddleChannelMessages` used
+ * to read only `.events` and drop that state, so one failed subtree left the
+ * partial transcript presenting as complete with no warning or recovery.
+ *
+ * The combine unit test proves the hook REPORTS failure; it cannot catch a
+ * consumer discarding it. This drives the REAL Huddle wiring
+ * (useHuddleChannelMessages -> ChannelScreen -> ChannelPane) through the mock
+ * bridge: two summarized roots, fail only ONE subtree's fetch at the IPC
+ * boundary, assert the surviving root's reply still renders AND the retry alert
+ * appears, then Retry recovers the failed subtree. Dropping the propagation
+ * turns this red.
+ */
+
+const HUDDLE_CHANNEL_ID = "11111111-1111-4111-8111-111111111111";
+const HUDDLE_PARENT_ID = "9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50";
+
+const ROOT_A_CONTENT = "Huddle root A";
+const REPLY_A_CONTENT = "Huddle reply A survives";
+const ROOT_B_CONTENT = "Huddle root B";
+const REPLY_B_CONTENT = "Huddle reply B recovered";
+
+async function waitForMockLiveSubscription(page: Page, channelName: string) {
+  await expect
+    .poll(() =>
+      page.evaluate(
+        (name) =>
+          window.__BUZZ_E2E_HAS_MOCK_LIVE_SUBSCRIPTION__?.({
+            channelName: name,
+          }) ?? false,
+        channelName,
+      ),
+    )
+    .toBe(true);
+}
+
+// Fail get_thread_replies for exactly one root while the flag names it, letting
+// the other subtree and the eventual retry succeed. Wrapping the real
+// __TAURI_INTERNALS__.invoke exercises the whole per-root query path with no
+// source seam to bypass — the aggregate error and the failed-only refetch are
+// production behavior, not a test stub.
+async function installPerRootThreadFailureSwitch(page: Page) {
+  await page.evaluate(() => {
+    const w = window as typeof window & {
+      __FAIL_THREAD_ROOT__?: string | null;
+      __TAURI_INTERNALS__: {
+        invoke: (
+          command: string,
+          payload: unknown,
+          options: unknown,
+        ) => Promise<unknown>;
+      };
+    };
+    w.__FAIL_THREAD_ROOT__ = null;
+    const original = w.__TAURI_INTERNALS__.invoke.bind(w.__TAURI_INTERNALS__);
+    w.__TAURI_INTERNALS__.invoke = async (command, payload, options) => {
+      if (
+        command === "get_thread_replies" &&
+        w.__FAIL_THREAD_ROOT__ != null &&
+        (payload as { rootEventId?: string })?.rootEventId ===
+          w.__FAIL_THREAD_ROOT__
+      ) {
+        throw new Error("relay unreachable: request timed out");
+      }
+      return original(command, payload, options);
+    };
+  });
+}
+
+async function setFailingThreadRoot(page: Page, rootId: string | null) {
+  await page.evaluate((rootId) => {
+    (
+      window as typeof window & { __FAIL_THREAD_ROOT__?: string | null }
+    ).__FAIL_THREAD_ROOT__ = rootId;
+  }, rootId);
+}
+
+test.describe("huddle thread load failure", () => {
+  test("a failed reply subtree shows the retry alert beside surviving rows; Retry recovers", async ({
+    page,
+  }) => {
+    await installMockBridge(page, {
+      windowLabel: `huddle-${HUDDLE_CHANNEL_ID}`,
+      huddle: {
+        parentChannelId: HUDDLE_PARENT_ID,
+        ephemeralChannelId: HUDDLE_CHANNEL_ID,
+        members: [
+          { pubkey: TEST_IDENTITIES.tyler.pubkey, role: "member" },
+          { pubkey: TEST_IDENTITIES.alice.pubkey, role: "bot" },
+        ],
+        transcriptionEnabled: true,
+      },
+    });
+    await page.goto("/");
+
+    await expect(page.getByTestId("huddle-transcript-intro")).toBeVisible();
+    await installPerRootThreadFailureSwitch(page);
+    await waitForMockLiveSubscription(page, "huddle");
+
+    // Seed two summarized roots. Each threaded reply emits a live thread
+    // summary (descendant_count > 0), so both roots enter the transcript's
+    // useThreadRepliesForRoots fan-out and each gets its own subtree fetch. Fail
+    // root B's fetch BEFORE seeding so its first fan-out fetch reaches the
+    // terminal error while root A resolves — the aggregate reports failure with
+    // A's reply already merged, exactly the partial-transcript case.
+    const rootB = "b".repeat(64);
+    await setFailingThreadRoot(page, rootB);
+    const seeded = await page.evaluate(
+      ({
+        agentPubkey,
+        rootAContent,
+        replyAContent,
+        rootBContent,
+        replyBContent,
+        rootBId,
+      }) => {
+        const emit = window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__;
+        if (!emit) throw new Error("Mock message emitter is not installed.");
+        const rootA = emit({ channelName: "huddle", content: rootAContent });
+        emit({
+          channelName: "huddle",
+          content: replyAContent,
+          parentEventId: rootA.id,
+          pubkey: agentPubkey,
+        });
+        emit({ channelName: "huddle", content: rootBContent, id: rootBId });
+        emit({
+          channelName: "huddle",
+          content: replyBContent,
+          parentEventId: rootBId,
+          pubkey: agentPubkey,
+        });
+        return { rootA: rootA.id };
+      },
+      {
+        agentPubkey: TEST_IDENTITIES.alice.pubkey,
+        rootAContent: ROOT_A_CONTENT,
+        replyAContent: REPLY_A_CONTENT,
+        rootBContent: ROOT_B_CONTENT,
+        replyBContent: REPLY_B_CONTENT,
+        rootBId: rootB,
+      },
+    );
+    expect(seeded.rootA).toBeTruthy();
+
+    // The load-bearing assertion: root A's reply still renders (non-destructive
+    // — a failed subtree does not blank the surviving rows) AND root B's failed
+    // fan-out surfaces the retry alert. That alert is rendered ONLY by the
+    // Huddle transcript's `huddleThreadRepliesError` propagation; without it the
+    // partial transcript would present as complete. (Reply rows themselves flow
+    // through the live channel window, so their presence is not the signal — the
+    // alert is.)
+    await expect(
+      page.getByTestId("message-row").filter({ hasText: REPLY_A_CONTENT }),
+    ).toBeVisible({ timeout: 15_000 });
+    await expect(
+      page.getByTestId("message-thread-replies-error"),
+    ).toContainText("Couldn't load replies", { timeout: 15_000 });
+
+    // Retry with fetches succeeding: the failed-only refetch recovers root B's
+    // subtree, the aggregate error clears, and the alert is dismissed while both
+    // replies stay visible.
+    await setFailingThreadRoot(page, null);
+    await page.getByTestId("message-thread-replies-retry").click();
+    await expect(page.getByTestId("message-thread-replies-error")).toHaveCount(
+      0,
+    );
+    await expect(
+      page.getByTestId("message-row").filter({ hasText: REPLY_B_CONTENT }),
+    ).toBeVisible();
+    await expect(
+      page.getByTestId("message-row").filter({ hasText: REPLY_A_CONTENT }),
+    ).toBeVisible();
+  });
+});
diff --git a/desktop/tests/e2e/project-conversation-load-failure.spec.ts b/desktop/tests/e2e/project-conversation-load-failure.spec.ts
new file mode 100644
index 0000000000..d76bb709ec
--- /dev/null
+++ b/desktop/tests/e2e/project-conversation-load-failure.spec.ts
@@ -0,0 +1,192 @@
+import { expect, test, type Page } from "@playwright/test";
+
+import { installMockBridge, TEST_IDENTITIES } from "../helpers/bridge";
+
+/**
+ * End-to-end guard for the false-empty thread-load bug on the SECOND producer
+ * of the shared thread panel: the Projects "channel conversation" panel
+ * (`ProjectConversationPanel`). PR #6447 wired the query failure state through
+ * `ChannelScreen`, but the Projects surface calls the same `useThreadReplies`
+ * and used to hard-code `threadRepliesPending={false}` with no error/retry — so
+ * a terminal `/query` failure there painted "No replies in this branch yet"
+ * with no recovery, the exact defect the PR fixed one surface over.
+ *
+ * This drives the REAL Projects panel wiring through the mock bridge: open the
+ * project's Channels tab, open a conversation, fail every `get_thread_replies`
+ * fetch at the IPC boundary, and assert the error/Retry card renders (never the
+ * false-empty). Any regression at the Projects call site (e.g. dropping
+ * `threadRepliesError` again, or a static `isError={false}`) ships a visible
+ * false-empty and turns this case red.
+ */
+
+const DEFAULT_MOCK_PUBKEY = "deadbeef".repeat(8);
+const ROOT_CONTENT = `Projects conversation root ${DEFAULT_MOCK_PUBKEY} buzz`;
+const REPLY_CONTENT = "Projects conversation reply body";
+
+// The projects surface is a preview feature — opt in before the app mounts.
+async function enableProjectsFeature(page: Page) {
+  await page.addInitScript(() => {
+    window.localStorage.setItem(
+      "buzz-feature-overrides-v1",
+      JSON.stringify({ projects: true }),
+    );
+  });
+}
+
+// Fail every get_thread_replies fetch at the IPC boundary while the flag is on,
+// then let the real mock handler answer once it is cleared. Wrapping
+// __TAURI_INTERNALS__.invoke exercises the whole Projects thread-load path —
+// the panel's useThreadReplies query, its retry, and the shared region — with
+// no source seam to bypass.
+async function installThreadFailureSwitch(page: Page) {
+  await page.evaluate(() => {
+    const w = window as typeof window & {
+      __FAIL_THREAD_REPLIES__?: boolean;
+      __TAURI_INTERNALS__: {
+        invoke: (
+          command: string,
+          payload: unknown,
+          options: unknown,
+        ) => Promise<unknown>;
+      };
+    };
+    w.__FAIL_THREAD_REPLIES__ = false;
+    const original = w.__TAURI_INTERNALS__.invoke.bind(w.__TAURI_INTERNALS__);
+    w.__TAURI_INTERNALS__.invoke = async (command, payload, options) => {
+      if (command === "get_thread_replies" && w.__FAIL_THREAD_REPLIES__) {
+        throw new Error("relay unreachable: request timed out");
+      }
+      return original(command, payload, options);
+    };
+  });
+}
+
+async function setThreadRepliesFailing(page: Page, failing: boolean) {
+  await page.evaluate((failing) => {
+    (
+      window as typeof window & { __FAIL_THREAD_REPLIES__?: boolean }
+    ).__FAIL_THREAD_REPLIES__ = failing;
+  }, failing);
+}
+
+test.describe("project conversation load failure", () => {
+  test("terminal fetch failure shows error card, never false-empty; Retry recovers", async ({
+    page,
+  }) => {
+    await enableProjectsFeature(page);
+    await installMockBridge(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+
+    // Seed the conversation BEFORE opening general — i.e. before its live
+    // subscription exists — so the reply lands in the mock store (searchable,
+    // and returnable by a successful get_thread_replies) but is never live
+    // pushed into the thread-replies cache. If general were open first, the
+    // live handler would seed that cache and the panel would render the list
+    // branch, masking the error card. The root carries the repository discovery
+    // token so it surfaces as the channel's latest discussion hit (what the
+    // Channels-tab row opens); its reply omits the token so it never competes
+    // to be the opened hit.
+    //
+    // Wait for the emitter first: emitting before the app boots is a silent
+    // no-op (the helper is undefined), which would leave the store empty.
+    await expect
+      .poll(() =>
+        page.evaluate(
+          () =>
+            typeof (
+              window as typeof window & {
+                __BUZZ_E2E_EMIT_MOCK_MESSAGE__?: unknown;
+              }
+            ).__BUZZ_E2E_EMIT_MOCK_MESSAGE__ === "function",
+        ),
+      )
+      .toBe(true);
+    const rootId = await page.evaluate(
+      ({ author, rootContent, replyContent }) => {
+        const now = Math.floor(Date.now() / 1000);
+        const emit = (
+          window as typeof window & {
+            __BUZZ_E2E_EMIT_MOCK_MESSAGE__: (input: {
+              channelName: string;
+              content: string;
+              parentEventId?: string;
+              pubkey?: string;
+              createdAt?: number;
+            }) => { id: string };
+          }
+        ).__BUZZ_E2E_EMIT_MOCK_MESSAGE__;
+        const root = emit({
+          channelName: "general",
+          content: rootContent,
+          pubkey: author,
+          createdAt: now,
+        });
+        emit({
+          channelName: "general",
+          content: replyContent,
+          parentEventId: root.id,
+          pubkey: author,
+          createdAt: now + 1,
+        });
+        return root.id;
+      },
+      {
+        author: TEST_IDENTITIES.alice.pubkey,
+        rootContent: ROOT_CONTENT,
+        replyContent: REPLY_CONTENT,
+      },
+    );
+    expect(rootId).toBeTruthy();
+
+    // Navigate to the project's Channels tab and open the general conversation.
+    await page.getByTestId("open-projects-view").click();
+    await page.getByTestId("projects-section-projects").click();
+    const projectEntry = page
+      .locator(
+        '[data-testid="project-card-buzz"], [data-testid="project-row-buzz"]',
+      )
+      .first();
+    await expect(projectEntry).toBeVisible({ timeout: 10_000 });
+    await projectEntry.click();
+    await page.getByRole("tab", { name: "Channels", exact: true }).click();
+    const channelRow = page
+      .getByTestId("project-channel-row")
+      .filter({ hasText: "#general" })
+      .first();
+    await expect(channelRow).toBeVisible({ timeout: 10_000 });
+
+    // Fail every thread-replies fetch, THEN open the conversation: the panel's
+    // query and its retry both fail, driving the terminal error state with an
+    // empty reply cache and nothing to fall back to.
+    await installThreadFailureSwitch(page);
+    await setThreadRepliesFailing(page, true);
+    await channelRow.click();
+
+    const panel = page.getByTestId("project-conversation-panel");
+    await expect(panel).toBeVisible();
+
+    // The load-bearing assertion: a terminal failure paints the error/Retry
+    // card and NEVER the false-empty "No replies in this branch yet" state.
+    await expect(
+      page.getByTestId("message-thread-replies-error"),
+    ).toContainText("Couldn't load replies", { timeout: 15_000 });
+    await expect(page.getByTestId("message-thread-replies-retry")).toHaveText(
+      "Retry",
+    );
+    await expect(page.getByText("No replies in this branch yet")).toHaveCount(
+      0,
+    );
+
+    // Retry with fetches succeeding: the reply loads and renders — the error
+    // card is gone and no false-empty appears.
+    await setThreadRepliesFailing(page, false);
+    await page.getByTestId("message-thread-replies-retry").click();
+    await expect(page.getByTestId("message-thread-replies-error")).toHaveCount(
+      0,
+    );
+    await expect(page.getByText(REPLY_CONTENT)).toBeVisible();
+    await expect(page.getByText("No replies in this branch yet")).toHaveCount(
+      0,
+    );
+  });
+});
diff --git a/desktop/tests/e2e/thread-load-failure.spec.ts b/desktop/tests/e2e/thread-load-failure.spec.ts
new file mode 100644
index 0000000000..291600e736
--- /dev/null
+++ b/desktop/tests/e2e/thread-load-failure.spec.ts
@@ -0,0 +1,161 @@
+import { expect, test, type Page } from "@playwright/test";
+
+import { TEST_IDENTITIES, installMockBridge } from "../helpers/bridge";
+
+/**
+ * End-to-end guard for the false-empty thread-load bug (PR #6447). A terminal
+ * thread-replies fetch failure must paint the error/Retry card and NEVER the
+ * "No replies in this branch yet" empty card — the two look similar but a failed
+ * load presented as an authoritative empty is the user-visible defect.
+ *
+ * Unit tests cover `ThreadReplyRegion` in isolation, but they cannot mount the
+ * full panel (Tiptap/React-Query), so they never observe the production
+ * panel→region handoff. This spec drives the REAL panel wiring through the mock
+ * bridge, so any regression at that seam (e.g. a static `isError={false}` at the
+ * call site) ships a visible false-empty and turns this case red.
+ */
+
+// Fail every get_thread_replies fetch at the IPC boundary while the flag is on,
+// then let the real mock handler answer once it is cleared. Wrapping
+// __TAURI_INTERNALS__.invoke (installed by the mock bridge) exercises the whole
+// thread-load path — query hook, retry, panel, region — exactly as production
+// does, with no source seam to bypass. A boolean gate (rather than a failure
+// countdown) is deterministic: stray thread-reply prefetches during channel
+// open can't drain it, so the panel's own load reliably reaches the terminal
+// error state, and clearing the flag makes the Retry fetch reliably succeed.
+async function installThreadFailureSwitch(page: Page) {
+  await page.evaluate(() => {
+    const w = window as typeof window & {
+      __FAIL_THREAD_REPLIES__?: boolean;
+      __TAURI_INTERNALS__: {
+        invoke: (
+          command: string,
+          payload: unknown,
+          options: unknown,
+        ) => Promise<unknown>;
+      };
+    };
+    w.__FAIL_THREAD_REPLIES__ = false;
+    const original = w.__TAURI_INTERNALS__.invoke.bind(w.__TAURI_INTERNALS__);
+    w.__TAURI_INTERNALS__.invoke = async (command, payload, options) => {
+      if (command === "get_thread_replies" && w.__FAIL_THREAD_REPLIES__) {
+        throw new Error("relay unreachable: request timed out");
+      }
+      return original(command, payload, options);
+    };
+  });
+}
+
+async function setThreadRepliesFailing(page: Page, failing: boolean) {
+  await page.evaluate((failing) => {
+    (
+      window as typeof window & { __FAIL_THREAD_REPLIES__?: boolean }
+    ).__FAIL_THREAD_REPLIES__ = failing;
+  }, failing);
+}
+
+// Open the welcome thread deterministically: prefer its summary row, but fall
+// back to hovering the root message and clicking Reply. The summary row depends
+// on the channel-window query having materialized the seeded reply, which can
+// lag; the root Reply affordance opens the same thread panel without that race,
+// so the panel is reliably open before the error-card assertions run.
+async function openWelcomeThread(page: Page) {
+  const summary = page.locator(
+    '[data-testid="message-thread-summary"][data-thread-head-id="mock-general-welcome"]',
+  );
+  if (await summary.count()) {
+    await summary.first().click();
+  } else {
+    const root = page.locator(
+      '[data-testid="message-row"][data-message-id="mock-general-welcome"]',
+    );
+    await root.hover();
+    await root.getByRole("button", { name: "Reply" }).click();
+  }
+  await expect(page.getByTestId("message-thread-panel")).toBeVisible();
+}
+
+test.describe("thread load failure", () => {
+  test("terminal fetch failure shows error card, never false-empty; Retry recovers", async ({
+    page,
+  }) => {
+    await installMockBridge(page);
+    await page.goto("/");
+
+    // Seed a reply into the mock store BEFORE opening general, i.e. before its
+    // live subscription exists. The reply lands in the channel window (so the
+    // "1 reply" thread summary renders) but is never live-pushed into the
+    // thread-replies cache — so the thread opens with an empty reply cache and
+    // the failed get_thread_replies has nothing to fall back to. If it were
+    // emitted while general was open, the live handler would seed the thread
+    // cache and the panel would render the list branch, masking the error card.
+    //
+    // Wait for the emitter to be installed first: emitting before the app has
+    // booted is a silent no-op (the helper is undefined), which would leave the
+    // store empty and the recovery assertion with nothing to render.
+    await expect
+      .poll(() =>
+        page.evaluate(
+          () =>
+            typeof (
+              window as typeof window & {
+                __BUZZ_E2E_EMIT_MOCK_MESSAGE__?: unknown;
+              }
+            ).__BUZZ_E2E_EMIT_MOCK_MESSAGE__ === "function",
+        ),
+      )
+      .toBe(true);
+    await page.evaluate((pubkey) => {
+      (
+        window as typeof window & {
+          __BUZZ_E2E_EMIT_MOCK_MESSAGE__?: (input: {
+            channelName: string;
+            content: string;
+            parentEventId?: string;
+            pubkey?: string;
+            createdAt?: number;
+          }) => unknown;
+        }
+      ).__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+        channelName: "general",
+        content: "First reply to welcome",
+        parentEventId: "mock-general-welcome",
+        pubkey,
+        createdAt: Math.floor(Date.now() / 1000) - 10,
+      });
+    }, TEST_IDENTITIES.alice.pubkey);
+
+    await page.getByTestId("channel-general").click();
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    await installThreadFailureSwitch(page);
+
+    // Fail every thread-replies fetch, then open the thread: the panel query and
+    // its retry both fail, driving the terminal error state.
+    await setThreadRepliesFailing(page, true);
+    await openWelcomeThread(page);
+
+    // The load-bearing assertion: a terminal failure paints the error/Retry
+    // card and NEVER the false-empty "No replies in this branch yet" state.
+    await expect(
+      page.getByTestId("message-thread-replies-error"),
+    ).toContainText("Couldn't load replies", { timeout: 15_000 });
+    await expect(page.getByTestId("message-thread-replies-retry")).toHaveText(
+      "Retry",
+    );
+    await expect(page.getByText("No replies in this branch yet")).toHaveCount(
+      0,
+    );
+
+    // Retry with fetches succeeding again: the reply loads and renders — the
+    // error card is gone and no false-empty appears.
+    await setThreadRepliesFailing(page, false);
+    await page.getByTestId("message-thread-replies-retry").click();
+    await expect(page.getByTestId("message-thread-replies-error")).toHaveCount(
+      0,
+    );
+    await expect(page.getByText("First reply to welcome")).toBeVisible();
+    await expect(page.getByText("No replies in this branch yet")).toHaveCount(
+      0,
+    );
+  });
+});

From f79d346a178408661fcad85122364ac2ad7e9cb2 Mon Sep 17 00:00:00 2001
From: Taylor Ho <taylorkmho@gmail.com>
Date: Mon, 24 Aug 2026 14:55:05 -0700
Subject: [PATCH 2/9] fix(composer): wrap Buzz chip labels without orphaning
 icons (#6581)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

**Category:** fix
**User Impact:** Long Buzz link chips now wrap without overflowing in
composers and sent messages; icon-bearing stubs use at most five
graphemes when no earlier separator exists, so some sent chips attach
the icon to a shorter prefix than before. Labels over 48 graphemes are
visibly truncated in the composer while their full identity remains
available to assistive technology and in the tooltip.

**Problem:** Long repository, issue, pull request, and channel chip
labels could orphan their icon or overflow narrow composers and sent
messages. **Solution:** Keep the icon with a bounded, grapheme-safe
leading fragment while allowing the remaining text to break anywhere;
cap visible labels at 48 graphemes without changing the full tooltip or
accessible identity.

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

**desktop/src/features/messages/lib/composerMessageLinkNode.ts**
Splits composer chip content into an icon-bearing leading fragment and a
freely wrapping remainder while preserving the semantic label and link
metadata.

**desktop/src/features/messages/lib/composerMessageLinkNode.test.mjs**
Updates renderer assertions for the fragment structure and verifies
every supported Buzz link kind retains the intended visible label.

**desktop/src/shared/styles/globals/composer.css**
Keeps ordinary composer mention decorations inline while relying on the
existing shared markdown chip wrapping rules for Buzz links.

**desktop/src/shared/ui/mentionChip.ts**
Centralizes grapheme-aware leading-fragment boundaries and label
truncation so composer and sent chips share the same visible identity.

**desktop/src/shared/ui/markdown/BuzzLinkChip.tsx**
Uses the shared grapheme-aware boundary when rendering sent-message chip
fragments.

**desktop/tests/e2e/navigation.spec.ts**
Covers increasing wrap depth across constrained widths, icon attachment,
the sent-message wrap, accessible labeling, and tooltip positioning over
both edge fragments.

</details>

## Reproduction steps

1. Open a desktop channel and paste a Buzz link with a long repository
or channel name into the composer.
2. Narrow the composer until the chip spans two or more lines.
3. Confirm the label breaks mid-string while the icon remains attached
to the first label fragment.
4. Send the message, hover both the first and last rendered fragments,
and confirm the tooltip follows the hovered fragment.

## Screenshots

**Before — the icon drops onto a separate line from its chip label**

![Composer chip with an orphaned icon before the
fix](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/6581/00-before-inline-chip-icon-wrap.png)

**After — the icon stays attached while the remaining label wraps**

The same long repository chip at three composer widths. Its label gains
line breaks as space contracts, while the icon remains attached to the
leading fragment.

**420px — one line**

![Long repository chip on one line at
420px](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/6581/01-wide-420px.png)

**210px — two lines**

![Long repository chip on two lines at
210px](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/6581/02-medium-210px.png)

**150px — three lines**

![Long repository chip on three lines at
150px](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/6581/03-narrow-150px.png)

---------

Signed-off-by: Taylor Ho <taylorkmho@gmail.com>
Co-authored-by: Carl <acda9e433d19dcd0e6b6840f7f4b98f3a56f1fab98049d444c087019e6d36560@buzz.block.builderlab.xyz>
---
 .../lib/composerMessageLinkNode.test.mjs      |  57 ++++-
 .../messages/lib/composerMessageLinkNode.ts   |  45 +++-
 .../src/shared/styles/globals/composer.css    |  10 +-
 .../src/shared/styles/globals/markdown.css    |   5 +
 desktop/src/shared/ui/markdown.test.mjs       |   6 +-
 .../src/shared/ui/markdown/BuzzLinkChip.tsx   |  22 +-
 .../useInlineTooltipPosition.test.mjs         | 147 +++++++++++++
 .../ui/markdown/useInlineTooltipPosition.ts   |  49 ++++-
 desktop/src/shared/ui/mentionChip.ts          |  41 +++-
 desktop/tests/e2e/navigation.spec.ts          | 200 +++++++++++++++++-
 10 files changed, 545 insertions(+), 37 deletions(-)
 create mode 100644 desktop/src/shared/ui/markdown/useInlineTooltipPosition.test.mjs

diff --git a/desktop/src/features/messages/lib/composerMessageLinkNode.test.mjs b/desktop/src/features/messages/lib/composerMessageLinkNode.test.mjs
index 3695275762..57212aeafe 100644
--- a/desktop/src/features/messages/lib/composerMessageLinkNode.test.mjs
+++ b/desktop/src/features/messages/lib/composerMessageLinkNode.test.mjs
@@ -19,6 +19,7 @@ const CHANNEL_MESSAGE_ID = "a".repeat(64);
 const CHANNEL_MESSAGE_HREF = `buzz://channel/${CHANNEL_ID}/${CHANNEL_MESSAGE_ID}`;
 const OWNER = "a".repeat(64);
 const REPO_HREF = `buzz://repo?owner=${OWNER}&d=buzz-world`;
+const PROJECT_HREF = `buzz://project?owner=${OWNER}&d=buzz-world`;
 const ISSUE_ID = "b".repeat(64);
 const ISSUE_HREF = `buzz://issue?id=${ISSUE_ID}&owner=${OWNER}&d=buzz-world`;
 const PR_ID = "c".repeat(64);
@@ -188,6 +189,10 @@ test("markdown parsing stops message links before emphasis delimiters", () => {
   assert.deepEqual(token.meta, { channelName: "general", href: HREF });
 });
 
+function renderedChipLabel(rendered) {
+  return `${rendered[2][2]}${rendered[3]}`;
+}
+
 test("composer node uses the sent-message chip presentation", () => {
   const node = {
     attrs: { channelName: "general", href: HREF },
@@ -209,7 +214,44 @@ test("composer node uses the sent-message chip presentation", () => {
   assert.equal(rendered[1]["data-buzz-link"], "");
   // Channel label only — no event hash, so the chip does not change width when
   // the draft is sent and the rendered chip resolves its metadata.
-  assert.equal(rendered[2], "general");
+  assert.match(rendered[1].class, /wrapping-inline-chip/);
+  assert.match(rendered[2][1].class, /inline-chip-leading-fragment/);
+  assert.equal(renderedChipLabel(rendered), "general");
+});
+
+test("composer node truncates and preserves grapheme-safe leading fragments", () => {
+  const render = ComposerMessageLinkNode.configure({
+    resolveChannelName: () => undefined,
+  }).config.renderHTML;
+  assert.ok(render);
+
+  const longName = `relay-${"observability".repeat(5)}`;
+  const longRendered = render.call(
+    { options: { resolveChannelName: () => undefined } },
+    {
+      node: { attrs: { channelName: longName, href: HREF } },
+      HTMLAttributes: {},
+    },
+  );
+  assert.equal(renderedChipLabel(longRendered), `${longName.slice(0, 47)}…`);
+
+  for (const [label, expectedLeading] of [
+    ["🇺🇸channel", "🇺🇸chan"],
+    ["e\u0301quipe", "e\u0301quip"],
+    ["relaytoolsobservabilityconsole-main", "relay"],
+    [" leading-space", ""],
+  ]) {
+    const rendered = render.call(
+      { options: { resolveChannelName: () => undefined } },
+      {
+        node: { attrs: { channelName: label, href: HREF } },
+        HTMLAttributes: {},
+      },
+    );
+    assert.equal(rendered[2][2], expectedLeading);
+    assert.match(rendered[2][1].class, /inline-chip-with-icon/);
+    assert.equal(renderedChipLabel(rendered), label);
+  }
 });
 
 test("composer node renders channel and entity chip presentations", () => {
@@ -227,24 +269,29 @@ test("composer node renders channel and entity chip presentations", () => {
   const channel = render(CHANNEL_HREF);
   assert.equal(channel[1]["data-channel-deep-link"], "");
   assert.match(channel[1].class, /inline-chip-icon-channel/);
-  assert.equal(channel[2], "general");
+  assert.equal(renderedChipLabel(channel), "general");
 
   const repo = render(REPO_HREF);
   assert.equal(repo[1]["data-buzz-link-kind"], "repo");
   assert.match(repo[1].class, /inline-chip-icon-repo/);
-  assert.equal(repo[2], "buzz-world");
+  assert.equal(renderedChipLabel(repo), "buzz-world");
+
+  const project = render(PROJECT_HREF);
+  assert.equal(project[1]["data-buzz-link-kind"], "project");
+  assert.match(project[1].class, /inline-chip-icon-project/);
+  assert.equal(renderedChipLabel(project), "buzz-world");
 
   const issue = render(ISSUE_HREF);
   assert.equal(issue[1]["data-buzz-link-kind"], "issue");
   assert.match(issue[1].class, /inline-chip-icon-issue/);
   // Repository name only — the rendered chip never widens into the issue
   // title, so the composer must not widen into the event hash either.
-  assert.equal(issue[2], "buzz-world");
+  assert.equal(renderedChipLabel(issue), "buzz-world");
 
   const pullRequest = render(PR_HREF);
   assert.equal(pullRequest[1]["data-buzz-link-kind"], "pr");
   assert.match(pullRequest[1].class, /inline-chip-icon-pr/);
-  assert.equal(pullRequest[2], "buzz-world");
+  assert.equal(renderedChipLabel(pullRequest), "buzz-world");
 });
 
 test("markdown rendering stores identity in attributes, not visible id text", () => {
diff --git a/desktop/src/features/messages/lib/composerMessageLinkNode.ts b/desktop/src/features/messages/lib/composerMessageLinkNode.ts
index 9587c312ca..59b15c78ba 100644
--- a/desktop/src/features/messages/lib/composerMessageLinkNode.ts
+++ b/desktop/src/features/messages/lib/composerMessageLinkNode.ts
@@ -12,8 +12,11 @@ import {
 } from "@/shared/lib/entityLink";
 import {
   inlineChipIconClasses,
+  inlineChipLeadingEnd,
   type InlineChipIconKind,
   MENTION_CHIP_BASE_CLASSES,
+  truncateInlineChipLabel,
+  WRAPPING_INLINE_CHIP_CLASSES,
 } from "@/shared/ui/mentionChip";
 import { buildChannelLink, parseChannelLink } from "./channelLink";
 import { getMessageLinkLabel } from "./messageLinkLabel";
@@ -285,6 +288,38 @@ function composerLinkPresentation(
   };
 }
 
+function wrappingComposerChipContent(
+  label: string,
+  icon: InlineChipIconKind,
+): { leading: [string, Record<string, string>, string]; remainder: string } {
+  const leadingEnd = inlineChipLeadingEnd(label);
+  if (!leadingEnd) {
+    return {
+      leading: [
+        "span",
+        {
+          "aria-hidden": "true",
+          class: `inline-chip-leading-fragment ${inlineChipIconClasses(icon)}`,
+        },
+        "",
+      ],
+      remainder: label,
+    };
+  }
+
+  return {
+    leading: [
+      "span",
+      {
+        "aria-hidden": "true",
+        class: `inline-chip-leading-fragment ${inlineChipIconClasses(icon)}`,
+      },
+      label.slice(0, leadingEnd),
+    ],
+    remainder: label.slice(leadingEnd),
+  };
+}
+
 export const ComposerMessageLinkNode =
   Node.create<ComposerMessageLinkNodeOptions>({
     name: COMPOSER_MESSAGE_LINK_NODE_NAME,
@@ -328,11 +363,16 @@ export const ComposerMessageLinkNode =
         String(node.attrs.channelName ?? ""),
         this.options.resolveChannelName,
       );
+      const visibleLabel = truncateInlineChipLabel(presentation.label);
+      const content = wrappingComposerChipContent(
+        visibleLabel,
+        presentation.icon,
+      );
       return [
         "span",
         mergeAttributes(HTMLAttributes, {
           "aria-label": presentation.ariaLabel,
-          class: `${MENTION_CHIP_BASE_CLASSES} ${inlineChipIconClasses(presentation.icon)} cursor-text`,
+          class: `${MENTION_CHIP_BASE_CLASSES} ${WRAPPING_INLINE_CHIP_CLASSES} ${inlineChipIconClasses(presentation.icon)} cursor-text`,
           "data-buzz-link": "",
           "data-channel-name": presentation.channelName,
           "data-composer-buzz-link": "",
@@ -340,7 +380,8 @@ export const ComposerMessageLinkNode =
           ...presentation.dataAttributes,
           title: presentation.ariaLabel,
         }),
-        presentation.label,
+        content.leading,
+        content.remainder,
       ];
     },
 
diff --git a/desktop/src/shared/styles/globals/composer.css b/desktop/src/shared/styles/globals/composer.css
index fbbcdf026c..781ac8a196 100644
--- a/desktop/src/shared/styles/globals/composer.css
+++ b/desktop/src/shared/styles/globals/composer.css
@@ -256,11 +256,11 @@
    Body copy is text-sm; inline code labels sit one step down (text-xs).
    All chip variants share one box height so mono labels stay balanced.
 
-   Rendered-message chips use inline-flex. The same decoration in the
-   composer pulls the caret into the chip and swallows the trailing
-   space after an @mention, so typing "hello" after @quinn becomes
-   "@quinnhello". Keep composer chips inline; leave ::before icons in
-   place. */
+   Plain-text mention decorations stay inline because inline-flex pulls the
+   caret into their decorated range and swallows the trailing space after an
+   @mention. Composer Buzz links are atom nodes, but their labels may still
+   fragment between characters; only the icon and leading label fragment stay
+   together. */
 .rich-text-composer .tiptap .mention-chip {
   display: inline;
   min-height: 0;
diff --git a/desktop/src/shared/styles/globals/markdown.css b/desktop/src/shared/styles/globals/markdown.css
index e443357ae8..9d0c382ac3 100644
--- a/desktop/src/shared/styles/globals/markdown.css
+++ b/desktop/src/shared/styles/globals/markdown.css
@@ -211,6 +211,11 @@
   white-space: nowrap;
 }
 
+.message-markdown
+  .inline-chip-leading-fragment.inline-chip-with-icon:empty::after {
+  content: "\200b";
+}
+
 .message-markdown .inline-chip-leading-fragment.inline-chip-with-icon::before {
   display: block;
   left: 0;
diff --git a/desktop/src/shared/ui/markdown.test.mjs b/desktop/src/shared/ui/markdown.test.mjs
index 8136ff9f08..6cd15c69b4 100644
--- a/desktop/src/shared/ui/markdown.test.mjs
+++ b/desktop/src/shared/ui/markdown.test.mjs
@@ -1121,7 +1121,7 @@ test("bare Buzz permalinks render cohesive icon-prefixed chips", () => {
   assert.equal((html.match(/data-channel-deep-link=""/g) ?? []).length, 1);
   assert.match(html, /inline-chip-icon-channel/);
   assert.match(html, /wrapping-inline-chip/);
-  assert.match(html, /inline-chip-leading-fragment[^>]*>e</);
+  assert.match(html, /inline-chip-leading-fragment[^>]*>engin</);
   assert.match(html, /inline-chip-icon-pr/);
   assert.match(html, /inline-chip-icon-issue/);
   assert.match(html, /inline-chip-icon-repo/);
@@ -1299,7 +1299,7 @@ test("bare Buzz permalinks shorten unavailable channel identifiers", () => {
   );
 
   assert.equal(
-    (html.match(/inline-chip-leading-fragment[^>]*>5<\/span>80ca78b/g) ?? [])
+    (html.match(/inline-chip-leading-fragment[^>]*>580ca<\/span>78b/g) ?? [])
       .length,
     2,
   );
@@ -1332,7 +1332,7 @@ test("channel references replace the authored hash with the channel icon", () =>
 
   assert.match(html, /inline-chip-icon-channel/);
   assert.match(html, /wrapping-inline-chip/);
-  assert.match(html, /inline-chip-leading-fragment[^>]*>e</);
+  assert.match(html, /inline-chip-leading-fragment[^>]*>engin</);
   assert.match(html.replace(/<[^>]+>/g, ""), /engineering/);
   assert.doesNotMatch(html, />#engineering</);
 });
diff --git a/desktop/src/shared/ui/markdown/BuzzLinkChip.tsx b/desktop/src/shared/ui/markdown/BuzzLinkChip.tsx
index c31aa9b519..7a9ac2e659 100644
--- a/desktop/src/shared/ui/markdown/BuzzLinkChip.tsx
+++ b/desktop/src/shared/ui/markdown/BuzzLinkChip.tsx
@@ -5,6 +5,7 @@ import { cn } from "@/shared/lib/cn";
 import { InlineChip } from "@/shared/ui/InlineChip";
 import {
   inlineChipIconClasses,
+  inlineChipLeadingEnd,
   type InlineChipIconKind,
   truncateInlineChipLabel,
   WRAPPING_INLINE_CHIP_CLASSES,
@@ -72,12 +73,21 @@ function wrappingChipContent(
 ): React.ReactNode {
   if (typeof children !== "string" || children.length === 0) return children;
 
-  const separatorIndex = children.search(/[-\s]/u);
-  const leadingEnd =
-    separatorIndex < 0
-      ? Array.from(children)[0]?.length
-      : separatorIndex + (children[separatorIndex] === "-" ? 1 : 0);
-  if (!leadingEnd) return children;
+  const leadingEnd = inlineChipLeadingEnd(children);
+  if (!leadingEnd) {
+    return (
+      <>
+        <span
+          aria-hidden="true"
+          className={cn(
+            "inline-chip-leading-fragment",
+            inlineChipIconClasses(icon),
+          )}
+        />
+        {children}
+      </>
+    );
+  }
 
   return (
     <>
diff --git a/desktop/src/shared/ui/markdown/useInlineTooltipPosition.test.mjs b/desktop/src/shared/ui/markdown/useInlineTooltipPosition.test.mjs
new file mode 100644
index 0000000000..c152986249
--- /dev/null
+++ b/desktop/src/shared/ui/markdown/useInlineTooltipPosition.test.mjs
@@ -0,0 +1,147 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { JSDOM } from "jsdom";
+
+async function withHookHarness(run) {
+  const dom = new JSDOM("<!doctype html><html><body></body></html>");
+  const originals = {
+    window: globalThis.window,
+    document: globalThis.document,
+    navigator: Object.getOwnPropertyDescriptor(globalThis, "navigator"),
+    MutationObserver: globalThis.MutationObserver,
+    requestAnimationFrame: globalThis.requestAnimationFrame,
+    cancelAnimationFrame: globalThis.cancelAnimationFrame,
+    act: globalThis.IS_REACT_ACT_ENVIRONMENT,
+  };
+  const frames = [];
+  const requestAnimationFrame = (callback) => {
+    frames.push(callback);
+    return frames.length;
+  };
+  const cancelAnimationFrame = (id) => {
+    frames[id - 1] = null;
+  };
+  Object.defineProperty(dom.window, "innerWidth", {
+    configurable: true,
+    value: 1000,
+  });
+  dom.window.requestAnimationFrame = requestAnimationFrame;
+  dom.window.cancelAnimationFrame = cancelAnimationFrame;
+  globalThis.window = dom.window;
+  globalThis.document = dom.window.document;
+  globalThis.MutationObserver = dom.window.MutationObserver;
+  globalThis.requestAnimationFrame = requestAnimationFrame;
+  globalThis.cancelAnimationFrame = cancelAnimationFrame;
+  Object.defineProperty(globalThis, "navigator", {
+    configurable: true,
+    value: dom.window.navigator,
+  });
+  globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+  try {
+    const React = (await import("react")).default;
+    const { act } = await import("react");
+    const { createRoot } = await import("react-dom/client");
+    const { useInlineTooltipPosition } = await import(
+      "./useInlineTooltipPosition.ts"
+    );
+    let controls;
+    function Probe() {
+      controls = useInlineTooltipPosition();
+      return null;
+    }
+    const root = createRoot(
+      dom.window.document.body.appendChild(
+        dom.window.document.createElement("div"),
+      ),
+    );
+    await act(async () => root.render(React.createElement(Probe)));
+    const flushFrames = async () => {
+      const pending = frames.splice(0, frames.length).filter(Boolean);
+      await act(async () => {
+        for (const callback of pending) callback();
+      });
+    };
+    const flushMutations = async () => {
+      await act(async () => Promise.resolve());
+    };
+
+    await run({ act, controls, dom, flushFrames, flushMutations });
+    await act(async () => root.unmount());
+  } finally {
+    globalThis.window = originals.window;
+    globalThis.document = originals.document;
+    globalThis.MutationObserver = originals.MutationObserver;
+    globalThis.requestAnimationFrame = originals.requestAnimationFrame;
+    globalThis.cancelAnimationFrame = originals.cancelAnimationFrame;
+    if (originals.navigator) {
+      Object.defineProperty(globalThis, "navigator", originals.navigator);
+    } else {
+      delete globalThis.navigator;
+    }
+    globalThis.IS_REACT_ACT_ENVIRONMENT = originals.act;
+  }
+}
+
+function translateX(styleValue) {
+  return (
+    Number.parseFloat(styleValue.match(/translate(?:3d)?\(([-\d.]+)px/)?.[1]) ||
+    0
+  );
+}
+
+test("follows Radix wrapper placement without mutating the wrapper", async () => {
+  await withHookHarness(
+    async ({ controls, dom, flushFrames, flushMutations }) => {
+      const wrapper = dom.window.document.createElement("div");
+      const content = dom.window.document.createElement("div");
+      wrapper.append(content);
+      dom.window.document.body.append(wrapper);
+      wrapper.style.transform = "translate(400px, 20px)";
+      content.getBoundingClientRect = () => {
+        const left =
+          translateX(wrapper.style.transform) +
+          (Number.parseFloat(wrapper.style.marginLeft) || 0) +
+          (Number.parseFloat(content.style.translate) || 0);
+        return {
+          bottom: 50,
+          height: 30,
+          left,
+          right: left + 100,
+          top: 20,
+          width: 100,
+          x: left,
+          y: 20,
+          toJSON() {},
+        };
+      };
+      const target = dom.window.document.createElement("span");
+      target.getClientRects = () => [
+        { bottom: 20, height: 20, left: 360, right: 430, top: 0, width: 70 },
+        { bottom: 40, height: 20, left: 450, right: 600, top: 20, width: 150 },
+      ];
+
+      controls.contentRef(content);
+      controls.onPointerMove({
+        clientX: 395,
+        clientY: 10,
+        currentTarget: target,
+      });
+      await flushFrames();
+      assert.equal(wrapper.style.marginLeft, "");
+      assert.equal(content.getBoundingClientRect().left, 345);
+
+      // Radix may place the popper wrapper after the pointer lifecycle. The
+      // hook must follow that external placement while leaving its style owned
+      // by Radix; mutating the wrapper is what made this ordering stale.
+      wrapper.style.transform = "translate(480px, 20px)";
+      await flushMutations();
+      await flushFrames();
+
+      assert.equal(wrapper.style.marginLeft, "");
+      assert.equal(content.getBoundingClientRect().left, 345);
+      assert.equal(content.getBoundingClientRect().right, 445);
+    },
+  );
+});
diff --git a/desktop/src/shared/ui/markdown/useInlineTooltipPosition.ts b/desktop/src/shared/ui/markdown/useInlineTooltipPosition.ts
index afa0f23d9c..2404710593 100644
--- a/desktop/src/shared/ui/markdown/useInlineTooltipPosition.ts
+++ b/desktop/src/shared/ui/markdown/useInlineTooltipPosition.ts
@@ -13,6 +13,7 @@ export function useInlineTooltipPosition() {
   const contentRef = React.useRef<HTMLDivElement | null>(null);
   const fragmentCenterXRef = React.useRef<number | null>(null);
   const placementObserverRef = React.useRef<MutationObserver | null>(null);
+  const placementFrameRef = React.useRef<number | null>(null);
   const placedRef = React.useRef(false);
 
   const positionContent = React.useCallback(() => {
@@ -32,14 +33,18 @@ export function useInlineTooltipPosition() {
     );
     const correction = desiredLeft - rect.left;
     if (Math.abs(correction) < 0.5) return;
-    const currentOffset = Number.parseFloat(wrapper.style.marginLeft) || 0;
-    wrapper.style.marginLeft = `${currentOffset + correction}px`;
+    const currentOffset = Number.parseFloat(content.style.translate) || 0;
+    content.style.translate = `${currentOffset + correction}px`;
   }, []);
 
   const setContentRef = React.useCallback(
     (content: HTMLDivElement | null) => {
       placementObserverRef.current?.disconnect();
       placementObserverRef.current = null;
+      if (placementFrameRef.current !== null) {
+        cancelAnimationFrame(placementFrameRef.current);
+        placementFrameRef.current = null;
+      }
       contentRef.current = content;
       placedRef.current = false;
       const wrapper = content?.parentElement;
@@ -48,27 +53,43 @@ export function useInlineTooltipPosition() {
       let transform = wrapper.style.transform;
       const handlePlacement = () => {
         const nextTransform = wrapper.style.transform;
-        if (nextTransform === transform) return;
-        transform = nextTransform;
+        if (nextTransform !== transform) transform = nextTransform;
         placedRef.current = true;
         positionContent();
+        if (placementFrameRef.current !== null) {
+          cancelAnimationFrame(placementFrameRef.current);
+        }
+        placementFrameRef.current = requestAnimationFrame(() => {
+          placementFrameRef.current = null;
+          positionContent();
+        });
       };
-      const observer = new MutationObserver(handlePlacement);
+      const observer = new MutationObserver(() => {
+        if (wrapper.style.transform !== transform) handlePlacement();
+      });
       observer.observe(wrapper, {
         attributeFilter: ["style"],
         attributes: true,
       });
       placementObserverRef.current = observer;
-      requestAnimationFrame(() => {
+      placementFrameRef.current = requestAnimationFrame(() => {
+        placementFrameRef.current = null;
         if (contentRef.current !== content) return;
-        placedRef.current = true;
-        positionContent();
+        handlePlacement();
       });
     },
     [positionContent],
   );
 
-  React.useEffect(() => () => placementObserverRef.current?.disconnect(), []);
+  React.useEffect(
+    () => () => {
+      placementObserverRef.current?.disconnect();
+      if (placementFrameRef.current !== null) {
+        cancelAnimationFrame(placementFrameRef.current);
+      }
+    },
+    [],
+  );
 
   const onPointerMove = React.useCallback(
     (event: React.PointerEvent<HTMLElement>) => {
@@ -77,7 +98,7 @@ export function useInlineTooltipPosition() {
       );
       if (rects.length <= 1) {
         fragmentCenterXRef.current = null;
-        contentRef.current?.parentElement?.style.removeProperty("margin-left");
+        contentRef.current?.style.removeProperty("translate");
         return;
       }
       const fragment = rects.reduce<DOMRect | null>((nearest, rect) => {
@@ -90,6 +111,14 @@ export function useInlineTooltipPosition() {
       if (!fragment) return;
       fragmentCenterXRef.current = fragment.left + fragment.width / 2;
       positionContent();
+      if (placementFrameRef.current !== null) {
+        cancelAnimationFrame(placementFrameRef.current);
+      }
+      placementFrameRef.current = requestAnimationFrame(() => {
+        placementFrameRef.current = null;
+        placedRef.current = true;
+        positionContent();
+      });
     },
     [positionContent],
   );
diff --git a/desktop/src/shared/ui/mentionChip.ts b/desktop/src/shared/ui/mentionChip.ts
index 5c92272858..cda291a9a6 100644
--- a/desktop/src/shared/ui/mentionChip.ts
+++ b/desktop/src/shared/ui/mentionChip.ts
@@ -3,14 +3,45 @@ export const MENTION_CHIP_BASE_CLASSES = "mention-chip";
 export const MENTION_CHIP_HOVER_CLASSES = "mention-chip-hover";
 
 const INLINE_CHIP_LABEL_MAX_CHARACTERS = 48;
+const INLINE_CHIP_LEADING_MAX_GRAPHEMES = 5;
+
+const inlineChipGraphemeSegmenter =
+  typeof Intl.Segmenter === "function"
+    ? new Intl.Segmenter(undefined, { granularity: "grapheme" })
+    : null;
+
+function inlineChipGraphemes(label: string): string[] {
+  return inlineChipGraphemeSegmenter
+    ? Array.from(
+        inlineChipGraphemeSegmenter.segment(label),
+        ({ segment }) => segment,
+      )
+    : Array.from(label);
+}
 
 /** Caps a fragmentable chip label without changing its underlying metadata. */
 export function truncateInlineChipLabel(label: string): string {
-  const characters = Array.from(label);
-  if (characters.length <= INLINE_CHIP_LABEL_MAX_CHARACTERS) return label;
-  return `${characters
-    .slice(0, INLINE_CHIP_LABEL_MAX_CHARACTERS - 1)
-    .join("")}…`;
+  const graphemes = inlineChipGraphemes(label);
+  if (graphemes.length <= INLINE_CHIP_LABEL_MAX_CHARACTERS) return label;
+  return `${graphemes.slice(0, INLINE_CHIP_LABEL_MAX_CHARACTERS - 1).join("")}…`;
+}
+
+/** Returns a bounded boundary after the icon-bearing prefix. */
+export function inlineChipLeadingEnd(label: string): number {
+  const graphemes = inlineChipGraphemes(label);
+  if (graphemes.length === 0) return 0;
+
+  let offset = 0;
+  for (const grapheme of graphemes.slice(
+    0,
+    INLINE_CHIP_LEADING_MAX_GRAPHEMES,
+  )) {
+    const nextOffset = offset + grapheme.length;
+    if (/\s/u.test(grapheme)) return offset;
+    offset = nextOffset;
+    if (grapheme === "-") return offset;
+  }
+  return offset;
 }
 
 /** Allows a long chip to fragment into separately decorated line boxes. */
diff --git a/desktop/tests/e2e/navigation.spec.ts b/desktop/tests/e2e/navigation.spec.ts
index 189db09e0f..d19849ea17 100644
--- a/desktop/tests/e2e/navigation.spec.ts
+++ b/desktop/tests/e2e/navigation.spec.ts
@@ -445,6 +445,204 @@ test("mixed Buzz permalinks render as chips in the composer", async ({
   await expect(composerInput).not.toContainText("buzz://");
 });
 
+test("composer Buzz chip labels wrap without orphaning their icons", async ({
+  page,
+}) => {
+  await page.addInitScript(() => {
+    window.__BUZZ_E2E_EXTRA_PROJECT_EVENTS__ = [
+      {
+        id: "mock-project-relaytoolsobservabilityconsole-main",
+        kind: 30617,
+        pubkey:
+          "953d3363262e86b770419834c53d2446409db6d918a57f8f339d495d54ab001f",
+        created_at: Math.floor(Date.now() / 1000) - 60,
+        content:
+          "Operator tooling and observability console for relay deployments.",
+        tags: [
+          ["d", "relaytoolsobservabilityconsole-main"],
+          ["name", "relaytoolsobservabilityconsole-main"],
+          [
+            "description",
+            "Operator tooling and observability console for relay deployments.",
+          ],
+          ["clone", "https://github.com/block/relay-tools.git"],
+        ],
+      },
+    ];
+  });
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+
+  const composerInput = page.getByTestId("message-input");
+  const repoLink =
+    "buzz://repo?owner=953d3363262e86b770419834c53d2446409db6d918a57f8f339d495d54ab001f&d=relaytoolsobservabilityconsole-main";
+  await composerInput.evaluate((element, text) => {
+    const clipboardData = new DataTransfer();
+    clipboardData.setData("text/plain", text);
+    element.dispatchEvent(
+      new ClipboardEvent("paste", {
+        bubbles: true,
+        cancelable: true,
+        clipboardData,
+      }),
+    );
+  }, repoLink);
+
+  const chip = composerInput.locator('[data-composer-buzz-link=""]');
+  const leadingFragment = chip.locator(".inline-chip-leading-fragment");
+  await expect(chip).toHaveText("relaytoolsobservabilityconsole-main");
+  const emptyLeadingFragmentHeight = await composerInput.evaluate((element) => {
+    const probe = document.createElement("span");
+    probe.className = "mention-chip wrapping-inline-chip";
+    const leading = document.createElement("span");
+    leading.className =
+      "inline-chip-leading-fragment inline-chip-with-icon inline-chip-icon-repo";
+    const remainder = document.createElement("span");
+    remainder.textContent = " leading-space";
+    probe.append(leading, remainder);
+    element.append(probe);
+    const height = leading.getBoundingClientRect().height;
+    probe.remove();
+    return height;
+  });
+  expect(emptyLeadingFragmentHeight).toBeGreaterThan(0);
+  const chipHeightAtWidth = async (width: number) => {
+    await composerInput.evaluate((element, nextWidth) => {
+      element.style.width = `${nextWidth}px`;
+    }, width);
+    return chip.evaluate((element) => {
+      const range = document.createRange();
+      range.selectNodeContents(element);
+      const rects = Array.from(range.getClientRects()).filter(
+        (rect) => rect.width > 0 && rect.height > 0,
+      );
+      return (
+        Math.max(...rects.map((rect) => rect.bottom)) -
+        Math.min(...rects.map((rect) => rect.top))
+      );
+    });
+  };
+  const wideHeight = await chipHeightAtWidth(420);
+  const mediumHeight = await chipHeightAtWidth(210);
+  const narrowHeight = await chipHeightAtWidth(90);
+  expect(mediumHeight).toBeGreaterThan(wideHeight);
+  expect(narrowHeight).toBeGreaterThan(mediumHeight);
+  await expect(chip).toHaveCSS("display", "inline");
+  await expect(chip).toHaveCSS("overflow-wrap", "anywhere");
+  await expect(leadingFragment).toHaveText("relay");
+  await expect
+    .poll(() =>
+      chip.evaluate((element) => {
+        const chipRange = document.createRange();
+        chipRange.selectNodeContents(element);
+        const leading = element.querySelector(".inline-chip-leading-fragment");
+        const composerBounds = element
+          .closest('[data-testid="message-input"]')
+          ?.getBoundingClientRect();
+        const leadingBounds = leading?.getBoundingClientRect();
+        return {
+          chipWraps:
+            new Set(
+              Array.from(chipRange.getClientRects(), (rect) =>
+                Math.round(rect.y),
+              ),
+            ).size >= 2,
+          leadingContained:
+            Boolean(composerBounds && leadingBounds) &&
+            leadingBounds.right <= composerBounds.right,
+          leadingLineBoxes: leading?.getClientRects().length ?? 0,
+        };
+      }),
+    )
+    .toMatchObject({
+      chipWraps: true,
+      leadingContained: true,
+      leadingLineBoxes: 1,
+    });
+
+  await expect(chip).toHaveAttribute(
+    "title",
+    "Open repository relaytoolsobservabilityconsole-main",
+  );
+  await chipHeightAtWidth(420);
+  await composerInput.press("End");
+  await composerInput.pressSequentially(" after");
+  await expect(composerInput).toContainText(
+    "relaytoolsobservabilityconsole-main after",
+  );
+  await expect(chip).toHaveText("relaytoolsobservabilityconsole-main");
+  await page.getByTestId("send-message").click();
+
+  const sentChip = page.getByTestId("message-row").last().getByRole("button", {
+    name: "Open repository relaytoolsobservabilityconsole-main",
+  });
+  await expect(sentChip).toBeVisible();
+  await sentChip.evaluate((element) => {
+    const container = element.parentElement;
+    if (container) container.style.width = "220px";
+  });
+  const fragmentRects = await sentChip.evaluate((element) =>
+    Array.from(element.getClientRects(), (rect) => ({
+      bottom: rect.bottom,
+      height: rect.height,
+      left: rect.left,
+      right: rect.right,
+      top: rect.top,
+      width: rect.width,
+    })).filter((rect) => rect.width > 0 && rect.height > 0),
+  );
+  expect(fragmentRects.length).toBeGreaterThanOrEqual(2);
+
+  const tooltip = page.getByRole("tooltip");
+  await sentChip.focus();
+  await expect(tooltip).toBeVisible();
+  const positionOverFragment = async (index: number) => {
+    const fragment = await sentChip.evaluate((element, fragmentIndex) => {
+      const rects = Array.from(element.getClientRects()).filter(
+        (rect) => rect.width > 0 && rect.height > 0,
+      );
+      const rect = rects.at(fragmentIndex);
+      if (!rect) return null;
+      return {
+        height: rect.height,
+        left: rect.left,
+        top: rect.top,
+        width: rect.width,
+      };
+    }, index);
+    if (!fragment) throw new Error(`Expected chip fragment ${index}`);
+    const cursorX = fragment.left + fragment.width / 2;
+    const cursorY = fragment.top + fragment.height / 2;
+    await page.mouse.move(cursorX, cursorY);
+    await expect(tooltip).toBeVisible();
+    let tooltipCenter = Number.NaN;
+    await expect
+      .poll(async () => {
+        const tooltipBox = await tooltip.boundingBox();
+        if (!tooltipBox) return Number.POSITIVE_INFINITY;
+        tooltipCenter = tooltipBox.x + tooltipBox.width / 2;
+        return Math.abs(tooltipCenter - cursorX);
+      })
+      .toBeLessThan(1);
+    return {
+      cursorX,
+      tooltipCenter,
+    };
+  };
+
+  const firstTooltip = await positionOverFragment(0);
+  const lastTooltip = await positionOverFragment(-1);
+  expect(
+    Math.abs(firstTooltip.tooltipCenter - firstTooltip.cursorX),
+  ).toBeLessThan(1);
+  expect(
+    Math.abs(lastTooltip.tooltipCenter - lastTooltip.cursorX),
+  ).toBeLessThan(1);
+  expect(
+    Math.abs(firstTooltip.tooltipCenter - lastTooltip.tooltipCenter),
+  ).toBeGreaterThan(1);
+});
+
 test("message links to visible root messages open the thread panel", async ({
   page,
 }) => {
@@ -593,7 +791,7 @@ test("message links to visible root messages open the thread panel", async ({
   await expect(randomChannelLink).toHaveCSS("display", "inline");
   await expect(
     randomChannelLink.locator(".inline-chip-leading-fragment"),
-  ).toHaveText("r");
+  ).toHaveText("rando");
   await expect(randomChannelLink).not.toHaveAttribute("title");
   await randomChannelLink.hover();
   const channelTooltip = page.getByRole("tooltip");

From 02dc49f0e60f75027e926e33a2d0021f7b4e0cd3 Mon Sep 17 00:00:00 2001
From: Jordan Mecom <jm@squareup.com>
Date: Mon, 24 Aug 2026 15:07:08 -0700
Subject: [PATCH 3/9] docs(security): route reports through private advisories
 (#6728)

Routes security researchers to GitHub's private vulnerability reporting
workflow instead of a public issue or email-first disclosure.

- Makes the private advisory form the primary path in `SECURITY.md`,
with email retained as a fallback.
- Adds private-reporting links to the contributor guide, issue chooser,
and bug template.

Checked with `git diff --check`, Ruby YAML parsing, and confirmation
that private vulnerability reporting is enabled for `block/buzz`.

Signed-off-by: Jordan Mecom <jm@squareup.com>
---
 .github/ISSUE_TEMPLATE/bug-report.md |  4 ++++
 .github/ISSUE_TEMPLATE/config.yml    |  4 ++++
 CONTRIBUTING.md                      |  4 ++++
 SECURITY.md                          | 19 +++++++++++++++----
 4 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md
index e383313452..c951650eb1 100644
--- a/.github/ISSUE_TEMPLATE/bug-report.md
+++ b/.github/ISSUE_TEMPLATE/bug-report.md
@@ -4,6 +4,10 @@ about: Report a reproducible bug in Buzz
 labels: bug
 ---
 
+> [!IMPORTANT]
+> Do not include security vulnerabilities in a public issue. [Report them
+> privately through a GitHub security advisory](https://github.com/block/buzz/security/advisories/new).
+
 **Describe the bug**
 A clear and concise description of what the bug is.
 
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 0086358db1..67bfbe0ce4 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1 +1,5 @@
 blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/block/buzz/security/advisories/new
+    about: Report security vulnerabilities privately to the Buzz maintainers.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index db0aea637f..0247b570a2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,6 +6,10 @@ get from zero to a merged pull request.
 
 If you have questions that aren't answered here, [open an issue](https://github.com/block/buzz/issues/new).
 
+If you believe you found a security vulnerability, do not open a public issue.
+Follow our [security policy](SECURITY.md) to submit a private vulnerability
+report instead.
+
 ---
 
 ## Table of Contents
diff --git a/SECURITY.md b/SECURITY.md
index 45202b10fb..add36efee4 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -2,16 +2,25 @@
 
 ## Reporting a Vulnerability
 
-**Please do not report security vulnerabilities through public GitHub issues.**
+**Do not report security vulnerabilities through a public GitHub issue, pull
+request, discussion, or other public channel.**
 
-If you discover a security vulnerability in Buzz, please report it by emailing
-**buzz@block.xyz**. Include as much detail as possible:
+Use GitHub's private vulnerability reporting form instead:
+
+**[Report a vulnerability privately](https://github.com/block/buzz/security/advisories/new)**
+
+Submitting the form starts a private security advisory with the Buzz
+maintainers. Use that advisory for vulnerability details, follow-up questions,
+and coordinated remediation. Include as much detail as possible:
 
 - A description of the vulnerability and its potential impact
 - Steps to reproduce or a proof-of-concept (if available)
 - The affected version(s) or commit range
 - Any suggested mitigations you've identified
 
+If GitHub's private reporting form is unavailable to you, email
+**buzz@block.xyz** and do not include vulnerability details in a public issue.
+
 You will receive an acknowledgment within **48 hours**. We aim to provide a
 full response — including a timeline for a fix — within **7 days** of initial
 contact. We'll keep you informed as we work toward a resolution.
@@ -121,4 +130,6 @@ We use `cargo audit` in CI to scan for known vulnerabilities in dependencies.
 ## Disclosure Policy
 
 We follow [coordinated disclosure](https://en.wikipedia.org/wiki/Coordinated_vulnerability_disclosure).
-Reporters will be credited unless they request anonymity.
+We use the private advisory to coordinate validation, remediation, and
+disclosure with the reporter. Reporters will be credited unless they request
+anonymity.

From 69b1225923c9bd98784e86a6976bbc34a3dc8630 Mon Sep 17 00:00:00 2001
From: Wes <wesbillman@users.noreply.github.com>
Date: Mon, 24 Aug 2026 16:21:31 -0600
Subject: [PATCH 4/9] fix(ci): prevent poisoned Rust caches (#6618)

## Summary

- roll every `Swatinem/rust-cache` use back from v2.9.2 to the last
known-good v2.9.1 digest
- give Unit Tests a new `sherpa-cache-v1` key so it cannot restore the
existing poisoned artifact
- pin Renovate to v2.9.1 and add CI contracts that reject unsafe cache
actions or a misplaced generation key

## Why

After #5441 upgraded rust-cache to v2.9.2, warm-cache `main` Unit Tests
runs began failing while linking `buzz-voice` with `could not find
native static library sherpa-onnx-c-api`. The failed run at `db5617dd1`
restored the same 1.4 KB cache generation that had already failed at
`01091c15a`; the preceding cold run at `26f4c3ed3` downloaded sherpa
1.13.4 and passed.

v2.9.2 changed target cleanup, while `sherpa-onnx-sys` treats its
prebuilt `lib/` directory as proof that the native archive exists.
Rolling back the action and invalidating the affected key removes both
sides of that failure state without disabling target caching.

## Validation

At `6da0037a0407fc498cd482fcbbb74c7a15907e9f`:

- `scripts/test-rust-cache-contract.sh`
- `scripts/test-rust-cache-contract-regressions.sh`
- negative fixtures reject a bad digest in a newly named `.yaml`
workflow and a generation key moved outside the cache action's `with`
block
- YAML parse for all workflows
- release, desktop candidate, mobile release, mobile candidate, and
mobile worktree source contracts
- `just file-size-check`
- pre-commit and pre-push hooks

The PR Unit Tests run proves the cold-cache path because pull requests
restore but do not save Rust caches. The first successful `main` run
after merge will save the new Unit Tests key; the following `main` run
will exercise the warm restore.

## Related issue

None found.

Signed-off-by: Wes <wesbillman@users.noreply.github.com>
Co-authored-by: Carl <32a2e2c9d428ee08902cab75d956da2c1d235a22d4766b0dd4138bf6e2e5db1d@buzz.block.builderlab.xyz>
---
 .github/workflows/ci.yml                      |  21 ++-
 .github/workflows/mesh-lifecycle.yml          |   2 +-
 .github/workflows/release.yml                 |   2 +-
 renovate.json                                 |   6 +
 .../test-rust-cache-contract-regressions.sh   | 161 ++++++++++++++++++
 scripts/test-rust-cache-contract.sh           | 122 +++++++++++++
 6 files changed, 304 insertions(+), 10 deletions(-)
 create mode 100755 scripts/test-rust-cache-contract-regressions.sh
 create mode 100755 scripts/test-rust-cache-contract.sh

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 59b9a73ec9..a87ea957cd 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -87,6 +87,10 @@ jobs:
           scripts/test-mobile-release-candidate-publisher.sh
       - name: Mobile worktree identity contract
         run: scripts/test-mobile-worktree-overrides.sh
+      - name: Rust cache contract
+        run: |
+          scripts/test-rust-cache-contract.sh
+          scripts/test-rust-cache-contract-regressions.sh
       - name: File size policy
         run: just file-size-check
 
@@ -101,7 +105,7 @@ jobs:
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
-      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2.9.1
         with:
           save-if: ${{ github.event_name != 'pull_request' }}
       - name: Format check
@@ -123,8 +127,9 @@ jobs:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - uses: rui314/setup-mold@9c9c13bf4c3f1adef0cc596abc155580bcb04444 # v1
-      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2.9.1
         with:
+          key: sherpa-cache-v1
           save-if: ${{ github.event_name != 'pull_request' }}
       - name: Install cargo-nextest
         uses: taiki-e/install-action@0fd46367812ee04360509b4169d9f659d6892bb2 # v2.79.15
@@ -147,7 +152,7 @@ jobs:
           fetch-depth: 2
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - uses: rui314/setup-mold@9c9c13bf4c3f1adef0cc596abc155580bcb04444 # v1
-      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2.9.1
         with:
           workspaces: desktop/src-tauri
           save-if: ${{ github.event_name != 'pull_request' }}
@@ -340,7 +345,7 @@ jobs:
           key: relay-artifacts-${{ runner.os }}-${{ hashFiles('crates/**', 'migrations/**', 'Dockerfile', 'Cargo.toml', 'Cargo.lock', 'rust-toolchain.toml', '.cargo/config.toml', '.github/workflows/ci.yml') }}
       - uses: rui314/setup-mold@9c9c13bf4c3f1adef0cc596abc155580bcb04444 # v1
         if: steps.relay-artifacts-cache.outputs.cache-hit != 'true'
-      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2.9.1
         if: steps.relay-artifacts-cache.outputs.cache-hit != 'true'
         with:
           workspaces: |
@@ -763,7 +768,7 @@ jobs:
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
-      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2.9.1
         with:
           save-if: ${{ github.event_name != 'pull_request' }}
       # Reuse the relay + git-credential-nostr built by Desktop E2E Relay
@@ -952,7 +957,7 @@ jobs:
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
-      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2.9.1
         with:
           key: cross-${{ matrix.target }}
           save-if: ${{ github.event_name != 'pull_request' }}
@@ -993,7 +998,7 @@ jobs:
       # toolchain (1.95.0 + clippy via profile = default) comes from the
       # repo-root rust-toolchain.toml, which the runner's preinstalled rustup
       # honors on demand; the host triple already is x86_64-pc-windows-msvc.
-      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2.9.1
         with:
           workspaces: |
             .
@@ -1070,7 +1075,7 @@ jobs:
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
-      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2.9.1
         with:
           workspaces: desktop/src-tauri
           save-if: ${{ github.event_name != 'pull_request' }}
diff --git a/.github/workflows/mesh-lifecycle.yml b/.github/workflows/mesh-lifecycle.yml
index b5f9660dfe..c699439980 100644
--- a/.github/workflows/mesh-lifecycle.yml
+++ b/.github/workflows/mesh-lifecycle.yml
@@ -55,7 +55,7 @@ jobs:
 
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
 
-      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2.9.1
         with:
           save-if: ${{ github.event_name != 'pull_request' }}
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index cc8147515a..187604fcf4 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -511,7 +511,7 @@ jobs:
 
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
 
-      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2.9.1
         with:
           workspaces: desktop/src-tauri
           lookup-only: true
diff --git a/renovate.json b/renovate.json
index ee07aae898..91bd5fcc83 100644
--- a/renovate.json
+++ b/renovate.json
@@ -23,6 +23,12 @@
       "separateMinorPatch": true,
       "separateMultipleMinor": false
     },
+    {
+      "description": "rust-cache v2.9.2 cleanup can preserve sherpa's prebuilt directory after removing its static archive, poisoning warm Unit Tests caches. Keep v2.9.1 until the action or sherpa validates the archive before reuse.",
+      "matchManagers": ["github-actions"],
+      "matchPackageNames": ["Swatinem/rust-cache"],
+      "allowedVersions": "<=2.9.1"
+    },
     {
       "description": "evalexpr v13 relicensed from MIT to AGPL-3.0 — pin below v13 until migrated to an MIT alternative.",
       "matchPackageNames": ["evalexpr"],
diff --git a/scripts/test-rust-cache-contract-regressions.sh b/scripts/test-rust-cache-contract-regressions.sh
new file mode 100755
index 0000000000..708c26e77b
--- /dev/null
+++ b/scripts/test-rust-cache-contract-regressions.sh
@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root=$(cd "$(dirname "$0")/.." && pwd)
+known_good='e18b497796c12c097a38f9edb9d0641fb99eee32'
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/.github/workflows"
+cp "$root"/.github/workflows/*.yml "$tmp/.github/workflows/"
+for workflow in "$root"/.github/workflows/*.yaml; do
+  [[ -e "$workflow" ]] || continue
+  cp "$workflow" "$tmp/.github/workflows/"
+done
+cp "$root/renovate.json" "$tmp/renovate.json"
+
+run_contract() {
+  BUZZ_RUST_CACHE_CONTRACT_ROOT="$tmp" "$root/scripts/test-rust-cache-contract.sh"
+}
+
+expect_failure() {
+  local expected=$1
+  local output
+  if output=$(run_contract 2>&1); then
+    echo "expected rust cache contract failure containing: $expected" >&2
+    exit 1
+  fi
+  if [[ "$output" != *"$expected"* ]]; then
+    printf 'unexpected rust cache contract error:\n%s\n' "$output" >&2
+    exit 1
+  fi
+}
+
+write_cache_workflow() {
+  cat > "$tmp/.github/workflows/new-cache-user.yaml"
+}
+
+run_contract >/dev/null
+
+write_cache_workflow <<'YAML'
+name: Bad digest
+on: workflow_dispatch
+jobs:
+  cache:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6
+YAML
+expect_failure 'restored rust-cache v2.9.2'
+
+write_cache_workflow <<'YAML'
+name: Mutable tag
+on: workflow_dispatch
+jobs:
+  cache:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: Swatinem/rust-cache@v2
+YAML
+expect_failure 'rust-cache must stay on the v2.9.1 digest'
+
+write_cache_workflow <<'YAML'
+name: Expression ref
+on: workflow_dispatch
+jobs:
+  cache:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: Swatinem/rust-cache@${{ matrix.cache-ref }}
+YAML
+expect_failure 'rust-cache must stay on the v2.9.1 digest'
+
+write_cache_workflow <<'YAML'
+name: Spaced key
+on: workflow_dispatch
+jobs:
+  cache:
+    runs-on: ubuntu-latest
+    steps:
+      - uses : Swatinem/rust-cache@v2
+YAML
+expect_failure 'rust-cache must stay on the v2.9.1 digest'
+
+write_cache_workflow <<'YAML'
+name: Flow mapping
+on: workflow_dispatch
+jobs:
+  cache:
+    runs-on: ubuntu-latest
+    steps:
+      - { uses: Swatinem/rust-cache@v2 }
+YAML
+expect_failure 'rust-cache must stay on the v2.9.1 digest'
+
+write_cache_workflow <<'YAML'
+name: Quoted key
+on: workflow_dispatch
+jobs:
+  cache:
+    runs-on: ubuntu-latest
+    steps:
+      - "uses": Swatinem/rust-cache@v2
+YAML
+expect_failure 'rust-cache must stay on the v2.9.1 digest'
+rm "$tmp/.github/workflows/new-cache-user.yaml"
+
+mkdir -p "$tmp/.github/actions/cache"
+cat > "$tmp/.github/actions/cache/action.yml" <<'YAML'
+name: Unsafe cache wrapper
+runs:
+  using: composite
+  steps:
+    - { uses: Swatinem/rust-cache@v2 }
+YAML
+write_cache_workflow <<'YAML'
+name: Local cache wrapper
+on: workflow_dispatch
+jobs:
+  cache:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: ./.github/actions/cache
+YAML
+expect_failure 'rust-cache must stay on the v2.9.1 digest'
+
+cat > "$tmp/.github/actions/cache/action.yml" <<YAML
+name: Safe preferred cache wrapper
+runs:
+  using: composite
+  steps:
+    - uses: Swatinem/rust-cache@$known_good
+YAML
+cat > "$tmp/.github/actions/cache/action.yaml" <<'YAML'
+name: Unreachable stale cache wrapper
+runs:
+  using: composite
+  steps:
+    - uses: Swatinem/rust-cache@v2
+YAML
+run_contract >/dev/null
+rm -rf "$tmp/.github/actions" "$tmp/.github/workflows/new-cache-user.yaml"
+
+python3 - "$tmp/.github/workflows/ci.yml" <<'PY'
+import pathlib
+import sys
+
+path = pathlib.Path(sys.argv[1])
+workflow = path.read_text()
+needle = "          key: sherpa-cache-v1\n          save-if:"
+replacement = "          save-if:"
+if workflow.count(needle) != 1:
+    raise SystemExit("expected one Unit Tests cache generation key")
+workflow = workflow.replace(needle, replacement)
+job = "  unit-tests:\n"
+if workflow.count(job) != 1:
+    raise SystemExit("expected one Unit Tests job")
+workflow = workflow.replace(job, job + "    env:\n      key: sherpa-cache-v1\n", 1)
+path.write_text(workflow)
+PY
+expect_failure 'rust-cache action must keep with.key set to sherpa-cache-v1'
+
+echo "rust cache contract regressions passed"
diff --git a/scripts/test-rust-cache-contract.sh b/scripts/test-rust-cache-contract.sh
new file mode 100755
index 0000000000..30abd02659
--- /dev/null
+++ b/scripts/test-rust-cache-contract.sh
@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root=${BUZZ_RUST_CACHE_CONTRACT_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}
+renovate="$root/renovate.json"
+known_good='e18b497796c12c097a38f9edb9d0641fb99eee32'
+known_bad='6323deb102c322ba6fcbdcafc7e3dddab59af2b6'
+
+ruby - "$root" "$renovate" "$known_good" "$known_bad" <<'RUBY'
+require "json"
+require "pathname"
+require "yaml"
+
+root_name, renovate_name, known_good, known_bad = ARGV
+root = Pathname(root_name)
+workflow_paths = (root / ".github" / "workflows").children
+  .select { |path| path.file? && [".yml", ".yaml"].include?(path.extname) }
+  .sort
+abort "no GitHub Actions workflows found" if workflow_paths.empty?
+
+load_workflow = lambda do |path|
+  workflow = YAML.safe_load(path.binread.force_encoding("UTF-8"), aliases: true)
+  abort "#{path}: workflow must be a YAML mapping" unless workflow.is_a?(Hash)
+  workflow
+rescue Psych::Exception => error
+  abort "#{path}: invalid workflow YAML: #{error.message}"
+end
+
+uses_values = []
+walk = nil
+walk = lambda do |value, path, location|
+  case value
+  when Hash
+    value.each do |key, child|
+      child_location = "#{location}.#{key}"
+      uses_values << [path, child_location, child] if key.to_s == "uses"
+      walk.call(child, path, child_location)
+    end
+  when Array
+    value.each_with_index do |child, index|
+      walk.call(child, path, "#{location}[#{index}]")
+    end
+  end
+end
+
+workflows = workflow_paths.to_h do |path|
+  workflow = load_workflow.call(path)
+  walk.call(workflow, path, "$")
+  [path, workflow]
+end
+
+loaded_paths = workflow_paths.to_h { |path| [path.cleanpath, true] }
+uses_index = 0
+while uses_index < uses_values.length
+  coordinate = uses_values[uses_index][2]
+  uses_index += 1
+  next unless coordinate.is_a?(String) && coordinate.start_with?("./")
+
+  clean_root = root.realpath
+  target = (clean_root / coordinate.delete_prefix("./")).cleanpath
+  resolved_target = target.exist? ? target.realpath : target
+  root_prefix = "#{clean_root}#{File::SEPARATOR}"
+  inside_root = resolved_target == clean_root || resolved_target.to_s.start_with?(root_prefix)
+  abort "local action path escapes contract root: #{coordinate}" unless inside_root
+  next unless target.directory?
+
+  manifest = [target / "action.yml", target / "action.yaml"].find(&:file?)
+  abort "local action manifest missing: #{coordinate}" unless manifest
+  clean_manifest = manifest.cleanpath
+  next if loaded_paths[clean_manifest]
+
+  loaded_paths[clean_manifest] = true
+  action = load_workflow.call(clean_manifest)
+  walk.call(action, clean_manifest, "$")
+end
+
+cache_uses = uses_values.each_with_object([]) do |(path, location, coordinate), found|
+  next unless coordinate.is_a?(String)
+
+  match = /\ASwatinem\/rust-cache@(.+)\z/i.match(coordinate)
+  found << [path, location, match[1]] if match
+end
+abort "no Swatinem/rust-cache actions found" if cache_uses.empty?
+
+cache_uses.each do |path, location, ref|
+  if ref == known_bad
+    abort "#{path}:#{location}: restored rust-cache v2.9.2, which poisons sherpa caches"
+  end
+  unless ref == known_good
+    abort "#{path}:#{location}: rust-cache must stay on the v2.9.1 digest"
+  end
+end
+
+ci_path = root / ".github" / "workflows" / "ci.yml"
+ci = workflows.fetch(ci_path) { load_workflow.call(ci_path) }
+jobs = ci["jobs"]
+unit_tests = jobs.is_a?(Hash) ? jobs["unit-tests"] : nil
+abort "unit-tests job missing" unless unit_tests.is_a?(Hash)
+steps = unit_tests["steps"]
+abort "Unit Tests steps missing" unless steps.is_a?(Array)
+cache_steps = steps.select do |step|
+  step.is_a?(Hash) && step["uses"].is_a?(String) &&
+    step["uses"].match?(/\ASwatinem\/rust-cache@/i)
+end
+abort "Unit Tests must contain exactly one rust-cache action step" unless cache_steps.length == 1
+
+cache_with = cache_steps.first["with"]
+unless cache_with.is_a?(Hash) && cache_with["key"] == "sherpa-cache-v1"
+  abort "Unit Tests rust-cache action must keep with.key set to sherpa-cache-v1"
+end
+
+renovate = JSON.parse(Pathname(renovate_name).binread.force_encoding("UTF-8"))
+rules = renovate.fetch("packageRules", []).select do |rule|
+  rule["matchManagers"] == ["github-actions"] &&
+    rule["matchPackageNames"] == ["Swatinem/rust-cache"]
+end
+unless rules.length == 1 && rules.first["allowedVersions"] == "<=2.9.1"
+  abort "Renovate must keep Swatinem/rust-cache at v2.9.1 or older"
+end
+RUBY
+
+echo "rust cache contract passed"

From 30d2fc52f96138311f2006627ffc1a6d5ff1865b Mon Sep 17 00:00:00 2001
From: Wes <wesbillman@users.noreply.github.com>
Date: Mon, 24 Aug 2026 16:24:43 -0600
Subject: [PATCH 5/9] fix(desktop): restore icon-only remote marker (#6491)

## Summary

- restore the agreed icon-only cloud marker for an agent from another
setup
- retain the accessible `From another Buzz setup` label and native hover
title
- keep the merged loading, hover/focus persistence, and exact-pubkey
routing safeguards unchanged
- update the duplicate-agent E2E to require an icon with no visible
marker text in both autocomplete and Channel members

## Why

PR #6401 accidentally changed the agreed compact icon treatment into a
visible `Other setup` badge during review hardening. This is the
smallest correction and is intended for the active release.

## Testing

- Desktop JS: 5,280/5,280 passed
- Desktop TypeScript typecheck passed
- E2E build passed
- focused duplicate-agent Playwright journey: 1/1 passed
- file-size gate passed
- changed-file Biome and `git diff --check` passed

Carl, an automated reviewer, opened this via Wes's GitHub account.

Signed-off-by: Wes <wesbillman@users.noreply.github.com>
Co-authored-by: Carl <32a2e2c9d428ee08902cab75d956da2c1d235a22d4766b0dd4138bf6e2e5db1d@buzz.block.builderlab.xyz>
---
 .../agents/ui/OtherSetupAgentMarker.tsx       | 13 +++------
 desktop/tests/e2e/mentions.spec.ts            | 27 ++++++++++++-------
 2 files changed, 21 insertions(+), 19 deletions(-)

diff --git a/desktop/src/features/agents/ui/OtherSetupAgentMarker.tsx b/desktop/src/features/agents/ui/OtherSetupAgentMarker.tsx
index e653943469..19ef31bd75 100644
--- a/desktop/src/features/agents/ui/OtherSetupAgentMarker.tsx
+++ b/desktop/src/features/agents/ui/OtherSetupAgentMarker.tsx
@@ -1,7 +1,6 @@
 import { Cloud } from "lucide-react";
 
 import { cn } from "@/shared/lib/cn";
-import { Badge } from "@/shared/ui/badge";
 
 const OTHER_SETUP_LABEL = "From another Buzz setup";
 
@@ -13,18 +12,14 @@ export function OtherSetupAgentMarker({
   testId?: string;
 }) {
   return (
-    <Badge
+    <span
       aria-label={OTHER_SETUP_LABEL}
-      className={cn(
-        "gap-1 px-1.5 py-0.5 font-medium normal-case tracking-normal",
-        className,
-      )}
+      className={cn("inline-flex shrink-0", className)}
       data-testid={testId}
+      role="img"
       title={OTHER_SETUP_LABEL}
-      variant="secondary"
     >
       <Cloud aria-hidden="true" className="h-3 w-3" />
-      Other setup
-    </Badge>
+    </span>
   );
 }
diff --git a/desktop/tests/e2e/mentions.spec.ts b/desktop/tests/e2e/mentions.spec.ts
index ad1acf87c3..8f0300af16 100644
--- a/desktop/tests/e2e/mentions.spec.ts
+++ b/desktop/tests/e2e/mentions.spec.ts
@@ -410,19 +410,25 @@ test("duplicate owned agents preserve provenance and exact pubkey selection", as
     0,
   );
   await expect(relayRow).toContainText("agent");
-  await expect(
-    relayRow.getByTestId("mention-agent-provenance"),
-  ).toHaveAttribute("aria-label", "From another Buzz setup");
-  await expect(
-    relayRow.getByText("Other setup", { exact: true }),
-  ).toBeVisible();
+  const relayProvenanceMarker = relayRow.getByTestId(
+    "mention-agent-provenance",
+  );
+  await expect(relayProvenanceMarker).toHaveAttribute(
+    "aria-label",
+    "From another Buzz setup",
+  );
+  await expect(relayProvenanceMarker).toHaveAttribute(
+    "title",
+    "From another Buzz setup",
+  );
+  await expect(relayProvenanceMarker).toBeVisible();
+  await expect(relayProvenanceMarker).toHaveText("");
+  await expect(relayProvenanceMarker.locator("svg")).toBeVisible();
   await expect(managedRow).not.toContainText("managed by you");
   await expect(relayRow).not.toContainText("managed by you");
 
   await page.setViewportSize({ width: 760, height: 640 });
-  await expect(
-    relayRow.getByText("Other setup", { exact: true }),
-  ).toBeVisible();
+  await expect(relayProvenanceMarker).toBeVisible();
   const rowBox = await relayRow.boundingBox();
   const dropdownBox = await dropdown.boundingBox();
   expect(rowBox).not.toBeNull();
@@ -495,7 +501,8 @@ test("duplicate owned agents preserve provenance and exact pubkey selection", as
     "aria-label",
     "From another Buzz setup",
   );
-  await expect(remoteSidebarMarker).toHaveText("Other setup");
+  await expect(remoteSidebarMarker).toHaveText("");
+  await expect(remoteSidebarMarker.locator("svg")).toBeVisible();
   const remoteSidebarRow = page.getByTestId(`sidebar-member-${relayPubkey}`);
   const localSidebarMarker = page.getByTestId(
     `sidebar-member-agent-provenance-${managedPubkey}`,

From c5166f2164035ca96787daee6528d5dc04c4a02e Mon Sep 17 00:00:00 2001
From: morgmart <98432065+morgmart@users.noreply.github.com>
Date: Mon, 24 Aug 2026 16:28:51 -0700
Subject: [PATCH 6/9] feat(desktop): simplify the message action rail (#6529)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Problem

Quick-reaction shortcuts make the message action rail visually noisy.
Reaction access should remain first-class, but through one predictable
Add reaction action rather than several learned emoji shortcuts.

## Change

The rail is now:

**Add reaction · Reply · Copy link · More**

- Remove all quick-reaction shortcut buttons and their divider from the
message action rail.
- Preserve Add reaction as the first action, including its existing
picker, tooltip, accessible name, keyboard behavior, reaction behavior,
and feedback.
- Keep the existing Link2 Copy link action, shared copy handler,
More-menu entry, eligibility guards, and success feedback unchanged.
- Keep reveal, positioning, responsiveness, styling, and remaining menu
paths unchanged.

The now-unused quick-reaction rendering component and imports were
removed from `MessageActionBar`; shared reaction learning remains intact
for other reaction surfaces.

## Tests

Focused smoke coverage verifies:

- zero `React with …` shortcut buttons;
- exact ordered rail: `Open reactions → Reply → Copy link → More
actions`;
- the rail and More-menu paths emit the same canonical thread-aware
`buzz://message` URL;
- existing success feedback;
- pending and huddle rows omit both copy-link surfaces;
- the action bar stays within the open thread panel.

The zero-shortcut contract was mutation-checked by restoring the prior
production action bar: the focused test failed causally with expected 0
versus received 3 quick-reaction buttons.

## Validation

At `4f062e0d60b0f0c16b6862cdea7137c287060947`:

- `pnpm exec biome check src/features/messages/ui/MessageActionBar.tsx
tests/e2e/message-copy-link.spec.ts` — passed.
- `pnpm exec tsc --noEmit` — passed.
- `pnpm test` — 5,432 passed, 0 failed.
- `pnpm build:e2e` — passed; existing dynamic-import and chunk-size
warnings only.
- `pnpm exec playwright test tests/e2e/message-copy-link.spec.ts
--project=smoke` — 2 passed.
- Pre-push `file-size-check`, `desktop-check`, `desktop-typecheck`, and
`desktop-test` — passed.

Vogue’s design review: **SHIP** — reaction remains discoverable and
accessible as the visible first action; the extra click is an
intentional efficiency tradeoff for the simpler hierarchy.

---------

Signed-off-by: Trace (Engineer) <9d485ff0c62915e08a801162c195c7ef096f6f6143925407255cea2656c4b8a4@buzz.block.builderlab.xyz>
Signed-off-by: morgmart <98432065+morgmart@users.noreply.github.com>
Signed-off-by: Rivet <a08d9a8418c7ff03afe19964724c8fd87bf1776ab9e9b9cafb8cc920edd02a6e@buzz.block.builderlab.xyz>
Co-authored-by: Trace (Engineer) <9d485ff0c62915e08a801162c195c7ef096f6f6143925407255cea2656c4b8a4@buzz.block.builderlab.xyz>
Co-authored-by: Rivet <a08d9a8418c7ff03afe19964724c8fd87bf1776ab9e9b9cafb8cc920edd02a6e@buzz.block.builderlab.xyz>
---
 desktop/playwright.config.ts                  |   1 +
 .../features/messages/ui/MessageActionBar.tsx | 141 +++++---------
 .../e2e/channel-activity-popover.spec.ts      |   9 +-
 desktop/tests/e2e/custom-emoji.spec.ts        |  21 +-
 desktop/tests/e2e/inbox-reactions.spec.ts     |  10 +-
 desktop/tests/e2e/message-copy-link.spec.ts   | 182 ++++++++++++++++++
 desktop/tests/e2e/reaction-order.spec.ts      |  25 +--
 7 files changed, 268 insertions(+), 121 deletions(-)
 create mode 100644 desktop/tests/e2e/message-copy-link.spec.ts

diff --git a/desktop/playwright.config.ts b/desktop/playwright.config.ts
index 69250c4b53..be15c75587 100644
--- a/desktop/playwright.config.ts
+++ b/desktop/playwright.config.ts
@@ -38,6 +38,7 @@ export default defineConfig({
         "**/invites-settings-screenshots.spec.ts",
         "**/messaging.spec.ts",
         "**/message-feedback-snapshots.spec.ts",
+        "**/message-copy-link.spec.ts",
         "**/custom-emoji.spec.ts",
         "**/profile-custom-emoji-status.spec.ts",
         "**/custom-emoji-ui.spec.ts",
diff --git a/desktop/src/features/messages/ui/MessageActionBar.tsx b/desktop/src/features/messages/ui/MessageActionBar.tsx
index 4fcf0f067a..9c490edb07 100644
--- a/desktop/src/features/messages/ui/MessageActionBar.tsx
+++ b/desktop/src/features/messages/ui/MessageActionBar.tsx
@@ -18,7 +18,6 @@ import { toast } from "sonner";
 
 import { buildMessageLink } from "@/features/messages/lib/messageLink";
 import { EmojiPicker } from "@/features/custom-emoji/ui/EmojiPicker";
-import { useCustomEmoji } from "@/features/custom-emoji/hooks";
 import { getThreadReference } from "@/features/messages/lib/threading";
 import { ReportMessageDialog } from "@/features/moderation/ui/ReportMessageDialog";
 import { MessageModerationMenuItems } from "@/features/moderation/ui/MessageModerationMenuItems";
@@ -26,15 +25,9 @@ import type {
   TimelineMessage,
   TimelineReaction,
 } from "@/features/messages/types";
-import {
-  recordQuickReactionEmoji,
-  useQuickReactionEmojis,
-} from "@/features/messages/ui/useQuickReactionEmojis";
-import { reactionEmojiUrl } from "@/shared/api/customEmoji";
+import { recordQuickReactionEmoji } from "@/features/messages/ui/useQuickReactionEmojis";
 import { cn } from "@/shared/lib/cn";
 import { copyTextToClipboard } from "@/shared/lib/clipboard";
-import { emojiDisplayName } from "@/shared/lib/emojiName";
-import { rewriteRelayUrl } from "@/shared/lib/mediaUrl";
 import { KIND_HUDDLE_STARTED } from "@/shared/constants/kinds";
 import { Button } from "@/shared/ui/button";
 import { HashArrowIn } from "@/shared/ui/icons";
@@ -53,6 +46,32 @@ import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
 const ACTION_BUTTON_CLASS = "h-8 w-8 rounded-full p-0";
 const ACTION_ICON_CLASS = "!h-4 !w-4";
 
+/** Copying a message link is offered from both the hover action bar and the
+ *  More menu; both paths share this exact link-building + toast behavior. */
+function copyMessageLink(channelId: string, message: TimelineMessage) {
+  const { rootId } = getThreadReference(message.tags ?? []);
+  const link = buildMessageLink({
+    channelId,
+    messageId: message.id,
+    threadRootId: rootId,
+  });
+  copyTextToClipboard(link, "Link copied to clipboard");
+}
+
+/** Gate shared by every copy-link surface: pending sends have no delivered
+ *  event to link to, huddle system rows aren't linkable, and callers without
+ *  a channelId (e.g. inbox preview rows) can't build the link. */
+function canCopyMessageLink(
+  message: TimelineMessage,
+  channelId: string | null | undefined,
+): channelId is string {
+  return (
+    !message.pending &&
+    message.kind !== KIND_HUDDLE_STARTED &&
+    Boolean(channelId)
+  );
+}
+
 function MoreActionsMenu({
   channelId,
   message,
@@ -242,17 +261,11 @@ function MoreActionsMenu({
             </DropdownMenuItem>
           ) : null}
 
-          {hasCopyActions && channelId ? (
+          {canCopyMessageLink(message, channelId) ? (
             <DropdownMenuItem
               data-testid={`copy-message-link-${message.id}`}
               onClick={() => {
-                const { rootId } = getThreadReference(message.tags ?? []);
-                const link = buildMessageLink({
-                  channelId,
-                  messageId: message.id,
-                  threadRootId: rootId,
-                });
-                copyTextToClipboard(link, "Link copied to clipboard");
+                copyMessageLink(channelId, message);
               }}
             >
               <Link2 className="h-4 w-4" />
@@ -316,51 +329,6 @@ function MoreActionsMenu({
   );
 }
 
-function QuickReactionButton({
-  customEmojiUrl,
-  emoji,
-  onSelect,
-}: {
-  customEmojiUrl?: string;
-  emoji: string;
-  onSelect: (emoji: string) => void;
-}) {
-  const displayName = emojiDisplayName(emoji);
-  const mediaUrl = customEmojiUrl ? rewriteRelayUrl(customEmojiUrl) : null;
-
-  return (
-    <Tooltip>
-      <TooltipTrigger asChild>
-        <button
-          aria-label={`React with ${displayName}`}
-          className="flex h-8 w-8 items-center justify-center rounded-full text-base leading-none text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
-          onClick={() => onSelect(emoji)}
-          title={displayName}
-          type="button"
-        >
-          {mediaUrl ? (
-            <img
-              alt={emoji}
-              className="h-5 w-5 object-contain"
-              draggable={false}
-              src={mediaUrl}
-            />
-          ) : (
-            <span aria-hidden="true" className="translate-y-px">
-              {emoji}
-            </span>
-          )}
-        </button>
-      </TooltipTrigger>
-      <TooltipContent>{displayName}</TooltipContent>
-    </Tooltip>
-  );
-}
-
-function isCustomEmojiShortcode(emoji: string) {
-  return emoji.startsWith(":") && emoji.endsWith(":");
-}
-
 export const MessageActionBar = React.memo(function MessageActionBar({
   channelId,
   message,
@@ -404,20 +372,6 @@ export const MessageActionBar = React.memo(function MessageActionBar({
 }) {
   const [isReactionPickerOpen, setIsReactionPickerOpen] = React.useState(false);
   const [isDropdownOpen, setIsDropdownOpen] = React.useState(false);
-  const customEmoji = useCustomEmoji();
-  const quickReactionEmojis = useQuickReactionEmojis(4, customEmoji);
-  const quickReactionItems = React.useMemo(
-    () =>
-      quickReactionEmojis
-        .map((emoji) => ({
-          customEmojiUrl: reactionEmojiUrl(emoji, customEmoji),
-          emoji,
-        }))
-        .filter(
-          (item) => !isCustomEmojiShortcode(item.emoji) || item.customEmojiUrl,
-        ),
-    [customEmoji, quickReactionEmojis],
-  );
   const hasReplyAction = Boolean(onReply);
   const hasReactionAction = Boolean(onReactionSelect);
 
@@ -482,22 +436,6 @@ export const MessageActionBar = React.memo(function MessageActionBar({
     >
       <div className="overflow-hidden rounded-full border border-border/70 bg-background/95 shadow-xs backdrop-blur-sm supports-[backdrop-filter]:bg-background/85">
         <div className="flex items-center gap-0.5 p-1">
-          {hasReactionAction && quickReactionItems.length > 0 ? (
-            <>
-              <div className="hidden items-center gap-0.5 sm:flex">
-                {quickReactionItems.map(({ customEmojiUrl, emoji }) => (
-                  <QuickReactionButton
-                    customEmojiUrl={customEmojiUrl}
-                    emoji={emoji}
-                    key={emoji}
-                    onSelect={handleReactionSelection}
-                  />
-                ))}
-              </div>
-              <div className="mx-0.5 hidden h-4 w-px bg-border/70 sm:block" />
-            </>
-          ) : null}
-
           {hasReactionAction ? (
             <Popover
               onOpenChange={setIsReactionPickerOpen}
@@ -566,6 +504,27 @@ export const MessageActionBar = React.memo(function MessageActionBar({
             </Tooltip>
           ) : null}
 
+          {canCopyMessageLink(message, channelId) ? (
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <Button
+                  aria-label="Copy link"
+                  className={ACTION_BUTTON_CLASS}
+                  data-testid={`copy-link-message-${message.id}`}
+                  onClick={() => {
+                    copyMessageLink(channelId, message);
+                  }}
+                  size="sm"
+                  type="button"
+                  variant="ghost"
+                >
+                  <Link2 className={ACTION_ICON_CLASS} />
+                </Button>
+              </TooltipTrigger>
+              <TooltipContent>Copy link</TooltipContent>
+            </Tooltip>
+          ) : null}
+
           {hasMoreMenuActions ? (
             <MoreActionsMenu
               channelId={channelId}
diff --git a/desktop/tests/e2e/channel-activity-popover.spec.ts b/desktop/tests/e2e/channel-activity-popover.spec.ts
index a62d064d76..1db10ed6f1 100644
--- a/desktop/tests/e2e/channel-activity-popover.spec.ts
+++ b/desktop/tests/e2e/channel-activity-popover.spec.ts
@@ -773,10 +773,11 @@ test.describe("channel activity hover preview", () => {
     await rootRow.hover();
     const actionBar = page.getByTestId(`message-action-bar-${root.id}`);
     await expect(actionBar).toBeVisible();
-    await actionBar
-      .getByRole("button", { name: /^React with / })
-      .first()
-      .click();
+    await actionBar.getByRole("button", { name: "Open reactions" }).click();
+    const picker = page.locator("em-emoji-picker");
+    await expect(picker).toBeVisible();
+    await picker.locator("input[type='search']").fill("thumbs up");
+    await picker.getByRole("button", { name: "👍" }).first().click();
     await expect(
       rootRow.getByRole("button", { name: /^Toggle .* reaction$/ }),
     ).toBeVisible();
diff --git a/desktop/tests/e2e/custom-emoji.spec.ts b/desktop/tests/e2e/custom-emoji.spec.ts
index 16ca3900ec..9a4bf7f07c 100644
--- a/desktop/tests/e2e/custom-emoji.spec.ts
+++ b/desktop/tests/e2e/custom-emoji.spec.ts
@@ -285,7 +285,7 @@ async function quickReactionStorageContains(
   }, emoji);
 }
 
-test("message quick reaction tray stays neutral after selecting a tray emoji", async ({
+test("message reaction action stays neutral after selecting from the picker", async ({
   page,
 }) => {
   await openGeneral(page);
@@ -294,19 +294,18 @@ test("message quick reaction tray stays neutral after selecting a tray emoji", a
   await expect(row).toBeVisible();
   await row.hover();
 
-  const quickReactionButton = row.getByRole("button", {
-    name: "React with :+1:",
-  });
-  await expect(quickReactionButton).toBeVisible();
-  await quickReactionButton.click();
+  const reactionTrigger = messageReactionTrigger(row);
+  await expect(reactionTrigger).toBeVisible();
+  await reactionTrigger.click();
+  const picker = page.locator("em-emoji-picker");
+  await expect(picker).toBeVisible();
+  await picker.locator("input[type='search']").fill("thumbs up");
+  await picker.getByRole("button", { name: "👍" }).first().click();
 
   await expect(row.getByLabel("Toggle 👍 reaction")).toBeVisible();
   await row.hover();
-  await expect(quickReactionButton).not.toHaveAttribute("aria-pressed", "true");
-  await expect(quickReactionButton).not.toHaveClass(SELECTED_ACTION_CLASS);
-  await expect(messageReactionTrigger(row)).not.toHaveClass(
-    SELECTED_ACTION_CLASS,
-  );
+  await expect(reactionTrigger).not.toHaveAttribute("aria-pressed", "true");
+  await expect(reactionTrigger).not.toHaveClass(SELECTED_ACTION_CLASS);
 });
 
 test("emoji picker keeps Frequently used live within the app session", async ({
diff --git a/desktop/tests/e2e/inbox-reactions.spec.ts b/desktop/tests/e2e/inbox-reactions.spec.ts
index 1b7451cbcc..2385be0f6c 100644
--- a/desktop/tests/e2e/inbox-reactions.spec.ts
+++ b/desktop/tests/e2e/inbox-reactions.spec.ts
@@ -114,7 +114,7 @@ test("inbox reaction on a thread-reply mention persists after refetch", async ({
     },
   );
 
-  // Open the inbox item and react via the hover action bar's quick reaction.
+  // Open the inbox item and react through Add reaction and the picker.
   const item = page.getByTestId(`home-inbox-item-${replyEvent.id}`);
   await item.click();
   const detail = page.getByTestId("home-inbox-detail");
@@ -152,9 +152,11 @@ test("inbox reaction on a thread-reply mention persists after refetch", async ({
   }
   expect(actionBarBox.y).toBeGreaterThanOrEqual(selectedMessageBox.y);
 
-  await selectedMessage
-    .getByRole("button", { name: "React with :+1:" })
-    .click();
+  await actionBar.getByRole("button", { name: "Open reactions" }).click();
+  const picker = page.locator("em-emoji-picker");
+  await expect(picker).toBeVisible();
+  await picker.locator("input[type='search']").fill("thumbs up");
+  await picker.getByRole("button", { name: "👍" }).first().click();
 
   // The pill must appear AND persist: the post-toggle refetch replaces the
   // optimistic state with fetched reaction events. Give the refetch time to
diff --git a/desktop/tests/e2e/message-copy-link.spec.ts b/desktop/tests/e2e/message-copy-link.spec.ts
new file mode 100644
index 0000000000..a7ef2f10c6
--- /dev/null
+++ b/desktop/tests/e2e/message-copy-link.spec.ts
@@ -0,0 +1,182 @@
+import { expect, test, type Locator, type Page } from "@playwright/test";
+
+import { KIND_HUDDLE_STARTED } from "../../src/shared/constants/kinds";
+import { installMockBridge } from "../helpers/bridge";
+
+const GENERAL_CHANNEL_ID = "9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50";
+
+async function latestClipboardWrite(page: Page) {
+  return page.evaluate(() =>
+    (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).findLast(
+      ({ command }) => command === "copy_text_to_clipboard",
+    ),
+  );
+}
+
+async function expectCopyLinkUnavailable(row: Locator, messageId: string) {
+  await row.hover();
+  await expect(row.getByTestId(`copy-link-message-${messageId}`)).toHaveCount(
+    0,
+  );
+
+  const moreActions = row.getByTestId(`more-actions-${messageId}`);
+  if (await moreActions.count()) {
+    await moreActions.click({ force: true });
+    await expect(
+      row.page().getByTestId(`copy-message-link-${messageId}`),
+    ).toHaveCount(0);
+    await row.page().keyboard.press("Escape");
+  }
+}
+
+test.beforeEach(async ({ page }) => {
+  await page.context().grantPermissions(["clipboard-read", "clipboard-write"], {
+    origin: "http://127.0.0.1:4173",
+  });
+  await installMockBridge(page);
+});
+
+test("message action rail copies the same canonical thread link as More", async ({
+  page,
+}) => {
+  await page.setViewportSize({ width: 900, height: 700 });
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () => typeof window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__ === "function",
+      ),
+    )
+    .toBe(true);
+
+  const { replyId, rootId } = await page.evaluate(() => {
+    const emit = window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__;
+    if (!emit) throw new Error("Mock message emitter is unavailable.");
+    const root = emit({
+      channelName: "general",
+      content: "Copy-link regression root",
+      id: "a".repeat(64),
+    });
+    const reply = emit({
+      channelName: "general",
+      content: "Copy-link regression reply",
+      id: "b".repeat(64),
+      parentEventId: root.id,
+    });
+    return { replyId: reply.id, rootId: root.id };
+  });
+
+  await page
+    .locator(
+      `[data-testid="message-thread-summary"][data-thread-head-id="${rootId}"]`,
+    )
+    .click();
+  const threadPanel = page.getByTestId("message-thread-panel");
+  const replyRow = threadPanel.locator(`[data-message-id="${replyId}"]`);
+  await expect(replyRow).toContainText("Copy-link regression reply");
+  await replyRow.hover();
+
+  const actionBar = replyRow.getByTestId(`message-action-bar-${replyId}`);
+  const quickReactions = actionBar.getByRole("button", {
+    name: /^React with /,
+  });
+  await expect(quickReactions).toHaveCount(0);
+  const orderedActionNames = await actionBar
+    .getByRole("button")
+    .evaluateAll((buttons) =>
+      buttons.map((button) => button.getAttribute("aria-label")),
+    );
+  expect(orderedActionNames).toEqual([
+    "Open reactions",
+    "Reply",
+    "Copy link",
+    "More actions",
+  ]);
+
+  const copyLink = actionBar.getByTestId(`copy-link-message-${replyId}`);
+  await expect(copyLink).toHaveAccessibleName("Copy link");
+  await copyLink.hover();
+  await expect(page.getByRole("tooltip", { name: "Copy link" })).toBeVisible();
+
+  const expectedLink = `buzz://message?channel=${GENERAL_CHANNEL_ID}&id=${replyId}&thread=${rootId}`;
+  await copyLink.click();
+  await expect
+    .poll(async () => (await latestClipboardWrite(page))?.payload.text)
+    .toBe(expectedLink);
+  await expect(
+    page.locator("[data-sonner-toast]").filter({
+      hasText: "Link copied to clipboard",
+    }),
+  ).toBeVisible();
+
+  await actionBar.getByTestId(`more-actions-${replyId}`).click();
+  await page.getByTestId(`copy-message-link-${replyId}`).click();
+  await expect
+    .poll(async () => {
+      const writes = (await page.evaluate(() =>
+        (window.__BUZZ_E2E_COMMAND_LOG__ ?? []).filter(
+          ({ command }) => command === "copy_text_to_clipboard",
+        ),
+      )) as Array<{ payload: unknown }>;
+      return writes.map(({ payload }) => payload);
+    })
+    .toEqual([{ text: expectedLink }, { text: expectedLink }]);
+
+  const [barBox, panelBox] = await Promise.all([
+    actionBar.boundingBox(),
+    threadPanel.boundingBox(),
+  ]);
+  expect(barBox).not.toBeNull();
+  expect(panelBox).not.toBeNull();
+  if (!barBox || !panelBox) throw new Error("Message action bounds missing.");
+  expect(barBox.x).toBeGreaterThanOrEqual(panelBox.x);
+  expect(barBox.x + barBox.width).toBeLessThanOrEqual(
+    panelBox.x + panelBox.width,
+  );
+});
+
+test("pending and huddle rows omit both copy-link surfaces", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+  await expect
+    .poll(() =>
+      page.evaluate(
+        () => typeof window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__ === "function",
+      ),
+    )
+    .toBe(true);
+
+  const { huddleId, pendingId } = await page.evaluate((huddleKind) => {
+    const emit = window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__;
+    if (!emit) throw new Error("Mock message emitter is unavailable.");
+    const pending = emit({
+      channelName: "general",
+      content: "Pending copy-link regression",
+      id: "c".repeat(64),
+      pending: true,
+    });
+    const huddle = emit({
+      channelName: "general",
+      content: JSON.stringify({
+        ephemeral_channel_id: "10000000-0000-4000-8000-000000000001",
+      }),
+      id: "d".repeat(64),
+      kind: huddleKind,
+    });
+    return { huddleId: huddle.id, pendingId: pending.id };
+  }, KIND_HUDDLE_STARTED);
+
+  await expectCopyLinkUnavailable(
+    page.locator(`[data-message-id="${pendingId}"]`),
+    pendingId,
+  );
+  await expectCopyLinkUnavailable(
+    page.locator(`[data-message-id="${huddleId}"]`),
+    huddleId,
+  );
+});
diff --git a/desktop/tests/e2e/reaction-order.spec.ts b/desktop/tests/e2e/reaction-order.spec.ts
index 34cf071e77..b37ce56dd1 100644
--- a/desktop/tests/e2e/reaction-order.spec.ts
+++ b/desktop/tests/e2e/reaction-order.spec.ts
@@ -64,16 +64,19 @@ async function getBodyToReactionGap(
   return Math.round(reactions.y - (body.y + body.height));
 }
 
-/** Click a quick-reaction tray button by emoji (hover → click tray button). */
-async function addQuickReaction(
+/** Add a reaction through the preserved message action and emoji picker. */
+async function addReaction(
+  page: import("@playwright/test").Page,
   row: import("@playwright/test").Locator,
   emoji: string,
-  label: string,
+  search: string,
 ) {
   await row.hover();
-  const btn = row.getByRole("button", { name: `React with ${label}` });
-  await expect(btn).toBeVisible();
-  await btn.click();
+  await row.getByRole("button", { name: "Open reactions" }).click();
+  const picker = page.locator("em-emoji-picker");
+  await expect(picker).toBeVisible();
+  await picker.locator("input[type='search']").fill(search);
+  await picker.getByRole("button", { name: emoji }).first().click();
   // Wait for the optimistic pill to appear before continuing.
   await expect(
     row
@@ -97,11 +100,11 @@ test("reaction pills render left-to-right in the order reactions were added", as
   // Add three reactions in order: 👍 → ❤️ → 😂.
   // Wait >1 s between each so mock bridge timestamps differ by at least 1 Unix
   // second — the formatter sorts by created_at, so distinct seconds matter.
-  await addQuickReaction(row, "👍", ":+1:");
+  await addReaction(page, row, "👍", "thumbs up");
   await page.waitForTimeout(1100);
-  await addQuickReaction(row, "❤️", ":heart:");
+  await addReaction(page, row, "❤️", "red heart");
   await page.waitForTimeout(1100);
-  await addQuickReaction(row, "😂", ":joy:");
+  await addReaction(page, row, "😂", "face with tears of joy");
 
   const pills = await getPillOrder(row);
   expect(pills).toEqual(["👍", "❤️", "😂"]);
@@ -136,9 +139,9 @@ test("a later emoji that accrues more reactors stays to the right of an earlier
   // since the key invariant is positional stability: even if ❤️ had higher
   // count it must stay right of 👍.
   // We use 🎉 (added second) and verify it stays right of 👍 (added first).
-  await addQuickReaction(row, "👍", ":+1:");
+  await addReaction(page, row, "👍", "thumbs up");
   await page.waitForTimeout(1100);
-  await addQuickReaction(row, "🎉", ":tada:");
+  await addReaction(page, row, "🎉", "party popper");
 
   // Both pills present in chronological order: 👍 left, 🎉 right.
   const afterAdd = await getPillOrder(row);

From e760c51820b2103d965c22b44254678e10fb689a Mon Sep 17 00:00:00 2001
From: Taylor Ho <taylorkmho@gmail.com>
Date: Mon, 24 Aug 2026 17:40:23 -0700
Subject: [PATCH 7/9] feat(workflows): discover trigger filter values (#6712)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

**Category:** improvement
**User Impact:** Workflow authors can discover people and messages while
configuring trigger filters, then see readable enriched labels instead
of raw identifiers.

**Problem:** Author and message filters required users to know and paste
raw public keys or event IDs, and configured workflows surfaced those
opaque values afterward. **Solution:** Add network-backed pickers and
presentation enrichment while keeping deterministic local public-key and
event-ID fallbacks authoritative whenever discovery is unavailable or
untrusted.

Related issue: none found.

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

**desktop/src/features/workflows/ui/WorkflowAuthorPicker.tsx**
Adds channel-aware author discovery, profile search, keyboard
navigation, loading states, and deterministic public-key fallback
selection.

**desktop/src/features/workflows/ui/WorkflowCard.tsx**
Uses enriched trigger presentation when building the workflow card’s
readable summary.

**desktop/src/features/workflows/ui/WorkflowDialog.tsx**
Keeps Escape scoped to an active filter picker before allowing the
inspector or dialog to close.

**desktop/src/features/workflows/ui/WorkflowFormBuilder.tsx**
Threads channel context into trigger filters and renders enriched
author/message summaries in the workflow sequence.

**desktop/src/features/workflows/ui/WorkflowMessagePicker.tsx**
Adds paged channel-history discovery, message search, exact event
lookup, profile labels, keyboard navigation, and bounded results.

**desktop/src/features/workflows/ui/WorkflowRichTriggerDescription.tsx**
Renders compact author identity details and loading presentation inside
trigger summaries.

**desktop/src/features/workflows/ui/WorkflowTriggerConditions.tsx**
Connects author and message filter accordions to their pickers while
preserving selected and excluded condition semantics.

**desktop/src/features/workflows/ui/useWorkflowAuthorPresentation.ts**
Resolves configured author keys to trusted display labels with
deterministic fallbacks.

**desktop/src/features/workflows/ui/useWorkflowTriggerPresentation.ts**
Enriches configured message IDs only after validating the fetched event
and channel.

**desktop/src/features/workflows/ui/workflowAuthorCandidates.test.mjs**
Covers author candidate normalization, ordering, deduplication, and
fallback behavior.

**desktop/src/features/workflows/ui/workflowAuthorCandidates.ts**
Builds stable author candidates from channel members, profiles, and raw
public keys.

**desktop/src/features/workflows/ui/workflowConditionExpression.ts**
Allows message IDs to participate in basic trigger-filter parsing.

**desktop/src/features/workflows/ui/workflowDefinition.ts**
Accepts enriched trigger text when generating workflow card labels.

**desktop/src/features/workflows/ui/workflowMessageCandidates.test.mjs**
Covers event validation, source merging, deterministic ordering, and
exact-lookup enrichment boundaries.

**desktop/src/features/workflows/ui/workflowMessageCandidates.ts**
Validates message candidates by event kind, channel, and exact event ID
before permitting enrichment.


**desktop/src/features/workflows/ui/workflowTriggerDescription.test.mjs**
Covers readable selected/excluded author and message descriptions plus
loading fallbacks.

**desktop/src/features/workflows/ui/workflowTriggerDescription.ts**
Builds concise enriched trigger descriptions while retaining stable
raw-ID fallbacks.

**desktop/tests/e2e/workflow-local-controls.spec.ts**
Exercises picker discovery, selection toggles, Escape ownership, bounded
scrolling, and enriched workflow summaries.

</details>

## Reproduction steps

1. Open Workflows and create a workflow for a channel with members and
message history.
2. Choose **Reaction Added** as the trigger and expand **Author**.
3. Confirm channel members and fetched profile results are discoverable,
searchable, and keyboard accessible; choose one.
4. Expand **Message**, confirm recent channel messages appear in a
bounded list, and choose one.
5. Toggle either selected filter between **is** and **is not**, then
collapse the inspector and confirm the sequence summary stays readable.
6. Add a send-message step and create the workflow; confirm its card
uses the resolved author and message labels.
7. Repeat while discovery is unavailable and confirm raw public
keys/event IDs remain selectable and authoritative.

## Screenshots

### Author discovery

![Author picker showing discoverable channel members and profile
labels](https://raw.githubusercontent.com/block/buzz/df47bdab841e0f52eb1f4ea9ac4e70aa16d240e0/pr-6712--01-author-discovery.png)

### Message discovery

![Message picker showing bounded channel history
discovery](https://raw.githubusercontent.com/block/buzz/df47bdab841e0f52eb1f4ea9ac4e70aa16d240e0/pr-6712--02-message-discovery.png)

### Selected filter summaries

![Workflow builder showing readable selected author and message
filters](https://raw.githubusercontent.com/block/buzz/df47bdab841e0f52eb1f4ea9ac4e70aa16d240e0/pr-6712--03-selected-filter-summaries.png)

### Enriched workflow card

![Workflow card showing enriched author and message
labels](https://raw.githubusercontent.com/block/buzz/df47bdab841e0f52eb1f4ea9ac4e70aa16d240e0/pr-6712--04-enriched-workflow-card.png)

---------

Signed-off-by: Taylor Ho <taylorkmho@gmail.com>
Co-authored-by: Carl <acda9e433d19dcd0e6b6840f7f4b98f3a56f1fab98049d444c087019e6d36560@buzz.block.builderlab.xyz>
Co-authored-by: Princess Donut <0366ccd5ee09c2779a9d6bd6683daa17c16a508a51f6a7e7314018dab8fdc49b@buzz.block.builderlab.xyz>
Co-authored-by: Rizz <302abe414ca6e3134763d2539bfcf145aea2a63fe5f8455204ed602fd40cf381@buzz.block.builderlab.xyz>
---
 desktop/src-tauri/src/commands/messages.rs    |  19 +-
 .../src/commands/messages/event_batch.rs      | 128 +++++
 desktop/src-tauri/src/lib.rs                  |   1 +
 .../workflows/ui/WorkflowAuthorPicker.tsx     | 361 ++++++++++++++
 .../features/workflows/ui/WorkflowCard.tsx    |  20 +-
 .../features/workflows/ui/WorkflowDialog.tsx  |   7 +
 .../workflows/ui/WorkflowFormBuilder.tsx      |  34 +-
 .../workflows/ui/WorkflowMessagePicker.tsx    | 469 ++++++++++++++++++
 .../ui/WorkflowRichTriggerDescription.tsx     |  53 ++
 .../ui/WorkflowTriggerConditions.tsx          | 220 +++++++-
 .../features/workflows/ui/WorkflowsView.tsx   |   7 +
 .../ui/useWorkflowAuthorPresentation.ts       |  57 +++
 ...seWorkflowListAuthorPresentations.test.mjs |  30 ++
 .../ui/useWorkflowListAuthorPresentations.ts  |  60 +++
 ...eWorkflowListMessagePresentations.test.mjs |  67 +++
 .../ui/useWorkflowListMessagePresentations.ts |  92 ++++
 .../ui/useWorkflowTriggerPresentation.ts      |  70 +++
 .../ui/workflowAuthorCandidates.test.mjs      | 146 ++++++
 .../workflows/ui/workflowAuthorCandidates.ts  | 130 +++++
 .../ui/workflowConditionExpression.ts         |   4 +-
 .../workflows/ui/workflowDefinition.ts        |   2 +-
 .../ui/workflowMessageCandidates.test.mjs     | 218 ++++++++
 .../workflows/ui/workflowMessageCandidates.ts | 139 ++++++
 .../ui/workflowTriggerDescription.test.mjs    |  63 ++-
 .../ui/workflowTriggerDescription.ts          |  47 ++
 desktop/src/shared/api/tauri.ts               |   6 +-
 desktop/src/shared/api/tauriEvents.ts         |  14 +
 desktop/src/testing/e2eBridge.ts              |   9 +
 .../tests/e2e/workflow-local-controls.spec.ts | 355 ++++++++++++-
 29 files changed, 2761 insertions(+), 67 deletions(-)
 create mode 100644 desktop/src-tauri/src/commands/messages/event_batch.rs
 create mode 100644 desktop/src/features/workflows/ui/WorkflowAuthorPicker.tsx
 create mode 100644 desktop/src/features/workflows/ui/WorkflowMessagePicker.tsx
 create mode 100644 desktop/src/features/workflows/ui/WorkflowRichTriggerDescription.tsx
 create mode 100644 desktop/src/features/workflows/ui/useWorkflowAuthorPresentation.ts
 create mode 100644 desktop/src/features/workflows/ui/useWorkflowListAuthorPresentations.test.mjs
 create mode 100644 desktop/src/features/workflows/ui/useWorkflowListAuthorPresentations.ts
 create mode 100644 desktop/src/features/workflows/ui/useWorkflowListMessagePresentations.test.mjs
 create mode 100644 desktop/src/features/workflows/ui/useWorkflowListMessagePresentations.ts
 create mode 100644 desktop/src/features/workflows/ui/useWorkflowTriggerPresentation.ts
 create mode 100644 desktop/src/features/workflows/ui/workflowAuthorCandidates.test.mjs
 create mode 100644 desktop/src/features/workflows/ui/workflowAuthorCandidates.ts
 create mode 100644 desktop/src/features/workflows/ui/workflowMessageCandidates.test.mjs
 create mode 100644 desktop/src/features/workflows/ui/workflowMessageCandidates.ts
 create mode 100644 desktop/src/shared/api/tauriEvents.ts

diff --git a/desktop/src-tauri/src/commands/messages.rs b/desktop/src-tauri/src/commands/messages.rs
index 5de2d32b80..1e221b6bd1 100644
--- a/desktop/src-tauri/src/commands/messages.rs
+++ b/desktop/src-tauri/src/commands/messages.rs
@@ -396,23 +396,8 @@ pub async fn get_channel_messages_before(
     })
 }
 
-#[tauri::command]
-pub async fn get_event(event_id: String, state: State<'_, AppState>) -> Result<String, String> {
-    let events = query_relay(
-        &state,
-        &[serde_json::json!({
-            "ids": [event_id],
-            "kinds": [0, 1, 3, 5, 7, 9, 30078, 40002, 40003, 40008, 40099, 40100, 45001, 45003, buzz_core_pkg::kind::KIND_HUDDLE_STARTED],
-            "limit": 1
-        })],
-    )
-    .await?;
-
-    let ev = events
-        .first()
-        .ok_or_else(|| "event not found".to_string())?;
-    serde_json::to_string(ev).map_err(|e| format!("serialize event: {e}"))
-}
+mod event_batch;
+pub use event_batch::{get_event, get_events};
 
 // ── Writes ──────────────────────────────────────────────────────────────────
 
diff --git a/desktop/src-tauri/src/commands/messages/event_batch.rs b/desktop/src-tauri/src/commands/messages/event_batch.rs
new file mode 100644
index 0000000000..1bb5174868
--- /dev/null
+++ b/desktop/src-tauri/src/commands/messages/event_batch.rs
@@ -0,0 +1,128 @@
+use std::collections::HashSet;
+
+use tauri::State;
+
+use crate::{app_state::AppState, relay::query_relay};
+
+// The relay clamps a single filter to this many events. Keep exact-ID reads in
+// chunks so a large workflow list cannot silently lose late presentations.
+const EVENT_QUERY_CHUNK_SIZE: usize = 1_000;
+
+const GET_EVENT_KINDS: [u32; 15] = [
+    0,
+    1,
+    3,
+    5,
+    7,
+    9,
+    30078,
+    40002,
+    40003,
+    40008,
+    40099,
+    40100,
+    45001,
+    45003,
+    buzz_core_pkg::kind::KIND_HUDDLE_STARTED,
+];
+
+#[tauri::command]
+pub async fn get_event(event_id: String, state: State<'_, AppState>) -> Result<String, String> {
+    let events = query_relay(
+        &state,
+        &[serde_json::json!({
+            "ids": [event_id],
+            "kinds": GET_EVENT_KINDS,
+            "limit": 1
+        })],
+    )
+    .await?;
+
+    let event = events
+        .first()
+        .ok_or_else(|| "event not found".to_string())?;
+    serde_json::to_string(event).map_err(|error| format!("serialize event: {error}"))
+}
+
+/// Resolve many exact event IDs in relay-sized chunks. Callers still validate
+/// event kind, channel scope, and requested ID before using presentation data.
+fn normalized_event_id_chunks(event_ids: Vec<String>) -> Vec<Vec<String>> {
+    let mut seen_ids = HashSet::new();
+    let event_ids = event_ids
+        .into_iter()
+        .map(|event_id| event_id.trim().to_ascii_lowercase())
+        .filter(|event_id| event_id.len() == 64 && event_id.chars().all(|c| c.is_ascii_hexdigit()))
+        .filter(|event_id| seen_ids.insert(event_id.clone()))
+        .collect::<Vec<_>>();
+    event_ids
+        .chunks(EVENT_QUERY_CHUNK_SIZE)
+        .map(<[String]>::to_vec)
+        .collect()
+}
+
+#[tauri::command]
+pub async fn get_events(
+    event_ids: Vec<String>,
+    state: State<'_, AppState>,
+) -> Result<Vec<serde_json::Value>, String> {
+    let event_id_chunks = normalized_event_id_chunks(event_ids);
+    if event_id_chunks.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    let mut events_by_id = std::collections::HashMap::new();
+    for event_ids in event_id_chunks {
+        let events = query_relay(
+            &state,
+            &[serde_json::json!({
+                "ids": event_ids,
+                "kinds": GET_EVENT_KINDS,
+                "limit": event_ids.len()
+            })],
+        )
+        .await?;
+        for event in events {
+            events_by_id.entry(event.id).or_insert(event);
+        }
+    }
+
+    events_by_id
+        .into_values()
+        .map(|event| {
+            serde_json::to_value(event).map_err(|error| format!("serialize event: {error}"))
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn keeps_exact_relay_ceiling_in_one_chunk() {
+        let chunks = normalized_event_id_chunks(
+            (0..EVENT_QUERY_CHUNK_SIZE)
+                .map(|index| format!("{index:064x}"))
+                .collect(),
+        );
+
+        assert_eq!(chunks.len(), 1);
+        assert_eq!(chunks[0].len(), EVENT_QUERY_CHUNK_SIZE);
+    }
+
+    #[test]
+    fn normalizes_deduplicates_and_keeps_ids_beyond_relay_ceiling() {
+        let last_id = format!("{:064x}", EVENT_QUERY_CHUNK_SIZE);
+        let mut event_ids = (0..=EVENT_QUERY_CHUNK_SIZE)
+            .map(|index| format!("{index:064X}"))
+            .collect::<Vec<_>>();
+        event_ids.extend(["not-an-event-id".to_string(), format!(" {last_id} ")]);
+
+        let chunks = normalized_event_id_chunks(event_ids);
+
+        assert_eq!(chunks.iter().map(Vec::len).sum::<usize>(), 1_001);
+        assert_eq!(chunks.len(), 2);
+        assert_eq!(chunks[0].len(), EVENT_QUERY_CHUNK_SIZE);
+        assert_eq!(chunks[1], [last_id]);
+    }
+}
diff --git a/desktop/src-tauri/src/lib.rs b/desktop/src-tauri/src/lib.rs
index 428aa4d2a7..613040b809 100644
--- a/desktop/src-tauri/src/lib.rs
+++ b/desktop/src-tauri/src/lib.rs
@@ -652,6 +652,7 @@ pub fn run() {
             add_reaction,
             remove_reaction,
             get_event,
+            get_events,
             show_native_notification,
             #[cfg(target_os = "macos")]
             macos_notifications::take_pending_activations,
diff --git a/desktop/src/features/workflows/ui/WorkflowAuthorPicker.tsx b/desktop/src/features/workflows/ui/WorkflowAuthorPicker.tsx
new file mode 100644
index 0000000000..bcf0b209ff
--- /dev/null
+++ b/desktop/src/features/workflows/ui/WorkflowAuthorPicker.tsx
@@ -0,0 +1,361 @@
+import { Check, LoaderCircle, Search } from "lucide-react";
+import * as React from "react";
+
+import { useChannelMembersQuery } from "@/features/channels/hooks";
+import { useRelayMembersQuery } from "@/features/community-members/hooks";
+import {
+  useFlattenedUserSearchResults,
+  useInfiniteUserSearchQuery,
+  useUsersBatchQuery,
+} from "@/features/profile/hooks";
+import { resolveUserLabel } from "@/features/profile/lib/identity";
+import { cn } from "@/shared/lib/cn";
+import { truncatePubkey } from "@/shared/lib/pubkey";
+import { Input } from "@/shared/ui/input";
+import { UserAvatar } from "@/shared/ui/UserAvatar";
+import {
+  enrichAuthorCandidates,
+  filterAuthorCandidatePage,
+  mergeAuthorCandidateSources,
+  nextWorkflowAuthorIndex,
+  parseDirectAuthorInput,
+  type WorkflowAuthorCandidate,
+} from "./workflowAuthorCandidates";
+
+const PAGE_SIZE = 50;
+
+export function WorkflowAuthorPicker({
+  channelId,
+  disabled,
+  id,
+  onChange,
+  onEscape,
+  value,
+}: {
+  channelId?: string | null;
+  disabled?: boolean;
+  id: string;
+  onChange: (pubkey: string) => void;
+  onEscape?: () => void;
+  value: string;
+}) {
+  const pickerRef = React.useRef<HTMLDivElement>(null);
+  const optionRefs = React.useRef(new Map<string, HTMLButtonElement>());
+  const [query, setQuery] = React.useState("");
+  const [activeIndex, setActiveIndex] = React.useState<number | null>(null);
+  const [columnCount, setColumnCount] = React.useState(2);
+  const trimmedQuery = query.trim();
+  const deferredQuery = React.useDeferredValue(trimmedQuery);
+  const normalizedValue = parseDirectAuthorInput(value);
+  const channelMembersQuery = useChannelMembersQuery(channelId ?? null);
+  const relayMembersQuery = useRelayMembersQuery(true);
+  const directoryQuery = useInfiniteUserSearchQuery(deferredQuery, {
+    allowEmpty: true,
+    limit: PAGE_SIZE,
+  });
+  const directoryResults = useFlattenedUserSearchResults(directoryQuery.data);
+  const directPubkey = parseDirectAuthorInput(deferredQuery);
+
+  const baseCandidates = React.useMemo(
+    () =>
+      mergeAuthorCandidateSources([
+        normalizedValue ? [{ pubkey: normalizedValue }] : [],
+        directPubkey ? [{ pubkey: directPubkey }] : [],
+        channelMembersQuery.data ?? [],
+        relayMembersQuery.data ?? [],
+        directoryResults,
+      ]),
+    [
+      channelMembersQuery.data,
+      directPubkey,
+      directoryResults,
+      normalizedValue,
+      relayMembersQuery.data,
+    ],
+  );
+  const candidatePage = React.useMemo(
+    () =>
+      filterAuthorCandidatePage(
+        baseCandidates,
+        deferredQuery,
+        directPubkey,
+        PAGE_SIZE,
+      ),
+    [baseCandidates, deferredQuery, directPubkey],
+  );
+  const profileQuery = useUsersBatchQuery(
+    candidatePage.map(({ pubkey }) => pubkey),
+  );
+  const candidates = React.useMemo(
+    () =>
+      enrichAuthorCandidates(candidatePage, profileQuery.data?.profiles ?? {}),
+    [candidatePage, profileQuery.data?.profiles],
+  );
+  const visibleCandidates = candidates;
+  const listId = `${id}-list`;
+
+  React.useEffect(() => {
+    if (activeIndex !== null && activeIndex >= visibleCandidates.length) {
+      setActiveIndex(
+        visibleCandidates.length > 0 ? visibleCandidates.length - 1 : null,
+      );
+    }
+  }, [activeIndex, visibleCandidates.length]);
+
+  React.useEffect(() => {
+    const picker = pickerRef.current;
+    if (!picker) return;
+    const updateColumnCount = () =>
+      setColumnCount(picker.clientWidth >= 544 ? 3 : 2);
+    updateColumnCount();
+    const observer = new ResizeObserver(updateColumnCount);
+    observer.observe(picker);
+    return () => observer.disconnect();
+  }, []);
+
+  React.useEffect(() => {
+    if (activeIndex === null) return;
+    const candidate = visibleCandidates[activeIndex];
+    if (!candidate) return;
+    optionRefs.current
+      .get(candidate.pubkey)
+      ?.scrollIntoView({ block: "nearest", inline: "nearest" });
+  }, [activeIndex, visibleCandidates]);
+
+  const loading =
+    (channelMembersQuery.isLoading ||
+      relayMembersQuery.isLoading ||
+      directoryQuery.isLoading) &&
+    visibleCandidates.length === 0;
+  const failed =
+    channelMembersQuery.isError ||
+    relayMembersQuery.isError ||
+    directoryQuery.isError;
+
+  function moveActive(delta: number) {
+    setActiveIndex((current) =>
+      nextWorkflowAuthorIndex(current, delta, visibleCandidates.length),
+    );
+  }
+
+  return (
+    <div
+      className="flex h-full min-h-0 flex-1 flex-col overflow-hidden rounded-lg border border-border/70 bg-background/35"
+      data-testid="workflow-author-picker"
+      ref={pickerRef}
+    >
+      <div className="relative shrink-0 border-b border-border/70">
+        <Search className="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
+        <Input
+          aria-activedescendant={
+            activeIndex !== null && visibleCandidates[activeIndex]
+              ? `${listId}-${visibleCandidates[activeIndex].pubkey}`
+              : undefined
+          }
+          aria-controls={listId}
+          aria-label="Search authors or paste a public key"
+          aria-expanded="true"
+          autoCapitalize="none"
+          autoComplete="off"
+          autoCorrect="off"
+          className="h-11 rounded-none border-0 bg-transparent pl-9 focus-visible:ring-0"
+          data-workflow-filter-picker-search="true"
+          disabled={disabled}
+          id={id}
+          onChange={(event) => {
+            setQuery(event.target.value);
+            setActiveIndex(null);
+          }}
+          onKeyDown={(event) => {
+            const currentQuery = event.currentTarget.value.trim();
+            const delta =
+              event.key === "ArrowDown"
+                ? columnCount
+                : event.key === "ArrowUp"
+                  ? -columnCount
+                  : event.key === "ArrowRight"
+                    ? 1
+                    : event.key === "ArrowLeft"
+                      ? -1
+                      : 0;
+            if (delta) {
+              event.preventDefault();
+              moveActive(delta);
+            } else if (
+              event.key === "Enter" &&
+              currentQuery === deferredQuery &&
+              visibleCandidates[activeIndex ?? 0]
+            ) {
+              event.preventDefault();
+              const candidate = visibleCandidates[activeIndex ?? 0];
+              onChange(
+                candidate.pubkey === normalizedValue ? "" : candidate.pubkey,
+              );
+            } else if (event.key === "Escape") {
+              event.preventDefault();
+              event.stopPropagation();
+              if (query) {
+                setQuery("");
+                setActiveIndex(null);
+              } else {
+                onEscape?.();
+              }
+            }
+          }}
+          placeholder="Search people or paste a public key…"
+          role="combobox"
+          spellCheck={false}
+          value={query}
+        />
+      </div>
+
+      <div
+        aria-label="Authors"
+        className={cn(
+          "grid min-h-0 flex-1 gap-2 overflow-y-auto overscroll-contain p-2",
+          columnCount === 3 ? "grid-cols-3" : "grid-cols-2",
+        )}
+        data-testid="workflow-author-picker-results"
+        id={listId}
+        onScroll={(event) => {
+          const list = event.currentTarget;
+          if (
+            list.scrollHeight - list.scrollTop - list.clientHeight < 64 &&
+            directoryQuery.hasNextPage &&
+            !directoryQuery.isFetchingNextPage
+          ) {
+            void directoryQuery.fetchNextPage();
+          }
+        }}
+        role="listbox"
+      >
+        {visibleCandidates.map((candidate, index) => (
+          <AuthorOption
+            active={activeIndex !== null && index === activeIndex}
+            candidate={candidate}
+            disabled={disabled}
+            id={`${listId}-${candidate.pubkey}`}
+            key={candidate.pubkey}
+            onSelect={() => {
+              setActiveIndex(null);
+              onChange(
+                candidate.pubkey === normalizedValue ? "" : candidate.pubkey,
+              );
+            }}
+            optionRef={(node) => {
+              if (node) optionRefs.current.set(candidate.pubkey, node);
+              else optionRefs.current.delete(candidate.pubkey);
+            }}
+            selected={candidate.pubkey === normalizedValue}
+          />
+        ))}
+        {loading ? (
+          <p
+            className="col-span-full flex items-center justify-center gap-2 px-3 py-8 text-sm text-muted-foreground"
+            role="status"
+          >
+            <LoaderCircle className="h-4 w-4 animate-spin" /> Loading authors…
+          </p>
+        ) : visibleCandidates.length === 0 ? (
+          <p className="col-span-full px-3 py-8 text-center text-sm text-muted-foreground">
+            {failed ? "Couldn’t load authors." : "No authors found."}
+          </p>
+        ) : null}
+        {failed ? (
+          <button
+            className="col-span-full rounded-md px-3 py-2 text-xs font-medium text-muted-foreground hover:bg-muted/45 hover:text-foreground"
+            onClick={() => {
+              void channelMembersQuery.refetch();
+              void relayMembersQuery.refetch();
+              void directoryQuery.refetch();
+            }}
+            type="button"
+          >
+            Couldn’t load all authors. Retry
+          </button>
+        ) : null}
+        {directoryQuery.hasNextPage ? (
+          <button
+            className="col-span-full rounded-md px-3 py-2 text-xs font-medium text-muted-foreground hover:bg-muted/45 hover:text-foreground"
+            disabled={disabled || directoryQuery.isFetchingNextPage}
+            onClick={() => void directoryQuery.fetchNextPage()}
+            type="button"
+          >
+            {directoryQuery.isFetchingNextPage
+              ? "Loading more…"
+              : "Load more authors"}
+          </button>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+function AuthorOption({
+  active,
+  candidate,
+  disabled,
+  id,
+  onSelect,
+  optionRef,
+  selected,
+}: {
+  active: boolean;
+  candidate: WorkflowAuthorCandidate;
+  disabled?: boolean;
+  id: string;
+  onSelect: () => void;
+  optionRef: (node: HTMLButtonElement | null) => void;
+  selected: boolean;
+}) {
+  const label = resolveUserLabel({
+    fallbackName: candidate.displayName,
+    profiles: {
+      [candidate.pubkey]: {
+        displayName: candidate.displayName,
+        avatarUrl: candidate.avatarUrl,
+        nip05Handle: candidate.nip05Handle,
+        ownerPubkey: candidate.ownerPubkey,
+        isAgent: candidate.isAgent,
+      },
+    },
+    pubkey: candidate.pubkey,
+  });
+  return (
+    <button
+      aria-selected={selected}
+      className={cn(
+        "relative flex min-h-24 min-w-0 flex-col items-center justify-center gap-2 rounded-lg border bg-muted/20 p-3 text-center transition-colors",
+        selected
+          ? "border-primary bg-primary/10"
+          : "border-border hover:bg-accent",
+        active && "ring-1 ring-ring",
+      )}
+      disabled={disabled}
+      id={id}
+      onClick={onSelect}
+      ref={optionRef}
+      role="option"
+      tabIndex={-1}
+      type="button"
+    >
+      <UserAvatar
+        avatarUrl={candidate.avatarUrl}
+        displayName={label}
+        size="md"
+      />
+      <span className="min-w-0 max-w-full">
+        <span className="block truncate text-sm font-medium">{label}</span>
+        <span className="block truncate text-xs text-muted-foreground">
+          {truncatePubkey(candidate.pubkey)}
+        </span>
+      </span>
+      <Check
+        className={cn(
+          "absolute right-2 top-2 h-4 w-4",
+          !selected && "opacity-0",
+        )}
+      />
+    </button>
+  );
+}
diff --git a/desktop/src/features/workflows/ui/WorkflowCard.tsx b/desktop/src/features/workflows/ui/WorkflowCard.tsx
index 48ce8d2db6..8556424f87 100644
--- a/desktop/src/features/workflows/ui/WorkflowCard.tsx
+++ b/desktop/src/features/workflows/ui/WorkflowCard.tsx
@@ -24,14 +24,20 @@ import {
   getWorkflowActionTiles,
   getWorkflowCardLabel,
   getWorkflowTriggerEmoji,
+  getWorkflowTriggerConfig,
   getWorkflowTriggerType,
 } from "./workflowDefinition";
 import { StatusEmoji } from "@/features/user-status/ui/StatusEmoji";
+import type { WorkflowCardAuthorPresentation } from "./useWorkflowListAuthorPresentations";
+import type { WorkflowMessagePresentation } from "./useWorkflowListMessagePresentations";
+import { workflowTriggerDescription } from "./workflowTriggerDescription";
 
 type WorkflowCardProps = {
   workflow: Workflow;
+  authorPresentation?: WorkflowCardAuthorPresentation;
   channelName?: string;
   isTogglingEnabled?: boolean;
+  messagePresentation?: WorkflowMessagePresentation;
   onView: (workflow: Workflow) => void;
   onTrigger: (workflowId: string) => void;
   onToggleEnabled: (workflow: Workflow) => void;
@@ -189,8 +195,10 @@ function ActionTileStack({
 
 export function WorkflowCard({
   workflow,
+  authorPresentation,
   channelName,
   isTogglingEnabled = false,
+  messagePresentation,
   onView,
   onTrigger,
   onToggleEnabled,
@@ -201,7 +209,17 @@ export function WorkflowCard({
   const [triggerAnimationSequence, setTriggerAnimationSequence] =
     React.useState(0);
   const isEnabled = getWorkflowEnabled(workflow.definition);
-  const cardLabel = getWorkflowCardLabel(workflow.definition);
+  const configuredTrigger = getWorkflowTriggerConfig(workflow.definition);
+  const cardLabel = getWorkflowCardLabel(workflow.definition, {
+    triggerDescription: configuredTrigger
+      ? workflowTriggerDescription(configuredTrigger, {
+          authorLabel: authorPresentation?.label ?? undefined,
+          authorLoading: authorPresentation?.loading,
+          messageLabel: messagePresentation?.messageLabel ?? undefined,
+          messageLoading: messagePresentation?.messageLoading,
+        })
+      : undefined,
+  });
   const triggerType = getWorkflowTriggerType(workflow.definition);
   const actionTiles = getWorkflowActionTiles(workflow.definition);
   const triggerEmoji = getWorkflowTriggerEmoji(workflow.definition);
diff --git a/desktop/src/features/workflows/ui/WorkflowDialog.tsx b/desktop/src/features/workflows/ui/WorkflowDialog.tsx
index 3f8655a3aa..198e0fe91c 100644
--- a/desktop/src/features/workflows/ui/WorkflowDialog.tsx
+++ b/desktop/src/features/workflows/ui/WorkflowDialog.tsx
@@ -557,6 +557,13 @@ export function WorkflowDialog({
         <DialogContent
           className="flex h-[88vh] max-h-[88vh] w-[calc(100vw-2rem)] max-w-6xl flex-col gap-0 overflow-hidden p-0"
           onEscapeKeyDown={(event) => {
+            if (
+              event.target instanceof HTMLElement &&
+              event.target.closest("[data-workflow-filter-picker-search]")
+            ) {
+              event.preventDefault();
+              return;
+            }
             if (formBuilderRef.current?.closeInspector()) {
               event.preventDefault();
               event.stopPropagation();
diff --git a/desktop/src/features/workflows/ui/WorkflowFormBuilder.tsx b/desktop/src/features/workflows/ui/WorkflowFormBuilder.tsx
index 58e4b4a960..8ac97402aa 100644
--- a/desktop/src/features/workflows/ui/WorkflowFormBuilder.tsx
+++ b/desktop/src/features/workflows/ui/WorkflowFormBuilder.tsx
@@ -30,8 +30,10 @@ import { Switch } from "@/shared/ui/switch";
 import { Textarea } from "@/shared/ui/textarea";
 import { reactionConditionValue } from "./workflowReactionCondition";
 import { WorkflowTriggerConditions } from "./WorkflowTriggerConditions";
+import { WorkflowRichTriggerDescription } from "./WorkflowRichTriggerDescription";
+import { useWorkflowTriggerPresentation } from "./useWorkflowTriggerPresentation";
+import { compactWorkflowTriggerDescription } from "./workflowTriggerDescription";
 import { workflowStepDescription } from "./workflowStepDescription";
-import { workflowTriggerDescription } from "./workflowTriggerDescription";
 import { WorkflowScheduleFields } from "./WorkflowScheduleFields";
 import { WorkflowStepCard } from "./WorkflowStepCard";
 import {
@@ -67,12 +69,14 @@ function TriggerConfigFields({
   trigger,
   onConditionDraftsChange,
   onUpdate,
+  workflowChannelId,
 }: {
   conditionDrafts: ParsedConditionExpression[] | null;
   disabled?: boolean;
   trigger: TriggerConfig;
   onConditionDraftsChange: (drafts: ParsedConditionExpression[] | null) => void;
   onUpdate: (trigger: TriggerConfig) => void;
+  workflowChannelId?: string | null;
 }) {
   switch (trigger.on) {
     case "message_posted":
@@ -94,6 +98,7 @@ function TriggerConfigFields({
           }
           triggerType={trigger.on}
           value={reactionConditionValue(trigger)}
+          workflowChannelId={workflowChannelId}
         />
       );
     case "webhook":
@@ -220,7 +225,7 @@ function WorkflowNode({
   terminal,
   title,
 }: {
-  description: string;
+  description: React.ReactNode;
   disabled?: boolean;
   icon?: React.ReactNode;
   label: string;
@@ -614,10 +619,23 @@ export const WorkflowFormBuilder = React.forwardRef<
       )
       ?.value.trim();
   }, [formState.trigger]);
-  const triggerDescription = workflowTriggerDescription(formState.trigger);
-  const visibleTriggerDescription = triggerEmoji
-    ? "Reaction added"
-    : triggerDescription;
+  const triggerPresentation = useWorkflowTriggerPresentation(
+    formState.trigger,
+    workflowChannelId,
+  );
+  const triggerDescription = triggerPresentation.description;
+  const compactTriggerDescription = compactWorkflowTriggerDescription(
+    triggerDescription,
+    triggerEmoji,
+  );
+  const visibleTriggerDescription = (
+    <WorkflowRichTriggerDescription
+      avatarUrl={triggerPresentation.avatarUrl}
+      description={compactTriggerDescription}
+      label={triggerPresentation.label}
+      loading={triggerPresentation.loading}
+    />
+  );
   const TriggerIcon = {
     diff_posted: GitPullRequest,
     message_posted: MessageSquare,
@@ -889,6 +907,7 @@ export const WorkflowFormBuilder = React.forwardRef<
                           >
                             <motion.div
                               animate="center"
+                              className="h-full min-h-0"
                               custom={selectionDirection}
                               exit="exit"
                               initial="enter"
@@ -905,7 +924,7 @@ export const WorkflowFormBuilder = React.forwardRef<
                               variants={inspectorContentVariants}
                             >
                               {selectedNode.type === "trigger" ? (
-                                <div>
+                                <div className="h-full min-h-0">
                                   <TriggerConfigFields
                                     conditionDrafts={triggerConditionDrafts}
                                     disabled={disabled}
@@ -916,6 +935,7 @@ export const WorkflowFormBuilder = React.forwardRef<
                                       updateFormState({ ...formState, trigger })
                                     }
                                     trigger={formState.trigger}
+                                    workflowChannelId={workflowChannelId}
                                   />
                                 </div>
                               ) : selectedStep ? (
diff --git a/desktop/src/features/workflows/ui/WorkflowMessagePicker.tsx b/desktop/src/features/workflows/ui/WorkflowMessagePicker.tsx
new file mode 100644
index 0000000000..6639d85b0f
--- /dev/null
+++ b/desktop/src/features/workflows/ui/WorkflowMessagePicker.tsx
@@ -0,0 +1,469 @@
+import { useInfiniteQuery, useQueries, useQuery } from "@tanstack/react-query";
+import { Check, LoaderCircle, Search } from "lucide-react";
+import * as React from "react";
+
+import { parseChannelWindowResponse } from "@/features/messages/lib/channelWindowResponse";
+import { useUsersBatchQuery } from "@/features/profile/hooks";
+import {
+  resolveUserLabel,
+  type UserProfileLookup,
+} from "@/features/profile/lib/identity";
+import { useSearchMessagesQuery } from "@/features/search/hooks";
+import { getChannelWindowEvents } from "@/shared/api/channelWindow";
+import { getEventById } from "@/shared/api/tauri";
+import type { ChannelPageCursor } from "@/shared/api/types";
+import { cn } from "@/shared/lib/cn";
+import { Input } from "@/shared/ui/input";
+import { UserAvatar } from "@/shared/ui/UserAvatar";
+import {
+  mergeMessageCandidateSources,
+  normalizeMessageEventId,
+  type WorkflowMessageCandidate,
+  validatedWorkflowMessageCandidate,
+  validateWorkflowMessageSearchResults,
+} from "./workflowMessageCandidates";
+
+const PAGE_SIZE = 25;
+
+function truncateContent(content: string | null): string {
+  const normalized = content?.trim().replaceAll(/\s+/g, " ") ?? "";
+  if (!normalized) return "No message body";
+  return normalized.length > 120
+    ? `${normalized.slice(0, 117)}...`
+    : normalized;
+}
+
+function formatTimestamp(unixSeconds: number | null): string | null {
+  if (unixSeconds === null) return null;
+  return new Intl.DateTimeFormat(undefined, {
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+  }).format(new Date(unixSeconds * 1_000));
+}
+
+export function WorkflowMessagePicker({
+  channelId,
+  disabled,
+  id,
+  onChange,
+  onEscape,
+  value,
+}: {
+  channelId?: string | null;
+  disabled?: boolean;
+  id: string;
+  onChange: (messageId: string) => void;
+  onEscape?: () => void;
+  value: string;
+}) {
+  const optionRefs = React.useRef(new Map<string, HTMLButtonElement>());
+  const [query, setQuery] = React.useState("");
+  const [activeIndex, setActiveIndex] = React.useState<number | null>(null);
+  const trimmedQuery = query.trim();
+  const deferredQuery = React.useDeferredValue(trimmedQuery);
+  const normalizedQuery = deferredQuery.toLowerCase();
+  const selectedId = normalizeMessageEventId(value);
+  const directId = normalizeMessageEventId(query);
+  const lookupId = directId ?? selectedId;
+
+  const historyQuery = useInfiniteQuery({
+    enabled: Boolean(channelId),
+    initialPageParam: null as ChannelPageCursor | null,
+    queryKey: ["workflow-message-picker", channelId],
+    queryFn: async ({ pageParam }) => {
+      if (!channelId) throw new Error("Choose a channel first.");
+      return parseChannelWindowResponse(
+        await getChannelWindowEvents(channelId, pageParam, PAGE_SIZE),
+        channelId,
+        pageParam,
+      );
+    },
+    getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
+    staleTime: 30_000,
+  });
+  const searchQuery = useSearchMessagesQuery(deferredQuery, {
+    channelId: channelId ?? undefined,
+    enabled: Boolean(channelId && normalizedQuery && !directId),
+    limit: 30,
+    minimumQueryLength: 1,
+  });
+  const exactQuery = useQuery({
+    enabled: Boolean(channelId && lookupId),
+    queryKey: ["workflow-message-picker-exact", channelId, lookupId],
+    queryFn: () => getEventById(lookupId ?? ""),
+    retry: false,
+    staleTime: 60_000,
+  });
+
+  const selectedFallback = selectedId
+    ? [{ id: selectedId, pubkey: null, content: null, createdAt: null }]
+    : [];
+  const directFallback = directId
+    ? [{ id: directId, pubkey: null, content: null, createdAt: null }]
+    : [];
+  const historyCandidates = React.useMemo(
+    () =>
+      (historyQuery.data?.pages ?? []).flatMap((page) =>
+        page.rows.flatMap(({ event }) => {
+          const candidate = channelId
+            ? validatedWorkflowMessageCandidate(event, { channelId })
+            : null;
+          return candidate ? [candidate] : [];
+        }),
+      ),
+    [channelId, historyQuery.data?.pages],
+  );
+  const searchHitIds = React.useMemo(
+    () => [
+      ...new Set(
+        (searchQuery.data?.hits ?? []).flatMap((hit) => {
+          const eventId = normalizeMessageEventId(hit.eventId);
+          return eventId ? [eventId] : [];
+        }),
+      ),
+    ],
+    [searchQuery.data?.hits],
+  );
+  const searchEventQueries = useQueries({
+    queries: searchHitIds.map((eventId) => ({
+      enabled: Boolean(channelId),
+      queryKey: ["workflow-message-picker-search-event", channelId, eventId],
+      queryFn: () => getEventById(eventId),
+      retry: false,
+      staleTime: 60_000,
+    })),
+  });
+  const searchCandidates = validateWorkflowMessageSearchResults(
+    searchHitIds.map((requestedId, index) => ({
+      requestedId,
+      event: searchEventQueries[index]?.data,
+    })),
+    channelId ?? "",
+  );
+  const exactCandidate = React.useMemo(() => {
+    if (!channelId || !lookupId) return null;
+    return validatedWorkflowMessageCandidate(exactQuery.data, {
+      channelId,
+      requestedId: lookupId,
+    });
+  }, [channelId, exactQuery.data, lookupId]);
+  const allCandidates = React.useMemo(() => {
+    // Preserve the relay-provided history/search order. Exact lookups and raw-ID
+    // fallbacks only fill gaps; selecting an existing row must not move it.
+    return mergeMessageCandidateSources([
+      historyCandidates,
+      searchCandidates,
+      exactCandidate ? [exactCandidate] : [],
+      selectedFallback,
+      directFallback,
+    ]);
+  }, [
+    directFallback,
+    exactCandidate,
+    historyCandidates,
+    searchCandidates,
+    selectedFallback,
+  ]);
+  const visibleCandidates = React.useMemo(() => {
+    if (directId) return allCandidates.filter(({ id }) => id === directId);
+    if (!normalizedQuery) return allCandidates;
+    return allCandidates.filter(
+      (candidate) =>
+        candidate.id.includes(normalizedQuery) ||
+        candidate.content?.toLowerCase().includes(normalizedQuery),
+    );
+  }, [allCandidates, directId, normalizedQuery]);
+  const profilePubkeys = React.useMemo(
+    () => [
+      ...new Set(
+        visibleCandidates.flatMap(({ pubkey }) => (pubkey ? [pubkey] : [])),
+      ),
+    ],
+    [visibleCandidates],
+  );
+  const profilesQuery = useUsersBatchQuery(profilePubkeys);
+  const listId = `${id}-list`;
+
+  React.useEffect(() => {
+    if (activeIndex !== null && activeIndex >= visibleCandidates.length) {
+      setActiveIndex(
+        visibleCandidates.length > 0 ? visibleCandidates.length - 1 : null,
+      );
+    }
+  }, [activeIndex, visibleCandidates.length]);
+  React.useEffect(() => {
+    if (activeIndex === null) return;
+    const candidate = visibleCandidates[activeIndex];
+    if (!candidate) return;
+    optionRefs.current
+      .get(candidate.id)
+      ?.scrollIntoView({ block: "nearest", inline: "nearest" });
+  }, [activeIndex, visibleCandidates]);
+
+  const searchEventsFetching = searchEventQueries.some(
+    ({ isFetching }) => isFetching,
+  );
+  const searchEventsFailed = searchEventQueries.some(({ isError }) => isError);
+  const loading =
+    (historyQuery.isLoading ||
+      searchQuery.isFetching ||
+      searchEventsFetching ||
+      exactQuery.isFetching) &&
+    visibleCandidates.length === 0;
+  const failed =
+    historyQuery.isError ||
+    searchQuery.isError ||
+    searchEventsFailed ||
+    exactQuery.isError;
+  const invalidDirectResult = Boolean(
+    directId && lookupId === directId && exactQuery.data && !exactCandidate,
+  );
+
+  return (
+    <div
+      className="flex h-full min-h-0 flex-1 flex-col overflow-hidden rounded-lg border border-border/70 bg-background/35"
+      data-testid="workflow-message-picker"
+    >
+      <div className="relative shrink-0 border-b border-border/70">
+        <Search className="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
+        <Input
+          aria-activedescendant={
+            activeIndex !== null && visibleCandidates[activeIndex]
+              ? `${listId}-${visibleCandidates[activeIndex].id}`
+              : undefined
+          }
+          aria-controls={listId}
+          aria-label="Search messages or paste a message ID"
+          aria-expanded="true"
+          autoCapitalize="none"
+          autoComplete="off"
+          autoCorrect="off"
+          className="h-11 rounded-none border-0 bg-transparent pl-9 focus-visible:ring-0"
+          data-workflow-filter-picker-search="true"
+          disabled={disabled || !channelId}
+          id={id}
+          onChange={(event) => {
+            setQuery(event.target.value);
+            setActiveIndex(null);
+          }}
+          onKeyDown={(event) => {
+            const currentQuery = event.currentTarget.value.trim();
+            if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+              event.preventDefault();
+              if (visibleCandidates.length > 0) {
+                setActiveIndex((current) => {
+                  const startingIndex = current ?? -1;
+                  return (
+                    (startingIndex +
+                      (event.key === "ArrowDown" ? 1 : -1) +
+                      visibleCandidates.length) %
+                    visibleCandidates.length
+                  );
+                });
+              }
+            } else if (event.key === "Enter") {
+              const currentDirectId = normalizeMessageEventId(currentQuery);
+              if (currentQuery !== deferredQuery && !currentDirectId) return;
+              const candidate = currentDirectId
+                ? allCandidates.find(({ id }) => id === currentDirectId)
+                : visibleCandidates[activeIndex ?? 0];
+              if (!candidate) return;
+              event.preventDefault();
+              if (invalidDirectResult) return;
+              onChange(candidate.id === selectedId ? "" : candidate.id);
+            } else if (event.key === "Escape") {
+              event.preventDefault();
+              event.stopPropagation();
+              if (query) {
+                setQuery("");
+                setActiveIndex(null);
+              } else {
+                onEscape?.();
+              }
+            }
+          }}
+          placeholder={
+            channelId
+              ? "Search messages or paste a message ID…"
+              : "Choose a channel first"
+          }
+          role="combobox"
+          spellCheck={false}
+          value={query}
+        />
+        {historyQuery.isFetching ||
+        searchQuery.isFetching ||
+        searchEventsFetching ||
+        exactQuery.isFetching ? (
+          <LoaderCircle
+            aria-label="Loading messages"
+            className="absolute right-3 top-1/2 h-4 w-4 -translate-y-1/2 animate-spin text-muted-foreground"
+          />
+        ) : null}
+      </div>
+      {invalidDirectResult ? (
+        <p className="shrink-0 border-b border-border/70 px-3 py-2 text-xs text-destructive">
+          That message is not available in this channel.
+        </p>
+      ) : null}
+      <div
+        aria-label="Messages"
+        className="min-h-0 flex-1 space-y-1 overflow-y-auto overscroll-contain p-2"
+        data-testid="workflow-message-picker-results"
+        id={listId}
+        onScroll={(event) => {
+          const list = event.currentTarget;
+          if (
+            !normalizedQuery &&
+            list.scrollHeight - list.scrollTop - list.clientHeight < 64 &&
+            historyQuery.hasNextPage &&
+            !historyQuery.isFetchingNextPage
+          ) {
+            void historyQuery.fetchNextPage();
+          }
+        }}
+        role="listbox"
+      >
+        {visibleCandidates.map((candidate, index) => (
+          <MessageOption
+            active={activeIndex !== null && index === activeIndex}
+            candidate={candidate}
+            disabled={disabled}
+            id={`${listId}-${candidate.id}`}
+            key={candidate.id}
+            onSelect={() => {
+              setActiveIndex(null);
+              if (!invalidDirectResult) {
+                onChange(candidate.id === selectedId ? "" : candidate.id);
+              }
+            }}
+            optionRef={(node) => {
+              if (node) optionRefs.current.set(candidate.id, node);
+              else optionRefs.current.delete(candidate.id);
+            }}
+            profiles={profilesQuery.data?.profiles}
+            selected={candidate.id === selectedId}
+          />
+        ))}
+        {loading ? (
+          <p
+            className="flex items-center justify-center gap-2 px-3 py-8 text-sm text-muted-foreground"
+            role="status"
+          >
+            <LoaderCircle className="h-4 w-4 animate-spin" /> Loading messages…
+          </p>
+        ) : visibleCandidates.length === 0 ? (
+          <p className="px-3 py-8 text-center text-sm text-muted-foreground">
+            {failed
+              ? "Couldn’t load messages."
+              : normalizedQuery
+                ? "No messages found."
+                : "No messages yet."}
+          </p>
+        ) : null}
+        {failed ? (
+          <button
+            className="w-full rounded-md px-3 py-2 text-xs font-medium text-muted-foreground hover:bg-muted/45 hover:text-foreground"
+            onClick={() => {
+              void historyQuery.refetch();
+              void searchQuery.refetch();
+              for (const searchEventQuery of searchEventQueries) {
+                void searchEventQuery.refetch();
+              }
+              void exactQuery.refetch();
+            }}
+            type="button"
+          >
+            Couldn’t load all messages. Retry
+          </button>
+        ) : null}
+        {!normalizedQuery && historyQuery.hasNextPage ? (
+          <button
+            className="w-full rounded-md px-3 py-2 text-xs font-medium text-muted-foreground hover:bg-muted/45 hover:text-foreground"
+            disabled={disabled || historyQuery.isFetchingNextPage}
+            onClick={() => void historyQuery.fetchNextPage()}
+            type="button"
+          >
+            {historyQuery.isFetchingNextPage
+              ? "Loading older messages…"
+              : "Load older messages"}
+          </button>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+function MessageOption({
+  active,
+  candidate,
+  disabled,
+  id,
+  onSelect,
+  optionRef,
+  profiles,
+  selected,
+}: {
+  active: boolean;
+  candidate: WorkflowMessageCandidate;
+  disabled?: boolean;
+  id: string;
+  onSelect: () => void;
+  optionRef: (node: HTMLButtonElement | null) => void;
+  profiles?: UserProfileLookup;
+  selected: boolean;
+}) {
+  const author = candidate.pubkey
+    ? resolveUserLabel({ profiles, pubkey: candidate.pubkey })
+    : "Selected message";
+  const profile = candidate.pubkey
+    ? profiles?.[candidate.pubkey.toLowerCase()]
+    : undefined;
+  const timestamp = formatTimestamp(candidate.createdAt);
+  return (
+    <button
+      aria-selected={selected}
+      className={cn(
+        "relative flex min-w-0 w-full items-start gap-2.5 overflow-hidden rounded-md border px-3 py-2.5 text-left transition-colors",
+        selected
+          ? "border-foreground/40 bg-muted/70"
+          : "border-transparent hover:border-border hover:bg-muted/45",
+        active && "ring-1 ring-ring",
+      )}
+      disabled={disabled}
+      id={id}
+      onClick={onSelect}
+      ref={optionRef}
+      role="option"
+      tabIndex={-1}
+      type="button"
+    >
+      {candidate.pubkey ? (
+        <UserAvatar
+          avatarUrl={profile?.avatarUrl ?? null}
+          displayName={author}
+          size="sm"
+        />
+      ) : null}
+      <span className="min-w-0 flex-1">
+        <span className="flex items-center gap-2 text-xs text-muted-foreground">
+          <span className="truncate font-medium text-foreground">{author}</span>
+          {timestamp ? (
+            <span className="ml-auto shrink-0">{timestamp}</span>
+          ) : null}
+        </span>
+        <span className="mt-1 block min-w-0 break-words text-sm leading-5 text-foreground [overflow-wrap:anywhere]">
+          {truncateContent(candidate.content)}
+        </span>
+        <span className="mt-1 block font-mono text-2xs text-muted-foreground">
+          {candidate.id.slice(0, 12)}…{candidate.id.slice(-8)}
+        </span>
+      </span>
+      <Check
+        className={cn("mt-1 h-4 w-4 shrink-0", !selected && "opacity-0")}
+      />
+    </button>
+  );
+}
diff --git a/desktop/src/features/workflows/ui/WorkflowRichTriggerDescription.tsx b/desktop/src/features/workflows/ui/WorkflowRichTriggerDescription.tsx
new file mode 100644
index 0000000000..50eb5ef672
--- /dev/null
+++ b/desktop/src/features/workflows/ui/WorkflowRichTriggerDescription.tsx
@@ -0,0 +1,53 @@
+import { LoaderCircle } from "lucide-react";
+
+import { UserAvatar } from "@/shared/ui/UserAvatar";
+import { splitWorkflowAuthorDescription } from "./workflowTriggerDescription";
+
+export function WorkflowRichTriggerDescription({
+  avatarUrl,
+  description,
+  label,
+  loading,
+}: {
+  avatarUrl?: string | null;
+  description: string;
+  label?: string | null;
+  loading?: boolean;
+}) {
+  if (loading) {
+    return (
+      <span className="flex min-w-0 items-center gap-1.5">
+        <span className="truncate">{description}</span>
+        <LoaderCircle
+          aria-label="Loading author"
+          className="h-3.5 w-3.5 shrink-0 animate-spin"
+          role="status"
+        />
+      </span>
+    );
+  }
+
+  const segments = label
+    ? splitWorkflowAuthorDescription(description, label)
+    : null;
+  if (!label || !segments) return description;
+
+  const { prefix, suffix } = segments;
+  return (
+    <span className="flex min-w-0 items-center gap-1.5">
+      {prefix ? <span className="shrink-0">{prefix}</span> : null}
+      <UserAvatar
+        avatarUrl={avatarUrl ?? null}
+        className="h-4 w-4"
+        displayName={label}
+        fallbackDelayMs={0}
+        size="xs"
+        testId="workflow-trigger-author-avatar"
+      />
+      <span className="min-w-0 truncate">
+        {label}
+        {suffix ? ` ${suffix}` : ""}
+      </span>
+    </span>
+  );
+}
diff --git a/desktop/src/features/workflows/ui/WorkflowTriggerConditions.tsx b/desktop/src/features/workflows/ui/WorkflowTriggerConditions.tsx
index 39caec253a..78f6e30606 100644
--- a/desktop/src/features/workflows/ui/WorkflowTriggerConditions.tsx
+++ b/desktop/src/features/workflows/ui/WorkflowTriggerConditions.tsx
@@ -3,8 +3,12 @@ import * as React from "react";
 
 import { cn } from "@/shared/lib/cn";
 import { Input } from "@/shared/ui/input";
+import { UserAvatar } from "@/shared/ui/UserAvatar";
 import { Tabs, TabsList, TabsTrigger } from "@/shared/ui/tabs";
+import { WorkflowAuthorPicker } from "./WorkflowAuthorPicker";
 import { WorkflowEmojiField } from "./WorkflowEmojiField";
+import { WorkflowMessagePicker } from "./WorkflowMessagePicker";
+import { useWorkflowTriggerPresentation } from "./useWorkflowTriggerPresentation";
 import { FieldLabel } from "./workflowFormPrimitives";
 import {
   buildConditionExpressions,
@@ -45,12 +49,81 @@ function compact(value: string): string {
     : `${trimmed.slice(0, 11)}…${trimmed.slice(-6)}`;
 }
 
+function fieldUsesFullHeightPicker(field: string): boolean {
+  return field === "trigger_author" || field === "trigger_message_id";
+}
+
 function fieldPlaceholder(field: string): string {
   if (field === "trigger_author") return "64-character hex pubkey";
   if (field === "trigger_message_id") return "64-character hex event ID";
   return "e.g. deploy";
 }
 
+function ExclusionStrike() {
+  return (
+    <span aria-hidden="true" className="pointer-events-none absolute inset-0">
+      <span className="absolute inset-0 [clip-path:circle(50%_at_50%_50%)]">
+        <span className="absolute left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2">
+          <span className="block h-1 w-9 translate-y-0.5 -rotate-45 rounded-full bg-background/90" />
+        </span>
+      </span>
+      <span className="absolute left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2">
+        <span className="block h-0.5 w-8 -rotate-45 rounded-full bg-muted-foreground" />
+      </span>
+    </span>
+  );
+}
+
+function AuthorConditionSummary({
+  avatarUrl,
+  excluded,
+  label,
+}: {
+  avatarUrl: string | null;
+  excluded: boolean;
+  label: string;
+}) {
+  return (
+    <span className="flex shrink-0 items-center">
+      <span className="relative shrink-0">
+        <UserAvatar
+          avatarUrl={avatarUrl}
+          className="h-6 w-6"
+          displayName={label}
+          fallbackDelayMs={0}
+          size="xs"
+        />
+        {excluded ? <ExclusionStrike /> : null}
+      </span>
+      <span className="sr-only">
+        {excluded ? "Excluded author: " : "Selected author: "}
+        {label}
+      </span>
+    </span>
+  );
+}
+
+function EmojiConditionSummary({
+  emoji,
+  excluded,
+}: {
+  emoji: string;
+  excluded: boolean;
+}) {
+  return (
+    <span className="relative flex h-6 w-6 shrink-0 items-center justify-center">
+      <span aria-hidden="true" className="text-2xl leading-none">
+        {emoji}
+      </span>
+      {excluded ? <ExclusionStrike /> : null}
+      <span className="sr-only">
+        {excluded ? "Excluded reaction emoji: " : "Selected reaction emoji: "}
+        {emoji}
+      </span>
+    </span>
+  );
+}
+
 export function WorkflowTriggerConditions({
   conditionDrafts,
   disabled,
@@ -58,6 +131,7 @@ export function WorkflowTriggerConditions({
   onConditionDraftsChange,
   triggerType,
   value,
+  workflowChannelId,
 }: {
   conditionDrafts: ParsedConditionExpression[] | null;
   disabled?: boolean;
@@ -68,6 +142,7 @@ export function WorkflowTriggerConditions({
     "message_posted" | "diff_posted" | "reaction_added"
   >;
   value: string;
+  workflowChannelId?: string | null;
 }) {
   const parsedValue = React.useMemo(
     () => parseConditionExpressions(value, triggerType),
@@ -79,8 +154,22 @@ export function WorkflowTriggerConditions({
   const [expandedField, setExpandedField] = React.useState<string | null>(
     () => conditionFieldsForTrigger(triggerType)[0]?.value ?? null,
   );
+  const disclosureButtons = React.useRef(new Map<string, HTMLButtonElement>());
+  const collapsePicker = React.useCallback((field: string) => {
+    setExpandedField(null);
+    disclosureButtons.current.get(field)?.focus();
+  }, []);
   const conditions = conditionDrafts ?? parsedValue ?? [];
   const localValue = React.useRef(value);
+  const triggerPresentation = useWorkflowTriggerPresentation(
+    {
+      filter: conditions.length
+        ? buildConditionExpressions(conditions)
+        : undefined,
+      on: triggerType,
+    },
+    workflowChannelId,
+  );
 
   React.useEffect(() => {
     if (value === localValue.current) return;
@@ -109,10 +198,16 @@ export function WorkflowTriggerConditions({
   };
 
   const fields = conditionFieldsForTrigger(triggerType);
+  const fullHeightPickerExpanded =
+    mode === "basic" && fieldUsesFullHeightPicker(expandedField ?? "");
 
   return (
     <Tabs
-      className="space-y-3"
+      className={cn(
+        "space-y-3",
+        fullHeightPickerExpanded &&
+          "flex h-full min-h-0 flex-col space-y-0 gap-3",
+      )}
       onValueChange={(next) => setMode(next as "basic" | "advanced")}
       value={mode}
     >
@@ -168,7 +263,12 @@ export function WorkflowTriggerConditions({
           </button>
         </div>
       ) : (
-        <div className="divide-y divide-border/50">
+        <div
+          className={cn(
+            "divide-y divide-border/50",
+            fullHeightPickerExpanded && "flex min-h-0 flex-1 flex-col",
+          )}
+        >
           {fields.map((field) => {
             const existing = conditions.find(
               (condition) => condition.field === field.value,
@@ -179,8 +279,32 @@ export function WorkflowTriggerConditions({
             const summary = existing
               ? `${OPERATOR_LABELS[condition.operator]}${condition.value ? ` ${compact(condition.value)}` : ""}`
               : "Any";
+            const authorSummary =
+              existing &&
+              field.value === "trigger_author" &&
+              triggerPresentation.pubkey &&
+              triggerPresentation.label
+                ? triggerPresentation.label
+                : null;
+            const messageSummary =
+              existing &&
+              field.value === "trigger_message_id" &&
+              triggerPresentation.messageId &&
+              triggerPresentation.messageLabel
+                ? triggerPresentation.messageLabel
+                    .trim()
+                    .replaceAll(/\s+/g, " ")
+                : null;
             return (
-              <div className={cn(expanded && "pb-4")} key={field.value}>
+              <div
+                className={cn(
+                  expanded && "pb-4 last:pb-0",
+                  expanded &&
+                    fieldUsesFullHeightPicker(field.value) &&
+                    "flex min-h-0 flex-1 flex-col",
+                )}
+                key={field.value}
+              >
                 <button
                   aria-expanded={expanded}
                   className="flex min-h-12 w-full items-center gap-3 py-3 text-left transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring disabled:opacity-50"
@@ -188,14 +312,43 @@ export function WorkflowTriggerConditions({
                   onClick={() =>
                     setExpandedField(expanded ? null : field.value)
                   }
+                  ref={(button) => {
+                    if (button)
+                      disclosureButtons.current.set(field.value, button);
+                    else disclosureButtons.current.delete(field.value);
+                  }}
                   type="button"
                 >
                   <span className="min-w-0 flex-1 truncate text-base font-medium">
                     {field.label}
                   </span>
-                  <span className="max-w-44 truncate font-mono text-xs text-muted-foreground">
-                    {summary}
-                  </span>
+                  {authorSummary ? (
+                    <AuthorConditionSummary
+                      avatarUrl={triggerPresentation.avatarUrl}
+                      excluded={condition.operator === "not_equals"}
+                      label={authorSummary}
+                    />
+                  ) : messageSummary ? (
+                    <span
+                      className={cn(
+                        "max-w-44 truncate text-xs text-muted-foreground",
+                        condition.operator === "not_equals" && "line-through",
+                      )}
+                    >
+                      “{messageSummary}”
+                    </span>
+                  ) : existing &&
+                    field.value === "trigger_emoji" &&
+                    condition.value.trim() ? (
+                    <EmojiConditionSummary
+                      emoji={condition.value.trim()}
+                      excluded={condition.operator === "not_equals"}
+                    />
+                  ) : (
+                    <span className="max-w-44 truncate font-mono text-xs text-muted-foreground">
+                      {summary}
+                    </span>
+                  )}
                   <ChevronRight
                     className={cn(
                       "h-4 w-4 shrink-0 text-muted-foreground/70 transition-transform duration-150 motion-reduce:transition-none",
@@ -204,7 +357,13 @@ export function WorkflowTriggerConditions({
                   />
                 </button>
                 {expanded ? (
-                  <div className="animate-in space-y-3 pt-1 fade-in slide-in-from-top-1 duration-150 motion-reduce:animate-none">
+                  <div
+                    className={cn(
+                      "animate-in space-y-3 pt-1 fade-in slide-in-from-top-1 duration-150 motion-reduce:animate-none",
+                      fieldUsesFullHeightPicker(field.value) &&
+                        "flex min-h-0 flex-1 flex-col space-y-0 gap-3",
+                    )}
+                  >
                     <fieldset>
                       <legend className="sr-only">Match</legend>
                       <div className="grid grid-cols-2 gap-2.5">
@@ -258,6 +417,51 @@ export function WorkflowTriggerConditions({
                           }
                           value={condition.value}
                         />
+                      ) : field.value === "trigger_author" ? (
+                        <WorkflowAuthorPicker
+                          channelId={workflowChannelId}
+                          disabled={disabled}
+                          id="wf-trigger-author-value"
+                          onEscape={() => collapsePicker(field.value)}
+                          onChange={(pubkey) =>
+                            updateConditions(
+                              pubkey
+                                ? [
+                                    ...conditions.filter(
+                                      (item) => item.field !== field.value,
+                                    ),
+                                    { ...condition, value: pubkey },
+                                  ]
+                                : conditions.filter(
+                                    (item) => item.field !== field.value,
+                                  ),
+                            )
+                          }
+                          value={condition.value}
+                        />
+                      ) : field.value === "trigger_message_id" ? (
+                        <WorkflowMessagePicker
+                          channelId={workflowChannelId}
+                          disabled={disabled}
+                          id="wf-trigger-message-id-value"
+                          key={workflowChannelId ?? "unscoped"}
+                          onEscape={() => collapsePicker(field.value)}
+                          onChange={(messageId) =>
+                            updateConditions(
+                              messageId
+                                ? [
+                                    ...conditions.filter(
+                                      (item) => item.field !== field.value,
+                                    ),
+                                    { ...condition, value: messageId },
+                                  ]
+                                : conditions.filter(
+                                    (item) => item.field !== field.value,
+                                  ),
+                            )
+                          }
+                          value={condition.value}
+                        />
                       ) : (
                         <div className="space-y-1.5">
                           <FieldLabel
@@ -299,7 +503,7 @@ export function WorkflowTriggerConditions({
                         </div>
                       )
                     ) : null}
-                    {existing ? (
+                    {existing && !fieldUsesFullHeightPicker(field.value) ? (
                       <button
                         className="text-xs font-medium text-muted-foreground hover:text-foreground"
                         disabled={disabled}
diff --git a/desktop/src/features/workflows/ui/WorkflowsView.tsx b/desktop/src/features/workflows/ui/WorkflowsView.tsx
index ba4cdf0bae..ef408267e6 100644
--- a/desktop/src/features/workflows/ui/WorkflowsView.tsx
+++ b/desktop/src/features/workflows/ui/WorkflowsView.tsx
@@ -13,6 +13,8 @@ import { getWorkflowActivationWarning } from "@/features/workflows/ui/workflowAc
 import { WorkflowCard } from "@/features/workflows/ui/WorkflowCard";
 import { WorkflowDeleteDialog } from "@/features/workflows/ui/WorkflowDeleteDialog";
 import { WorkflowEditorHost } from "@/features/workflows/ui/WorkflowEditorHost";
+import { useWorkflowListAuthorPresentations } from "@/features/workflows/ui/useWorkflowListAuthorPresentations";
+import { useWorkflowListMessagePresentations } from "@/features/workflows/ui/useWorkflowListMessagePresentations";
 import type { WorkflowEditorRoute } from "@/features/workflows/ui/WorkflowsScreen";
 import type { WorkflowEditorPane } from "@/features/workflows/ui/workflowEditorPane";
 import {
@@ -146,6 +148,9 @@ export function WorkflowsView({
   });
 
   const allWorkflows = allWorkflowsQuery.data ?? [];
+  const workflows = allWorkflows.map(({ workflow }) => workflow);
+  const authorPresentations = useWorkflowListAuthorPresentations(workflows);
+  const messagePresentations = useWorkflowListMessagePresentations(workflows);
 
   const triggerMutation = useMutation({
     mutationFn: (workflowId: string) => triggerWorkflow(workflowId),
@@ -310,12 +315,14 @@ export function WorkflowsView({
               <CreateWorkflowCard onClick={onCreateWorkflow} />
               {allWorkflows.map(({ workflow, channelName }) => (
                 <WorkflowCard
+                  authorPresentation={authorPresentations.get(workflow.id)}
                   channelName={channelName}
                   isTogglingEnabled={
                     toggleEnabledMutation.isPending &&
                     toggleEnabledMutation.variables?.id === workflow.id
                   }
                   key={workflow.id}
+                  messagePresentation={messagePresentations.get(workflow.id)}
                   onDelete={handleDelete}
                   onDuplicate={handleDuplicate}
                   onEdit={handleEdit}
diff --git a/desktop/src/features/workflows/ui/useWorkflowAuthorPresentation.ts b/desktop/src/features/workflows/ui/useWorkflowAuthorPresentation.ts
new file mode 100644
index 0000000000..320ba0f835
--- /dev/null
+++ b/desktop/src/features/workflows/ui/useWorkflowAuthorPresentation.ts
@@ -0,0 +1,57 @@
+import { useUsersBatchQuery } from "@/features/profile/hooks";
+import { resolveUserLabel } from "@/features/profile/lib/identity";
+import { useIdentityQuery } from "@/shared/api/hooks";
+import { parseConditionExpressions } from "./workflowConditionExpression";
+import type { TriggerConfig } from "./workflowFormTypes";
+import { workflowTriggerDescription } from "./workflowTriggerDescription";
+
+const FULL_HEX_PUBKEY = /^[0-9a-f]{64}$/i;
+
+export type WorkflowAuthorPresentation = {
+  avatarUrl: string | null;
+  description: string;
+  label: string | null;
+  loading: boolean;
+  pubkey: string | null;
+};
+
+export function workflowTriggerAuthorPubkey(
+  trigger: TriggerConfig,
+): string | null {
+  const conditions = trigger.filter
+    ? parseConditionExpressions(trigger.filter, trigger.on)
+    : [];
+  const condition = conditions?.find(({ field }) => field === "trigger_author");
+  return condition && FULL_HEX_PUBKEY.test(condition.value)
+    ? condition.value.toLowerCase()
+    : null;
+}
+
+export function useWorkflowAuthorPresentation(
+  trigger: TriggerConfig,
+): WorkflowAuthorPresentation {
+  const identityQuery = useIdentityQuery();
+  const pubkey = workflowTriggerAuthorPubkey(trigger);
+  const profilesQuery = useUsersBatchQuery(pubkey ? [pubkey] : []);
+  const profile = pubkey ? profilesQuery.data?.profiles[pubkey] : undefined;
+  const loading = Boolean(pubkey && !profile && profilesQuery.isPending);
+  const label =
+    pubkey && !loading
+      ? resolveUserLabel({
+          currentPubkey: identityQuery.data?.pubkey,
+          profiles: profilesQuery.data?.profiles,
+          pubkey,
+        })
+      : null;
+
+  return {
+    avatarUrl: profile?.avatarUrl ?? null,
+    description: workflowTriggerDescription(trigger, {
+      authorLabel: label ?? undefined,
+      authorLoading: loading,
+    }),
+    label,
+    loading,
+    pubkey,
+  };
+}
diff --git a/desktop/src/features/workflows/ui/useWorkflowListAuthorPresentations.test.mjs b/desktop/src/features/workflows/ui/useWorkflowListAuthorPresentations.test.mjs
new file mode 100644
index 0000000000..40952367b4
--- /dev/null
+++ b/desktop/src/features/workflows/ui/useWorkflowListAuthorPresentations.test.mjs
@@ -0,0 +1,30 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { workflowAuthorLookups } from "./useWorkflowListAuthorPresentations.ts";
+
+function workflow(index, pubkey) {
+  return {
+    id: `workflow-${index}`,
+    definition: {
+      trigger: {
+        on: "message_posted",
+        filter: `trigger_author == "${pubkey}"`,
+      },
+      steps: [],
+    },
+  };
+}
+
+test("collects configured authors for one list-level batch", () => {
+  const authors = ["a".repeat(64), "b".repeat(64), "a".repeat(64)];
+  const lookups = authors.flatMap((pubkey, index) =>
+    workflowAuthorLookups([workflow(index, pubkey)]),
+  );
+
+  assert.equal(lookups.length, 3);
+  assert.deepEqual(
+    [...new Set(lookups.map(({ pubkey }) => pubkey))],
+    authors.slice(0, 2),
+  );
+});
diff --git a/desktop/src/features/workflows/ui/useWorkflowListAuthorPresentations.ts b/desktop/src/features/workflows/ui/useWorkflowListAuthorPresentations.ts
new file mode 100644
index 0000000000..a2ad5f90dd
--- /dev/null
+++ b/desktop/src/features/workflows/ui/useWorkflowListAuthorPresentations.ts
@@ -0,0 +1,60 @@
+import { useUsersBatchQuery } from "@/features/profile/hooks";
+import { resolveUserLabel } from "@/features/profile/lib/identity";
+import { useIdentityQuery } from "@/shared/api/hooks";
+import type { Workflow } from "@/shared/api/types";
+import { getWorkflowTriggerConfig } from "./workflowDefinition";
+import {
+  type WorkflowAuthorPresentation,
+  workflowTriggerAuthorPubkey,
+} from "./useWorkflowAuthorPresentation";
+
+export type WorkflowCardAuthorPresentation = Omit<
+  WorkflowAuthorPresentation,
+  "description"
+>;
+
+type WorkflowAuthorLookup = {
+  pubkey: string;
+  workflowId: string;
+};
+
+export function workflowAuthorLookups(
+  workflows: readonly Workflow[],
+): WorkflowAuthorLookup[] {
+  return workflows.flatMap((workflow) => {
+    const trigger = getWorkflowTriggerConfig(workflow.definition);
+    const pubkey = trigger ? workflowTriggerAuthorPubkey(trigger) : null;
+    return pubkey ? [{ pubkey, workflowId: workflow.id }] : [];
+  });
+}
+
+export function useWorkflowListAuthorPresentations(
+  workflows: readonly Workflow[],
+): Map<string, WorkflowCardAuthorPresentation> {
+  const identityQuery = useIdentityQuery();
+  const lookups = workflowAuthorLookups(workflows);
+  const pubkeys = [...new Set(lookups.map(({ pubkey }) => pubkey))];
+  const profilesQuery = useUsersBatchQuery(pubkeys);
+
+  return new Map(
+    lookups.map(({ pubkey, workflowId }) => {
+      const profile = profilesQuery.data?.profiles[pubkey];
+      const loading = !profile && profilesQuery.isPending;
+      return [
+        workflowId,
+        {
+          avatarUrl: profile?.avatarUrl ?? null,
+          label: loading
+            ? null
+            : resolveUserLabel({
+                currentPubkey: identityQuery.data?.pubkey,
+                profiles: profilesQuery.data?.profiles,
+                pubkey,
+              }),
+          loading,
+          pubkey,
+        },
+      ];
+    }),
+  );
+}
diff --git a/desktop/src/features/workflows/ui/useWorkflowListMessagePresentations.test.mjs b/desktop/src/features/workflows/ui/useWorkflowListMessagePresentations.test.mjs
new file mode 100644
index 0000000000..bf423b19d4
--- /dev/null
+++ b/desktop/src/features/workflows/ui/useWorkflowListMessagePresentations.test.mjs
@@ -0,0 +1,67 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  loadWorkflowMessagePresentations,
+  workflowMessageLookups,
+} from "./useWorkflowListMessagePresentations.ts";
+
+const CHANNEL_ID = "94a444a4-c0a3-5966-ab05-530c6ddc2301";
+
+function workflow(index) {
+  const messageId = index.toString(16).padStart(64, "0");
+  return {
+    id: `workflow-${index}`,
+    channelId: CHANNEL_ID,
+    definition: {
+      trigger: {
+        on: "reaction_added",
+        filter: `trigger_message_id == "${messageId}"`,
+      },
+      steps: [],
+    },
+  };
+}
+
+test("loads presentation for many workflow cards with one batched fetch", async () => {
+  const workflows = Array.from({ length: 40 }, (_, index) =>
+    workflow(index + 1),
+  );
+  const lookups = workflowMessageLookups(workflows);
+  const calls = [];
+
+  const presentations = await loadWorkflowMessagePresentations(
+    lookups,
+    async (eventIds) => {
+      calls.push(eventIds);
+      return eventIds.map((id, index) => ({
+        id,
+        pubkey: "a".repeat(64),
+        created_at: index,
+        kind: 9,
+        tags: [["h", CHANNEL_ID]],
+        content: `Message ${index + 1}`,
+        sig: "b".repeat(128),
+      }));
+    },
+  );
+
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].length, workflows.length);
+  assert.equal(presentations.size, workflows.length);
+  assert.equal(presentations.get("workflow-40")?.messageLabel, "Message 40");
+});
+
+test("deduplicates shared message IDs inside the single batch", async () => {
+  const duplicate = workflow(1);
+  duplicate.id = "workflow-duplicate";
+  const lookups = workflowMessageLookups([workflow(1), duplicate]);
+  let requestedIds = [];
+
+  await loadWorkflowMessagePresentations(lookups, async (eventIds) => {
+    requestedIds = eventIds;
+    return [];
+  });
+
+  assert.deepEqual(requestedIds, [`${"0".repeat(63)}1`]);
+});
diff --git a/desktop/src/features/workflows/ui/useWorkflowListMessagePresentations.ts b/desktop/src/features/workflows/ui/useWorkflowListMessagePresentations.ts
new file mode 100644
index 0000000000..da0dd95b42
--- /dev/null
+++ b/desktop/src/features/workflows/ui/useWorkflowListMessagePresentations.ts
@@ -0,0 +1,92 @@
+import { useQuery } from "@tanstack/react-query";
+
+import { getEventsByIds } from "@/shared/api/tauri";
+import type { RelayEvent, Workflow } from "@/shared/api/types";
+import { getWorkflowTriggerConfig } from "./workflowDefinition";
+import {
+  type WorkflowTriggerPresentation,
+  workflowTriggerMessageId,
+} from "./useWorkflowTriggerPresentation";
+import { validatedWorkflowMessageCandidate } from "./workflowMessageCandidates";
+
+export type WorkflowMessagePresentation = Pick<
+  WorkflowTriggerPresentation,
+  "messageId" | "messageLabel" | "messageLoading"
+>;
+
+type WorkflowMessageLookup = {
+  channelId: string;
+  messageId: string;
+  workflowId: string;
+};
+
+export function workflowMessageLookups(
+  workflows: readonly Workflow[],
+): WorkflowMessageLookup[] {
+  return workflows.flatMap((workflow) => {
+    const trigger = getWorkflowTriggerConfig(workflow.definition);
+    const messageId = trigger ? workflowTriggerMessageId(trigger) : null;
+    return workflow.channelId && messageId
+      ? [{ channelId: workflow.channelId, messageId, workflowId: workflow.id }]
+      : [];
+  });
+}
+
+export async function loadWorkflowMessagePresentations(
+  lookups: readonly WorkflowMessageLookup[],
+  fetchEvents: (eventIds: string[]) => Promise<RelayEvent[]> = getEventsByIds,
+): Promise<Map<string, WorkflowMessagePresentation>> {
+  const eventIds = [...new Set(lookups.map(({ messageId }) => messageId))];
+  if (eventIds.length === 0) return new Map();
+
+  const events = await fetchEvents(eventIds);
+  const eventById = new Map(
+    events.map((event) => [event.id.toLowerCase(), event]),
+  );
+  return new Map(
+    lookups.map(({ channelId, messageId, workflowId }) => {
+      const message = validatedWorkflowMessageCandidate(
+        eventById.get(messageId),
+        {
+          channelId,
+          requestedId: messageId,
+        },
+      );
+      return [
+        workflowId,
+        {
+          messageId,
+          messageLabel: message?.content?.trim() || null,
+          messageLoading: false,
+        },
+      ];
+    }),
+  );
+}
+
+export function useWorkflowListMessagePresentations(
+  workflows: readonly Workflow[],
+): Map<string, WorkflowMessagePresentation> {
+  const lookups = workflowMessageLookups(workflows);
+  const lookupKey = lookups
+    .map(({ channelId, messageId, workflowId }) =>
+      [workflowId, channelId, messageId].join(":"),
+    )
+    .sort()
+    .join(",");
+  const query = useQuery({
+    queryKey: ["workflow-list-message-presentations", lookupKey],
+    queryFn: () => loadWorkflowMessagePresentations(lookups),
+    enabled: lookups.length > 0,
+    retry: false,
+    staleTime: 60_000,
+  });
+
+  if (!query.isPending) return query.data ?? new Map();
+  return new Map(
+    lookups.map(({ messageId, workflowId }) => [
+      workflowId,
+      { messageId, messageLabel: null, messageLoading: true },
+    ]),
+  );
+}
diff --git a/desktop/src/features/workflows/ui/useWorkflowTriggerPresentation.ts b/desktop/src/features/workflows/ui/useWorkflowTriggerPresentation.ts
new file mode 100644
index 0000000000..20245f1b2b
--- /dev/null
+++ b/desktop/src/features/workflows/ui/useWorkflowTriggerPresentation.ts
@@ -0,0 +1,70 @@
+import { useQuery } from "@tanstack/react-query";
+
+import { getEventById } from "@/shared/api/tauri";
+import { useWorkflowAuthorPresentation } from "./useWorkflowAuthorPresentation";
+import { parseConditionExpressions } from "./workflowConditionExpression";
+import type { TriggerConfig } from "./workflowFormTypes";
+import {
+  normalizeMessageEventId,
+  validatedWorkflowMessageCandidate,
+} from "./workflowMessageCandidates";
+import { workflowTriggerDescription } from "./workflowTriggerDescription";
+
+export type WorkflowTriggerPresentation = ReturnType<
+  typeof useWorkflowAuthorPresentation
+> & {
+  messageId: string | null;
+  messageLabel: string | null;
+  messageLoading: boolean;
+};
+
+export function workflowTriggerMessageId(
+  trigger: TriggerConfig,
+): string | null {
+  const conditions = trigger.filter
+    ? parseConditionExpressions(trigger.filter, trigger.on)
+    : [];
+  const condition = conditions?.find(
+    ({ field }) => field === "trigger_message_id",
+  );
+  return condition ? normalizeMessageEventId(condition.value) : null;
+}
+
+export function useWorkflowTriggerPresentation(
+  trigger: TriggerConfig,
+  workflowChannelId?: string | null,
+): WorkflowTriggerPresentation {
+  const author = useWorkflowAuthorPresentation(trigger);
+  const messageId = workflowTriggerMessageId(trigger);
+  const messageQuery = useQuery({
+    enabled: Boolean(messageId && workflowChannelId),
+    queryKey: ["workflow-trigger-message", workflowChannelId, messageId],
+    queryFn: () => getEventById(messageId ?? ""),
+    retry: false,
+    staleTime: 60_000,
+  });
+  const message =
+    workflowChannelId && messageId
+      ? validatedWorkflowMessageCandidate(messageQuery.data, {
+          channelId: workflowChannelId,
+          requestedId: messageId,
+        })
+      : null;
+  const messageLoading = Boolean(
+    messageId && workflowChannelId && messageQuery.isPending,
+  );
+  const messageLabel = message?.content?.trim() || null;
+
+  return {
+    ...author,
+    description: workflowTriggerDescription(trigger, {
+      authorLabel: author.label ?? undefined,
+      authorLoading: author.loading,
+      messageLabel: messageLabel ?? undefined,
+      messageLoading,
+    }),
+    messageId,
+    messageLabel,
+    messageLoading,
+  };
+}
diff --git a/desktop/src/features/workflows/ui/workflowAuthorCandidates.test.mjs b/desktop/src/features/workflows/ui/workflowAuthorCandidates.test.mjs
new file mode 100644
index 0000000000..7c504ce2e0
--- /dev/null
+++ b/desktop/src/features/workflows/ui/workflowAuthorCandidates.test.mjs
@@ -0,0 +1,146 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { npubEncode } from "nostr-tools/nip19";
+
+import {
+  enrichAuthorCandidates,
+  filterAuthorCandidatePage,
+  mergeAuthorCandidateSources,
+  nextWorkflowAuthorIndex,
+  normalizeAuthorPubkey,
+  parseDirectAuthorInput,
+} from "./workflowAuthorCandidates.ts";
+
+const A = "a".repeat(64);
+const B = "b".repeat(64);
+const C = "c".repeat(64);
+
+test("normalizes only valid 64-character hex candidate identities", () => {
+  assert.equal(normalizeAuthorPubkey(`  ${A.toUpperCase()}  `), A);
+  assert.equal(normalizeAuthorPubkey(A.slice(1)), null);
+  assert.equal(normalizeAuthorPubkey("z".repeat(64)), null);
+  assert.equal(normalizeAuthorPubkey(npubEncode(A)), null);
+});
+
+test("parses direct hex and npub input to normalized hex", () => {
+  assert.equal(parseDirectAuthorInput(A.toUpperCase()), A);
+  assert.equal(parseDirectAuthorInput(`  ${npubEncode(A)}  `), A);
+  assert.equal(parseDirectAuthorInput("not-a-pubkey"), null);
+});
+
+test("merges valid candidates with stable first-wins source priority", () => {
+  const merged = mergeAuthorCandidateSources([
+    [
+      { pubkey: B.toUpperCase(), displayName: "Channel B" },
+      { pubkey: "invalid", displayName: "Invalid" },
+      { pubkey: A, displayName: "Channel A", isAgent: true },
+    ],
+    [
+      { pubkey: A.toUpperCase(), displayName: "Directory A" },
+      { pubkey: C, displayName: "Directory C" },
+      { pubkey: B, displayName: "Directory B" },
+    ],
+  ]);
+
+  assert.deepEqual(
+    merged.map(({ pubkey, displayName }) => ({ pubkey, displayName })),
+    [
+      { pubkey: B, displayName: "Channel B" },
+      { pubkey: A, displayName: "Channel A" },
+      { pubkey: C, displayName: "Directory C" },
+    ],
+  );
+  assert.equal(merged[1].isAgent, true);
+});
+
+test("wraps author grid movement without producing negative indices", () => {
+  assert.equal(nextWorkflowAuthorIndex(null, -2, 2), 1);
+  assert.equal(nextWorkflowAuthorIndex(null, -3, 3), 2);
+  assert.equal(nextWorkflowAuthorIndex(1, -2, 2), 1);
+  assert.equal(nextWorkflowAuthorIndex(null, 2, 2), 1);
+  assert.equal(nextWorkflowAuthorIndex(null, 1, 0), null);
+});
+
+test("bounds filtered candidates while pinning direct input", () => {
+  const candidates = mergeAuthorCandidateSources([
+    Array.from({ length: 1_500 }, (_, index) => ({
+      pubkey: index.toString(16).padStart(64, "0"),
+      displayName: `Member ${index}`,
+    })),
+  ]);
+
+  const initialPage = filterAuthorCandidatePage(candidates, "", null, 50);
+  assert.equal(initialPage.length, 50);
+  assert.deepEqual(
+    initialPage.map(({ displayName }) => displayName),
+    Array.from({ length: 50 }, (_, index) => `Member ${index}`),
+  );
+
+  const filteredPage = filterAuthorCandidatePage(
+    candidates,
+    "Member 12",
+    null,
+    50,
+  );
+  assert.equal(filteredPage.length, 50);
+  assert.ok(
+    filteredPage.every(({ displayName }) => displayName.includes("Member 12")),
+  );
+
+  const direct = candidates[1_234].pubkey;
+  assert.deepEqual(
+    filterAuthorCandidatePage(candidates, direct, direct, 50).map(
+      ({ pubkey }) => pubkey,
+    ),
+    [direct],
+  );
+});
+
+test("profile enrichment updates matching presentation without reordering", () => {
+  const candidates = mergeAuthorCandidateSources([
+    [
+      {
+        pubkey: B,
+        displayName: "Roster B",
+        nip05Handle: "b@old.example",
+      },
+      { pubkey: A, displayName: "Roster A" },
+      { pubkey: C, displayName: "Roster C" },
+    ],
+  ]);
+
+  const enriched = enrichAuthorCandidates(candidates, {
+    [A.toUpperCase()]: {
+      displayName: "Profile A",
+      avatarUrl: "https://example.test/a.png",
+      nip05Handle: null,
+      ownerPubkey: B.toUpperCase(),
+      isAgent: true,
+    },
+    [B]: {
+      displayName: null,
+      name: "Profile B name",
+      avatarUrl: null,
+      nip05Handle: null,
+      ownerPubkey: null,
+    },
+    ["d".repeat(64)]: {
+      displayName: "Not a candidate",
+      avatarUrl: null,
+      nip05Handle: null,
+      ownerPubkey: null,
+    },
+  });
+
+  assert.deepEqual(
+    enriched.map(({ pubkey }) => pubkey),
+    [B, A, C],
+  );
+  assert.equal(enriched[0].displayName, "Profile B name");
+  assert.equal(enriched[0].nip05Handle, "b@old.example");
+  assert.equal(enriched[1].displayName, "Profile A");
+  assert.equal(enriched[1].avatarUrl, "https://example.test/a.png");
+  assert.equal(enriched[1].ownerPubkey, B);
+  assert.equal(enriched[1].isAgent, true);
+  assert.strictEqual(enriched[2], candidates[2]);
+});
diff --git a/desktop/src/features/workflows/ui/workflowAuthorCandidates.ts b/desktop/src/features/workflows/ui/workflowAuthorCandidates.ts
new file mode 100644
index 0000000000..cd5bf01c88
--- /dev/null
+++ b/desktop/src/features/workflows/ui/workflowAuthorCandidates.ts
@@ -0,0 +1,130 @@
+import type { UserProfileSummary } from "@/shared/api/types";
+import { parsePubkeyInput } from "@/shared/lib/nostrUtils";
+
+const HEX_PUBKEY = /^[0-9a-f]{64}$/;
+
+export type WorkflowAuthorCandidate = {
+  pubkey: string;
+  displayName: string | null;
+  avatarUrl: string | null;
+  nip05Handle: string | null;
+  ownerPubkey: string | null;
+  isAgent: boolean;
+};
+
+export type WorkflowAuthorCandidateInput = {
+  pubkey: string;
+  displayName?: string | null;
+  avatarUrl?: string | null;
+  nip05Handle?: string | null;
+  ownerPubkey?: string | null;
+  isAgent?: boolean;
+};
+
+/** Normalize a candidate identity without accepting alternate encodings. */
+export function normalizeAuthorPubkey(pubkey: string): string | null {
+  const normalized = pubkey.trim().toLowerCase();
+  return HEX_PUBKEY.test(normalized) ? normalized : null;
+}
+
+/** Parse direct user input (hex or npub) into the canonical stored hex form. */
+export function parseDirectAuthorInput(input: string): string | null {
+  return parsePubkeyInput(input);
+}
+
+/**
+ * Merge candidate sources in priority order. The first occurrence of an
+ * identity owns both its position and source-provided presentation fields.
+ */
+export function mergeAuthorCandidateSources(
+  sources: readonly (readonly WorkflowAuthorCandidateInput[])[],
+): WorkflowAuthorCandidate[] {
+  const merged: WorkflowAuthorCandidate[] = [];
+  const seen = new Set<string>();
+
+  for (const source of sources) {
+    for (const candidate of source) {
+      const pubkey = normalizeAuthorPubkey(candidate.pubkey);
+      if (!pubkey || seen.has(pubkey)) continue;
+      seen.add(pubkey);
+      merged.push({
+        pubkey,
+        displayName: candidate.displayName ?? null,
+        avatarUrl: candidate.avatarUrl ?? null,
+        nip05Handle: candidate.nip05Handle ?? null,
+        ownerPubkey: normalizeAuthorPubkey(candidate.ownerPubkey ?? ""),
+        isAgent: candidate.isAgent ?? false,
+      });
+    }
+  }
+
+  return merged;
+}
+
+export function nextWorkflowAuthorIndex(
+  current: number | null,
+  delta: number,
+  length: number,
+): number | null {
+  if (length === 0) return null;
+  const startingIndex = current ?? -1;
+  return (((startingIndex + delta) % length) + length) % length;
+}
+
+export function filterAuthorCandidatePage(
+  candidates: readonly WorkflowAuthorCandidate[],
+  query: string,
+  directPubkey: string | null,
+  limit: number,
+): WorkflowAuthorCandidate[] {
+  if (directPubkey) {
+    return candidates
+      .filter(({ pubkey }) => pubkey === directPubkey)
+      .slice(0, 1);
+  }
+  const needle = query.toLowerCase();
+  return candidates
+    .filter(
+      (candidate) =>
+        !needle ||
+        [candidate.displayName, candidate.nip05Handle, candidate.pubkey].some(
+          (field) => field?.toLowerCase().includes(needle),
+        ),
+    )
+    .slice(0, limit);
+}
+
+/**
+ * Add fetched profile presentation to existing identities without changing
+ * candidate membership or order. Missing profile fields preserve useful data
+ * already supplied by the higher-priority discovery source.
+ */
+export function enrichAuthorCandidates(
+  candidates: readonly WorkflowAuthorCandidate[],
+  profiles: Readonly<Record<string, UserProfileSummary | undefined>>,
+): WorkflowAuthorCandidate[] {
+  const normalizedProfiles = new Map(
+    Object.entries(profiles).flatMap(([pubkey, profile]) => {
+      const normalized = normalizeAuthorPubkey(pubkey);
+      return normalized && profile ? [[normalized, profile] as const] : [];
+    }),
+  );
+
+  return candidates.map((candidate) => {
+    const profile = normalizedProfiles.get(candidate.pubkey);
+    if (!profile) return candidate;
+    return {
+      ...candidate,
+      displayName:
+        profile.displayName?.trim() ||
+        profile.name?.trim() ||
+        candidate.displayName,
+      avatarUrl: profile.avatarUrl ?? candidate.avatarUrl,
+      nip05Handle: profile.nip05Handle ?? candidate.nip05Handle,
+      ownerPubkey:
+        normalizeAuthorPubkey(profile.ownerPubkey ?? "") ??
+        candidate.ownerPubkey,
+      isAgent: profile.isAgent ?? candidate.isAgent,
+    };
+  });
+}
diff --git a/desktop/src/features/workflows/ui/workflowConditionExpression.ts b/desktop/src/features/workflows/ui/workflowConditionExpression.ts
index e44d6a7a16..9a1fd04732 100644
--- a/desktop/src/features/workflows/ui/workflowConditionExpression.ts
+++ b/desktop/src/features/workflows/ui/workflowConditionExpression.ts
@@ -27,7 +27,7 @@ export type ParsedConditionExpression = {
 };
 
 const AUTHOR_FIELD: ConditionField = {
-  label: "Author pubkey",
+  label: "Author",
   value: "trigger_author",
 };
 const FIELDS_BY_TRIGGER: Record<TriggerType, ConditionField[]> = {
@@ -39,7 +39,7 @@ const FIELDS_BY_TRIGGER: Record<TriggerType, ConditionField[]> = {
   reaction_added: [
     { label: "Reaction emoji", value: "trigger_emoji" },
     AUTHOR_FIELD,
-    { label: "Message event ID", value: "trigger_message_id" },
+    { label: "Message", value: "trigger_message_id" },
   ],
   webhook: [],
   schedule: [],
diff --git a/desktop/src/features/workflows/ui/workflowDefinition.ts b/desktop/src/features/workflows/ui/workflowDefinition.ts
index e6d7084596..84ec62f496 100644
--- a/desktop/src/features/workflows/ui/workflowDefinition.ts
+++ b/desktop/src/features/workflows/ui/workflowDefinition.ts
@@ -89,7 +89,7 @@ export function getWorkflowTriggerEmoji(
   return nonEmptyString(emojiCondition?.value);
 }
 
-function getWorkflowTriggerConfig(
+export function getWorkflowTriggerConfig(
   definition: Record<string, unknown>,
 ): TriggerConfig | null {
   const trigger = asRecord(definition.trigger);
diff --git a/desktop/src/features/workflows/ui/workflowMessageCandidates.test.mjs b/desktop/src/features/workflows/ui/workflowMessageCandidates.test.mjs
new file mode 100644
index 0000000000..739bb90e4b
--- /dev/null
+++ b/desktop/src/features/workflows/ui/workflowMessageCandidates.test.mjs
@@ -0,0 +1,218 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  enrichMessageCandidateFromExactLookup,
+  isPickableWorkflowMessageEvent,
+  mergeMessageCandidateSources,
+  normalizeMessageEventId,
+  validateWorkflowMessageSearchResults,
+  validatedWorkflowMessageCandidate,
+} from "./workflowMessageCandidates.ts";
+
+const A = "a".repeat(64);
+const B = "b".repeat(64);
+const C = "c".repeat(64);
+const CHANNEL = "workflow-channel";
+
+function relayEvent({
+  id = A,
+  kind = 9,
+  channelId = CHANNEL,
+  content = "Fetched preview",
+} = {}) {
+  return {
+    id,
+    pubkey: C,
+    created_at: 1_725_000_000,
+    kind,
+    tags: channelId === null ? [] : [["h", channelId]],
+    content,
+    sig: "",
+  };
+}
+
+function fallback(id = A) {
+  return { id, pubkey: null, content: null, createdAt: null };
+}
+
+test("normalizes only valid 64-character hex event IDs", () => {
+  assert.equal(normalizeMessageEventId(`  ${A.toUpperCase()}  `), A);
+  assert.equal(normalizeMessageEventId(A.slice(1)), null);
+  assert.equal(normalizeMessageEventId("z".repeat(64)), null);
+});
+
+test("merges valid candidates with stable first-wins source priority", () => {
+  const merged = mergeMessageCandidateSources([
+    [
+      { id: B.toUpperCase(), content: "Recent B" },
+      { id: "invalid", content: "Invalid" },
+      { id: A, content: "Recent A", pubkey: C },
+    ],
+    [
+      { id: A.toUpperCase(), content: "Search A" },
+      { id: C, content: "Search C" },
+      { id: B, content: "Search B" },
+    ],
+  ]);
+
+  assert.deepEqual(
+    merged.map(({ id, content }) => ({ id, content })),
+    [
+      { id: B, content: "Recent B" },
+      { id: A, content: "Recent A" },
+      { id: C, content: "Search C" },
+    ],
+  );
+  assert.equal(merged[1].pubkey, C);
+});
+
+test("accepts only the existing narrow message kinds in the exact channel", () => {
+  for (const kind of [9, 40_002, 45_001, 45_003, 40_008]) {
+    assert.equal(
+      isPickableWorkflowMessageEvent(relayEvent({ kind }), CHANNEL),
+      true,
+    );
+  }
+
+  assert.equal(
+    isPickableWorkflowMessageEvent(relayEvent({ kind: 40_099 }), CHANNEL),
+    false,
+  );
+  assert.equal(
+    isPickableWorkflowMessageEvent(
+      relayEvent({ channelId: "another-channel" }),
+      CHANNEL,
+    ),
+    false,
+  );
+  assert.equal(
+    isPickableWorkflowMessageEvent(
+      {
+        ...relayEvent(),
+        tags: [
+          ["h", CHANNEL],
+          ["h", "another-channel"],
+        ],
+      },
+      CHANNEL,
+    ),
+    false,
+  );
+  assert.equal(
+    isPickableWorkflowMessageEvent(relayEvent({ channelId: null }), CHANNEL),
+    false,
+  );
+});
+
+test("single validator rejects wrong IDs, channels, and kinds", () => {
+  assert.deepEqual(
+    validatedWorkflowMessageCandidate(relayEvent(), {
+      channelId: CHANNEL,
+      requestedId: A.toUpperCase(),
+    }),
+    {
+      id: A,
+      pubkey: C,
+      content: "Fetched preview",
+      createdAt: 1_725_000_000,
+    },
+  );
+  assert.equal(
+    validatedWorkflowMessageCandidate(relayEvent({ id: B }), {
+      channelId: CHANNEL,
+      requestedId: A,
+    }),
+    null,
+  );
+  assert.equal(
+    validatedWorkflowMessageCandidate(
+      relayEvent({ channelId: "another-channel" }),
+      { channelId: CHANNEL },
+    ),
+    null,
+  );
+  assert.equal(
+    validatedWorkflowMessageCandidate(relayEvent({ kind: 40_099 }), {
+      channelId: CHANNEL,
+    }),
+    null,
+  );
+});
+
+test("exact lookup enriches only the normalized requested event ID", () => {
+  const enriched = enrichMessageCandidateFromExactLookup(
+    fallback(A.toUpperCase()),
+    relayEvent({ id: A.toUpperCase() }),
+    CHANNEL,
+  );
+
+  assert.deepEqual(enriched, {
+    id: A,
+    pubkey: C,
+    content: "Fetched preview",
+    createdAt: 1_725_000_000,
+  });
+
+  const wrongEvent = relayEvent({ id: B, content: "Wrong preview" });
+  const original = fallback(A);
+  assert.strictEqual(
+    enrichMessageCandidateFromExactLookup(original, wrongEvent, CHANNEL),
+    original,
+  );
+});
+
+test("search discovery exposes only exact events that pass the real event boundary", () => {
+  const candidates = validateWorkflowMessageSearchResults(
+    [
+      {
+        requestedId: A,
+        event: relayEvent({ id: A, content: "Validated search preview" }),
+      },
+      {
+        requestedId: B,
+        event: {
+          ...relayEvent({ id: B, content: "Projection-laundered preview" }),
+          tags: [
+            ["h", CHANNEL],
+            ["h", "another-channel"],
+          ],
+        },
+      },
+      {
+        requestedId: C,
+        event: relayEvent({ id: B, content: "Wrong exact event" }),
+      },
+    ],
+    CHANNEL,
+  );
+
+  assert.deepEqual(candidates, [
+    {
+      id: A,
+      pubkey: C,
+      content: "Validated search preview",
+      createdAt: 1_725_000_000,
+    },
+  ]);
+});
+
+test("invalid lookup results preserve the deterministic fallback without preview", () => {
+  const original = fallback(A);
+  const invalidEvents = [
+    undefined,
+    relayEvent({ channelId: "another-channel", content: "Cross-channel" }),
+    relayEvent({ kind: 40_099, content: "System message" }),
+    relayEvent({ channelId: null, content: "Unscoped" }),
+  ];
+
+  for (const event of invalidEvents) {
+    const result = enrichMessageCandidateFromExactLookup(
+      original,
+      event,
+      CHANNEL,
+    );
+    assert.strictEqual(result, original);
+    assert.equal(result.content, null);
+  }
+});
diff --git a/desktop/src/features/workflows/ui/workflowMessageCandidates.ts b/desktop/src/features/workflows/ui/workflowMessageCandidates.ts
new file mode 100644
index 0000000000..b89ed6801e
--- /dev/null
+++ b/desktop/src/features/workflows/ui/workflowMessageCandidates.ts
@@ -0,0 +1,139 @@
+import type { RelayEvent } from "@/shared/api/types";
+import {
+  CHANNEL_MESSAGE_EVENT_KINDS,
+  KIND_STREAM_MESSAGE_DIFF,
+} from "@/shared/constants/kinds";
+
+const HEX_EVENT_ID = /^[0-9a-f]{64}$/;
+const PICKABLE_MESSAGE_KINDS = new Set<number>([
+  ...CHANNEL_MESSAGE_EVENT_KINDS,
+  KIND_STREAM_MESSAGE_DIFF,
+]);
+
+export type WorkflowMessageCandidate = {
+  id: string;
+  pubkey: string | null;
+  content: string | null;
+  createdAt: number | null;
+};
+
+export type WorkflowMessageCandidateInput = {
+  id: string;
+  pubkey?: string | null;
+  content?: string | null;
+  createdAt?: number | null;
+};
+
+export type WorkflowMessageEventValidation = {
+  channelId: string;
+  requestedId?: string | null;
+};
+
+/** Normalize an event ID without accepting alternate encodings. */
+export function normalizeMessageEventId(eventId: string): string | null {
+  const normalized = eventId.trim().toLowerCase();
+  return HEX_EVENT_ID.test(normalized) ? normalized : null;
+}
+
+/**
+ * Merge candidate sources in priority order. The first occurrence of an event
+ * owns both its position and its presentation fields.
+ */
+export function mergeMessageCandidateSources(
+  sources: readonly (readonly WorkflowMessageCandidateInput[])[],
+): WorkflowMessageCandidate[] {
+  const merged: WorkflowMessageCandidate[] = [];
+  const seen = new Set<string>();
+
+  for (const source of sources) {
+    for (const candidate of source) {
+      const id = normalizeMessageEventId(candidate.id);
+      if (!id || seen.has(id)) continue;
+      seen.add(id);
+      merged.push({
+        id,
+        pubkey: candidate.pubkey ?? null,
+        content: candidate.content ?? null,
+        createdAt: candidate.createdAt ?? null,
+      });
+    }
+  }
+
+  return merged;
+}
+
+/** Whether an event is a user-pickable message in exactly the given channel. */
+export function isPickableWorkflowMessageEvent(
+  event: RelayEvent,
+  channelId: string,
+): boolean {
+  return (
+    PICKABLE_MESSAGE_KINDS.has(event.kind) &&
+    event.tags.filter((tag) => tag[0] === "h").length === 1 &&
+    event.tags.find((tag) => tag[0] === "h")?.[1] === channelId
+  );
+}
+
+/**
+ * Validate any fetched event before it can enrich a deterministic message ID.
+ * Transport scoping is not trusted: the event must carry exactly one matching
+ * channel tag, use a pickable kind, and match a requested ID when provided.
+ */
+export function validatedWorkflowMessageCandidate(
+  event: RelayEvent | null | undefined,
+  { channelId, requestedId }: WorkflowMessageEventValidation,
+): WorkflowMessageCandidate | null {
+  if (!event || !isPickableWorkflowMessageEvent(event, channelId)) return null;
+  const eventId = normalizeMessageEventId(event.id);
+  if (!eventId) return null;
+  if (requestedId !== undefined && requestedId !== null) {
+    const normalizedRequestedId = normalizeMessageEventId(requestedId);
+    if (!normalizedRequestedId || eventId !== normalizedRequestedId)
+      return null;
+  }
+  return {
+    id: eventId,
+    pubkey: event.pubkey,
+    content: event.content,
+    createdAt: event.created_at,
+  };
+}
+
+export type WorkflowMessageSearchResult = {
+  requestedId: string;
+  event: RelayEvent | null | undefined;
+};
+
+/**
+ * Validate exact events resolved from search-hit IDs. Search projections are
+ * discovery hints only and never supply presentation or selection fields.
+ */
+export function validateWorkflowMessageSearchResults(
+  results: readonly WorkflowMessageSearchResult[],
+  channelId: string,
+): WorkflowMessageCandidate[] {
+  return results.flatMap(({ requestedId, event }) => {
+    const candidate = validatedWorkflowMessageCandidate(event, {
+      channelId,
+      requestedId,
+    });
+    return candidate ? [candidate] : [];
+  });
+}
+
+/**
+ * Enrich a deterministic event-ID fallback only when an exact lookup returned
+ * that same event in the expected channel and with a pickable message kind.
+ * Invalid or unrelated fetches leave the fallback untouched.
+ */
+export function enrichMessageCandidateFromExactLookup(
+  fallback: WorkflowMessageCandidate,
+  event: RelayEvent | null | undefined,
+  channelId: string,
+): WorkflowMessageCandidate {
+  const candidate = validatedWorkflowMessageCandidate(event, {
+    channelId,
+    requestedId: fallback.id,
+  });
+  return candidate ?? fallback;
+}
diff --git a/desktop/src/features/workflows/ui/workflowTriggerDescription.test.mjs b/desktop/src/features/workflows/ui/workflowTriggerDescription.test.mjs
index 94b04356cd..1f2d03b238 100644
--- a/desktop/src/features/workflows/ui/workflowTriggerDescription.test.mjs
+++ b/desktop/src/features/workflows/ui/workflowTriggerDescription.test.mjs
@@ -1,7 +1,36 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 
-import { workflowTriggerDescription } from "./workflowTriggerDescription.ts";
+import {
+  compactWorkflowTriggerDescription,
+  splitWorkflowAuthorDescription,
+  workflowTriggerDescription,
+} from "./workflowTriggerDescription.ts";
+
+test("splits generated author attribution instead of matching quoted user copy", () => {
+  assert.deepEqual(
+    splitWorkflowAuthorDescription(
+      "Reaction added by Carl to “thanks Carl”",
+      "Carl",
+    ),
+    { prefix: "Reaction added by", suffix: "to “thanks Carl”" },
+  );
+  assert.deepEqual(
+    splitWorkflowAuthorDescription("Message by Carl contains “Carl”", "Carl"),
+    { prefix: "Message by", suffix: "contains “Carl”" },
+  );
+  assert.deepEqual(
+    splitWorkflowAuthorDescription(
+      "Message by anyone except Carl contains “Carl”",
+      "Carl",
+    ),
+    { prefix: "Message by anyone except", suffix: "contains “Carl”" },
+  );
+  assert.equal(
+    splitWorkflowAuthorDescription("Message contains “Carl”", "Carl"),
+    null,
+  );
+});
 
 test("describes selected trigger conditions on the workflow canvas", () => {
   assert.equal(
@@ -143,6 +172,38 @@ test("describes selected trigger conditions on the workflow canvas", () => {
   );
 });
 
+test("compacts only an included emoji already rendered as the node icon", () => {
+  assert.equal(
+    compactWorkflowTriggerDescription("😍 reaction added", "😍"),
+    "Reaction added",
+  );
+  assert.equal(
+    compactWorkflowTriggerDescription("😍 reaction added by Carl", "😍"),
+    "Reaction added by Carl",
+  );
+  assert.equal(
+    compactWorkflowTriggerDescription(
+      "😍 reaction added by Carl to “release 😍 notes”",
+      "😍",
+    ),
+    "Reaction added by Carl to “release 😍 notes”",
+  );
+  assert.equal(
+    compactWorkflowTriggerDescription(
+      "Any reaction except 😍 added",
+      undefined,
+    ),
+    "Any reaction except 😍 added",
+  );
+  assert.equal(
+    compactWorkflowTriggerDescription(
+      "Reaction added to “😍 reaction added”",
+      "😍",
+    ),
+    "Reaction added to “😍 reaction added”",
+  );
+});
+
 test("keeps the base label for unfiltered and custom triggers", () => {
   assert.equal(
     workflowTriggerDescription({ on: "message_posted" }),
diff --git a/desktop/src/features/workflows/ui/workflowTriggerDescription.ts b/desktop/src/features/workflows/ui/workflowTriggerDescription.ts
index 49d3842f97..51bba6c010 100644
--- a/desktop/src/features/workflows/ui/workflowTriggerDescription.ts
+++ b/desktop/src/features/workflows/ui/workflowTriggerDescription.ts
@@ -66,6 +66,53 @@ function textConditionDescription(
   }
 }
 
+export type WorkflowAuthorDescriptionSegments = {
+  prefix: string;
+  suffix: string;
+};
+
+/** Locate the generated author attribution without matching quoted user copy. */
+export function splitWorkflowAuthorDescription(
+  description: string,
+  label: string,
+): WorkflowAuthorDescriptionSegments | null {
+  const markers = [` by anyone except ${label}`, ` by ${label}`];
+
+  for (const marker of markers) {
+    let insideQuote = false;
+    for (
+      let index = 0;
+      index <= description.length - marker.length;
+      index += 1
+    ) {
+      const character = description[index];
+      if (character === "“") insideQuote = true;
+      if (character === "”") insideQuote = false;
+      if (!insideQuote && description.startsWith(marker, index)) {
+        const labelIndex = index + marker.length - label.length;
+        return {
+          prefix: description.slice(0, labelIndex).trimEnd(),
+          suffix: description.slice(labelIndex + label.length).trimStart(),
+        };
+      }
+    }
+  }
+
+  return null;
+}
+
+/** Remove a reaction value from compact copy when the node icon already shows it. */
+export function compactWorkflowTriggerDescription(
+  description: string,
+  triggerEmoji?: string,
+): string {
+  if (!triggerEmoji) return description;
+  const emojiPrefix = `${triggerEmoji} reaction added`;
+  return description.startsWith(emojiPrefix)
+    ? `Reaction added${description.slice(emojiPrefix.length)}`
+    : description;
+}
+
 /** Build the concise trigger summary rendered on the workflow canvas. */
 export function workflowTriggerDescription(
   trigger: TriggerConfig,
diff --git a/desktop/src/shared/api/tauri.ts b/desktop/src/shared/api/tauri.ts
index 9055a2a48a..6c5b59c983 100644
--- a/desktop/src/shared/api/tauri.ts
+++ b/desktop/src/shared/api/tauri.ts
@@ -43,6 +43,7 @@ import type {
 
 export * from "@/shared/api/tauriChannels";
 export { sendChannelMessage } from "@/shared/api/tauriMessages";
+export { getEventById, getEventsByIds } from "@/shared/api/tauriEvents";
 
 type RawPresenceLookup = Record<string, PresenceStatus>;
 
@@ -465,11 +466,6 @@ export async function searchMessages(
   };
 }
 
-export async function getEventById(eventId: string): Promise<RelayEvent> {
-  const eventJson = await invokeTauri<string>("get_event", { eventId });
-  return JSON.parse(eventJson) as RelayEvent;
-}
-
 type RawThreadCursor = {
   created_at: number;
   event_id: string;
diff --git a/desktop/src/shared/api/tauriEvents.ts b/desktop/src/shared/api/tauriEvents.ts
new file mode 100644
index 0000000000..7377c25e0c
--- /dev/null
+++ b/desktop/src/shared/api/tauriEvents.ts
@@ -0,0 +1,14 @@
+import { invokeTauri } from "@/shared/api/tauri";
+import type { RelayEvent } from "@/shared/api/types";
+
+export async function getEventById(eventId: string): Promise<RelayEvent> {
+  const eventJson = await invokeTauri<string>("get_event", { eventId });
+  return JSON.parse(eventJson) as RelayEvent;
+}
+
+export async function getEventsByIds(
+  eventIds: string[],
+): Promise<RelayEvent[]> {
+  if (eventIds.length === 0) return [];
+  return invokeTauri<RelayEvent[]>("get_events", { eventIds });
+}
diff --git a/desktop/src/testing/e2eBridge.ts b/desktop/src/testing/e2eBridge.ts
index 9002d751c8..5bbc160752 100644
--- a/desktop/src/testing/e2eBridge.ts
+++ b/desktop/src/testing/e2eBridge.ts
@@ -13585,6 +13585,15 @@ export function maybeInstallE2eTauriMocks() {
           payload as Parameters<typeof handleGetEvent>[0],
           activeConfig,
         );
+      case "get_events":
+        return Promise.all(
+          (payload as { eventIds: string[] }).eventIds.map(
+            async (eventId) =>
+              JSON.parse(
+                await handleGetEvent({ eventId }, activeConfig),
+              ) as RelayEvent,
+          ),
+        );
       case "sign_event":
         window.__BUZZ_E2E_SIGNED_EVENTS__?.push({
           content: (payload as { content: string }).content,
diff --git a/desktop/tests/e2e/workflow-local-controls.spec.ts b/desktop/tests/e2e/workflow-local-controls.spec.ts
index 2cdd1b28d7..6a8319082c 100644
--- a/desktop/tests/e2e/workflow-local-controls.spec.ts
+++ b/desktop/tests/e2e/workflow-local-controls.spec.ts
@@ -4,6 +4,15 @@ import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { waitForAnimations } from "../helpers/animations";
 import { installMockBridge } from "../helpers/bridge";
 
+declare global {
+  interface Window {
+    __BUZZ_WORKFLOW_BATCH_CALLS__?: {
+      eventBatches: number[];
+      userBatches: number[];
+    };
+  }
+}
+
 test.beforeEach(async ({ page }) => {
   await installMockBridge(page);
 });
@@ -419,6 +428,173 @@ test("renders deterministic trigger, step, and workflow-card summaries", async (
   ).toBeLessThan(0.5);
 });
 
+test("Escape closes a filter picker, restores disclosure focus, then closes its inspector", async ({
+  page,
+}) => {
+  for (const width of [760, 1280]) {
+    await page.setViewportSize({ width, height: 820 });
+    await page.goto(
+      "/#/workflows?view=create&channel=94a444a4-c0a3-5966-ab05-530c6ddc2301&pane=trigger",
+    );
+
+    const dialog = page.getByRole("dialog", { name: "Create workflow" });
+    const inspector = dialog.getByTestId("workflow-node-inspector");
+    await selectTrigger(page, dialog, "Reaction Added");
+    for (const field of [
+      {
+        label: "Author",
+        picker: "workflow-author-picker",
+        search: "Search authors or paste a public key",
+      },
+      {
+        label: "Message",
+        picker: "workflow-message-picker",
+        search: "Search messages or paste a message ID",
+      },
+    ]) {
+      const disclosure = dialog
+        .getByText(field.label, { exact: true })
+        .locator("..");
+      await disclosure.click();
+      const picker = dialog.getByTestId(field.picker);
+      const search = dialog.getByRole("combobox", { name: field.search });
+      await expect(picker).toBeVisible();
+
+      await search.press("Escape");
+      await expect(picker).toBeHidden();
+      await expect(disclosure).toBeFocused();
+      await expect(inspector).toBeVisible();
+    }
+
+    await page.keyboard.press("Escape");
+    await expect(inspector).toBeHidden();
+    await expect(dialog).toBeVisible();
+  }
+});
+
+test("workflow grid batches card author and message presentation reads", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.waitForFunction(
+    () => typeof window.__TAURI_INTERNALS__?.invoke === "function",
+  );
+  await page.evaluate(async () => {
+    const invoke = window.__TAURI_INTERNALS__?.invoke;
+    if (!invoke) throw new Error("mock invoke bridge unavailable");
+    for (let index = 0; index < 40; index += 1) {
+      const messageId = (index + 1).toString(16).padStart(64, "0");
+      const author = (index + 101).toString(16).padStart(64, "0");
+      await invoke("create_workflow", {
+        channelId: "94a444a4-c0a3-5966-ab05-530c6ddc2301",
+        yamlDefinition: JSON.stringify({
+          name: `batched_card_${index}`,
+          trigger: {
+            on: "reaction_added",
+            filter: `trigger_author == "${author}" && trigger_message_id == "${messageId}"`,
+          },
+          steps: [],
+        }),
+      });
+    }
+
+    const calls = { eventBatches: [], userBatches: [] };
+    window.__BUZZ_WORKFLOW_BATCH_CALLS__ = calls;
+    window.__TAURI_INTERNALS__.invoke = async (command, args) => {
+      if (command === "get_events") {
+        calls.eventBatches.push(
+          (args?.eventIds as unknown[] | undefined)?.length ?? 0,
+        );
+      }
+      if (command === "get_users_batch") {
+        calls.userBatches.push(
+          (args?.pubkeys as unknown[] | undefined)?.length ?? 0,
+        );
+      }
+      return invoke(command, args);
+    };
+  });
+
+  await page.getByTestId("open-workflows-view").click();
+  await expect(
+    page.locator('[data-testid^="workflow-card-mock-wf-"]'),
+  ).toHaveCount(40);
+  await expect
+    .poll(() =>
+      page.evaluate(() => {
+        const calls = window.__BUZZ_WORKFLOW_BATCH_CALLS__;
+        return {
+          eventBatchCount: calls?.eventBatches.filter((size) => size === 40)
+            .length,
+          userBatchCount: calls?.userBatches.filter((size) => size === 40)
+            .length,
+        };
+      }),
+    )
+    .toEqual({ eventBatchCount: 1, userBatchCount: 1 });
+});
+
+test("does not select stale picker results when Enter outruns deferred filtering", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.waitForFunction(
+    () => typeof window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__ === "function",
+  );
+  await page.evaluate(() => {
+    window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+      channelName: "agents",
+      content: "Deferred message candidate",
+      id: "d".repeat(64),
+    });
+  });
+  await page.getByTestId("open-workflows-view").click();
+  await page.getByRole("button", { name: "Create Workflow" }).click();
+  const dialog = page.getByRole("dialog", { name: "Create workflow" });
+  const channelList = page.getByTestId("channel-combobox-list");
+  if (!(await channelList.isVisible())) {
+    await dialog.getByRole("combobox", { name: "Channel" }).click();
+  }
+  await channelList
+    .getByRole("option", { name: "agents", exact: true })
+    .click();
+  await selectTrigger(page, dialog, "Reaction Added");
+
+  await dialog.getByText("Author", { exact: true }).locator("..").click();
+  const authorSearch = dialog.getByRole("combobox", {
+    name: "Search authors or paste a public key",
+  });
+  await expect(dialog.getByRole("option").first()).toBeVisible();
+  await authorSearch.evaluate((input: HTMLInputElement) => {
+    input.value = "no-such-author";
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+    input.dispatchEvent(
+      new KeyboardEvent("keydown", { bubbles: true, key: "Enter" }),
+    );
+  });
+
+  await dialog.getByText("Message", { exact: true }).locator("..").click();
+  const messageSearch = dialog.getByRole("combobox", {
+    name: "Search messages or paste a message ID",
+  });
+  await expect(
+    dialog.getByRole("option", { name: /Deferred message/ }),
+  ).toBeVisible();
+  await messageSearch.evaluate((input: HTMLInputElement) => {
+    input.value = "no-such-message";
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+    input.dispatchEvent(
+      new KeyboardEvent("keydown", { bubbles: true, key: "Enter" }),
+    );
+  });
+
+  await dialog.getByRole("tab", { name: "YAML" }).click();
+  const definition = parseYaml(
+    await dialog.getByRole("textbox", { name: "Workflow YAML" }).inputValue(),
+  );
+  expect(definition.trigger.filter).toBeUndefined();
+});
+
 test("round-trips manual author and reaction message IDs through save and reopen", async ({
   page,
 }) => {
@@ -431,26 +607,46 @@ test("round-trips manual author and reaction message IDs through save and reopen
   await dialog.getByRole("button", { name: /^Trigger:/ }).click();
   await openTriggerInspector(dialog);
 
-  await dialog.getByRole("button", { name: "Author pubkey" }).click();
-  await dialog.getByLabel("Author pubkey").fill("not-hex");
-  await expect(
-    dialog.getByText("Enter a 64-character hex pubkey."),
-  ).toBeVisible();
-  await expect(dialog.getByRole("button", { name: "Create" })).toBeDisabled();
+  await dialog.getByText("Author", { exact: true }).locator("..").click();
+  const authorResults = dialog.getByTestId("workflow-author-picker-results");
   await expect
     .poll(() =>
-      page.evaluate(
-        () =>
-          (window.__BUZZ_E2E_COMMAND_PAYLOADS__ ?? []).filter(
-            (call) => call.command === "create_workflow",
-          ).length,
-      ),
+      authorResults.evaluate((results) => {
+        const template = results.querySelector<HTMLElement>("[role=option]");
+        if (!template) return false;
+        for (let index = 0; index < 20; index += 1) {
+          const clone = template.cloneNode(true) as HTMLElement;
+          clone.dataset.scrollFixture = "true";
+          clone.removeAttribute("id");
+          results.append(clone);
+        }
+        return results.scrollHeight > results.clientHeight;
+      }),
     )
-    .toBe(0);
-  await dialog.getByLabel("Author pubkey").fill(author);
+    .toBe(true);
+  await authorResults.hover();
+  await page.mouse.wheel(0, 240);
+  await expect
+    .poll(() => authorResults.evaluate((node) => node.scrollTop))
+    .toBeGreaterThan(0);
+  await authorResults.evaluate((results) => {
+    for (const fixture of results.querySelectorAll("[data-scroll-fixture]")) {
+      fixture.remove();
+    }
+    results.scrollTop = 0;
+  });
+  const authorSearch = dialog.getByRole("combobox", {
+    name: "Search authors or paste a public key",
+  });
+  await authorSearch.fill(author);
+  await expect(
+    dialog.getByRole("option", { name: new RegExp(author.slice(0, 8)) }),
+  ).toBeVisible();
+  await authorSearch.press("Enter");
+  await expect(
+    dialog.getByRole("option", { name: new RegExp(author.slice(0, 8)) }),
+  ).toHaveAttribute("aria-selected", "true");
   await expect(dialog.getByRole("button", { name: "Create" })).toBeEnabled();
-  await dialog.getByLabel("Author pubkey").fill("still-not-hex");
-  await expect(dialog.getByRole("button", { name: "Create" })).toBeDisabled();
   await dialog.getByRole("tab", { name: "YAML" }).click();
   const correctionEditor = dialog.getByRole("textbox", {
     name: "Workflow YAML",
@@ -461,16 +657,29 @@ test("round-trips manual author and reaction message IDs through save and reopen
   await expect(dialog.getByRole("button", { name: "Create" })).toBeEnabled();
   await dialog.getByRole("tab", { name: "Form" }).click();
   await openTriggerInspector(dialog);
-  await dialog.getByRole("button", { name: "Author pubkey" }).click();
-  await expect(dialog.getByLabel("Author pubkey")).toHaveValue("");
-  await dialog.getByLabel("Author pubkey").fill(author);
+  await dialog.getByText("Author", { exact: true }).locator("..").click();
+  const correctedAuthorSearch = dialog.getByRole("combobox", {
+    name: "Search authors or paste a public key",
+  });
+  await correctedAuthorSearch.fill(author);
+  await expect(
+    dialog.getByRole("option", { name: new RegExp(author.slice(0, 8)) }),
+  ).toBeVisible();
+  await correctedAuthorSearch.press("Enter");
   await dialog
     .getByRole("group", { name: "Match" })
     .getByRole("button", { name: "is not", exact: true })
     .click();
 
-  await dialog.getByRole("button", { name: "Message event ID" }).click();
-  await dialog.getByLabel("Message event ID").fill(messageId);
+  await dialog.getByText("Message", { exact: true }).locator("..").click();
+  const messageSearch = dialog.getByRole("combobox", {
+    name: "Search messages or paste a message ID",
+  });
+  await messageSearch.fill(messageId);
+  await messageSearch.press("Enter");
+  await expect(
+    dialog.getByRole("option", { name: new RegExp(messageId.slice(0, 12)) }),
+  ).toHaveAttribute("aria-selected", "true");
 
   await dialog.getByRole("tab", { name: "YAML" }).click();
   const yamlEditor = dialog.getByRole("textbox", { name: "Workflow YAML" });
@@ -486,10 +695,16 @@ test("round-trips manual author and reaction message IDs through save and reopen
 
   const reopened = await reopenWorkflow(page, name);
   await openTriggerInspector(reopened);
-  await reopened.getByRole("button", { name: "Author pubkey" }).click();
-  await expect(reopened.getByLabel("Author pubkey")).toHaveValue(author);
-  await reopened.getByRole("button", { name: "Message event ID" }).click();
-  await expect(reopened.getByLabel("Message event ID")).toHaveValue(messageId);
+  await reopened.getByText("Author", { exact: true }).locator("..").click();
+  await expect(
+    reopened.getByRole("option", { name: new RegExp(author.slice(0, 8)) }),
+  ).toHaveAttribute("aria-selected", "true");
+  await reopened.getByText("Message", { exact: true }).locator("..").click();
+  await expect(
+    reopened.getByRole("option", {
+      name: new RegExp(messageId.slice(0, 12)),
+    }),
+  ).toHaveAttribute("aria-selected", "true");
   await reopened.getByRole("tab", { name: "YAML" }).click();
   definition = parseYaml(
     await reopened.getByRole("textbox", { name: "Workflow YAML" }).inputValue(),
@@ -497,6 +712,96 @@ test("round-trips manual author and reaction message IDs through save and reopen
   expect(definition.trigger.filter).toContain(messageId);
 });
 
+test("toggles selected author and message filters while preserving sibling conditions", async ({
+  page,
+}) => {
+  const author = "a".repeat(64);
+  const replacementAuthor = "c".repeat(64);
+  const messageId = "b".repeat(64);
+  const dialog = await openCreateWorkflow(
+    page,
+    `toggle_trigger_ids_${Date.now()}`,
+  );
+  await selectTrigger(page, dialog, "Reaction Added");
+  await dialog.getByRole("tab", { name: "YAML" }).click();
+  const yamlEditor = dialog.getByRole("textbox", { name: "Workflow YAML" });
+  const definition = parseYaml(await yamlEditor.inputValue());
+  definition.trigger.filter =
+    `trigger_emoji == "👍" && trigger_author == "${author.toUpperCase()}" && ` +
+    `trigger_message_id == "${messageId.toUpperCase()}"`;
+  await yamlEditor.fill(stringifyYaml(definition));
+  await dialog.getByRole("tab", { name: "Form" }).click();
+  await openTriggerInspector(dialog);
+  const authorField = dialog
+    .getByText("Author", { exact: true })
+    .locator("..")
+    .locator("..");
+  await authorField.getByText("Author", { exact: true }).locator("..").click();
+  const authorOption = dialog.getByRole("option", {
+    name: new RegExp(author.slice(0, 8)),
+  });
+  await expect(authorOption).toHaveAttribute("aria-selected", "true");
+  await expect(
+    authorField.getByRole("button", { name: "Clear filter" }),
+  ).toHaveCount(0);
+  await authorOption.click();
+
+  const authorSearch = dialog.getByRole("combobox", {
+    name: "Search authors or paste a public key",
+  });
+  await authorSearch.fill(replacementAuthor);
+  const replacementAuthorOption = dialog.getByRole("option", {
+    name: new RegExp(replacementAuthor.slice(0, 8)),
+  });
+  await expect(replacementAuthorOption).toBeVisible();
+  await authorSearch.press("Enter");
+  await expect(replacementAuthorOption).toHaveAttribute(
+    "aria-selected",
+    "true",
+  );
+  await expect(authorSearch).toHaveValue(replacementAuthor);
+  await authorSearch.press("Enter");
+  await expect(authorSearch).toHaveValue(replacementAuthor);
+
+  const messageField = dialog
+    .getByText("Message", { exact: true })
+    .locator("..")
+    .locator("..");
+  await messageField
+    .getByText("Message", { exact: true })
+    .locator("..")
+    .click();
+  const messageSearch = dialog.getByRole("combobox", {
+    name: "Search messages or paste a message ID",
+  });
+  await expect(
+    dialog.getByRole("option", { name: new RegExp(messageId.slice(0, 12)) }),
+  ).toHaveAttribute("aria-selected", "true");
+  await expect(
+    messageField.getByRole("button", { name: "Clear filter" }),
+  ).toHaveCount(0);
+  await messageSearch.fill(messageId);
+  await messageSearch.press("Enter");
+  await expect(messageSearch).toHaveValue(messageId);
+  await messageSearch.press("Enter");
+  const selectedMessage = dialog.getByRole("option", {
+    name: new RegExp(messageId.slice(0, 12)),
+  });
+  await expect(selectedMessage).toHaveAttribute("aria-selected", "true");
+  await selectedMessage.click();
+  await expect(messageSearch).toHaveValue(messageId);
+
+  await dialog.getByRole("button", { name: "Reaction emoji" }).click();
+  await expect(
+    dialog.getByRole("button", { name: "Clear filter" }),
+  ).toBeVisible();
+
+  await dialog.getByRole("tab", { name: "YAML" }).click();
+  expect(parseYaml(await yamlEditor.inputValue()).trigger.filter).toBe(
+    'trigger_emoji == "👍"',
+  );
+});
+
 test("hides and clears message-text step conditions for schedule triggers", async ({
   page,
 }) => {

From 8d2d0ff5ad42733e9949442c4b6358d0ba87f9a8 Mon Sep 17 00:00:00 2001
From: Luke Tornquist <tornquist@squareup.com>
Date: Mon, 24 Aug 2026 20:42:15 -0400
Subject: [PATCH 8/9] Centralize replaceable event persistence (#6660)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Why
Command persistence duplicated NIP-33 replacement SQL in the relay and
obscured the boundary between database runtime concerns and domain-store
behavior. This proving slice establishes that boundary inside the
existing `buzz-db` crate.

## What
- Centralize parameterized-replaceable coordinate locking, ordering,
replacement, watermark, and mention-indexing behavior in `buzz-db`
- Expose transaction-required replacement and ordinary-insertion seams
while keeping transaction ownership and workflow conflict messages in
the relay
- Cover concurrency, same-second ties, stale writes, replay, caller
rollback, nested rollback recovery, and mention-index atomicity with
focused PostgreSQL tests

## Risk Assessment
Medium — this changes core event persistence and command idempotency
paths, while intentionally preserving NIP-33, NIP-RS, mesh, and workflow
conflict semantics.

## References
- Architecture guardrail:
https://github.com/TheSentinel454/buzz/issues/34
- Proving slice: https://github.com/TheSentinel454/buzz/issues/3,
https://github.com/TheSentinel454/buzz/issues/4,
https://github.com/TheSentinel454/buzz/issues/6

Generated with Codex

---------

Signed-off-by: tornquist <tornquist@squareup.com>
---
 .github/workflows/ci.yml                      |  13 +
 crates/buzz-db/src/channel.rs                 |   2 +-
 crates/buzz-db/src/event.rs                   |  53 +-
 crates/buzz-db/src/lib.rs                     | 747 +++++++++++-------
 crates/buzz-db/src/replaceable.rs             | 417 ++++++++++
 .../src/handlers/command_executor.rs          | 370 +++++----
 6 files changed, 1140 insertions(+), 462 deletions(-)
 create mode 100644 crates/buzz-db/src/replaceable.rs

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a87ea957cd..8016766812 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -679,6 +679,19 @@ jobs:
           VALUES ('00000000-0000-4000-8000-00000000c0de', 'localhost:3000')
           ON CONFLICT (lower(host)) DO NOTHING
           ;"
+      - name: Replaceable persistence PostgreSQL tests
+        # Transaction, concurrency, and mention-index coverage for the
+        # replaceable-event store seam. These tests require real Postgres and
+        # are ignored by the infrastructure-free unit-test job.
+        run: |
+          filter='package(buzz-db) and test(/tests::(parameterized_|concurrent_parameterized_)/)'
+          cargo nextest run \
+            --archive-file target/ci/backend-integration-tests.tar.zst \
+            -E "${filter}" \
+            --run-ignored ignored-only
+        env:
+          DATABASE_URL: postgres://buzz:${{ env.BUZZ_TEST_POSTGRES_PASSWORD }}@localhost:5432/buzz
+          TEST_DATABASE_URL: postgres://buzz:${{ env.BUZZ_TEST_POSTGRES_PASSWORD }}@localhost:5432/buzz
       - name: Start relay
         run: |
           chmod +x ./target/ci/buzz-relay
diff --git a/crates/buzz-db/src/channel.rs b/crates/buzz-db/src/channel.rs
index 109a9367d7..a1890adb56 100644
--- a/crates/buzz-db/src/channel.rs
+++ b/crates/buzz-db/src/channel.rs
@@ -625,7 +625,7 @@ pub async fn lock_member_snapshot(
     // this key before INSERT; migration 0032 then takes the membership key in
     // the INSERT trigger. Taking both in that order avoids mixed-version
     // duplicate heads without introducing a lock-order inversion.
-    let replacement_lock = crate::event_replacement_lock_key(
+    let replacement_lock = crate::replaceable::event_replacement_lock_key(
         community_id,
         39002,
         relay_pubkey,
diff --git a/crates/buzz-db/src/event.rs b/crates/buzz-db/src/event.rs
index 5d682d7843..dcfc97c844 100644
--- a/crates/buzz-db/src/event.rs
+++ b/crates/buzz-db/src/event.rs
@@ -6,7 +6,7 @@
 
 use chrono::{DateTime, Utc};
 use nostr::Event;
-use sqlx::{PgPool, Postgres, QueryBuilder, Row, Transaction};
+use sqlx::{PgConnection, PgPool, Postgres, QueryBuilder, Row, Transaction};
 use uuid::Uuid;
 
 use buzz_core::kind::{
@@ -275,6 +275,30 @@ pub async fn insert_event(
     community_id: CommunityId,
     event: &Event,
     channel_id: Option<Uuid>,
+) -> Result<(StoredEvent, bool)> {
+    let mut connection = pool.acquire().await?;
+    insert_event_on(&mut connection, community_id, event, channel_id).await
+}
+
+/// Insert a Nostr event in a caller-owned PostgreSQL transaction.
+///
+/// This is the transaction-composition seam for callers that must keep the
+/// event insert open while performing related work. The caller owns commit or
+/// rollback.
+pub async fn insert_event_in_transaction(
+    tx: &mut Transaction<'_, Postgres>,
+    community_id: CommunityId,
+    event: &Event,
+    channel_id: Option<Uuid>,
+) -> Result<(StoredEvent, bool)> {
+    insert_event_on(tx.as_mut(), community_id, event, channel_id).await
+}
+
+async fn insert_event_on(
+    connection: &mut PgConnection,
+    community_id: CommunityId,
+    event: &Event,
+    channel_id: Option<Uuid>,
 ) -> Result<(StoredEvent, bool)> {
     let kind_u16 = event.kind.as_u16();
     let kind_u32 = u32::from(kind_u16);
@@ -317,7 +341,7 @@ pub async fn insert_event(
     .bind(channel_id)
     .bind(d_tag.as_deref())
     .bind(not_before)
-    .execute(pool)
+    .execute(connection)
     .await?;
 
     let was_inserted = result.rows_affected() > 0;
@@ -1607,6 +1631,31 @@ mod tests {
         id
     }
 
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn event_insert_in_existing_transaction_rolls_back_with_caller() {
+        let pool = setup_pool().await;
+        let community_uuid = make_test_community(&pool).await;
+        let community = CommunityId::from_uuid(community_uuid);
+        let event = make_text_event("caller-owned transaction");
+
+        let mut tx = pool.begin().await.expect("begin event insert transaction");
+        let (_, was_inserted) = insert_event_in_transaction(&mut tx, community, &event, None)
+            .await
+            .expect("insert event in caller transaction");
+        assert!(was_inserted);
+        tx.rollback().await.expect("roll back event insert");
+
+        let persisted: i64 =
+            sqlx::query_scalar("SELECT count(*) FROM events WHERE community_id = $1 AND id = $2")
+                .bind(community_uuid)
+                .bind(event.id.as_bytes().as_slice())
+                .fetch_one(&pool)
+                .await
+                .expect("count rolled-back event");
+        assert_eq!(persisted, 0);
+    }
+
     #[tokio::test]
     #[ignore = "requires Postgres"]
     async fn event_insert_ttl_trigger_handles_permanent_ephemeral_duplicate_and_activation_race() {
diff --git a/crates/buzz-db/src/lib.rs b/crates/buzz-db/src/lib.rs
index 3ff230f950..cbce6d3753 100644
--- a/crates/buzz-db/src/lib.rs
+++ b/crates/buzz-db/src/lib.rs
@@ -8,6 +8,21 @@
 //! - Events table is partitioned by month on `created_at`.
 //! - No FK references to partitioned tables.
 //! - Uses `sqlx::query()` (runtime) not `sqlx::query!()` (compile-time).
+//!
+//! ## Runtime and store ownership
+//! This crate intentionally keeps database runtime and Buzz domain persistence
+//! together while maintaining an internal boundary between them:
+//!
+//! - Runtime concerns own pool construction, writer/replica routing, transaction
+//!   creation, session invariants, metrics, and health support.
+//! - Store concerns own domain-specific SQL, row mapping, locking, mutation
+//!   rules, indexes, and focused persistence tests.
+//!
+//! Transaction-required store operations accept [`sqlx::Transaction`] so their
+//! composition requirement is visible in the type. Private connection helpers
+//! are reserved for SQL primitives that are valid on any same-session
+//! connection. New domains should prove this boundary incrementally instead of
+//! exposing raw pools or introducing broad store traits.
 
 /// Explicit deployment-global admin report reads.
 pub mod admin_moderation;
@@ -45,6 +60,8 @@ pub mod reaction;
 pub mod relay_invite;
 /// Relay-level membership persistence (NIP-43).
 pub mod relay_members;
+/// Replaceable-event persistence and coordinate locking.
+pub mod replaceable;
 /// Replica freshness fence for keyset-cursor read routing.
 pub mod replica_fence;
 /// Thread metadata persistence.
@@ -68,37 +85,12 @@ use uuid::Uuid;
 
 use buzz_core::{CommunityId, StoredEvent};
 
-pub(crate) fn event_replacement_lock_key(
-    community_id: CommunityId,
-    kind: i32,
-    pubkey: &[u8],
-    coordinate: Option<&[u8]>,
-) -> i64 {
-    let mut hash: u64 = 0xcbf29ce484222325;
-    let kind_bytes = kind.to_le_bytes();
-    for bytes in [
-        community_id.as_uuid().as_bytes().as_slice(),
-        kind_bytes.as_slice(),
-        pubkey,
-    ] {
-        for byte in bytes {
-            hash ^= *byte as u64;
-            hash = hash.wrapping_mul(0x100000001b3);
-        }
-    }
-    if let Some(coordinate) = coordinate {
-        for byte in coordinate {
-            hash ^= *byte as u64;
-            hash = hash.wrapping_mul(0x100000001b3);
-        }
-    }
-    hash as i64
-}
-
 /// Extract p-tag mentions from an event and insert into the `event_mentions` table.
 ///
-/// Called after event insertion. Failures are logged but do not block event storage.
-/// Uses `INSERT ... ON CONFLICT DO NOTHING` so duplicate inserts are silently skipped.
+/// This pool-owning wrapper propagates failures to its caller. Replacement writes
+/// use the transaction-bound helper below so event storage and mention indexing
+/// commit or roll back together. Duplicate inserts are silently skipped with
+/// `INSERT ... ON CONFLICT DO NOTHING`.
 pub async fn insert_mentions(
     pool: &PgPool,
     community_id: CommunityId,
@@ -4875,7 +4867,7 @@ impl Db {
             .ok_or(DbError::InvalidTimestamp(created_at_secs))?;
 
         // Collisions only cause extra serialization; they cannot change behavior.
-        let lock_key = event_replacement_lock_key(
+        let lock_key = replaceable::event_replacement_lock_key(
             community_id,
             kind_i32,
             pubkey_bytes.as_slice(),
@@ -5058,8 +5050,12 @@ impl Db {
         let kind_i32 = buzz_core::kind::KIND_NIP43_MEMBERSHIP_LIST as i32;
         let pubkey_bytes = relay_keypair.public_key().to_bytes();
 
-        let lock_key =
-            event_replacement_lock_key(community_id, kind_i32, pubkey_bytes.as_slice(), None);
+        let lock_key = replaceable::event_replacement_lock_key(
+            community_id,
+            kind_i32,
+            pubkey_bytes.as_slice(),
+            None,
+        );
 
         let mut tx = self.pool.begin().await?;
 
@@ -5166,243 +5162,6 @@ impl Db {
             member_count,
         ))
     }
-
-    /// Atomically replace a NIP-33 parameterized replaceable event (kind 30000–39999).
-    ///
-    /// Keeps only the event with the highest `created_at` per `(kind, pubkey, d_tag)`.
-    /// Same-second ties are broken by lowest event `id` (deterministic ordering).
-    /// The entire check → retire old payload → insert runs in a single transaction
-    /// with an advisory lock to prevent concurrent-insert races. NIP-RS read-state
-    /// coordinates hard-delete the superseded payload and preserve a compact
-    /// ordering watermark. Buzz mesh status coordinates also hard-delete their
-    /// superseded heartbeat payload because only the live head has product
-    /// value; other NIP-33 kinds retain soft-deleted history.
-    ///
-    /// **Channel policy:** NIP-33 replacement keys on `(kind, pubkey, d_tag)` globally —
-    /// `channel_id` is NOT part of the replacement key. This matches the Nostr spec:
-    /// an author's parameterized replaceable event is a single global resource identified
-    /// by its d-tag, regardless of which channel it was submitted to. The `channel_id`
-    /// parameter is stored on the new row for query scoping but does not affect replacement.
-    ///
-    /// Note: `replace_addressable_event()` keys on `channel_id` because it serves
-    /// relay-signed NIP-29 group metadata (kind 39000–39002) where the relay is the
-    /// author and channel_id distinguishes groups. User-submitted NIP-33 events use
-    /// this function instead, where the author's pubkey + d-tag is the natural key.
-    #[datastore_span(name = "replace_parameterized_event", system = "postgresql")]
-    pub async fn replace_parameterized_event(
-        &self,
-        community_id: CommunityId,
-        event: &nostr::Event,
-        d_tag: &str,
-        channel_id: Option<Uuid>,
-    ) -> Result<(StoredEvent, bool)> {
-        let kind_i32 = buzz_core::kind::event_kind_i32(event);
-        let pubkey_bytes = event.pubkey.to_bytes();
-        let created_at_secs = event.created_at.as_secs() as i64;
-        let created_at = chrono::DateTime::from_timestamp(created_at_secs, 0)
-            .ok_or(DbError::InvalidTimestamp(created_at_secs))?;
-
-        let lock_key = event_replacement_lock_key(
-            community_id,
-            kind_i32,
-            pubkey_bytes.as_slice(),
-            Some(d_tag.as_bytes()),
-        );
-
-        let mut tx = self.pool.begin().await?;
-
-        sqlx::query("SELECT pg_advisory_xact_lock($1)")
-            .bind(lock_key)
-            .execute(&mut *tx)
-            .await?;
-
-        let d_tag_count = event
-            .tags
-            .iter()
-            .filter(|tag| tag.as_slice().first().is_some_and(|part| part == "d"))
-            .count();
-        let has_exact_d_tag = event.tags.iter().any(|tag| {
-            let parts = tag.as_slice();
-            parts.len() >= 2 && parts[0] == "d" && parts[1] == d_tag
-        });
-        let read_state_t_tag_count = event
-            .tags
-            .iter()
-            .filter(|tag| {
-                let parts = tag.as_slice();
-                parts.len() == 2 && parts[0] == "t" && parts[1] == "read-state"
-            })
-            .count();
-        let is_nip_rs = kind_i32 == buzz_core::kind::KIND_READ_STATE as i32
-            && d_tag_count == 1
-            && has_exact_d_tag
-            && d_tag.strip_prefix("read-state:").is_some_and(|slot| {
-                slot.len() == 32
-                    && slot
-                        .bytes()
-                        .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase())
-            })
-            && read_state_t_tag_count == 1;
-        let is_buzz_mesh_status = kind_i32 == buzz_core::kind::KIND_BOOKMARK_SET as i32
-            && d_tag.starts_with("buzz-mesh-member-status:")
-            && event.tags.iter().any(|tag| {
-                let parts = tag.as_slice();
-                parts.len() == 2 && parts[0] == "k" && parts[1] == "buzz-mesh-status"
-            });
-        let hard_delete_superseded = is_nip_rs || is_buzz_mesh_status;
-
-        // Check the live head and, for NIP-RS, the compact historical ordering
-        // watermark. The watermark remains after a NIP-09 coordinate deletion,
-        // preventing a previously accepted signed blob from being resurrected.
-        let existing: Option<(chrono::DateTime<chrono::Utc>, Vec<u8>)> = sqlx::query_as(
-            "SELECT created_at, id FROM events \
-             WHERE community_id = $1 AND kind = $2 AND pubkey = $3 AND d_tag = $4 AND deleted_at IS NULL \
-             ORDER BY created_at DESC, id ASC LIMIT 1",
-        )
-        .bind(community_id.as_uuid())
-        .bind(kind_i32)
-        .bind(pubkey_bytes.as_slice())
-        .bind(d_tag)
-        .fetch_optional(&mut *tx)
-        .await?;
-        let watermark: Option<(chrono::DateTime<chrono::Utc>, Vec<u8>)> = if is_nip_rs {
-            sqlx::query_as(
-                "SELECT created_at, event_id FROM parameterized_event_watermarks \
-                 WHERE community_id = $1 AND kind = $2 AND pubkey = $3 AND d_tag = $4",
-            )
-            .bind(community_id.as_uuid())
-            .bind(kind_i32)
-            .bind(pubkey_bytes.as_slice())
-            .bind(d_tag)
-            .fetch_optional(&mut *tx)
-            .await?
-        } else {
-            None
-        };
-
-        // Stale-write protection: reject if either durable ordering source
-        // dominates the incoming tuple. Equal timestamps use lowest event id.
-        let incoming_id = event.id.as_bytes().as_slice();
-        let dominated =
-            existing
-                .iter()
-                .chain(watermark.iter())
-                .any(|(accepted_ts, accepted_id)| {
-                    created_at < *accepted_ts
-                        || (created_at == *accepted_ts && incoming_id >= accepted_id.as_slice())
-                });
-        if dominated {
-            tx.rollback().await?;
-            let received_at = chrono::Utc::now();
-            return Ok((
-                StoredEvent::with_received_at(event.clone(), received_at, channel_id, false),
-                false,
-            ));
-        }
-
-        if existing.is_some() {
-            if is_nip_rs {
-                // Migration 0011 rejects regex-coordinate hard deletes from
-                // pre-fix writers. Authorize only this corrected NIP-RS delete,
-                // transaction-locally so pooled connections cannot leak it.
-                sqlx::query("SELECT set_config('buzz.nip_rs_hard_delete', 'on', true)")
-                    .execute(&mut *tx)
-                    .await?;
-            }
-            let statement = if hard_delete_superseded {
-                "DELETE FROM events \
-                 WHERE community_id = $1 AND kind = $2 AND pubkey = $3 AND d_tag = $4 AND deleted_at IS NULL"
-            } else {
-                "UPDATE events SET deleted_at = NOW() \
-                 WHERE community_id = $1 AND kind = $2 AND pubkey = $3 AND d_tag = $4 AND deleted_at IS NULL"
-            };
-            sqlx::query(statement)
-                .bind(community_id.as_uuid())
-                .bind(kind_i32)
-                .bind(pubkey_bytes.as_slice())
-                .bind(d_tag)
-                .execute(&mut *tx)
-                .await?;
-
-            if hard_delete_superseded {
-                if let Some((_, existing_id)) = &existing {
-                    // Event first, mentions second: migration 0009's live-event
-                    // fence uses this global lock order to avoid deadlocks.
-                    sqlx::query(
-                        "DELETE FROM event_mentions WHERE community_id = $1 AND event_id = $2",
-                    )
-                    .bind(community_id.as_uuid())
-                    .bind(existing_id)
-                    .execute(&mut *tx)
-                    .await?;
-                }
-            }
-        }
-
-        // Insert the new event inside the transaction.
-        let sig_bytes = event.sig.serialize();
-        let tags_json = serde_json::to_value(&event.tags)?;
-        let received_at = chrono::Utc::now();
-
-        let insert_result = sqlx::query(
-            "INSERT INTO events (community_id, id, pubkey, created_at, kind, tags, content, sig, received_at, channel_id, d_tag, not_before) \
-             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12) \
-             ON CONFLICT DO NOTHING",
-        )
-        .bind(community_id.as_uuid())
-        .bind(event.id.as_bytes().as_slice())
-        .bind(pubkey_bytes.as_slice())
-        .bind(created_at)
-        .bind(kind_i32)
-        .bind(&tags_json)
-        .bind(&event.content)
-        .bind(sig_bytes.as_slice())
-        .bind(received_at)
-        .bind(channel_id)
-        .bind(d_tag)
-        .bind(event::extract_not_before(event))
-        .execute(&mut *tx)
-        .await?;
-
-        let was_inserted = insert_result.rows_affected() > 0;
-        if !was_inserted {
-            tx.rollback().await?;
-            return Ok((
-                StoredEvent::with_received_at(event.clone(), received_at, channel_id, false),
-                false,
-            ));
-        }
-
-        if is_nip_rs {
-            sqlx::query(
-                "INSERT INTO parameterized_event_watermarks \
-                     (community_id, kind, pubkey, d_tag, created_at, event_id) \
-                 VALUES ($1, $2, $3, $4, $5, $6) \
-                 ON CONFLICT (community_id, kind, pubkey, d_tag) DO UPDATE SET \
-                     created_at = EXCLUDED.created_at, event_id = EXCLUDED.event_id",
-            )
-            .bind(community_id.as_uuid())
-            .bind(kind_i32)
-            .bind(pubkey_bytes.as_slice())
-            .bind(d_tag)
-            .bind(created_at)
-            .bind(incoming_id)
-            .execute(&mut *tx)
-            .await?;
-        }
-
-        tx.commit().await?;
-
-        // Mentions are a denormalized index — safe outside the transaction.
-        if let Err(e) = crate::insert_mentions(&self.pool, community_id, event, channel_id).await {
-            tracing::warn!(event_id = %event.id, "Failed to insert mentions: {e}");
-        }
-
-        Ok((
-            StoredEvent::with_received_at(event.clone(), received_at, channel_id, true),
-            true,
-        ))
-    }
 }
 
 /// A full API token record.
@@ -6014,6 +5773,456 @@ mod tests {
         assert_eq!(live, 0, "watermark must block stale resurrection");
     }
 
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn nip_rs_transaction_operation_restores_hard_delete_opt_in() {
+        use nostr::{EventBuilder, Keys, Kind, Tag, Timestamp};
+
+        let db = setup_db().await;
+        let community = CommunityId::from_uuid(make_community(&db.pool).await);
+        let keys = Keys::generate();
+        let base = Timestamp::now().as_secs();
+        let replace_d_tag = format!("read-state:{}", "b".repeat(32));
+        let victim_d_tag = format!("read-state:{}", "c".repeat(32));
+        let event = |d_tag: &str, content: &str, timestamp: u64| {
+            EventBuilder::new(
+                Kind::Custom(buzz_core::kind::KIND_READ_STATE as u16),
+                content,
+            )
+            .tags(vec![
+                Tag::parse(["d", d_tag]).expect("d tag"),
+                Tag::parse(["t", "read-state"]).expect("t tag"),
+            ])
+            .custom_created_at(Timestamp::from(timestamp))
+            .sign_with_keys(&keys)
+            .expect("sign read state")
+        };
+        let old = event(&replace_d_tag, "old", base);
+        let new = event(&replace_d_tag, "new", base + 1);
+        let victim = event(&victim_d_tag, "victim", base);
+
+        assert!(
+            db.replace_parameterized_event(community, &old, &replace_d_tag, None)
+                .await
+                .expect("insert old head")
+                .1
+        );
+        assert!(
+            db.replace_parameterized_event(community, &victim, &victim_d_tag, None)
+                .await
+                .expect("insert victim head")
+                .1
+        );
+
+        let mut tx = db
+            .begin_transaction()
+            .await
+            .expect("begin caller transaction");
+        let result = db
+            .replace_parameterized_event_in_transaction(
+                &mut tx,
+                community,
+                &new,
+                &replace_d_tag,
+                None,
+                replaceable::ParameterizedReplacePrecondition::Unconditional,
+            )
+            .await
+            .expect("replace inside caller transaction");
+        assert_eq!(
+            result.status,
+            replaceable::ParameterizedReplaceStatus::Inserted
+        );
+
+        let leaked: Option<String> = sqlx::query_scalar(
+            "SELECT NULLIF(current_setting('buzz.nip_rs_hard_delete', true), '')",
+        )
+        .fetch_one(&mut *tx)
+        .await
+        .expect("read hard-delete opt-in after replacement");
+        assert_ne!(leaked.as_deref(), Some("on"));
+
+        let unauthorized = sqlx::query(
+            "DELETE FROM events WHERE community_id=$1 AND kind=30078 \
+             AND pubkey=$2 AND d_tag=$3 AND deleted_at IS NULL",
+        )
+        .bind(community.as_uuid())
+        .bind(keys.public_key().to_bytes())
+        .bind(&victim_d_tag)
+        .execute(&mut *tx)
+        .await;
+        assert!(
+            unauthorized.is_err(),
+            "replacement opt-in must not authorize later caller SQL"
+        );
+        tx.rollback().await.expect("roll back caller transaction");
+    }
+
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn parameterized_replacement_in_existing_transaction_honors_revision_and_rollback() {
+        use nostr::{EventBuilder, Keys, Kind, Tag, Timestamp};
+
+        let db = setup_db().await;
+        let community = CommunityId::from_uuid(make_community(&db.pool).await);
+        let keys = Keys::generate();
+        let d_tag = format!("transactional-project-{}", Uuid::new_v4().simple());
+        let base = Timestamp::now().as_secs();
+        let event = |content: &str, timestamp: u64| {
+            EventBuilder::new(Kind::Custom(buzz_core::kind::KIND_PROJECT as u16), content)
+                .tags(vec![Tag::parse(["d", d_tag.as_str()]).expect("d tag")])
+                .custom_created_at(Timestamp::from(timestamp))
+                .sign_with_keys(&keys)
+                .expect("sign project")
+        };
+        let old = event("old", base);
+        let new = event("new", base + 1);
+
+        assert!(
+            db.replace_parameterized_event(community, &old, &d_tag, None)
+                .await
+                .expect("insert old head")
+                .1
+        );
+
+        let mut tx = db.begin_transaction().await.expect("begin replacement tx");
+        let outcome = db
+            .replace_parameterized_event_in_transaction(
+                &mut tx,
+                community,
+                &new,
+                &d_tag,
+                None,
+                replaceable::ParameterizedReplacePrecondition::ExpectedRevision(
+                    old.id.as_bytes().as_slice(),
+                ),
+            )
+            .await
+            .expect("replace inside caller transaction");
+        assert_eq!(
+            outcome.status,
+            replaceable::ParameterizedReplaceStatus::Inserted
+        );
+        tx.rollback().await.expect("roll back replacement tx");
+
+        let live_id: Vec<u8> = sqlx::query_scalar(
+            "SELECT id FROM events WHERE community_id=$1 AND kind=$2 AND pubkey=$3 \
+             AND d_tag=$4 AND deleted_at IS NULL",
+        )
+        .bind(community.as_uuid())
+        .bind(buzz_core::kind::KIND_PROJECT as i32)
+        .bind(keys.public_key().to_bytes())
+        .bind(&d_tag)
+        .fetch_one(&db.pool)
+        .await
+        .expect("load live head after rollback");
+        assert_eq!(live_id, old.id.as_bytes().to_vec());
+
+        let mut tx = db
+            .begin_transaction()
+            .await
+            .expect("begin stale revision tx");
+        let mismatch = db
+            .replace_parameterized_event_in_transaction(
+                &mut tx,
+                community,
+                &new,
+                &d_tag,
+                None,
+                replaceable::ParameterizedReplacePrecondition::ExpectedRevision(
+                    [0x42; 32].as_slice(),
+                ),
+            )
+            .await
+            .expect("evaluate stale revision");
+        assert_eq!(
+            mismatch.status,
+            replaceable::ParameterizedReplaceStatus::RevisionMismatch
+        );
+        tx.rollback().await.expect("roll back stale revision tx");
+
+        let missing_d_tag = format!("missing-project-{}", Uuid::new_v4().simple());
+        let missing = EventBuilder::new(
+            Kind::Custom(buzz_core::kind::KIND_PROJECT as u16),
+            "missing",
+        )
+        .tags(vec![
+            Tag::parse(["d", missing_d_tag.as_str()]).expect("missing d tag")
+        ])
+        .custom_created_at(Timestamp::from(base + 2))
+        .sign_with_keys(&keys)
+        .expect("sign missing project");
+        let mut tx = db
+            .begin_transaction()
+            .await
+            .expect("begin missing revision tx");
+        let missing_result = db
+            .replace_parameterized_event_in_transaction(
+                &mut tx,
+                community,
+                &missing,
+                &missing_d_tag,
+                None,
+                replaceable::ParameterizedReplacePrecondition::ExpectedRevision(
+                    [0x24; 32].as_slice(),
+                ),
+            )
+            .await
+            .expect("evaluate missing revision");
+        assert_eq!(
+            missing_result.status,
+            replaceable::ParameterizedReplaceStatus::RevisionMissing
+        );
+        tx.rollback().await.expect("roll back missing revision tx");
+    }
+
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn parameterized_replacement_rolls_back_when_mention_indexing_fails() {
+        use nostr::{EventBuilder, Keys, Kind, Tag, Timestamp};
+
+        let admin = PgPool::connect(&admin_url().await)
+            .await
+            .expect("connect admin");
+        let (pool, scratch_name) = create_scratch_db(&admin, "atomic_parameterized").await;
+        let db = Db::from_pool(pool.clone());
+        let community = CommunityId::from_uuid(make_community(&pool).await);
+        let keys = Keys::generate();
+        let mentioned = Keys::generate().public_key().to_hex();
+        let d_tag = format!("mention-project-{}", Uuid::new_v4().simple());
+        let tags = || {
+            vec![
+                Tag::parse(["d", d_tag.as_str()]).expect("d tag"),
+                Tag::parse(["p", mentioned.as_str()]).expect("p tag"),
+            ]
+        };
+        let base = Timestamp::now().as_secs();
+        let old = EventBuilder::new(Kind::Custom(buzz_core::kind::KIND_PROJECT as u16), "old")
+            .tags(tags())
+            .custom_created_at(Timestamp::from(base))
+            .sign_with_keys(&keys)
+            .expect("sign old project");
+        let new = EventBuilder::new(Kind::Custom(buzz_core::kind::KIND_PROJECT as u16), "new")
+            .tags(tags())
+            .custom_created_at(Timestamp::from(base + 1))
+            .sign_with_keys(&keys)
+            .expect("sign new project");
+
+        assert!(
+            db.replace_parameterized_event(community, &old, &d_tag, None)
+                .await
+                .expect("insert old project")
+                .1
+        );
+        sqlx::query(
+            "CREATE FUNCTION reject_test_mention() RETURNS trigger AS $$ \
+             BEGIN RAISE EXCEPTION 'injected mention failure'; END; \
+             $$ LANGUAGE plpgsql",
+        )
+        .execute(&pool)
+        .await
+        .expect("create failure function");
+        sqlx::query(
+            "CREATE TRIGGER reject_test_mention BEFORE INSERT ON event_mentions \
+             FOR EACH ROW EXECUTE FUNCTION reject_test_mention()",
+        )
+        .execute(&pool)
+        .await
+        .expect("install failure injection");
+
+        let mut tx = db
+            .begin_transaction()
+            .await
+            .expect("begin caller transaction");
+        let error = db
+            .replace_parameterized_event_in_transaction(
+                &mut tx,
+                community,
+                &new,
+                &d_tag,
+                None,
+                replaceable::ParameterizedReplacePrecondition::Unconditional,
+            )
+            .await
+            .expect_err("mention failure must fail replacement");
+        assert!(error.to_string().contains("injected mention failure"));
+
+        let probe: i32 = sqlx::query_scalar("SELECT 1")
+            .fetch_one(&mut *tx)
+            .await
+            .expect("inner failure must leave caller transaction usable");
+        assert_eq!(probe, 1);
+
+        let live_id: Vec<u8> = sqlx::query_scalar(
+            "SELECT id FROM events WHERE community_id=$1 AND kind=$2 AND pubkey=$3 \
+             AND d_tag=$4 AND deleted_at IS NULL",
+        )
+        .bind(community.as_uuid())
+        .bind(buzz_core::kind::KIND_PROJECT as i32)
+        .bind(keys.public_key().to_bytes())
+        .bind(&d_tag)
+        .fetch_one(&mut *tx)
+        .await
+        .expect("load live project after failed indexing");
+        assert_eq!(live_id, old.id.as_bytes().to_vec());
+        let new_rows: i64 =
+            sqlx::query_scalar("SELECT count(*) FROM events WHERE community_id=$1 AND id=$2")
+                .bind(community.as_uuid())
+                .bind(new.id.as_bytes().as_slice())
+                .fetch_one(&mut *tx)
+                .await
+                .expect("count rolled-back project");
+        assert_eq!(new_rows, 0);
+        tx.commit().await.expect("commit usable caller transaction");
+
+        drop_scratch_db(&admin, pool, &scratch_name).await;
+    }
+
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn parameterized_duplicate_restores_live_head_inside_caller_transaction() {
+        use nostr::{EventBuilder, Keys, Kind, Tag, Timestamp};
+
+        let db = setup_db().await;
+        let community = CommunityId::from_uuid(make_community(&db.pool).await);
+        let keys = Keys::generate();
+        let d_tag = format!("duplicate-project-{}", Uuid::new_v4().simple());
+        let base = Timestamp::now().as_secs();
+        let event = |content: &str, timestamp: u64| {
+            EventBuilder::new(Kind::Custom(buzz_core::kind::KIND_PROJECT as u16), content)
+                .tags(vec![Tag::parse(["d", d_tag.as_str()]).expect("d tag")])
+                .custom_created_at(Timestamp::from(timestamp))
+                .sign_with_keys(&keys)
+                .expect("sign project")
+        };
+        let old = event("old-live-head", base);
+        let duplicate = event("soft-deleted-duplicate", base + 1);
+
+        assert!(
+            db.replace_parameterized_event(community, &duplicate, &d_tag, None)
+                .await
+                .expect("insert future duplicate")
+                .1
+        );
+        sqlx::query("UPDATE events SET deleted_at=NOW() WHERE community_id=$1 AND id=$2")
+            .bind(community.as_uuid())
+            .bind(duplicate.id.as_bytes().as_slice())
+            .execute(&db.pool)
+            .await
+            .expect("soft-delete duplicate row");
+
+        let mut seed_tx = db
+            .begin_transaction()
+            .await
+            .expect("begin seed transaction");
+        let (_, was_inserted) =
+            event::insert_event_in_transaction(&mut seed_tx, community, &old, None)
+                .await
+                .expect("insert older live head");
+        assert!(was_inserted);
+        seed_tx.commit().await.expect("commit older live head");
+
+        let mut tx = db
+            .begin_transaction()
+            .await
+            .expect("begin caller transaction");
+        let result = db
+            .replace_parameterized_event_in_transaction(
+                &mut tx,
+                community,
+                &duplicate,
+                &d_tag,
+                None,
+                replaceable::ParameterizedReplacePrecondition::Unconditional,
+            )
+            .await
+            .expect("evaluate soft-deleted duplicate");
+        assert_eq!(
+            result.status,
+            replaceable::ParameterizedReplaceStatus::Duplicate
+        );
+
+        let live_id: Vec<u8> = sqlx::query_scalar(
+            "SELECT id FROM events WHERE community_id=$1 AND kind=$2 AND pubkey=$3 \
+             AND d_tag=$4 AND deleted_at IS NULL",
+        )
+        .bind(community.as_uuid())
+        .bind(buzz_core::kind::KIND_PROJECT as i32)
+        .bind(keys.public_key().to_bytes())
+        .bind(&d_tag)
+        .fetch_one(&mut *tx)
+        .await
+        .expect("caller transaction remains usable after duplicate");
+        assert_eq!(live_id, old.id.as_bytes().to_vec());
+        tx.rollback().await.expect("roll back caller transaction");
+    }
+
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn concurrent_parameterized_replacement_keeps_deterministic_head() {
+        use nostr::{EventBuilder, Keys, Kind, Tag, Timestamp};
+
+        let db = setup_db().await;
+        let community = CommunityId::from_uuid(make_community(&db.pool).await);
+        let keys = Keys::generate();
+        let d_tag = format!("concurrent-project-{}", Uuid::new_v4().simple());
+        let created_at = Timestamp::now().as_secs();
+        let event = |content: &str, timestamp: u64| {
+            EventBuilder::new(Kind::Custom(buzz_core::kind::KIND_PROJECT as u16), content)
+                .tags(vec![Tag::parse(["d", d_tag.as_str()]).expect("d tag")])
+                .custom_created_at(Timestamp::from(timestamp))
+                .sign_with_keys(&keys)
+                .expect("sign project")
+        };
+        let first = event("first", created_at);
+        let second = event("second", created_at);
+        let expected = if first.id.as_bytes() < second.id.as_bytes() {
+            &first
+        } else {
+            &second
+        };
+
+        let (first_result, second_result) = tokio::join!(
+            db.replace_parameterized_event(community, &first, &d_tag, None),
+            db.replace_parameterized_event(community, &second, &d_tag, None),
+        );
+        let first_inserted = first_result.expect("first concurrent writer").1;
+        let second_inserted = second_result.expect("second concurrent writer").1;
+        assert!(
+            first_inserted || second_inserted,
+            "at least one concurrent writer must insert",
+        );
+
+        let live_ids: Vec<Vec<u8>> = sqlx::query_scalar(
+            "SELECT id FROM events WHERE community_id=$1 AND kind=$2 AND pubkey=$3 \
+             AND d_tag=$4 AND deleted_at IS NULL",
+        )
+        .bind(community.as_uuid())
+        .bind(buzz_core::kind::KIND_PROJECT as i32)
+        .bind(keys.public_key().to_bytes())
+        .bind(&d_tag)
+        .fetch_all(&db.pool)
+        .await
+        .expect("load concurrent live head");
+        assert_eq!(live_ids, vec![expected.id.as_bytes().to_vec()]);
+
+        assert!(
+            !db.replace_parameterized_event(community, expected, &d_tag, None)
+                .await
+                .expect("replay winning event")
+                .1,
+            "replaying the live event must be idempotent",
+        );
+        let stale = event("stale", created_at.saturating_sub(1));
+        assert!(
+            !db.replace_parameterized_event(community, &stale, &d_tag, None)
+                .await
+                .expect("submit stale event")
+                .1,
+            "an older event must not replace the live head",
+        );
+    }
+
     #[tokio::test]
     #[ignore = "requires Postgres"]
     async fn mesh_status_replacement_keeps_one_physical_row() {
diff --git a/crates/buzz-db/src/replaceable.rs b/crates/buzz-db/src/replaceable.rs
new file mode 100644
index 0000000000..aa57a51666
--- /dev/null
+++ b/crates/buzz-db/src/replaceable.rs
@@ -0,0 +1,417 @@
+//! Replaceable-event persistence and coordinate locking.
+
+use buzz_core::{CommunityId, StoredEvent};
+use buzz_datastore_tracing::datastore_span;
+use chrono::{DateTime, Utc};
+use sqlx::{Acquire, Postgres, Transaction};
+use uuid::Uuid;
+
+use crate::{Db, DbError, Result};
+
+/// Result category for a parameterized-replaceable event write.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ParameterizedReplaceStatus {
+    /// The incoming event was inserted as the coordinate's live head.
+    Inserted,
+    /// The exact event was already accepted.
+    Duplicate,
+    /// A newer event, or lower-ID same-second event, already dominates it.
+    Superseded,
+    /// A requested current revision has no live coordinate head.
+    RevisionMissing,
+    /// The live coordinate head differs from the requested revision.
+    RevisionMismatch,
+    /// An exact replay was required, but the event is not the live head.
+    ReplayOnlyMiss,
+}
+
+/// Structural precondition for a parameterized-replaceable write.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ParameterizedReplacePrecondition<'a> {
+    /// Apply normal NIP-33 ordering without a revision precondition.
+    Unconditional,
+    /// Require the live head to match this validated event ID.
+    ExpectedRevision(&'a [u8]),
+    /// Accept only an exact live-head replay and perform no mutation otherwise.
+    ExactReplayOnly,
+}
+
+/// Result of a transaction-bound parameterized-replaceable event write.
+#[derive(Clone, Debug)]
+pub struct ParameterizedReplaceResult {
+    /// Stored representation of the submitted event.
+    pub event: StoredEvent,
+    /// Whether and why the coordinate accepted the event.
+    pub status: ParameterizedReplaceStatus,
+}
+
+impl ParameterizedReplaceResult {
+    fn new(
+        event: &nostr::Event,
+        received_at: DateTime<Utc>,
+        channel_id: Option<Uuid>,
+        status: ParameterizedReplaceStatus,
+    ) -> Self {
+        Self {
+            event: StoredEvent::with_received_at(
+                event.clone(),
+                received_at,
+                channel_id,
+                status == ParameterizedReplaceStatus::Inserted,
+            ),
+            status,
+        }
+    }
+}
+
+/// Derive the transaction-scoped advisory-lock key for an event coordinate.
+///
+/// Hash collisions only add serialization; the SQL predicates still determine
+/// which rows are read or changed.
+pub(crate) fn event_replacement_lock_key(
+    community_id: CommunityId,
+    kind: i32,
+    pubkey: &[u8],
+    coordinate: Option<&[u8]>,
+) -> i64 {
+    let mut hash: u64 = 0xcbf29ce484222325;
+    let kind_bytes = kind.to_le_bytes();
+    for bytes in [
+        community_id.as_uuid().as_bytes().as_slice(),
+        kind_bytes.as_slice(),
+        pubkey,
+    ] {
+        for byte in bytes {
+            hash ^= *byte as u64;
+            hash = hash.wrapping_mul(0x100000001b3);
+        }
+    }
+    if let Some(coordinate) = coordinate {
+        for byte in coordinate {
+            hash ^= *byte as u64;
+            hash = hash.wrapping_mul(0x100000001b3);
+        }
+    }
+    hash as i64
+}
+
+/// Replace a parameterized event in a caller-owned transaction.
+///
+/// This function acquires a transaction-scoped advisory lock but never commits
+/// or rolls back the outer transaction. The typed precondition can require the
+/// current live head to have an exact event ID or restrict the operation to an
+/// idempotent replay.
+async fn replace_parameterized_event_in_transaction_impl(
+    tx: &mut Transaction<'_, Postgres>,
+    community_id: CommunityId,
+    event: &nostr::Event,
+    d_tag: &str,
+    channel_id: Option<Uuid>,
+    precondition: ParameterizedReplacePrecondition<'_>,
+) -> Result<ParameterizedReplaceResult> {
+    let kind_i32 = buzz_core::kind::event_kind_i32(event);
+    let pubkey_bytes = event.pubkey.to_bytes();
+    let created_at_secs = event.created_at.as_secs() as i64;
+    let created_at = DateTime::from_timestamp(created_at_secs, 0)
+        .ok_or(DbError::InvalidTimestamp(created_at_secs))?;
+    let received_at = Utc::now();
+
+    let lock_key = event_replacement_lock_key(
+        community_id,
+        kind_i32,
+        pubkey_bytes.as_slice(),
+        Some(d_tag.as_bytes()),
+    );
+    sqlx::query("SELECT pg_advisory_xact_lock($1)")
+        .bind(lock_key)
+        .execute(&mut **tx)
+        .await?;
+
+    let d_tag_count = event
+        .tags
+        .iter()
+        .filter(|tag| tag.as_slice().first().is_some_and(|part| part == "d"))
+        .count();
+    let has_exact_d_tag = event.tags.iter().any(|tag| {
+        let parts = tag.as_slice();
+        parts.len() >= 2 && parts[0] == "d" && parts[1] == d_tag
+    });
+    let read_state_t_tag_count = event
+        .tags
+        .iter()
+        .filter(|tag| {
+            let parts = tag.as_slice();
+            parts.len() == 2 && parts[0] == "t" && parts[1] == "read-state"
+        })
+        .count();
+    let is_nip_rs = kind_i32 == buzz_core::kind::KIND_READ_STATE as i32
+        && d_tag_count == 1
+        && has_exact_d_tag
+        && d_tag.strip_prefix("read-state:").is_some_and(|slot| {
+            slot.len() == 32
+                && slot
+                    .bytes()
+                    .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase())
+        })
+        && read_state_t_tag_count == 1;
+    let is_buzz_mesh_status = kind_i32 == buzz_core::kind::KIND_BOOKMARK_SET as i32
+        && d_tag.starts_with("buzz-mesh-member-status:")
+        && event.tags.iter().any(|tag| {
+            let parts = tag.as_slice();
+            parts.len() == 2 && parts[0] == "k" && parts[1] == "buzz-mesh-status"
+        });
+    let hard_delete_superseded = is_nip_rs || is_buzz_mesh_status;
+
+    let existing: Option<(DateTime<Utc>, Vec<u8>)> = sqlx::query_as(
+        "SELECT created_at, id FROM events \
+         WHERE community_id = $1 AND kind = $2 AND pubkey = $3 AND d_tag = $4 AND deleted_at IS NULL \
+         ORDER BY created_at DESC, id ASC LIMIT 1",
+    )
+    .bind(community_id.as_uuid())
+    .bind(kind_i32)
+    .bind(pubkey_bytes.as_slice())
+    .bind(d_tag)
+    .fetch_optional(&mut **tx)
+    .await?;
+    let watermark: Option<(DateTime<Utc>, Vec<u8>)> = if is_nip_rs {
+        sqlx::query_as(
+            "SELECT created_at, event_id FROM parameterized_event_watermarks \
+             WHERE community_id = $1 AND kind = $2 AND pubkey = $3 AND d_tag = $4",
+        )
+        .bind(community_id.as_uuid())
+        .bind(kind_i32)
+        .bind(pubkey_bytes.as_slice())
+        .bind(d_tag)
+        .fetch_optional(&mut **tx)
+        .await?
+    } else {
+        None
+    };
+
+    let incoming_id = event.id.as_bytes().as_slice();
+    if existing
+        .as_ref()
+        .is_some_and(|(_, existing_id)| existing_id.as_slice() == incoming_id)
+        || watermark
+            .as_ref()
+            .is_some_and(|(_, event_id)| event_id.as_slice() == incoming_id)
+    {
+        return Ok(ParameterizedReplaceResult::new(
+            event,
+            received_at,
+            channel_id,
+            ParameterizedReplaceStatus::Duplicate,
+        ));
+    }
+
+    if precondition == ParameterizedReplacePrecondition::ExactReplayOnly {
+        return Ok(ParameterizedReplaceResult::new(
+            event,
+            received_at,
+            channel_id,
+            ParameterizedReplaceStatus::ReplayOnlyMiss,
+        ));
+    }
+
+    if let ParameterizedReplacePrecondition::ExpectedRevision(expected_revision) = precondition {
+        let status = match existing.as_ref() {
+            None => Some(ParameterizedReplaceStatus::RevisionMissing),
+            Some((_, existing_id)) if existing_id.as_slice() != expected_revision => {
+                Some(ParameterizedReplaceStatus::RevisionMismatch)
+            }
+            Some(_) => None,
+        };
+        if let Some(status) = status {
+            return Ok(ParameterizedReplaceResult::new(
+                event,
+                received_at,
+                channel_id,
+                status,
+            ));
+        }
+    }
+
+    let dominated = existing
+        .iter()
+        .chain(watermark.iter())
+        .any(|(accepted_ts, accepted_id)| {
+            created_at < *accepted_ts
+                || (created_at == *accepted_ts && incoming_id >= accepted_id.as_slice())
+        });
+    if dominated {
+        return Ok(ParameterizedReplaceResult::new(
+            event,
+            received_at,
+            channel_id,
+            ParameterizedReplaceStatus::Superseded,
+        ));
+    }
+
+    let mut savepoint = tx.begin().await?;
+    if existing.is_some() {
+        let previous_nip_rs_hard_delete: Option<String> = if is_nip_rs {
+            sqlx::query_scalar(
+                "SELECT NULLIF(current_setting('buzz.nip_rs_hard_delete', true), '')",
+            )
+            .fetch_one(&mut *savepoint)
+            .await?
+        } else {
+            None
+        };
+        if is_nip_rs {
+            sqlx::query("SELECT set_config('buzz.nip_rs_hard_delete', 'on', true)")
+                .execute(&mut *savepoint)
+                .await?;
+        }
+        let statement = if hard_delete_superseded {
+            "DELETE FROM events \
+             WHERE community_id = $1 AND kind = $2 AND pubkey = $3 AND d_tag = $4 AND deleted_at IS NULL"
+        } else {
+            "UPDATE events SET deleted_at = NOW() \
+             WHERE community_id = $1 AND kind = $2 AND pubkey = $3 AND d_tag = $4 AND deleted_at IS NULL"
+        };
+        sqlx::query(statement)
+            .bind(community_id.as_uuid())
+            .bind(kind_i32)
+            .bind(pubkey_bytes.as_slice())
+            .bind(d_tag)
+            .execute(&mut *savepoint)
+            .await?;
+
+        if is_nip_rs {
+            let previous_value = previous_nip_rs_hard_delete.as_deref().unwrap_or_default();
+            sqlx::query("SELECT set_config('buzz.nip_rs_hard_delete', $1, true)")
+                .bind(previous_value)
+                .execute(&mut *savepoint)
+                .await?;
+        }
+
+        if hard_delete_superseded {
+            if let Some((_, existing_id)) = &existing {
+                sqlx::query("DELETE FROM event_mentions WHERE community_id = $1 AND event_id = $2")
+                    .bind(community_id.as_uuid())
+                    .bind(existing_id)
+                    .execute(&mut *savepoint)
+                    .await?;
+            }
+        }
+    }
+
+    let sig_bytes = event.sig.serialize();
+    let tags_json = serde_json::to_value(&event.tags)?;
+    let insert_result = sqlx::query(
+        "INSERT INTO events (community_id, id, pubkey, created_at, kind, tags, content, sig, received_at, channel_id, d_tag, not_before) \
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12) \
+         ON CONFLICT DO NOTHING",
+    )
+    .bind(community_id.as_uuid())
+    .bind(incoming_id)
+    .bind(pubkey_bytes.as_slice())
+    .bind(created_at)
+    .bind(kind_i32)
+    .bind(&tags_json)
+    .bind(&event.content)
+    .bind(sig_bytes.as_slice())
+    .bind(received_at)
+    .bind(channel_id)
+    .bind(d_tag)
+    .bind(crate::event::extract_not_before(event))
+    .execute(&mut *savepoint)
+    .await?;
+
+    if insert_result.rows_affected() == 0 {
+        savepoint.rollback().await?;
+        return Ok(ParameterizedReplaceResult::new(
+            event,
+            received_at,
+            channel_id,
+            ParameterizedReplaceStatus::Duplicate,
+        ));
+    }
+
+    if is_nip_rs {
+        sqlx::query(
+            "INSERT INTO parameterized_event_watermarks \
+                 (community_id, kind, pubkey, d_tag, created_at, event_id) \
+             VALUES ($1, $2, $3, $4, $5, $6) \
+             ON CONFLICT (community_id, kind, pubkey, d_tag) DO UPDATE SET \
+                 created_at = EXCLUDED.created_at, event_id = EXCLUDED.event_id",
+        )
+        .bind(community_id.as_uuid())
+        .bind(kind_i32)
+        .bind(pubkey_bytes.as_slice())
+        .bind(d_tag)
+        .bind(created_at)
+        .bind(incoming_id)
+        .execute(&mut *savepoint)
+        .await?;
+    }
+
+    crate::insert_mentions_in_transaction(&mut savepoint, community_id, event, channel_id).await?;
+    savepoint.commit().await?;
+
+    Ok(ParameterizedReplaceResult::new(
+        event,
+        received_at,
+        channel_id,
+        ParameterizedReplaceStatus::Inserted,
+    ))
+}
+
+impl Db {
+    /// Replace a NIP-33 event inside a caller-owned transaction.
+    ///
+    /// The caller owns commit or rollback. Requiring [`Transaction`] here and
+    /// in the internal state machine makes the advisory-lock contract explicit.
+    pub async fn replace_parameterized_event_in_transaction(
+        &self,
+        tx: &mut Transaction<'_, Postgres>,
+        community_id: CommunityId,
+        event: &nostr::Event,
+        d_tag: &str,
+        channel_id: Option<Uuid>,
+        precondition: ParameterizedReplacePrecondition<'_>,
+    ) -> Result<ParameterizedReplaceResult> {
+        replace_parameterized_event_in_transaction_impl(
+            tx,
+            community_id,
+            event,
+            d_tag,
+            channel_id,
+            precondition,
+        )
+        .await
+    }
+
+    /// Atomically replace a NIP-33 parameterized replaceable event.
+    ///
+    /// Replacement keys on `(kind, pubkey, d_tag)` across channels. The
+    /// highest timestamp wins; same-second ties use the lowest event ID.
+    #[datastore_span(name = "replace_parameterized_event", system = "postgresql")]
+    pub async fn replace_parameterized_event(
+        &self,
+        community_id: CommunityId,
+        event: &nostr::Event,
+        d_tag: &str,
+        channel_id: Option<Uuid>,
+    ) -> Result<(StoredEvent, bool)> {
+        let mut tx = self.pool.begin().await?;
+        let result = self
+            .replace_parameterized_event_in_transaction(
+                &mut tx,
+                community_id,
+                event,
+                d_tag,
+                channel_id,
+                ParameterizedReplacePrecondition::Unconditional,
+            )
+            .await?;
+        let was_inserted = result.status == ParameterizedReplaceStatus::Inserted;
+        if was_inserted {
+            tx.commit().await?;
+        } else {
+            tx.rollback().await?;
+        }
+        Ok((result.event, was_inserted))
+    }
+}
diff --git a/crates/buzz-relay/src/handlers/command_executor.rs b/crates/buzz-relay/src/handlers/command_executor.rs
index d8569a7a86..007db43ffd 100644
--- a/crates/buzz-relay/src/handlers/command_executor.rs
+++ b/crates/buzz-relay/src/handlers/command_executor.rs
@@ -105,8 +105,9 @@ async fn persist_command_event(
     event: &Event,
     channel_id_override: Option<Uuid>,
 ) -> Result<PersistResult, IngestError> {
-    let channel_id = channel_id_override.or_else(|| extract_channel_id(event));
+    use buzz_db::replaceable::{ParameterizedReplacePrecondition, ParameterizedReplaceStatus};
 
+    let channel_id = channel_id_override.or_else(|| extract_channel_id(event));
     let mut tx = db
         .begin_transaction()
         .await
@@ -118,22 +119,8 @@ async fn persist_command_event(
             IngestError::Rejected(format!("restricted: community writes are fenced: {error}"))
         })?;
 
-    // INSERT with ON CONFLICT DO NOTHING — idempotency guard.
-    let id_bytes = event.id.as_bytes();
-    let pubkey_bytes = event.pubkey.to_bytes();
-    let sig_bytes = event.sig.serialize();
-    let tags_json = serde_json::to_value(&event.tags)
-        .map_err(|e| IngestError::Internal(format!("error: serialize tags: {e}")))?;
-    let kind_i32 = event.kind.as_u16() as i32;
-    let created_at_secs = event.created_at.as_secs() as i64;
-    let created_at = chrono::DateTime::from_timestamp(created_at_secs, 0).ok_or_else(|| {
-        IngestError::Rejected(format!("invalid: bad timestamp {created_at_secs}"))
-    })?;
-    let received_at = chrono::Utc::now();
-
-    // Extract d_tag for parameterized replaceable kinds (NIP-33).
     let d_tag = buzz_db::event::extract_d_tag(event);
-    if let Some(ref d_tag) = d_tag {
+    if let Some(d_tag) = d_tag.as_deref() {
         if d_tag.len() > buzz_db::event::D_TAG_MAX_LEN {
             return Err(IngestError::Rejected(format!(
                 "invalid: d tag too long ({} bytes, max {})",
@@ -142,130 +129,81 @@ async fn persist_command_event(
             )));
         }
 
-        // Command kinds normally use plain insert semantics, but workflow
-        // definitions are NIP-33 events. Serialize writers for the same
-        // coordinate and reject stale writes before executing the domain
-        // mutation, otherwise old updates can overwrite newer workflow state.
-        let lock_key = {
-            let mut h: u64 = 0xcbf29ce484222325;
-            for b in tenant.community().as_uuid().as_bytes() {
-                h ^= *b as u64;
-                h = h.wrapping_mul(0x100000001b3);
-            }
-            for b in kind_i32.to_le_bytes() {
-                h ^= b as u64;
-                h = h.wrapping_mul(0x100000001b3);
-            }
-            for b in pubkey_bytes.as_slice() {
-                h ^= *b as u64;
-                h = h.wrapping_mul(0x100000001b3);
-            }
-            for b in d_tag.as_bytes() {
-                h ^= *b as u64;
-                h = h.wrapping_mul(0x100000001b3);
-            }
-            h as i64
+        let kind = event.kind.as_u16() as i32;
+        let (expected_revision, revision_error) = match parse_expected_workflow_revision(
+            kind,
+            extract_tag(event, "expected-revision").as_deref(),
+        ) {
+            Ok(expected_revision) => (expected_revision, None),
+            Err(error) => (None, Some(error)),
         };
-
-        sqlx::query("SELECT pg_advisory_xact_lock($1)")
-            .bind(lock_key)
-            .execute(tx.as_mut())
-            .await
-            .map_err(|e| IngestError::Internal(format!("error: lock event coordinate: {e}")))?;
-
-        let existing: Option<(chrono::DateTime<chrono::Utc>, Vec<u8>)> = sqlx::query_as(
-            "SELECT created_at, id FROM events \
-             WHERE community_id = $1 AND kind = $2 AND pubkey = $3 AND d_tag = $4 AND deleted_at IS NULL \
-             ORDER BY created_at DESC, id ASC LIMIT 1",
-        )
-        .bind(tenant.community().as_uuid())
-        .bind(kind_i32)
-        .bind(pubkey_bytes.as_slice())
-        .bind(d_tag)
-        .fetch_optional(tx.as_mut())
-        .await
-        .map_err(|e| IngestError::Internal(format!("error: query event coordinate: {e}")))?;
-
-        let incoming_id = event.id.as_bytes().as_slice();
-        if existing
-            .as_ref()
-            .is_some_and(|(_, existing_id)| existing_id.as_slice() == incoming_id)
-        {
-            return Ok(PersistResult::Duplicate);
-        }
-
-        let expected_revision = extract_tag(event, "expected-revision");
-        validate_workflow_revision(
-            kind_i32,
-            expected_revision.as_deref(),
-            existing.as_ref().map(|(_, id)| id.as_slice()),
-        )?;
-        if let Some((existing_ts, existing_id)) = existing {
-            let dominated = created_at < existing_ts
-                || (created_at == existing_ts && incoming_id >= existing_id.as_slice());
-            if dominated {
-                if kind_i32 == KIND_WORKFLOW_DEF as i32 && expected_revision.is_some() {
-                    return Err(IngestError::Rejected(
-                        "conflict: workflow update was superseded; refresh and try again".into(),
-                    ));
-                }
-                return Ok(PersistResult::Duplicate);
-            }
-
-            sqlx::query(
-                "UPDATE events SET deleted_at = NOW() \
-                 WHERE community_id = $1 AND kind = $2 AND pubkey = $3 AND d_tag = $4 AND deleted_at IS NULL",
+        let precondition = if revision_error.is_some() {
+            ParameterizedReplacePrecondition::ExactReplayOnly
+        } else if let Some(expected_revision) = expected_revision.as_deref() {
+            ParameterizedReplacePrecondition::ExpectedRevision(expected_revision)
+        } else {
+            ParameterizedReplacePrecondition::Unconditional
+        };
+        let result = db
+            .replace_parameterized_event_in_transaction(
+                &mut tx,
+                tenant.community(),
+                event,
+                d_tag,
+                channel_id,
+                precondition,
             )
-            .bind(tenant.community().as_uuid())
-            .bind(kind_i32)
-            .bind(pubkey_bytes.as_slice())
-            .bind(d_tag)
-            .execute(tx.as_mut())
             .await
-            .map_err(|e| IngestError::Internal(format!("error: replace old event: {e}")))?;
-        }
+            .map_err(|e| {
+                IngestError::Internal(format!("error: replace parameterized event: {e}"))
+            })?;
+
+        return match result.status {
+            ParameterizedReplaceStatus::Inserted => Ok(PersistResult::Inserted(tx)),
+            ParameterizedReplaceStatus::Duplicate => Ok(PersistResult::Duplicate),
+            ParameterizedReplaceStatus::Superseded
+                if kind == KIND_WORKFLOW_DEF as i32 && expected_revision.is_some() =>
+            {
+                Err(IngestError::Rejected(
+                    "conflict: workflow update was superseded; refresh and try again".into(),
+                ))
+            }
+            ParameterizedReplaceStatus::Superseded => Ok(PersistResult::Duplicate),
+            ParameterizedReplaceStatus::RevisionMissing => Err(IngestError::Rejected(
+                "conflict: workflow revision does not exist".into(),
+            )),
+            ParameterizedReplaceStatus::RevisionMismatch => Err(IngestError::Rejected(
+                "conflict: workflow changed since it was loaded".into(),
+            )),
+            ParameterizedReplaceStatus::ReplayOnlyMiss => match revision_error {
+                Some(error) => Err(error),
+                None => Err(IngestError::Internal(
+                    "error: replay-only replacement lacked a revision error".into(),
+                )),
+            },
+        };
     }
 
-    let result = sqlx::query(
-        r#"
-        INSERT INTO events (community_id, id, pubkey, created_at, kind, tags, content, sig, received_at, channel_id, d_tag)
-        VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
-        ON CONFLICT DO NOTHING
-        "#,
-    )
-    .bind(tenant.community().as_uuid())
-    .bind(id_bytes.as_slice())
-    .bind(pubkey_bytes.as_slice())
-    .bind(created_at)
-    .bind(kind_i32)
-    .bind(&tags_json)
-    .bind(&event.content)
-    .bind(sig_bytes.as_slice())
-    .bind(received_at)
-    .bind(channel_id)
-    .bind(d_tag.as_deref())
-    .execute(tx.as_mut())
-    .await
-    .map_err(|e| IngestError::Internal(format!("error: insert event: {e}")))?;
-
-    if result.rows_affected() == 0 {
-        // Duplicate — rollback (implicit on drop) and signal idempotent success.
-        Ok(PersistResult::Duplicate)
-    } else {
+    let (_, was_inserted) =
+        buzz_db::event::insert_event_in_transaction(&mut tx, tenant.community(), event, channel_id)
+            .await
+            .map_err(|e| IngestError::Internal(format!("error: insert event: {e}")))?;
+    if was_inserted {
         Ok(PersistResult::Inserted(tx))
+    } else {
+        Ok(PersistResult::Duplicate)
     }
 }
 
-fn validate_workflow_revision(
+fn parse_expected_workflow_revision(
     kind: i32,
     expected_revision: Option<&str>,
-    existing_id: Option<&[u8]>,
-) -> Result<(), IngestError> {
+) -> Result<Option<Vec<u8>>, IngestError> {
     if kind != KIND_WORKFLOW_DEF as i32 {
-        return Ok(());
+        return Ok(None);
     }
 
-    let expected_id = expected_revision
+    expected_revision
         .map(|expected| {
             let id = hex::decode(expected).map_err(|_| {
                 IngestError::Rejected("invalid: bad expected workflow revision".into())
@@ -277,18 +215,7 @@ fn validate_workflow_revision(
             }
             Ok(id)
         })
-        .transpose()?;
-
-    match (expected_id.as_deref(), existing_id) {
-        (None, _) => Ok(()),
-        (Some(_), None) => Err(IngestError::Rejected(
-            "conflict: workflow revision does not exist".into(),
-        )),
-        (Some(expected), Some(existing)) if expected != existing => Err(IngestError::Rejected(
-            "conflict: workflow changed since it was loaded".into(),
-        )),
-        (Some(_), Some(_)) => Ok(()),
-    }
+        .transpose()
 }
 
 /// Extract all `p` tag values (hex pubkeys) from an event.
@@ -425,7 +352,7 @@ async fn handle_dm_open(
         .await
         .map_err(|e| IngestError::Internal(format!("error: db open_dm: {e}")))?;
 
-    // Commit: event + mutation succeeded atomically.
+    // Finalize the idempotency record after the separate mutation succeeds.
     tx.commit()
         .await
         .map_err(|e| IngestError::Internal(format!("error: commit transaction: {e}")))?;
@@ -586,7 +513,7 @@ async fn handle_dm_add_member(
         .await
         .map_err(|e| IngestError::Internal(format!("error: db open_dm: {e}")))?;
 
-    // Commit: event + mutation succeeded atomically.
+    // Finalize the idempotency record after the separate mutation succeeds.
     tx.commit()
         .await
         .map_err(|e| IngestError::Internal(format!("error: commit transaction: {e}")))?;
@@ -691,7 +618,7 @@ async fn handle_dm_hide(
         .await
         .map_err(|e| IngestError::Internal(format!("error: db hide_dm: {e}")))?;
 
-    // Commit: event + mutation succeeded atomically.
+    // Finalize the idempotency record after the separate mutation succeeds.
     tx.commit()
         .await
         .map_err(|e| IngestError::Internal(format!("error: commit transaction: {e}")))?;
@@ -994,7 +921,7 @@ async fn handle_workflow_trigger(
         .await
         .map_err(|e| IngestError::Internal(format!("error: db create_workflow_run: {e}")))?;
 
-    // Commit: event + run creation succeeded atomically.
+    // Finalize the idempotency record after the separate run creation succeeds.
     tx.commit()
         .await
         .map_err(|e| IngestError::Internal(format!("error: commit transaction: {e}")))?;
@@ -1169,7 +1096,7 @@ async fn handle_approval_grant(
         ));
     }
 
-    // Commit: event + approval update succeeded atomically.
+    // Finalize the idempotency record after the separate approval update succeeds.
     tx.commit()
         .await
         .map_err(|e| IngestError::Internal(format!("error: commit transaction: {e}")))?;
@@ -1280,7 +1207,7 @@ async fn handle_approval_deny(
         ));
     }
 
-    // Commit: event + approval denial succeeded atomically.
+    // Finalize the idempotency record after the separate approval denial succeeds.
     tx.commit()
         .await
         .map_err(|e| IngestError::Internal(format!("error: commit transaction: {e}")))?;
@@ -1489,57 +1416,40 @@ mod tests {
         .expect("workflow event")
     }
 
-    fn rejection_message(result: Result<(), IngestError>) -> String {
+    fn rejection_message(result: Result<Option<Vec<u8>>, IngestError>) -> String {
         match result {
             Err(IngestError::Rejected(message)) => message,
             Err(IngestError::AuthFailed(message)) => panic!("unexpected auth failure: {message}"),
             Err(IngestError::Internal(message)) => panic!("unexpected internal failure: {message}"),
-            Ok(()) => panic!("expected revision validation to fail"),
+            Ok(_) => panic!("expected revision parsing to fail"),
         }
     }
 
     #[test]
-    fn workflow_revision_accepts_create_and_matching_update() {
-        let existing = [0x42; 32];
-        assert!(validate_workflow_revision(KIND_WORKFLOW_DEF as i32, None, None).is_ok());
-        assert!(validate_workflow_revision(
-            KIND_WORKFLOW_DEF as i32,
-            Some(&hex::encode(existing)),
-            Some(&existing),
-        )
-        .is_ok());
+    fn workflow_revision_parser_accepts_create_and_valid_update() {
+        let revision = [0x42; 32];
+        assert_eq!(
+            parse_expected_workflow_revision(KIND_WORKFLOW_DEF as i32, None)
+                .expect("tagless workflow"),
+            None
+        );
+        assert_eq!(
+            parse_expected_workflow_revision(
+                KIND_WORKFLOW_DEF as i32,
+                Some(&hex::encode(revision)),
+            )
+            .expect("valid revision"),
+            Some(revision.to_vec())
+        );
     }
 
     #[test]
-    fn workflow_revision_rejects_stale_and_malformed_updates() {
-        let existing = [0x42; 32];
-        let stale = [0x24; 32];
-        assert_eq!(
-            rejection_message(validate_workflow_revision(
-                KIND_WORKFLOW_DEF as i32,
-                Some(&hex::encode(stale)),
-                Some(&existing),
-            )),
-            "conflict: workflow changed since it was loaded",
-        );
-        assert!(
-            validate_workflow_revision(KIND_WORKFLOW_DEF as i32, None, Some(&existing)).is_ok(),
-            "tagless legacy workflow updates remain compatible during rollout",
-        );
+    fn workflow_revision_parser_rejects_malformed_values() {
         for malformed in ["not-hex", "42"] {
             assert_eq!(
-                rejection_message(validate_workflow_revision(
+                rejection_message(parse_expected_workflow_revision(
                     KIND_WORKFLOW_DEF as i32,
                     Some(malformed),
-                    Some(&existing),
-                )),
-                "invalid: bad expected workflow revision",
-            );
-            assert_eq!(
-                rejection_message(validate_workflow_revision(
-                    KIND_WORKFLOW_DEF as i32,
-                    Some(malformed),
-                    None,
                 )),
                 "invalid: bad expected workflow revision",
             );
@@ -1547,14 +1457,11 @@ mod tests {
     }
 
     #[test]
-    fn workflow_revision_rejects_update_for_missing_coordinate() {
+    fn revision_tag_does_not_change_other_command_kinds() {
         assert_eq!(
-            rejection_message(validate_workflow_revision(
-                KIND_WORKFLOW_DEF as i32,
-                Some(&hex::encode([0x42; 32])),
-                None,
-            )),
-            "conflict: workflow revision does not exist",
+            parse_expected_workflow_revision(KIND_DM_OPEN as i32, Some("not-hex"))
+                .expect("non-workflow revision tag"),
+            None
         );
     }
 
@@ -1567,6 +1474,25 @@ mod tests {
         let created_at = Timestamp::now().as_secs();
         let create = workflow_event(&keys, workflow_id, created_at, None, "create");
 
+        let missing_revision = hex::encode([0x24; 32]);
+        let missing_revision_update = workflow_event(
+            &keys,
+            Uuid::new_v4(),
+            created_at,
+            Some(&missing_revision),
+            "missing-revision",
+        );
+        let error = match persist_command_event(&db, &tenant, &missing_revision_update, None).await
+        {
+            Err(error) => error,
+            Ok(_) => panic!("missing revision must not create a workflow"),
+        };
+        assert!(matches!(
+            error,
+            IngestError::Rejected(ref message)
+                if message == "conflict: workflow revision does not exist"
+        ));
+
         let PersistResult::Inserted(tx) = persist_command_event(&db, &tenant, &create, None)
             .await
             .expect("persist create")
@@ -1621,6 +1547,23 @@ mod tests {
             PersistResult::Duplicate
         ));
 
+        let stale_revision_update = workflow_event(
+            &keys,
+            workflow_id,
+            created_at + 1,
+            Some(&create_revision),
+            "stale-revision",
+        );
+        let error = match persist_command_event(&db, &tenant, &stale_revision_update, None).await {
+            Err(error) => error,
+            Ok(_) => panic!("stale revision must not replace the current workflow"),
+        };
+        assert!(matches!(
+            error,
+            IngestError::Rejected(ref message)
+                if message == "conflict: workflow changed since it was loaded"
+        ));
+
         let error = match persist_command_event(&db, &tenant, &dominated_update, None).await {
             Err(error) => error,
             Ok(_) => panic!("distinct dominated CAS update must not report duplicate success"),
@@ -1632,8 +1575,55 @@ mod tests {
         ));
     }
 
-    #[test]
-    fn revision_tag_does_not_change_other_command_kinds() {
-        assert!(validate_workflow_revision(KIND_DM_OPEN as i32, Some("not-hex"), None).is_ok());
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn workflow_persistence_replays_legacy_malformed_revision_before_validation() {
+        let (db, tenant) = persistence_test_context().await;
+        let keys = Keys::generate();
+        let workflow_id = Uuid::new_v4();
+        let created_at = Timestamp::now().as_secs();
+        let legacy = workflow_event(
+            &keys,
+            workflow_id,
+            created_at,
+            Some("not-hex"),
+            "legacy-malformed",
+        );
+
+        let mut tx = db.begin_transaction().await.expect("begin legacy seed");
+        let (_, was_inserted) = buzz_db::event::insert_event_in_transaction(
+            &mut tx,
+            tenant.community(),
+            &legacy,
+            extract_channel_id(&legacy),
+        )
+        .await
+        .expect("seed legacy workflow event");
+        assert!(was_inserted);
+        tx.commit().await.expect("commit legacy seed");
+
+        assert!(matches!(
+            persist_command_event(&db, &tenant, &legacy, None)
+                .await
+                .expect("exact legacy replay must remain idempotent"),
+            PersistResult::Duplicate
+        ));
+
+        let distinct = workflow_event(
+            &keys,
+            workflow_id,
+            created_at + 1,
+            Some("not-hex"),
+            "distinct-malformed",
+        );
+        let error = match persist_command_event(&db, &tenant, &distinct, None).await {
+            Err(error) => error,
+            Ok(_) => panic!("distinct malformed revision must remain rejected"),
+        };
+        assert!(matches!(
+            error,
+            IngestError::Rejected(ref message)
+                if message == "invalid: bad expected workflow revision"
+        ));
     }
 }

From a8e1c66c4a5017a32e41e04e2ba6059e2dfcae21 Mon Sep 17 00:00:00 2001
From: Taylor Ho <taylorkmho@gmail.com>
Date: Mon, 24 Aug 2026 20:45:42 -0700
Subject: [PATCH 9/9] fix(desktop): polish inline chip states (#6718)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

**Category:** fix
**User Impact:** Inline chips now read more consistently, fit cleanly in
the composer, and show deleted message links with the same calm muted
treatment as unresolved links.

**Problem:** Deleted message links looked like destructive actions even
though they are informational, while mention chips had slightly uneven
vertical spacing, a high-set human icon, and could clip inside the
composer. **Solution:** Unify unavailable-state styling, tighten chip
spacing, optically align the human icon, and give composer chips enough
line height to paint without changing caret behavior.

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

**desktop/src/shared/styles/globals/markdown.css**
Makes chip padding vertically symmetric, moves only the human `@` icon
down by 1px, and shares muted colors between deleted and unresolved
message links while preserving their separate semantic classes.

**desktop/src/shared/styles/globals/composer.css**
Adds a composer-only line height derived from the text size and chip
padding so inline chips no longer clip while retaining inline caret
behavior.

**desktop/tests/e2e/entity-link-recipient-cards.spec.ts**
Verifies deleted and unresolved chips have matching computed colors
while deleted links retain their tooltip, semantics, and navigation
behavior.

**desktop/tests/e2e/mentions.spec.ts**
Covers composer chip height, clipping, the human icon's 1px optical
offset, and visual capture.

</details>

## Reproduction steps

1. Open a channel containing a link to a definitively deleted message
and compare it with a transient or unresolved message link; both should
use the muted unavailable treatment, while the deleted link still says
“Message deleted” and navigates to its fallback destination.
2. Insert a person mention in the composer; the chip should have
balanced vertical spacing and paint fully without clipping.
3. Compare a person mention with a channel chip; only the human `@` icon
should sit 1px lower.

## Screenshots

### Deleted message link

| Before | After |
| --- | --- |
| ![Deleted message link
before](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/6718/deleted-chip-before.png)
| ![Deleted message link
after](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/6718/deleted-chip-after.png)
|

### Composer chip polish

| Before | After |
| --- | --- |
| ![Composer mention chip
before](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/6718/composer-chip-before.png)
| ![Composer mention chip
after](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/6718/composer-chip-after-07411aba3.png)
|

## Validation

- `desktop/tests/e2e/entity-link-recipient-cards.spec.ts` +
`desktop/tests/e2e/mentions.spec.ts`: 82/82 passed
- Desktop unit suite: 5,397 passed
- Formatting and lint checks passed (existing informational warnings
only)
- Pre-push desktop check, typecheck, and unit tests passed at
`0255c3fd49f9244cd727d0dd20c514b3a1812152`

---------

Signed-off-by: Taylor Ho <taylorkmho@gmail.com>
---
 .../src/shared/styles/globals/composer.css    |   9 +-
 .../src/shared/styles/globals/markdown.css    |  13 +-
 .../e2e/entity-link-recipient-cards.spec.ts   |  31 +++++
 desktop/tests/e2e/mentions.spec.ts            | 113 ++++++++++++++++++
 4 files changed, 157 insertions(+), 9 deletions(-)

diff --git a/desktop/src/shared/styles/globals/composer.css b/desktop/src/shared/styles/globals/composer.css
index 781ac8a196..5ebe4b5775 100644
--- a/desktop/src/shared/styles/globals/composer.css
+++ b/desktop/src/shared/styles/globals/composer.css
@@ -96,6 +96,7 @@
   @apply text-message font-normal tracking-normal;
   outline: none;
   min-height: 1lh;
+  padding-block: 0.0625rem;
 }
 
 .rich-text-composer .tiptap p {
@@ -260,8 +261,14 @@
    caret into their decorated range and swallows the trailing space after an
    @mention. Composer Buzz links are atom nodes, but their labels may still
    fragment between characters; only the icon and leading label fragment stay
-   together. */
+   together. The line-height keeps each inline decoration box tall enough to
+   paint both block-padding edges without clipping. */
 .rich-text-composer .tiptap .mention-chip {
   display: inline;
   min-height: 0;
+  line-height: calc(
+    1em +
+    var(--inline-chip-padding-block-start) +
+    var(--inline-chip-padding-block-end)
+  );
 }
diff --git a/desktop/src/shared/styles/globals/markdown.css b/desktop/src/shared/styles/globals/markdown.css
index 9d0c382ac3..135c036e74 100644
--- a/desktop/src/shared/styles/globals/markdown.css
+++ b/desktop/src/shared/styles/globals/markdown.css
@@ -1,5 +1,5 @@
 .message-markdown {
-  --inline-chip-padding-block-start: 0.1875rem;
+  --inline-chip-padding-block-start: 0.125rem;
   --inline-chip-padding-block-end: 0.125rem;
   --inline-chip-padding-inline: 0.25rem;
   --inline-chip-min-height: calc(
@@ -101,15 +101,11 @@
 }
 
 .message-markdown .mention-chip.buzz-link-unavailable,
-.message-markdown .mention-chip.buzz-link-unavailable:hover {
-  background: hsl(var(--secondary));
-  color: hsl(var(--secondary-foreground) / 0.7);
-}
-
+.message-markdown .mention-chip.buzz-link-unavailable:hover,
 .message-markdown .mention-chip.buzz-link-deleted,
 .message-markdown .mention-chip.buzz-link-deleted:hover {
-  background: hsl(var(--destructive) / 0.12);
-  color: hsl(var(--destructive));
+  background: hsl(var(--secondary));
+  color: hsl(var(--secondary-foreground) / 0.7);
 }
 
 .message-markdown .mention-chip.inbox-channel-chip {
@@ -336,6 +332,7 @@
 }
 
 .message-markdown .inline-chip-icon-human::before {
+  transform: translateY(calc(-50% + 0.0625rem));
   -webkit-mask:
     url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='12' cy='12' r='4'/%3E%3Cpath d='M16 8v5a3 3 0 0 0 6 0v-1a10 10 0 1 0-4 8'/%3E%3C/svg%3E")
     center / contain no-repeat;
diff --git a/desktop/tests/e2e/entity-link-recipient-cards.spec.ts b/desktop/tests/e2e/entity-link-recipient-cards.spec.ts
index 056b059b0e..6ca502c346 100644
--- a/desktop/tests/e2e/entity-link-recipient-cards.spec.ts
+++ b/desktop/tests/e2e/entity-link-recipient-cards.spec.ts
@@ -662,6 +662,10 @@ test("deleted reply links identify deletion and fall back to their thread root",
 test("deleted top-level message links identify deletion and fall back to channel navigation", async ({
   page,
 }) => {
+  await page.addInitScript(() => {
+    window.localStorage.setItem("buzz-theme", "buzz-dark");
+    window.localStorage.setItem("buzz-accent-color", "#c0a2f1");
+  });
   const missingMessageId = "d".repeat(64);
   const channelId = "9dae0116-799b-5071-a0a8-fdd30a91a35d";
   const link = `buzz://message?channel=${channelId}&id=${missingMessageId}`;
@@ -685,6 +689,33 @@ test("deleted top-level message links identify deletion and fall back to channel
   );
   await expect(deletedLink).toHaveClass(/buzz-link-deleted/);
   await expect(deletedLink).not.toHaveClass(/buzz-link-unavailable/);
+  const unavailableColors = await linkMessage.evaluate((message) => {
+    const probe = document.createElement("span");
+    probe.className = "mention-chip buzz-link-unavailable";
+    message.querySelector(".message-markdown")?.append(probe);
+    const styles = getComputedStyle(probe);
+    const colors = {
+      backgroundColor: styles.backgroundColor,
+      color: styles.color,
+    };
+    probe.remove();
+    return colors;
+  });
+  await expect
+    .poll(() =>
+      deletedLink.evaluate((element) => {
+        const styles = getComputedStyle(element);
+        return {
+          backgroundColor: styles.backgroundColor,
+          color: styles.color,
+        };
+      }),
+    )
+    .toEqual(unavailableColors);
+  await waitForAnimations(page);
+  await linkMessage.screenshot({
+    path: `${SHOTS}/deleted-message-link-after.png`,
+  });
   await deletedLink.hover();
   await expect(page.getByRole("tooltip")).toHaveText("Message deleted");
 
diff --git a/desktop/tests/e2e/mentions.spec.ts b/desktop/tests/e2e/mentions.spec.ts
index 8f0300af16..e90281a52f 100644
--- a/desktop/tests/e2e/mentions.spec.ts
+++ b/desktop/tests/e2e/mentions.spec.ts
@@ -1,5 +1,7 @@
 import { expect, test } from "@playwright/test";
 
+import { waitForAnimations } from "../helpers/animations";
+
 import {
   installMockBridge,
   openChannelBrowser,
@@ -844,6 +846,9 @@ test("mention autocomplete caps global people search at 50 results", async ({
 test("selecting a person mention inserts @Name into input", async ({
   page,
 }) => {
+  await page.addInitScript(() => {
+    window.localStorage.setItem("buzz-theme", "buzz-dark");
+  });
   await page.goto("/");
   await page.getByTestId("channel-general").click();
   await expect(page.getByTestId("chat-title")).toHaveText("general");
@@ -872,6 +877,114 @@ test("selecting a person mention inserts @Name into input", async ({
     ),
   );
   expect(iconMask).toContain("data:image/svg+xml");
+  await expect(mentionChip).toHaveCSS("line-height", "18px");
+  const scrollViewport = page.getByTestId("message-input-scroll");
+  const paintedBounds = await mentionChip.evaluate((element) => {
+    const chip = element.getBoundingClientRect();
+    const viewport = element
+      .closest("[data-testid='message-input-scroll']")
+      ?.getBoundingClientRect();
+    if (!viewport)
+      throw new Error("Mention chip is missing its scroll viewport");
+    return {
+      chipTop: chip.top,
+      chipBottom: chip.bottom,
+      viewportTop: viewport.top,
+      viewportBottom: viewport.bottom,
+    };
+  });
+  expect(paintedBounds.chipTop).toBeGreaterThanOrEqual(
+    paintedBounds.viewportTop,
+  );
+  expect(paintedBounds.chipBottom).toBeLessThanOrEqual(
+    paintedBounds.viewportBottom,
+  );
+  const humanIconTranslateY = await mentionChip.evaluate(
+    (element) =>
+      new DOMMatrix(getComputedStyle(element, "::before").transform).m42,
+  );
+  const channelIconTranslateY = await input.evaluate((composer) => {
+    const probe = document.createElement("span");
+    probe.className =
+      "mention-chip inline-chip-with-icon inline-chip-icon-channel";
+    composer.append(probe);
+    const translateY = new DOMMatrix(
+      getComputedStyle(probe, "::before").transform,
+    ).m42;
+    probe.remove();
+    return translateY;
+  });
+  expect(humanIconTranslateY - channelIconTranslateY).toBeCloseTo(1);
+
+  await input.fill("@bo");
+  await dropdown.getByText("bob").click();
+  await input.press("Shift+Enter");
+  await page.keyboard.type("@bo");
+  await dropdown.getByText("bob").click();
+  await input.press("Shift+Enter");
+  await page.keyboard.type("@bo");
+  await dropdown.getByText("bob").click();
+  const multilineChips = input.locator(".human-mention-highlight");
+  await expect(multilineChips).toHaveCount(3);
+  const multilinePaintBounds = await multilineChips.evaluateAll((elements) => {
+    const viewport = elements[0]
+      ?.closest("[data-testid='message-input-scroll']")
+      ?.getBoundingClientRect();
+    if (!viewport) {
+      throw new Error("Mention chips are missing their scroll viewport");
+    }
+    return elements.map((element) => {
+      const chip = element.getBoundingClientRect();
+      return {
+        chipTop: chip.top,
+        chipBottom: chip.bottom,
+        viewportTop: viewport.top,
+        viewportBottom: viewport.bottom,
+      };
+    });
+  });
+  for (const bounds of multilinePaintBounds) {
+    expect(bounds.chipTop).toBeGreaterThanOrEqual(bounds.viewportTop);
+    expect(bounds.chipBottom).toBeLessThanOrEqual(bounds.viewportBottom);
+  }
+
+  await scrollViewport.evaluate((element) => {
+    element.style.width = "8rem";
+  });
+  await input.fill("A deliberately long prefix that forces @bo");
+  await dropdown.getByText("bob").click();
+  const wrappedChip = input.locator(".human-mention-highlight", {
+    hasText: "bob",
+  });
+  const wrappedPaintBounds = await wrappedChip.evaluate((element) => {
+    const chip = element.getBoundingClientRect();
+    const viewport = element
+      .closest("[data-testid='message-input-scroll']")
+      ?.getBoundingClientRect();
+    if (!viewport)
+      throw new Error("Mention chip is missing its scroll viewport");
+    return {
+      chipTop: chip.top,
+      chipBottom: chip.bottom,
+      viewportTop: viewport.top,
+      viewportBottom: viewport.bottom,
+    };
+  });
+  expect(wrappedPaintBounds.chipTop).toBeGreaterThanOrEqual(
+    wrappedPaintBounds.viewportTop,
+  );
+  expect(wrappedPaintBounds.chipBottom).toBeLessThanOrEqual(
+    wrappedPaintBounds.viewportBottom,
+  );
+  await expect(input).toHaveCSS("height", /^(?!20px$)/);
+  await scrollViewport.evaluate((element) => {
+    element.style.removeProperty("width");
+  });
+
+  await waitForAnimations(page);
+  await page.getByTestId("message-composer").screenshot({
+    path: "test-results/inline-chip-polish/composer-after.png",
+  });
 });
 
 test("immediate ArrowLeft after a person mention is not bounced past the trailing space", async ({