From 32894e5a0a8584d1b20b7d371941b75ffe6dcd40 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Wed, 26 Aug 2026 15:41:57 +1000
Subject: [PATCH 1/7] fix(desktop): scope composer autocomplete to focus

Prevent inactive channel composers from rendering stale inline autocomplete state while a thread send toggles their shared disabled state. Preserve editor focus for composer mention controls and cover the thread-send regression end to end.

Co-authored-by: Jitter <2b2e6415e748c35180847a37aadae06a11e30dddc76b784e7fd9354c4eb42e7a@buzz.block.builderlab.xyz>
Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../messages/lib/useRichTextEditor.ts         |  8 +--
 .../messages/ui/ComposerAddressControls.tsx   |  6 ++-
 .../features/messages/ui/MessageComposer.tsx  | 22 ++++----
 .../e2e/persistent-agent-audience.spec.ts     | 53 +++++++++++++++++++
 4 files changed, 73 insertions(+), 16 deletions(-)

diff --git a/desktop/src/features/messages/lib/useRichTextEditor.ts b/desktop/src/features/messages/lib/useRichTextEditor.ts
index e3e17071fad..4d5ccd39c82 100644
--- a/desktop/src/features/messages/lib/useRichTextEditor.ts
+++ b/desktop/src/features/messages/lib/useRichTextEditor.ts
@@ -165,18 +165,15 @@ export function useRichTextEditor({
   onLinkShortcut,
 }: RichTextEditorOptions) {
   const addressedAgentMentionNamesRef = React.useRef<readonly string[]>([]);
+  const [isFocused, setIsFocused] = React.useState(false);
   const onUpdateRef = React.useRef(onUpdate);
   onUpdateRef.current = onUpdate;
-
   const onSubmitRef = React.useRef(onSubmit);
   onSubmitRef.current = onSubmit;
-
   const onEditLastOwnMessageRef = React.useRef(onEditLastOwnMessage);
   onEditLastOwnMessageRef.current = onEditLastOwnMessage;
-
   const onEditLinkRef = React.useRef(onEditLink);
   onEditLinkRef.current = onEditLink;
-
   const onLinkSelectionChangeRef = React.useRef(onLinkSelectionChange);
   onLinkSelectionChangeRef.current = onLinkSelectionChange;
 
@@ -600,6 +597,8 @@ export function useRichTextEditor({
           buildPreviewUpdate(ed.state.doc, ed.state.selection.anchor),
         );
       },
+      onFocus: () => setIsFocused(true),
+      onBlur: () => setIsFocused(false),
     },
     [],
   );
