From 8f1d9003b329dd45ff9898a098405f3aae887c03 Mon Sep 17 00:00:00 2001
From: Raing5Days <Raing5Days@users.noreply.github.com>
Date: Fri, 30 Oct 2026 20:41:15 +0800
Subject: [PATCH 1/3] fix(search): format diagnostic panel as a popover to
 prevent footer overlap

When search source diagnostics are expanded in the footer, the content previously
overflowed and vertically centered over the healthy results due to footer flex sizing
and lack of an elevated background.

Render the diagnostics as an absolute popover panel positioned above the footer summary,
styled with raised background, subtle border and overlay shadow. Add escape and
click-outside handling to close the panel cleanly.

Fixes #3628
---
 .../GlobalSearchContent.test.tsx              |  39 +++++++
 .../app/global-search/GlobalSearchRoot.scss   | 104 ++++++++++++++++--
 .../app/global-search/GlobalSearchRoot.tsx    |  91 ++++++++++-----
 3 files changed, 202 insertions(+), 32 deletions(-)

diff --git a/src/web-ui/src/app/global-search/GlobalSearchContent.test.tsx b/src/web-ui/src/app/global-search/GlobalSearchContent.test.tsx
index bc42d5320a..cd7937aa62 100644
--- a/src/web-ui/src/app/global-search/GlobalSearchContent.test.tsx
+++ b/src/web-ui/src/app/global-search/GlobalSearchContent.test.tsx
@@ -104,6 +104,45 @@ describe('GlobalSearchContent accessibility', () => {
     expect(details.querySelector('button')?.disabled).toBe(true);
   });
 
+  it('toggles diagnostic panel and closes it on Escape or click outside', async () => {
+    const failure = { ...snapshot, diagnostics: [{
+      providerId: 'files', code: 'workspace_unavailable', message: 'Connection timed out',
+      workspaceName: 'Remote project', workspacePath: '/srv/project', hostLabel: 'build-host',
+    }] };
+    fixtures.search.mockImplementationOnce((_providers, _request, _signal, onUpdate) => onUpdate(failure));
+    act(() => root.render(<GlobalSearchContent initialQuery="needle" />));
+    await act(async () => { await vi.runOnlyPendingTimersAsync(); });
+
+    const details = container.querySelector('details')!;
+    const summary = details.querySelector('summary')!;
+    expect(details.hasAttribute('open')).toBe(false);
+    expect(details.querySelector('.global-search__diagnostics-panel')).not.toBeNull();
+
+    // Toggle open
+    act(() => {
+      details.open = true;
+      details.dispatchEvent(new Event('toggle'));
+    });
+    expect(details.open).toBe(true);
+
+    // Escape closes diagnostics panel
+    act(() => {
+      container.querySelector('.global-search')!.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    });
+    expect(details.open).toBe(false);
+
+    // Reopen and click outside closes diagnostics panel
+    act(() => {
+      details.open = true;
+      details.dispatchEvent(new Event('toggle'));
+    });
+    expect(details.open).toBe(true);
+    act(() => {
+      document.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
+    });
+    expect(details.open).toBe(false);
+  });
+
   it('discards old results and ignores late completions after a device switch', async () => {
     act(() => root.render(<GlobalSearchContent />));
     await act(async () => { await vi.runOnlyPendingTimersAsync(); });
diff --git a/src/web-ui/src/app/global-search/GlobalSearchRoot.scss b/src/web-ui/src/app/global-search/GlobalSearchRoot.scss
index e448388e10..d9fd4eb21b 100644
--- a/src/web-ui/src/app/global-search/GlobalSearchRoot.scss
+++ b/src/web-ui/src/app/global-search/GlobalSearchRoot.scss
@@ -340,6 +340,8 @@ $chevron-box-slack: 5px;
   }
 
   &__footer {
+    position: relative;
+    z-index: 5;
     display: flex;
     flex: 0 0 40px;
     align-items: center;
@@ -890,17 +892,105 @@ $chevron-box-slack: 5px;
 }
 
 .global-search__diagnostics {
+  position: relative;
   min-width: 0;
-  flex: 1;
-  max-height: 200px;
-  overflow: auto;
-  summary { cursor: pointer; }
+  margin-right: auto;
+  color: var(--openbitfun-color-content-muted);
+
+  summary {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    cursor: pointer;
+    user-select: none;
+    color: var(--openbitfun-color-content-muted);
+    font-size: var(--openbitfun-type-meta-font-size);
+    border-radius: var(--openbitfun-radius-sm);
+    padding: 2px 6px;
+    margin-left: -6px;
+    list-style: none;
+    transition: background-color var(--openbitfun-motion-duration-fast, 150ms) ease,
+                color var(--openbitfun-motion-duration-fast, 150ms) ease;
+
+    &::-webkit-details-marker {
+      display: none;
+    }
+
+    &:hover {
+      background: var(--openbitfun-color-action-quiet-hover);
+      color: var(--openbitfun-color-content-primary);
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--openbitfun-color-accent-default);
+      outline-offset: 1px;
+    }
+  }
+
+  &[open] summary {
+    background: var(--openbitfun-color-action-quiet-hover);
+    color: var(--openbitfun-color-content-primary);
+  }
+}
+
+.global-search__diagnostics-icon {
+  flex: 0 0 auto;
+  color: var(--openbitfun-color-content-secondary);
 }
