fix(mention): emit parallel p + mention tags on intentional @mentions

Contract for #2296 / #1743: intentional authored @mentions emit
["mention", pubkey] alongside ["p", pubkey] from SDK build_message,
desktop ordinary composer + reply tags + edit path, mobile send, and
workflow_sink. Relay offline-agent notices stay gated on mention tags
only (never bare structural p). Tests cover parallel tags + structural-p
non-trigger.

Signed-off-by: Bartok9 <danielrpike9@gmail.com>

Author: Bartok9

crates/buzz-relay/src/handlers/event.rs

@@ -586,10 +586,11 @@ async fn dispatch_persistent_event_inner(
 
 /// Collect explicit `@mention` targets from event tags.
 ///
-/// Desktop emits `["mention", pubkey]` via `mergeOutgoingTagsWithReferenceMentions`
-/// / `MENTION_REFERENCE_TAG` for composer @mentions. Structural reply-author
-/// routing only adds `p` tags (`buildReplyTags`) and must **not** count as an
-/// explicit mention (Brad review on #2296 / same finding on #1862).
+/// Producers emit `["mention", pubkey]` in parallel with `p` for intentional
+/// authored @mentions (SDK/CLI `build_message`, Desktop ordinary composer /
+/// `buildReplyTags` mention loop, Mobile `SendMessage`). The non-member
+/// "send without inviting" path also uses bare `mention` tags.
+/// Structural reply-author `p` alone must **not** count (Brad #2296 / #1862).
 ///
 /// - Dedupes first-seen hex (lowercased)
 /// - Skips malformed tags (missing/empty pubkey)
@@ -2744,6 +2745,48 @@ mod tests {
             assert_eq!(found, vec![bot]);
         }
 
+        #[test]
+        fn explicit_mention_from_sdk_style_tags_not_structural_p() {
+            // Contract: intentional mentions carry parallel p+mention; structural
+            // reply author is p-only and must not extract.
+            let author = "aa".repeat(32);
+            let offline_bot = "bb".repeat(32);
+            let structural_only = nostr::Tags::from_list(vec![
+                nostr::Tag::parse(["p", &author]).unwrap(),
+                nostr::Tag::parse(["h", "00000000-0000-0000-0000-000000000001"]).unwrap(),
+            ]);
+            assert!(
+                crate::handlers::event::explicit_mention_pubkeys_from_tags(&structural_only)
+                    .is_empty()
+            );
+
+            let intentional = nostr::Tags::from_list(vec![
+                nostr::Tag::parse(["p", &author]).unwrap(),
+                nostr::Tag::parse(["h", "00000000-0000-0000-0000-000000000001"]).unwrap(),
+                nostr::Tag::parse(["p", &offline_bot]).unwrap(),
+                nostr::Tag::custom(
+                    nostr::TagKind::Custom("mention".into()),
+                    [&offline_bot],
+                ),
+            ]);
+            assert_eq!(
+                crate::handlers::event::explicit_mention_pubkeys_from_tags(&intentional),
+                vec![offline_bot.clone()]
+            );
+
+            use std::collections::{HashMap, HashSet};
+            let bots: HashSet<String> = [offline_bot.clone()].into_iter().collect();
+            let present: HashMap<String, String> = HashMap::new();
+            let mentioned =
+                crate::handlers::event::explicit_mention_pubkeys_from_tags(&intentional);
+            assert_eq!(
+                crate::handlers::event::select_offline_mentioned_bots(
+                    &mentioned, &bots, &present
+                ),
+                vec![offline_bot]
+            );
+        }
+
         #[test]
         fn offline_matrix_explicit_offline_bot_only() {
             use std::collections::{HashMap, HashSet};

crates/buzz-relay/src/workflow_sink.rs

@@ -296,6 +296,11 @@ impl ActionSink for RelayActionSink {
                     Tag::parse(["p", &mentioned])
                         .map_err(|e| ActionSinkError::EventBuild(format!("mention p tag: {e}")))?,
                 );
+                tags.push(
+                    Tag::parse(["mention", &mentioned]).map_err(|e| {
+                        ActionSinkError::EventBuild(format!("mention intent tag: {e}"))
+                    })?,
+                );
             }
 
             let kind = Kind::from(KIND_STREAM_MESSAGE as u16);

crates/buzz-sdk/src/builders.rs

@@ -189,7 +189,12 @@ fn thread_tags(thread_ref: &ThreadRef, tags: &mut Vec<Tag>) -> Result<(), SdkErr
     Ok(())
 }
 