@@ -930,6 +929,7 @@ export function useRichTextEditor({
 
   return {
     editor,
+    isFocused,
     getMarkdown,
     isEmpty,
     clearContent,
diff --git a/desktop/src/features/messages/ui/ComposerAddressControls.tsx b/desktop/src/features/messages/ui/ComposerAddressControls.tsx
index ae39931334e..30bfe196e3f 100644
--- a/desktop/src/features/messages/ui/ComposerAddressControls.tsx
+++ b/desktop/src/features/messages/ui/ComposerAddressControls.tsx
@@ -195,7 +195,10 @@ export function ComposerMentionButton({
                 data-testid="message-insert-mention"
                 disabled={disabled}
                 onClick={onOpen}
-                onMouseDown={onCaptureSelection}
+                onMouseDown={(event) => {
+                  onCaptureSelection();
+                  event.preventDefault();
+                }}
                 type="button"
               >
                 <AtSign aria-hidden="true" className="h-4 w-4 shrink-0" />
@@ -303,6 +306,7 @@ export function ComposerMentionButton({
           <button
             className="shrink-0 rounded-md px-1.5 py-1 font-medium text-primary outline-hidden hover:bg-primary/10 focus-visible:ring-1 focus-visible:ring-ring"
             onClick={onConfirmationTurnOff}
+            onMouseDown={(event) => event.preventDefault()}
             type="button"
           >
             Turn off
diff --git a/desktop/src/features/messages/ui/MessageComposer.tsx b/desktop/src/features/messages/ui/MessageComposer.tsx
index 0cc8650795e..4d80ede1a75 100644
--- a/desktop/src/features/messages/ui/MessageComposer.tsx
+++ b/desktop/src/features/messages/ui/MessageComposer.tsx
@@ -783,6 +783,8 @@ function MessageComposerImpl({
   const handlePaperclipClick = React.useCallback(() => {
     void media.handlePaperclip();
   }, [media.handlePaperclip]);
+  const gate = <T,>(open: boolean, suggestions: T[]) =>
+    richText.isFocused && open ? suggestions : [];
   return (
     <>
       <footer
@@ -843,20 +845,18 @@ function MessageComposerImpl({
             <EmojiAutocomplete
               onSelect={applyEmojiInsert}
               selectedIndex={emojiAutocomplete.emojiSelectedIndex}
-              suggestions={
-                emojiAutocomplete.isEmojiAutocompleteOpen
-                  ? emojiAutocomplete.emojiSuggestions
-                  : []
-              }
+              suggestions={gate(
+                emojiAutocomplete.isEmojiAutocompleteOpen,
+                emojiAutocomplete.emojiSuggestions,
+              )}
             />
             <ChannelAutocomplete
               onSelect={applyChannelInsert}
               selectedIndex={channelLinks.channelSelectedIndex}
-              suggestions={
-                channelLinks.isChannelOpen
-                  ? channelLinks.channelSuggestions
-                  : []
-              }
+              suggestions={gate(
+                channelLinks.isChannelOpen,
+                channelLinks.channelSuggestions,
+              )}
             />
             <MentionAutocomplete
               keepMentionedAgentsPinned={keepMentionedAgentsPinned}
@@ -877,7 +877,7 @@ function MessageComposerImpl({
               onDismiss={mentions.cancelMentionAutocomplete}
               onSelect={selectMentionSuggestion}
               selectedIndex={mentions.mentionSelectedIndex}
-              suggestions={mentions.isMentionOpen ? mentions.suggestions : []}
+              suggestions={gate(mentions.isMentionOpen, mentions.suggestions)}
             />
             {media.uploadState.status === "error" ? (
               <div className="mb-2 rounded-lg bg-destructive/10 px-3 py-2 text-xs text-destructive">
diff --git a/desktop/tests/e2e/persistent-agent-audience.spec.ts b/desktop/tests/e2e/persistent-agent-audience.spec.ts
index 643031454ac..e9b9e275522 100644
--- a/desktop/tests/e2e/persistent-agent-audience.spec.ts
+++ b/desktop/tests/e2e/persistent-agent-audience.spec.ts
@@ -690,6 +690,59 @@ test("always-mentioned agents remain selected without replaying their animation
   ).toHaveCount(1);
 });
 
+test("the unfocused main composer keeps its mention menu closed during a thread send", async ({
+  page,
+}) => {
+  await installAudienceFixtures(page, { sendMessageDelayMs: 500 });
+  await openGeneral(page);
+
+  const mainComposer = channelComposer(page);
+  const mainInput = mainComposer.getByTestId("message-input");
+  await automaticallyMention(mainComposer, "Morgarita");
+  await mainInput.fill("@Morgarita earlier message");
+  await mainInput.press("Enter");
+  await expect(mainInput).toHaveText("@Morgarita ");
+  await mainInput.fill("@Morgarita");
+  await expect(mainInput).toHaveText("@Morgarita");
+  await expect(mainComposer.getByTestId("mention-autocomplete")).toBeVisible();
+  await mainInput.press("Escape");
+  await expect(mainComposer.getByTestId("mention-autocomplete")).toHaveCount(0);
+
+  const rootMessage = page.locator(
+    `[data-testid="message-row"][data-message-id="${THREAD_ROOT_ID}"]`,
+  );
+  await rootMessage
+    .getByRole("button", { name: "Reply" })
+    .evaluate((button: HTMLButtonElement) => button.click());
+
+  const threadPanel = page.getByTestId("message-thread-panel");
+  await expect(threadPanel).toBeVisible();
+  const threadInput = threadPanel.getByTestId("message-input");
+  await threadInput.click();
+  await expect(threadInput).toBeFocused();
+  await expect(mainComposer.getByTestId("mention-autocomplete")).toHaveCount(0);
+  await mainComposer.evaluate((element) => {
+    element.dataset.mentionMenuReopened = "false";
+    new MutationObserver(() => {
+      if (element.querySelector('[data-testid="mention-autocomplete"]')) {
+        element.dataset.mentionMenuReopened = "true";
+      }
+    }).observe(element, { childList: true, subtree: true });
+  });
+
+  const reply = `Thread reply ${Date.now()}`;
+  await threadInput.fill(reply);
+  await threadInput.press("Enter");
+  await expect(mainInput).toHaveAttribute("contenteditable", "false");
+  await expect(threadPanel).toContainText(reply);
+  await expect(mainInput).toHaveAttribute("contenteditable", "true");
+
+  expect(await mainComposer.getAttribute("data-mention-menu-reopened")).toBe(
+    "false",
+  );
+  await expect(mainComposer.getByTestId("mention-autocomplete")).toHaveCount(0);
+});
+
 test("a failed always-mentioned send shakes the composer avatar without replaying its selection animation", async ({
   page,
 }) => {

From 11a33389469f2c7f62abed5bab181318a572f24e Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Wed, 26 Aug 2026 16:16:21 +1000
Subject: [PATCH 2/7] fix(desktop): stop setEditable toggles from replaying
 composer updates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The mid-send editable toggles emitted Tiptap's default synthetic update
event with an unchanged doc, replaying onUpdate with stale text/cursor.
That resurrected consumer state derived from it — most visibly reopening
a mention menu the user had dismissed with Escape as soon as the drafted
composer regained focus, and re-firing typing notifications for an
untouched draft. Pass emitUpdate=false to both setEditable calls (real
content changes dispatch their own transactions and still emit updates)
and extend the thread-send E2E regression test to assert the dismissed
menu stays closed after refocusing the drafted composer.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../src/features/messages/lib/useRichTextEditor.ts | 10 ++++++++--
 .../tests/e2e/persistent-agent-audience.spec.ts    | 14 +++++++++++++-
 2 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/desktop/src/features/messages/lib/useRichTextEditor.ts b/desktop/src/features/messages/lib/useRichTextEditor.ts
index 4d5ccd39c82..e53dbdaf6e7 100644
--- a/desktop/src/features/messages/lib/useRichTextEditor.ts
+++ b/desktop/src/features/messages/lib/useRichTextEditor.ts
@@ -617,13 +617,19 @@ export function useRichTextEditor({
   const hadFocusBeforeDisableRef = React.useRef(false);
   React.useEffect(() => {
     if (!editor || editor.isEditable === editable) return;
+    // `emitUpdate: false` on both toggles — the doc hasn't changed, so the
+    // default synthetic `update` event would replay `onUpdate` with stale
+    // text/cursor and resurrect consumer state derived from it (e.g. reopen
+    // a mention menu the user dismissed with Escape, or re-fire a typing
+    // notification for an untouched draft). Real content changes (typing,
+    // clearContent) dispatch real transactions that emit their own updates.
     if (!editable) {
       // About to disable: remember whether we currently hold focus so we know
       // whether to restore it when re-enabled.
       hadFocusBeforeDisableRef.current = editor.isFocused;
-      editor.setEditable(false);
+      editor.setEditable(false, false);
     } else {
-      editor.setEditable(true);
+      editor.setEditable(true, false);
       // Re-enabled: if we owned focus before the disable blurred us, take it
       // back (preserving the current selection — `focus()` with no arg keeps
       // the existing selection rather than jumping to the end).
diff --git a/desktop/tests/e2e/persistent-agent-audience.spec.ts b/desktop/tests/e2e/persistent-agent-audience.spec.ts
index e9b9e275522..7593cd736a0 100644
--- a/desktop/tests/e2e/persistent-agent-audience.spec.ts
+++ b/desktop/tests/e2e/persistent-agent-audience.spec.ts
@@ -690,7 +690,7 @@ test("always-mentioned agents remain selected without replaying their animation
   ).toHaveCount(1);
 });
 
-test("the unfocused main composer keeps its mention menu closed during a thread send", async ({
+test("the unfocused main composer keeps its dismissed mention menu closed through a thread send", async ({
   page,
 }) => {
   await installAudienceFixtures(page, { sendMessageDelayMs: 500 });
@@ -741,6 +741,18 @@ test("the unfocused main composer keeps its mention menu closed during a thread
     "false",
   );
   await expect(mainComposer.getByTestId("mention-autocomplete")).toHaveCount(0);
+
+  // Refocusing the drafted composer must not resurrect the menu the user
+  // dismissed with Escape: the setEditable toggles around the send used to
+  // emit a phantom update that replayed the stale "@Morgarita" query and
+  // flipped the mention state back open, so a bare click brought the menu
+  // back without any typing.
+  await mainInput.click();
+  await expect(mainInput).toBeFocused();
+  await expect(mainComposer.getByTestId("mention-autocomplete")).toHaveCount(0);
+  expect(await mainComposer.getAttribute("data-mention-menu-reopened")).toBe(
+    "false",
+  );
 });
 
 test("a failed always-mentioned send shakes the composer avatar without replaying its selection animation", async ({

From 55043a47b2a03d7f6b0aff2ce37c6b319a269d7f Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Wed, 26 Aug 2026 16:26:59 +1000
Subject: [PATCH 3/7] fix(desktop): gate composer autocompletes on editor focus
 internally
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The focus gate that keeps a background composer from rendering stale
suggestion overlays lived in MessageComposer's render, so ForumComposer
— which renders the same autocomplete components and toggles its own
editable state during submission — was left ungated, and any future
composer surface could silently reintroduce this class of bug. Move the
gate into MentionAutocomplete, ChannelAutocomplete, and
EmojiAutocomplete behind a required isEditorFocused prop, wire both
composers through it, and cover the gate in the MentionAutocomplete
unit tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../src/features/forum/ui/ForumComposer.tsx   |  1 +
 .../forum/ui/ForumComposerAutocompletes.tsx   |  4 +++
 .../messages/ui/ChannelAutocomplete.tsx       |  8 ++++-
 .../messages/ui/EmojiAutocomplete.tsx         |  8 ++++-
 .../messages/ui/MentionAutocomplete.test.mjs  | 36 +++++++++++++++++++
 .../messages/ui/MentionAutocomplete.tsx       | 10 +++++-
 .../features/messages/ui/MessageComposer.tsx  | 25 +++++++------
 7 files changed, 78 insertions(+), 14 deletions(-)

diff --git a/desktop/src/features/forum/ui/ForumComposer.tsx b/desktop/src/features/forum/ui/ForumComposer.tsx
index 53b09cfd1dd..44d420fc14e 100644
--- a/desktop/src/features/forum/ui/ForumComposer.tsx
+++ b/desktop/src/features/forum/ui/ForumComposer.tsx
@@ -526,6 +526,7 @@ export function ForumComposer({
                   ? channelLinks.channelSuggestions
                   : []
               }
+              isEditorFocused={richText.isFocused}
               mentionSelectedIndex={mentions.mentionSelectedIndex}
               mentionSuggestions={
                 mentions.isMentionOpen ? mentions.suggestions : []
diff --git a/desktop/src/features/forum/ui/ForumComposerAutocompletes.tsx b/desktop/src/features/forum/ui/ForumComposerAutocompletes.tsx
index 149eec7b91c..b5dd8951c78 100644
--- a/desktop/src/features/forum/ui/ForumComposerAutocompletes.tsx
+++ b/desktop/src/features/forum/ui/ForumComposerAutocompletes.tsx
@@ -8,6 +8,7 @@ import {
 type ForumComposerAutocompletesProps = {
   channelSelectedIndex: number;
   channelSuggestions: ChannelSuggestion[];
+  isEditorFocused: boolean;
   mentionSelectedIndex: number;
   mentionSuggestions: MentionSuggestion[];
   onChannelSelect: (suggestion: ChannelSuggestion) => void;
@@ -20,6 +21,7 @@ type ForumComposerAutocompletesProps = {
 export function ForumComposerAutocompletes({
   channelSelectedIndex,
   channelSuggestions,
+  isEditorFocused,
   mentionSelectedIndex,
   mentionSuggestions,
   onChannelSelect,
@@ -31,12 +33,14 @@ export function ForumComposerAutocompletes({
   return (
     <>
       <ChannelAutocomplete
+        isEditorFocused={isEditorFocused}
         onSelect={onChannelSelect}
         position={position}
         selectedIndex={channelSelectedIndex}
         suggestions={channelSuggestions}
       />
       <MentionAutocomplete
+        isEditorFocused={isEditorFocused}
         onDismiss={onMentionDismiss}
         onFetchMore={onMentionFetchMore}
         onSelect={onMentionSelect}
diff --git a/desktop/src/features/messages/ui/ChannelAutocomplete.tsx b/desktop/src/features/messages/ui/ChannelAutocomplete.tsx
index 1305919a1c9..c79b954dc29 100644
--- a/desktop/src/features/messages/ui/ChannelAutocomplete.tsx
+++ b/desktop/src/features/messages/ui/ChannelAutocomplete.tsx
@@ -12,6 +12,11 @@ import {
 type ChannelAutocompleteProps = {
   suggestions: ChannelSuggestion[];
   selectedIndex: number;
+  /**
+   * Whether the owning composer's editor holds focus. Unfocused composers
+   * must not render suggestions — see MentionAutocomplete for the rationale.
+   */
+  isEditorFocused: boolean;
   onSelect: (suggestion: ChannelSuggestion) => void;
   position?: "above" | "below";
 };
@@ -19,6 +24,7 @@ type ChannelAutocompleteProps = {
 export const ChannelAutocomplete = React.memo(function ChannelAutocomplete({
   suggestions,
   selectedIndex,
+  isEditorFocused,
   onSelect,
   position = "above",
 }: ChannelAutocompleteProps) {
@@ -31,7 +37,7 @@ export const ChannelAutocomplete = React.memo(function ChannelAutocomplete({
     activeItem?.scrollIntoView({ block: "nearest" });
   }, [selectedIndex]);
 
-  if (suggestions.length === 0) {
+  if (!isEditorFocused || suggestions.length === 0) {
     return null;
   }
 
diff --git a/desktop/src/features/messages/ui/EmojiAutocomplete.tsx b/desktop/src/features/messages/ui/EmojiAutocomplete.tsx
index d44933aef1f..7005a43123a 100644
--- a/desktop/src/features/messages/ui/EmojiAutocomplete.tsx
+++ b/desktop/src/features/messages/ui/EmojiAutocomplete.tsx
@@ -15,6 +15,11 @@ import {
 type EmojiAutocompleteProps = {
   suggestions: EmojiSuggestion[];
   selectedIndex: number;
+  /**
+   * Whether the owning composer's editor holds focus. Unfocused composers
+   * must not render suggestions — see MentionAutocomplete for the rationale.
+   */
+  isEditorFocused: boolean;
   onSelect: (suggestion: EmojiSuggestion) => void;
   position?: "above" | "below";
 };
@@ -22,6 +27,7 @@ type EmojiAutocompleteProps = {
 export const EmojiAutocomplete = React.memo(function EmojiAutocomplete({
   suggestions,
   selectedIndex,
+  isEditorFocused,
   onSelect,
   position = "above",
 }: EmojiAutocompleteProps) {
@@ -40,7 +46,7 @@ export const EmojiAutocomplete = React.memo(function EmojiAutocomplete({
     [],
   );
 
-  if (suggestions.length === 0) {
+  if (!isEditorFocused || suggestions.length === 0) {
     return null;
   }
 
diff --git a/desktop/src/features/messages/ui/MentionAutocomplete.test.mjs b/desktop/src/features/messages/ui/MentionAutocomplete.test.mjs
index be3ec6938ef..a9ce1df9457 100644
--- a/desktop/src/features/messages/ui/MentionAutocomplete.test.mjs
+++ b/desktop/src/features/messages/ui/MentionAutocomplete.test.mjs
@@ -50,6 +50,7 @@ test("agent rows offer automatic mention controls", async () => {
   const props = {
     suggestions: [suggestion],
     selectedIndex: 0,
+    isEditorFocused: true,
     onSelect: (value) => selected.push(value),
     onToggleAlwaysAddressAgent: (value) => toggled.push(value),
     lockedAgentPubkeys: new Set(),
@@ -119,6 +120,7 @@ test("options expand in place without replacing the people list", async () => {
     React.createElement(MentionAutocomplete, {
       suggestions: [suggestion],
       selectedIndex: 0,
+      isEditorFocused: true,
       onSelect: () => {},
       keepMentionedAgentsPinned: true,
       onKeepMentionedAgentsPinnedChange: (value) => changes.push(value),
@@ -150,6 +152,7 @@ test("options expand in place without replacing the people list", async () => {
     React.createElement(MentionAutocomplete, {
       suggestions: [],
       selectedIndex: 0,
+      isEditorFocused: true,
       onSelect: () => {},
       keepMentionedAgentsPinned: false,
       onKeepMentionedAgentsPinnedChange: (value) => changes.push(value),
@@ -161,6 +164,7 @@ test("options expand in place without replacing the people list", async () => {
     React.createElement(MentionAutocomplete, {
       suggestions: [suggestion],
       selectedIndex: 0,
+      isEditorFocused: true,
       onSelect: () => {},
       keepMentionedAgentsPinned: false,
       onKeepMentionedAgentsPinnedChange: (value) => changes.push(value),
@@ -252,6 +256,7 @@ test("clicking outside dismisses the tray without intercepting its trigger", asy
         React.createElement(MentionAutocomplete, {
           suggestions: [suggestion],
           selectedIndex: 0,
+          isEditorFocused: true,
           onDismiss: () => {
             dismissCount += 1;
           },
@@ -311,6 +316,7 @@ test("collision npubs sit inline with agent metadata", async () => {
     React.createElement(MentionAutocomplete, {
       suggestions,
       selectedIndex: 0,
+      isEditorFocused: true,
       onSelect: () => {},
     }),
   );
@@ -360,6 +366,7 @@ test("does not intercept Tab from the editor", async () => {
         React.createElement(MentionAutocomplete, {
           suggestions,
           selectedIndex: 1,
+          isEditorFocused: true,
           onSelect: () => {},
           onToggleAlwaysAddressAgent: () => {},
         }),
@@ -374,6 +381,35 @@ test("does not intercept Tab from the editor", async () => {
   assert.equal(wasNotCancelled, true);
   assert.equal(document.activeElement, input);
 });
+
+test("renders nothing while the editor is unfocused", async () => {
+  const React = await import("react");
+  const { render } = await import("@testing-library/react");
+  const { MentionAutocomplete } = await import("./MentionAutocomplete.tsx");
+  const props = {
+    suggestions: [
+      {
+        pubkey: "agent-pubkey",
+        displayName: "Agent Ada",
+        isAgent: true,
+      },
+    ],
+    selectedIndex: 0,
+    isEditorFocused: false,
+    onSelect: () => {},
+  };
+  const view = render(React.createElement(MentionAutocomplete, props));
+
+  assert.equal(view.queryByTestId("mention-autocomplete-layer"), null);
+
+  view.rerender(
+    React.createElement(MentionAutocomplete, {
+      ...props,
+      isEditorFocused: true,
+    }),
+  );
+  assert.ok(view.getByTestId("mention-autocomplete-layer"));
+});
 function suggestion(agentProvenance) {
   return {
     pubkey: "1".repeat(64),
diff --git a/desktop/src/features/messages/ui/MentionAutocomplete.tsx b/desktop/src/features/messages/ui/MentionAutocomplete.tsx
index 08b7dfb37ce..fda69433f47 100644
--- a/desktop/src/features/messages/ui/MentionAutocomplete.tsx
+++ b/desktop/src/features/messages/ui/MentionAutocomplete.tsx
@@ -37,6 +37,13 @@ export type MentionSuggestion = {
 type MentionAutocompleteProps = {
   suggestions: MentionSuggestion[];
   selectedIndex: number;
+  /**
+   * Whether the owning composer's editor holds focus. The focus gate lives
+   * here rather than in each composer so a background composer replaying a
+   * stale update (e.g. a shared mid-send disabled toggle) can't resurrect
+   * its suggestion overlay.
+   */
+  isEditorFocused: boolean;
   onFetchMore?: () => void;
   onSelect: (suggestion: MentionSuggestion) => void;
   lockedAgentPubkeys?: ReadonlySet<string>;
@@ -59,6 +66,7 @@ export function showMentionAgentProvenanceMarker(
 export const MentionAutocomplete = React.memo(function MentionAutocomplete({
   suggestions,
   selectedIndex,
+  isEditorFocused,
   onFetchMore,
   onSelect,
   lockedAgentPubkeys,
@@ -145,7 +153,7 @@ export const MentionAutocomplete = React.memo(function MentionAutocomplete({
     }
   }, [onFetchMore]);
 
-  if (suggestions.length === 0) {
+  if (!isEditorFocused || suggestions.length === 0) {
     return null;
   }
 
diff --git a/desktop/src/features/messages/ui/MessageComposer.tsx b/desktop/src/features/messages/ui/MessageComposer.tsx
index 4d80ede1a75..fc06355d8b2 100644
--- a/desktop/src/features/messages/ui/MessageComposer.tsx
+++ b/desktop/src/features/messages/ui/MessageComposer.tsx
@@ -783,8 +783,6 @@ function MessageComposerImpl({
   const handlePaperclipClick = React.useCallback(() => {
     void media.handlePaperclip();
   }, [media.handlePaperclip]);
-  const gate = <T,>(open: boolean, suggestions: T[]) =>
-    richText.isFocused && open ? suggestions : [];
   return (
     <>
       <footer
@@ -843,22 +841,27 @@ function MessageComposerImpl({
           >
             {ownsDropZone && media.isDragOver && <DropZoneOverlay />}
             <EmojiAutocomplete
+              isEditorFocused={richText.isFocused}
               onSelect={applyEmojiInsert}
               selectedIndex={emojiAutocomplete.emojiSelectedIndex}
-              suggestions={gate(
-                emojiAutocomplete.isEmojiAutocompleteOpen,
-                emojiAutocomplete.emojiSuggestions,
-              )}
+              suggestions={
+                emojiAutocomplete.isEmojiAutocompleteOpen
+                  ? emojiAutocomplete.emojiSuggestions
+                  : []
+              }
             />
             <ChannelAutocomplete
+              isEditorFocused={richText.isFocused}
               onSelect={applyChannelInsert}
               selectedIndex={channelLinks.channelSelectedIndex}
-              suggestions={gate(
-                channelLinks.isChannelOpen,
-                channelLinks.channelSuggestions,
-              )}
+              suggestions={
+                channelLinks.isChannelOpen
+                  ? channelLinks.channelSuggestions
+                  : []
+              }
             />
             <MentionAutocomplete
+              isEditorFocused={richText.isFocused}
               keepMentionedAgentsPinned={keepMentionedAgentsPinned}
               lockedAgentPubkeys={lockedAgentPubkeys}
               openOptionsRequest={openMentionOptionsRequest}
@@ -877,7 +880,7 @@ function MessageComposerImpl({
               onDismiss={mentions.cancelMentionAutocomplete}
               onSelect={selectMentionSuggestion}
               selectedIndex={mentions.mentionSelectedIndex}
-              suggestions={gate(mentions.isMentionOpen, mentions.suggestions)}
+              suggestions={mentions.isMentionOpen ? mentions.suggestions : []}
             />
             {media.uploadState.status === "error" ? (
               <div className="mb-2 rounded-lg bg-destructive/10 px-3 py-2 text-xs text-destructive">

From 3179751cecaf6a675c8509ef5ec54af104ba8f86 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Wed, 26 Aug 2026 16:29:02 +1000
Subject: [PATCH 4/7] test(desktop): widen the thread-send mid-send assertion
 window
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The dismissed-mention-menu regression test asserted the main composer's
contenteditable=false state inside a 500ms send window, while sibling
tests use 1500-2000ms for equivalent mid-send checks — on a loaded CI
runner the window could close before the first poll. Bump the fixture's
sendMessageDelayMs to 1500 to match; the MutationObserver-based core
regression check was already timing-independent.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 desktop/tests/e2e/persistent-agent-audience.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/desktop/tests/e2e/persistent-agent-audience.spec.ts b/desktop/tests/e2e/persistent-agent-audience.spec.ts
index 7593cd736a0..9ea3e6e7862 100644
--- a/desktop/tests/e2e/persistent-agent-audience.spec.ts
+++ b/desktop/tests/e2e/persistent-agent-audience.spec.ts
@@ -693,7 +693,7 @@ test("always-mentioned agents remain selected without replaying their animation
 test("the unfocused main composer keeps its dismissed mention menu closed through a thread send", async ({
   page,
 }) => {
-  await installAudienceFixtures(page, { sendMessageDelayMs: 500 });
+  await installAudienceFixtures(page, { sendMessageDelayMs: 1_500 });
   await openGeneral(page);
 
   const mainComposer = channelComposer(page);

From 755e2d8eccf925d92a8fcc4c8528654de13698f6 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Wed, 26 Aug 2026 16:41:18 +1000
Subject: [PATCH 5/7] refactor(desktop): extract the message composer's
 autocomplete overlays

The focus-gate prop pushed MessageComposer.tsx three lines past the 1000-line
ceiling. Extract its three suggestion overlays into a sibling component,
mirroring the existing ForumComposerAutocompletes split, so the composer sheds
the block rather than the gate raising the limit.

Behavior is unchanged: the two agent-audience callbacks were each guarded by
`audienceScope && editTarget == null`, so that predicate crosses the boundary
once as `audienceControlsEnabled` and the child resolves both callbacks from it.

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../features/messages/ui/MessageComposer.tsx  |  51 +++------
 .../ui/MessageComposerAutocompletes.tsx       | 102 ++++++++++++++++++
 2 files changed, 114 insertions(+), 39 deletions(-)
 create mode 100644 desktop/src/features/messages/ui/MessageComposerAutocompletes.tsx

diff --git a/desktop/src/features/messages/ui/MessageComposer.tsx b/desktop/src/features/messages/ui/MessageComposer.tsx
index fc06355d8b2..d66968c8b69 100644
--- a/desktop/src/features/messages/ui/MessageComposer.tsx
+++ b/desktop/src/features/messages/ui/MessageComposer.tsx
@@ -46,11 +46,9 @@ import { useLinkEditor } from "@/features/messages/lib/useLinkEditor";
 import { useComposerSpoilerParticles } from "@/features/messages/lib/useComposerSpoilerParticles";
 import { useTypingBroadcast } from "@/features/messages/useTypingBroadcast";
 import { cn } from "@/shared/lib/cn";
-import { ChannelAutocomplete } from "./ChannelAutocomplete";
 import { ComposerReplyEditBanner } from "./ComposerReplyEditBanner";
 import { ComposerAttachments, DropZoneOverlay } from "./ComposerAttachments";
-import { EmojiAutocomplete } from "./EmojiAutocomplete";
-import { MentionAutocomplete } from "./MentionAutocomplete";
+import { MessageComposerAutocompletes } from "./MessageComposerAutocompletes";
 import { ComposerDockToolbar } from "./ComposerDockToolbar";
 import { ComposerUploadProgressPill } from "./ComposerUploadProgressPill";
 import { NonMemberMentionDialog } from "./NonMemberMentionDialog";
@@ -840,47 +838,22 @@ function MessageComposerImpl({
             }}
           >
             {ownsDropZone && media.isDragOver && <DropZoneOverlay />}
-            <EmojiAutocomplete
-              isEditorFocused={richText.isFocused}
-              onSelect={applyEmojiInsert}
-              selectedIndex={emojiAutocomplete.emojiSelectedIndex}
-              suggestions={
-                emojiAutocomplete.isEmojiAutocompleteOpen
-                  ? emojiAutocomplete.emojiSuggestions
-                  : []
-              }
-            />
-            <ChannelAutocomplete
-              isEditorFocused={richText.isFocused}
-              onSelect={applyChannelInsert}
-              selectedIndex={channelLinks.channelSelectedIndex}
-              suggestions={
-                channelLinks.isChannelOpen
-                  ? channelLinks.channelSuggestions
-                  : []
-              }
-            />
-            <MentionAutocomplete
+            <MessageComposerAutocompletes
+              audienceControlsEnabled={Boolean(
+                audienceScope && editTarget == null,
+              )}
+              channelLinks={channelLinks}
+              emojiAutocomplete={emojiAutocomplete}
               isEditorFocused={richText.isFocused}
               keepMentionedAgentsPinned={keepMentionedAgentsPinned}
               lockedAgentPubkeys={lockedAgentPubkeys}
+              mentions={mentions}
               openOptionsRequest={openMentionOptionsRequest}
-              onKeepMentionedAgentsPinnedChange={
-                audienceScope && editTarget == null
-                  ? setKeepMentionedAgentsPinned
-                  : undefined
-              }
+              onChannelSelect={applyChannelInsert}
+              onEmojiSelect={applyEmojiInsert}
+              onMentionSelect={selectMentionSuggestion}
               onOptionsRevealComplete={completeMentionOptionsReveal}
-              onToggleAlwaysAddressAgent={
-                audienceScope && editTarget == null
-                  ? toggleAlwaysAddressAgent
-                  : undefined
-              }
-              onFetchMore={mentions.fetchMoreSuggestions}
-              onDismiss={mentions.cancelMentionAutocomplete}
-              onSelect={selectMentionSuggestion}
-              selectedIndex={mentions.mentionSelectedIndex}
-              suggestions={mentions.isMentionOpen ? mentions.suggestions : []}
+              onToggleAlwaysAddressAgent={toggleAlwaysAddressAgent}
             />
             {media.uploadState.status === "error" ? (
               <div className="mb-2 rounded-lg bg-destructive/10 px-3 py-2 text-xs text-destructive">
diff --git a/desktop/src/features/messages/ui/MessageComposerAutocompletes.tsx b/desktop/src/features/messages/ui/MessageComposerAutocompletes.tsx
new file mode 100644
index 00000000000..08601eb59df
--- /dev/null
+++ b/desktop/src/features/messages/ui/MessageComposerAutocompletes.tsx
@@ -0,0 +1,102 @@
+import { setKeepMentionedAgentsPinned } from "@/features/messages/lib/autoPinMentionedAgentsPreference";
+import type {
+  ChannelSuggestion,
+  UseChannelLinksResult,
+} from "@/features/messages/lib/useChannelLinks";
+import type {
+  EmojiSuggestion,
+  UseEmojiAutocompleteResult,
+} from "@/features/messages/lib/useEmojiAutocomplete";
+import type { UseMentionsResult } from "@/features/messages/lib/useMentions";
+import { ChannelAutocomplete } from "./ChannelAutocomplete";
+import { EmojiAutocomplete } from "./EmojiAutocomplete";
+import {
+  MentionAutocomplete,
+  type MentionSuggestion,
+} from "./MentionAutocomplete";
+
+type MessageComposerAutocompletesProps = {
+  /**
+   * Whether the mention menu offers its agent-audience controls. Edit
+   * composers and channels without a persistent audience omit them.
+   */
+  audienceControlsEnabled: boolean;
+  channelLinks: UseChannelLinksResult;
+  emojiAutocomplete: UseEmojiAutocompleteResult;
+  isEditorFocused: boolean;
+  keepMentionedAgentsPinned: boolean;
+  lockedAgentPubkeys: ReadonlySet<string>;
+  mentions: UseMentionsResult;
+  /**
+   * Bumped to ask the mention menu to reveal its agent-audience options; the
+   * menu reports back through `onOptionsRevealComplete` once it has.
+   */
+  openOptionsRequest?: number;
+  onChannelSelect: (suggestion: ChannelSuggestion) => void;
+  onEmojiSelect: (suggestion: EmojiSuggestion) => void;
+  onMentionSelect: (suggestion: MentionSuggestion) => void;
+  onOptionsRevealComplete?: (request: number) => void;
+  onToggleAlwaysAddressAgent: (suggestion: MentionSuggestion) => void;
+};
+
+/**
+ * The message composer's three suggestion overlays. Each one gates its own
+ * rendering on `isEditorFocused`, so a background composer replaying a stale
+ * update cannot resurrect a suggestion menu over the focused composer.
+ */
+export function MessageComposerAutocompletes({
+  audienceControlsEnabled,
+  channelLinks,
+  emojiAutocomplete,
+  isEditorFocused,
+  keepMentionedAgentsPinned,
+  lockedAgentPubkeys,
+  mentions,
+  openOptionsRequest,
+  onChannelSelect,
+  onEmojiSelect,
+  onMentionSelect,
+  onOptionsRevealComplete,
+  onToggleAlwaysAddressAgent,
+}: MessageComposerAutocompletesProps) {
+  return (
+    <>
+      <EmojiAutocomplete
+        isEditorFocused={isEditorFocused}
+        onSelect={onEmojiSelect}
+        selectedIndex={emojiAutocomplete.emojiSelectedIndex}
+        suggestions={
+          emojiAutocomplete.isEmojiAutocompleteOpen
+            ? emojiAutocomplete.emojiSuggestions
+            : []
+        }
+      />
+      <ChannelAutocomplete
+        isEditorFocused={isEditorFocused}
+        onSelect={onChannelSelect}
+        selectedIndex={channelLinks.channelSelectedIndex}
+        suggestions={
+          channelLinks.isChannelOpen ? channelLinks.channelSuggestions : []
+        }
+      />
+      <MentionAutocomplete
+        isEditorFocused={isEditorFocused}
+        keepMentionedAgentsPinned={keepMentionedAgentsPinned}
+        lockedAgentPubkeys={lockedAgentPubkeys}
+        openOptionsRequest={openOptionsRequest}
+        onKeepMentionedAgentsPinnedChange={
+          audienceControlsEnabled ? setKeepMentionedAgentsPinned : undefined
+        }
+        onOptionsRevealComplete={onOptionsRevealComplete}
+        onToggleAlwaysAddressAgent={
+          audienceControlsEnabled ? onToggleAlwaysAddressAgent : undefined
+        }
+        onFetchMore={mentions.fetchMoreSuggestions}
+        onDismiss={mentions.cancelMentionAutocomplete}
+        onSelect={onMentionSelect}
+        selectedIndex={mentions.mentionSelectedIndex}
+        suggestions={mentions.isMentionOpen ? mentions.suggestions : []}
+      />
+    </>
+  );
+}

From 97be71ba0204cdbcc75aa3886ea09e34a07f9891 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Wed, 26 Aug 2026 20:46:05 +1000
Subject: [PATCH 6/7] fix(desktop): keep autocomplete overlays open on
 container presses
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The focus gate that stops a background composer from rendering stale
suggestions unmounts an overlay the moment its editor blurs, and a
mousedown steals focus from a contenteditable unless the handler
prevents its default. The controls inside these overlays already did;
their containers did not, so any container-targeted press tore the
overlay down mid-interaction — the mention list's padding ring on every
platform, and its scrollbar wherever a non-overlay one is rendered
(Windows WebView2, macOS with "Show scroll bars: Always"), plus the same
holes in the channel and emoji lists.

Prevent mousedown on each overlay's container, matching the idiom the
inner controls already use. Not pointerdown: cancelling that would
suppress the compatibility mouse events the suggestion rows select on.

The options surface needed one more step. A label hands focus to its
control from the click default action, which no mousedown guard can
cancel, so clicking the "Automatically mention agents" text still blurred
the editor and the overlay vanished before the forwarded click reached
the switch. Cancel the label's forwarding and drive the switch directly,
keeping the htmlFor association for assistive tech.

Cover the container presses and the label in the MentionAutocomplete
unit tests, and add an E2E regression test that presses the live mention
list's padding ring and then its options label.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../messages/ui/ChannelAutocomplete.tsx       |  2 +
 .../messages/ui/EmojiAutocomplete.tsx         |  2 +
 .../messages/ui/MentionAutocomplete.test.mjs  | 48 +++++++++++++++++++
 .../messages/ui/MentionAutocomplete.tsx       | 18 +++++++
 .../e2e/persistent-agent-audience.spec.ts     | 38 +++++++++++++++
 5 files changed, 108 insertions(+)

diff --git a/desktop/src/features/messages/ui/ChannelAutocomplete.tsx b/desktop/src/features/messages/ui/ChannelAutocomplete.tsx
index c79b954dc29..bf34e9f252c 100644
--- a/desktop/src/features/messages/ui/ChannelAutocomplete.tsx
+++ b/desktop/src/features/messages/ui/ChannelAutocomplete.tsx
@@ -48,6 +48,7 @@ export const ChannelAutocomplete = React.memo(function ChannelAutocomplete({
         position === "below" ? "top-full mt-1" : "bottom-full mb-1",
       )}
     >
+      {/* biome-ignore lint/a11y/noStaticElementInteractions: pointer-only guard, no behavior of its own — an unprevented mousedown here (scrollbar, padding ring) blurs the editor, and the focus gate above would unmount the overlay mid-press. */}
       <div
         className={cn(
           "max-h-48 overflow-y-auto rounded-xl p-1",
@@ -57,6 +58,7 @@ export const ChannelAutocomplete = React.memo(function ChannelAutocomplete({
             : "origin-bottom slide-in-from-bottom-1",
           POPOVER_SURFACE_CLASS,
         )}
+        onMouseDown={(event) => event.preventDefault()}
         ref={listRef}
         style={POPOVER_SHADOW_STYLE}
       >
diff --git a/desktop/src/features/messages/ui/EmojiAutocomplete.tsx b/desktop/src/features/messages/ui/EmojiAutocomplete.tsx
index 7005a43123a..20909381f5f 100644
--- a/desktop/src/features/messages/ui/EmojiAutocomplete.tsx
+++ b/desktop/src/features/messages/ui/EmojiAutocomplete.tsx
@@ -57,6 +57,7 @@ export const EmojiAutocomplete = React.memo(function EmojiAutocomplete({
         position === "below" ? "top-full mt-1" : "bottom-full mb-1",
       )}
     >
+      {/* biome-ignore lint/a11y/noStaticElementInteractions: pointer-only guard, no behavior of its own — an unprevented mousedown here blurs the editor, and the focus gate above would unmount the overlay mid-press. The scroll element lives inside VirtualizedList, but its mousedown bubbles to this wrapper and preventDefault acts on the same event, so scrollbar presses are covered too. */}
       <div
         className={cn(
           "rounded-xl p-1",
@@ -67,6 +68,7 @@ export const EmojiAutocomplete = React.memo(function EmojiAutocomplete({
           POPOVER_SURFACE_CLASS,
         )}
         data-testid="emoji-autocomplete"
+        onMouseDown={(event) => event.preventDefault()}
         style={POPOVER_SHADOW_STYLE}
       >
         <VirtualizedList
diff --git a/desktop/src/features/messages/ui/MentionAutocomplete.test.mjs b/desktop/src/features/messages/ui/MentionAutocomplete.test.mjs
index a9ce1df9457..53478946732 100644
--- a/desktop/src/features/messages/ui/MentionAutocomplete.test.mjs
+++ b/desktop/src/features/messages/ui/MentionAutocomplete.test.mjs
@@ -410,6 +410,54 @@ test("renders nothing while the editor is unfocused", async () => {
   );
   assert.ok(view.getByTestId("mention-autocomplete-layer"));
 });
+
+test("container presses do not blur the editor out from under the overlay", async () => {
+  const React = await import("react");
+  const { fireEvent, render } = await import("@testing-library/react");
+  const { MentionAutocomplete } = await import("./MentionAutocomplete.tsx");
+  const mention = {
+    pubkey: "agent-pubkey",
+    displayName: "Agent Ada",
+    isAgent: true,
+  };
+  const selected = [];
+  const pinnedChanges = [];
+  const view = render(
+    React.createElement(MentionAutocomplete, {
+      suggestions: [mention],
+      selectedIndex: 0,
+      isEditorFocused: true,
+      onSelect: (value) => selected.push(value),
+      keepMentionedAgentsPinned: true,
+      onKeepMentionedAgentsPinnedChange: (value) => pinnedChanges.push(value),
+    }),
+  );
+
+  // fireEvent returns false when the dispatched event was canceled, which is
+  // what keeps a contenteditable from losing focus on mousedown.
+  assert.equal(
+    fireEvent.mouseDown(view.getByTestId("mention-autocomplete")),
+    false,
+  );
+
+  const options = view.getByRole("button", { name: "Options" });
+  assert.equal(fireEvent.mouseDown(options.parentElement), false);
+
+  // A label hands focus to its control from the click default action, which
+  // no mousedown guard can cancel, so the label drives the switch itself.
+  fireEvent.click(options);
+  assert.equal(
+    fireEvent.click(view.getByText("Automatically mention agents")),
+    false,
+  );
+  assert.deepEqual(pinnedChanges, [false]);
+
+  // The row buttons must keep selecting: preventing mousedown on the
+  // containers, not pointerdown, leaves their compatibility events intact.
+  fireEvent.mouseDown(view.getByRole("button", { name: "Mention Agent Ada" }));
+  assert.deepEqual(selected, [mention]);
+});
+
 function suggestion(agentProvenance) {
   return {
     pubkey: "1".repeat(64),
diff --git a/desktop/src/features/messages/ui/MentionAutocomplete.tsx b/desktop/src/features/messages/ui/MentionAutocomplete.tsx
index fda69433f47..7d913b3084d 100644
--- a/desktop/src/features/messages/ui/MentionAutocomplete.tsx
+++ b/desktop/src/features/messages/ui/MentionAutocomplete.tsx
@@ -178,12 +178,14 @@ export const MentionAutocomplete = React.memo(function MentionAutocomplete({
       <div className="w-full max-w-2xl">
         {onKeepMentionedAgentsPinnedChange ? (
           <div className="mb-2 flex justify-end">
+            {/* biome-ignore lint/a11y/noStaticElementInteractions: pointer-only guard, no behavior of its own — an unprevented mousedown on this surface (its padding, the switch's label) blurs the editor, and the focus gate above would unmount the overlay before the click lands. */}
             <div
               className={cn(
                 "max-w-full overflow-hidden rounded-xl text-popover-foreground ring-1 ring-border/50 transition-[width] duration-200 ease-out",
                 POPOVER_SURFACE_CLASS,
                 optionsOpen ? "w-72" : "w-24",
               )}
+              onMouseDown={(event) => event.preventDefault()}
               ref={optionsSurfaceRef}
               style={POPOVER_SHADOW_STYLE}
             >
@@ -202,9 +204,23 @@ export const MentionAutocomplete = React.memo(function MentionAutocomplete({
                   transition={{ duration: 0.16, ease: "easeOut" }}
                 >
                   <div className="flex min-h-12 items-center justify-between gap-3 px-3 py-2">
+                    {/* A label moves focus to its control from the click
+                        default action, not from mousedown, so the surface's
+                        mousedown guard alone can't keep the editor focused
+                        here. Cancel the forwarding and drive the switch
+                        directly; the association still names the control for
+                        assistive tech, which reaches the switch by keyboard
+                        without going through this label. */}
+                    {/* biome-ignore lint/a11y/useKeyWithClickEvents: pointer-only affordance; the switch it labels is the keyboard-accessible path. */}
                     <label
                       className="flex min-w-0 flex-col"
                       htmlFor={keepPinnedSwitchId}
+                      onClick={(event) => {
+                        event.preventDefault();
+                        onKeepMentionedAgentsPinnedChange?.(
+                          !keepMentionedAgentsPinned,
+                        );
+                      }}
                     >
                       <span className="text-sm font-medium">
                         Automatically mention agents
@@ -247,6 +263,7 @@ export const MentionAutocomplete = React.memo(function MentionAutocomplete({
             </div>
           </div>
         ) : null}
+        {/* biome-ignore lint/a11y/noStaticElementInteractions: pointer-only guard, same as the options surface — here it covers presses on the scrollbar and the list's padding ring. */}
         <div
           className={cn(
             "max-h-48 w-full overflow-y-auto rounded-xl p-1",
@@ -257,6 +274,7 @@ export const MentionAutocomplete = React.memo(function MentionAutocomplete({
             POPOVER_SURFACE_CLASS,
           )}
           data-testid="mention-autocomplete"
+          onMouseDown={(event) => event.preventDefault()}
           onScroll={handleScroll}
           ref={listRef}
           style={POPOVER_SHADOW_STYLE}
diff --git a/desktop/tests/e2e/persistent-agent-audience.spec.ts b/desktop/tests/e2e/persistent-agent-audience.spec.ts
index 9ea3e6e7862..d22d192598b 100644
--- a/desktop/tests/e2e/persistent-agent-audience.spec.ts
+++ b/desktop/tests/e2e/persistent-agent-audience.spec.ts
@@ -755,6 +755,44 @@ test("the unfocused main composer keeps its dismissed mention menu closed throug
   );
 });
 
+test("pressing a mention overlay's own container keeps it open", async ({
+  page,
+}) => {
+  await keepMentionedAgentsPinned(page);
+  await installAudienceFixtures(page);
+  await openGeneral(page);
+
+  const composer = channelComposer(page);
+  const input = composer.getByTestId("message-input");
+  await composer.getByTestId("message-insert-mention").click();
+  const list = composer.getByTestId("mention-autocomplete");
+  await expect(list).toBeVisible();
+  await expect(input).toBeFocused();
+
+  // A mousedown landing on the list container itself — its padding ring here,
+  // a native scrollbar on platforms that render one — steals focus from the
+  // editor unless the default is prevented, and the focus gate would then
+  // unmount the menu mid-press.
+  const listBox = await list.boundingBox();
+  if (!listBox) throw new Error("mention list is not laid out");
+  await list.click({ position: { x: 2, y: listBox.height / 2 } });
+  await expect(input).toBeFocused();
+  await expect(list).toBeVisible();
+
+  // Same hazard on the options surface, where it needs no exotic scrollbar
+  // setting to reproduce: the switch's label text is a container press, so the
+  // overlay used to vanish before the forwarded click reached the switch.
+  await composer.getByTestId("mention-options-trigger").click();
+  const preference = composer.getByTestId("mention-keep-agents-pinned-toggle");
+  await expect(preference).toHaveAttribute("data-state", "checked");
+  await composer
+    .getByText("Automatically mention agents", { exact: true })
+    .click();
+  await expect(preference).toHaveAttribute("data-state", "unchecked");
+  await expect(input).toBeFocused();
+  await expect(list).toBeVisible();
+});
+
 test("a failed always-mentioned send shakes the composer avatar without replaying its selection animation", async ({
   page,
 }) => {

From a666e2cdeb02f3b79fb304483f558236449ec8e6 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Fri, 28 Aug 2026 13:16:35 +1000
Subject: [PATCH 7/7] fix(desktop): keep the mention overlay reachable while
 focus moves into it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The focus gate this branch added answered the wrong question. Gating each
suggestion overlay on the editor's own focus meant the mention overlay
unmounted the instant keyboard focus moved toward its Options button or
switch, so the branch closed a stale-menu bug by foreclosing focus-based
access to those controls — and all three autocomplete key handlers
claimed Tab with or without Shift, so no route in existed to begin with.

Replace the editor-focus gate with composer focus ownership: a
form-scoped hook tracks whether document focus lives anywhere inside the
owning composer, using focusout + relatedTarget containment so an
internal handoff never passes through an unowned state that would
unmount the overlay mid-move. Both composers wire it through as
composerOwnsFocus. The stale-menu protection holds — focus in a sibling
composer's form leaves a background composer unowned, so a replayed
stale update still can't resurrect its overlay — while focus inside the
overlay's own controls now keeps it mounted.

For the route in and back out: stop treating Shift+Tab as a suggestion
select in the mention, channel, and emoji handlers (forward Tab keeps
selecting), have the composer send Shift+Tab from the editor to the
overlay's Options trigger, and handle Escape inside the overlay by
returning focus to the editor before dismissing. From the trigger,
native tab order reaches the switch and the per-row always-mention
toggles; without an Options surface the key falls through to the
browser's backward focus move. The editor-focus state this retires was
the gate's only consumer, so drop it from useRichTextEditor.

Cover focusMentionOptionsTrigger, the Escape exit, and the ownership
hook in unit tests, and add a real-composer E2E that walks editor →
Options → switch by keyboard, operates the switch while a
MutationObserver proves the surface never unmounted, returns via Escape,
re-checks forward-Tab selection, and hands focus to the thread composer
to prove sibling isolation.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../src/features/forum/ui/ForumComposer.tsx   |   6 +-
 .../forum/ui/ForumComposerAutocompletes.tsx   |   8 +-
 .../features/messages/lib/useChannelLinks.ts  |   5 +-
 .../lib/useComposerFocusOwnership.test.mjs    | 121 +++++++++++++
 .../messages/lib/useComposerFocusOwnership.ts |  44 +++++
 .../messages/lib/useEmojiAutocomplete.ts      |   5 +-
 .../src/features/messages/lib/useMentions.ts  |   6 +-
 .../messages/lib/useRichTextEditor.ts         |   4 -
 .../messages/ui/ChannelAutocomplete.tsx       |   8 +-
 .../messages/ui/EmojiAutocomplete.tsx         |   8 +-
 .../messages/ui/MentionAutocomplete.test.mjs  | 164 +++++++++++++-----
 .../messages/ui/MentionAutocomplete.tsx       |  56 +++++-
 .../features/messages/ui/MessageComposer.tsx  |  21 ++-
 .../ui/MessageComposerAutocompletes.tsx       |  16 +-
 .../e2e/persistent-agent-audience.spec.ts     |  79 +++++++++
 15 files changed, 470 insertions(+), 81 deletions(-)
 create mode 100644 desktop/src/features/messages/lib/useComposerFocusOwnership.test.mjs
 create mode 100644 desktop/src/features/messages/lib/useComposerFocusOwnership.ts

diff --git a/desktop/src/features/forum/ui/ForumComposer.tsx b/desktop/src/features/forum/ui/ForumComposer.tsx
index 44d420fc14e..03fb365ebdd 100644
--- a/desktop/src/features/forum/ui/ForumComposer.tsx
+++ b/desktop/src/features/forum/ui/ForumComposer.tsx
@@ -5,6 +5,7 @@ import { ChevronDown } from "lucide-react";
 import { buildOutgoingMessage } from "@/features/messages/lib/imetaMediaMarkdown";
 import { useChannelLinks } from "@/features/messages/lib/useChannelLinks";
 import type { ChannelSuggestion } from "@/features/messages/lib/useChannelLinks";
+import { useComposerFocusOwnership } from "@/features/messages/lib/useComposerFocusOwnership";
 import { useMediaUpload } from "@/features/messages/lib/useMediaUpload";
 import { isMentionCodeContext } from "@/features/messages/lib/mentionCodeContext";
 import { useMentions } from "@/features/messages/lib/useMentions";
@@ -101,6 +102,8 @@ export function ForumComposer({
     mentions.isMentionOpen || channelLinks.isChannelOpen;
 
   const submitMessageRef = React.useRef<() => void>(() => {});
+  const formRef = React.useRef<HTMLFormElement>(null);
+  const composerOwnsFocus = useComposerFocusOwnership(formRef);
 
   // Set after `useLinkEditor` exists; the editor's link-click handler
   // delegates through this ref to break the hook ordering cycle.
@@ -500,6 +503,7 @@ export function ForumComposer({
         }}
         onFocusCapture={expandCompactComposer}
         onSubmit={handleSubmit}
+        ref={formRef}
       >
         {media.isDragOver && <DropZoneOverlay />}
         {isCompactLayout ? (
@@ -526,7 +530,7 @@ export function ForumComposer({
                   ? channelLinks.channelSuggestions
                   : []
               }
-              isEditorFocused={richText.isFocused}
+              composerOwnsFocus={composerOwnsFocus}
               mentionSelectedIndex={mentions.mentionSelectedIndex}
               mentionSuggestions={
                 mentions.isMentionOpen ? mentions.suggestions : []
diff --git a/desktop/src/features/forum/ui/ForumComposerAutocompletes.tsx b/desktop/src/features/forum/ui/ForumComposerAutocompletes.tsx
index b5dd8951c78..e3a63e7dd58 100644
--- a/desktop/src/features/forum/ui/ForumComposerAutocompletes.tsx
+++ b/desktop/src/features/forum/ui/ForumComposerAutocompletes.tsx
@@ -8,7 +8,7 @@ import {
 type ForumComposerAutocompletesProps = {
   channelSelectedIndex: number;
   channelSuggestions: ChannelSuggestion[];
-  isEditorFocused: boolean;
+  composerOwnsFocus: boolean;
   mentionSelectedIndex: number;
   mentionSuggestions: MentionSuggestion[];
   onChannelSelect: (suggestion: ChannelSuggestion) => void;
@@ -21,7 +21,7 @@ type ForumComposerAutocompletesProps = {
 export function ForumComposerAutocompletes({
   channelSelectedIndex,
   channelSuggestions,
-  isEditorFocused,
+  composerOwnsFocus,
   mentionSelectedIndex,
   mentionSuggestions,
   onChannelSelect,
@@ -33,14 +33,14 @@ export function ForumComposerAutocompletes({
   return (
     <>
       <ChannelAutocomplete
-        isEditorFocused={isEditorFocused}
+        composerOwnsFocus={composerOwnsFocus}
         onSelect={onChannelSelect}
         position={position}
         selectedIndex={channelSelectedIndex}
         suggestions={channelSuggestions}
       />
       <MentionAutocomplete
-        isEditorFocused={isEditorFocused}
+        composerOwnsFocus={composerOwnsFocus}
         onDismiss={onMentionDismiss}
         onFetchMore={onMentionFetchMore}
         onSelect={onMentionSelect}
diff --git a/desktop/src/features/messages/lib/useChannelLinks.ts b/desktop/src/features/messages/lib/useChannelLinks.ts
index c9e573b3fc5..4b703f53cd6 100644
--- a/desktop/src/features/messages/lib/useChannelLinks.ts
+++ b/desktop/src/features/messages/lib/useChannelLinks.ts
@@ -177,8 +177,11 @@ export function useChannelLinks() {
         return { handled: true };
       }
 
+      // Forward Tab selects; Shift+Tab deliberately does not. The reverse
+      // move stays the browser's, so this overlay can't swallow a keyboard
+      // user's way back out (see useMentions for the same split).
       if (
-        event.key === "Tab" ||
+        (event.key === "Tab" && !event.shiftKey) ||
         (event.key === "Enter" &&
           !event.ctrlKey &&
           !event.metaKey &&
diff --git a/desktop/src/features/messages/lib/useComposerFocusOwnership.test.mjs b/desktop/src/features/messages/lib/useComposerFocusOwnership.test.mjs
new file mode 100644
index 00000000000..4e467949a8b
--- /dev/null
+++ b/desktop/src/features/messages/lib/useComposerFocusOwnership.test.mjs
@@ -0,0 +1,121 @@
+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,
+    Element: dom.window.Element,
+    Event: dom.window.Event,
+    FocusEvent: dom.window.FocusEvent,
+    getComputedStyle: dom.window.getComputedStyle.bind(dom.window),
+    HTMLElement: dom.window.HTMLElement,
+    IS_REACT_ACT_ENVIRONMENT: true,
+    Node: dom.window.Node,
+    window: dom.window,
+  });
+});
+
+afterEach(async () => {
+  const { cleanup } = await import("@testing-library/react");
+  cleanup();
+});
+
+after(() => dom.window.close());
+
+async function renderHarness() {
+  const React = await import("react");
+  const { render } = await import("@testing-library/react");
+  const { useComposerFocusOwnership } = await import(
+    "./useComposerFocusOwnership.ts"
+  );
+
+  function Harness() {
+    const formRef = React.useRef(null);
+    const ownsFocus = useComposerFocusOwnership(formRef);
+    return React.createElement(
+      React.Fragment,
+      null,
+      React.createElement(
+        "form",
+        { "data-testid": "composer", ref: formRef },
+        React.createElement("input", { "aria-label": "Editor" }),
+        React.createElement("button", { type: "button" }, "Overlay control"),
+        React.createElement("output", {
+          "data-testid": "owned",
+          "data-owned": String(ownsFocus),
+        }),
+      ),
+      React.createElement("input", { "aria-label": "Elsewhere" }),
+    );
+  }
+
+  const view = render(React.createElement(Harness));
+  return {
+    view,
+    ownership: () => view.getByTestId("owned").getAttribute("data-owned"),
+  };
+}
+
+test("tracks focus entering, moving within, and leaving the composer", async () => {
+  const { act } = await import("react");
+  const { view, ownership } = await renderHarness();
+
+  assert.equal(ownership(), "false");
+
+  const editor = view.getByRole("textbox", { name: "Editor" });
+  await act(async () => editor.focus());
+  assert.equal(ownership(), "true");
+
+  // Focus handed from the editor to an overlay control stays owned — this is
+  // the transition an editor-focus gate got wrong, unmounting the overlay
+  // before the control it was handing focus to could receive it.
+  const control = view.getByRole("button", { name: "Overlay control" });
+  await act(async () => control.focus());
+  assert.equal(ownership(), "true");
+
+  const elsewhere = view.getByRole("textbox", { name: "Elsewhere" });
+  await act(async () => elsewhere.focus());
+  assert.equal(ownership(), "false");
+});
+
+test("an internal focus move never reports an unowned intermediate state", async () => {
+  const React = await import("react");
+  const { act } = React;
+  const { render } = await import("@testing-library/react");
+  const { useComposerFocusOwnership } = await import(
+    "./useComposerFocusOwnership.ts"
+  );
+
+  const observed = [];
+  function Harness() {
+    const formRef = React.useRef(null);
+    const ownsFocus = useComposerFocusOwnership(formRef);
+    observed.push(ownsFocus);
+    return React.createElement(
+      "form",
+      { ref: formRef },
+      React.createElement("input", { "aria-label": "Editor" }),
+      React.createElement("button", { type: "button" }, "Overlay control"),
+    );
+  }
+
+  const view = render(React.createElement(Harness));
+  const editor = view.getByRole("textbox", { name: "Editor" });
+  const control = view.getByRole("button", { name: "Overlay control" });
+  await act(async () => editor.focus());
+  observed.length = 0;
+
+  // relatedTarget mirrors a browser handing focus editor → overlay control.
+  // The focusout handler must read it instead of assuming focus left.
+  const { fireEvent } = await import("@testing-library/react");
+  fireEvent.focusOut(editor, { relatedTarget: control });
+  fireEvent.focusIn(control);
+
+  assert.equal(observed.includes(false), false);
+});
diff --git a/desktop/src/features/messages/lib/useComposerFocusOwnership.ts b/desktop/src/features/messages/lib/useComposerFocusOwnership.ts
new file mode 100644
index 00000000000..f39d618dc03
--- /dev/null
+++ b/desktop/src/features/messages/lib/useComposerFocusOwnership.ts
@@ -0,0 +1,44 @@
+import * as React from "react";
+
+/**
+ * Tracks whether a composer owns document focus: true while the focused
+ * element lives anywhere inside `containerRef` (the composer form) — the
+ * editor or the focusable controls of its suggestion overlays.
+ *
+ * This is the value the autocomplete overlays gate their rendering on. It is
+ * deliberately not the editor's own focus state: an overlay gated on editor
+ * focus alone unmounts the moment keyboard focus moves from the editor into
+ * the overlay's controls, which makes those controls unreachable. Ownership
+ * is tracked with `focusout` + `relatedTarget` containment rather than
+ * blur/focus pairs so an internal focus move never passes through a false
+ * state — a false flicker would unmount the overlay before the control it
+ * is handing focus to receives it. Each composer form has its own instance,
+ * so focus in one composer never keeps a sibling composer's overlays alive.
+ */
+export function useComposerFocusOwnership(
+  containerRef: React.RefObject<HTMLElement | null>,
+): boolean {
+  const [ownsFocus, setOwnsFocus] = React.useState(false);
+
+  React.useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    setOwnsFocus(container.contains(document.activeElement));
+    const handleFocusIn = () => setOwnsFocus(true);
+    const handleFocusOut = (event: FocusEvent) => {
+      setOwnsFocus(
+        event.relatedTarget instanceof Node &&
+          container.contains(event.relatedTarget),
+      );
+    };
+    container.addEventListener("focusin", handleFocusIn);
+    container.addEventListener("focusout", handleFocusOut);
+    return () => {
+      container.removeEventListener("focusin", handleFocusIn);
+      container.removeEventListener("focusout", handleFocusOut);
+    };
+  }, [containerRef]);
+
+  return ownsFocus;
+}
diff --git a/desktop/src/features/messages/lib/useEmojiAutocomplete.ts b/desktop/src/features/messages/lib/useEmojiAutocomplete.ts
index 57e458bc911..21a0a102350 100644
--- a/desktop/src/features/messages/lib/useEmojiAutocomplete.ts
+++ b/desktop/src/features/messages/lib/useEmojiAutocomplete.ts
@@ -238,8 +238,11 @@ export function useEmojiAutocomplete(customEmoji: CustomEmoji[] = []) {
         return { handled: true };
       }
 
+      // Forward Tab selects; Shift+Tab deliberately does not. The reverse
+      // move stays the browser's, so this overlay can't swallow a keyboard
+      // user's way back out (see useMentions for the same split).
       if (
-        event.key === "Tab" ||
+        (event.key === "Tab" && !event.shiftKey) ||
         (event.key === "Enter" &&
           !event.ctrlKey &&
           !event.metaKey &&
diff --git a/desktop/src/features/messages/lib/useMentions.ts b/desktop/src/features/messages/lib/useMentions.ts
index de6e6da6c8f..f846b545d6c 100644
--- a/desktop/src/features/messages/lib/useMentions.ts
+++ b/desktop/src/features/messages/lib/useMentions.ts
@@ -749,9 +749,13 @@ export function useMentions(
         );
         return { handled: true };
       }
+      // Shift+Tab is deliberately not a select: it is the keyboard route out
+      // of the editor — into this overlay's Options controls where the
+      // composer offers them, otherwise the browser's own backward focus
+      // move — so those controls stay reachable.
       if (
         exactMentionSpace ||
-        event.key === "Tab" ||
+        (event.key === "Tab" && !event.shiftKey) ||
         (event.key === "Enter" &&
           !event.ctrlKey &&
           !event.metaKey &&
diff --git a/desktop/src/features/messages/lib/useRichTextEditor.ts b/desktop/src/features/messages/lib/useRichTextEditor.ts
index e53dbdaf6e7..2f00531820d 100644
--- a/desktop/src/features/messages/lib/useRichTextEditor.ts
+++ b/desktop/src/features/messages/lib/useRichTextEditor.ts
@@ -165,7 +165,6 @@ export function useRichTextEditor({
   onLinkShortcut,
 }: RichTextEditorOptions) {
   const addressedAgentMentionNamesRef = React.useRef<readonly string[]>([]);
-  const [isFocused, setIsFocused] = React.useState(false);
   const onUpdateRef = React.useRef(onUpdate);
   onUpdateRef.current = onUpdate;
   const onSubmitRef = React.useRef(onSubmit);
@@ -597,8 +596,6 @@ export function useRichTextEditor({
           buildPreviewUpdate(ed.state.doc, ed.state.selection.anchor),
         );
       },
-      onFocus: () => setIsFocused(true),
-      onBlur: () => setIsFocused(false),
     },
     [],
   );
@@ -935,7 +932,6 @@ export function useRichTextEditor({
 
   return {
     editor,
-    isFocused,
     getMarkdown,
     isEmpty,
     clearContent,
diff --git a/desktop/src/features/messages/ui/ChannelAutocomplete.tsx b/desktop/src/features/messages/ui/ChannelAutocomplete.tsx
index bf34e9f252c..5c759a8a693 100644
--- a/desktop/src/features/messages/ui/ChannelAutocomplete.tsx
+++ b/desktop/src/features/messages/ui/ChannelAutocomplete.tsx
@@ -13,10 +13,10 @@ type ChannelAutocompleteProps = {
   suggestions: ChannelSuggestion[];
   selectedIndex: number;
   /**
-   * Whether the owning composer's editor holds focus. Unfocused composers
+   * Whether the owning composer owns document focus. Composers that don't
    * must not render suggestions — see MentionAutocomplete for the rationale.
    */
-  isEditorFocused: boolean;
+  composerOwnsFocus: boolean;
   onSelect: (suggestion: ChannelSuggestion) => void;
   position?: "above" | "below";
 };
@@ -24,7 +24,7 @@ type ChannelAutocompleteProps = {
 export const ChannelAutocomplete = React.memo(function ChannelAutocomplete({
   suggestions,
   selectedIndex,
-  isEditorFocused,
+  composerOwnsFocus,
   onSelect,
   position = "above",
 }: ChannelAutocompleteProps) {
@@ -37,7 +37,7 @@ export const ChannelAutocomplete = React.memo(function ChannelAutocomplete({
     activeItem?.scrollIntoView({ block: "nearest" });
   }, [selectedIndex]);
 
-  if (!isEditorFocused || suggestions.length === 0) {
+  if (!composerOwnsFocus || suggestions.length === 0) {
     return null;
   }
 
diff --git a/desktop/src/features/messages/ui/EmojiAutocomplete.tsx b/desktop/src/features/messages/ui/EmojiAutocomplete.tsx
index 20909381f5f..9807c2602a9 100644
--- a/desktop/src/features/messages/ui/EmojiAutocomplete.tsx
+++ b/desktop/src/features/messages/ui/EmojiAutocomplete.tsx
@@ -16,10 +16,10 @@ type EmojiAutocompleteProps = {
   suggestions: EmojiSuggestion[];
   selectedIndex: number;
   /**
-   * Whether the owning composer's editor holds focus. Unfocused composers
+   * Whether the owning composer owns document focus. Composers that don't
    * must not render suggestions — see MentionAutocomplete for the rationale.
    */
-  isEditorFocused: boolean;
+  composerOwnsFocus: boolean;
   onSelect: (suggestion: EmojiSuggestion) => void;
   position?: "above" | "below";
 };
@@ -27,7 +27,7 @@ type EmojiAutocompleteProps = {
 export const EmojiAutocomplete = React.memo(function EmojiAutocomplete({
   suggestions,
   selectedIndex,
-  isEditorFocused,
+  composerOwnsFocus,
   onSelect,
   position = "above",
 }: EmojiAutocompleteProps) {
@@ -46,7 +46,7 @@ export const EmojiAutocomplete = React.memo(function EmojiAutocomplete({
     [],
   );
 
-  if (!isEditorFocused || suggestions.length === 0) {
+  if (!composerOwnsFocus || suggestions.length === 0) {
     return null;
   }
 
diff --git a/desktop/src/features/messages/ui/MentionAutocomplete.test.mjs b/desktop/src/features/messages/ui/MentionAutocomplete.test.mjs
index 53478946732..ac0cc0ba4cb 100644
--- a/desktop/src/features/messages/ui/MentionAutocomplete.test.mjs
+++ b/desktop/src/features/messages/ui/MentionAutocomplete.test.mjs
@@ -50,7 +50,7 @@ test("agent rows offer automatic mention controls", async () => {
   const props = {
     suggestions: [suggestion],
     selectedIndex: 0,
-    isEditorFocused: true,
+    composerOwnsFocus: true,
     onSelect: (value) => selected.push(value),
     onToggleAlwaysAddressAgent: (value) => toggled.push(value),
     lockedAgentPubkeys: new Set(),
@@ -120,7 +120,7 @@ test("options expand in place without replacing the people list", async () => {
     React.createElement(MentionAutocomplete, {
       suggestions: [suggestion],
       selectedIndex: 0,
-      isEditorFocused: true,
+      composerOwnsFocus: true,
       onSelect: () => {},
       keepMentionedAgentsPinned: true,
       onKeepMentionedAgentsPinnedChange: (value) => changes.push(value),
@@ -152,7 +152,7 @@ test("options expand in place without replacing the people list", async () => {
     React.createElement(MentionAutocomplete, {
       suggestions: [],
       selectedIndex: 0,
-      isEditorFocused: true,
+      composerOwnsFocus: true,
       onSelect: () => {},
       keepMentionedAgentsPinned: false,
       onKeepMentionedAgentsPinnedChange: (value) => changes.push(value),
@@ -164,7 +164,7 @@ test("options expand in place without replacing the people list", async () => {
     React.createElement(MentionAutocomplete, {
       suggestions: [suggestion],
       selectedIndex: 0,
-      isEditorFocused: true,
+      composerOwnsFocus: true,
       onSelect: () => {},
       keepMentionedAgentsPinned: false,
       onKeepMentionedAgentsPinnedChange: (value) => changes.push(value),
@@ -193,6 +193,7 @@ test("automatic selection loads the setting once, then updates it in place", asy
   const props = {
     suggestions: [suggestion],
     selectedIndex: 0,
+    composerOwnsFocus: true,
     onSelect: () => {},
     keepMentionedAgentsPinned: false,
     onKeepMentionedAgentsPinnedChange: () => {},
@@ -256,7 +257,7 @@ test("clicking outside dismisses the tray without intercepting its trigger", asy
         React.createElement(MentionAutocomplete, {
           suggestions: [suggestion],
           selectedIndex: 0,
-          isEditorFocused: true,
+          composerOwnsFocus: true,
           onDismiss: () => {
             dismissCount += 1;
           },
@@ -316,7 +317,7 @@ test("collision npubs sit inline with agent metadata", async () => {
     React.createElement(MentionAutocomplete, {
       suggestions,
       selectedIndex: 0,
-      isEditorFocused: true,
+      composerOwnsFocus: true,
       onSelect: () => {},
     }),
   );
@@ -334,55 +335,126 @@ test("collision npubs sit inline with agent metadata", async () => {
   }
 });
 
-test("does not intercept Tab from the editor", async () => {
+test("focusMentionOptionsTrigger hands focus to the Options trigger", async () => {
   const React = await import("react");
-  const { fireEvent, render } = await import("@testing-library/react");
-  const { MentionAutocomplete } = await import("./MentionAutocomplete.tsx");
-  const { TooltipProvider } = await import("@/shared/ui/tooltip");
-  const suggestions = [
-    {
-      pubkey: "agent-a",
-      displayName: "Agent Ada",
-      isAgent: true,
-    },
-    {
-      pubkey: "agent-b",
-      displayName: "Agent Bea",
-      isAgent: true,
-    },
-  ];
+  const { render } = await import("@testing-library/react");
+  const { MentionAutocomplete, focusMentionOptionsTrigger } = await import(
+    "./MentionAutocomplete.tsx"
+  );
+  const suggestion = {
+    pubkey: "agent-pubkey",
+    displayName: "Agent Ada",
+    isAgent: true,
+  };
   const view = render(
     React.createElement(
-      TooltipProvider,
-      null,
-      React.createElement(
-        "form",
-        null,
-        React.createElement(
-          "div",
-          { "data-testid": "message-input-scroll" },
-          React.createElement("input", { "aria-label": "Message" }),
-        ),
-        React.createElement(MentionAutocomplete, {
-          suggestions,
-          selectedIndex: 1,
-          isEditorFocused: true,
-          onSelect: () => {},
-          onToggleAlwaysAddressAgent: () => {},
-        }),
-      ),
+      "form",
+      { "data-testid": "composer-form" },
+      React.createElement("input", { "aria-label": "Message" }),
+      React.createElement(MentionAutocomplete, {
+        suggestions: [suggestion],
+        selectedIndex: 0,
+        composerOwnsFocus: true,
+        onSelect: () => {},
+        keepMentionedAgentsPinned: true,
+        onKeepMentionedAgentsPinnedChange: () => {},
+      }),
     ),
   );
 
+  const form = view.getByTestId("composer-form");
   const input = view.getByRole("textbox", { name: "Message" });
   input.focus();
-  const wasNotCancelled = fireEvent.keyDown(input, { key: "Tab" });
 
-  assert.equal(wasNotCancelled, true);
+  assert.equal(focusMentionOptionsTrigger(form), true);
+  assert.equal(
+    document.activeElement,
+    view.getByTestId("mention-options-trigger"),
+  );
+});
+
+test("focusMentionOptionsTrigger declines when no Options surface renders", async () => {
+  const React = await import("react");
+  const { render } = await import("@testing-library/react");
+  const { MentionAutocomplete, focusMentionOptionsTrigger } = await import(
+    "./MentionAutocomplete.tsx"
+  );
+  const suggestion = {
+    pubkey: "agent-pubkey",
+    displayName: "Agent Ada",
+    isAgent: true,
+  };
+  const view = render(
+    React.createElement(
+      "form",
+      { "data-testid": "composer-form" },
+      React.createElement("input", { "aria-label": "Message" }),
+      // No onKeepMentionedAgentsPinnedChange: composers without audience
+      // controls render no Options surface, so the key event must fall
+      // through to its default backward focus move instead of stranding
+      // focus.
+      React.createElement(MentionAutocomplete, {
+        suggestions: [suggestion],
+        selectedIndex: 0,
+        composerOwnsFocus: true,
+        onSelect: () => {},
+      }),
+    ),
+  );
+
+  const form = view.getByTestId("composer-form");
+  const input = view.getByRole("textbox", { name: "Message" });
+  input.focus();
+
+  assert.equal(focusMentionOptionsTrigger(form), false);
   assert.equal(document.activeElement, input);
+  assert.equal(focusMentionOptionsTrigger(null), false);
+});
+
+test("Escape inside the overlay returns focus to the editor and dismisses", async () => {
+  const React = await import("react");
+  const { fireEvent, render } = await import("@testing-library/react");
+  const { MentionAutocomplete, focusMentionOptionsTrigger } = await import(
+    "./MentionAutocomplete.tsx"
+  );
+  const dismissals = [];
+  const view = render(
+    React.createElement(
+      "form",
+      { "data-testid": "composer-form" },
+      React.createElement("input", {
+        "aria-label": "Message",
+        "data-testid": "message-input",
+      }),
+      React.createElement(MentionAutocomplete, {
+        suggestions: [
+          {
+            pubkey: "agent-pubkey",
+            displayName: "Agent Ada",
+            isAgent: true,
+          },
+        ],
+        selectedIndex: 0,
+        composerOwnsFocus: true,
+        onDismiss: () => dismissals.push(true),
+        onSelect: () => {},
+        keepMentionedAgentsPinned: true,
+        onKeepMentionedAgentsPinnedChange: () => {},
+      }),
+    ),
+  );
+
+  const form = view.getByTestId("composer-form");
+  assert.equal(focusMentionOptionsTrigger(form), true);
+  const trigger = view.getByTestId("mention-options-trigger");
+  const wasNotCancelled = fireEvent.keyDown(trigger, { key: "Escape" });
+
+  assert.equal(wasNotCancelled, false);
+  assert.equal(document.activeElement, view.getByTestId("message-input"));
+  assert.deepEqual(dismissals, [true]);
 });
 
-test("renders nothing while the editor is unfocused", async () => {
+test("renders nothing while the composer does not own focus", async () => {
   const React = await import("react");
   const { render } = await import("@testing-library/react");
   const { MentionAutocomplete } = await import("./MentionAutocomplete.tsx");
@@ -395,7 +467,7 @@ test("renders nothing while the editor is unfocused", async () => {
       },
     ],
     selectedIndex: 0,
-    isEditorFocused: false,
+    composerOwnsFocus: false,
     onSelect: () => {},
   };
   const view = render(React.createElement(MentionAutocomplete, props));
@@ -405,7 +477,7 @@ test("renders nothing while the editor is unfocused", async () => {
   view.rerender(
     React.createElement(MentionAutocomplete, {
       ...props,
-      isEditorFocused: true,
+      composerOwnsFocus: true,
     }),
   );
   assert.ok(view.getByTestId("mention-autocomplete-layer"));
@@ -426,7 +498,7 @@ test("container presses do not blur the editor out from under the overlay", asyn
     React.createElement(MentionAutocomplete, {
       suggestions: [mention],
       selectedIndex: 0,
-      isEditorFocused: true,
+      composerOwnsFocus: true,
       onSelect: (value) => selected.push(value),
       keepMentionedAgentsPinned: true,
       onKeepMentionedAgentsPinnedChange: (value) => pinnedChanges.push(value),
diff --git a/desktop/src/features/messages/ui/MentionAutocomplete.tsx b/desktop/src/features/messages/ui/MentionAutocomplete.tsx
index 7d913b3084d..0b873a4074c 100644
--- a/desktop/src/features/messages/ui/MentionAutocomplete.tsx
+++ b/desktop/src/features/messages/ui/MentionAutocomplete.tsx
@@ -38,12 +38,14 @@ type MentionAutocompleteProps = {
   suggestions: MentionSuggestion[];
   selectedIndex: number;
   /**
-   * Whether the owning composer's editor holds focus. The focus gate lives
-   * here rather than in each composer so a background composer replaying a
-   * stale update (e.g. a shared mid-send disabled toggle) can't resurrect
-   * its suggestion overlay.
+   * Whether the owning composer owns document focus — its editor or this
+   * overlay's own controls (see useComposerFocusOwnership). The focus gate
+   * lives here rather than in each composer so a background composer
+   * replaying a stale update (e.g. a shared mid-send disabled toggle) can't
+   * resurrect its suggestion overlay, while keyboard focus moving into the
+   * Options controls keeps the overlay mounted.
    */
-  isEditorFocused: boolean;
+  composerOwnsFocus: boolean;
   onFetchMore?: () => void;
   onSelect: (suggestion: MentionSuggestion) => void;
   lockedAgentPubkeys?: ReadonlySet<string>;
@@ -63,10 +65,27 @@ export function showMentionAgentProvenanceMarker(
   return hasNameCollision && suggestion.agentProvenance === "managed-elsewhere";
 }
 
+/**
+ * Move keyboard focus to the mention overlay's Options trigger inside
+ * `container` (the composer form). Returns false when the trigger isn't
+ * rendered — overlay closed, or a composer without audience controls — so
+ * the caller can leave the key event to its default behavior.
+ */
+export function focusMentionOptionsTrigger(
+  container: HTMLElement | null,
+): boolean {
+  const trigger = container?.querySelector<HTMLElement>(
+    "[data-mention-options-trigger]",
+  );
+  if (!trigger) return false;
+  trigger.focus();
+  return true;
+}
+
 export const MentionAutocomplete = React.memo(function MentionAutocomplete({
   suggestions,
   selectedIndex,
-  isEditorFocused,
+  composerOwnsFocus,
   onFetchMore,
   onSelect,
   lockedAgentPubkeys,
@@ -153,7 +172,27 @@ export const MentionAutocomplete = React.memo(function MentionAutocomplete({
     }
   }, [onFetchMore]);
 
-  if (!isEditorFocused || suggestions.length === 0) {
+  // Escape from inside the overlay is the keyboard counterpart of pressing
+  // outside it: hand focus back to the editor the overlay belongs to, then
+  // dismiss. Focusing first keeps the composer's focus ownership unbroken, so
+  // the overlay never unmounts with focus stranded on the document. Escape in
+  // the editor itself never reaches here — that path is the composer's own
+  // key handler.
+  const handleOverlayKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if (event.key !== "Escape") return;
+      event.preventDefault();
+      event.stopPropagation();
+      rootRef.current
+        ?.closest("form")
+        ?.querySelector<HTMLElement>('[data-testid="message-input"]')
+        ?.focus();
+      onDismiss?.();
+    },
+    [onDismiss],
+  );
+
+  if (!composerOwnsFocus || suggestions.length === 0) {
     return null;
   }
 
@@ -167,12 +206,14 @@ export const MentionAutocomplete = React.memo(function MentionAutocomplete({
   }
 
   return (
+    // biome-ignore lint/a11y/noStaticElementInteractions: the overlay's own controls are the interactive elements; this listener only gives them the standard Escape-to-dismiss exit.
     <div
       className={cn(
         "absolute left-0 right-0 z-50 px-3 sm:px-4",
         position === "below" ? "top-full mt-1" : "bottom-full mb-1",
       )}
       data-testid="mention-autocomplete-layer"
+      onKeyDown={handleOverlayKeyDown}
       ref={rootRef}
     >
       <div className="w-full max-w-2xl">
@@ -246,6 +287,7 @@ export const MentionAutocomplete = React.memo(function MentionAutocomplete({
                 aria-controls={optionsId}
                 aria-expanded={optionsOpen}
                 className="flex h-8 w-full items-center justify-between gap-1 px-2.5 text-sm font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-popover-foreground"
+                data-mention-options-trigger
                 data-testid="mention-options-trigger"
                 onClick={() => setOptionsOpen((open) => !open)}
                 onMouseDown={(event) => event.preventDefault()}
diff --git a/desktop/src/features/messages/ui/MessageComposer.tsx b/desktop/src/features/messages/ui/MessageComposer.tsx
index d66968c8b69..dc33334f06b 100644
--- a/desktop/src/features/messages/ui/MessageComposer.tsx
+++ b/desktop/src/features/messages/ui/MessageComposer.tsx
@@ -25,6 +25,7 @@ import {
   takeQueuedAttachmentsForDraft,
   useBackgroundMediaUpload,
 } from "@/features/messages/lib/backgroundMediaUploadStore";
+import { useComposerFocusOwnership } from "@/features/messages/lib/useComposerFocusOwnership";
 import { isMentionCodeContext } from "@/features/messages/lib/mentionCodeContext";
 import { useMentions } from "@/features/messages/lib/useMentions";
 import {
@@ -48,6 +49,7 @@ import { useTypingBroadcast } from "@/features/messages/useTypingBroadcast";
 import { cn } from "@/shared/lib/cn";
 import { ComposerReplyEditBanner } from "./ComposerReplyEditBanner";
 import { ComposerAttachments, DropZoneOverlay } from "./ComposerAttachments";
+import { focusMentionOptionsTrigger } from "./MentionAutocomplete";
 import { MessageComposerAutocompletes } from "./MessageComposerAutocompletes";
 import { ComposerDockToolbar } from "./ComposerDockToolbar";
 import { ComposerUploadProgressPill } from "./ComposerUploadProgressPill";
@@ -246,6 +248,8 @@ function MessageComposerImpl({
     emojiAutocomplete.isEmojiAutocompleteOpen;
   const submitMessageRef = React.useRef<() => void>(() => {});
   const composerScrollRef = React.useRef<HTMLDivElement>(null);
+  const formRef = React.useRef<HTMLFormElement>(null);
+  const composerOwnsFocus = useComposerFocusOwnership(formRef);
   const onEditLinkRef = React.useRef<
     ((info: LinkSelectionInfo) => void) | null
   >(null);
@@ -720,6 +724,19 @@ function MessageComposerImpl({
         }
         return;
       }
+      // Shift+Tab is the keyboard route from the editor into the mention
+      // overlay's Options controls — forward Tab is consumed below to select
+      // the highlighted suggestion. Falls through (e.g. a composer with no
+      // audience controls) to the browser's native backward focus move.
+      if (
+        event.key === "Tab" &&
+        event.shiftKey &&
+        mentions.isMentionOpen &&
+        focusMentionOptionsTrigger(formRef.current)
+      ) {
+        event.preventDefault();
+        return;
+      }
       const { handled, suggestion } = mentions.handleMentionKeyDown(event, {
         isCodeContext: () => isMentionCodeContext(richText.editor),
       });
@@ -754,6 +771,7 @@ function MessageComposerImpl({
       applyEmojiInsert,
       channelLinks.handleChannelKeyDown,
       applyChannelInsert,
+      mentions.isMentionOpen,
       mentions.handleMentionKeyDown,
       richText.editor,
       selectMentionSuggestion,
@@ -836,6 +854,7 @@ function MessageComposerImpl({
             onSubmit={(event) => {
               handleSubmit(event);
             }}
+            ref={formRef}
           >
             {ownsDropZone && media.isDragOver && <DropZoneOverlay />}
             <MessageComposerAutocompletes
@@ -843,8 +862,8 @@ function MessageComposerImpl({
                 audienceScope && editTarget == null,
               )}
               channelLinks={channelLinks}
+              composerOwnsFocus={composerOwnsFocus}
               emojiAutocomplete={emojiAutocomplete}
-              isEditorFocused={richText.isFocused}
               keepMentionedAgentsPinned={keepMentionedAgentsPinned}
               lockedAgentPubkeys={lockedAgentPubkeys}
               mentions={mentions}
diff --git a/desktop/src/features/messages/ui/MessageComposerAutocompletes.tsx b/desktop/src/features/messages/ui/MessageComposerAutocompletes.tsx
index 08601eb59df..a4e82121091 100644
--- a/desktop/src/features/messages/ui/MessageComposerAutocompletes.tsx
+++ b/desktop/src/features/messages/ui/MessageComposerAutocompletes.tsx
@@ -22,8 +22,8 @@ type MessageComposerAutocompletesProps = {
    */
   audienceControlsEnabled: boolean;
   channelLinks: UseChannelLinksResult;
+  composerOwnsFocus: boolean;
   emojiAutocomplete: UseEmojiAutocompleteResult;
-  isEditorFocused: boolean;
   keepMentionedAgentsPinned: boolean;
   lockedAgentPubkeys: ReadonlySet<string>;
   mentions: UseMentionsResult;
@@ -41,14 +41,16 @@ type MessageComposerAutocompletesProps = {
 
 /**
  * The message composer's three suggestion overlays. Each one gates its own
- * rendering on `isEditorFocused`, so a background composer replaying a stale
- * update cannot resurrect a suggestion menu over the focused composer.
+ * rendering on `composerOwnsFocus`, so a background composer replaying a
+ * stale update cannot resurrect a suggestion menu over the focused composer,
+ * while keyboard focus moving into an overlay's own controls keeps that
+ * overlay mounted.
  */
 export function MessageComposerAutocompletes({
   audienceControlsEnabled,
   channelLinks,
+  composerOwnsFocus,
   emojiAutocomplete,
-  isEditorFocused,
   keepMentionedAgentsPinned,
   lockedAgentPubkeys,
   mentions,
@@ -62,7 +64,7 @@ export function MessageComposerAutocompletes({
   return (
     <>
       <EmojiAutocomplete
-        isEditorFocused={isEditorFocused}
+        composerOwnsFocus={composerOwnsFocus}
         onSelect={onEmojiSelect}
         selectedIndex={emojiAutocomplete.emojiSelectedIndex}
         suggestions={
@@ -72,7 +74,7 @@ export function MessageComposerAutocompletes({
         }
       />
       <ChannelAutocomplete
-        isEditorFocused={isEditorFocused}
+        composerOwnsFocus={composerOwnsFocus}
         onSelect={onChannelSelect}
         selectedIndex={channelLinks.channelSelectedIndex}
         suggestions={
@@ -80,7 +82,7 @@ export function MessageComposerAutocompletes({
         }
       />
       <MentionAutocomplete
-        isEditorFocused={isEditorFocused}
+        composerOwnsFocus={composerOwnsFocus}
         keepMentionedAgentsPinned={keepMentionedAgentsPinned}
         lockedAgentPubkeys={lockedAgentPubkeys}
         openOptionsRequest={openOptionsRequest}
diff --git a/desktop/tests/e2e/persistent-agent-audience.spec.ts b/desktop/tests/e2e/persistent-agent-audience.spec.ts
index d22d192598b..6cc2f22a883 100644
--- a/desktop/tests/e2e/persistent-agent-audience.spec.ts
+++ b/desktop/tests/e2e/persistent-agent-audience.spec.ts
@@ -793,6 +793,85 @@ test("pressing a mention overlay's own container keeps it open", async ({
   await expect(list).toBeVisible();
 });
 
+test("the mention Options controls are reachable and operable by keyboard", async ({
+  page,
+}) => {
+  await keepMentionedAgentsPinned(page);
+  await installAudienceFixtures(page);
+  await openThread(page);
+
+  const mainComposer = channelComposer(page);
+  const mainInput = mainComposer.getByTestId("message-input");
+  await mainInput.click();
+  await mainInput.fill("@Mor");
+  const list = mainComposer.getByTestId("mention-autocomplete");
+  await expect(list).toBeVisible();
+  await expect(mainInput).toBeFocused();
+
+  // Trip a flag if the overlay ever unmounts from here on — "operable while
+  // the surface stays mounted" has to hold through every focus handoff below,
+  // not just at the polled assertion boundaries.
+  await mainComposer.evaluate((element) => {
+    element.dataset.mentionMenuUnmounted = "false";
+    new MutationObserver(() => {
+      if (!element.querySelector('[data-testid="mention-autocomplete"]')) {
+        element.dataset.mentionMenuUnmounted = "true";
+      }
+    }).observe(element, { childList: true, subtree: true });
+  });
+
+  // Forward Tab still selects the highlighted suggestion, so Shift+Tab is the
+  // route into the overlay. It only reaches the Options controls if the focus
+  // gate treats them as composer-owned focus rather than unmounting on the
+  // editor's blur.
+  await mainInput.press("Shift+Tab");
+  const optionsTrigger = mainComposer.getByTestId("mention-options-trigger");
+  await expect(optionsTrigger).toBeFocused();
+
+  await page.keyboard.press("Enter");
+  const preference = mainComposer.getByTestId(
+    "mention-keep-agents-pinned-toggle",
+  );
+  await expect(preference).toBeVisible();
+  await expect(preference).toHaveAttribute("data-state", "checked");
+
+  // The switch sits before its trigger in the expanded surface's tab order.
+  await page.keyboard.press("Shift+Tab");
+  await expect(preference).toBeFocused();
+  await page.keyboard.press("Space");
+  await expect(preference).toHaveAttribute("data-state", "unchecked");
+
+  await expect(list).toBeVisible();
+  expect(await mainComposer.getAttribute("data-mention-menu-unmounted")).toBe(
+    "false",
+  );
+
+  // Escape is the way back out: focus returns to the editor and the menu
+  // closes, rather than stranding focus on a control that just unmounted.
+  await page.keyboard.press("Escape");
+  await expect(mainInput).toBeFocused();
+  await expect(list).toHaveCount(0);
+
+  // Forward Tab is unchanged by the Shift+Tab route.
+  await mainInput.fill("@Morg");
+  await expect(list).toBeVisible();
+  await mainInput.press("Tab");
+  await expect(mainInput).toHaveText("@Morgarita ");
+  await expect(list).toHaveCount(0);
+
+  // Ownership is still per-composer: focus moving to a sibling composer hides
+  // this composer's menu, which is what stops a background composer from
+  // resurrecting a stale one. Programmatic focus, not a click — a pointerdown
+  // would dismiss the menu through its outside-press handler and mask the gate
+  // under test.
+  await mainInput.fill("@Mor");
+  await expect(list).toBeVisible();
+  const threadInput = threadComposer(page).getByTestId("message-input");
+  await threadInput.focus();
+  await expect(threadInput).toBeFocused();
+  await expect(list).toHaveCount(0);
+});
+
 test("a failed always-mentioned send shakes the composer avatar without replaying its selection animation", async ({
   page,
 }) => {