-.global-search__diagnostic-target { margin-block: 8px; }
+
+.global-search__diagnostics-panel {
+  position: absolute;
+  bottom: calc(100% + 8px);
+  left: 0;
+  z-index: 30;
+  box-sizing: border-box;
+  width: max-content;
+  min-width: 280px;
+  max-width: min(480px, calc(100vw - 36px));
+  max-height: 240px;
+  overflow-y: auto;
+  padding: 10px 14px;
+  background: var(--openbitfun-color-surface-raised);
+  border: 1px solid var(--openbitfun-color-border-subtle);
+  border-radius: var(--openbitfun-radius-md);
+  box-shadow: var(--openbitfun-shadow-overlay);
+  color: var(--openbitfun-color-content-primary);
+  font-size: var(--openbitfun-type-meta-font-size);
+}
+
+.global-search__diagnostic-target {
+  margin-block-end: 8px;
+  color: var(--openbitfun-color-content-muted);
+  font-size: var(--openbitfun-type-meta-font-size);
+}
+
 .global-search__diagnostic {
   padding-block: 8px;
   border-top: 1px solid var(--openbitfun-color-border-subtle);
   overflow-wrap: anywhere;
-  p { margin-block: 4px 8px; }
+
+  strong {
+    color: var(--openbitfun-color-content-primary);
+    font-weight: var(--openbitfun-type-label-selected-font-weight, 600);
+  }
+
+  p {
+    margin-block: 4px 8px;
+    color: var(--openbitfun-color-content-secondary);
+    line-height: var(--openbitfun-type-body-line-height, 1.4);
+  }
+}
+
+.global-search__diagnostic-header {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 8px;
+}
+
+.global-search__diagnostic-path {
+  color: var(--openbitfun-color-content-muted);
+  font-family: var(--openbitfun-font-family-mono, monospace);
+  font-size: var(--openbitfun-type-micro-font-size, 11px);
+  margin-block-start: 2px;
 }
-.global-search__diagnostic-path { color: var(--openbitfun-color-content-muted); }
diff --git a/src/web-ui/src/app/global-search/GlobalSearchRoot.tsx b/src/web-ui/src/app/global-search/GlobalSearchRoot.tsx
index 34723d4db9..ca32d2c0be 100644
--- a/src/web-ui/src/app/global-search/GlobalSearchRoot.tsx
+++ b/src/web-ui/src/app/global-search/GlobalSearchRoot.tsx
@@ -20,7 +20,7 @@ import { OverflowText,
   Dialog,
   DialogBody,
 } from '@openbitfun/ui';
-import { BarChart3, Blocks, CheckSquare2, FileText, Keyboard, MessageSquareText, MessagesSquare, Network, Users } from 'lucide-react';
+import { AlertCircle, BarChart3, Blocks, CheckSquare2, FileText, Keyboard, MessageSquareText, MessagesSquare, Network, Users } from 'lucide-react';
 import { useShortcut } from '@/infrastructure/hooks/useShortcut';
 import { useI18n } from '@/infrastructure/i18n';
 import { getActiveSurfaceScope, onSurfaceActivated } from '@/infrastructure/peer-device/deviceSurface';
@@ -183,6 +183,8 @@ export const GlobalSearchContent: React.FC<GlobalSearchContentProps> = ({
   const retryRef = useRef<{ context: string; providerId: string; previous: GlobalSearchSnapshot } | null>(null);
   const [activeId, setActiveId] = useState<string | null>(null);
   const [drilldownGroup, setDrilldownGroup] = useState<GlobalSearchDrilldownGroupId | null>(null);
+  const [diagnosticsOpen, setDiagnosticsOpen] = useState(false);
+  const diagnosticsRef = useRef<HTMLDetailsElement>(null);
   const inputRef = useRef<HTMLInputElement>(null);
   const inputCompositionActiveRef = useRef(false);
   const listRef = useRef<HTMLDivElement>(null);
@@ -376,13 +378,39 @@ export const GlobalSearchContent: React.FC<GlobalSearchContentProps> = ({
     focusSearchInput();
   }, [focusSearchInput]);
 
+  useEffect(() => {
+    if (snapshot.diagnostics.length === 0) {
+      setDiagnosticsOpen(false);
+    }
+  }, [snapshot.diagnostics.length]);
+
+  useEffect(() => {
+    if (!diagnosticsOpen) return;
+    const handlePointerDownOutside = (event: PointerEvent) => {
+      if (diagnosticsRef.current && !diagnosticsRef.current.contains(event.target as Node)) {
+        setDiagnosticsOpen(false);
+      }
+    };
+    document.addEventListener('pointerdown', handlePointerDownOutside);
+    return () => document.removeEventListener('pointerdown', handlePointerDownOutside);
+  }, [diagnosticsOpen]);
+
   const handleRootKeyDownCapture = useCallback((event: React.KeyboardEvent<HTMLDivElement>) => {
     if (isImeOwnedKeyboardEvent(event, inputCompositionActiveRef.current)) return;
-    if (event.key !== 'Escape' || !drilldownGroup) return;
-    event.preventDefault();
-    event.stopPropagation();
-    closeGroupDetails();
-  }, [closeGroupDetails, drilldownGroup]);
+    if (event.key === 'Escape') {
+      if (diagnosticsOpen) {
+        event.preventDefault();
+        event.stopPropagation();
+        setDiagnosticsOpen(false);
+        return;
+      }
+      if (drilldownGroup) {
+        event.preventDefault();
+        event.stopPropagation();
+        closeGroupDetails();
+      }
+    }
+  }, [closeGroupDetails, diagnosticsOpen, drilldownGroup]);
 
   const effectiveScope = parsedQuery.scope;
   const emptyLabel = effectiveScope === 'content' && parsedQuery.query.length < 2