-/// Deduplicate and cap mentions, emitting p-tags.
+/// Deduplicate and cap intentional mentions.
+///
+/// Emits both `["p", hex]` (delivery / subscription fan-out) and
+/// `["mention", hex]` (explicit intent marker). Relay offline-agent notices
+/// (#1743 / #2296) gate on `mention` only so structural reply-author `p`
+/// tags never false-trigger.
 fn mention_tags(mentions: &[&str], tags: &mut Vec<Tag>) -> Result<(), SdkError> {
     if mentions.len() > crate::mentions::MENTION_CAP {
         return Err(SdkError::TooManyMentions);
@@ -199,6 +204,7 @@ fn mention_tags(mentions: &[&str], tags: &mut Vec<Tag>) -> Result<(), SdkError>
         let lower = hex.to_ascii_lowercase();
         if seen.insert(lower.clone()) {
             tags.push(tag(&["p", &lower])?);
+            tags.push(tag(&["mention", &lower])?);
         }
     }
     Ok(())
@@ -218,7 +224,8 @@ fn imeta_tags(media_tags: &[Vec<String>], tags: &mut Vec<Tag>) -> Result<(), Sdk
 /// - `channel_id`: target channel UUID
 /// - `content`: message text (max 64 KiB)
 /// - `thread_ref`: optional NIP-10 reply context
-/// - `mentions`: pubkey hex strings to p-tag (deduped, max 50)
+/// - `mentions`: pubkey hex strings for intentional @mentions (deduped, max 50);
+///   emits both `p` and `mention` tags
 /// - `broadcast`: if true, adds `["broadcast", "1"]` tag
 /// - `media_tags`: raw imeta tag vectors
 pub fn build_message(
@@ -2410,6 +2417,18 @@ mod tests {
         let ev = sign(build_message(cid, "hi", None, &[hex, hex], false, &[]).unwrap());
         let p_tags = tag_values(&ev, "p");
         assert_eq!(p_tags.len(), 1);
+        let mention_tags = tag_values(&ev, "mention");
+        assert_eq!(mention_tags, vec![hex.to_string()]);
+    }
+
+    #[test]
+    fn message_mentions_emit_parallel_p_and_mention() {
+        let cid = uuid();
+        let a = "aa".repeat(32);
+        let b = "bb".repeat(32);
+        let ev = sign(build_message(cid, "hi @a @b", None, &[&a, &b], false, &[]).unwrap());
+        assert_eq!(tag_values(&ev, "p"), vec![a.clone(), b.clone()]);
+        assert_eq!(tag_values(&ev, "mention"), vec![a, b]);
     }
 
     #[test]

crates/buzz-sdk/src/mentions.rs

@@ -15,7 +15,7 @@
 //!                                                          │
 //! body text ──► strip_code_regions ──► extract_nostr_uris ─┤
 //!                                                          ▼
-//!                            explicit mentions ──► normalize ──► merge_mentions ──► p-tags
+//!                            explicit mentions ──► normalize ──► merge_mentions ──► p + mention tags
 //! ```
 //!
 //! When the set of known member names is available upfront,
@@ -31,7 +31,7 @@ use std::collections::HashSet;
 
 use nostr::{FromBech32, PublicKey};
 
-/// Maximum number of mention p-tags allowed on a single message.
+/// Maximum number of intentional mentions allowed on a single message.
 ///
 /// Matches the cap enforced by Buzz message builders and the legacy MCP
 /// inline implementation.

desktop/src-tauri/src/events.rs

@@ -68,7 +68,9 @@ fn mention_tags(mentions: &[&str]) -> Result<Vec<Tag>, String> {
         check_pubkey(hex)?;
         let lower = hex.to_ascii_lowercase();
         if seen.insert(lower.clone()) {
+            // Parallel p (fan-out) + mention (explicit intent) for #2296 contract.
             tags.push(tag(vec!["p", &lower])?);
+            tags.push(tag(vec!["mention", &lower])?);
         }
     }
     Ok(tags)
@@ -403,6 +405,19 @@ pub fn build_forum_comment(
 
 /// Kind 40003 — edit a message with full content, media, emoji, mentions,
 /// and optional monotonic link-preview suppression.
+///
+/// Carries the full new content AND a fresh imeta tag set; the receiver
+/// overlays the imeta tags onto the original event so the rendered message
+/// reflects exactly the edited state. NIP-30 custom-emoji tags ride along the
+/// same way so an edited body's `:shortcode:`s stay resolvable (the send path
+/// attaches these too).
+///
+/// `mentions` carries the pubkeys of mentions that are *newly added* by this
+/// edit (the caller diffs the edited body against the original). Only those get
+/// parallel `p` + `mention` tags so the newly-mentioned party is notified/woken,
+/// while a typo-fix edit that leaves the mention set unchanged emits neither
+/// and never re-wakes anyone. Mirrors the send path's `mention_tags` (dedup +
+/// lowercase); the receiver overlays these onto the original event's audience.
 pub fn build_message_edit(
     channel_id: Uuid,
     target_event_id: EventId,
@@ -930,11 +945,11 @@ mod tests {
         assert_eq!(event.pubkey.to_hex(), TARGET_HEX);
     }
 
-    // ── build_message_edit `p`-tag emission (lane 8ace8eed) ──────────────
+    // ── build_message_edit p+mention emission (lane 8ace8eed) ──────────────
     //
     // The composer diffs the edited body's mentions against the original and
     // hands `build_message_edit` only the *newly added* pubkeys. These tests
-    // pin the builder's contract given that contract: emit a `p` per added
+    // pins the builder's contract: emit parallel `p` + `mention` per added
     // mention (deduped, lowercased), and none when the added set is empty
     // (typo-fix edit) — so an unchanged mention set re-wakes nobody.
 
@@ -962,20 +977,21 @@ mod tests {
         let tags = edit_tags(&[ALICE_HEX]);
         assert_eq!(tags[0][0], "h");
         assert_eq!(tags[1][0], "e");
-        // The `p` tag rides right after the `e` tag (insertion order).
+        // `p` + parallel `mention` ride right after the `e` tag (insertion order).
         assert_eq!(tags[2], vec!["p".to_string(), ALICE_HEX.to_string()]);
+        assert_eq!(tags[3], vec!["mention".to_string(), ALICE_HEX.to_string()]);
     }
 
     #[test]
     fn edit_with_no_added_mentions_emits_no_p_tag() {
         // Typo-fix edit: mention set unchanged, so the composer passes `&[]`.
-        // The edit event must carry no `p` tag and re-wake nobody.
+        // The edit event must carry no `p`/`mention` tags and re-wake nobody.
         let tags = edit_tags(&[]);
         assert!(
-            !tags
-                .iter()
-                .any(|t| t.first().map(String::as_str) == Some("p")),
-            "unchanged-mention edit must not emit any `p` tag, got {tags:?}"
+            !tags.iter().any(|t| {
+                matches!(t.first().map(String::as_str), Some("p" | "mention"))
+            }),
+            "unchanged-mention edit must not emit p/mention tags, got {tags:?}"
         );
     }
 
@@ -995,5 +1011,18 @@ mod tests {
         );
         assert_eq!(p_tags[0], &vec!["p".to_string(), ALICE_HEX.to_string()]);
         assert_eq!(p_tags[1], &vec!["p".to_string(), BOB_HEX.to_string()]);
+        let mention_tags: Vec<&Vec<String>> = tags
+            .iter()
+            .filter(|t| t.first().map(String::as_str) == Some("mention"))
+            .collect();
+        assert_eq!(mention_tags.len(), 2);
+        assert_eq!(
+            mention_tags[0],
+            &vec!["mention".to_string(), ALICE_HEX.to_string()]
+        );
+        assert_eq!(
+            mention_tags[1],
+            &vec!["mention".to_string(), BOB_HEX.to_string()]
+        );
     }
 }

desktop/src/features/messages/hooks.ts

@@ -109,6 +109,7 @@ export function createOptimisticMessage(
       identity.pubkey,
     )) {
       tags.push(["p", pubkey]);
+      tags.push(["mention", pubkey]);
     }
   }
 
