From 0409d510792e2356b926f4fe48ef2ce50e26d48c Mon Sep 17 00:00:00 2001
From: Hao Wang <haowang@HaodeMac-mini.lan>
Date: Wed, 22 Jul 2026 21:25:47 +0800
Subject: [PATCH 1/4] fix(desktop): recover transient client lookup races

---
 apps/desktop/src/app/contrib/wiring.tsx       |  14 +-
 .../src/components/error-boundary.test.tsx    | 265 ++++++++++++++++++
 .../desktop/src/components/error-boundary.tsx | 147 ++++++++++
 3 files changed, 424 insertions(+), 2 deletions(-)
 create mode 100644 apps/desktop/src/components/error-boundary.test.tsx

diff --git a/apps/desktop/src/app/contrib/wiring.tsx b/apps/desktop/src/app/contrib/wiring.tsx
index b2d0c03a98816..3fc9cf9bf0aa9 100644
--- a/apps/desktop/src/app/contrib/wiring.tsx
+++ b/apps/desktop/src/app/contrib/wiring.tsx
@@ -16,6 +16,7 @@ import { useLocation, useNavigate } from 'react-router-dom'
 import { formatRefValue } from '@/components/assistant-ui/directive-text'
 import { BootFailureOverlay } from '@/components/boot-failure-overlay'
 import { DesktopInstallOverlay } from '@/components/desktop-install-overlay'
+import { ErrorBoundary, ScopedErrorFallback } from '@/components/error-boundary'
 import { GatewayConnectingOverlay } from '@/components/gateway-connecting-overlay'
 import { NotificationStack } from '@/components/notifications'
 import { DesktopOnboardingOverlay } from '@/components/onboarding'
@@ -823,8 +824,17 @@ export function ContribWiring({ children }: { children: ReactNode }) {
   // The voice cap changes only on config load; the gateway instance + all
   // chat reactivity are subscribed inside ChatRoutesSurface / ChatView.
   const chatRoutesNode = useMemo(
-    () => <ChatRoutesSurface actions={actions} maxVoiceRecordingSeconds={voiceMaxRecordingSeconds} />,
-    [actions, voiceMaxRecordingSeconds]
+    () => (
+      <ErrorBoundary
+        fallback={ScopedErrorFallback}
+        label="chat-routes"
+        recoverClientLookup
+        resetKeys={[profileScope, gatewayState, activeSessionId, routeToken]}
+      >
+        <ChatRoutesSurface actions={actions} maxVoiceRecordingSeconds={voiceMaxRecordingSeconds} />
+      </ErrorBoundary>
+    ),
+    [actions, activeSessionId, gatewayState, profileScope, routeToken, voiceMaxRecordingSeconds]
   )
 
   const api = useMemo<WiringApi>(
diff --git a/apps/desktop/src/components/error-boundary.test.tsx b/apps/desktop/src/components/error-boundary.test.tsx
new file mode 100644
index 0000000000000..5b2dabf670a28
--- /dev/null
+++ b/apps/desktop/src/components/error-boundary.test.tsx
@@ -0,0 +1,265 @@
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { StrictMode } from 'react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { ErrorBoundary } from './error-boundary'
+
+const USE_LOOKUP_ERROR = new Error('useClientLookup: Index 0 out of bounds (length: 0)')
+const TAP_LOOKUP_ERROR = new Error('tapClientLookup: Index 0 out of bounds (length: 0)')
+
+function makeBomb(box: { error: Error | null }) {
+  return function Bomb() {
+    if (box.error) {
+      throw box.error
+    }
+
+    return <div>recovered</div>
+  }
+}
+
+function Fallback({ reset }: { reset: () => void }) {
+  return <button onClick={reset}>manual reset</button>
+}
+
+function countLogCalls(spy: ReturnType<typeof vi.spyOn>, text: string) {
+  return spy.mock.calls.filter((call: unknown[]) => call.some((value: unknown) => String(value).includes(text))).length
+}
+
+describe('ErrorBoundary client lookup recovery', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.spyOn(console, 'error').mockImplementation(() => undefined)
+  })
+
+  afterEach(() => {
+    cleanup()
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+  })
+
+  it.each([USE_LOOKUP_ERROR, TAP_LOOKUP_ERROR])('recovers exact root lookup errors after the first delay', error => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const recoveredSpy = vi.spyOn(console, 'info').mockImplementation(() => undefined)
+    const box: { error: Error | null } = { error }
+    const Bomb = makeBomb(box)
+
+    render(
+      <ErrorBoundary fallback={Fallback} label="root">
+        <Bomb />
+      </ErrorBoundary>
+    )
+
+    expect(countLogCalls(warnSpy, 'client lookup recovery attempt 1/3')).toBe(1)
+    act(() => vi.advanceTimersByTime(249))
+    expect(screen.getByRole('button', { name: 'manual reset' })).toBeTruthy()
+
+    box.error = null
+    act(() => vi.advanceTimersByTime(1))
+
+    expect(screen.getByText('recovered')).toBeTruthy()
+    expect(countLogCalls(recoveredSpy, 'client lookup recovery recovered after attempt 1')).toBe(1)
+  })
+
+  it('waits for a later retry when the client store recovers slowly', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const box: { error: Error | null } = { error: USE_LOOKUP_ERROR }
+    const Bomb = makeBomb(box)
+
+    render(
+      <ErrorBoundary fallback={Fallback} label="root">
+        <Bomb />
+      </ErrorBoundary>
+    )
+
+    act(() => vi.advanceTimersByTime(250))
+    expect(countLogCalls(warnSpy, 'client lookup recovery attempt')).toBe(2)
+
+    box.error = null
+    act(() => vi.advanceTimersByTime(999))
+    expect(screen.getByRole('button', { name: 'manual reset' })).toBeTruthy()
+
+    act(() => vi.advanceTimersByTime(1))
+    expect(screen.getByText('recovered')).toBeTruthy()
+  })
+
+  it('stops after three persistent errors and reports exhaustion once', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const Bomb = makeBomb({ error: USE_LOOKUP_ERROR })
+
+    render(
+      <ErrorBoundary fallback={Fallback} label="root">
+        <Bomb />
+      </ErrorBoundary>
+    )
+
+    act(() => vi.advanceTimersByTime(250))
+    act(() => vi.advanceTimersByTime(1_000))
+    act(() => vi.advanceTimersByTime(3_000))
+
+    expect(countLogCalls(warnSpy, 'client lookup recovery attempt')).toBe(3)
+    expect(countLogCalls(warnSpy, 'client lookup recovery exhausted')).toBe(1)
+    expect(screen.getByRole('button', { name: 'manual reset' })).toBeTruthy()
+    expect(vi.getTimerCount()).toBe(0)
+  })
+
+  it('does not restore the retry budget until a recovery remains stable for 30 seconds', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const box: { error: Error | null } = { error: USE_LOOKUP_ERROR }
+    const Bomb = makeBomb(box)
+
+    const view = render(
+      <ErrorBoundary fallback={Fallback} label="root">
+        <Bomb />
+      </ErrorBoundary>
+    )
+
+    box.error = null
+    act(() => vi.advanceTimersByTime(250))
+    expect(screen.getByText('recovered')).toBeTruthy()
+
+    act(() => vi.advanceTimersByTime(29_999))
+    box.error = USE_LOOKUP_ERROR
+    view.rerender(
+      <ErrorBoundary fallback={Fallback} label="root">
+        <Bomb />
+      </ErrorBoundary>
+    )
+    expect(countLogCalls(warnSpy, 'client lookup recovery attempt 2/3')).toBe(1)
+
+    box.error = null
+    act(() => vi.advanceTimersByTime(1_000))
+    act(() => vi.advanceTimersByTime(30_000))
+
+    box.error = USE_LOOKUP_ERROR
+    view.rerender(
+      <ErrorBoundary fallback={Fallback} label="root">
+        <Bomb />
+      </ErrorBoundary>
+    )
+    expect(countLogCalls(warnSpy, 'client lookup recovery attempt 1/3')).toBe(2)
+  })
+
+  it('clears the retry budget when the user manually resets the boundary', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const box: { error: Error | null } = { error: USE_LOOKUP_ERROR }
+    const Bomb = makeBomb(box)
+
+    const view = render(
+      <ErrorBoundary fallback={Fallback} label="root">
+        <Bomb />
+      </ErrorBoundary>
+    )
+
+    act(() => vi.advanceTimersByTime(250))
+    act(() => vi.advanceTimersByTime(1_000))
+    act(() => vi.advanceTimersByTime(3_000))
+    box.error = null
+    fireEvent.click(screen.getByRole('button', { name: 'manual reset' }))
+    expect(screen.getByText('recovered')).toBeTruthy()
+
+    box.error = USE_LOOKUP_ERROR
+    view.rerender(
+      <ErrorBoundary fallback={Fallback} label="root">
+        <Bomb />
+      </ErrorBoundary>
+    )
+    expect(countLogCalls(warnSpy, 'client lookup recovery attempt 1/3')).toBe(2)
+  })
+
+  it('clears pending timers when unmounted', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const Bomb = makeBomb({ error: USE_LOOKUP_ERROR })
+
+    const { unmount } = render(
+      <ErrorBoundary fallback={Fallback} label="root">
+        <Bomb />
+      </ErrorBoundary>
+    )
+
+    unmount()
+    act(() => vi.runAllTimers())
+
+    expect(vi.getTimerCount()).toBe(0)
+    expect(countLogCalls(warnSpy, 'client lookup recovery attempt')).toBe(1)
+  })
+
+  it('does not double-schedule recovery in StrictMode', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const Bomb = makeBomb({ error: USE_LOOKUP_ERROR })
+
+    render(
+      <StrictMode>
+        <ErrorBoundary fallback={Fallback} label="root">
+          <Bomb />
+        </ErrorBoundary>
+      </StrictMode>
+    )
+
+    expect(countLogCalls(warnSpy, 'client lookup recovery attempt 1/3')).toBe(1)
+    expect(vi.getTimerCount()).toBe(1)
+  })
+
+  it('does not auto-recover unrelated root errors', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const UnrelatedBomb = makeBomb({ error: new Error('tapClientResource: Index 0 out of bounds (length: 0)') })
+
+    render(
+      <ErrorBoundary fallback={Fallback} label="root">
+        <UnrelatedBomb />
+      </ErrorBoundary>
+    )
+
+    expect(vi.getTimerCount()).toBe(0)
+    expect(warnSpy).not.toHaveBeenCalled()
+  })
+
+  it('does not auto-recover lookup errors outside the root boundary', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const ScopedBomb = makeBomb({ error: USE_LOOKUP_ERROR })
+
+    render(
+      <ErrorBoundary fallback={Fallback} label="thread">
+        <ScopedBomb />
+      </ErrorBoundary>
+    )
+
+    expect(vi.getTimerCount()).toBe(0)
+    expect(warnSpy).not.toHaveBeenCalled()
+  })
+
+  it('auto-recovers lookup errors in an explicitly enabled scoped boundary', () => {
+    const box: { error: Error | null } = { error: USE_LOOKUP_ERROR }
+    const ScopedBomb = makeBomb(box)
+
+    render(
+      <ErrorBoundary fallback={Fallback} label="chat-routes" recoverClientLookup>
+        <ScopedBomb />
+      </ErrorBoundary>
+    )
+
+    box.error = null
+    act(() => vi.advanceTimersByTime(250))
+
+    expect(screen.getByText('recovered')).toBeTruthy()
+  })
+
+  it('resets a scoped failure when its connection identity changes', () => {
+    const box: { error: Error | null } = { error: new Error('render failed') }
+    const ScopedBomb = makeBomb(box)
+
+    const view = render(
+      <ErrorBoundary fallback={Fallback} label="chat-routes" resetKeys={['connecting', 'session-a']}>
+        <ScopedBomb />
+      </ErrorBoundary>
+    )
+
+    box.error = null
+    view.rerender(
+      <ErrorBoundary fallback={Fallback} label="chat-routes" resetKeys={['open', 'session-a']}>
+        <ScopedBomb />
+      </ErrorBoundary>
+    )
+
+    expect(screen.getByText('recovered')).toBeTruthy()
+  })
+})
diff --git a/apps/desktop/src/components/error-boundary.tsx b/apps/desktop/src/components/error-boundary.tsx
index 87b6b7743c511..5c5dd61f9e5f3 100644
--- a/apps/desktop/src/components/error-boundary.tsx
+++ b/apps/desktop/src/components/error-boundary.tsx
@@ -14,29 +14,147 @@ interface ErrorBoundaryProps {
   fallback?: (props: ErrorBoundaryFallbackProps) => ReactNode
   label?: string
   onError?: (error: Error, info: ErrorInfo) => void
+  recoverClientLookup?: boolean
+  resetKeys?: readonly unknown[]
 }
 
 interface ErrorBoundaryState {
   error: Error | null
 }
 
+const CLIENT_LOOKUP_ERROR = /^(?:tap|use)ClientLookup: Index \d+\s+out of bounds \(length:\s*\d+\)$/i
+const AUTO_RECOVERY_DELAYS_MS = [250, 1_000, 3_000] as const
+const STABLE_RECOVERY_WINDOW_MS = 30_000
+
+const isTransientClientLookupError = (error: Error): boolean => CLIENT_LOOKUP_ERROR.test(error.message)
+
 export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
   state: ErrorBoundaryState = { error: null }
+  private autoRecoveryCount = 0
+  private autoRecoveryExhausted = false
+  private autoRecoveryTimer: number | null = null
+  private stableRecoveryTimer: number | null = null
+  private pendingAutoRecoveryAttempt: number | null = null
 
   static getDerivedStateFromError(error: Error): ErrorBoundaryState {
     return { error }
   }
 
+  componentDidMount() {
+    // React StrictMode simulates an unmount/remount cycle while preserving the
+    // component instance. Restore a pending retry that the simulated unmount
+    // cleaned up without consuming another attempt from the episode budget.
+    if (this.autoRecoveryTimer === null && this.pendingAutoRecoveryAttempt !== null) {
+      this.scheduleAutoRecovery(this.pendingAutoRecoveryAttempt)
+    }
+  }
+
   componentDidCatch(error: Error, info: ErrorInfo) {
     const tag = this.props.label ? `[error-boundary:${this.props.label}]` : '[error-boundary]'
     console.error(tag, error, info.componentStack)
     this.props.onError?.(error, info)
+
+    this.clearStableRecoveryTimer()
+
+    const recoveryEnabled = this.props.recoverClientLookup ?? this.props.label === 'root'
+
+    if (!recoveryEnabled || !isTransientClientLookupError(error)) {
+      return
+    }
+
+    const attempt = this.takeAutoRecoveryAttempt()
+
+    if (attempt === null) {
+      if (!this.autoRecoveryExhausted) {
+        this.autoRecoveryExhausted = true
+        console.warn(`${tag} client lookup recovery exhausted`)
+      }
+
+      return
+    }
+
+    console.warn(`${tag} client lookup recovery attempt ${attempt}/${AUTO_RECOVERY_DELAYS_MS.length}`)
+    this.scheduleAutoRecovery(attempt)
+  }
+
+  componentDidUpdate(previousProps: ErrorBoundaryProps) {
+    if (this.state.error && resetKeysChanged(previousProps.resetKeys, this.props.resetKeys)) {
+      this.reset()
+    }
+  }
+
+  componentWillUnmount() {
+    this.clearAutoRecoveryTimer()
+    this.clearStableRecoveryTimer()
   }
 
   reset = () => {
+    this.clearAutoRecoveryTimer()
+    this.clearStableRecoveryTimer()
+    this.autoRecoveryCount = 0
+    this.autoRecoveryExhausted = false
+    this.pendingAutoRecoveryAttempt = null
     this.setState({ error: null })
   }
 
+  private takeAutoRecoveryAttempt(): number | null {
+    if (this.autoRecoveryCount >= AUTO_RECOVERY_DELAYS_MS.length) {
+      return null
+    }
+
+    this.autoRecoveryCount += 1
+
+    return this.autoRecoveryCount
+  }
+
+  private scheduleAutoRecovery(attempt: number) {
+    this.clearAutoRecoveryTimer()
+    this.pendingAutoRecoveryAttempt = attempt
+    this.autoRecoveryTimer = window.setTimeout(this.autoRecover, AUTO_RECOVERY_DELAYS_MS[attempt - 1])
+  }
+
+  private autoRecover = () => {
+    this.autoRecoveryTimer = null
+    const attempt = this.pendingAutoRecoveryAttempt
+    this.pendingAutoRecoveryAttempt = null
+
+    this.setState({ error: null }, () => {
+      if (this.state.error !== null || attempt === null) {
+        return
+      }
+
+      const tag = this.props.label ? `[error-boundary:${this.props.label}]` : '[error-boundary]'
+      console.info(`${tag} client lookup recovery recovered after attempt ${attempt}`)
+      this.scheduleStableRecoveryReset()
+    })
+  }
+
+  private scheduleStableRecoveryReset() {
+    this.clearStableRecoveryTimer()
+    this.stableRecoveryTimer = window.setTimeout(() => {
+      this.stableRecoveryTimer = null
+
+      if (this.state.error === null) {
+        this.autoRecoveryCount = 0
+        this.autoRecoveryExhausted = false
+      }
+    }, STABLE_RECOVERY_WINDOW_MS)
+  }
+
+  private clearAutoRecoveryTimer() {
+    if (this.autoRecoveryTimer !== null) {
+      window.clearTimeout(this.autoRecoveryTimer)
+      this.autoRecoveryTimer = null
+    }
+  }
+
+  private clearStableRecoveryTimer() {
+    if (this.stableRecoveryTimer !== null) {
+      window.clearTimeout(this.stableRecoveryTimer)
+      this.stableRecoveryTimer = null
+    }
+  }
+
   render() {
     const { error } = this.state
 
@@ -75,3 +193,32 @@ function RootErrorFallback({ error, reset }: ErrorBoundaryFallbackProps) {
     </div>
   )
 }