@@ -666,26 +694,39 @@ export const GlobalSearchContent: React.FC<GlobalSearchContentProps> = ({
           || snapshot.diagnostics.length > 0) ? (
         <footer className="global-search__footer" data-openbitfun-component="global-search" data-openbitfun-part="footer">
           {snapshot.diagnostics.length > 0 ? (
-            <details className="global-search__diagnostics" data-testid={`${testIdPrefix}-partial-status`}>
-              <summary>{tCommon('nav.search.partialUnavailable')}</summary>
-              <div className="global-search__diagnostic-target">
-                {tCommon('nav.search.diagnosticTarget', { host: hostLabel })}
-              </div>
-              {snapshot.diagnostics.map((diagnostic, index) => (
-                <div className="global-search__diagnostic" key={`${diagnostic.providerId}:${diagnostic.code}:${index}`}>
-                  <strong>{providers.find(provider => provider.id === diagnostic.providerId)?.groups
-                    .map(group => tCommon(`nav.search.groups.${group}`)).join(' / ') ?? diagnostic.providerId}</strong>
-                  {diagnostic.workspaceName ? <div>{diagnostic.workspaceName} · {diagnostic.hostLabel ?? hostLabel}</div> : null}
-                  {diagnostic.workspacePath ? <div className="global-search__diagnostic-path">{diagnostic.workspacePath}</div> : null}
-                  <p>{diagnostic.message}</p>
-                  {diagnostic.retryable !== false ? (
-                    <Button size="sm" variant="outline" disabled={snapshot.isSearching}
-                      onClick={() => retryProvider(diagnostic.providerId)}>
-                      {tCommon('nav.search.retrySource')}
-                    </Button>
-                  ) : null}
+            <details
+              className="global-search__diagnostics"
+              data-testid={`${testIdPrefix}-partial-status`}
+              ref={diagnosticsRef}
+              open={diagnosticsOpen}
+              onToggle={(event) => setDiagnosticsOpen(event.currentTarget.open)}
+            >
+              <summary className="global-search__diagnostics-summary">
+                <AlertCircle size={13} aria-hidden="true" className="global-search__diagnostics-icon" />
+                <span>{tCommon('nav.search.partialUnavailable')}</span>
+              </summary>
+              <div className="global-search__diagnostics-panel">
+                <div className="global-search__diagnostic-target">
+                  {tCommon('nav.search.diagnosticTarget', { host: hostLabel })}
                 </div>
-              ))}
+                {snapshot.diagnostics.map((diagnostic, index) => (
+                  <div className="global-search__diagnostic" key={`${diagnostic.providerId}:${diagnostic.code}:${index}`}>
+                    <div className="global-search__diagnostic-header">
+                      <strong>{providers.find(provider => provider.id === diagnostic.providerId)?.groups
+                        .map(group => tCommon(`nav.search.groups.${group}`)).join(' / ') ?? diagnostic.providerId}</strong>
+                      {diagnostic.workspaceName ? <div>{diagnostic.workspaceName} · {diagnostic.hostLabel ?? hostLabel}</div> : null}
+                    </div>
+                    {diagnostic.workspacePath ? <div className="global-search__diagnostic-path">{diagnostic.workspacePath}</div> : null}
+                    <p>{diagnostic.message}</p>
+                    {diagnostic.retryable !== false ? (
+                      <Button size="sm" variant="outline" disabled={snapshot.isSearching}
+                        onClick={() => retryProvider(diagnostic.providerId)}>
+                        {tCommon('nav.search.retrySource')}
+                      </Button>
+                    ) : null}
+                  </div>
+                ))}
+              </div>
             </details>
           ) : null}
           <span className="global-search__footer-keys" aria-hidden="true">

From df974a5af2c98acd0334b4498f4860a174427b43 Mon Sep 17 00:00:00 2001
From: Raing5Days <Raing5Days@users.noreply.github.com>
Date: Fri, 30 Oct 2026 21:16:49 +0800
Subject: [PATCH 2/3] fix(search): drop uncontracted fallbacks from diagnostic
 panel tokens

The theme color audit contract rejects `var(--token, fallback)` usages whose
tokens are not registered with a fallback boundary contract. The new diagnostic
popover introduced five such fallbacks, failing `theme:color-audit:test`.

Use the canonical tokens directly. `--openbitfun-type-body-line-height` does
not exist in the design tokens, so pair the copy with
`--openbitfun-type-body-sm-line-height` instead.
---
 .../src/app/global-search/GlobalSearchRoot.scss      | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/web-ui/src/app/global-search/GlobalSearchRoot.scss b/src/web-ui/src/app/global-search/GlobalSearchRoot.scss
index d9fd4eb21b..5d6d4e7a81 100644
--- a/src/web-ui/src/app/global-search/GlobalSearchRoot.scss
+++ b/src/web-ui/src/app/global-search/GlobalSearchRoot.scss
@@ -909,8 +909,8 @@ $chevron-box-slack: 5px;
     padding: 2px 6px;
     margin-left: -6px;
     list-style: none;
-    transition: background-color var(--openbitfun-motion-duration-fast, 150ms) ease,
-                color var(--openbitfun-motion-duration-fast, 150ms) ease;
+    transition: background-color var(--openbitfun-motion-duration-fast) ease,
+                color var(--openbitfun-motion-duration-fast) ease;
 
     &::-webkit-details-marker {
       display: none;
@@ -971,13 +971,13 @@ $chevron-box-slack: 5px;
 
   strong {
     color: var(--openbitfun-color-content-primary);
-    font-weight: var(--openbitfun-type-label-selected-font-weight, 600);
+    font-weight: var(--openbitfun-type-label-selected-font-weight);
   }
 
   p {
     margin-block: 4px 8px;
     color: var(--openbitfun-color-content-secondary);
-    line-height: var(--openbitfun-type-body-line-height, 1.4);
+    line-height: var(--openbitfun-type-body-sm-line-height);
   }
 }
 
@@ -990,7 +990,7 @@ $chevron-box-slack: 5px;
 
 .global-search__diagnostic-path {
   color: var(--openbitfun-color-content-muted);
-  font-family: var(--openbitfun-font-family-mono, monospace);
-  font-size: var(--openbitfun-type-micro-font-size, 11px);
+  font-family: var(--openbitfun-font-family-mono);
+  font-size: var(--openbitfun-type-micro-font-size);
   margin-block-start: 2px;
 }

From 6513e65aac1e536cd539df84addfa3f818515aec Mon Sep 17 00:00:00 2001
From: GCWing <gcwing@foxmail.com>
Date: Sat, 31 Oct 2026 09:53:16 +0800
Subject: [PATCH 3/3] fix(search): coordinate diagnostics overlay and modal
 dismissal

---
 src/web-ui/AGENTS.md                          |   9 +
 .../GlobalSearchContent.test.tsx              | 200 ++++++++++++++----
 .../app/global-search/GlobalSearchRoot.scss   |  53 ++---
 .../app/global-search/GlobalSearchRoot.tsx    | 148 ++++++++-----
 4 files changed, 269 insertions(+), 141 deletions(-)

diff --git a/src/web-ui/AGENTS.md b/src/web-ui/AGENTS.md
index 19e61f7c1d..5127a7addf 100644
--- a/src/web-ui/AGENTS.md
+++ b/src/web-ui/AGENTS.md
@@ -289,6 +289,15 @@ establish visual or remote transport behavior):
 pnpm --dir src/web-ui run test:run src/shared/ui/OverlayStack.test.tsx src/shared/ui/OverlayOwnership.contract.test.ts src/shared/ui/Dialog.test.tsx src/shared/ui/MenuPopover.test.tsx src/infrastructure/appearance/runtime/AppearanceOverlayHost.test.ts src/shared/notification-system/components/NotificationContainer.test.tsx src/shared/context-menu-system/components/ui/ContextMenu.test.tsx
 ```
 
+For global-search source diagnostics, retry, portal ownership and layered Escape dismissal:
+
+```bash
+pnpm --dir src/web-ui run test:run src/app/global-search src/shared/ui/OverlayStack.test.tsx src/shared/ui/Dialog.test.tsx
+```
+
+These DOM fixtures include simulated Peer surface switches and viewport geometry;
+they do not establish native rendering or live remote behavior.
+
 For the compact model picker, smart-mode items, session/default selection,
 and host capability negotiation:
 
diff --git a/src/web-ui/src/app/global-search/GlobalSearchContent.test.tsx b/src/web-ui/src/app/global-search/GlobalSearchContent.test.tsx
index cd7937aa62..5df255791c 100644
--- a/src/web-ui/src/app/global-search/GlobalSearchContent.test.tsx
+++ b/src/web-ui/src/app/global-search/GlobalSearchContent.test.tsx
@@ -3,7 +3,8 @@ import React, { act } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { activateSurface, resetDeviceSurfaceForTest } from '@/infrastructure/peer-device/deviceSurface';
-import { GlobalSearchContent } from './GlobalSearchRoot';
+import GlobalSearchRoot, { GlobalSearchContent } from './GlobalSearchRoot';
+import { useGlobalSearchStore } from './globalSearchStore';
 import type { GlobalSearchSnapshot } from './types';
 
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
@@ -43,17 +44,39 @@ const snapshot: GlobalSearchSnapshot = {
   ],
 };
 
+const diagnosticSnapshot: GlobalSearchSnapshot = { ...snapshot, diagnostics: [{
+  providerId: 'files', code: 'workspace_unavailable', message: 'Connection timed out',
+  workspaceName: 'Remote project', workspacePath: '/srv/project', hostLabel: 'build-host',
+}] };
+
 describe('GlobalSearchContent accessibility', () => {
   let container: HTMLDivElement;
   let root: Root;
+  const diagnosticPanel = () => document.querySelector<HTMLElement>('.global-search__diagnostics-panel');
+  const diagnosticTrigger = () => document.querySelector<HTMLButtonElement>('[data-testid$="-partial-status"] button')!;
+  const key = (target: Element, value: string, isComposing = false) => act(() => {
+    target.dispatchEvent(new KeyboardEvent('keydown', { key: value, bubbles: true, cancelable: true, isComposing }));
+  });
+  const renderDiagnostics = async (modal = false) => {
+    fixtures.search.mockImplementationOnce((_providers, _request, _signal, onUpdate) => onUpdate(diagnosticSnapshot));
+    if (modal) useGlobalSearchStore.getState().openSearch('needle');
+    act(() => root.render(modal ? <GlobalSearchRoot /> : <GlobalSearchContent initialQuery="needle" />));
+    await act(async () => { await vi.runOnlyPendingTimersAsync(); });
+    return diagnosticTrigger();
+  };
   beforeEach(() => {
     resetDeviceSurfaceForTest();
+    useGlobalSearchStore.setState({ open: false, initialQuery: '' });
     vi.useFakeTimers();
     fixtures.activate.mockReset();
     fixtures.search.mockReset();
     fixtures.search.mockImplementation((_providers, _request, _signal, onUpdate) => onUpdate(snapshot));
     HTMLElement.prototype.scrollIntoView = vi.fn();
+    HTMLElement.prototype.scrollTo = vi.fn();
     vi.stubGlobal('CSS', { escape: (value: string) => value });
+    const media = new EventTarget();
+    Object.defineProperty(media, 'matches', { value: false });
+    vi.stubGlobal('matchMedia', () => media);
     container = document.createElement('div');
     document.body.appendChild(container);
     root = createRoot(container);
@@ -61,7 +84,10 @@ describe('GlobalSearchContent accessibility', () => {
   afterEach(() => {
     act(() => root.unmount());
     container.remove();
+    useGlobalSearchStore.setState({ open: false, initialQuery: '' });
+    document.querySelectorAll('[data-openbitfun-overlay-host]').forEach(element => element.remove());
     vi.useRealTimers();
+    vi.restoreAllMocks();
     vi.unstubAllGlobals();
   });
   it('retains named native actions and tracks keyboard selection in the controlled grid', async () => {
@@ -83,64 +109,154 @@ describe('GlobalSearchContent accessibility', () => {
     expect(fixtures.activate).toHaveBeenCalledWith(snapshot.items[0].target, expect.anything());
   });
   it('shows source diagnostics and retries without clearing the query or healthy results', async () => {
-    const failure = { ...snapshot, diagnostics: [{
-      providerId: 'files', code: 'workspace_unavailable', message: 'Connection timed out',
-      workspaceName: 'Remote project', workspacePath: '/srv/project', hostLabel: 'build-host',
-    }] };
-    fixtures.search.mockImplementationOnce((_providers, _request, _signal, onUpdate) => onUpdate(failure));
+    fixtures.search.mockImplementationOnce((_providers, _request, _signal, onUpdate) => onUpdate(diagnosticSnapshot));
     fixtures.search.mockImplementationOnce((_providers, _request, _signal, onUpdate, retry) =>
       onUpdate({ ...retry.previous, isSearching: true }));
     act(() => root.render(<GlobalSearchContent initialQuery="needle" />));
     await act(async () => { await vi.runOnlyPendingTimersAsync(); });
-    const details = container.querySelector('details')!;
-    expect(details.textContent).toContain('Connection timed out');
-    expect(details.textContent).toContain('/srv/project');
-    expect(details.textContent).toContain('build-host');
-    act(() => details.querySelector<HTMLButtonElement>('button')!.click());
+    act(() => diagnosticTrigger().click());
+    const panel = diagnosticPanel()!;
+    expect(panel.textContent).toContain('Connection timed out');
+    expect(panel.textContent).toContain('/srv/project');
+    expect(panel.textContent).toContain('build-host');
+    act(() => panel.querySelector<HTMLButtonElement>('button')!.click());
     await act(async () => { await vi.runOnlyPendingTimersAsync(); });
-    expect(fixtures.search.mock.calls[1][4]).toEqual({ previous: failure, providerIds: ['files'] });
+    expect(fixtures.search.mock.calls[1][4]).toEqual({ previous: diagnosticSnapshot, providerIds: ['files'] });
     expect(container.querySelector('input')?.value).toBe('needle');
     expect(container.textContent).toContain('Open terminal');
-    expect(details.querySelector('button')?.disabled).toBe(true);
+    expect(panel.querySelector('button')?.disabled).toBe(true);
   });
 
-  it('toggles diagnostic panel and closes it on Escape or click outside', async () => {
-    const failure = { ...snapshot, diagnostics: [{
-      providerId: 'files', code: 'workspace_unavailable', message: 'Connection timed out',
-      workspaceName: 'Remote project', workspacePath: '/srv/project', hostLabel: 'build-host',
-    }] };
-    fixtures.search.mockImplementationOnce((_providers, _request, _signal, onUpdate) => onUpdate(failure));
-    act(() => root.render(<GlobalSearchContent initialQuery="needle" />));
-    await act(async () => { await vi.runOnlyPendingTimersAsync(); });
-
-    const details = container.querySelector('details')!;
-    const summary = details.querySelector('summary')!;
-    expect(details.hasAttribute('open')).toBe(false);
-    expect(details.querySelector('.global-search__diagnostics-panel')).not.toBeNull();
-
-    // Toggle open
+  it('toggles a named diagnostics portal through its owning trigger', async () => {
+    const trigger = await renderDiagnostics();
+    expect(trigger.getAttribute('aria-expanded')).toBe('false');
+    expect(diagnosticPanel()).toBeNull();
+    act(() => trigger.click());
+    const panel = diagnosticPanel()!;
+    expect(trigger.getAttribute('aria-expanded')).toBe('true');
+    expect(trigger.getAttribute('aria-controls')).toBe(panel.id);
+    expect(panel.getAttribute('role')).toBe('dialog');
+    expect(panel.getAttribute('aria-labelledby')).toBe(trigger.id);
+    expect(panel.closest('[data-openbitfun-overlay-layer]')).not.toBeNull();
+    expect(container.contains(panel)).toBe(false);
+    expect(document.activeElement).toBe(panel);
     act(() => {
-      details.open = true;
-      details.dispatchEvent(new Event('toggle'));
+      trigger.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
+      trigger.click();
     });
-    expect(details.open).toBe(true);
+    expect(diagnosticPanel()).toBeNull();
+    expect(trigger.getAttribute('aria-expanded')).toBe('false');
+  });
 
-    // Escape closes diagnostics panel
-    act(() => {
-      container.querySelector('.global-search')!.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
-    });
-    expect(details.open).toBe(false);
+  it.each(['panel', 'query'])('dismisses diagnostics before the real search Dialog with focus in the %s', async (focus) => {
+    const trigger = await renderDiagnostics(true);
+    act(() => trigger.click());
+    const panel = diagnosticPanel()!;
+    const dialog = document.querySelector<HTMLElement>('[data-testid="global-search-dialog"]')!;
+    const target = focus === 'panel' ? panel : dialog.querySelector<HTMLInputElement>('input')!;
+    act(() => target.focus());
+    expect(document.activeElement).toBe(target);
+    key(target, 'Escape', true);
+    expect(diagnosticPanel()).toBe(panel);
+    key(target, 'Escape');
+    expect(diagnosticPanel()).toBeNull();
+    expect(useGlobalSearchStore.getState().open).toBe(true);
+    expect(dialog.getAttribute('data-state')).toBe('open');
+    expect(document.activeElement).toBe(trigger);
+    key(trigger, 'Escape');
+    expect(useGlobalSearchStore.getState().open).toBe(false);
+    await act(async () => { await vi.runOnlyPendingTimersAsync(); });
+    expect(document.querySelector('[data-testid="global-search-dialog"]')).toBeNull();
+  });
 
-    // Reopen and click outside closes diagnostics panel
+  it('keeps portalled retry controls inside the modal focus domain and preserves outside focus on dismissal', async () => {
+    const trigger = await renderDiagnostics(true);
+    act(() => trigger.click());
+    const panel = diagnosticPanel()!;
+    const retry = panel.querySelector<HTMLButtonElement>('button')!;
     act(() => {
-      details.open = true;
-      details.dispatchEvent(new Event('toggle'));
+      retry.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
+      retry.focus();
     });
-    expect(details.open).toBe(true);
+    expect(diagnosticPanel()).toBe(panel);
+    expect(document.activeElement).toBe(retry);
+    const input = document.querySelector<HTMLInputElement>('[data-testid="global-search-dialog"] input')!;
     act(() => {
-      document.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
+      input.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
+      input.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }));
+      input.focus();
     });
-    expect(details.open).toBe(false);
+    expect(diagnosticPanel()).toBeNull();
+    expect(useGlobalSearchStore.getState().open).toBe(true);
+    expect(document.activeElement).toBe(input);
+  });
+
+  it('dismisses only the top layer for each outside pointer gesture', async () => {
+    const trigger = await renderDiagnostics(true);
+    act(() => trigger.click());
+    const backdrop = document.querySelector('[data-testid="global-search-dialog"]')!.parentElement!;
+    const clickBackdrop = () => {
+      act(() => backdrop.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true })));
+      act(() => backdrop.dispatchEvent(new MouseEvent('mousedown', { bubbles: true })));
+    };
+    clickBackdrop();
+    expect(diagnosticPanel()).toBeNull();
+    expect(useGlobalSearchStore.getState().open).toBe(true);
+    clickBackdrop();
+    expect(useGlobalSearchStore.getState().open).toBe(false);
+  });
+
+  it('dismisses diagnostics before leaving a group detail page or closing the search Dialog', async () => {
+    const grouped: GlobalSearchSnapshot = { ...diagnosticSnapshot, items: ['one', 'two'].map(id => ({
+      id, providerId: 'workspaces', group: 'workspaces', title: id, score: 80,
+      target: { kind: 'workspace', workspaceId: id },
+    })) };
+    fixtures.search.mockImplementationOnce((_providers, _request, _signal, onUpdate) => onUpdate(grouped));
+    useGlobalSearchStore.getState().openSearch();
+    act(() => root.render(<GlobalSearchRoot />));
+    await act(async () => { await vi.runOnlyPendingTimersAsync(); });
+    act(() => document.querySelector<HTMLButtonElement>('[data-testid="global-search-group-drilldown-workspaces"]')!.click());
+    await act(async () => { await vi.runOnlyPendingTimersAsync(); });
+    const view = document.querySelector('.global-search')!;
+    expect(view.getAttribute('data-search-view')).toBe('workspaces');
+    act(() => diagnosticTrigger().click());
+    key(diagnosticPanel()!, 'Escape');
+    expect(diagnosticPanel()).toBeNull();
+    expect(view.getAttribute('data-search-view')).toBe('workspaces');
+    expect(useGlobalSearchStore.getState().open).toBe(true);
+    key(diagnosticTrigger(), 'Escape');
+    expect(view.getAttribute('data-search-view')).toBe('overview');
+    expect(useGlobalSearchStore.getState().open).toBe(true);
+    key(diagnosticTrigger(), 'Escape');
+    expect(useGlobalSearchStore.getState().open).toBe(false);
+  });
+
+  it('clamps diagnostics near viewport edges instead of clipping them to the search container', async () => {
+    vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
+      return this.classList.contains('global-search__diagnostics-panel')
+        ? new DOMRect(0, 0, 300, 200)
+        : new DOMRect(window.innerWidth - 100, window.innerHeight - 40, 80, 24);
+    });
+    const trigger = await renderDiagnostics(true);
+    act(() => trigger.click());
+    const panel = diagnosticPanel()!;
+    expect(Number.parseFloat(panel.style.left) + 300).toBeLessThanOrEqual(window.innerWidth - 8);
+    expect(Number.parseFloat(panel.style.top) + 200).toBeLessThan(window.innerHeight - 40);
+    expect(panel.style.visibility).toBe('visible');
+  });
+
+  it('removes old-host diagnostics immediately when switching devices', async () => {
+    const trigger = await renderDiagnostics(true);
+    act(() => trigger.click());
+    expect(diagnosticPanel()?.textContent).toContain('/srv/project');
+    const [, , signal, publishOld] = fixtures.search.mock.calls[0];
+    act(() => activateSurface('peer-b'));
+    expect(signal.aborted).toBe(true);
+    expect(diagnosticPanel()).toBeNull();
+    expect(document.querySelector('[data-testid="global-search-partial-status"]')).toBeNull();
+    act(() => publishOld(diagnosticSnapshot));
+    expect(diagnosticPanel()).toBeNull();
+    expect(document.body.textContent).not.toContain('/srv/project');
   });
 
   it('discards old results and ignores late completions after a device switch', async () => {
diff --git a/src/web-ui/src/app/global-search/GlobalSearchRoot.scss b/src/web-ui/src/app/global-search/GlobalSearchRoot.scss
index 5d6d4e7a81..9cb1ee5a27 100644
--- a/src/web-ui/src/app/global-search/GlobalSearchRoot.scss
+++ b/src/web-ui/src/app/global-search/GlobalSearchRoot.scss
@@ -340,8 +340,6 @@ $chevron-box-slack: 5px;
   }
 
   &__footer {
-    position: relative;
-    z-index: 5;
     display: flex;
     flex: 0 0 40px;
     align-items: center;
@@ -892,42 +890,17 @@ $chevron-box-slack: 5px;
 }
 
 .global-search__diagnostics {
-  position: relative;
   min-width: 0;
   margin-right: auto;
   color: var(--openbitfun-color-content-muted);
+}
 
-  summary {
-    display: inline-flex;
-    align-items: center;
-    gap: 6px;
-    cursor: pointer;
-    user-select: none;
-    color: var(--openbitfun-color-content-muted);
-    font-size: var(--openbitfun-type-meta-font-size);
-    border-radius: var(--openbitfun-radius-sm);
-    padding: 2px 6px;
-    margin-left: -6px;
-    list-style: none;
-    transition: background-color var(--openbitfun-motion-duration-fast) ease,
-                color var(--openbitfun-motion-duration-fast) ease;
-
-    &::-webkit-details-marker {
-      display: none;
-    }
-
-    &:hover {
-      background: var(--openbitfun-color-action-quiet-hover);
-      color: var(--openbitfun-color-content-primary);
-    }
-
-    &:focus-visible {
-      outline: 2px solid var(--openbitfun-color-accent-default);
-      outline-offset: 1px;
-    }
-  }
+.global-search__diagnostics-summary {
+  color: var(--openbitfun-color-content-muted);
+  font-size: var(--openbitfun-type-meta-font-size);
+  margin-left: -6px;
 
-  &[open] summary {
+  &[aria-expanded='true'] {
     background: var(--openbitfun-color-action-quiet-hover);
     color: var(--openbitfun-color-content-primary);
   }
@@ -939,15 +912,12 @@ $chevron-box-slack: 5px;
 }
 
 .global-search__diagnostics-panel {
-  position: absolute;
-  bottom: calc(100% + 8px);
-  left: 0;
-  z-index: 30;
+  position: fixed;
   box-sizing: border-box;
   width: max-content;
-  min-width: 280px;
-  max-width: min(480px, calc(100vw - 36px));
-  max-height: 240px;
+  min-width: min(280px, calc(100vw - 16px));
+  max-width: min(480px, calc(100vw - 16px));
+  max-height: min(240px, calc(100vh - 16px));
   overflow-y: auto;
   padding: 10px 14px;
   background: var(--openbitfun-color-surface-raised);
@@ -955,6 +925,7 @@ $chevron-box-slack: 5px;
   border-radius: var(--openbitfun-radius-md);
   box-shadow: var(--openbitfun-shadow-overlay);
   color: var(--openbitfun-color-content-primary);
+  font-family: var(--openbitfun-type-body-sm-font-family);
   font-size: var(--openbitfun-type-meta-font-size);
 }
 
@@ -990,7 +961,7 @@ $chevron-box-slack: 5px;
 
 .global-search__diagnostic-path {
   color: var(--openbitfun-color-content-muted);
-  font-family: var(--openbitfun-font-family-mono);
+  font-family: var(--openbitfun-type-code-sm-font-family);
   font-size: var(--openbitfun-type-micro-font-size);
   margin-block-start: 2px;
 }
diff --git a/src/web-ui/src/app/global-search/GlobalSearchRoot.tsx b/src/web-ui/src/app/global-search/GlobalSearchRoot.tsx
index ca32d2c0be..9ffb2fadc7 100644
--- a/src/web-ui/src/app/global-search/GlobalSearchRoot.tsx
+++ b/src/web-ui/src/app/global-search/GlobalSearchRoot.tsx
@@ -19,6 +19,7 @@ import { OverflowText,
   ScrollArea,
   Dialog,
   DialogBody,
+  Portal,
 } from '@openbitfun/ui';
 import { AlertCircle, BarChart3, Blocks, CheckSquare2, FileText, Keyboard, MessageSquareText, MessagesSquare, Network, Users } from 'lucide-react';
 import { useShortcut } from '@/infrastructure/hooks/useShortcut';
@@ -30,6 +31,7 @@ import { useMyAgentStore } from '@/app/scenes/my-agent/myAgentStore';
 import { useNurseryStore } from '@/app/scenes/profile/nurseryStore';
 import { notificationService } from '@/shared/notification-system';
 import { createLogger } from '@/shared/utils/logger';
+import { useAnchoredPopoverPosition } from '@/shared/utils/useAnchoredPopoverPosition';
 import { activateGlobalSearchTarget } from './globalSearchActivator';
 import { runFederatedSearch } from './federatedSearchEngine';
 import { globalSearchRegistry } from './globalSearchRegistry';
@@ -184,13 +186,29 @@ export const GlobalSearchContent: React.FC<GlobalSearchContentProps> = ({
   const [activeId, setActiveId] = useState<string | null>(null);
   const [drilldownGroup, setDrilldownGroup] = useState<GlobalSearchDrilldownGroupId | null>(null);
   const [diagnosticsOpen, setDiagnosticsOpen] = useState(false);
-  const diagnosticsRef = useRef<HTMLDetailsElement>(null);
+  const diagnosticsTriggerRef = useRef<HTMLButtonElement>(null);
+  const diagnosticsPanelRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLInputElement>(null);
   const inputCompositionActiveRef = useRef(false);
   const listRef = useRef<HTMLDivElement>(null);
   const generatedId = useId().replace(/:/g, '');
   const instanceId = `global-search-${generatedId || 'content'}`;
   const resultsId = `${instanceId}-results`;
+  const diagnosticsId = `${instanceId}-diagnostics`;
+  const diagnosticsTriggerId = `${diagnosticsId}-trigger`;
+  const diagnosticsVisible = active && diagnosticsOpen && snapshot.diagnostics.length > 0;
+  const diagnosticsLayout = useAnchoredPopoverPosition({
+    open: diagnosticsVisible,
+    anchorRef: diagnosticsTriggerRef,
+    popoverRef: diagnosticsPanelRef,
+    preferredPlacement: 'top',
+    gap: 8,
+    layoutRevision: snapshot.diagnostics,
+  });
+  const diagnosticsPositioned = diagnosticsLayout !== null;
+  useEffect(() => {
+    if (diagnosticsVisible && diagnosticsPositioned) diagnosticsPanelRef.current?.focus();
+  }, [diagnosticsVisible, diagnosticsPositioned]);
   const testIdPrefix = variant === 'modal' ? 'global-search' : 'embedded-global-search';
   const providers = useSyncExternalStore(
     globalSearchRegistry.subscribe,
@@ -379,38 +397,19 @@ export const GlobalSearchContent: React.FC<GlobalSearchContentProps> = ({
   }, [focusSearchInput]);
 
   useEffect(() => {
-    if (snapshot.diagnostics.length === 0) {
+    if (!active || snapshot.diagnostics.length === 0) {
       setDiagnosticsOpen(false);
     }
-  }, [snapshot.diagnostics.length]);
-
-  useEffect(() => {
-    if (!diagnosticsOpen) return;
-    const handlePointerDownOutside = (event: PointerEvent) => {
-      if (diagnosticsRef.current && !diagnosticsRef.current.contains(event.target as Node)) {
-        setDiagnosticsOpen(false);
-      }
-    };
-    document.addEventListener('pointerdown', handlePointerDownOutside);
-    return () => document.removeEventListener('pointerdown', handlePointerDownOutside);
-  }, [diagnosticsOpen]);
+  }, [active, snapshot.diagnostics.length]);
 
   const handleRootKeyDownCapture = useCallback((event: React.KeyboardEvent<HTMLDivElement>) => {
-    if (isImeOwnedKeyboardEvent(event, inputCompositionActiveRef.current)) return;
-    if (event.key === 'Escape') {
-      if (diagnosticsOpen) {
-        event.preventDefault();
-        event.stopPropagation();
-        setDiagnosticsOpen(false);
-        return;
-      }
-      if (drilldownGroup) {
-        event.preventDefault();
-        event.stopPropagation();
-        closeGroupDetails();
-      }
-    }
-  }, [closeGroupDetails, diagnosticsOpen, drilldownGroup]);
+    // The diagnostics layer owns Escape before the underlying group or dialog.
+    if (diagnosticsVisible || isImeOwnedKeyboardEvent(event, inputCompositionActiveRef.current)) return;
+    if (event.key !== 'Escape' || !drilldownGroup) return;
+    event.preventDefault();
+    event.stopPropagation();
+    closeGroupDetails();
+  }, [closeGroupDetails, diagnosticsVisible, drilldownGroup]);
 
   const effectiveScope = parsedQuery.scope;
   const emptyLabel = effectiveScope === 'content' && parsedQuery.query.length < 2
@@ -694,40 +693,73 @@ export const GlobalSearchContent: React.FC<GlobalSearchContentProps> = ({
           || snapshot.diagnostics.length > 0) ? (
         <footer className="global-search__footer" data-openbitfun-component="global-search" data-openbitfun-part="footer">
           {snapshot.diagnostics.length > 0 ? (
-            <details
+            <div
               className="global-search__diagnostics"
               data-testid={`${testIdPrefix}-partial-status`}
-              ref={diagnosticsRef}
-              open={diagnosticsOpen}
-              onToggle={(event) => setDiagnosticsOpen(event.currentTarget.open)}
             >
-              <summary className="global-search__diagnostics-summary">
-                <AlertCircle size={13} aria-hidden="true" className="global-search__diagnostics-icon" />
-                <span>{tCommon('nav.search.partialUnavailable')}</span>
-              </summary>
-              <div className="global-search__diagnostics-panel">
-                <div className="global-search__diagnostic-target">
-                  {tCommon('nav.search.diagnosticTarget', { host: hostLabel })}
-                </div>
-                {snapshot.diagnostics.map((diagnostic, index) => (
-                  <div className="global-search__diagnostic" key={`${diagnostic.providerId}:${diagnostic.code}:${index}`}>
-                    <div className="global-search__diagnostic-header">
-                      <strong>{providers.find(provider => provider.id === diagnostic.providerId)?.groups
-                        .map(group => tCommon(`nav.search.groups.${group}`)).join(' / ') ?? diagnostic.providerId}</strong>
-                      {diagnostic.workspaceName ? <div>{diagnostic.workspaceName} · {diagnostic.hostLabel ?? hostLabel}</div> : null}
+              <Button
+                ref={diagnosticsTriggerRef}
+                id={diagnosticsTriggerId}
+                className="global-search__diagnostics-summary"
+                variant="text"
+                size="xs"
+                aria-haspopup="dialog"
+                aria-expanded={diagnosticsVisible}
+                aria-controls={diagnosticsVisible ? diagnosticsId : undefined}
+                leadingIcon={<AlertCircle size={13} aria-hidden="true" className="global-search__diagnostics-icon" />}
+                onClick={() => setDiagnosticsOpen(open => !open)}
+              >
+                {tCommon('nav.search.partialUnavailable')}
+              </Button>
+              {diagnosticsVisible ? (
+                <Portal
+                  ownerRef={diagnosticsTriggerRef}
+                  surfaceRef={diagnosticsPanelRef}
+                  open={diagnosticsVisible}
+                  dismissOnPointerOutside
+                  onDismiss={(reason) => {
+                    if (reason === 'escape-key') diagnosticsTriggerRef.current?.focus();
+                    setDiagnosticsOpen(false);
+                  }}
+                >
+                  <div
+                    ref={diagnosticsPanelRef}
+                    id={diagnosticsId}
+                    role="dialog"
+                    aria-labelledby={diagnosticsTriggerId}
+                    tabIndex={-1}
+                    className="global-search__diagnostics-panel"
+                    data-openbitfun-native-webview-occlusion
+                    style={{
+                      left: diagnosticsLayout?.left ?? 0,
+                      top: diagnosticsLayout?.top ?? 0,
+                      visibility: diagnosticsLayout ? 'visible' : 'hidden',
+                    }}
+                  >
+                    <div className="global-search__diagnostic-target">
+                      {tCommon('nav.search.diagnosticTarget', { host: hostLabel })}
                     </div>
-                    {diagnostic.workspacePath ? <div className="global-search__diagnostic-path">{diagnostic.workspacePath}</div> : null}
-                    <p>{diagnostic.message}</p>
-                    {diagnostic.retryable !== false ? (
-                      <Button size="sm" variant="outline" disabled={snapshot.isSearching}
-                        onClick={() => retryProvider(diagnostic.providerId)}>
-                        {tCommon('nav.search.retrySource')}
-                      </Button>
-                    ) : null}
+                    {snapshot.diagnostics.map((diagnostic, index) => (
+                      <div className="global-search__diagnostic" key={`${diagnostic.providerId}:${diagnostic.code}:${index}`}>
+                        <div className="global-search__diagnostic-header">
+                          <strong>{providers.find(provider => provider.id === diagnostic.providerId)?.groups
+                            .map(group => tCommon(`nav.search.groups.${group}`)).join(' / ') ?? diagnostic.providerId}</strong>
+                          {diagnostic.workspaceName ? <div>{diagnostic.workspaceName} · {diagnostic.hostLabel ?? hostLabel}</div> : null}
+                        </div>
+                        {diagnostic.workspacePath ? <div className="global-search__diagnostic-path">{diagnostic.workspacePath}</div> : null}
+                        <p>{diagnostic.message}</p>
+                        {diagnostic.retryable !== false ? (
+                          <Button size="sm" variant="outline" disabled={snapshot.isSearching}
+                            onClick={() => retryProvider(diagnostic.providerId)}>
+                            {tCommon('nav.search.retrySource')}
+                          </Button>
+                        ) : null}
+                      </div>
+                    ))}
                   </div>
-                ))}
-              </div>
-            </details>
+                </Portal>
+              ) : null}
+            </div>
           ) : null}
           <span className="global-search__footer-keys" aria-hidden="true">
             <KeyHint>↑↓</KeyHint> {tCommon('nav.search.footer.navigate')}