@@ -519,8 +520,11 @@ export function useSendMessageMutation(
             ...baseTags,
             // For non-replies, add mention p-tags here (replies get them via buildReplyTags)
             ...(!parentEventId
-              ? normalizeMentionPubkeys(recipientPubkeys, identity.pubkey).map(
-                  (pk) => ["p", pk],
+              ? normalizeMentionPubkeys(recipientPubkeys, identity.pubkey).flatMap(
+                  (pk) => [
+                    ["p", pk],
+                    ["mention", pk],
+                  ],
                 )
               : []),
             ...imetaTags,

desktop/src/features/messages/lib/threading.ts

@@ -110,11 +110,13 @@ export function buildReplyTags(
     ["h", channelId],
   ];
 
-  // Add p-tags for mentioned users so mention-filtered subscriptions
-  // (e.g. ACP agent harness) receive the reply event.
+  // Intentional @mentions: `p` for subscription fan-out + explicit `mention`
+  // intent marker (relay offline-agent notice gates on mention only; structural
+  // reply-author `p` above must never count as a mention).
   // Best-effort normalization — relay performs authoritative validation.
   for (const pubkey of normalizeMentionPubkeys(mentionPubkeys, authorPubkey)) {
     tags.push(["p", pubkey]);
+    tags.push(["mention", pubkey]);
   }
 
   if (parentEventId === rootEventId) {

desktop/src/shared/api/relayClientSession.ts

@@ -260,6 +260,7 @@ export class RelayClient {
     const tags: string[][] = [["h", channelId]];
     for (const pubkey of mentionPubkeys) {
       tags.push(["p", pubkey]);
+      tags.push(["mention", pubkey]);
     }
     for (const tag of extraTags) {
       tags.push(tag);

desktop/src/testing/e2eBridge.ts

@@ -3884,6 +3884,7 @@ function appendMentionTags(
     }
     seen.add(lower);
     tags.push(["p", lower]);
+    tags.push(["mention", lower]);
   }
 }
 

mobile/lib/features/channels/send_message_provider.dart

@@ -66,10 +66,16 @@ class SendMessage {
         if (seenMentions.add(pk.toLowerCase())) pk,
     ];
 
+    // Intentional @mentions emit `p` (fan-out) + `mention` (explicit intent).
+    // Structural reply routing uses only `e` tags here; relay offline notices
+    // gate on `mention` so we never treat reply-author `p` as a mention.
     final tags = <List<String>>[
       ['h', channelId],
       if (parentEventId != null) ..._buildReplyTags(parentEventId, rootEventId),
-      for (final pk in normalizedMentions) ['p', pk],
+      for (final pk in normalizedMentions) ...[
+        ['p', pk],
+        ['mention', pk],
+      ],
       ...mediaTags,
     ];