+
+export function ScopedErrorFallback({ error, reset }: ErrorBoundaryFallbackProps) {
+  const { t } = useI18n()
+
+  return (
+    <div className="grid h-full min-h-64 place-items-center p-6">
+      <ErrorState
+        className="w-full max-w-[28rem]"
+        description={error.message || t.errors.boundaryDesc}
+        title={t.errors.boundaryTitle}
+      >
+        <Button className="font-semibold" onClick={reset} size="lg">
+          {t.common.retry}
+        </Button>
+        <Button onClick={() => void window.hermesDesktop?.revealLogs()?.catch(() => undefined)} variant="text">
+          {t.errors.openLogs}
+        </Button>
+      </ErrorState>
+    </div>
+  )
+}
+
+function resetKeysChanged(previous: readonly unknown[] | undefined, next: readonly unknown[] | undefined): boolean {
+  if (!previous || !next || previous.length !== next.length) {
+    return Boolean(previous || next)
+  }
+
+  return previous.some((value, index) => !Object.is(value, next[index]))
+}

From 74c99e182c6e25119eb20197f61dd55f5a391854 Mon Sep 17 00:00:00 2001
From: Hao Wang <haowang@HaodeMac-mini.lan>
Date: Wed, 22 Jul 2026 21:26:01 +0800
Subject: [PATCH 2/4] perf(desktop): serialize profile backend cold starts

---
 apps/desktop/electron/main.ts                 | 133 +++++++++++++-----
 apps/desktop/electron/preload.ts              |   2 +-
 .../electron/profile-backend-startup.test.ts  |  82 +++++++++++
 .../electron/profile-backend-startup.ts       |  61 ++++++++
 .../src/app/chat/sidebar/profile-switcher.tsx |  16 +--
 .../src/app/chat/sidebar/session-row.test.tsx |  30 +++-
 .../src/app/chat/sidebar/session-row.tsx      |   8 --
 .../app/chat/sidebar/use-profile-prewarm.ts   |  38 -----
 apps/desktop/src/global.d.ts                  |   4 +-
 apps/desktop/src/store/gateway.ts             |  29 +---
 apps/desktop/src/store/profile.test.ts        |  44 ++----
 apps/desktop/src/store/profile.ts             |  37 +----
 12 files changed, 289 insertions(+), 195 deletions(-)
 create mode 100644 apps/desktop/electron/profile-backend-startup.test.ts
 create mode 100644 apps/desktop/electron/profile-backend-startup.ts
 delete mode 100644 apps/desktop/src/app/chat/sidebar/use-profile-prewarm.ts

diff --git a/apps/desktop/electron/main.ts b/apps/desktop/electron/main.ts
index 7bf789ccf118d..9ea84d327a278 100644
--- a/apps/desktop/electron/main.ts
+++ b/apps/desktop/electron/main.ts
@@ -131,6 +131,11 @@ import { createLinkTitleWindow, guardLinkTitleSession, readLinkTitleWindowTitle
 import { ensureMainWindow } from './main-window-lifecycle'
 import { serializeJsonBody, setJsonRequestHeaders } from './oauth-net-request'
 import { createKeepAwake } from './power-save'
+import {
+  createProfileBackendStartupQueue,
+  normalizeProfileBackendStartReason,
+  reusePoolConnection
+} from './profile-backend-startup'
 import { decideProfileDeleteAction, profileNameFromDeleteRequest, resolveRouteProfile } from './profile-delete-routing'
 import * as remoteLifecycle from './remote-lifecycle'
 import { RemoteLivenessTracker, RemoteRevalidationCoordinator, revalidateRemoteConnection } from './remote-liveness'
@@ -988,6 +993,10 @@ let softRehomeInProgress = false
 // with no named profiles never populates this map, so their experience is
 // byte-for-byte the single-backend behavior.
 const backendPool = new Map() // profile -> { process, port, token, connectionPromise, lastActiveAt }
+// A cold local profile boot performs the same Python import, plugin/MCP setup,
+// and readiness work as the primary backend. Let only one profile do that work
+// at a time; existing pool promises and remote profiles do not wait here.
+const profileBackendStartupQueue = createProfileBackendStartupQueue()
 // Keep the pool light: cap concurrent profile backends (LRU eviction) and reap
 // idle ones. A user idles at exactly the primary backend; pool backends only
 // exist while a non-primary profile is actively being chatted through.
@@ -7471,26 +7480,48 @@ function primaryProfileKey() {
 // profile to startHermes() (the window backend: boot UI, bootstrap, remote
 // mode), and any OTHER profile to a lazily-spawned pool backend. An empty /
 // unknown profile resolves to the primary, so all legacy callers are unchanged.
-async function ensureBackend(profile) {
+async function ensureBackend(profile, requestedReason = 'unknown') {
   const key = profile && String(profile).trim() ? String(profile).trim() : primaryProfileKey()
+  const reason = normalizeProfileBackendStartReason(requestedReason)
 
   if (key === primaryProfileKey()) {
-    return startHermes()
-  }
+    if (backendConnectionState.getPromise()) {
+      return startHermes()
+    }
 
-  const existing = backendPool.get(key)
+    const startedAt = Date.now()
+    const primaryReason = reason === 'unknown' ? 'primary_boot' : reason
+    rememberLog(`Starting primary Hermes backend (reason ${primaryReason})`)
+
+    try {
+      const connection = await startHermes()
+      rememberLog(
+        `Primary Hermes backend ready (reason ${primaryReason}, mode ${connection.mode}, duration ${Date.now() - startedAt}ms)`
+      )
+
+      return connection
+    } catch (error) {
+      rememberLog(
+        `Primary Hermes backend failed (reason ${primaryReason}, duration ${Date.now() - startedAt}ms): ${error instanceof Error ? error.message : String(error)}`
+      )
+      throw error
+    }
+  }
 
-  if (existing) {
-    existing.lastActiveAt = Date.now()
+  const existingConnection = reusePoolConnection(backendPool.get(key))
 
-    return existing.connectionPromise
+  if (existingConnection) {
+    return existingConnection
   }
 
   evictLruPoolBackends(POOL_MAX_BACKENDS - 1)
 
   const entry = { process: null, port: null, token: null, connectionPromise: null, lastActiveAt: Date.now() }
-  entry.connectionPromise = spawnPoolBackend(key, entry).catch(error => {
-    backendPool.delete(key)
+  entry.connectionPromise = startPoolBackend(key, entry, reason).catch(error => {
+    if (backendPool.get(key) === entry) {
+      backendPool.delete(key)
+    }
+
     throw error
   })
   backendPool.set(key, entry)
@@ -7499,6 +7530,63 @@ async function ensureBackend(profile) {
   return entry.connectionPromise
 }
 
+async function startPoolBackend(profile, entry, reason) {
+  const requestedAt = Date.now()
+  const remote = await resolveRemoteBackend(profile)
+
+  if (remote) {
+    rememberLog(`Connecting to remote Hermes backend for profile "${profile}" (reason ${reason})`)
+
+    try {
+      await waitForHermes(remote.baseUrl, remote.token)
+    } catch (error) {
+      rememberLog(
+        `Remote Hermes backend failed for profile "${profile}" (reason ${reason}, duration ${Date.now() - requestedAt}ms): ${error instanceof Error ? error.message : String(error)}`
+      )
+      throw error
+    }
+
+    rememberLog(
+      `Remote Hermes backend ready for profile "${profile}" (reason ${reason}, duration ${Date.now() - requestedAt}ms)`
+    )
+
+    return {
+      ...remote,
+      profile,
+      logs: hermesLog.slice(-80),
+      ...getWindowState()
+    }
+  }
+
+  rememberLog(`Queueing local Hermes backend for profile "${profile}" (reason ${reason})`)
+
+  return profileBackendStartupQueue.run(async () => {
+    if (backendPool.get(profile) !== entry) {
+      throw new Error(`Hermes backend for profile "${profile}" was removed before startup.`)
+    }
+
+    const spawnStartedAt = Date.now()
+    const queueWaitMs = spawnStartedAt - requestedAt
+    rememberLog(
+      `Starting queued local Hermes backend for profile "${profile}" (reason ${reason}, queue wait ${queueWaitMs}ms)`
+    )
+
+    try {
+      const connection = await spawnPoolBackend(profile, entry, reason)
+      rememberLog(
+        `Local Hermes backend ready for profile "${profile}" (reason ${reason}, queue wait ${queueWaitMs}ms, spawn ${Date.now() - spawnStartedAt}ms, total ${Date.now() - requestedAt}ms)`
+      )
+
+      return connection
+    } catch (error) {
+      rememberLog(
+        `Local Hermes backend failed for profile "${profile}" (reason ${reason}, queue wait ${queueWaitMs}ms, spawn ${Date.now() - spawnStartedAt}ms): ${error instanceof Error ? error.message : String(error)}`
+      )
+      throw error
+    }
+  })
+}
+
 // Mark a pool profile as recently used so the idle reaper spares it. The
 // renderer calls this when it opens a profile's chat WS and periodically while
 // streaming, since the main process can't see the direct renderer↔backend WS.
@@ -7573,26 +7661,7 @@ function startPoolIdleReaper() {
 // Spawn an additional dashboard backend pinned to a named profile. Mirrors the
 // local-spawn portion of startHermes() but without the boot-progress UI,
 // bootstrap, or remote handling (those belong to the primary backend only).
-async function spawnPoolBackend(profile, entry) {
-  // A profile may point at its OWN remote backend (connection.json
-  // `profiles[name]`), or inherit the app-wide remote (env / global settings).
-  // In either case there is no local child to spawn — we just verify the
-  // remote is reachable and hand back its connection descriptor. The pool
-  // entry keeps `entry.process === null`, which stopPoolBackend/evict already
-  // tolerate.
-  const remote = await resolveRemoteBackend(profile)
-
-  if (remote) {
-    await waitForHermes(remote.baseUrl, remote.token)
-
-    return {
-      ...remote,
-      profile,
-      logs: hermesLog.slice(-80),
-      ...getWindowState()
-    }
-  }
-
+async function spawnPoolBackend(profile, entry, reason) {
   const token = crypto.randomBytes(32).toString('base64url')
   // --profile wins over the inherited HERMES_HOME env (see _apply_profile_override
   // step 3 in hermes_cli/main.py), so the child re-homes to this profile.
@@ -7605,7 +7674,7 @@ async function spawnPoolBackend(profile, entry) {
   const webDist = resolveWebDist()
   const readyFile = backend.readyFile ? makeDashboardReadyFile() : null
 
-  rememberLog(`Starting Hermes backend for profile "${profile}" via ${backend.label}`)
+  rememberLog(`Starting Hermes backend for profile "${profile}" via ${backend.label} (reason ${reason})`)
 
   const child = spawn(
     backend.command,
@@ -8597,7 +8666,7 @@ function createWindow() {
   // shared (backendConnectionState), so the renderer's getConnection() joins
   // this in-flight boot instead of duplicating it; early boot-progress events
   // the renderer misses are recovered by its getBootProgress() pull on mount.
-  startHermes().catch(error => rememberLog(error.stack || error.message))
+  ensureBackend(null, 'primary_boot').catch(error => rememberLog(error.stack || error.message))
 
   mainWindow.webContents.once('did-finish-load', () => {
     // Zoom restore is handled by wireCommonWindowHandlers (shared with session
@@ -8607,7 +8676,7 @@ function createWindow() {
   })
 }
 
-ipcMain.handle('hermes:connection', async (_event, profile) => ensureBackend(profile))
+ipcMain.handle('hermes:connection', async (_event, profile, reason) => ensureBackend(profile, reason))
 // Reconnect-after-wake recovery. A REMOTE primary backend has no child process,
 // so the 'exit'/'error' handlers that would clear a dead connection promise never
 // fire — once the remote becomes unreachable across a sleep/wake the renderer
diff --git a/apps/desktop/electron/preload.ts b/apps/desktop/electron/preload.ts
index 7652a7688dd25..69dfd137fbc9f 100644
--- a/apps/desktop/electron/preload.ts
+++ b/apps/desktop/electron/preload.ts
@@ -1,7 +1,7 @@
 import { contextBridge, ipcRenderer, webUtils } from 'electron'
 
 contextBridge.exposeInMainWorld('hermesDesktop', {
-  getConnection: profile => ipcRenderer.invoke('hermes:connection', profile),
+  getConnection: (profile, reason) => ipcRenderer.invoke('hermes:connection', profile, reason),
   revalidateConnection: () => ipcRenderer.invoke('hermes:connection:revalidate'),
   touchBackend: profile => ipcRenderer.invoke('hermes:backend:touch', profile),
   getGatewayWsUrl: profile => ipcRenderer.invoke('hermes:gateway:ws-url', profile),
diff --git a/apps/desktop/electron/profile-backend-startup.test.ts b/apps/desktop/electron/profile-backend-startup.test.ts
new file mode 100644
index 0000000000000..786366effc375
--- /dev/null
+++ b/apps/desktop/electron/profile-backend-startup.test.ts
@@ -0,0 +1,82 @@
+import assert from 'node:assert/strict'
+
+import { test } from 'vitest'
+
+import {
+  createProfileBackendStartupQueue,
+  normalizeProfileBackendStartReason,
+  reusePoolConnection
+} from './profile-backend-startup'
+
+test('serializes concurrent local profile cold starts', async () => {
+  const queue = createProfileBackendStartupQueue()
+  let active = 0
+  let maximumActive = 0
+  let releaseFirst: () => void
+
+  const firstGate = new Promise<void>(resolve => {
+    releaseFirst = resolve
+  })
+
+  let markFirstStarted: () => void
+
+  const firstStarted = new Promise<void>(resolve => {
+    markFirstStarted = resolve
+  })
+
+  const started: string[] = []
+
+  const first = queue.run(async () => {
+    active += 1
+    maximumActive = Math.max(maximumActive, active)
+    started.push('first')
+    markFirstStarted!()
+    await firstGate
+    active -= 1
+
+    return 'first'
+  })
+
+  const second = queue.run(async () => {
+    active += 1
+    maximumActive = Math.max(maximumActive, active)
+    started.push('second')
+    active -= 1
+
+    return 'second'
+  })
+
+  await firstStarted
+  assert.deepEqual(started, ['first'])
+  releaseFirst!()
+  assert.deepEqual(await Promise.all([first, second]), ['first', 'second'])
+  assert.deepEqual(started, ['first', 'second'])
+  assert.equal(maximumActive, 1)
+})
+
+test('a failed local startup releases the next queued profile', async () => {
+  const queue = createProfileBackendStartupQueue()
+
+  const first = queue.run(async () => {
+    throw new Error('profile failed to start')
+  })
+
+  const second = queue.run(async () => 'ready')
+
+  await assert.rejects(first, /profile failed to start/)
+  assert.equal(await second, 'ready')
+})
+
+test('reuses an existing backend promise immediately while another profile starts', async () => {
+  const connection = Promise.resolve({ profile: 'already-running' })
+  const entry = { connectionPromise: connection, lastActiveAt: 1 }
+
+  assert.equal(reusePoolConnection(entry, 99), connection)
+  assert.equal(entry.lastActiveAt, 99)
+})
+
+test('normalizes untrusted renderer start reasons to unknown', () => {
+  assert.equal(normalizeProfileBackendStartReason('profile_activate'), 'profile_activate')
+  assert.equal(normalizeProfileBackendStartReason('not-a-reason'), 'unknown')
+  assert.equal(normalizeProfileBackendStartReason({}), 'unknown')
+})
diff --git a/apps/desktop/electron/profile-backend-startup.ts b/apps/desktop/electron/profile-backend-startup.ts
new file mode 100644
index 0000000000000..b2543bcbb0442
--- /dev/null
+++ b/apps/desktop/electron/profile-backend-startup.ts
@@ -0,0 +1,61 @@
+export type ProfileBackendStartReason = 'primary_boot' | 'profile_activate' | 'background_session' | 'unknown'
+
+const START_REASONS = new Set<ProfileBackendStartReason>([
+  'primary_boot',
+  'profile_activate',
+  'background_session',
+  'unknown'
+])
+
+export function normalizeProfileBackendStartReason(value: unknown): ProfileBackendStartReason {
+  return typeof value === 'string' && START_REASONS.has(value as ProfileBackendStartReason)
+    ? (value as ProfileBackendStartReason)
+    : 'unknown'
+}
+
+/**
+ * Runs local profile backend startup work one at a time. This intentionally
+ * does not own remote connections: they do not spawn a local child or compete
+ * for the machine resources this queue protects.
+ */
+export function createProfileBackendStartupQueue() {
+  let tail: Promise<void> = Promise.resolve()
+
+  return {
+    run<T>(task: () => Promise<T>): Promise<T> {
+      const previous = tail
+      let release: () => void
+
+      tail = new Promise<void>(resolve => {
+        release = resolve
+      })
+
+      return previous
+        .catch(() => undefined)
+        .then(task)
+        .finally(release!)
+    }
+  }
+}
+
+export interface ReusablePoolConnection<T> {
+  connectionPromise: Promise<T>
+  lastActiveAt: number
+}
+
+/**
+ * Keep an existing pool connection on its current path. In particular, do not
+ * make it wait behind a different profile's cold start.
+ */
+export function reusePoolConnection<T>(
+  entry: ReusablePoolConnection<T> | undefined,
+  now = Date.now()
+): Promise<T> | null {
+  if (!entry) {
+    return null
+  }
+
+  entry.lastActiveAt = now
+
+  return entry.connectionPromise
+}
diff --git a/apps/desktop/src/app/chat/sidebar/profile-switcher.tsx b/apps/desktop/src/app/chat/sidebar/profile-switcher.tsx
index 52fa8de19c0af..ba23c8ab44c27 100644
--- a/apps/desktop/src/app/chat/sidebar/profile-switcher.tsx
+++ b/apps/desktop/src/app/chat/sidebar/profile-switcher.tsx
@@ -66,8 +66,6 @@ import { DeleteProfileDialog } from '../../profiles/delete-profile-dialog'
 import { RenameProfileDialog } from '../../profiles/rename-profile-dialog'
 import { PROFILES_ROUTE } from '../../routes'
 
-import { useProfilePrewarm } from './use-profile-prewarm'
-
 const RAIL_GAP = 4 // px — matches gap-1 between squares.
 
 // Past this many profiles the strip of colored squares stops scaling (tiny
@@ -471,14 +469,11 @@ function ProfileDropdown({
   )
 }
 
-// One dropdown row per profile — its own component so each row can own a
-// hover-intent prewarm timer (see useProfilePrewarm).
 function ProfileDropdownItem({ color, name }: { color: null | string; name: string }) {
   const hue = color ?? 'var(--ui-text-quaternary)'
-  const { cancelPrewarm, startPrewarm } = useProfilePrewarm(name)
 
   return (
-    <SelectItem onPointerEnter={startPrewarm} onPointerLeave={cancelPrewarm} value={name}>
+    <SelectItem value={name}>
       <span className="flex min-w-0 items-center gap-1.5">
         <span
           aria-hidden="true"
@@ -560,9 +555,6 @@ function ProfileSquare({
   const [pickerOpen, setPickerOpen] = useState(false)
   const pressTimer = useRef<null | number>(null)
   const suppressClick = useRef(false)
-  // Hovering a square telegraphs the switch — start that profile's backend
-  // spawn now so a cold click doesn't pay the full boot.
-  const { cancelPrewarm, startPrewarm } = useProfilePrewarm(label)
 
   const { attributes, isDragging, listeners, setNodeRef, transform, transition } = useSortable({
     id: label,
@@ -652,11 +644,7 @@ function ProfileSquare({
                         setPickerOpen(true)
                       }, LONG_PRESS_MS)
                     }}
-                    onPointerEnter={startPrewarm}
-                    onPointerLeave={() => {
-                      clearPress()
-                      cancelPrewarm()
-                    }}
+                    onPointerLeave={clearPress}
                     onPointerUp={clearPress}
                   >
                     {label.replace(/[^a-z0-9]/gi, '').charAt(0) || '?'}
diff --git a/apps/desktop/src/app/chat/sidebar/session-row.test.tsx b/apps/desktop/src/app/chat/sidebar/session-row.test.tsx
index 96ddec809148a..c547fe7790844 100644
--- a/apps/desktop/src/app/chat/sidebar/session-row.test.tsx
+++ b/apps/desktop/src/app/chat/sidebar/session-row.test.tsx
@@ -1,4 +1,4 @@
-import { cleanup, render, screen } from '@testing-library/react'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { atom } from 'nanostores'
 import type * as React from 'react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -106,10 +106,6 @@ vi.mock('./session-actions-menu', () => ({
   SessionContextMenu: ({ children }: { children: React.ReactNode }) => <>{children}</>
 }))
 
-vi.mock('./use-profile-prewarm', () => ({
-  useProfilePrewarm: () => ({ cancelPrewarm: vi.fn(), startPrewarm: vi.fn() })
-}))
-
 function makeSession(overrides: Partial<SessionInfo> & { title: string }): SessionInfo {
   return {
     handoff_platform: null,
@@ -127,6 +123,30 @@ const tipTrigger = (el: HTMLElement) => el.closest('[data-slot="tooltip-trigger"
 const noop = vi.fn()
 
 describe('SidebarSessionRow', () => {
+  it('does not resume or start a profile backend when the pointer only hovers a cross-profile row', () => {
+    const onResume = vi.fn()
+
+    const { container } = render(
+      <SidebarSessionRow
+        isPinned={false}
+        isSelected={false}
+        isWorking={false}
+        onArchive={noop}
+        onDelete={noop}
+        onPin={noop}
+        onResume={onResume}
+        session={makeSession({ profile: 'coder', title: 'Other profile session' })}
+      />
+    )
+
+    const row = container.querySelector('.row-hover')
+    expect(row).toBeTruthy()
+    fireEvent.pointerEnter(row as HTMLElement)
+    fireEvent.pointerLeave(row as HTMLElement)
+
+    expect(onResume).not.toHaveBeenCalled()
+  })
+
   it('wires the actions kebab tooltip text through to SessionActionsMenu', () => {
     render(
       <SidebarSessionRow
diff --git a/apps/desktop/src/app/chat/sidebar/session-row.tsx b/apps/desktop/src/app/chat/sidebar/session-row.tsx
index 7b1fb92007b8d..d0300efa314d8 100644
--- a/apps/desktop/src/app/chat/sidebar/session-row.tsx
+++ b/apps/desktop/src/app/chat/sidebar/session-row.tsx
@@ -23,7 +23,6 @@ import { canOpenSessionWindow, openSessionInNewWindow } from '@/store/windows'
 import { SidebarRowBody, SidebarRowGrab, SidebarRowLabel, SidebarRowLead, SidebarRowShell } from './chrome'
 import { SessionActionsMenu, SessionContextMenu } from './session-actions-menu'
 import { type SessionDotState, sessionDotState, sessionShowsRunningArc } from './session-row-state'
-import { useProfilePrewarm } from './use-profile-prewarm'
 
 interface SidebarSessionRowProps extends React.ComponentProps<'div'> {
   session: SessionInfo
@@ -77,7 +76,6 @@ export function SidebarSessionRow({
 }: SidebarSessionRowProps) {
   const { t } = useI18n()
   const r = t.sidebar.row
-  const { cancelPrewarm, startPrewarm } = useProfilePrewarm(session.profile)
   const title = sessionTitle(session)
   const age = formatAge(session.last_active || session.started_at, r)
   const handleLabel = `Reorder ${title}`
@@ -170,12 +168,6 @@ export function SidebarSessionRow({
 
           startSessionDrag({ id: session.id, profile: session.profile || 'default', title }, event)
         }}
-        // Hovering a row from another profile (the all-profiles view) telegraphs
-        // a cross-profile resume — start that backend's spawn now so the click
-        // doesn't pay the full cold boot. Same-profile rows no-op inside
-        // prewarmProfileBackend.
-        onPointerEnter={startPrewarm}
-        onPointerLeave={cancelPrewarm}
         ref={ref}
         style={style}
         {...rest}
diff --git a/apps/desktop/src/app/chat/sidebar/use-profile-prewarm.ts b/apps/desktop/src/app/chat/sidebar/use-profile-prewarm.ts
deleted file mode 100644
index 4aecf5cad5254..0000000000000
--- a/apps/desktop/src/app/chat/sidebar/use-profile-prewarm.ts
+++ /dev/null
@@ -1,38 +0,0 @@
-import { useCallback, useEffect, useRef } from 'react'
-
-import { prewarmProfileBackend } from '@/store/profile'
-
-// Dwell before firing: long enough that sweeping the pointer across the rail
-// or a mixed-profile session list doesn't spawn a backend for every element
-// passed through, short enough to beat the click by hundreds of ms.
-const PREWARM_DWELL_MS = 120
-
-/**
- * pointerenter/pointerleave handlers that pre-warm `profile`'s pool backend
- * after a short hover dwell (see prewarmProfileBackend in store/profile).
- * Consumers merge these with their own pointer handlers.
- */
-export function useProfilePrewarm(profile: string | null | undefined) {
-  const timer = useRef<null | number>(null)
-  const profileRef = useRef(profile)
-  profileRef.current = profile
-
-  const cancelPrewarm = useCallback(() => {
-    if (timer.current != null) {
-      clearTimeout(timer.current)
-      timer.current = null
-    }
-  }, [])
-
-  useEffect(() => cancelPrewarm, [cancelPrewarm])
-
-  const startPrewarm = useCallback(() => {
-    cancelPrewarm()
-    timer.current = window.setTimeout(() => {
-      timer.current = null
-      prewarmProfileBackend(profileRef.current || 'default')
-    }, PREWARM_DWELL_MS)
-  }, [cancelPrewarm])
-
-  return { cancelPrewarm, startPrewarm }
-}
diff --git a/apps/desktop/src/global.d.ts b/apps/desktop/src/global.d.ts
index d9d9af1ee13cc..dfec25ebe7b20 100644
--- a/apps/desktop/src/global.d.ts
+++ b/apps/desktop/src/global.d.ts
@@ -10,12 +10,14 @@ import type {
 export {}
 
 declare global {
+  type HermesConnectionReason = 'primary_boot' | 'profile_activate' | 'background_session' | 'unknown'
+
   interface Window {
     hermesDesktop: {
       // Resolve a backend connection. Omit `profile` (or pass the primary) for
       // the window's backend; pass a named profile to lazily spawn/reuse that
       // profile's backend from the pool.
-      getConnection: (profile?: string | null) => Promise<HermesConnection>
+      getConnection: (profile?: string | null, reason?: HermesConnectionReason) => Promise<HermesConnection>
       // Reconnect-after-wake recovery: liveness-probe the cached PRIMARY backend
       // and drop it if a remote one has gone unreachable, so the next
       // getConnection() rebuilds a reachable descriptor instead of the renderer
diff --git a/apps/desktop/src/store/gateway.ts b/apps/desktop/src/store/gateway.ts
index 9b0f037b2ac6a..4aa56e466b84d 100644
--- a/apps/desktop/src/store/gateway.ts
+++ b/apps/desktop/src/store/gateway.ts
@@ -102,14 +102,14 @@ function clearTimer(entry: Secondary): void {
   }
 }
 
-async function openSecondary(entry: Secondary): Promise<void> {
+async function openSecondary(entry: Secondary, reason: HermesConnectionReason): Promise<void> {
   const desktop = window.hermesDesktop
 
   if (!desktop) {
     return
   }
 
-  const conn = await desktop.getConnection(entry.profile)
+  const conn = await desktop.getConnection(entry.profile, reason)
   const wsUrl = await resolveGatewayWsUrl(desktop, conn)
   await entry.gateway.connect(wsUrl)
   void desktop.touchBackend?.(entry.profile).catch(() => undefined)
@@ -137,7 +137,7 @@ async function reconnectSecondary(entry: Secondary): Promise<void> {
   entry.reconnecting = true
 
   try {
-    await openSecondary(entry)
+    await openSecondary(entry, 'background_session')
     entry.reconnectAttempt = 0
   } catch {
     // Transport failure → fall through to the backoff below.
@@ -181,27 +181,6 @@ function createSecondary(profile: string): Secondary {
   return entry
 }
 
-// Open `profile`'s socket WITHOUT making it active — the hover-intent pre-warm
-// (store/profile). Runs the same spawn + connect chain as a real switch, so by
-// click time ensureGatewayForProfile finds an open socket and just activates
-// it. No scheduleReconnect on failure: a hover is speculative, so a dead
-// backend must not start a background retry loop — the real switch owns retry
-// and error UX. An already-open (or primary) profile is a no-op.
-export async function openGatewayForProfile(profile: string): Promise<void> {
-  const key = normKey(profile)
-
-  if (key === primaryProfile) {
-    return
-  }
-
-  const entry = secondaries.get(key) ?? createSecondary(key)
-  entry.wantOpen = true
-
-  if (!isOpen(entry.gateway)) {
-    await openSecondary(entry)
-  }
-}
-
 // Make `profile` the active gateway, lazily opening its socket if needed. The
 // primary is a no-op fast path. Background sockets are never closed here.
 export async function ensureGatewayForProfile(profile: string): Promise<void> {
@@ -226,7 +205,7 @@ export async function ensureGatewayForProfile(profile: string): Promise<void> {
     entry.reconnectAttempt = 0
 
     try {
-      await openSecondary(entry)
+      await openSecondary(entry, 'profile_activate')
     } catch {
       scheduleReconnect(entry)
     }
diff --git a/apps/desktop/src/store/profile.test.ts b/apps/desktop/src/store/profile.test.ts
index 49d6186a43d0d..bb521654ab171 100644
--- a/apps/desktop/src/store/profile.test.ts
+++ b/apps/desktop/src/store/profile.test.ts
@@ -7,11 +7,10 @@ import type { ProfileInfo } from '@/types/hermes'
 // Keep profile.ts's side-effecting imports inert: the gateway socket layer and
 // the REST query client must not run for real in a unit test.
 const ensureGatewayForProfile = vi.fn(async () => undefined)
-const openGatewayForProfile = vi.fn(async (_profile: string) => undefined)
 const $gateway = atom<unknown>({ id: 'live-socket' })
 const resetStarmapGraph = vi.fn()
 
-vi.mock('@/store/gateway', () => ({ $gateway, ensureGatewayForProfile, openGatewayForProfile }))
+vi.mock('@/store/gateway', () => ({ $gateway, ensureGatewayForProfile }))
 vi.mock('@/hermes', () => ({
   getProfiles: vi.fn(async () => ({ profiles: [] })),
   setApiRequestProfile: vi.fn()
@@ -19,7 +18,7 @@ vi.mock('@/hermes', () => ({
 vi.mock('@/lib/query-client', () => ({ invalidateProfileScopedQueries: vi.fn() }))
 vi.mock('@/store/starmap', () => ({ resetStarmapGraph }))
 
-const { $activeGatewayProfile, $profiles, ensureGatewayProfile, prewarmProfileBackend, refreshProfiles } =
+const { $activeGatewayProfile, $profiles, ensureGatewayProfile, refreshProfiles, selectProfile } =
   await import('./profile')
 
 const { $connection } = await import('./session')
@@ -47,7 +46,6 @@ const getConnection = vi.fn<(profile?: string | null) => Promise<HermesConnectio
 beforeEach(() => {
   getConnection.mockReset()
   ensureGatewayForProfile.mockClear()
-  openGatewayForProfile.mockClear()
   $gateway.set({ id: 'live-socket' })
   $activeGatewayProfile.set('default')
   $connection.set(localConn())
@@ -73,7 +71,7 @@ describe('ensureGatewayProfile → $connection sync (#46651)', () => {
     await ensureGatewayProfile('vps-remote')
 
     expect(ensureGatewayForProfile).toHaveBeenCalledWith('vps-remote')
-    expect(getConnection).toHaveBeenCalledWith('vps-remote')
+    expect(getConnection).toHaveBeenCalledWith('vps-remote', 'profile_activate')
     expect($connection.get()?.mode).toBe('remote')
     expect($connection.get()?.profile).toBe('vps-remote')
   })
@@ -85,7 +83,7 @@ describe('ensureGatewayProfile → $connection sync (#46651)', () => {
 
     await ensureGatewayProfile('default')
 
-    expect(getConnection).toHaveBeenCalledWith('default')
+    expect(getConnection).toHaveBeenCalledWith('default', 'profile_activate')
     expect($connection.get()?.mode).toBe('local')
   })
 
@@ -119,37 +117,11 @@ describe('profile-scoped cache invalidation', () => {
   })
 })
 
-describe('prewarmProfileBackend (hover-intent pool spawn)', () => {
-  it('opens the gateway (spawn + connect, no activation) for a non-active profile', () => {
-    prewarmProfileBackend('warm-basic')
+describe('explicit profile activation', () => {
+  it('starts the target gateway only after an explicit profile selection', async () => {
+    selectProfile('coder')
 
-    expect(openGatewayForProfile).toHaveBeenCalledWith('warm-basic')
-    // Pre-warm must never activate — that's the click's job.
-    expect(ensureGatewayForProfile).not.toHaveBeenCalled()
-  })
-
-  it('skips the profile the gateway is already on', () => {
-    $activeGatewayProfile.set('warm-active')
-
-    prewarmProfileBackend('warm-active')
-
-    expect(openGatewayForProfile).not.toHaveBeenCalled()
-  })
-
-  it('throttles repeat pre-warms for the same profile within the interval', () => {
-    prewarmProfileBackend('warm-throttle-a')
-    prewarmProfileBackend('warm-throttle-a')
-    prewarmProfileBackend('warm-throttle-b')
-
-    const calls = openGatewayForProfile.mock.calls.map(([name]) => name)
-    expect(calls.filter(name => name === 'warm-throttle-a')).toHaveLength(1)
-    expect(calls.filter(name => name === 'warm-throttle-b')).toHaveLength(1)
-  })
-
-  it('swallows spawn failures — error UX belongs to the real switch', () => {
-    openGatewayForProfile.mockRejectedValueOnce(new Error('spawn failed'))
-
-    expect(() => prewarmProfileBackend('warm-failing')).not.toThrow()
+    await vi.waitFor(() => expect(ensureGatewayForProfile).toHaveBeenCalledWith('coder'))
   })
 })
 
diff --git a/apps/desktop/src/store/profile.ts b/apps/desktop/src/store/profile.ts
index c97614884dcab..85d63fb29a870 100644
--- a/apps/desktop/src/store/profile.ts
+++ b/apps/desktop/src/store/profile.ts
@@ -11,7 +11,7 @@ import {
   storedStringArray,
   storedStringRecord
 } from '@/lib/storage'
-import { $gateway, ensureGatewayForProfile, openGatewayForProfile } from '@/store/gateway'
+import { $gateway, ensureGatewayForProfile } from '@/store/gateway'
 import { setConnection } from '@/store/session'
 import { resetStarmapGraph } from '@/store/starmap'
 import type { ProfileInfo } from '@/types/hermes'
@@ -191,39 +191,6 @@ $activeGatewayProfile.subscribe(value => {
 // so a lazy spawn doesn't read as a hang. Single-profile users never swap.
 export const $gatewaySwapTarget = atom<string | null>(null)
 
-// ── Hover-intent backend pre-warm ───────────────────────────────────────────
-// A cold switch to a profile whose pool backend isn't running pays the full
-// spawn (Python boot + port announce + readiness probe — measured ~2.5-3s)
-// plus the socket connect before the sidebar can repopulate. The pointer
-// entering a profile square in the rail signals the switch a few hundred ms
-// before the click lands, so we run the same spawn + connect chain then
-// (openGatewayForProfile — without activating). `ensureBackend` in the
-// Electron main is idempotent (a pooled profile returns its existing
-// connectionPromise), so the real switch joins the in-flight work instead of
-// duplicating it — and a pre-warm for an already-open profile is a no-op.
-// Throttled per profile so drive-by hovers can't spam spawn attempts; failures
-// stay silent here and surface on the real switch, which owns retry/error UX.
-const PREWARM_MIN_INTERVAL_MS = 60_000
-
-const prewarmedAt = new Map<string, number>()
-
-export function prewarmProfileBackend(name: string): void {
-  const key = normalizeProfileKey(name)
-
-  if (key === normalizeProfileKey($activeGatewayProfile.get())) {
-    return
-  }
-
-  const now = Date.now()
-
-  if (now - (prewarmedAt.get(key) ?? 0) < PREWARM_MIN_INTERVAL_MS) {
-    return
-  }
-
-  prewarmedAt.set(key, now)
-  openGatewayForProfile(key).catch(() => undefined)
-}
-
 let gatewaySwitch: Promise<void> | null = null
 
 // Keep the renderer's $connection (mode / baseUrl / profile) in lockstep with
@@ -246,7 +213,7 @@ async function syncConnectionToActiveProfile(profile: string): Promise<void> {
   }
 
   try {
-    setConnection(await getConnection(profile))
+    setConnection(await getConnection(profile, 'profile_activate'))
   } catch {
     // Leave the prior connection in place; boot/reconnect resyncs it later.
   }

From e304e97cc5041f95f879277519768e4ea9f4d1ff Mon Sep 17 00:00:00 2001
From: Hao Wang <haowang@HaodeMac-mini.lan>
Date: Wed, 22 Jul 2026 21:26:12 +0800
Subject: [PATCH 3/4] perf(gateway): bound model discovery and log stalls

---
 apps/desktop/src/app/chat/composer/types.ts   |   7 -
 apps/desktop/src/app/chat/index.tsx           |  24 +-
 apps/desktop/src/lib/chat-runtime.ts          |  71 +----
 hermes_cli/inventory.py                       | 250 +++++++++++++++++-
 hermes_cli/mcp_startup.py                     |  23 +-
 hermes_cli/model_switch.py                    | 198 +++++++++++++-
 hermes_cli/models.py                          |  85 +++---
 hermes_cli/perf_diagnostics.py                | 125 +++++++++
 hermes_cli/web_server.py                      |  66 +++--
 tests/hermes_cli/test_inventory.py            | 175 ++++++++++++
 .../test_inventory_explicit_pruning.py        |  61 +++++
 .../test_model_catalog_concurrency.py         |  77 ++++++
 tests/hermes_cli/test_perf_diagnostics.py     |  34 +++
 tests/test_tui_gateway_server.py              |   5 +-
 tui_gateway/server.py                         |  24 +-
 tui_gateway/ws.py                             |  10 +-
 16 files changed, 1060 insertions(+), 175 deletions(-)
 create mode 100644 hermes_cli/perf_diagnostics.py
 create mode 100644 tests/hermes_cli/test_inventory_explicit_pruning.py
 create mode 100644 tests/hermes_cli/test_model_catalog_concurrency.py
 create mode 100644 tests/hermes_cli/test_perf_diagnostics.py

diff --git a/apps/desktop/src/app/chat/composer/types.ts b/apps/desktop/src/app/chat/composer/types.ts
index 24abcf3736971..e1b1c932ac08b 100644
--- a/apps/desktop/src/app/chat/composer/types.ts
+++ b/apps/desktop/src/app/chat/composer/types.ts
@@ -11,19 +11,12 @@ export interface ContextSuggestion {
   meta?: string
 }
 
-export interface QuickModelOption {
-  provider: string
-  providerName: string
-  model: string
-}
-
 export interface ChatBarState {
   model: {
     model: string
     provider: string
     canSwitch: boolean
     loading?: boolean
-    quickModels?: QuickModelOption[]
     /** Reused status-bar dropdown (built with gateway + selectModel upstream). */
     modelMenuContent?: ReactNode
   }
diff --git a/apps/desktop/src/app/chat/index.tsx b/apps/desktop/src/app/chat/index.tsx
index bd18be0c4834f..20c14f6493ac2 100644
--- a/apps/desktop/src/app/chat/index.tsx
+++ b/apps/desktop/src/app/chat/index.tsx
@@ -1,6 +1,5 @@
 import { type AppendMessage, AssistantRuntimeProvider, type ThreadMessage } from '@assistant-ui/react'
 import { useStore } from '@nanostores/react'
-import { useQuery } from '@tanstack/react-query'
 import type * as React from 'react'
 import { Suspense, useCallback, useEffect, useMemo } from 'react'
 import { useLocation } from 'react-router-dom'
@@ -17,16 +16,15 @@ import { TitleMenuTrigger } from '@/components/ui/title-menu-trigger'
 import { type HermesGateway } from '@/hermes'
 import { useI18n } from '@/i18n'
 import type { ChatMessage } from '@/lib/chat-messages'
-import { quickModelOptions, sessionTitle } from '@/lib/chat-runtime'
+import { sessionTitle } from '@/lib/chat-runtime'
 import { useIncrementalExternalStoreRuntime } from '@/lib/incremental-external-store-runtime'
-import { modelOptionsQueryKey, requestModelOptions } from '@/lib/model-options'
 import { cn } from '@/lib/utils'
 import { migrateSessionDraft } from '@/store/composer'
 import { migrateQueuedPrompts, parkQueuedPrompts } from '@/store/composer-queue'
 import { $pinnedSessionIds } from '@/store/layout'
 import { $petActive } from '@/store/pet'
 import { $petOverlayActive } from '@/store/pet-overlay'
-import { $activeGatewayProfile, $gatewaySwapTarget, $profiles } from '@/store/profile'
+import { $gatewaySwapTarget, $profiles } from '@/store/profile'
 import {
   $contextSuggestions,
   $freshDraftReady,
@@ -40,7 +38,6 @@ import {
   sessionPinId
 } from '@/store/session'
 import { isSecondaryWindow, isWatchWindow } from '@/store/windows'
-import type { ModelOptionsResponse } from '@/types/hermes'
 
 import { routeSessionId } from '../routes'
 import { titlebarHeaderBaseClass, titlebarHeaderShadowClass, titlebarHeaderTitleClass } from '../shell/titlebar'
@@ -255,7 +252,6 @@ export function ChatView({
   const sessionAnchor = isPrimary ? 'workspace' : `session-tile:${storedId ?? ''}`
   const awaitingResponse = useStore(view.$awaitingResponse)
   const busy = useStore(view.$busy)
-  const activeGatewayProfile = useStore($activeGatewayProfile)
   const contextSuggestions = useStore($contextSuggestions)
   // Per-session (SessionView) reads — a tile IS its session, so these come
   // from the view slice, not the global atoms (which track the primary only).
@@ -357,17 +353,6 @@ export function ChatView({
   const showChatBar = !loadingSession && !resumeExhausted && !isWatchWindow()
   const threadKey = selectedSessionId || activeSessionId || (isRoutedSessionView ? location.pathname : 'new')
 
-  const modelOptionsQuery = useQuery<ModelOptionsResponse>({
-    queryKey: modelOptionsQueryKey(activeGatewayProfile, activeSessionId),
-    queryFn: () => requestModelOptions({ gateway: gateway || undefined, sessionId: activeSessionId }),
-    enabled: gatewayOpen
-  })
-
-  const quickModels = useMemo(
-    () => quickModelOptions(modelOptionsQuery.data, currentProvider, currentModel),
-    [currentModel, currentProvider, modelOptionsQuery.data]
-  )
-
   const chatBarState = useMemo<ChatBarState>(
     () => ({
       model: {
@@ -375,8 +360,7 @@ export function ChatView({
         provider: currentProvider,
         canSwitch: gatewayOpen,
         loading: !gatewayOpen || (!currentModel && !currentProvider),
-        modelMenuContent,
-        quickModels
+        modelMenuContent
       },
       tools: {
         enabled: true,
@@ -388,7 +372,7 @@ export function ChatView({
         active: false
       }
     }),
-    [contextSuggestions, currentModel, currentProvider, gatewayOpen, modelMenuContent, quickModels]
+    [contextSuggestions, currentModel, currentProvider, gatewayOpen, modelMenuContent]
   )
 
   // Drop files anywhere in the conversation area, not just on the composer
diff --git a/apps/desktop/src/lib/chat-runtime.ts b/apps/desktop/src/lib/chat-runtime.ts
index 775961d9546b7..f7cdcaa4cf987 100644
--- a/apps/desktop/src/lib/chat-runtime.ts
+++ b/apps/desktop/src/lib/chat-runtime.ts
@@ -1,12 +1,11 @@
 import type { ThreadMessage } from '@assistant-ui/react'
 
-import type { QuickModelOption } from '@/app/chat/composer/types'
 import type { ClientSessionState, CommandDispatchResponse } from '@/app/types'
 import { formatRefValue } from '@/components/assistant-ui/directive-text'
 import { type ChatMessage, type ChatMessagePart, chatMessageText, textPart } from '@/lib/chat-messages'
 import { normalize } from '@/lib/text'
 import type { ComposerAttachment } from '@/store/composer'
-import type { ModelOptionsResponse, SessionInfo } from '@/types/hermes'
+import type { SessionInfo } from '@/types/hermes'
 
 export const SLASH_COMMAND_RE = /^\/[^\s/]*(?:\s|$)/
 export const BUILTIN_PERSONALITIES = [
@@ -267,74 +266,6 @@ export function parseCommandDispatch(raw: unknown): CommandDispatchResponse | nu
   }
 }
 
-export function quickModelOptions(
-  data: ModelOptionsResponse | undefined,
-  currentProvider: string,
-  currentModel: string
-): QuickModelOption[] {
-  const seen = new Set<string>()
-  const options: QuickModelOption[] = []
-
-  const providers = [...(data?.providers ?? [])].sort((a, b) => {
-    if (a.slug === currentProvider) {
-      return -1
-    }
-
-    if (b.slug === currentProvider) {
-      return 1
-    }
-
-    if (a.is_current) {
-      return -1
-    }
-
-    if (b.is_current) {
-      return 1
-    }
-
-    return 0
-  })
-
-  const add = (provider: string, providerName: string, model: string) => {
-    const key = `${provider}:${model}`
-
-    if (!model || seen.has(key)) {
-      return
-    }
-
-    seen.add(key)
-    options.push({ provider, providerName, model })
-  }
-
-  if (currentProvider && currentModel) {
-    add(currentProvider, currentProvider, currentModel)
-  }
-
-  for (const provider of providers) {
-    const models = [...(provider.models ?? [])].sort((a, b) => {
-      if (provider.slug === currentProvider && a === currentModel) {
-        return -1
-      }
-
-      if (provider.slug === currentProvider && b === currentModel) {
-        return 1
-      }
-
-      return 0
-    })
-
-    for (const model of models) {
-      add(provider.slug, provider.name, model)
-    }
-
-    if (options.length >= 8) {
-      break
-    }
-  }
-
-  return options.slice(0, 8)
-}
-
 export function toRuntimeMessage(message: ChatMessage): ThreadMessage {
   const role =
     message.role === 'user' || message.role === 'assistant' || message.role === 'system' ? message.role : 'assistant'
diff --git a/hermes_cli/inventory.py b/hermes_cli/inventory.py
index cd9817bb5a1b0..50fc7bdad2c7c 100644
--- a/hermes_cli/inventory.py
+++ b/hermes_cli/inventory.py
@@ -33,8 +33,28 @@
 
 from __future__ import annotations
 
+from collections import OrderedDict
+from concurrent.futures import Future
+import copy
 from dataclasses import dataclass, replace
-from typing import Optional
+import hashlib
+import json
+import logging
+import os
+from pathlib import Path
+import threading
+import time
+from typing import Any, Optional
+
+
+logger = logging.getLogger(__name__)
+
+_MODELS_PAYLOAD_CACHE_TTL_S = 60.0
+_MODELS_PAYLOAD_CACHE_MAX_ENTRIES = 64
+_models_payload_cache: OrderedDict[tuple, tuple[float, dict]] = OrderedDict()
+_models_payload_inflight: dict[tuple, Future] = {}
+_models_payload_cache_lock = threading.RLock()
+_models_payload_refresh_epoch = 0
 
 
 # ─── Public types ───────────────────────────────────────────────────────
@@ -183,6 +203,7 @@ def build_models_payload(
         probe_custom_providers=probe_custom_providers,
         probe_current_custom_provider=probe_current_custom_provider,
         excluded_providers=ctx.excluded_providers or [],
+        explicit_only=explicit_only,
     )
 
     moa_row = _moa_provider_row(ctx.current_provider)
@@ -263,6 +284,233 @@ def build_models_payload(
     }
 
 
+# ─── Public: short-lived picker payload cache ──────────────────────────
+
+
+def build_cached_models_payload(
+    ctx: ConfigContext,
+    *,
+    explicit_only: bool = False,
+    include_unconfigured: bool = False,
+    picker_hints: bool = False,
+    canonical_order: bool = False,
+    pricing: bool = False,
+    capabilities: bool = False,
+    force_fresh_nous_tier: bool = False,
+    refresh: bool = False,
+    probe_custom_providers: bool = True,
+    probe_current_custom_provider: bool = False,
+    max_models: int | None = None,
+) -> dict:
+    """Build a picker payload with a process-local, 60-second response cache.
+
+    ``build_models_payload`` deliberately remains the uncached construction
+    primitive for CLI and tests.  Desktop/TUI picker requests use this wrapper
+    so concurrent opens share one provider discovery run.  Cache keys include
+    the complete context, all builder flags, and file/environment generations
+    that can change authentication or catalog output.
+    """
+    flags = {
+        "explicit_only": explicit_only,
+        "include_unconfigured": include_unconfigured,
+        "picker_hints": picker_hints,
+        "canonical_order": canonical_order,
+        "pricing": pricing,
+        "capabilities": capabilities,
+        "force_fresh_nous_tier": force_fresh_nous_tier,
+        "refresh": refresh,
+        "probe_custom_providers": probe_custom_providers,
+        "probe_current_custom_provider": probe_current_custom_provider,
+        "max_models": max_models,
+    }
+    global _models_payload_refresh_epoch
+
+    started = time.monotonic()
+    generation = _models_payload_generation()
+
+    with _models_payload_cache_lock:
+        if refresh:
+            # An explicit refresh must never return a previous payload.  Clear
+            # every context variant because the provider-model cache is itself
+            # refreshed below and can affect any picker shape.
+            _models_payload_refresh_epoch += 1
+            _models_payload_cache.clear()
+        request_epoch = _models_payload_refresh_epoch
+        key = _models_payload_cache_key(ctx, flags, generation, request_epoch)
+
+        if not refresh:
+            cached = _models_payload_cache.get(key)
+            if cached is not None:
+                cached_at, payload = cached
+                if time.monotonic() - cached_at < _MODELS_PAYLOAD_CACHE_TTL_S:
+                    _models_payload_cache.move_to_end(key)
+                    _log_models_payload_cache("hit", started, payload)
+                    return copy.deepcopy(payload)
+                del _models_payload_cache[key]
+
+        future = _models_payload_inflight.get(key)
+        if future is None:
+            future = Future()
+            _models_payload_inflight[key] = future
+            owner = True
+        else:
+            owner = False
+
+    if not owner:
+        try:
+            payload = future.result()
+        except BaseException:
+            _log_models_payload_cache("wait", started, None)
+            raise
+        _log_models_payload_cache("wait", started, payload)
+        return copy.deepcopy(payload)
+
+    try:
+        payload = build_models_payload(ctx, **flags)
+        stored_payload = copy.deepcopy(payload)
+        # Provider discovery can atomically rewrite provider/cache files.  Use
+        # the post-build generation when storing so the very next normal open
+        # is a hit instead of being invalidated by this request's own work.
+        final_generation = _models_payload_generation()
+        with _models_payload_cache_lock:
+            # A refresh that started after this request owns the new cache
+            # generation. Do not let an older, slower build overwrite it.
+            if request_epoch == _models_payload_refresh_epoch:
+                final_key = _models_payload_cache_key(
+                    ctx, flags, final_generation, request_epoch
+                )
+                _store_models_payload_cache(final_key, stored_payload)
+                if refresh:
+                    # Refresh is a distinct behavior flag, but its freshly-built
+                    # output is also the correct warm result for the equivalent
+                    # normal request.  Preserve flag-complete keys for both forms.
+                    normal_flags = dict(flags, refresh=False)
+                    _store_models_payload_cache(
+                        _models_payload_cache_key(
+                            ctx, normal_flags, final_generation, request_epoch
+                        ),
+                        stored_payload,
+                    )
+            future.set_result(stored_payload)
+        _log_models_payload_cache("miss", started, stored_payload)
+        return copy.deepcopy(stored_payload)
+    except BaseException as exc:
+        with _models_payload_cache_lock:
+            future.set_exception(exc)
+        _log_models_payload_cache("miss", started, None)
+        raise
+    finally:
+        with _models_payload_cache_lock:
+            if _models_payload_inflight.get(key) is future:
+                del _models_payload_inflight[key]
+
+
+def _store_models_payload_cache(key: tuple, payload: dict) -> None:
+    _models_payload_cache[key] = (time.monotonic(), copy.deepcopy(payload))
+    _models_payload_cache.move_to_end(key)
+    while len(_models_payload_cache) > _MODELS_PAYLOAD_CACHE_MAX_ENTRIES:
+        _models_payload_cache.popitem(last=False)
+
+
+def _models_payload_cache_key(
+    ctx: ConfigContext,
+    flags: dict[str, Any],
+    generation: tuple,
+    refresh_epoch: int,
+) -> tuple:
+    return (
+        _stable_digest({
+            "context": {
+                "current_provider": ctx.current_provider,
+                "current_model": ctx.current_model,
+                "current_base_url": ctx.current_base_url,
+                "user_providers": ctx.user_providers,
+                "custom_providers": ctx.custom_providers,
+                "excluded_providers": ctx.excluded_providers,
+            },
+            "flags": flags,
+        }),
+        generation,
+        refresh_epoch,
+    )
+
+
+def _models_payload_generation() -> tuple:
+    """Return non-secret file/environment generations used by the picker.
+
+    This mirrors the credential/cache inputs used by provider discovery without
+    reading credential contents into logs or cache keys.
+    """
+    from hermes_cli.config import get_config_path, get_env_path, get_hermes_home
+
+    home = get_hermes_home()
+    paths = {
+        "config": get_config_path(),
+        "dotenv": get_env_path(),
+        "auth": home / "auth.json",
+        "credentials": home / "credentials.json",
+        "provider_models": home / "provider_models_cache.json",
+        "models_dev": home / "models_dev_cache.json",
+        "ollama_cloud": home / "ollama_cloud_models_cache.json",
+        "model_catalog": home / "cache" / "model_catalog.json",
+        "nous_recommended": home / "cache" / "nous_recommended_cache.json",
+        "codex_auth": Path(os.path.expanduser("~/.codex/auth.json")),
+        "claude_credentials": Path(os.path.expanduser("~/.claude/.credentials.json")),
+        "copilot_hosts": Path(os.path.expanduser("~/.config/github-copilot/hosts.json")),
+        "minimax_credentials": Path(os.path.expanduser("~/.minimax/credentials.json")),
+    }
+    file_generation = tuple(
+        (name, _path_generation(path)) for name, path in sorted(paths.items())
+    )
+    return file_generation + (("credential_env", _credential_environment_generation()),)
+
+
+def _path_generation(path: Path) -> tuple[int | None, int | None]:
+    try:
+        stat = path.stat()
+        return stat.st_mtime_ns, stat.st_size
+    except OSError:
+        return None, None
+
+
+def _credential_environment_generation() -> str:
+    """Fingerprint provider credential-related environment values privately."""
+    names: set[str] = set()
+    try:
+        from hermes_cli.auth import PROVIDER_REGISTRY
+
+        for provider in PROVIDER_REGISTRY.values():
+            names.update(getattr(provider, "api_key_env_vars", ()) or ())
+            base_url_env = getattr(provider, "base_url_env_var", "") or ""
+            if base_url_env:
+                names.add(base_url_env)
+    except Exception:
+        pass
+    return _stable_digest({name: os.environ.get(name, "") for name in sorted(names)})
+
+
+def _stable_digest(value: Any) -> str:
+    encoded = json.dumps(
+        value,
+        sort_keys=True,
+        separators=(",", ":"),
+        default=repr,
+    ).encode("utf-8", errors="replace")
+    return hashlib.blake2b(encoded, digest_size=16).hexdigest()
+
+
+def _log_models_payload_cache(
+    cache: str, started: float, payload: dict | None
+) -> None:
+    provider_count = len(payload.get("providers") or []) if payload else 0
+    logger.info(
+        "model_inventory cache=%s total_ms=%.1f provider_count=%d",
+        cache,
+        (time.monotonic() - started) * 1000,
+        provider_count,
+    )
+
+
 def _apply_capabilities(rows: list[dict]) -> None:
     """Attach a ``{model: {fast, reasoning}}`` map to each provider row.
 
diff --git a/hermes_cli/mcp_startup.py b/hermes_cli/mcp_startup.py
index a8744161d5636..693c4f3d00152 100644
--- a/hermes_cli/mcp_startup.py
+++ b/hermes_cli/mcp_startup.py
@@ -60,16 +60,19 @@ def start_background_mcp_discovery(*, logger, thread_name: str) -> None:
 
         def _discover() -> None:
             try:
-                _discover_mcp_tools_without_interactive_oauth()
-                try:
-                    from tools.mcp_tool import get_mcp_status
-                    status = get_mcp_status() or []
-                    if not any(entry.get("connected") for entry in status):
-                        logger.warning(
-                            "Background MCP discovery completed with zero connected servers"
-                        )
-                except Exception:
-                    logger.debug("Failed to inspect MCP status after background discovery", exc_info=True)
+                from hermes_cli.perf_diagnostics import track_activity
+
+                with track_activity("background", "mcp.discovery"):
+                    _discover_mcp_tools_without_interactive_oauth()
+                    try:
+                        from tools.mcp_tool import get_mcp_status
+                        status = get_mcp_status() or []
+                        if not any(entry.get("connected") for entry in status):
+                            logger.warning(
+                                "Background MCP discovery completed with zero connected servers"
+                            )
+                    except Exception:
+                        logger.debug("Failed to inspect MCP status after background discovery", exc_info=True)
             except Exception:
                 logger.debug("Background MCP tool discovery failed", exc_info=True)
             finally:
diff --git a/hermes_cli/model_switch.py b/hermes_cli/model_switch.py
index fa83973622a8c..659b0fd604958 100644
--- a/hermes_cli/model_switch.py
+++ b/hermes_cli/model_switch.py
@@ -22,8 +22,9 @@
 
 import logging
 import re
+from concurrent.futures import Future, ThreadPoolExecutor
 from dataclasses import dataclass
-from typing import Any, List, NamedTuple, Optional
+from typing import Any, Callable, List, NamedTuple, Optional
 
 from hermes_cli.providers import (
     ProviderDef,
@@ -1588,6 +1589,44 @@ def switch_model(
 _picker_prewarm_done = _threading.Event()
 
 
+class _BoundedProviderCatalogLoader:
+    """Prefetch independent provider catalogs with a small fixed worker cap."""
+
+    def __init__(
+        self,
+        fetch: Callable[[str], list[str]],
+        *,
+        max_workers: int = 4,
+    ) -> None:
+        self._fetch = fetch
+        self._max_workers = max(1, max_workers)
+        self._executor: ThreadPoolExecutor | None = None
+        self._futures: dict[str, Future[list[str]]] = {}
+
+    def prefetch(self, providers: list[str]) -> None:
+        unique = list(dict.fromkeys(provider for provider in providers if provider))
+        if not unique:
+            return
+
+        self._executor = ThreadPoolExecutor(
+            max_workers=min(self._max_workers, len(unique)),
+            thread_name_prefix="model-catalog",
+        )
+        for provider in unique:
+            self._futures[provider] = self._executor.submit(self._fetch, provider)
+
+    def get(self, provider: str) -> list[str]:
+        future = self._futures.get(provider)
+        if future is None:
+            return self._fetch(provider)
+        return future.result()
+
+    def close(self) -> None:
+        if self._executor is not None:
+            self._executor.shutdown(wait=True)
+            self._executor = None
+
+
 def _credential_pool_is_usable(provider: str, *, raw_pool_present: bool = False) -> bool:
     """Return whether *provider* has a credential that can be selected now.
 
@@ -1677,6 +1716,7 @@ def list_authenticated_providers(
     probe_current_custom_provider: bool = False,
     for_picker: bool = False,
     excluded_providers: list | None = None,
+    explicit_only: bool = False,
 ) -> List[dict]:
     """Detect which providers have credentials and list their curated models.
 
@@ -1713,6 +1753,11 @@ def list_authenticated_providers(
     opens: probe only the currently-selected custom endpoint so its model list
     matches the active provider without blocking on every saved/offline custom
     endpoint.
+
+    ``explicit_only`` prunes ambient providers *before* credential/catalog
+    discovery.  The payload builder still applies its row-level filter as a
+    defence in depth, but expensive live model discovery must never run for a
+    provider that the configured-only Desktop picker will discard.
     """
     import os
     from agent.models_dev import (
@@ -1744,6 +1789,62 @@ def list_authenticated_providers(
     _current_provider_norm = str(current_provider or "").strip().lower()
     _current_base_url_norm = str(current_base_url or "").strip().rstrip("/").lower()
 
+    _configured_provider_slugs = {
+        str(slug or "").strip().lower()
+        for slug in (user_providers or {})
+        if str(slug or "").strip()
+    }
+    for row in custom_providers or []:
+        if not isinstance(row, dict):
+            continue
+        for candidate in (
+            row.get("slug"),
+            row.get("provider"),
+            custom_provider_slug(str(row.get("name") or "")),
+        ):
+            normalized = str(candidate or "").strip().lower()
+            if normalized:
+                _configured_provider_slugs.add(normalized)
+
+    _explicit_config_cache: dict[str, bool] = {}
+
+    def _explicit_provider_allowed(*slugs: str) -> bool:
+        if not explicit_only:
+            return True
+
+        normalized = {
+            str(slug or "").strip().lower()
+            for slug in slugs
+            if str(slug or "").strip()
+        }
+        if not normalized:
+            return False
+        if _current_provider_norm and _current_provider_norm in normalized:
+            return True
+        if normalized & _configured_provider_slugs:
+            return True
+
+        from hermes_cli.auth import is_provider_explicitly_configured
+
+        for slug in normalized:
+            allowed = _explicit_config_cache.get(slug)
+            if allowed is None:
+                allowed = bool(is_provider_explicitly_configured(slug))
+                _explicit_config_cache[slug] = allowed
+            if allowed:
+                return True
+        return False
+
+    _models_dev_data_cache: dict = {}
+    _models_dev_data_loaded = False
+
+    def _models_dev_data() -> dict:
+        nonlocal _models_dev_data_cache, _models_dev_data_loaded
+        if not _models_dev_data_loaded:
+            _models_dev_data_cache = fetch_models_dev()
+            _models_dev_data_loaded = True
+        return _models_dev_data_cache
+
     def _can_probe_custom_provider(*, row_is_current: bool) -> bool:
         return bool(probe_custom_providers or (probe_current_custom_provider and row_is_current))
 
@@ -1823,7 +1924,69 @@ def _has_aws_sdk_creds_for_listing(slug: str) -> bool:
         except Exception:
             return False
 
-    data = fetch_models_dev()
+    # Provider catalog requests are independent HTTP calls. Start the subset
+    # with a concrete local credential/config signal together, then consume
+    # their futures in the existing deterministic section order below.
+    from hermes_cli.models import CANONICAL_PROVIDERS as _prefetch_canonical
+    from hermes_cli.providers import HERMES_OVERLAYS as _prefetch_overlays
+
+    _prefetch_store_slugs: set[str] = set()
+    try:
+        from hermes_cli.auth import _load_auth_store as _load_prefetch_auth_store
+
+        _prefetch_store = _load_prefetch_auth_store() or {}
+        _prefetch_store_slugs.update(
+            str(slug).strip().lower()
+            for slug in (_prefetch_store.get("providers") or {})
+            if str(slug).strip()
+        )
+        _prefetch_store_slugs.update(
+            str(slug).strip().lower()
+            for slug in (_prefetch_store.get("credential_pool") or {})
+            if str(slug).strip()
+        )
+    except Exception:
+        pass
+
+    _prefetch_signal_slugs = set(_configured_provider_slugs)
+    if _current_provider_norm:
+        _prefetch_signal_slugs.add(_current_provider_norm)
+    _prefetch_signal_slugs.update(_prefetch_store_slugs)
+    for _slug, _config in PROVIDER_REGISTRY.items():
+        if any(os.environ.get(name) for name in (_config.api_key_env_vars or ())):
+            _prefetch_signal_slugs.add(str(_slug).strip().lower())
+    for _pid, _overlay in _prefetch_overlays.items():
+        if any(os.environ.get(name) for name in (_overlay.extra_env_vars or ())):
+            _prefetch_signal_slugs.add(str(_pid).strip().lower())
+
+    _prefetch_mdev_to_hermes = {
+        value: key for key, value in PROVIDER_TO_MODELS_DEV.items()
+    }
+    _prefetch_known_slugs = set(PROVIDER_TO_MODELS_DEV)
+    _prefetch_known_slugs.update(
+        _prefetch_mdev_to_hermes.get(pid, pid) for pid in _prefetch_overlays
+    )
+    _prefetch_known_slugs.update(provider.slug for provider in _prefetch_canonical)
+    _prefetch_skip = {"lmstudio", "nous", "ollama-cloud"}
+    _prefetch_providers = [
+        slug
+        for slug in sorted(_prefetch_known_slugs)
+        if slug not in _prefetch_skip
+        and slug.lower() not in _excluded
+        and _explicit_provider_allowed(slug)
+        and (
+            slug.lower() in _prefetch_signal_slugs
+            or any(
+                PROVIDER_TO_MODELS_DEV.get(slug) == signaled
+                for signaled in _prefetch_signal_slugs
+            )
+        )
+    ]
+    _catalog_loader = _BoundedProviderCatalogLoader(
+        cached_provider_model_ids,
+        max_workers=4,
+    )
+    _catalog_loader.prefetch(_prefetch_providers)
 
     # Build curated model lists keyed by hermes provider ID
     curated: dict[str, list[str]] = dict(_PROVIDER_MODELS)
@@ -1833,9 +1996,10 @@ def _has_aws_sdk_creds_for_listing(slug: str) -> bool:
     # newly added Portal models surface in the /model picker without
     # requiring a Hermes release. Falls back to the in-repo
     # _PROVIDER_MODELS["nous"] snapshot when the manifest is unreachable.
-    curated["nous"] = get_curated_nous_model_ids()
+    if _explicit_provider_allowed("nous"):
+        curated["nous"] = get_curated_nous_model_ids()
     # Ollama Cloud uses dynamic discovery (no static curated list)
-    if "ollama-cloud" not in curated:
+    if "ollama-cloud" not in curated and _explicit_provider_allowed("ollama-cloud"):
         from hermes_cli.models import fetch_ollama_cloud_models
         curated["ollama-cloud"] = fetch_ollama_cloud_models()
     # LM Studio has no static catalog — probe its native /api/v1/models
@@ -1904,6 +2068,9 @@ def _has_aws_sdk_creds_for_listing(slug: str) -> bool:
         if _canonical != hermes_id:
             continue
 
+        if not _explicit_provider_allowed(hermes_id, mdev_id, _canonical):
+            continue
+
         # Skip duplicates: another entry with the same slug was already
         # emitted (e.g. two PROVIDER_TO_MODELS_DEV entries routing to the
         # same hermes_id).  Distinct canonical profiles that share a
@@ -1914,9 +2081,6 @@ def _has_aws_sdk_creds_for_listing(slug: str) -> bool:
             continue
         if hermes_id.lower() in _excluded or mdev_id.lower() in _excluded:
             continue
-        pdata = data.get(mdev_id)
-        if not isinstance(pdata, dict):
-            continue
 
         # Prefer auth.py PROVIDER_REGISTRY for env var names — it's our
         # source of truth.  models.dev can have wrong mappings (e.g.
@@ -1926,6 +2090,9 @@ def _has_aws_sdk_creds_for_listing(slug: str) -> bool:
         # section 2 (HERMES_OVERLAYS) with proper auth store checking.
         if pconfig and pconfig.auth_type != "api_key":
             continue
+        pdata = _models_dev_data().get(mdev_id)
+        if not isinstance(pdata, dict):
+            continue
         # models.dev catalogs include providers Hermes may not route yet.
         # Gate on runtime capability rather than registry membership: special
         # providers and plugin aliases can be routable without a registry row.
@@ -1961,7 +2128,7 @@ def _has_aws_sdk_creds_for_listing(slug: str) -> bool:
         # /model picker sees the SAME list `hermes model` would build, with
         # disk caching to keep the picker open snappy. Falls back to the
         # curated static list when the live fetcher returns nothing.
-        model_ids = cached_provider_model_ids(hermes_id)
+        model_ids = _catalog_loader.get(hermes_id)
         if not model_ids:
             model_ids = curated.get(hermes_id, [])
             if hermes_id in _MODELS_DEV_PREFERRED:
@@ -2019,6 +2186,8 @@ def _has_aws_sdk_creds_for_listing(slug: str) -> bool:
             continue
         if pid.lower() in _excluded or hermes_slug.lower() in _excluded:
             continue
+        if not _explicit_provider_allowed(pid, hermes_slug):
+            continue
 
         # Check if credentials exist
         has_creds = False
@@ -2102,12 +2271,12 @@ def _has_aws_sdk_creds_for_listing(slug: str) -> bool:
             # catalog. ``cached_provider_model_ids()`` falls back to the
             # curated list when the live endpoint is unreachable, so this
             # is safe for unauthenticated and offline cases too.
-            model_ids = cached_provider_model_ids(hermes_slug)
+            model_ids = _catalog_loader.get(hermes_slug)
         # For aws_sdk providers (bedrock), use live discovery so the list
         # reflects the active region (eu.*, ap.*) not the static us.* list.
         elif overlay.auth_type == "aws_sdk":
             try:
-                _ids = cached_provider_model_ids(hermes_slug)
+                _ids = _catalog_loader.get(hermes_slug)
                 model_ids = _ids if _ids else (curated.get(hermes_slug, []) or curated.get(pid, []))
             except Exception:
                 model_ids = curated.get(hermes_slug, []) or curated.get(pid, [])
@@ -2152,7 +2321,7 @@ def _has_aws_sdk_creds_for_listing(slug: str) -> bool:
             # Unified pathway — see Section 1 rationale. Fall back to the
             # curated dict (with models.dev merge for preferred providers)
             # when the live fetcher comes up empty.
-            model_ids = cached_provider_model_ids(hermes_slug)
+            model_ids = _catalog_loader.get(hermes_slug)
             if not model_ids:
                 model_ids = curated.get(hermes_slug, []) or curated.get(pid, [])
                 if hermes_slug in _MODELS_DEV_PREFERRED:
@@ -2190,6 +2359,8 @@ def _has_aws_sdk_creds_for_listing(slug: str) -> bool:
             continue
         if _cp.slug.lower() in _excluded:
             continue
+        if not _explicit_provider_allowed(_cp.slug):
+            continue
 
         # Check credentials via PROVIDER_REGISTRY (auth.py)
         _cp_config = _auth_registry.get(_cp.slug)
@@ -2226,13 +2397,13 @@ def _has_aws_sdk_creds_for_listing(slug: str) -> bool:
         # region (eu.*, us.*, ap.*) instead of the hardcoded us.* static list.
         if _cp_config and getattr(_cp_config, "auth_type", "") == "aws_sdk":
             try:
-                _ids = cached_provider_model_ids(_cp.slug)
+                _ids = _catalog_loader.get(_cp.slug)
                 _cp_model_ids = _ids if _ids else curated.get(_cp.slug, [])
             except Exception:
                 _cp_model_ids = curated.get(_cp.slug, [])
         else:
             # Unified pathway — same as sections 1 and 2.
-            _cp_model_ids = cached_provider_model_ids(_cp.slug)
+            _cp_model_ids = _catalog_loader.get(_cp.slug)
             if not _cp_model_ids:
                 _cp_model_ids = curated.get(_cp.slug, [])
         _cp_total = len(_cp_model_ids)
@@ -2787,6 +2958,7 @@ def _has_aws_sdk_creds_for_listing(slug: str) -> bool:
     # Sort: current provider first, then by model count descending
     results.sort(key=lambda r: (not r["is_current"], -r["total_models"]))
 
+    _catalog_loader.close()
     return results
 
 
diff --git a/hermes_cli/models.py b/hermes_cli/models.py
index dbb14e05f684d..41e129cf690f4 100644
--- a/hermes_cli/models.py
+++ b/hermes_cli/models.py
@@ -8,12 +8,14 @@
 from __future__ import annotations
 
 import json
+import logging
 import os
 import re
 import urllib.parse
 import urllib.request
 import urllib.error
 import time
+import threading
 from difflib import get_close_matches
 from pathlib import Path
 from typing import Any, NamedTuple, Optional
@@ -21,6 +23,8 @@
 from hermes_cli import __version__ as _HERMES_VERSION
 from hermes_cli.urllib_security import open_credentialed_url
 
+logger = logging.getLogger(__name__)
+
 # Identify ourselves so endpoints fronted by Cloudflare's Browser Integrity
 # Check (error 1010) don't reject the default ``Python-urllib/*`` signature.
 _HERMES_USER_AGENT = f"hermes-cli/{_HERMES_VERSION}"
@@ -2691,6 +2695,7 @@ def provider_model_ids(provider: Optional[str], *, force_refresh: bool = False)
 #     to a live fetch — the picker keeps working.
 
 _PROVIDER_MODELS_CACHE_TTL = 3600  # 1h
+_provider_models_cache_lock = threading.RLock()
 
 
 def _provider_models_cache_path() -> Path:
@@ -2804,35 +2809,52 @@ def cached_provider_model_ids(
     Hits the cache when fresh; otherwise calls the live function and
     persists a non-empty result. Always returns a list (never None).
     """
+    started = time.monotonic()
     normalized = normalize_provider(provider) or (provider or "")
+
+    def _finish(status: str, models: list[str]) -> list[str]:
+        logger.info(
+            "model catalog provider=%s cache=%s duration_ms=%.1f models=%d",
+            normalized or "unknown",
+            status,
+            (time.monotonic() - started) * 1000,
+            len(models),
+        )
+        return models
+
     if not normalized:
-        return []
+        return _finish("invalid", [])
 
-    cache = _load_provider_models_cache()
     fp = _credential_fingerprint(normalized)
-    entry = cache.get(normalized)
     now = time.time()
+    with _provider_models_cache_lock:
+        cache = _load_provider_models_cache()
+        entry = cache.get(normalized)
 
-    if (
-        not force_refresh
-        and isinstance(entry, dict)
-        and entry.get("fp") == fp
-        and isinstance(entry.get("models"), list)
-        and entry["models"]
-        and (now - float(entry.get("at", 0))) < ttl_seconds
-    ):
-        return list(entry["models"])
+        if (
+            not force_refresh
+            and isinstance(entry, dict)
+            and entry.get("fp") == fp
+            and isinstance(entry.get("models"), list)
+            and entry["models"]
+            and (now - float(entry.get("at", 0))) < ttl_seconds
+        ):
+            return _finish("hit", list(entry["models"]))
 
     # Cache miss / stale / forced refresh — call the live path.
     live = provider_model_ids(normalized, force_refresh=force_refresh)
     if live:
-        cache[normalized] = {
-            "fp": fp,
-            "at": now,
-            "models": list(live),
-        }
-        _save_provider_models_cache(cache)
-        return list(live)
+        # Multiple catalog workers can finish together. Reload under the lock
+        # before merging so one provider cannot overwrite another's entry.
+        with _provider_models_cache_lock:
+            latest_cache = _load_provider_models_cache()
+            latest_cache[normalized] = {
+                "fp": fp,
+                "at": now,
+                "models": list(live),
+            }
+            _save_provider_models_cache(latest_cache)
+        return _finish("live", list(live))
 
     # Live fetch returned nothing. If we have a stale entry with the
     # SAME fingerprint, prefer it over an empty result — stale data
@@ -2843,8 +2865,8 @@ def cached_provider_model_ids(
         and isinstance(entry.get("models"), list)
         and entry["models"]
     ):
-        return list(entry["models"])
-    return list(live or [])
+        return _finish("stale", list(entry["models"]))
+    return _finish("empty", list(live or []))
 
 
 def clear_provider_models_cache(provider: Optional[str] = None) -> None:
@@ -2855,16 +2877,17 @@ def clear_provider_models_cache(provider: Optional[str] = None) -> None:
     ``hermes model --refresh``.
     """
     try:
-        if provider is None:
-            path = _provider_models_cache_path()
-            if path.exists():
-                path.unlink()
-            return
-        cache = _load_provider_models_cache()
-        normalized = normalize_provider(provider) or provider or ""
-        if normalized in cache:
-            del cache[normalized]
-            _save_provider_models_cache(cache)
+        with _provider_models_cache_lock:
+            if provider is None:
+                path = _provider_models_cache_path()
+                if path.exists():
+                    path.unlink()
+                return
+            cache = _load_provider_models_cache()
+            normalized = normalize_provider(provider) or provider or ""
+            if normalized in cache:
+                del cache[normalized]
+                _save_provider_models_cache(cache)
     except Exception:
         pass
 
diff --git a/hermes_cli/perf_diagnostics.py b/hermes_cli/perf_diagnostics.py
new file mode 100644
index 0000000000000..ddbd3528bfbf4
--- /dev/null
+++ b/hermes_cli/perf_diagnostics.py
@@ -0,0 +1,125 @@
+"""Small, secret-free activity registry for gateway stall diagnostics."""
+
+from __future__ import annotations
+
+from collections import deque
+from contextlib import contextmanager
+import itertools
+import logging
+import os
+import threading
+import time
+from typing import Iterator
+
+_log = logging.getLogger(__name__)
+_lock = threading.RLock()
+_sequence = itertools.count(1)
+_active: dict[int, dict] = {}
+_recent_slow: deque[dict] = deque(maxlen=20)
+_SLOW_ACTIVITY_SECONDS = 2.0
+
+
+def begin_activity(category: str, name: str, **attributes: object) -> int:
+    """Register an operation without retaining payloads, credentials, or IDs."""
+    token = next(_sequence)
+    safe_attributes = {
+        str(key): value
+        for key, value in attributes.items()
+        if isinstance(value, (bool, int, float, str))
+    }
+    with _lock:
+        _active[token] = {
+            "category": str(category),
+            "name": str(name),
+            "started": time.monotonic(),
+            "attributes": safe_attributes,
+        }
+    return token
+
+
+def finish_activity(token: int, *, error: bool = False) -> None:
+    with _lock:
+        row = _active.pop(token, None)
+    if row is None:
+        return
+
+    elapsed = time.monotonic() - row["started"]
+    if elapsed < _SLOW_ACTIVITY_SECONDS:
+        return
+
+    completed = {
+        "category": row["category"],
+        "name": row["name"],
+        "duration_ms": round(elapsed * 1000, 1),
+        "error": bool(error),
+        "attributes": row["attributes"],
+    }
+    with _lock:
+        _recent_slow.append(completed)
+    _log.info(
+        "slow activity category=%s name=%s duration_ms=%.1f error=%s attributes=%s",
+        completed["category"],
+        completed["name"],
+        completed["duration_ms"],
+        completed["error"],
+        completed["attributes"],
+    )
+
+
+@contextmanager
+def track_activity(category: str, name: str, **attributes: object) -> Iterator[None]:
+    token = begin_activity(category, name, **attributes)
+    failed = False
+    try:
+        yield
+    except BaseException:
+        failed = True
+        raise
+    finally:
+        finish_activity(token, error=failed)
+
+
+def diagnostics_snapshot(*, active_limit: int = 8, recent_limit: int = 8) -> dict:
+    """Return bounded process/profile identity and current/recent activities."""
+    now = time.monotonic()
+    with _lock:
+        active = sorted(
+            (
+                {
+                    "category": row["category"],
+                    "name": row["name"],
+                    "elapsed_ms": round((now - row["started"]) * 1000, 1),
+                    "attributes": dict(row["attributes"]),
+                }
+                for row in _active.values()
+            ),
+            key=lambda row: row["elapsed_ms"],
+            reverse=True,
+        )[: max(0, active_limit)]
+        recent_count = max(0, recent_limit)
+        recent = list(_recent_slow)[-recent_count:] if recent_count else []
+
+    return {
+        "pid": os.getpid(),
+        "profile": _profile_name(),
+        "active": active,
+        "recent_slow": recent,
+    }
+
+
+def _profile_name() -> str:
+    explicit = os.environ.get("HERMES_PROFILE", "").strip()
+    if explicit:
+        return explicit
+    try:
+        from hermes_cli.profiles import get_active_profile_name
+
+        return get_active_profile_name() or "default"
+    except Exception:
+        return "default"
+
+
+def _reset_for_tests() -> None:
+    with _lock:
+        _active.clear()
+        _recent_slow.clear()
diff --git a/hermes_cli/web_server.py b/hermes_cli/web_server.py
index 238b4acf88e7b..4a7ef84d54b74 100644
--- a/hermes_cli/web_server.py
+++ b/hermes_cli/web_server.py
@@ -6376,25 +6376,27 @@ def get_model_options(
     Models" control. Normal opens leave it false to stay on the 1h cache.
     """
     try:
-        from hermes_cli.inventory import build_models_payload, load_picker_context
+        from hermes_cli.inventory import build_cached_models_payload, load_picker_context
+        from hermes_cli.perf_diagnostics import track_activity
 
         # Most desktop surfaces should only list providers the user has already
         # configured. Onboarding opts into the full provider universe via
         # include_unconfigured=1 so it can still render setup affordances for
         # providers that are not yet authenticated.
-        with _profile_scope(profile):
-            return build_models_payload(
-                load_picker_context(),
-                explicit_only=bool(explicit_only),
-                include_unconfigured=bool(include_unconfigured),
-                picker_hints=True,
-                canonical_order=True,
-                pricing=True,
-                capabilities=True,
-                refresh=bool(refresh),
-                probe_custom_providers=bool(refresh),
-                probe_current_custom_provider=not bool(refresh),
-            )
+        with track_activity("http", "model.options", refresh=bool(refresh)):
+            with _profile_scope(profile):
+                return build_cached_models_payload(
+                    load_picker_context(),
+                    explicit_only=bool(explicit_only),
+                    include_unconfigured=bool(include_unconfigured),
+                    picker_hints=True,
+                    canonical_order=True,
+                    pricing=True,
+                    capabilities=True,
+                    refresh=bool(refresh),
+                    probe_custom_providers=bool(refresh),
+                    probe_current_custom_provider=not bool(refresh),
+                )
     except HTTPException:
         raise
     except Exception:
@@ -19219,6 +19221,9 @@ def _mount_plugin_api_routes():
     execution vector that bypasses the user's intent. (#46435,
     GHSA-mcfc-hp25-cjv7)
     """
+    mount_started = time.monotonic()
+    mounted_count = 0
+
     # Load the enabled/disabled sets once for the loop.
     try:
         from hermes_cli.plugins_cmd import _get_enabled_set, _get_disabled_set
@@ -19284,6 +19289,7 @@ def _mount_plugin_api_routes():
         if not api_path.exists():
             _log.warning("Plugin %s declares api=%s but file not found", plugin["name"], api_file_name)
             continue
+        plugin_started = time.monotonic()
         try:
             module_name = f"hermes_dashboard_plugin_{plugin['name']}"
             spec = importlib.util.spec_from_file_location(module_name, api_path)
@@ -19307,9 +19313,22 @@ def _mount_plugin_api_routes():
                 _log.warning("Plugin %s api file has no 'router' attribute", plugin["name"])
                 continue
             app.include_router(router, prefix=f"/api/plugins/{plugin['name']}")
+            mounted_count += 1
             _log.info("Mounted plugin API routes: /api/plugins/%s/", plugin["name"])
         except Exception as exc:
             _log.warning("Failed to load plugin %s API routes: %s", plugin["name"], exc)
+        finally:
+            _log.info(
+                "plugin api mount name=%s duration_ms=%.1f",
+                plugin_name,
+                (time.monotonic() - plugin_started) * 1000,
+            )
+
+    _log.info(
+        "plugin api mount complete mounted=%d total_ms=%.1f",
+        mounted_count,
+        (time.monotonic() - mount_started) * 1000,
+    )
 
 
 # Mount plugin API routes before the SPA catch-all.
@@ -19627,6 +19646,17 @@ async def _serve():
             actual_port = _read_bound_port(server, fallback=port)
             app.state.bound_port = actual_port
 
+            from hermes_cli.perf_diagnostics import diagnostics_snapshot
+
+            _identity = diagnostics_snapshot(active_limit=0, recent_limit=0)
+            _log.info(
+                "gateway diagnostics ready pid=%s profile=%s port=%s headless=%s",
+                _identity["pid"],
+                _identity["profile"],
+                actual_port,
+                headless,
+            )
+
             _write_dashboard_ready_file(actual_port)
             # Port-discovery sentinel parsed by the desktop spawn. `serve` is a
             # plain backend, not a dashboard, so it announces a neutral token;
@@ -19671,9 +19701,15 @@ def _loop_heartbeat(expected: float) -> None:
                 now = _hb_loop.time()
                 drift = now - expected
                 if drift > _hb_stall_threshold:
+                    snapshot = diagnostics_snapshot()
                     _log.warning(
-                        "event loop stalled %.1fs (GIL pressure suspected)",
+                        "event loop stalled %.1fs (GIL pressure suspected) "
+                        "pid=%s profile=%s active=%s recent_slow=%s",
                         drift,
+                        snapshot["pid"],
+                        snapshot["profile"],
+                        snapshot["active"],
+                        snapshot["recent_slow"],
                     )
                 _hb_loop.call_later(
                     _hb_interval, _loop_heartbeat, now + _hb_interval
diff --git a/tests/hermes_cli/test_inventory.py b/tests/hermes_cli/test_inventory.py
index 6c262180b9d87..057b1272ed961 100644
--- a/tests/hermes_cli/test_inventory.py
+++ b/tests/hermes_cli/test_inventory.py
@@ -19,11 +19,13 @@
 
 from __future__ import annotations
 
+import threading
 from unittest.mock import patch
 
 
 from hermes_cli.inventory import (
     ConfigContext,
+    build_cached_models_payload,
     build_models_payload,
     load_picker_context,
 )
@@ -1031,3 +1033,176 @@ def test_list_authenticated_providers_refresh_busts_cache():
         assert clear.call_count == 0
         model_switch.list_authenticated_providers(refresh=True)
         assert clear.call_count == 1
+
+
+# ─── cached picker payload ─────────────────────────────────────────────
+
+
+def _clear_models_payload_cache() -> None:
+    from hermes_cli import inventory
+
+    with inventory._models_payload_cache_lock:
+        inventory._models_payload_cache.clear()
+        inventory._models_payload_inflight.clear()
+        inventory._models_payload_refresh_epoch = 0
+
+
+def _cached_payload(marker: str) -> dict:
+    return {
+        "providers": [{"slug": marker, "models": [marker]}],
+        "model": marker,
+        "provider": marker,
+    }
+
+
+def test_cached_models_payload_uses_ttl_and_returns_deep_copy(monkeypatch):
+    from hermes_cli import inventory
+
+    _clear_models_payload_cache()
+    monkeypatch.setattr(inventory, "_models_payload_generation", lambda: ("g1",))
+    builder = patch("hermes_cli.inventory.build_models_payload", return_value=_cached_payload("one"))
+    with builder as build:
+        first = build_cached_models_payload(_empty_ctx())
+        first["providers"][0]["models"].append("mutated")
+        second = build_cached_models_payload(_empty_ctx())
+        assert build.call_count == 1
+
+    assert second["providers"][0]["models"] == ["one"]
+
+    monkeypatch.setattr(inventory, "_MODELS_PAYLOAD_CACHE_TTL_S", -1)
+    with patch("hermes_cli.inventory.build_models_payload", return_value=_cached_payload("two")) as build:
+        expired = build_cached_models_payload(_empty_ctx())
+    assert build.call_count == 1
+    assert expired["provider"] == "two"
+
+
+def test_cached_models_payload_coalesces_inflight_requests(monkeypatch):
+    from hermes_cli import inventory
+
+    _clear_models_payload_cache()
+    monkeypatch.setattr(inventory, "_models_payload_generation", lambda: ("g1",))
+    started = threading.Event()
+    release = threading.Event()
+    results: list[dict] = []
+
+    def build(*_args, **_kwargs):
+        started.set()
+        assert release.wait(timeout=2)
+        return _cached_payload("shared")
+
+    with patch("hermes_cli.inventory.build_models_payload", side_effect=build) as mocked:
+        first = threading.Thread(target=lambda: results.append(build_cached_models_payload(_empty_ctx())))
+        second = threading.Thread(target=lambda: results.append(build_cached_models_payload(_empty_ctx())))
+        first.start()
+        assert started.wait(timeout=2)
+        second.start()
+        release.set()
+        first.join(timeout=2)
+        second.join(timeout=2)
+
+    assert not first.is_alive()
+    assert not second.is_alive()
+    assert mocked.call_count == 1
+    assert [result["provider"] for result in results] == ["shared", "shared"]
+
+
+def test_cached_models_payload_propagates_errors_without_poisoning_next_request(monkeypatch):
+    from hermes_cli import inventory
+
+    _clear_models_payload_cache()
+    monkeypatch.setattr(inventory, "_models_payload_generation", lambda: ("g1",))
+    with patch(
+        "hermes_cli.inventory.build_models_payload",
+        side_effect=[RuntimeError("temporary failure"), _cached_payload("recovered")],
+    ) as build:
+        try:
+            build_cached_models_payload(_empty_ctx())
+        except RuntimeError as exc:
+            assert str(exc) == "temporary failure"
+        else:
+            raise AssertionError("expected builder exception")
+        recovered = build_cached_models_payload(_empty_ctx())
+
+    assert build.call_count == 2
+    assert recovered["provider"] == "recovered"
+
+
+def test_cached_models_payload_refresh_invalidates_and_warms_normal_key(monkeypatch):
+    from hermes_cli import inventory
+
+    _clear_models_payload_cache()
+    monkeypatch.setattr(inventory, "_models_payload_generation", lambda: ("g1",))
+    with patch(
+        "hermes_cli.inventory.build_models_payload",
+        side_effect=[_cached_payload("old"), _cached_payload("fresh")],
+    ) as build:
+        assert build_cached_models_payload(_empty_ctx())["provider"] == "old"
+        assert build_cached_models_payload(_empty_ctx(), refresh=True)["provider"] == "fresh"
+        assert build_cached_models_payload(_empty_ctx())["provider"] == "fresh"
+
+    assert build.call_count == 2
+
+
+def test_cached_models_payload_refresh_prevents_older_build_from_repopulating_cache(monkeypatch):
+    from hermes_cli import inventory
+
+    _clear_models_payload_cache()
+    monkeypatch.setattr(inventory, "_models_payload_generation", lambda: ("g1",))
+    old_started = threading.Event()
+    release_old = threading.Event()
+
+    def build(_ctx, **flags):
+        if not flags["refresh"]:
+            old_started.set()
+            assert release_old.wait(timeout=2)
+            return _cached_payload("old")
+
+        return _cached_payload("fresh")
+
+    results: list[dict] = []
+    with patch("hermes_cli.inventory.build_models_payload", side_effect=build) as mocked:
+        old_request = threading.Thread(
+            target=lambda: results.append(build_cached_models_payload(_empty_ctx()))
+        )
+        old_request.start()
+        assert old_started.wait(timeout=2)
+
+        assert build_cached_models_payload(_empty_ctx(), refresh=True)["provider"] == "fresh"
+        release_old.set()
+        old_request.join(timeout=2)
+
+        assert build_cached_models_payload(_empty_ctx())["provider"] == "fresh"
+
+    assert not old_request.is_alive()
+    assert mocked.call_count == 2
+    assert results[0]["provider"] == "old"
+
+
+def test_cached_models_payload_misses_when_generation_changes(monkeypatch):
+    from hermes_cli import inventory
+
+    _clear_models_payload_cache()
+    generation = ["g1"]
+    monkeypatch.setattr(inventory, "_models_payload_generation", lambda: tuple(generation))
+    with patch(
+        "hermes_cli.inventory.build_models_payload",
+        side_effect=[_cached_payload("first"), _cached_payload("second")],
+    ) as build:
+        assert build_cached_models_payload(_empty_ctx())["provider"] == "first"
+        assert build_cached_models_payload(_empty_ctx())["provider"] == "first"
+        generation[0] = "g2"
+        assert build_cached_models_payload(_empty_ctx())["provider"] == "second"
+
+    assert build.call_count == 2
+
+
+def test_cached_models_payload_caps_entries_at_64(monkeypatch):
+    from hermes_cli import inventory
+
+    _clear_models_payload_cache()
+    monkeypatch.setattr(inventory, "_models_payload_generation", lambda: ("g1",))
+    with patch("hermes_cli.inventory.build_models_payload", return_value=_cached_payload("row")):
+        for index in range(65):
+            build_cached_models_payload(_empty_ctx(model=f"model-{index}"))
+
+    assert len(inventory._models_payload_cache) == 64
diff --git a/tests/hermes_cli/test_inventory_explicit_pruning.py b/tests/hermes_cli/test_inventory_explicit_pruning.py
new file mode 100644
index 0000000000000..c50e291a8b5eb
--- /dev/null
+++ b/tests/hermes_cli/test_inventory_explicit_pruning.py
@@ -0,0 +1,61 @@
+"""Configured-only model inventory must prune ambient providers before I/O."""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+from hermes_cli.inventory import ConfigContext, build_models_payload
+from hermes_cli.model_switch import list_authenticated_providers
+
+
+def _ctx() -> ConfigContext:
+    return ConfigContext(
+        current_provider="openai-codex",
+        current_model="gpt-5.6-sol",
+        current_base_url="",
+        user_providers={},
+        custom_providers=[],
+        excluded_providers=[],
+    )
+
+
+def test_payload_forwards_explicit_only_to_discovery() -> None:
+    with patch(
+        "hermes_cli.model_switch.list_authenticated_providers",
+        return_value=[],
+    ) as discover:
+        build_models_payload(_ctx(), explicit_only=True)
+
+    assert discover.call_args.kwargs["explicit_only"] is True
+
+
+def test_explicit_only_skips_ambient_catalog_io_before_row_filtering() -> None:
+    model_calls: list[str] = []
+
+    def _models(provider: str, **_kwargs) -> list[str]:
+        model_calls.append(provider)
+        return ["gpt-5.6-sol"]
+
+    with (
+        patch("agent.models_dev.fetch_models_dev") as models_dev,
+        patch("hermes_cli.models.get_curated_nous_model_ids") as nous_manifest,
+        patch("hermes_cli.models.cached_provider_model_ids", side_effect=_models),
+        patch(
+            "hermes_cli.model_switch._credential_pool_is_usable",
+            side_effect=lambda slug, **_kwargs: slug == "openai-codex",
+        ),
+        patch(
+            "hermes_cli.auth.is_provider_explicitly_configured",
+            return_value=False,
+        ),
+    ):
+        rows = list_authenticated_providers(
+            current_provider="openai-codex",
+            current_model="gpt-5.6-sol",
+            explicit_only=True,
+        )
+
+    assert [row["slug"] for row in rows] == ["openai-codex"]
+    assert model_calls == ["openai-codex"]
+    models_dev.assert_not_called()
+    nous_manifest.assert_not_called()
diff --git a/tests/hermes_cli/test_model_catalog_concurrency.py b/tests/hermes_cli/test_model_catalog_concurrency.py
new file mode 100644
index 0000000000000..09bce99eee468
--- /dev/null
+++ b/tests/hermes_cli/test_model_catalog_concurrency.py
@@ -0,0 +1,77 @@
+"""Bounded model-catalog discovery and cache merge guarantees."""
+
+from __future__ import annotations
+
+import json
+import threading
+
+from hermes_cli import models
+from hermes_cli.model_switch import _BoundedProviderCatalogLoader
+
+
+def test_catalog_loader_runs_in_parallel_with_a_fixed_cap() -> None:
+    release = threading.Event()
+    reached_cap = threading.Event()
+    lock = threading.Lock()
+    active = 0
+    maximum_active = 0
+
+    def fetch(provider: str) -> list[str]:
+        nonlocal active, maximum_active
+        with lock:
+            active += 1
+            maximum_active = max(maximum_active, active)
+            if active == 4:
+                reached_cap.set()
+        assert release.wait(timeout=2)
+        with lock:
+            active -= 1
+        return [f"{provider}-model"]
+
+    loader = _BoundedProviderCatalogLoader(fetch, max_workers=4)
+    loader.prefetch([f"provider-{index}" for index in range(6)])
+    assert reached_cap.wait(timeout=2)
+    assert maximum_active == 4
+
+    release.set()
+    assert loader.get("provider-5") == ["provider-5-model"]
+    loader.close()
+    assert maximum_active == 4
+
+
+def test_concurrent_provider_cache_writes_merge_entries(tmp_path, monkeypatch) -> None:
+    cache_path = tmp_path / "provider_models_cache.json"
+    barrier = threading.Barrier(2)
+    results: dict[str, list[str]] = {}
+
+    monkeypatch.setattr(models, "_provider_models_cache_path", lambda: cache_path)
+    monkeypatch.setattr(models, "_credential_fingerprint", lambda provider: provider)
+
+    def fetch(provider: str, *, force_refresh: bool = False) -> list[str]:
+        del force_refresh
+        barrier.wait(timeout=2)
+        return [f"{provider}-model"]
+
+    monkeypatch.setattr(models, "provider_model_ids", fetch)
+
+    threads = [
+        threading.Thread(
+            target=lambda provider=provider: results.setdefault(
+                provider,
+                models.cached_provider_model_ids(provider, force_refresh=True),
+            )
+        )
+        for provider in ("anthropic", "openrouter")
+    ]
+    for thread in threads:
+        thread.start()
+    for thread in threads:
+        thread.join(timeout=2)
+
+    assert all(not thread.is_alive() for thread in threads)
+    assert results == {
+        "anthropic": ["anthropic-model"],
+        "openrouter": ["openrouter-model"],
+    }
+    stored = json.loads(cache_path.read_text(encoding="utf-8"))
+    assert set(stored) == {"anthropic", "openrouter"}
diff --git a/tests/hermes_cli/test_perf_diagnostics.py b/tests/hermes_cli/test_perf_diagnostics.py
new file mode 100644
index 0000000000000..bc7eded2549fc
--- /dev/null
+++ b/tests/hermes_cli/test_perf_diagnostics.py
@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from hermes_cli import perf_diagnostics
+
+
+def setup_function() -> None:
+    perf_diagnostics._reset_for_tests()
+
+
+def test_snapshot_contains_only_bounded_activity_metadata(monkeypatch) -> None:
+    monkeypatch.setenv("HERMES_PROFILE", "coder")
+    token = perf_diagnostics.begin_activity("rpc", "model.options", pool=True)
+
+    snapshot = perf_diagnostics.diagnostics_snapshot()
+
+    assert snapshot["pid"] > 0
+    assert snapshot["profile"] == "coder"
+    assert snapshot["active"][0]["category"] == "rpc"
+    assert snapshot["active"][0]["name"] == "model.options"
+    assert snapshot["active"][0]["attributes"] == {"pool": True}
+    perf_diagnostics.finish_activity(token)
+
+
+def test_slow_activity_is_retained_after_completion(monkeypatch) -> None:
+    clock = iter((10.0, 12.5, 12.5))
+    monkeypatch.setattr(perf_diagnostics.time, "monotonic", lambda: next(clock))
+    token = perf_diagnostics.begin_activity("backup", "snapshot")
+
+    perf_diagnostics.finish_activity(token, error=True)
+    snapshot = perf_diagnostics.diagnostics_snapshot()
+
+    assert snapshot["active"] == []
+    assert snapshot["recent_slow"][0]["duration_ms"] == 2500.0
+    assert snapshot["recent_slow"][0]["error"] is True
diff --git a/tests/test_tui_gateway_server.py b/tests/test_tui_gateway_server.py
index 125d3eb584e1e..fff335861847b 100644
--- a/tests/test_tui_gateway_server.py
+++ b/tests/test_tui_gateway_server.py
@@ -8185,7 +8185,10 @@ def test_model_options_propagates_list_exception(monkeypatch):
         "hermes_cli.model_switch.list_authenticated_providers",
         side_effect=RuntimeError("catalog blew up"),
     ):
-        resp = server._methods["model.options"](77, {"session_id": ""})
+        resp = server._methods["model.options"](
+            77,
+            {"session_id": "", "refresh": True},
+        )
     assert "error" in resp
     assert resp["error"]["code"] == 5033
     assert "catalog blew up" in resp["error"]["message"]
diff --git a/tui_gateway/server.py b/tui_gateway/server.py
index 03d8492d932c5..ef0437b8beb51 100644
--- a/tui_gateway/server.py
+++ b/tui_gateway/server.py
@@ -25,6 +25,7 @@
     set_hermes_home_override,
 )
 from hermes_cli.env_loader import load_hermes_dotenv
+from hermes_cli.perf_diagnostics import begin_activity, finish_activity, track_activity
 from utils import is_truthy_value
 from tools.environments.local import hermes_subprocess_env
 from agent.replay_cleanup import sanitize_replay_history
@@ -1525,20 +1526,31 @@ def dispatch(req: dict, transport: Optional[Transport] = None) -> dict | None:
 
         _rid, method, _params = normalized
         if method not in _LONG_HANDLERS:
-            return handle_request(req)
+            with track_activity("rpc", method, pool=False):
+                return handle_request(req)
 
         # Snapshot the context so the pool worker sees the bound transport.
         ctx = contextvars.copy_context()
+        activity_token = begin_activity("rpc", method, pool=True)
 
         def run():
+            failed = False
             try:
                 resp = handle_request(req)
             except Exception as exc:
+                failed = True
                 resp = _err(req.get("id"), -32000, f"handler error: {exc}")
-            if resp is not None:
-                t.write(resp)
+            try:
+                if resp is not None:
+                    t.write(resp)
+            finally:
+                finish_activity(activity_token, error=failed)
 
-        _pool.submit(lambda: ctx.run(run))
+        try:
+            _pool.submit(lambda: ctx.run(run))
+        except Exception:
+            finish_activity(activity_token, error=True)
+            raise
 
         return None
     finally:
@@ -14632,7 +14644,7 @@ def _model_picker_context(agent):
 @method("model.options")
 def _(rid, params: dict) -> dict:
     try:
-        from hermes_cli.inventory import build_models_payload
+        from hermes_cli.inventory import build_cached_models_payload
 
         session = _sessions.get(params.get("session_id", ""))
         agent = session.get("agent") if session else None
@@ -14649,7 +14661,7 @@ def _(rid, params: dict) -> dict:
         # Curated model lists are preserved — list_authenticated_providers
         # populates `models` from the curated catalog, not provider_model_ids
         # (which would pull non-agentic models like TTS/embeddings/etc.).
-        payload = build_models_payload(
+        payload = build_cached_models_payload(
             ctx,
             explicit_only=bool(params.get("explicit_only")),
             include_unconfigured=bool(params.get("include_unconfigured")),
diff --git a/tui_gateway/ws.py b/tui_gateway/ws.py
index b61ef130cc452..9b3702d5bf285 100644
--- a/tui_gateway/ws.py
+++ b/tui_gateway/ws.py
@@ -29,6 +29,7 @@ async def ws(ws: WebSocket):
 import logging
 import socket
 import threading
+import time
 from typing import Any
 
 from tui_gateway import server
@@ -282,6 +283,7 @@ def _disable_nagle(ws: Any) -> None:
 
 async def handle_ws(ws: Any) -> None:
     """Run one WebSocket session. Wire-compatible with ``tui_gateway.entry``."""
+    connection_started = time.monotonic()
     peer = _ws_peer_label(ws)
     transport: WSTransport | None = None
     messages = 0
@@ -329,6 +331,11 @@ async def handle_ws(ws: Any) -> None:
         if ready_ok:
             # Live-apply skins Hermes activates mid-conversation.
             server._ensure_skin_watcher()
+            _log.info(
+                "ws ready peer=%s duration_ms=%.1f",
+                peer,
+                (time.monotonic() - connection_started) * 1000,
+            )
         if not ready_ok:
             disconnect_reason = "ready_send_failed"
             send_failures += 1
@@ -457,7 +464,7 @@ async def handle_ws(ws: Any) -> None:
             _log.debug("ws close failed peer=%s error=%s", peer, exc)
         _log.info(
             "ws closed peer=%s reason=%s messages=%d parse_errors=%d "
-            "dispatch_crashes=%d send_failures=%d reaped_sessions=%d detached_sessions=%d",
+            "dispatch_crashes=%d send_failures=%d reaped_sessions=%d detached_sessions=%d lifetime_ms=%.1f",
             peer,
             disconnect_reason,
             messages,
@@ -466,4 +473,5 @@ async def handle_ws(ws: Any) -> None:
             send_failures,
             reaped_sessions,
             detached_sessions,
+            (time.monotonic() - connection_started) * 1000,
         )

From f0fcaf50cfd1f622c82f56954644233de7e8c106 Mon Sep 17 00:00:00 2001
From: Hao Wang <haowang@HaodeMac-mini.lan>
Date: Wed, 22 Jul 2026 21:26:51 +0800
Subject: [PATCH 4/4] fix(backup): serialize and atomically publish snapshots

---
 hermes_cli/backup.py                      | 241 +++++++++++++++++++---
 tests/hermes_cli/test_backup_stability.py | 105 ++++++++++
 2 files changed, 319 insertions(+), 27 deletions(-)
 create mode 100644 tests/hermes_cli/test_backup_stability.py

diff --git a/hermes_cli/backup.py b/hermes_cli/backup.py
index 2a25217160c0a..83dd5ff3e7f84 100644
--- a/hermes_cli/backup.py
+++ b/hermes_cli/backup.py
@@ -15,8 +15,10 @@
 import sqlite3
 import sys
 import tempfile
+import threading
 import time
 import zipfile
+from contextlib import contextmanager
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional
@@ -84,6 +86,7 @@
 
 # File names to skip (runtime state that's meaningless on another machine)
 _EXCLUDED_NAMES = {
+    ".backup.lock",
     "gateway.pid",
     "cron.pid",
 }
@@ -132,6 +135,85 @@
 _EXTERNAL_PREFIX = "_external/"
 
 
+class BackupInProgressError(RuntimeError):
+    """Raised when another process already owns the Hermes backup slot."""
+
+
+class _SQLiteSnapshotError(RuntimeError):
+    pass
+
+
+@contextmanager
+def _backup_operation_lock(hermes_home: Path, timeout_seconds: float = 0.25):
+    """Acquire one cross-process backup slot for full and quick snapshots."""
+    lock_path = hermes_home / ".backup.lock"
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    handle = lock_path.open("a+b")
+    acquired = False
+    deadline = time.monotonic() + max(0.0, timeout_seconds)
+    try:
+        if os.name == "nt":
+            import msvcrt
+
+            if lock_path.stat().st_size == 0:
+                handle.write(b" ")
+                handle.flush()
+            while True:
+                try:
+                    handle.seek(0)
+                    msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
+                    acquired = True
+                    break
+                except (OSError, PermissionError):
+                    if time.monotonic() >= deadline:
+                        raise BackupInProgressError("another Hermes backup is already running")
+                    time.sleep(0.05)
+        else:
+            import fcntl
+
+            while True:
+                try:
+                    fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+                    acquired = True
+                    break
+                except (BlockingIOError, OSError):
+                    if time.monotonic() >= deadline:
+                        raise BackupInProgressError("another Hermes backup is already running")
+                    time.sleep(0.05)
+
+        yield
+    finally:
+        if acquired:
+            try:
+                if os.name == "nt":
+                    import msvcrt
+
+                    handle.seek(0)
+                    msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+                else:
+                    import fcntl
+
+                    fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+            except (OSError, PermissionError):
+                pass
+        handle.close()
+
+
+@contextmanager
+def _atomic_output_path(final_path: Path):
+    """Yield a hidden sibling path and publish it only after a clean close."""
+    partial_path = final_path.with_name(
+        f".{final_path.name}.{os.getpid()}-{threading.get_ident()}.partial"
+    )
+    partial_path.unlink(missing_ok=True)
+    try:
+        yield partial_path
+        os.replace(partial_path, final_path)
+    except BaseException:
+        partial_path.unlink(missing_ok=True)
+        raise
+
+
 def _collect_memory_provider_external_paths() -> List[Path]:
     """Return existing absolute paths the active memory provider stores
     outside HERMES_HOME, resolved from config only (no network, no init).
@@ -304,6 +386,20 @@ def run_backup(args) -> None:
         print(f"Error: Hermes home directory not found at {hermes_root}")
         sys.exit(1)
 
+    try:
+        from hermes_cli.perf_diagnostics import track_activity
+
+        with _backup_operation_lock(hermes_root):
+            with track_activity("backup", "full"):
+                _run_backup_locked(args, hermes_root)
+    except BackupInProgressError as exc:
+        print(f"Error: {exc}")
+        raise SystemExit(2) from exc
+
+
+def _run_backup_locked(args, hermes_root: Path) -> None:
+    """Write a full backup while the cross-process backup slot is held."""
+
     # Determine output path
     if args.output:
         out_path = Path(args.output).expanduser().resolve()
@@ -323,6 +419,8 @@ def run_backup(args) -> None:
     out_path.parent.mkdir(parents=True, exist_ok=True)
 
     # Collect files
+    scan_started = time.monotonic()
+    logger.info("backup phase=scan status=started")
     print(f"Scanning {display_hermes_home()} ...")
     files_to_add: list[tuple[Path, Path]] = []  # (absolute, relative)
     skipped_dirs = set()
@@ -377,18 +475,30 @@ def run_backup(args) -> None:
             external_to_add.append((fpath, arcname))
 
     if not files_to_add and not external_to_add:
+        logger.info(
+            "backup phase=scan status=empty duration_ms=%.1f",
+            (time.monotonic() - scan_started) * 1000,
+        )
         print("No files to back up.")
         return
 
     # Create the zip
     file_count = len(files_to_add) + len(external_to_add)
+    logger.info(
+        "backup phase=scan status=complete duration_ms=%.1f files=%d",
+        (time.monotonic() - scan_started) * 1000,
+        file_count,
+    )
+    logger.info("backup phase=archive status=started files=%d", file_count)
     print(f"Backing up {file_count} files ...")
 
     total_bytes = 0
     errors = []
     t0 = time.monotonic()
 
-    with zipfile.ZipFile(out_path, "w", zipfile.ZIP_DEFLATED, compresslevel=6) as zf:
+    with _atomic_output_path(out_path) as archive_path, zipfile.ZipFile(
+        archive_path, "w", zipfile.ZIP_DEFLATED, compresslevel=6
+    ) as zf:
         for i, (abs_path, rel_path) in enumerate(files_to_add, 1):
             try:
                 # Safe copy for SQLite databases (handles WAL mode)
@@ -419,6 +529,11 @@ def run_backup(args) -> None:
             # Progress every 500 files
             if i % 500 == 0:
                 print(f"  {i}/{file_count} files ...")
+                logger.info(
+                    "backup phase=archive status=progress completed=%d total=%d",
+                    i,
+                    file_count,
+                )
 
         # External memory-provider state, stored under the ``_external/`` arc
         # prefix. These never include ``.db`` files in practice (config/env
@@ -433,6 +548,13 @@ def run_backup(args) -> None:
 
     elapsed = time.monotonic() - t0
     zip_size = out_path.stat().st_size
+    logger.info(
+        "backup phase=archive status=complete duration_ms=%.1f files=%d errors=%d bytes=%d",
+        elapsed * 1000,
+        file_count,
+        len(errors),
+        zip_size,
+    )
 
     # Summary
     print()
@@ -808,6 +930,26 @@ def create_quick_snapshot(
     hermes_home: Optional[Path] = None,
     keep: Optional[int] = None,
     max_file_size: Optional[int] = None,
+) -> Optional[str]:
+    """Create one atomic quick snapshot while holding the shared backup slot."""
+    home = hermes_home or get_hermes_home()
+    from hermes_cli.perf_diagnostics import track_activity
+
+    with _backup_operation_lock(home):
+        with track_activity("backup", "quick_snapshot"):
+            return _create_quick_snapshot_locked(
+                label=label,
+                hermes_home=home,
+                keep=keep,
+                max_file_size=max_file_size,
+            )
+
+
+def _create_quick_snapshot_locked(
+    label: Optional[str] = None,
+    hermes_home: Optional[Path] = None,
+    keep: Optional[int] = None,
+    max_file_size: Optional[int] = None,
 ) -> Optional[str]:
     """Create a quick state snapshot of critical files.
 
@@ -853,9 +995,17 @@ def _too_large(path: Path, rel_name: str) -> bool:
         return True
 
     ts = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
-    snap_id = f"{ts}-{label}" if label else ts
+    base_snap_id = f"{ts}-{label}" if label else ts
+    snap_id = base_snap_id
+    suffix = 2
+    while (root / snap_id).exists():
+        snap_id = f"{base_snap_id}-{suffix}"
+        suffix += 1
     snap_dir = root / snap_id
-    snap_dir.mkdir(parents=True, exist_ok=True)
+    staging_dir = root / f".{snap_id}.{os.getpid()}.partial"
+    shutil.rmtree(staging_dir, ignore_errors=True)
+    staging_dir.mkdir(parents=True, exist_ok=False)
+    logger.info("quick snapshot phase=copy status=started id=%s", snap_id)
 
     manifest: Dict[str, int] = {}  # rel_path -> file size
 
@@ -879,7 +1029,7 @@ def _too_large(path: Path, rel_name: str) -> bool:
                     continue
                 if _too_large(sub, sub_rel):
                     continue
-                dst = snap_dir / sub_rel
+                dst = staging_dir / sub_rel
                 dst.parent.mkdir(parents=True, exist_ok=True)
                 try:
                     # Route SQLite DBs through the WAL-safe backup() path so a
@@ -901,7 +1051,7 @@ def _too_large(path: Path, rel_name: str) -> bool:
         if _too_large(src, rel):
             continue
 
-        dst = snap_dir / rel
+        dst = staging_dir / rel
         dst.parent.mkdir(parents=True, exist_ok=True)
 
         try:
@@ -915,7 +1065,7 @@ def _too_large(path: Path, rel_name: str) -> bool:
             logger.warning("Could not snapshot %s: %s", rel, exc)
 
     if not manifest:
-        shutil.rmtree(snap_dir, ignore_errors=True)
+        shutil.rmtree(staging_dir, ignore_errors=True)
         return None
 
     # Write manifest
@@ -927,15 +1077,22 @@ def _too_large(path: Path, rel_name: str) -> bool:
         "total_size": sum(manifest.values()),
         "files": manifest,
     }
-    with open(snap_dir / "manifest.json", "w", encoding="utf-8") as f:
+    with open(staging_dir / "manifest.json", "w", encoding="utf-8") as f:
         json.dump(meta, f, indent=2)
 
+    os.replace(staging_dir, snap_dir)
+
     # Auto-prune. Defaults preserve historical manual /snapshot behavior; callers
     # with known high-churn safety snapshots (for example pre-update) can pass a
     # smaller keep value so large state.db copies do not accumulate indefinitely.
     _prune_quick_snapshots(root, keep=_QUICK_DEFAULT_KEEP if keep is None else keep)
 
-    logger.info("State snapshot created: %s (%d files)", snap_id, len(manifest))
+    logger.info(
+        "quick snapshot phase=copy status=complete id=%s files=%d bytes=%d",
+        snap_id,
+        len(manifest),
+        sum(manifest.values()),
+    )
     return snap_id
 
 
@@ -950,7 +1107,7 @@ def list_quick_snapshots(
 
     results = []
     for d in sorted(root.iterdir(), reverse=True):
-        if not d.is_dir():
+        if not d.is_dir() or d.name.startswith(".") or d.name.endswith(".partial"):
             continue
         manifest_path = d / "manifest.json"
         if manifest_path.exists():
@@ -1159,7 +1316,11 @@ def _prune_quick_snapshots(root: Path, keep: int = _QUICK_DEFAULT_KEEP) -> int:
         return 0
 
     dirs = sorted(
-        (d for d in root.iterdir() if d.is_dir()),
+        (
+            d
+            for d in root.iterdir()
+            if d.is_dir() and not d.name.startswith(".") and not d.name.endswith(".partial")
+        ),
         key=lambda d: d.name,
         reverse=True,
     )
@@ -1201,12 +1362,27 @@ def run_quick_backup(args) -> None:
 # ---------------------------------------------------------------------------
 
 def _write_full_zip_backup(out_path: Path, hermes_root: Path) -> Optional[Path]:
+    """Single-flight wrapper for automatic full zip backups."""
+    try:
+        from hermes_cli.perf_diagnostics import track_activity
+
+        with _backup_operation_lock(hermes_root):
+            with track_activity("backup", "automatic_full"):
+                return _write_full_zip_backup_locked(out_path, hermes_root)
+    except BackupInProgressError as exc:
+        logger.warning("Full-zip backup skipped: %s", exc)
+        return None
+
+
+def _write_full_zip_backup_locked(out_path: Path, hermes_root: Path) -> Optional[Path]:
     """Write a full zip snapshot of ``hermes_root`` to ``out_path``.
 
     Uses the same exclusion rules and SQLite safe-copy as :func:`run_backup`.
     Returns the output path on success, None on failure (nothing to back up,
     or write error — caller should surface the outcome but not raise).
     """
+    scan_started = time.monotonic()
+    logger.info("automatic backup phase=scan status=started")
     files_to_add: list[tuple[Path, Path]] = []
     try:
         for dirpath, dirnames, filenames in os.walk(hermes_root, followlinks=False):
@@ -1232,10 +1408,18 @@ def _write_full_zip_backup(out_path: Path, hermes_root: Path) -> Optional[Path]:
     if not files_to_add:
         return None
 
-    sqlite_snapshot_failed = False
+    logger.info(
+        "automatic backup phase=scan status=complete duration_ms=%.1f files=%d",
+        (time.monotonic() - scan_started) * 1000,
+        len(files_to_add),
+    )
+
+    archive_started = time.monotonic()
     try:
-        with zipfile.ZipFile(out_path, "w", zipfile.ZIP_DEFLATED, compresslevel=6) as zf:
-            for abs_path, rel_path in files_to_add:
+        with _atomic_output_path(out_path) as archive_path, zipfile.ZipFile(
+            archive_path, "w", zipfile.ZIP_DEFLATED, compresslevel=6
+        ) as zf:
+            for index, (abs_path, rel_path) in enumerate(files_to_add, 1):
                 try:
                     if abs_path.suffix == ".db":
                         # Stage the snapshot alongside the output zip so that the
@@ -1252,8 +1436,7 @@ def _write_full_zip_backup(out_path: Path, hermes_root: Path) -> Optional[Path]:
                                     "Full-zip backup aborted: SQLite snapshot failed for %s",
                                     rel_path,
                                 )
-                                sqlite_snapshot_failed = True
-                                break
+                                raise _SQLiteSnapshotError(str(rel_path))
                             zf.write(tmp_db, arcname=str(rel_path))
                         finally:
                             tmp_db.unlink(missing_ok=True)
@@ -1262,21 +1445,25 @@ def _write_full_zip_backup(out_path: Path, hermes_root: Path) -> Optional[Path]:
                 except (PermissionError, OSError, ValueError) as exc:
                     logger.debug("Skipping %s in zip backup: %s", rel_path, exc)
                     continue
-    except OSError as exc:
+                if index % 500 == 0:
+                    logger.info(
+                        "automatic backup phase=archive status=progress completed=%d total=%d",
+                        index,
+                        len(files_to_add),
+                    )
+    except (OSError, _SQLiteSnapshotError) as exc:
         logger.warning("Full-zip backup: zip write failed: %s", exc)
-        # Best-effort cleanup of partial file
-        try:
-            out_path.unlink(missing_ok=True)
-        except OSError:
-            pass
+        # ``_atomic_output_path`` already removed the hidden partial.  Do not
+        # unlink ``out_path`` here: it may be a previous valid backup that the
+        # atomic publisher deliberately preserved.
         return None
 
-    if sqlite_snapshot_failed:
-        try:
-            out_path.unlink(missing_ok=True)
-        except OSError:
-            pass
-        return None
+    logger.info(
+        "automatic backup phase=archive status=complete duration_ms=%.1f files=%d bytes=%d",
+        (time.monotonic() - archive_started) * 1000,
+        len(files_to_add),
+        out_path.stat().st_size,
+    )
 
     return out_path
 
diff --git a/tests/hermes_cli/test_backup_stability.py b/tests/hermes_cli/test_backup_stability.py
new file mode 100644
index 0000000000000..d461d507220b4
--- /dev/null
+++ b/tests/hermes_cli/test_backup_stability.py
@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from hermes_cli.backup import (
+    BackupInProgressError,
+    _atomic_output_path,
+    _backup_operation_lock,
+    _write_full_zip_backup,
+    create_quick_snapshot,
+    list_quick_snapshots,
+)
+
+
+def test_backup_lock_rejects_a_second_operation(tmp_path) -> None:
+    home = tmp_path / ".hermes"
+    home.mkdir()
+
+    with _backup_operation_lock(home):
+        with pytest.raises(BackupInProgressError):
+            with _backup_operation_lock(home, timeout_seconds=0):
+                raise AssertionError("second backup unexpectedly acquired the lock")
+
+
+def test_atomic_output_publishes_only_after_clean_close(tmp_path) -> None:
+    final = tmp_path / "backup.zip"
+    final.write_bytes(b"previous")
+
+    with _atomic_output_path(final) as partial:
+        partial.write_bytes(b"complete")
+        assert final.read_bytes() == b"previous"
+
+    assert final.read_bytes() == b"complete"
+    assert not partial.exists()
+
+
+def test_atomic_output_keeps_previous_file_after_failure(tmp_path) -> None:
+    final = tmp_path / "backup.zip"
+    final.write_bytes(b"previous")
+
+    with pytest.raises(RuntimeError):
+        with _atomic_output_path(final) as partial:
+            partial.write_bytes(b"incomplete")
+            raise RuntimeError("compression failed")
+
+    assert final.read_bytes() == b"previous"
+    assert not partial.exists()
+
+
+def test_quick_snapshot_is_published_with_manifest(tmp_path, monkeypatch) -> None:
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "config.yaml").write_text("model: {}\n", encoding="utf-8")
+    published: list[tuple[Path, Path]] = []
+
+    from hermes_cli import backup
+
+    real_replace = backup.os.replace
+
+    def replace(source, destination) -> None:
+        source_path = Path(source)
+        destination_path = Path(destination)
+        if destination_path.parent == home / "state-snapshots":
+            assert source_path.name.endswith(".partial")
+            assert (source_path / "manifest.json").is_file()
+            assert not destination_path.exists()
+            published.append((source_path, destination_path))
+        real_replace(source, destination)
+
+    monkeypatch.setattr(backup.os, "replace", replace)
+    snapshot_id = create_quick_snapshot(hermes_home=home)
+
+    assert snapshot_id is not None
+    assert len(published) == 1
+    manifest = json.loads(
+        (home / "state-snapshots" / snapshot_id / "manifest.json").read_text(encoding="utf-8")
+    )
+    assert manifest["id"] == snapshot_id
+    assert manifest["files"] == {"config.yaml": 10}
+
+
+def test_quick_snapshot_listing_ignores_partial_directories(tmp_path) -> None:
+    home = tmp_path / ".hermes"
+    partial = home / "state-snapshots" / ".unfinished.1.partial"
+    partial.mkdir(parents=True)
+    (partial / "manifest.json").write_text('{"id":"unfinished"}', encoding="utf-8")
+
+    assert list_quick_snapshots(hermes_home=home) == []
+
+
+def test_failed_automatic_backup_preserves_previous_archive(tmp_path, monkeypatch) -> None:
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "state.db").write_bytes(b"not-a-database")
+    archive = tmp_path / "automatic.zip"
+    archive.write_bytes(b"previous-valid-backup")
+
+    monkeypatch.setattr("hermes_cli.backup._safe_copy_db", lambda _src, _dst: False)
+
+    assert _write_full_zip_backup(archive, home) is None
+    assert archive.read_bytes() == b"previous-valid-backup"
+    assert list(tmp_path.glob(".*.partial")) == []